How to use the Camera API

This page describes how clients can use the Camera API to access the camera on a phone. This includes configuring the camera, and capturing images and video.

Note that the functionality that can be obtained through the API is dependent on what is available in the camera hardware. The API includes functions that you should call to check if functionality is available before using it.

The sections are:

• Accessing the camera

• Power control

• Using a view finder

• Basic camera image settings

• Capturing a still image

• Capturing video

To access the camera, use CCamera::NewL() to create the object, and then reserve the camera for your use using CCamera::Reserve().

A client must implement a callback interface so that the camera can notify it when events occur, such as when an image has been captured or a buffer of video data is ready. The recommended callback interface to implement is MCameraObserver2. There is also an older callback interface, MCameraObserver, which is still supported, but which new clients do not need to use.

A client may not always be able to gain control of the camera, as, if more than one client is requesting control, then a priority calculation is used to determine which client should have it. Higher priority clients will take ownership from lower priority clients when they contend for use of the camera.

There are two parts that make up a client's priority value:

• Clients may declare themselves to have a priority from -100 to 100. The default priority is zero.

• Clients with system capability MultimediaDD will take priority ahead of clients without that capability, regardless of the declared priority values.

A camera implementation may use additional prioritisation decisions, such as prioritising a particular process ID. However this API does not assume any camera policy for this, as this is implementation specific.

The CCamera::Reserve() call will be unsuccessful if a higher priority client is already using the camera: the MCameraObserver2::HandleEvent() call back will return an error.

If a client is superseded by another, it will receive a MCameraObserver2::HandleEvent() notification that the camera is no longer available. It should expect no further call backs for outstanding capture requests or notifications for pending custom extended operations (histograms, snapshots, etc.) and further attempts to use the camera without a successful CCamera::Reserve() call will fail.

Secondary clients

Multiple clients may share the camera if the secondary clients create their camera objects using the CCamera::NewDuplicateL() factory function. This can only be called with the handle of an existing camera object, read using CCamera::Handle(), and lets more than one client make CCamera::Reserve() calls at once. This is to allow, for example, a video conferencing application to have a camera object open for control of its functions, but also for the multimedia system to have a camera object open for reading frames of data.

The secondary client (using the CCamera::NewDuplicateL() call) assumes the priority of the primary client (which generated the camera handle using CCamera::NewL()). Each client calls CCamera::Reserve(), and must call CCamera::Release() once they no longer wish to use camera functionality. Even if the primary client finishes, a secondary client retains camera control until it calls CCamera::Release(). If a higher priority client gains control, all the clients will receive individual MCameraObserver2::HandleEvent() notifications.

Once a camera object is available, the client application needs to switch on the camera power, using CCamera::PowerOn(). The callback interface is notified when power on is complete.

Once the camera is powered-on, the client will probably need to transfer view finder data to the screen.

You can specify the portion of the screen to which view finder data is to be transferred. This is in screen co-ordinates, and may be modified if, for example, the camera requires the destination to have a certain byte alignment. The size of image returned by the view finder may not be the exact size requested if this conflicts with the requirement for the view finder to show the unclipped view in the ratio required for image capture or video capture. The camera will return the best match.

The view finder can, if the camera implementation supports it, transfer frames from the camera directly to the display memory at a location of the client's choosing. Alternatively, if supported, the user may implement a view finder function themselves, in which case the client is passed the view image as a bitmap.

A client calls the following functions to control the view finder:

• CCamera::StartViewFinderDirectL() to display view finder data to a specified portion of the screen using direct screen access.

• CCamera::StartViewFinderBitmapsL() to get view finder data as a bitmap.

• CCamera::SetViewFinderMirrorL() to specify view finder mirroring on or off. Mirroring flips the image horizontally, so that the user can use the device as a virtual mirror.

• CCamera::StopViewFinder() to stop transfer of view finder data to the screen.

CCamera provides functions that allow you to alter the brightness, contrast, and zoom level of the camera image. Before using such functions though, you should test that the camera supports what you want. To do this, get a TCameraInfo object using the CameraInfo() function. The object's iOptionsSupported member is a bitfield of flags that describe which options are supported by the camera.

To change the camera image brightness:

1. Check if brightness control is supported, by testing if the TCameraInfo::EBrightnessSupported flag is set in the options.

2. Set the brightness using CCamera::SetBrightnessL().

   The brightness should be in the range -100 to +100, or to set the brightness automatically, use the flag CCamera::EBrightnessAuto.

To change the camera image contrast:

1. Check if contrast control is supported, by testing if the TCameraInfo::EContrastSupported flag is set in the options.

2. Set the contrast using CCamera::SetContrastL().

   The contrast should be in the range -100 to +100, or to set the contrast automatically, use the flag CCamera::EContrastAuto.

To alter the camera zoom:

1. Test if zoom is supported, and for what range of values, by reading the minimum and maximum zoom values from the data members in TCameraInfo. A value of zero means zoom is not supported. A step of one in the zoom value corresponds to the smallest zoom change available. The camera zoom increases linearly with the zoom value until the maximum zoom value.

   A separate set of values is available for zoom and for digital zoom. TCameraInfo also has members that say what is the actual zoom factor when at minimum (non-digital only) and maximum zoom.

2. Set the zoom using CCamera::SetDigitalZoomFactorL() or CCamera::SetZoomFactorL().

Before a client application captures still, or video, images it can first specify the required image format. There may be complicated dependencies between frame sizes and formats, so the required format must be specified as follows:

1. Select the format from those available from either the TCameraInfo::iImageFormatsSupported or the TCameraInfo::iVideoFrameFormatsSupported bitfield, for still or video images respectively.

2. Select the required size using either CCamera::EnumerateCaptureSizes() or CCamera::EnumerateVideoFrameSizes() for still or video images respectively. Note that not all possible sizes are guaranteed to be supported for any given format. Unsupported sizes will be returned as (0,0).

3. For video capture, select the frame rate using CCamera::EnumerateVideoFrameRates(). Again, not all rates are guaranteed to be supported, as dependencies may exist in the camera between the format, size, exposure mode and rate.

Image capture involves transferring the current image from the camera to the client.

1. Client applications can specify the image format, size, and optionally a clipping rectangle. These settings are made using CCamera::PrepareImageCaptureL(), which must be called at least once before requesting images, to allow the camera device to allocate the necessary resources.

   Note that:

   • Image settings should be used only for capturing images and for video capture the camera should be prepared separately

   • It is valid to prepare the camera for image capture and for video capture in any order preceding the image capture. Each successive image capture requires a separate call.

   • Image capture cannot take place while video capture is active.

2. Call CCamera::CaptureImage() to start image capture.

   The camera calls back the client's MCameraObserver2::ImageBufferReady() function when image capture is complete. The client can then read the image from the MCameraBuffer object passed to that function.

   Note that the view finder is not automatically stopped when an image is captured. It is the responsibility of the client to stop the view finder and display the captured image.

Video capture involves transferring the image frames from the camera to the client.

1. Video capture is initialised by CCamera::PrepareVideoCaptureL() which must be called before video is captured. As well as format, size, and rate (Image format), you set the number of buffers to use and the number of frames per buffer.

   Note that:

   • If video is not supported, then the function leaves with the error KErrNotSupported.

   • Video settings should be used for capturing video only; for image capture, the camera should be prepared separately.

   • Video capture cannot take place while there is an outstanding still image capture active.

2. Call CCamera::StartVideoCapture() to start video capture.

   The camera then fills the buffers as frames become available. Once a buffer has been filled, it is passed to the client through a callback to MCameraObserver2::VideoBufferReady(), which passes the buffer in an MCameraBuffer object.

   Note that:

   • If an error occurs with video capture, then the client is notified by MCameraObserver2::VideoBufferReady() passing an error, in which case no valid frame data is included.

     If the error is fatal to the process of capturing video, such as the camera being switched off, then video capture stops and outstanding buffers will be deleted by the camera object.

   • If the camera runs out of frame buffers, then there will be no call backs until the client calls MCameraBuffer::Release(), after which MCameraObserver2::VideoBufferReady() will start being called again.

   • You can use multiple sequences of CCamera::StartVideoCapture()/StopVideoCapture() calls following a single call to CCamera::PrepareVideoCaptureL().

3. In the callback, the client needs to extract the data from the MCameraBuffer object, either as a descriptor, a bitmap or a handle to a kernel chunk. In all three cases the camera retains ownership of the data. Once the data has been used, the buffer should be released by calling its Release() function, which indicates that the camera may reuse or delete it.

   The buffer format available depend on the format selected. Either the image data will be available as a bitmap (owned by the Font and Bitmap server) or it will be available as a descriptor and chunk (the descriptor refers to the memory in the chunk). An attempt to access an inappropriate format will cause the function to leave.

   For the purpose of synchronisation, a buffer provides the index of the starting frame in the buffer and the elapsed time (timestamp) since the video capture started. It is assumed that the frames within the buffer have been captured sequentially at the requested frame rate. Their individual timestamps can be calculated as a function of their index, capture rate and first frame time latency. In cases where considerable jitter is expected or observed, it may be better to have a single frame in a buffer.