media / capture / mojom / image_capture.mojom [blame]

// Copyright 2016 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module media.mojom;

// Equivalent to idl MediaSettingsRange, arbitrary range representing the
// allowed variations of a Capability or an Option.
// https://w3c.github.io/mediacapture-image/#mediasettingsrange-section
[Stable]
struct Range {
  double max;
  double min;
  double current;
  double step;
};

[Stable, Extensible]
enum BackgroundBlurMode {
  [Default]
  OFF,
  BLUR
};

[Stable, Extensible]
enum EyeGazeCorrectionMode {
  [Default]
  OFF,
  ON,
  STARE
};

// https://w3c.github.io/mediacapture-image/#meteringmode-section
[Stable, Extensible]
enum MeteringMode { NONE, MANUAL, SINGLE_SHOT, CONTINUOUS };

// https://w3c.github.io/mediacapture-image/#redeyereduction-section
[Stable, Extensible]
enum RedEyeReduction { NEVER, ALWAYS, CONTROLLABLE };

//  https://www.w3.org/TR/image-capture/#FillLightMode
[Stable, Extensible]
enum FillLightMode { OFF, AUTO, FLASH };

// Equivalent to idl's MediaTrackCapabilities plus PhotoCapabilities and their
// associated current settings (MediaTrackSettings plus PhotoSettings).
//
// A capability can be expressed as an array of unique supported values for
// requested settings in |PhotoSettings| (e.g. |supported_white_balance_modes|
// for |PhotoSettings.white_balance_mode|), as a range of supported values for
// requested settings in |PhotoSettings| (e.g. from |exposure_compensation.min|
// to |exposure_compensation.max| for |PhotoState.exposure_compensation|) or as
// a boolean flag indicating whether all (boolean) values are supported for
// requested settings in |PhotoSettings| (e.g. |supports_torch| for
// |PhotoState.torch|).
//
// The current settings are expressed right after or along the corresponding
// capabilities (e.g. |current_white_balance_mode| after
// |supported_white_balance_modes|, |exposure_compensation.current| along
// |exposure_compensation.min| and |exposure_compensation.max| and |torch|
// after |supports_torch|).
//
// If there are no supported values for a requested setting in |PhotoSettings|
// (an array of unique supported values is empty, a range of supported values
// is empty or a boolean flag is false), the corresponding current setting
// should be ignored and the corresponding |has_bla| flag in |PhotoSettings|
// should be false.
//
// As non-nullable fields are only allowed in version 0 of a struct, non-POD
// fields with version higher than 0 are nullable. That nullability should not
// be utilised.
[Stable]
struct PhotoState {
  // https://w3c.github.io/mediacapture-image/#mediatrackcapabilities-section
  // and https://w3c.github.io/mediacapture-image/#mediatracksettings-section

  // An array of unique supported values for
  // |PhotoSettings.white_balance_mode|.
  array<MeteringMode> supported_white_balance_modes;
  // The current white balance mode.
  // Only meaningful if |supported_white_balance_modes| is non-empty.
  MeteringMode current_white_balance_mode;
  // An array of unique supported values for |PhotoSettings.exposure_mode|.
  array<MeteringMode> supported_exposure_modes;
  // The current exposure_mode.
  // Only meaningful if |supported_exposure_modes| is non-empty.
  MeteringMode current_exposure_mode;
  // An array of unique supported values for |PhotoSettings.focus_mode|.
  array<MeteringMode> supported_focus_modes;
  // The current focus mode.
  // Only meaningful if |supported_focus_modes| is non-empty.
  MeteringMode current_focus_mode;
  // An array of current points of interest.
  array<Point2D> points_of_interest;

  // A range of supported values for |PhotoSettings.exposure_compensation| and
  // the current exposure compensation.
  // |exposure_compensation.current| is meaningful only if
  // |exposure_compensation.min| < |exposure_compensation.max|.
  Range exposure_compensation;
  // A range of supported values for |PhotoSettings.exposure_time| and
  // the current exposure time.
  // |exposure_time.current| is meaningful only if
  // |exposure_time.min| < |exposure_time.max|.
  Range exposure_time;
  // A range of supported values for |PhotoSettings.color_temperature| and
  // the current color temporature.
  // |color_temperature.current| is meaningful only if
  // |color_temperature.min| < |color_temperature.max|.
  Range color_temperature;
  // A range of supported values for |PhotoSettings.iso| and
  // the current exposure compensation.
  // |iso.current| is meaningful only if |iso.min| < |iso.max|.
  Range iso;

  // A range of supported values for |PhotoSettings.brightness| and the current
  // brightness.
  // |brightness.current| is meaningful only if
  // |brightness.min| < |brightness.max|.
  Range brightness;
  // A range of supported values for |PhotoSettings.contrast| and the current
  // contrast.
  // |contrast.current| is meaningful only if |contrast.min| < |contrast.max|.
  Range contrast;
  // A range of supported values for |PhotoSettings.saturation| and the current
  // saturation.
  // |saturation.current| is meaningful only if
  // |saturation.min| < |saturation.max|.
  Range saturation;
  // A range of supported values for |PhotoSettings.sharpness| and
  // the current sharpness.
  // |sharpness.current| is meaningful only if
  // |sharpness.min| < |sharpness.max|.
  Range sharpness;

  // A range of supported values for |PhotoSettings.focus_distance| and
  // the current focus distance.
  // |focus_distance.current| is meaningful only if
  // |focus_distance.min| < |focus_distance.max|.
  Range focus_distance;

  // A range of supported values for |PhotoSettings.pan| and the current pan.
  // |pan.current| is meaningful only if |pan.min| < |pan.max|.
  Range pan;
  // A range of supported values for |PhotoSettings.tilt| and the current tilt.
  // |tilt.current| is meaningful only if |tilt.min| < |tilt.max|.
  Range tilt;
  // A range of supported values for |PhotoSettings.zoom| and the current zoom.
  // |zoom.current| is meaningful only if |zoom.min| < |zoom.max|.
  Range zoom;

  // Whether |PhotoSettings.torch| is supported.
  bool supports_torch;
  // The current torch.
  // Only meaningful if |supports_torch| is true.
  bool torch;

  // https://w3c.github.io/mediacapture-image/##photocapabilities-section and
  // https://w3c.github.io/mediacapture-image/##photosettings-section
  RedEyeReduction red_eye_reduction;
  Range height;
  Range width;
  array<FillLightMode> fill_light_mode;

  // W3C Media Capture Extensions

  // An array of unique supported values for
  // |PhotoSettings.background_blur_mode|.
  // Should not be null (but is nullable for stable backward compatibility).
  [MinVersion=1]
  array<BackgroundBlurMode>? supported_background_blur_modes;
  // The current background blur mode.
  // Only meaningful if |supported_background_blur_modes| is non-empty.
  [MinVersion=1]
  BackgroundBlurMode background_blur_mode;
  // An array of unique supported values for
  // |PhotoSettings.current_face_framing_mode|.
  // Should not be null (but is nullable for stable backward compatibility).
  [MinVersion=2]
  array<MeteringMode>? supported_face_framing_modes;
  // The current face framing mode.
  // Only meaningful if |supported_face_framing_modes| is non-empty.
  [MinVersion=2]
  MeteringMode current_face_framing_mode;
  // An array of unique supported values for
  // |PhotoSettings.current_eye_gaze_correction_mode|.
  // Should not be null (but is nullable for stable backward compatibility).
  [MinVersion=3]
  array<EyeGazeCorrectionMode>? supported_eye_gaze_correction_modes;
  // The current eye gaze correction mode.
  // Only meaningful if |supported_eye_gaze_correction_modes| is non-empty.
  [MinVersion=3]
  EyeGazeCorrectionMode current_eye_gaze_correction_mode;
  // An array of unique supported values for
  // |PhotoSettings.background_segmentation_mask_state|.
  // Should not be null (but is nullable for stable backward compatibility).
  [MinVersion=4]
  array<bool>? supported_background_segmentation_mask_states;
  // The current background mask state.
  // Only meaningful if |supported_background_segmentation_mask_states| is
  // non-empty.
  [MinVersion=4]
  bool current_background_segmentation_mask_state;
};

// Equivalent to idl Point2D.
// https://w3c.github.io/mediacapture-image/#point2d-section
// TODO(mcasas): use gfx::mojom::PointF after https://crbug.com/640049.
[Stable]
struct Point2D {
  double x;
  double y;
};

// Equivalent to idl PhotoSettings + MediaTrackConstraintSet.
// Primitive types were not nullable in the past. This is the reason why older
// fields in this struct have has_ flags, and newer fields are nullable.
[Stable]
struct PhotoSettings {
  // https://w3c.github.io/mediacapture-image/#mediatracksettings-section and
  // https://w3c.github.io/mediacapture-image/#mediatrackconstraintset-section
  bool has_white_balance_mode;
  MeteringMode white_balance_mode;
  bool has_exposure_mode;
  MeteringMode exposure_mode;
  bool has_focus_mode;
  MeteringMode focus_mode;
  array<Point2D> points_of_interest;

  bool has_exposure_compensation;
  double exposure_compensation;
  bool has_exposure_time;
  double exposure_time;
  bool has_color_temperature;
  double color_temperature;
  bool has_iso;
  double iso;

  bool has_brightness;
  double brightness;
  bool has_contrast;
  double contrast;
  bool has_saturation;
  double saturation;
  bool has_sharpness;
  double sharpness;

  bool has_focus_distance;
  double focus_distance;

  bool has_pan;
  double pan;
  bool has_tilt;
  double tilt;
  bool has_zoom;
  double zoom;

  bool has_torch;
  bool torch;

  // https://w3c.github.io/mediacapture-image/##photosettings-section
  bool has_fill_light_mode;
  FillLightMode fill_light_mode;
  bool has_width;
  double width;
  bool has_height;
  double height;
  bool has_red_eye_reduction;
  bool red_eye_reduction;

  // W3C Media Capture Extensions
  [MinVersion=1]
  bool has_background_blur_mode;
  [MinVersion=1]
  BackgroundBlurMode background_blur_mode;
  [MinVersion=2]
  bool has_face_framing_mode;
  [MinVersion=2]
  MeteringMode face_framing_mode;
  [MinVersion=3]
  EyeGazeCorrectionMode? eye_gaze_correction_mode;
  [MinVersion=4]
  bool? background_segmentation_mask_state;
};

// This is a mojo move-only equivalent of a Blob, i.e. MIME type and Data.
[Stable]
struct Blob {
  string mime_type;
  array<uint8> data;
};

// |source_id| is the renderer-side UUID identifier of the image capture device.
interface ImageCapture
{
    // Retrieves the image capture device capabilities and current settings.
    // https://www.w3.org/TR/image-capture/#dom-imagecapture-getphotocapabilities
    GetPhotoState(string source_id)
        => (PhotoState state);

    // Sets the |settings| on the associated video capture device.
    SetPhotoOptions(string source_id, PhotoSettings settings)
        => (bool success);

    // Takes a Photo from the given |source_id|, returning it encoded in |blob|
    // with the format specified in its |mime_type|.
    // https://www.w3.org/TR/image-capture/#dom-imagecapture-takephoto
    TakePhoto(string source_id)
        => (Blob blob);
};