Camera Library

The Camera library provides an application a consistent interface to interact with one or more cameras connected to a device.

Applications access buffers by binding callback functions or events to a particular stage of the imaging datapath. Depending on the camera hardware capabilities, you control the camera in the following manner:

  • Connect and disconnect from a camera
  • Start and stop the photo viewfinder and video viewfinder
  • Use features on the camera, such as scene modes, change zoom, auto-focus, auto-white-balance, and auto-exposure
  • Take pictures individually or in burst mode
  • Encode video and save recordings to file
  • Modify focus and access focus regions
  • Turn flash and video-lights on and off
The Camera library does not automatically play audible shutter sounds when a picture is taken or a video is recorded. Camera applications must supply their own sound when a photo is captured or a video recording begins and ends. While you can choose to not have a shutter sound when taking a picture — you are responsible to ensure that the application adheres to the local laws of the regions in which you wish to distribute the application. For example, it is illegal to mute or modify the shutter sound of a camera application in Japan and Korea. Ensure you comply with the laws and regulations for the countries in which you distribute your application.

Camera Image Buffer Access

The camera service provides read access to image data from different stages in the imaging datapath (image buffers). Applications access buffers by binding callback functions or events to a particular stage of the imaging datapath.

The camera API is widely adaptable to the specific design patterns of your application due to the option of using either threaded callbacks (callback-mode) or events received in an event-loop (event-mode). Using events does not preclude you from also using callbacks. The two are interoperable and the camera API internally implements callback threads using events.

About event-mode

Camera events are used asynchronously to notify an application when the camera service has some data or status information available that can be acted upon. For example, a status event may indicate that a change in focus has occurred, that the shutter has fired, or that a video recording has run out of disk-space.

Status events do not have buffers associated with them, but instead carry just enough data to convey the necessary status information. In comparison, an imaging event signals to the application that a data buffer has become available and can be retrieved and processed. An example of an imaging event would be a viewfinder buffer or a still image buffer becoming available.

When an imaging event is received, the application can then safely call one of the get-buffer functions. For example, the camera_get_viewfinder_buffer() function processes the data appropriately, and then releases the buffer back to the camera service using camera_return_buffer() function.

To bind an event to a given point in the camera datapath, use one of the following functions:

Multiple events can be bound to the same point in the datapath, but this may be less efficient than dispatching multiple tasks after receiving a single event in your application.

To unbind an event from a given point in the camera datapath, use the camera_disable_event() function.

When a non-status event occurs, such as a shutter or status event, your application can retrieve the buffer associated with this event by calling the corresponding get function:

  • camera_get_image_buffer()

  • camera_get_postview_buffer()

  • camera_get_raw_buffer()

  • camera_get_video_buffer()

  • camera_get_video_buffer()

  • camera_get_viewfinder_buffer()

When your application is finished processing the buffer, (e.g. when you save the image buffer to disk) the buffer must be returned to the camera service using the camera_return_buffer() function. No additional buffers are made available to your application until you return the previously acquired buffer. Since some events happen more frequently than others (e.g. saving the image buffer to disk) it may be necessary to dispatch tasks using separate threads to keep your event loop suitably serviced.

For example, if you are using an algorithm to detect a smile, the algorithm searches through multiple viewfinder frames until a still-image is acquired. Since it may take more time to save this image to disk than the inter-frame period of the viewfinder frames. In this case, it would make more sense to process the image-saving task on a different thread than the viewfinder- processing task. This problem is also resolved by using the available callback threads.

About callback-mode

Callbacks are one mechanism of asynchronously accessing camera image data as well as status information. Callbacks are provided to execute custom code when performing camera operations such as taking a picture or encoding video. Callbacks provide you a great amount of flexibility to control what occurs in your application when a function executes. For example, you can use callbacks to perform image processing or saving of data to disk. Callback functions execute in a separate thread, so you need to be sure that your code is thread-safe through the use of appropriate thread synchronization primitives (mutexes, semaphores, condvars, etc.)

Unlike events, which can be explicitly bound to a specific location in the image datapath, callbacks are implicitly registered only when invoking the following functions:

Callbacks are de-registered when the operation started by one of the above functions completes. For example, when the camera_stop_viewfinder() function is invoked, any callbacks registered during the camera_start_photo_viewfinder() function call are deregistered.

The following callback signatures for Camera library functions:

image_callback: The callback is invoked when the final image data becomes available. You can choose to save the image to disk or perform other post-processing algorithms on the image. The callback has the following signature:

   void function_name( camera_handle_t,
                       camera_buffer_t*,
                       void*)
  • camera_handle_t: The handle of the camera invoking the callback.

  • camera_buffer_t*: A pointer to a camera_buffer_t structure which describes the image data. This data is only guaranteed to be valid while your callback function is executing.

  • void*: The user-specified argument in the arg argument.

postview_callback: The callback is invoked when the postview image data is available. The image data provided is a preview-sized version of the captured still image. For example, you could display the preview-size image instead of down-scaling and decompressing the final image. The callback has the following signature:

   void function_name( camera_handle_t,
                       camera_buffer_t*,
                       void*)
  • camera_handle_t: The handle of the camera invoking the callback.

  • camera_buffer_t*: A pointer to a camera_buffer_t structure which describes the postview frame. This data is only guaranteed to be valid while your callback function is executing.

  • void*: The user-specified argument in the arg argument.

raw_callback: This callback is reserved for future use. Do not use.

shutter_callback: The callback is invoked when the shutter fires on the camera. It's your responsibility to play audible shutter sounds when a picture is taken or a video is recorded. While you can choose to not have a shutter sound when taking a picture — you are responsible to ensure that the application adheres to the local laws of the regions in which you wish to distribute the application. For example, it is illegal to mute or modify the shutter sound of a camera application in Japan and Korea. Ensure you comply with the laws and regulations for the countries in which you distribute your application. If you use burst mode to capture images in rapid succession, choose an appropriate moment to play the shutter sound rather than play the shutter sound repeatedly.

The callback has the following signature:

   void function_name( camera_handle_t,
                       void*)
  • camera_handle_t: The handle of the camera invoking the callback.

  • void*: The user-specified argument in the arg argument.

status_callback:The callback is invoked when additional data relevant to the state of the camera is being reported. For example, the time remaining on disk for a diskspace warning event. The callback has the following signature:

   void function_name( camera_handle_t,
                       camera_devstatus_t,
                       uint16_t,
                       void*)
  • camera_handle_t: The handle of the camera invoking the callback.

  • camera_dev_status_t: The status event that occurred.

  • uint16_t: Any extra data associated with the status event that occurred.

  • void*: The user-specified argument in the arg argument. The function is a callback that gets invoked when status events occur.

video_callback: The callback is invoked when an uncompressed video frame becomes available. The callback has the following signature:

   void function_name( camera_handle_t,
                       camera_buffer_t*,
                       void*)
  • camera_handle_t: The handle of the camera invoking the callback.

  • camera_buffer_t*: A pointer to a camera_buffer_t structure which describes the video frame. This data is only guaranteed to be valid while your callback function is executing.

  • void*: The user-specified argument in the arg argument.

On platforms which advertise the CAMERA_FEATURE_PREVIEWISVIDEO feature, video frames are not explicitly available. Instead, use the frames returned by the viewfinder_callback.

viewfinder_callback: The callback is invoked when a viewfinder buffer becomes available. The viewfinder is rendered to a screen window by the camera service. You are not required to add display code, unless you need to perform custom output using some other mechanism. The callback has the following signature:

   void function_name( camera_handle_t,
                       camera_buffer_t*,
                       void*)
  • camera_handle_t: The handle of the camera invoking the callback.

  • camera_buffer_t*: A pointer to a camera_buffer_t structure which describes the viewfinder frame. This data is only guaranteed to be valid while your callback function is executing.

  • void*: The user-specified argument in the arg argument.