Contents

1 Introduction

The Camera API allows a developer to take a picture, capture video, or preview the camera's viewfinder. A developer can optionally specify specify where the captured media should be saved.

2 Features String

An camera feature declaration in a widget's configuration document represent a developer's intention to use the functionality provided by this API.

The feature string for the camera API is: http://wacapps.net/api/camera

The camera feature string needs to be present in a widget's configuration document in order for the API to be made available at runtime.

2.1 Processing the feature declaration 

A user agent needs to process feature elements in accordance with the W3C's Widgets Packaging and Configuration specification.

CAMERA-process-feature: If the  feature-list  contains any features whose feature-name exactly matches the camera feature string, then the user agent MUST apply the steps for processing a camera feature declaration.

Steps for processing a camera feature declaration

The steps for processing a camera feature declaration is given by the following algorithm:

1. Implement the DeviceapisCamera interface when the widget's start file is instantiated.

2. Implement the  CameraManager and Camera interfaces in a manner that conforms to WebIDL.

XML Example

<widget xmlns="http://www.w3.org/ns/widgets">
  <feature name="http://wacapps.net/api/camera"/>
</widget>

3 DeviceapisCamera Interface

[NoInterfaceObject]
interface DeviceapisCamera {
    readonly attribute CameraManager camera;
};
Deviceapis implements DeviceapisCamera;

3.1 The camera attribute

The camera attribute is the point of access to the Camera API (see CameraManager interface).

4 CameraManager Interface

interface CameraManager {
    void getCameras (CameraCB successCallback,
            optional Function? errorCallback);
};
callback CamerasCB = void(Camera[] cameras);   

4.1 The getCameras() method

The getCameras() method is used to asynchronously retrieve the cameras of the device that can be used by the widget; this excludes any cameras that cannot be used by the widget, but may be present on the device.

When the getCameras() method is invoked, the user agent must run the steps to get the cameras.  If an error occurs during steps to get the cameras, the user agent MUST run the steps to handle an error.

The steps to get the cameras

The steps to get the cameras are given by the following algorithm:

1. Run the general invocation checks algorithm. If no exceptions were generated, continue asynchronously.

2. Let camera list be an empty array.

3. If the device contains a main back camera, and it can be used by the widget, then create a new object that implements the Camera interface, and set its id to "back". Append the camera object to the camera list.

4. If the device contains a main front camera, and it can be used by the widget, then create a new object that implements the Camera interface, and set its id attribute to "front".

5. If the device contains any other cameras, and any of them can be used by the widget, then create a new object that implements the Camera interface that represents each of the cameras and append them to the camera list. For each of these cameras, it is recommended that the id attribute be set to something that the developer will understand (e.g., "back_2" for back camera )

6. Queue a task to invoke the successCallback with camera list as the argument.

HTML Example

function onCreatePreviewNodeSuccess(previewObject) {
	var previewDiv = document.getElementById("preview");
	previewId = previewObject.id;
	previewDiv.appendChild(previewObject);
	previewObject.style.visibility = "visible";
}

function success(cams) {
	if (cams.length > 0) {
		mainCamera = cams[0];
		mainCamera.createPreviewNode(onCreatePreviewNodeSuccess, error);
		return;
	}
	alert("Sorry, no cameras available.");
};
deviceapis.camera.getCameras(success, error);

5 Camera Interface

The Camera interface allows a application to capture media from a camera of the device and provides a means to display the camera viewfinder.

interface Camera{
    readonly attribute DOMString id;

    void captureImage(Function successCallback,
                      optional ErrorCB? errorCallback,
                      optional CameraOptions options);

    void startVideoCapture(Function successCallback,
                           optional ErrorCB? errorCallback,
                           optional CameraOptions options);

    void stopVideoCapture();

    void createPreviewNode(Function successCallback,
                           optional ErrorCB? errorCallback);
};

5.1 The id attribute

The id attribute uniquely identifies a camera on the device.

5.2 The captureImage() method

The captureImage() method asynchronously attempts to capture a still image and save it to the device.

When the captureImage() method is invoked, the user agent MUST run the steps to capture an image.

Steps to capture an image

The steps to capture an image are given by the following algorithm:

1. Run the general invocation checks algorithm. If no exceptions were generated, continue asynchronously.
2. Let path be null.
3. Let data be the data resulting from capturing an image from the camera that is associated with the object that invoked this algorithm.
4. If the options argument is passed, it contains the destinationFilename attribute:
   1. If the value of the destinationFilename attribute is null, terminate these sub-steps and continue.
   2. Let potential-path be the result of calling toString on the destinationFilename attribute.
   3. If potential-path is not a DOMString, or its an empty DOMString, terminate these sub-steps and continue.
   4. Let resolved-path be the result of resolving the potential path.
5. Attempt to save the data to the device at either path (if not null) or at runtime-specific location that is also accessible to the application. If saving fails for whatever reason and errorCallback argument was used:
1. Let error be a new DOMException.
2. Queue a task to invoke errorCallback with error as the argument.
3. Terminate this algorithm ignoring all substeps below.
1. If the file was succesfully saved to disk, let path be a virtual path to the location of the file.
6. Queue a task to invoke successCallback with path as the argument.

JavaScript Example

function onCaptureImageSuccess(filename) {
	deviceapis.filesystem.resolve(
	function(file) {
		var imgHeader = document.createElement("P");
		imgHeader.innerHTML = 'Image saved to: ' + file.fullPath;
		document.getElementById('cameraBody').appendChild(imgHeader);
		var img = document.createElement('img');
		img.src = file.toURI() + "?" + new Date().getTime();
		document.getElementById('cameraBody').appendChild(img);
	},
	null,
	filename, "rw");
}

try {
	mainCamera.captureImage(
	onCaptureImageSuccess, error, {
		destinationFilename: "images/cam01.jpg",
		highRes: false
	});
} catch(exp) {
	alert("Exception :[" + exp.code + "] " + exp.message);
}

5.3 The startVideoCapture() method

When invoked, and if not disabled, the startVideoCapture() method requests that the device attempt to capturing video.

If the video capture starts successfully, it continues until either stopVideoCapture() is explicitly called or when capture is stopped automatically because of some platform limitation (e.g. maximum video size or video capture duration is reached).

Once capture is stopped, and the media is available in a specific location in the file system, the successCallback is invoked.

If the options argument contains invalid values or null, the implementation MUST ignore that argument.

If the errorCallback does not contain a valid function (e.g. null), in case of any error that should be returned in the errorCallback (see above), the implementation MUST silently fail and no further action is required (i.e. the error is not notified to the developer).

Javascript Example

function success(filename) {
	alert("Captured video path:" + filename);
}

function fail(e) {
	alert("Capture video failed with error:" + e.message);
}

var options = {
	destinationFilename: "videos/a.3gp"
};

mainCamera.startVideoCapture(success, fail, options);

5.4 The stopVideoCapture() method

The stopVideoCapture() method is used to stop capturing video. If no video capture is active when this API is called, invoking ths method does nothing.

When this method is called, the capture is stopped, the video is created and saved, and the successCallback registered for startVideoCapture() is invoked. In case of any error in this process, the user agent MUST invoke the function that represents the errorCall back that was passed to the startVideoCapture().

Javascript Example

//to be invoked when the user decides to stop the video recording
function stopCapture() {
	mainCamera.stopVideoCapture();
}

5.5 The createPreviewNode() method

The createPreviewNode() creates a WRT-specific HTMLUnknownElement, which can be used for displaying the camera preview window. The newly-created DOM node can then be appended to a container element (e.g. <div>) in the Document. This supplies a position and dimension for the preview. The preview begins as soon as the newly-created DOM object becomes 'visible' in the DOM, and stops when the newly-created DOM object becomes invisible, is detached from the DOM tree or is partially or completely scrolled out of the display viewport.

The element corresponding to the newly-created DOM object MUST respect the CSS 'z-index' attribute (e.g. a textual overlay on top of video displaying the description of the video).

6 CameraOptions dictionary

The CameraOptions dictionary allows a developer to specify some options to control how camera operations are performed.

dictionary CameraOptions {
    DOMString? destinationFilename;
    Boolean?   highRes;
};

6.1 The destinationFilename member

The destinationFilename member represents a virtual path where the caputed media is to be stored.

6.2 The highRes member

The hightRes member serves as an indicator the the WRT as to take the picture in "high resolution" or not. What high resolution means is left to implemetations.

Change Log

This specification was last updated on 30 April 2012.

A complete list of changes are kept on our GIT repository.