1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/webidl/CameraControl.webidl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,448 @@
1.4 +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* vim: set ts=2 et sw=2 tw=80: */
1.6 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this file,
1.8 + * You can obtain one at http://mozilla.org/MPL/2.0/.
1.9 + */
1.10 +
1.11 +/* Camera regions are used to set focus and metering areas;
1.12 + the coordinates are referenced to the sensor:
1.13 + (-1000, -1000) is the top-left corner
1.14 + (1000, 1000) is the bottom-right corner
1.15 + The weight of the region can range from 0 to 1000. */
1.16 +dictionary CameraRegion
1.17 +{
1.18 + long top = -1000;
1.19 + long left = -1000;
1.20 + long bottom = 1000;
1.21 + long right = 1000;
1.22 + unsigned long weight = 1000;
1.23 +};
1.24 +
1.25 +/* The position information to record in the image header.
1.26 + 'NaN' indicates the information is not available. */
1.27 +dictionary CameraPosition
1.28 +{
1.29 + unrestricted double latitude = NaN;
1.30 + unrestricted double longitude = NaN;
1.31 + unrestricted double altitude = NaN;
1.32 + unrestricted double timestamp = NaN;
1.33 +};
1.34 +
1.35 +/*
1.36 + Options for takePicture().
1.37 +*/
1.38 +dictionary CameraPictureOptions
1.39 +{
1.40 + /* an object with a combination of 'height' and 'width' properties
1.41 + chosen from CameraCapabilities.pictureSizes */
1.42 + CameraSize pictureSize = null;
1.43 +
1.44 + /* one of the file formats chosen from
1.45 + CameraCapabilities.fileFormats */
1.46 + DOMString fileFormat = "";
1.47 +
1.48 + /* the rotation of the image in degrees, from 0 to 270 in
1.49 + steps of 90; this doesn't affect the image, only the
1.50 + rotation recorded in the image header.*/
1.51 + long rotation = 0;
1.52 +
1.53 + /* an object containing any or all of 'latitude', 'longitude',
1.54 + 'altitude', and 'timestamp', used to record when and where
1.55 + the image was taken. e.g.
1.56 + {
1.57 + latitude: 43.647118,
1.58 + longitude: -79.3943,
1.59 + altitude: 500
1.60 + // timestamp not specified, in this case, and
1.61 + // won't be included in the image header
1.62 + }
1.63 +
1.64 + can be null in the case where position information isn't
1.65 + available/desired.
1.66 +
1.67 + 'altitude' is in metres; 'timestamp' is UTC, in seconds from
1.68 + January 1, 1970.
1.69 + */
1.70 + CameraPosition position = null;
1.71 +
1.72 + /* the number of seconds from January 1, 1970 UTC. This can be
1.73 + different from the positional timestamp (above). */
1.74 + // XXXbz this should really accept a date too, no?
1.75 + long long dateTime = 0;
1.76 +};
1.77 +
1.78 +/* These properties affect the actual video recording, e.g.
1.79 + {
1.80 + rotation: 0,
1.81 + maxFileSizeBytes: 1024 * 1024,
1.82 + maxVideoLengthMs: 0
1.83 + }
1.84 +
1.85 + 'rotation' is the degrees clockwise to rotate the recorded video; if
1.86 + this options is not supported, it will be ignored; if this option is
1.87 + missing, the default is 0.
1.88 +
1.89 + 'maxFileSizeBytes' is the maximum size in bytes to which the recorded
1.90 + video file will be allowed to grow.
1.91 +
1.92 + 'maxVideoLengthMs' is the maximum length in milliseconds to which the
1.93 + recorded video will be allowed to grow.
1.94 +
1.95 + if either 'maxFileSizeBytes' or 'maxVideoLengthMs' is missing, zero,
1.96 + or negative, that limit will be disabled.
1.97 +*/
1.98 +dictionary CameraStartRecordingOptions
1.99 +{
1.100 + long rotation = 0;
1.101 + long long maxFileSizeBytes = 0;
1.102 + long long maxVideoLengthMs = 0;
1.103 +
1.104 + /* If startRecording() is called with flashMode set to "auto" and the
1.105 + camera has determined that the scene is poorly lit, the flash mode
1.106 + will be automatically changed to "torch" until stopRecording() is
1.107 + called. During this time, flashMode will reflect the new setting. If
1.108 + flashMode is changed while recording is in progress, the new setting
1.109 + will be left as-is on stopRecording(). If the camera does not
1.110 + support this setting, it will be ignored. */
1.111 + boolean autoEnableLowLightTorch = false;
1.112 +};
1.113 +
1.114 +callback CameraSetConfigurationCallback = void (CameraConfiguration configuration);
1.115 +callback CameraAutoFocusCallback = void (boolean focused);
1.116 +callback CameraTakePictureCallback = void (Blob picture);
1.117 +callback CameraStartRecordingCallback = void ();
1.118 +callback CameraShutterCallback = void ();
1.119 +callback CameraClosedCallback = void ();
1.120 +callback CameraReleaseCallback = void ();
1.121 +callback CameraRecorderStateChange = void (DOMString newState);
1.122 +callback CameraPreviewStateChange = void (DOMString newState);
1.123 +callback CameraAutoFocusMovingCallback = void (boolean isMoving);
1.124 +
1.125 +/*
1.126 + attributes here affect the preview, any pictures taken, and/or
1.127 + any video recorded by the camera.
1.128 +*/
1.129 +[Func="nsDOMCameraControl::HasSupport"]
1.130 +interface CameraControl : MediaStream
1.131 +{
1.132 + [Constant, Cached]
1.133 + readonly attribute CameraCapabilities capabilities;
1.134 +
1.135 + /* one of the values chosen from capabilities.effects;
1.136 + default is "none" */
1.137 + [Throws]
1.138 + attribute DOMString effect;
1.139 +
1.140 + /* one of the values chosen from capabilities.whiteBalanceModes;
1.141 + default is "auto" */
1.142 + [Throws]
1.143 + attribute DOMString whiteBalanceMode;
1.144 +
1.145 + /* one of the values chosen from capabilities.sceneModes;
1.146 + default is "auto" */
1.147 + [Throws]
1.148 + attribute DOMString sceneMode;
1.149 +
1.150 + /* one of the values chosen from capabilities.flashModes;
1.151 + default is "auto" */
1.152 + [Throws]
1.153 + attribute DOMString flashMode;
1.154 +
1.155 + /* one of the values chosen from capabilities.focusModes;
1.156 + default is "auto", if supported, or "fixed" */
1.157 + [Throws]
1.158 + attribute DOMString focusMode;
1.159 +
1.160 + /* one of the values chosen from capabilities.zoomRatios; other
1.161 + values will be rounded to the nearest supported value;
1.162 + default is 1.0 */
1.163 + [Throws]
1.164 + attribute double zoom;
1.165 +
1.166 + /* an array of one or more objects that define where the
1.167 + camera will perform light metering, each defining the properties:
1.168 + {
1.169 + top: -1000,
1.170 + left: -1000,
1.171 + bottom: 1000,
1.172 + right: 1000,
1.173 + weight: 1000
1.174 + }
1.175 +
1.176 + 'top', 'left', 'bottom', and 'right' all range from -1000 at
1.177 + the top-/leftmost of the sensor to 1000 at the bottom-/rightmost
1.178 + of the sensor.
1.179 +
1.180 + objects missing one or more of these properties will be ignored;
1.181 + if the array contains more than capabilities.maxMeteringAreas,
1.182 + extra areas will be ignored.
1.183 +
1.184 + this attribute can be set to null to allow the camera to determine
1.185 + where to perform light metering. */
1.186 + [Throws]
1.187 + attribute any meteringAreas;
1.188 +
1.189 + /* an array of one or more objects that define where the camera will
1.190 + perform auto-focusing, with the same definition as meteringAreas.
1.191 +
1.192 + if the array contains more than capabilities.maxFocusAreas, extra
1.193 + areas will be ignored.
1.194 +
1.195 + this attribute can be set to null to allow the camera to determine
1.196 + where to focus. */
1.197 + [Throws]
1.198 + attribute any focusAreas;
1.199 +
1.200 + /* focal length in millimetres */
1.201 + [Throws]
1.202 + readonly attribute double focalLength;
1.203 +
1.204 + /* the distances in metres to where the image subject appears to be
1.205 + in focus. 'focusDistanceOptimum' is where the subject will appear
1.206 + sharpest; the difference between 'focusDistanceFar' and
1.207 + 'focusDistanceNear' is the image's depth of field.
1.208 +
1.209 + 'focusDistanceFar' may be infinity. */
1.210 + [Throws]
1.211 + readonly attribute double focusDistanceNear;
1.212 + [Throws]
1.213 + readonly attribute double focusDistanceOptimum;
1.214 + [Throws]
1.215 + readonly attribute unrestricted double focusDistanceFar;
1.216 +
1.217 + /* 'compensation' is optional, and if missing, will
1.218 + set the camera to use automatic exposure compensation.
1.219 +
1.220 + acceptable values must range from minExposureCompensation
1.221 + to maxExposureCompensation in steps of stepExposureCompensation;
1.222 + invalid values will be rounded to the nearest valid value. */
1.223 + [Throws]
1.224 + void setExposureCompensation(optional double compensation);
1.225 + [Throws]
1.226 + readonly attribute unrestricted double exposureCompensation;
1.227 +
1.228 + /* one of the values chosen from capabilities.isoModes; default
1.229 + value is "auto" if supported. */
1.230 + [Throws]
1.231 + attribute DOMString isoMode;
1.232 +
1.233 + /* the function to call on the camera's shutter event, to trigger
1.234 + a shutter sound and/or a visual shutter indicator. */
1.235 + attribute CameraShutterCallback? onShutter;
1.236 +
1.237 + /* the function to call when the camera hardware is closed
1.238 + by the underlying framework, e.g. when another app makes a more
1.239 + recent call to get the camera. */
1.240 + attribute CameraClosedCallback? onClosed;
1.241 +
1.242 + /* the function to call when the recorder changes state, either because
1.243 + the recording process encountered an error, or because one of the
1.244 + recording limits (see CameraStartRecordingOptions) was reached. */
1.245 + attribute CameraRecorderStateChange? onRecorderStateChange;
1.246 +
1.247 + /* the function to call when the viewfinder stops or starts,
1.248 + useful for synchronizing other UI elements. */
1.249 + attribute CameraPreviewStateChange? onPreviewStateChange;
1.250 +
1.251 + /* the size of the picture to be returned by a call to takePicture();
1.252 + an object with 'height' and 'width' properties that corresponds to
1.253 + one of the options returned by capabilities.pictureSizes. */
1.254 + [Throws]
1.255 + attribute any pictureSize;
1.256 +
1.257 + /* the size of the thumbnail to be included in the picture returned
1.258 + by a call to takePicture(), assuming the chosen fileFormat supports
1.259 + one; an object with 'height' and 'width' properties that corresponds
1.260 + to one of the options returned by capabilities.pictureSizes.
1.261 +
1.262 + this setting should be considered a hint: the implementation will
1.263 + respect it when possible, and override it if necessary. */
1.264 + [Throws]
1.265 + attribute any thumbnailSize;
1.266 +
1.267 + /* the angle, in degrees, that the image sensor is mounted relative
1.268 + to the display; e.g. if 'sensorAngle' is 270 degrees (or -90 degrees),
1.269 + then the preview stream needs to be rotated +90 degrees to have the
1.270 + same orientation as the real world. */
1.271 + readonly attribute long sensorAngle;
1.272 +
1.273 + /* tell the camera to attempt to focus the image */
1.274 + [Throws]
1.275 + void autoFocus(CameraAutoFocusCallback onSuccess, optional CameraErrorCallback onError);
1.276 +
1.277 + /* if continuous autofocus is supported and focusMode is set to enable it,
1.278 + then this function is called whenever the camera decides to start and
1.279 + stop moving the focus position; it can be used to update a UI element to
1.280 + indicate that the camera is still trying to focus, or has finished. Some
1.281 + platforms do not support this event, in which case the callback is never
1.282 + invoked. */
1.283 + [Pref="camera.control.autofocus_moving_callback.enabled"]
1.284 + attribute CameraAutoFocusMovingCallback? onAutoFocusMoving;
1.285 +
1.286 + /* capture an image and return it as a blob to the 'onSuccess' callback;
1.287 + if the camera supports it, this may be invoked while the camera is
1.288 + already recording video.
1.289 +
1.290 + invoking this function will stop the preview stream, which must be
1.291 + manually restarted (e.g. by calling .play() on it). */
1.292 + [Throws]
1.293 + void takePicture(CameraPictureOptions aOptions,
1.294 + CameraTakePictureCallback onSuccess,
1.295 + optional CameraErrorCallback onError);
1.296 +
1.297 + /* start recording video; 'aOptions' is a
1.298 + CameraStartRecordingOptions object. */
1.299 + [Throws]
1.300 + void startRecording(CameraStartRecordingOptions aOptions,
1.301 + DeviceStorage storageArea,
1.302 + DOMString filename,
1.303 + CameraStartRecordingCallback onSuccess,
1.304 + optional CameraErrorCallback onError);
1.305 +
1.306 + /* stop precording video. */
1.307 + [Throws]
1.308 + void stopRecording();
1.309 +
1.310 + /* call in or after the takePicture() onSuccess callback to
1.311 + resume the camera preview stream. */
1.312 + [Throws]
1.313 + void resumePreview();
1.314 +
1.315 + /* release the camera so that other applications can use it; you should
1.316 + probably call this whenever the camera is not longer in the foreground
1.317 + (depending on your usage model).
1.318 +
1.319 + the callbacks are optional, unless you really need to know when
1.320 + the hardware is ultimately released.
1.321 +
1.322 + once this is called, the camera control object is to be considered
1.323 + defunct; a new instance will need to be created to access the camera. */
1.324 + [Throws]
1.325 + void release(optional CameraReleaseCallback onSuccess,
1.326 + optional CameraErrorCallback onError);
1.327 +
1.328 + /* changes the camera configuration on the fly;
1.329 + 'configuration' is of type CameraConfiguration.
1.330 +
1.331 + XXXmikeh the 'configuration' argument needs to be optional, else
1.332 + the WebIDL compiler throws: "WebIDL.WebIDLError: error: Dictionary
1.333 + argument or union argument containing a dictionary not followed by
1.334 + a required argument must be optional"
1.335 + */
1.336 + [Throws]
1.337 + void setConfiguration(optional CameraConfiguration configuration,
1.338 + optional CameraSetConfigurationCallback onSuccess,
1.339 + optional CameraErrorCallback onError);
1.340 +
1.341 + /* if focusMode is set to either 'continuous-picture' or 'continuous-video',
1.342 + then calling autoFocus() will trigger its onSuccess callback immediately
1.343 + if the camera was either successfully focused, or if no focus could be
1.344 + acquired; if the focus acquisition is still in progress, the onSuccess
1.345 + callback will be invoked later, its argument indicating success or
1.346 + failure.
1.347 +
1.348 + once autoFocus() is called with a continuous autofocus mode set, the
1.349 + continuous autofocus process is stopped and focus is locked in the
1.350 + current state until this method is called.
1.351 + */
1.352 + [Throws]
1.353 + void resumeContinuousFocus();
1.354 +};
1.355 +
1.356 +/* The coordinates of a point, relative to the camera sensor, of the center of
1.357 + detected facial features. As with CameraRegions:
1.358 + { x: -1000, y: -1000 } is the top-left corner
1.359 + { x: 1000, y: 1000 } is the bottom-right corner
1.360 + x and y can range from -1000 to 1000.
1.361 +*/
1.362 +[Pref="camera.control.face_detection.enabled", Func="DOMCameraPoint::HasSupport"]
1.363 +interface CameraPoint
1.364 +{
1.365 + attribute long x;
1.366 + attribute long y;
1.367 +};
1.368 +
1.369 +/* The information of the each face detected by a camera device, e.g.
1.370 + {
1.371 + id: 1,
1.372 + score: 80,
1.373 + bound: { left: -203,
1.374 + top: -400,
1.375 + right: 300,
1.376 + bottom: 250 },
1.377 + leftEye: { x: -100,
1.378 + y: -200 },
1.379 + rightEye: { x: 100,
1.380 + y: 100 },
1.381 + mouth: { x: 150,
1.382 + y: 150 } }
1.383 +
1.384 + 'id' is an unique value per face while the face is visible to the tracker.
1.385 + If the face leaves the viewfinder and then returns, it will be assigned
1.386 + a new value.
1.387 +
1.388 + 'score' is the confidence level for the detection of the face.
1.389 + This range is 1 to 100, where 100 is the highest confidence.
1.390 +
1.391 + 'bounds' is the bounds of the face. It is guaranteed left < right and
1.392 + top < bottom. The coordinates can be smaller than -1000 or bigger than 1000.
1.393 + But at least one vertex will be within (-1000, -1000) and (1000, 1000).
1.394 +
1.395 + 'leftEye' is the coordinates of the centre of the left eye. The coordinates
1.396 + are in the same space as the ones for 'bounds'. This is an optional field
1.397 + and may not be supported on all devices. If it is not supported or detected,
1.398 + the value will be set to null.
1.399 +
1.400 + 'rightEye' is the coordinates of the detected right eye; null if not
1.401 + supported or detected.
1.402 +
1.403 + 'mouth' is the coordinates of the detected mouth; null if not supported or
1.404 + detected.
1.405 +*/
1.406 +[Pref="camera.control.face_detection.enabled", Func="DOMCameraDetectedFace::HasSupport"]
1.407 +interface CameraDetectedFace
1.408 +{
1.409 + readonly attribute unsigned long id;
1.410 +
1.411 + readonly attribute unsigned long score;
1.412 +
1.413 + readonly attribute DOMRect bounds;
1.414 +
1.415 + readonly attribute boolean hasLeftEye;
1.416 + readonly attribute CameraPoint? leftEye;
1.417 +
1.418 + readonly attribute boolean hasRightEye;
1.419 + readonly attribute CameraPoint? rightEye;
1.420 +
1.421 + readonly attribute boolean hasMouth;
1.422 + readonly attribute CameraPoint? mouth;
1.423 +};
1.424 +
1.425 +callback CameraFaceDetectionCallback = void (sequence<CameraDetectedFace> faces);
1.426 +
1.427 +partial interface CameraControl
1.428 +{
1.429 + /* Starts the face detection. This should be called after the preview is
1.430 + started. The camera will periodically call 'onFacesDetected' with a
1.431 + sequence of zero or one or more detected faces in the preview frame.
1.432 +
1.433 + How often the callback is invoked is implementation dependent.
1.434 +
1.435 + This method throws an exception if face detection fails to start.
1.436 + */
1.437 + [Throws, Pref="camera.control.face_detection.enabled"]
1.438 + void startFaceDetection();
1.439 +
1.440 + /* Stops the face detection.
1.441 +
1.442 + This method throws an exception if face detection can't be stopped.
1.443 + */
1.444 + [Throws, Pref="camera.control.face_detection.enabled"]
1.445 + void stopFaceDetection();
1.446 +
1.447 + /* Callback for faces detected in the preview frame. If no faces are
1.448 + detected, the callback is invoked with an empty sequence. */
1.449 + [Pref="camera.control.face_detection.enabled"]
1.450 + attribute CameraFaceDetectionCallback? onFacesDetected;
1.451 +};
