The Tor Browser / file comparison
comparison: dom/webidl/CameraControl.webidl
dom/webidl/CameraControl.webidl
- changeset 0
- 6474c204b198
equal
deleted
inserted
replaced
| -1:000000000000 | 0:48a6fa3bcaba |
|---|---|
| 1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ | |
| 2 /* vim: set ts=2 et sw=2 tw=80: */ | |
| 3 /* This Source Code Form is subject to the terms of the Mozilla Public | |
| 4 * License, v. 2.0. If a copy of the MPL was not distributed with this file, | |
| 5 * You can obtain one at http://mozilla.org/MPL/2.0/. | |
| 6 */ | |
| 7 | |
| 8 /* Camera regions are used to set focus and metering areas; | |
| 9 the coordinates are referenced to the sensor: | |
| 10 (-1000, -1000) is the top-left corner | |
| 11 (1000, 1000) is the bottom-right corner | |
| 12 The weight of the region can range from 0 to 1000. */ | |
| 13 dictionary CameraRegion | |
| 14 { | |
| 15 long top = -1000; | |
| 16 long left = -1000; | |
| 17 long bottom = 1000; | |
| 18 long right = 1000; | |
| 19 unsigned long weight = 1000; | |
| 20 }; | |
| 21 | |
| 22 /* The position information to record in the image header. | |
| 23 'NaN' indicates the information is not available. */ | |
| 24 dictionary CameraPosition | |
| 25 { | |
| 26 unrestricted double latitude = NaN; | |
| 27 unrestricted double longitude = NaN; | |
| 28 unrestricted double altitude = NaN; | |
| 29 unrestricted double timestamp = NaN; | |
| 30 }; | |
| 31 | |
| 32 /* | |
| 33 Options for takePicture(). | |
| 34 */ | |
| 35 dictionary CameraPictureOptions | |
| 36 { | |
| 37 /* an object with a combination of 'height' and 'width' properties | |
| 38 chosen from CameraCapabilities.pictureSizes */ | |
| 39 CameraSize pictureSize = null; | |
| 40 | |
| 41 /* one of the file formats chosen from | |
| 42 CameraCapabilities.fileFormats */ | |
| 43 DOMString fileFormat = ""; | |
| 44 | |
| 45 /* the rotation of the image in degrees, from 0 to 270 in | |
| 46 steps of 90; this doesn't affect the image, only the | |
| 47 rotation recorded in the image header.*/ | |
| 48 long rotation = 0; | |
| 49 | |
| 50 /* an object containing any or all of 'latitude', 'longitude', | |
| 51 'altitude', and 'timestamp', used to record when and where | |
| 52 the image was taken. e.g. | |
| 53 { | |
| 54 latitude: 43.647118, | |
| 55 longitude: -79.3943, | |
| 56 altitude: 500 | |
| 57 // timestamp not specified, in this case, and | |
| 58 // won't be included in the image header | |
| 59 } | |
| 60 | |
| 61 can be null in the case where position information isn't | |
| 62 available/desired. | |
| 63 | |
| 64 'altitude' is in metres; 'timestamp' is UTC, in seconds from | |
| 65 January 1, 1970. | |
| 66 */ | |
| 67 CameraPosition position = null; | |
| 68 | |
| 69 /* the number of seconds from January 1, 1970 UTC. This can be | |
| 70 different from the positional timestamp (above). */ | |
| 71 // XXXbz this should really accept a date too, no? | |
| 72 long long dateTime = 0; | |
| 73 }; | |
| 74 | |
| 75 /* These properties affect the actual video recording, e.g. | |
| 76 { | |
| 77 rotation: 0, | |
| 78 maxFileSizeBytes: 1024 * 1024, | |
| 79 maxVideoLengthMs: 0 | |
| 80 } | |
| 81 | |
| 82 'rotation' is the degrees clockwise to rotate the recorded video; if | |
| 83 this options is not supported, it will be ignored; if this option is | |
| 84 missing, the default is 0. | |
| 85 | |
| 86 'maxFileSizeBytes' is the maximum size in bytes to which the recorded | |
| 87 video file will be allowed to grow. | |
| 88 | |
| 89 'maxVideoLengthMs' is the maximum length in milliseconds to which the | |
| 90 recorded video will be allowed to grow. | |
| 91 | |
| 92 if either 'maxFileSizeBytes' or 'maxVideoLengthMs' is missing, zero, | |
| 93 or negative, that limit will be disabled. | |
| 94 */ | |
| 95 dictionary CameraStartRecordingOptions | |
| 96 { | |
| 97 long rotation = 0; | |
| 98 long long maxFileSizeBytes = 0; | |
| 99 long long maxVideoLengthMs = 0; | |
| 100 | |
| 101 /* If startRecording() is called with flashMode set to "auto" and the | |
| 102 camera has determined that the scene is poorly lit, the flash mode | |
| 103 will be automatically changed to "torch" until stopRecording() is | |
| 104 called. During this time, flashMode will reflect the new setting. If | |
| 105 flashMode is changed while recording is in progress, the new setting | |
| 106 will be left as-is on stopRecording(). If the camera does not | |
| 107 support this setting, it will be ignored. */ | |
| 108 boolean autoEnableLowLightTorch = false; | |
| 109 }; | |
| 110 | |
| 111 callback CameraSetConfigurationCallback = void (CameraConfiguration configuration); | |
| 112 callback CameraAutoFocusCallback = void (boolean focused); | |
| 113 callback CameraTakePictureCallback = void (Blob picture); | |
| 114 callback CameraStartRecordingCallback = void (); | |
| 115 callback CameraShutterCallback = void (); | |
| 116 callback CameraClosedCallback = void (); | |
| 117 callback CameraReleaseCallback = void (); | |
| 118 callback CameraRecorderStateChange = void (DOMString newState); | |
| 119 callback CameraPreviewStateChange = void (DOMString newState); | |
| 120 callback CameraAutoFocusMovingCallback = void (boolean isMoving); | |
| 121 | |
| 122 /* | |
| 123 attributes here affect the preview, any pictures taken, and/or | |
| 124 any video recorded by the camera. | |
| 125 */ | |
| 126 [Func="nsDOMCameraControl::HasSupport"] | |
| 127 interface CameraControl : MediaStream | |
| 128 { | |
| 129 [Constant, Cached] | |
| 130 readonly attribute CameraCapabilities capabilities; | |
| 131 | |
| 132 /* one of the values chosen from capabilities.effects; | |
| 133 default is "none" */ | |
| 134 [Throws] | |
| 135 attribute DOMString effect; | |
| 136 | |
| 137 /* one of the values chosen from capabilities.whiteBalanceModes; | |
| 138 default is "auto" */ | |
| 139 [Throws] | |
| 140 attribute DOMString whiteBalanceMode; | |
| 141 | |
| 142 /* one of the values chosen from capabilities.sceneModes; | |
| 143 default is "auto" */ | |
| 144 [Throws] | |
| 145 attribute DOMString sceneMode; | |
| 146 | |
| 147 /* one of the values chosen from capabilities.flashModes; | |
| 148 default is "auto" */ | |
| 149 [Throws] | |
| 150 attribute DOMString flashMode; | |
| 151 | |
| 152 /* one of the values chosen from capabilities.focusModes; | |
| 153 default is "auto", if supported, or "fixed" */ | |
| 154 [Throws] | |
| 155 attribute DOMString focusMode; | |
| 156 | |
| 157 /* one of the values chosen from capabilities.zoomRatios; other | |
| 158 values will be rounded to the nearest supported value; | |
| 159 default is 1.0 */ | |
| 160 [Throws] | |
| 161 attribute double zoom; | |
| 162 | |
| 163 /* an array of one or more objects that define where the | |
| 164 camera will perform light metering, each defining the properties: | |
| 165 { | |
| 166 top: -1000, | |
| 167 left: -1000, | |
| 168 bottom: 1000, | |
| 169 right: 1000, | |
| 170 weight: 1000 | |
| 171 } | |
| 172 | |
| 173 'top', 'left', 'bottom', and 'right' all range from -1000 at | |
| 174 the top-/leftmost of the sensor to 1000 at the bottom-/rightmost | |
| 175 of the sensor. | |
| 176 | |
| 177 objects missing one or more of these properties will be ignored; | |
| 178 if the array contains more than capabilities.maxMeteringAreas, | |
| 179 extra areas will be ignored. | |
| 180 | |
| 181 this attribute can be set to null to allow the camera to determine | |
| 182 where to perform light metering. */ | |
| 183 [Throws] | |
| 184 attribute any meteringAreas; | |
| 185 | |
| 186 /* an array of one or more objects that define where the camera will | |
| 187 perform auto-focusing, with the same definition as meteringAreas. | |
| 188 | |
| 189 if the array contains more than capabilities.maxFocusAreas, extra | |
| 190 areas will be ignored. | |
| 191 | |
| 192 this attribute can be set to null to allow the camera to determine | |
| 193 where to focus. */ | |
| 194 [Throws] | |
| 195 attribute any focusAreas; | |
| 196 | |
| 197 /* focal length in millimetres */ | |
| 198 [Throws] | |
| 199 readonly attribute double focalLength; | |
| 200 | |
| 201 /* the distances in metres to where the image subject appears to be | |
| 202 in focus. 'focusDistanceOptimum' is where the subject will appear | |
| 203 sharpest; the difference between 'focusDistanceFar' and | |
| 204 'focusDistanceNear' is the image's depth of field. | |
| 205 | |
| 206 'focusDistanceFar' may be infinity. */ | |
| 207 [Throws] | |
| 208 readonly attribute double focusDistanceNear; | |
| 209 [Throws] | |
| 210 readonly attribute double focusDistanceOptimum; | |
| 211 [Throws] | |
| 212 readonly attribute unrestricted double focusDistanceFar; | |
| 213 | |
| 214 /* 'compensation' is optional, and if missing, will | |
| 215 set the camera to use automatic exposure compensation. | |
| 216 | |
| 217 acceptable values must range from minExposureCompensation | |
| 218 to maxExposureCompensation in steps of stepExposureCompensation; | |
| 219 invalid values will be rounded to the nearest valid value. */ | |
| 220 [Throws] | |
| 221 void setExposureCompensation(optional double compensation); | |
| 222 [Throws] | |
| 223 readonly attribute unrestricted double exposureCompensation; | |
| 224 | |
| 225 /* one of the values chosen from capabilities.isoModes; default | |
| 226 value is "auto" if supported. */ | |
| 227 [Throws] | |
| 228 attribute DOMString isoMode; | |
| 229 | |
| 230 /* the function to call on the camera's shutter event, to trigger | |
| 231 a shutter sound and/or a visual shutter indicator. */ | |
| 232 attribute CameraShutterCallback? onShutter; | |
| 233 | |
| 234 /* the function to call when the camera hardware is closed | |
| 235 by the underlying framework, e.g. when another app makes a more | |
| 236 recent call to get the camera. */ | |
| 237 attribute CameraClosedCallback? onClosed; | |
| 238 | |
| 239 /* the function to call when the recorder changes state, either because | |
| 240 the recording process encountered an error, or because one of the | |
| 241 recording limits (see CameraStartRecordingOptions) was reached. */ | |
| 242 attribute CameraRecorderStateChange? onRecorderStateChange; | |
| 243 | |
| 244 /* the function to call when the viewfinder stops or starts, | |
| 245 useful for synchronizing other UI elements. */ | |
| 246 attribute CameraPreviewStateChange? onPreviewStateChange; | |
| 247 | |
| 248 /* the size of the picture to be returned by a call to takePicture(); | |
| 249 an object with 'height' and 'width' properties that corresponds to | |
| 250 one of the options returned by capabilities.pictureSizes. */ | |
| 251 [Throws] | |
| 252 attribute any pictureSize; | |
| 253 | |
| 254 /* the size of the thumbnail to be included in the picture returned | |
| 255 by a call to takePicture(), assuming the chosen fileFormat supports | |
| 256 one; an object with 'height' and 'width' properties that corresponds | |
| 257 to one of the options returned by capabilities.pictureSizes. | |
| 258 | |
| 259 this setting should be considered a hint: the implementation will | |
| 260 respect it when possible, and override it if necessary. */ | |
| 261 [Throws] | |
| 262 attribute any thumbnailSize; | |
| 263 | |
| 264 /* the angle, in degrees, that the image sensor is mounted relative | |
| 265 to the display; e.g. if 'sensorAngle' is 270 degrees (or -90 degrees), | |
| 266 then the preview stream needs to be rotated +90 degrees to have the | |
| 267 same orientation as the real world. */ | |
| 268 readonly attribute long sensorAngle; | |
| 269 | |
| 270 /* tell the camera to attempt to focus the image */ | |
| 271 [Throws] | |
| 272 void autoFocus(CameraAutoFocusCallback onSuccess, optional CameraErrorCallback onError); | |
| 273 | |
| 274 /* if continuous autofocus is supported and focusMode is set to enable it, | |
| 275 then this function is called whenever the camera decides to start and | |
| 276 stop moving the focus position; it can be used to update a UI element to | |
| 277 indicate that the camera is still trying to focus, or has finished. Some | |
| 278 platforms do not support this event, in which case the callback is never | |
| 279 invoked. */ | |
| 280 [Pref="camera.control.autofocus_moving_callback.enabled"] | |
| 281 attribute CameraAutoFocusMovingCallback? onAutoFocusMoving; | |
| 282 | |
| 283 /* capture an image and return it as a blob to the 'onSuccess' callback; | |
| 284 if the camera supports it, this may be invoked while the camera is | |
| 285 already recording video. | |
| 286 | |
| 287 invoking this function will stop the preview stream, which must be | |
| 288 manually restarted (e.g. by calling .play() on it). */ | |
| 289 [Throws] | |
| 290 void takePicture(CameraPictureOptions aOptions, | |
| 291 CameraTakePictureCallback onSuccess, | |
| 292 optional CameraErrorCallback onError); | |
| 293 | |
| 294 /* start recording video; 'aOptions' is a | |
| 295 CameraStartRecordingOptions object. */ | |
| 296 [Throws] | |
| 297 void startRecording(CameraStartRecordingOptions aOptions, | |
| 298 DeviceStorage storageArea, | |
| 299 DOMString filename, | |
| 300 CameraStartRecordingCallback onSuccess, | |
| 301 optional CameraErrorCallback onError); | |
| 302 | |
| 303 /* stop precording video. */ | |
| 304 [Throws] | |
| 305 void stopRecording(); | |
| 306 | |
| 307 /* call in or after the takePicture() onSuccess callback to | |
| 308 resume the camera preview stream. */ | |
| 309 [Throws] | |
| 310 void resumePreview(); | |
| 311 | |
| 312 /* release the camera so that other applications can use it; you should | |
| 313 probably call this whenever the camera is not longer in the foreground | |
| 314 (depending on your usage model). | |
| 315 | |
| 316 the callbacks are optional, unless you really need to know when | |
| 317 the hardware is ultimately released. | |
| 318 | |
| 319 once this is called, the camera control object is to be considered | |
| 320 defunct; a new instance will need to be created to access the camera. */ | |
| 321 [Throws] | |
| 322 void release(optional CameraReleaseCallback onSuccess, | |
| 323 optional CameraErrorCallback onError); | |
| 324 | |
| 325 /* changes the camera configuration on the fly; | |
| 326 'configuration' is of type CameraConfiguration. | |
| 327 | |
| 328 XXXmikeh the 'configuration' argument needs to be optional, else | |
| 329 the WebIDL compiler throws: "WebIDL.WebIDLError: error: Dictionary | |
| 330 argument or union argument containing a dictionary not followed by | |
| 331 a required argument must be optional" | |
| 332 */ | |
| 333 [Throws] | |
| 334 void setConfiguration(optional CameraConfiguration configuration, | |
| 335 optional CameraSetConfigurationCallback onSuccess, | |
| 336 optional CameraErrorCallback onError); | |
| 337 | |
| 338 /* if focusMode is set to either 'continuous-picture' or 'continuous-video', | |
| 339 then calling autoFocus() will trigger its onSuccess callback immediately | |
| 340 if the camera was either successfully focused, or if no focus could be | |
| 341 acquired; if the focus acquisition is still in progress, the onSuccess | |
| 342 callback will be invoked later, its argument indicating success or | |
| 343 failure. | |
| 344 | |
| 345 once autoFocus() is called with a continuous autofocus mode set, the | |
| 346 continuous autofocus process is stopped and focus is locked in the | |
| 347 current state until this method is called. | |
| 348 */ | |
| 349 [Throws] | |
| 350 void resumeContinuousFocus(); | |
| 351 }; | |
| 352 | |
| 353 /* The coordinates of a point, relative to the camera sensor, of the center of | |
| 354 detected facial features. As with CameraRegions: | |
| 355 { x: -1000, y: -1000 } is the top-left corner | |
| 356 { x: 1000, y: 1000 } is the bottom-right corner | |
| 357 x and y can range from -1000 to 1000. | |
| 358 */ | |
| 359 [Pref="camera.control.face_detection.enabled", Func="DOMCameraPoint::HasSupport"] | |
| 360 interface CameraPoint | |
| 361 { | |
| 362 attribute long x; | |
| 363 attribute long y; | |
| 364 }; | |
| 365 | |
| 366 /* The information of the each face detected by a camera device, e.g. | |
| 367 { | |
| 368 id: 1, | |
| 369 score: 80, | |
| 370 bound: { left: -203, | |
| 371 top: -400, | |
| 372 right: 300, | |
| 373 bottom: 250 }, | |
| 374 leftEye: { x: -100, | |
| 375 y: -200 }, | |
| 376 rightEye: { x: 100, | |
| 377 y: 100 }, | |
| 378 mouth: { x: 150, | |
| 379 y: 150 } } | |
| 380 | |
| 381 'id' is an unique value per face while the face is visible to the tracker. | |
| 382 If the face leaves the viewfinder and then returns, it will be assigned | |
| 383 a new value. | |
| 384 | |
| 385 'score' is the confidence level for the detection of the face. | |
| 386 This range is 1 to 100, where 100 is the highest confidence. | |
| 387 | |
| 388 'bounds' is the bounds of the face. It is guaranteed left < right and | |
| 389 top < bottom. The coordinates can be smaller than -1000 or bigger than 1000. | |
| 390 But at least one vertex will be within (-1000, -1000) and (1000, 1000). | |
| 391 | |
| 392 'leftEye' is the coordinates of the centre of the left eye. The coordinates | |
| 393 are in the same space as the ones for 'bounds'. This is an optional field | |
| 394 and may not be supported on all devices. If it is not supported or detected, | |
| 395 the value will be set to null. | |
| 396 | |
| 397 'rightEye' is the coordinates of the detected right eye; null if not | |
| 398 supported or detected. | |
| 399 | |
| 400 'mouth' is the coordinates of the detected mouth; null if not supported or | |
| 401 detected. | |
| 402 */ | |
| 403 [Pref="camera.control.face_detection.enabled", Func="DOMCameraDetectedFace::HasSupport"] | |
| 404 interface CameraDetectedFace | |
| 405 { | |
| 406 readonly attribute unsigned long id; | |
| 407 | |
| 408 readonly attribute unsigned long score; | |
| 409 | |
| 410 readonly attribute DOMRect bounds; | |
| 411 | |
| 412 readonly attribute boolean hasLeftEye; | |
| 413 readonly attribute CameraPoint? leftEye; | |
| 414 | |
| 415 readonly attribute boolean hasRightEye; | |
| 416 readonly attribute CameraPoint? rightEye; | |
| 417 | |
| 418 readonly attribute boolean hasMouth; | |
| 419 readonly attribute CameraPoint? mouth; | |
| 420 }; | |
| 421 | |
| 422 callback CameraFaceDetectionCallback = void (sequence<CameraDetectedFace> faces); | |
| 423 | |
| 424 partial interface CameraControl | |
| 425 { | |
| 426 /* Starts the face detection. This should be called after the preview is | |
| 427 started. The camera will periodically call 'onFacesDetected' with a | |
| 428 sequence of zero or one or more detected faces in the preview frame. | |
| 429 | |
| 430 How often the callback is invoked is implementation dependent. | |
| 431 | |
| 432 This method throws an exception if face detection fails to start. | |
| 433 */ | |
| 434 [Throws, Pref="camera.control.face_detection.enabled"] | |
| 435 void startFaceDetection(); | |
| 436 | |
| 437 /* Stops the face detection. | |
| 438 | |
| 439 This method throws an exception if face detection can't be stopped. | |
| 440 */ | |
| 441 [Throws, Pref="camera.control.face_detection.enabled"] | |
| 442 void stopFaceDetection(); | |
| 443 | |
| 444 /* Callback for faces detected in the preview frame. If no faces are | |
| 445 detected, the callback is invoked with an empty sequence. */ | |
| 446 [Pref="camera.control.face_detection.enabled"] | |
| 447 attribute CameraFaceDetectionCallback? onFacesDetected; | |
| 448 }; |
