michael@0: /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* vim: set ts=2 et sw=2 tw=80: */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
michael@0:  * You can obtain one at http://mozilla.org/MPL/2.0/.
michael@0:  */
michael@0: 
michael@0: /* Camera regions are used to set focus and metering areas;
michael@0:    the coordinates are referenced to the sensor:
michael@0:      (-1000, -1000) is the top-left corner
michael@0:      (1000, 1000) is the bottom-right corner
michael@0:    The weight of the region can range from 0 to 1000. */
michael@0: dictionary CameraRegion
michael@0: {
michael@0:   long top = -1000;
michael@0:   long left = -1000;
michael@0:   long bottom = 1000;
michael@0:   long right = 1000;
michael@0:   unsigned long weight = 1000;
michael@0: };
michael@0: 
michael@0: /* The position information to record in the image header.
michael@0:    'NaN' indicates the information is not available. */
michael@0: dictionary CameraPosition
michael@0: {
michael@0:   unrestricted double latitude = NaN;
michael@0:   unrestricted double longitude = NaN;
michael@0:   unrestricted double altitude = NaN;
michael@0:   unrestricted double timestamp = NaN;
michael@0: };
michael@0: 
michael@0: /*
michael@0:   Options for takePicture().
michael@0: */
michael@0: dictionary CameraPictureOptions
michael@0: {
michael@0:   /* an object with a combination of 'height' and 'width' properties
michael@0:      chosen from CameraCapabilities.pictureSizes */
michael@0:   CameraSize pictureSize = null;
michael@0: 
michael@0:   /* one of the file formats chosen from
michael@0:      CameraCapabilities.fileFormats */
michael@0:   DOMString fileFormat = "";
michael@0: 
michael@0:   /* the rotation of the image in degrees, from 0 to 270 in
michael@0:      steps of 90; this doesn't affect the image, only the
michael@0:      rotation recorded in the image header.*/
michael@0:   long rotation = 0;
michael@0: 
michael@0:   /* an object containing any or all of 'latitude', 'longitude',
michael@0:      'altitude', and 'timestamp', used to record when and where
michael@0:      the image was taken.  e.g.
michael@0:      {
michael@0:          latitude:  43.647118,
michael@0:          longitude: -79.3943,
michael@0:          altitude:  500
michael@0:          // timestamp not specified, in this case, and
michael@0:          // won't be included in the image header
michael@0:      }
michael@0: 
michael@0:      can be null in the case where position information isn't
michael@0:      available/desired.
michael@0: 
michael@0:      'altitude' is in metres; 'timestamp' is UTC, in seconds from
michael@0:      January 1, 1970.
michael@0:   */
michael@0:   CameraPosition position = null;
michael@0: 
michael@0:   /* the number of seconds from January 1, 1970 UTC.  This can be
michael@0:      different from the positional timestamp (above). */
michael@0:   // XXXbz this should really accept a date too, no?
michael@0:   long long dateTime = 0;
michael@0: };
michael@0: 
michael@0: /* These properties affect the actual video recording, e.g.
michael@0:       {
michael@0:          rotation: 0,
michael@0:          maxFileSizeBytes: 1024 * 1024,
michael@0:          maxVideoLengthMs: 0
michael@0:       }
michael@0: 
michael@0:    'rotation' is the degrees clockwise to rotate the recorded video; if
michael@0:    this options is not supported, it will be ignored; if this option is
michael@0:    missing, the default is 0.
michael@0: 
michael@0:    'maxFileSizeBytes' is the maximum size in bytes to which the recorded
michael@0:    video file will be allowed to grow.
michael@0: 
michael@0:    'maxVideoLengthMs' is the maximum length in milliseconds to which the
michael@0:    recorded video will be allowed to grow.
michael@0: 
michael@0:    if either 'maxFileSizeBytes' or 'maxVideoLengthMs' is missing, zero,
michael@0:    or negative, that limit will be disabled.
michael@0: */
michael@0: dictionary CameraStartRecordingOptions
michael@0: {
michael@0:   long      rotation = 0;
michael@0:   long long maxFileSizeBytes = 0;
michael@0:   long long maxVideoLengthMs = 0;
michael@0: 
michael@0:   /* If startRecording() is called with flashMode set to "auto" and the
michael@0:      camera has determined that the scene is poorly lit, the flash mode
michael@0:      will be automatically changed to "torch" until stopRecording() is
michael@0:      called. During this time, flashMode will reflect the new setting. If
michael@0:      flashMode is changed while recording is in progress, the new setting
michael@0:      will be left as-is on stopRecording(). If the camera does not
michael@0:      support this setting, it will be ignored. */
michael@0:   boolean autoEnableLowLightTorch = false;
michael@0: };
michael@0: 
michael@0: callback CameraSetConfigurationCallback = void (CameraConfiguration configuration);
michael@0: callback CameraAutoFocusCallback = void (boolean focused);
michael@0: callback CameraTakePictureCallback = void (Blob picture);
michael@0: callback CameraStartRecordingCallback = void ();
michael@0: callback CameraShutterCallback = void ();
michael@0: callback CameraClosedCallback = void ();
michael@0: callback CameraReleaseCallback = void ();
michael@0: callback CameraRecorderStateChange = void (DOMString newState);
michael@0: callback CameraPreviewStateChange = void (DOMString newState);
michael@0: callback CameraAutoFocusMovingCallback = void (boolean isMoving);
michael@0: 
michael@0: /*
michael@0:     attributes here affect the preview, any pictures taken, and/or
michael@0:     any video recorded by the camera.
michael@0: */
michael@0: [Func="nsDOMCameraControl::HasSupport"]
michael@0: interface CameraControl : MediaStream
michael@0: {
michael@0:   [Constant, Cached]
michael@0:   readonly attribute CameraCapabilities capabilities;
michael@0: 
michael@0:   /* one of the values chosen from capabilities.effects;
michael@0:      default is "none" */
michael@0:   [Throws]
michael@0:   attribute DOMString       effect;
michael@0: 
michael@0:   /* one of the values chosen from capabilities.whiteBalanceModes;
michael@0:      default is "auto" */
michael@0:   [Throws]
michael@0:   attribute DOMString       whiteBalanceMode;
michael@0: 
michael@0:   /* one of the values chosen from capabilities.sceneModes;
michael@0:      default is "auto" */
michael@0:   [Throws]
michael@0:   attribute DOMString       sceneMode;
michael@0: 
michael@0:   /* one of the values chosen from capabilities.flashModes;
michael@0:      default is "auto" */
michael@0:   [Throws]
michael@0:   attribute DOMString       flashMode;
michael@0: 
michael@0:   /* one of the values chosen from capabilities.focusModes;
michael@0:      default is "auto", if supported, or "fixed" */
michael@0:   [Throws]
michael@0:   attribute DOMString       focusMode;
michael@0: 
michael@0:   /* one of the values chosen from capabilities.zoomRatios; other
michael@0:      values will be rounded to the nearest supported value;
michael@0:      default is 1.0 */
michael@0:   [Throws]
michael@0:   attribute double          zoom;
michael@0: 
michael@0:   /* an array of one or more objects that define where the
michael@0:      camera will perform light metering, each defining the properties:
michael@0:       {
michael@0:           top: -1000,
michael@0:           left: -1000,
michael@0:           bottom: 1000,
michael@0:           right: 1000,
michael@0:           weight: 1000
michael@0:       }
michael@0: 
michael@0:       'top', 'left', 'bottom', and 'right' all range from -1000 at
michael@0:       the top-/leftmost of the sensor to 1000 at the bottom-/rightmost
michael@0:       of the sensor.
michael@0: 
michael@0:       objects missing one or more of these properties will be ignored;
michael@0:       if the array contains more than capabilities.maxMeteringAreas,
michael@0:       extra areas will be ignored.
michael@0: 
michael@0:       this attribute can be set to null to allow the camera to determine
michael@0:       where to perform light metering. */
michael@0:   [Throws]
michael@0:   attribute any             meteringAreas;
michael@0: 
michael@0:   /* an array of one or more objects that define where the camera will
michael@0:      perform auto-focusing, with the same definition as meteringAreas.
michael@0: 
michael@0:      if the array contains more than capabilities.maxFocusAreas, extra
michael@0:      areas will be ignored.
michael@0: 
michael@0:      this attribute can be set to null to allow the camera to determine
michael@0:      where to focus. */
michael@0:   [Throws]
michael@0:   attribute any             focusAreas;
michael@0: 
michael@0:   /* focal length in millimetres */
michael@0:   [Throws]
michael@0:   readonly attribute double focalLength;
michael@0: 
michael@0:   /* the distances in metres to where the image subject appears to be
michael@0:      in focus.  'focusDistanceOptimum' is where the subject will appear
michael@0:      sharpest; the difference between 'focusDistanceFar' and
michael@0:      'focusDistanceNear' is the image's depth of field.
michael@0: 
michael@0:      'focusDistanceFar' may be infinity. */
michael@0:   [Throws]
michael@0:   readonly attribute double focusDistanceNear;
michael@0:   [Throws]
michael@0:   readonly attribute double focusDistanceOptimum;
michael@0:   [Throws]
michael@0:   readonly attribute unrestricted double focusDistanceFar;
michael@0: 
michael@0:   /* 'compensation' is optional, and if missing, will
michael@0:      set the camera to use automatic exposure compensation.
michael@0: 
michael@0:      acceptable values must range from minExposureCompensation
michael@0:      to maxExposureCompensation in steps of stepExposureCompensation;
michael@0:      invalid values will be rounded to the nearest valid value. */
michael@0:   [Throws]
michael@0:   void setExposureCompensation(optional double compensation);
michael@0:   [Throws]
michael@0:   readonly attribute unrestricted double exposureCompensation;
michael@0: 
michael@0:   /* one of the values chosen from capabilities.isoModes; default
michael@0:      value is "auto" if supported. */
michael@0:   [Throws]
michael@0:   attribute DOMString       isoMode;
michael@0: 
michael@0:   /* the function to call on the camera's shutter event, to trigger
michael@0:      a shutter sound and/or a visual shutter indicator. */
michael@0:   attribute CameraShutterCallback? onShutter;
michael@0: 
michael@0:   /* the function to call when the camera hardware is closed
michael@0:      by the underlying framework, e.g. when another app makes a more
michael@0:      recent call to get the camera. */
michael@0:   attribute CameraClosedCallback? onClosed;
michael@0: 
michael@0:   /* the function to call when the recorder changes state, either because
michael@0:      the recording process encountered an error, or because one of the
michael@0:      recording limits (see CameraStartRecordingOptions) was reached. */
michael@0:   attribute CameraRecorderStateChange? onRecorderStateChange;
michael@0: 
michael@0:   /* the function to call when the viewfinder stops or starts,
michael@0:      useful for synchronizing other UI elements. */
michael@0:   attribute CameraPreviewStateChange? onPreviewStateChange;
michael@0: 
michael@0:   /* the size of the picture to be returned by a call to takePicture();
michael@0:      an object with 'height' and 'width' properties that corresponds to
michael@0:      one of the options returned by capabilities.pictureSizes. */
michael@0:   [Throws]
michael@0:   attribute any              pictureSize;
michael@0: 
michael@0:   /* the size of the thumbnail to be included in the picture returned
michael@0:      by a call to takePicture(), assuming the chosen fileFormat supports
michael@0:      one; an object with 'height' and 'width' properties that corresponds
michael@0:      to one of the options returned by capabilities.pictureSizes.
michael@0: 
michael@0:      this setting should be considered a hint: the implementation will
michael@0:      respect it when possible, and override it if necessary. */
michael@0:   [Throws]
michael@0:   attribute any             thumbnailSize;
michael@0: 
michael@0:   /* the angle, in degrees, that the image sensor is mounted relative
michael@0:      to the display; e.g. if 'sensorAngle' is 270 degrees (or -90 degrees),
michael@0:      then the preview stream needs to be rotated +90 degrees to have the
michael@0:      same orientation as the real world. */
michael@0:   readonly attribute long   sensorAngle;
michael@0: 
michael@0:   /* tell the camera to attempt to focus the image */
michael@0:   [Throws]
michael@0:   void autoFocus(CameraAutoFocusCallback onSuccess, optional CameraErrorCallback onError);
michael@0: 
michael@0:   /* if continuous autofocus is supported and focusMode is set to enable it,
michael@0:      then this function is called whenever the camera decides to start and
michael@0:      stop moving the focus position; it can be used to update a UI element to
michael@0:      indicate that the camera is still trying to focus, or has finished. Some
michael@0:      platforms do not support this event, in which case the callback is never
michael@0:      invoked. */
michael@0:   [Pref="camera.control.autofocus_moving_callback.enabled"]
michael@0:   attribute CameraAutoFocusMovingCallback? onAutoFocusMoving;
michael@0: 
michael@0:   /* capture an image and return it as a blob to the 'onSuccess' callback;
michael@0:      if the camera supports it, this may be invoked while the camera is
michael@0:      already recording video.
michael@0: 
michael@0:      invoking this function will stop the preview stream, which must be
michael@0:      manually restarted (e.g. by calling .play() on it). */
michael@0:   [Throws]
michael@0:   void takePicture(CameraPictureOptions aOptions,
michael@0:                    CameraTakePictureCallback onSuccess,
michael@0:                    optional CameraErrorCallback onError);
michael@0: 
michael@0:   /* start recording video; 'aOptions' is a
michael@0:      CameraStartRecordingOptions object. */
michael@0:   [Throws]
michael@0:   void startRecording(CameraStartRecordingOptions aOptions,
michael@0:                       DeviceStorage storageArea,
michael@0:                       DOMString filename,
michael@0:                       CameraStartRecordingCallback onSuccess,
michael@0:                       optional CameraErrorCallback onError);
michael@0: 
michael@0:   /* stop precording video. */
michael@0:   [Throws]
michael@0:   void stopRecording();
michael@0: 
michael@0:   /* call in or after the takePicture() onSuccess callback to
michael@0:      resume the camera preview stream. */
michael@0:   [Throws]
michael@0:   void resumePreview();
michael@0: 
michael@0:   /* release the camera so that other applications can use it; you should
michael@0:      probably call this whenever the camera is not longer in the foreground
michael@0:      (depending on your usage model).
michael@0: 
michael@0:      the callbacks are optional, unless you really need to know when
michael@0:      the hardware is ultimately released.
michael@0: 
michael@0:      once this is called, the camera control object is to be considered
michael@0:      defunct; a new instance will need to be created to access the camera. */
michael@0:   [Throws]
michael@0:   void release(optional CameraReleaseCallback onSuccess,
michael@0:                optional CameraErrorCallback onError);
michael@0: 
michael@0:   /* changes the camera configuration on the fly;
michael@0:      'configuration' is of type CameraConfiguration.
michael@0: 
michael@0:      XXXmikeh the 'configuration' argument needs to be optional, else
michael@0:      the WebIDL compiler throws: "WebIDL.WebIDLError: error: Dictionary
michael@0:      argument or union argument containing a dictionary not followed by
michael@0:      a required argument must be optional"
michael@0:   */
michael@0:   [Throws]
michael@0:   void setConfiguration(optional CameraConfiguration configuration,
michael@0:                         optional CameraSetConfigurationCallback onSuccess,
michael@0:                         optional CameraErrorCallback onError);
michael@0: 
michael@0:   /* if focusMode is set to either 'continuous-picture' or 'continuous-video',
michael@0:      then calling autoFocus() will trigger its onSuccess callback immediately
michael@0:      if the camera was either successfully focused, or if no focus could be
michael@0:      acquired; if the focus acquisition is still in progress, the onSuccess
michael@0:      callback will be invoked later, its argument indicating success or
michael@0:      failure.
michael@0: 
michael@0:      once autoFocus() is called with a continuous autofocus mode set, the
michael@0:      continuous autofocus process is stopped and focus is locked in the
michael@0:      current state until this method is called.
michael@0:   */
michael@0:   [Throws]
michael@0:   void resumeContinuousFocus();
michael@0: };
michael@0: 
michael@0: /* The coordinates of a point, relative to the camera sensor, of the center of
michael@0:    detected facial features. As with CameraRegions:
michael@0:      { x: -1000, y: -1000 } is the top-left corner
michael@0:      { x:  1000, y:  1000 } is the bottom-right corner
michael@0:    x and y can range from -1000 to 1000.
michael@0: */
michael@0: [Pref="camera.control.face_detection.enabled", Func="DOMCameraPoint::HasSupport"]
michael@0: interface CameraPoint
michael@0: {
michael@0:   attribute long x;
michael@0:   attribute long y;
michael@0: };
michael@0: 
michael@0: /* The information of the each face detected by a camera device, e.g.
michael@0:      {
michael@0:        id: 1,
michael@0:        score: 80,
michael@0:        bound: { left:   -203,
michael@0:                 top:    -400,
michael@0:                 right:   300,
michael@0:                 bottom:  250 },
michael@0:        leftEye:  { x:  -100,
michael@0:                    y:  -200 },
michael@0:        rightEye: { x:   100,
michael@0:                    y:   100 },
michael@0:        mouth:    { x:   150,
michael@0:                    y:   150 } }
michael@0: 
michael@0:    'id' is an unique value per face while the face is visible to the tracker.
michael@0:    If the face leaves the viewfinder and then returns, it will be assigned
michael@0:    a new value.
michael@0: 
michael@0:    'score' is the confidence level for the detection of the face.
michael@0:    This range is 1 to 100, where 100 is the highest confidence.
michael@0: 
michael@0:    'bounds' is the bounds of the face. It is guaranteed left < right and
michael@0:    top < bottom. The coordinates can be smaller than -1000 or bigger than 1000.
michael@0:    But at least one vertex will be within (-1000, -1000) and (1000, 1000).
michael@0: 
michael@0:    'leftEye' is the coordinates of the centre of the left eye. The coordinates
michael@0:    are in the same space as the ones for 'bounds'. This is an optional field
michael@0:    and may not be supported on all devices. If it is not supported or detected,
michael@0:    the value will be set to null.
michael@0: 
michael@0:    'rightEye' is the coordinates of the detected right eye; null if not
michael@0:    supported or detected.
michael@0: 
michael@0:    'mouth' is the coordinates of the detected mouth; null if not supported or
michael@0:    detected.
michael@0: */
michael@0: [Pref="camera.control.face_detection.enabled", Func="DOMCameraDetectedFace::HasSupport"]
michael@0: interface CameraDetectedFace
michael@0: {
michael@0:   readonly attribute unsigned long id;
michael@0: 
michael@0:   readonly attribute unsigned long score;
michael@0: 
michael@0:   readonly attribute DOMRect bounds;
michael@0: 
michael@0:   readonly attribute boolean hasLeftEye;
michael@0:   readonly attribute CameraPoint? leftEye;
michael@0: 
michael@0:   readonly attribute boolean hasRightEye;
michael@0:   readonly attribute CameraPoint? rightEye;
michael@0: 
michael@0:   readonly attribute boolean hasMouth;
michael@0:   readonly attribute CameraPoint? mouth;
michael@0: };
michael@0: 
michael@0: callback CameraFaceDetectionCallback = void (sequence<CameraDetectedFace> faces);
michael@0: 
michael@0: partial interface CameraControl
michael@0: {
michael@0:   /* Starts the face detection. This should be called after the preview is
michael@0:      started. The camera will periodically call 'onFacesDetected' with a
michael@0:      sequence of zero or one or more detected faces in the preview frame.
michael@0: 
michael@0:      How often the callback is invoked is implementation dependent.
michael@0: 
michael@0:      This method throws an exception if face detection fails to start.
michael@0:   */
michael@0:   [Throws, Pref="camera.control.face_detection.enabled"]
michael@0:   void startFaceDetection();
michael@0: 
michael@0:   /* Stops the face detection.
michael@0: 
michael@0:      This method throws an exception if face detection can't be stopped.
michael@0:   */
michael@0:   [Throws, Pref="camera.control.face_detection.enabled"]
michael@0:   void stopFaceDetection();
michael@0: 
michael@0:   /* Callback for faces detected in the preview frame. If no faces are
michael@0:      detected, the callback is invoked with an empty sequence. */
michael@0:   [Pref="camera.control.face_detection.enabled"]
michael@0:   attribute CameraFaceDetectionCallback? onFacesDetected;
michael@0: };