Camera Library

The Camera library provides an application with a consistent interface to interact with one or more cameras connected to a device, as well as work with metadata stored with images and videos.

About the Camera service

To use the Camera service API, you must set one or more of the following permissions in the application descriptor (bar-descriptor.xml) file based on what you want to do:
  • use_camera: To access the camera for taking photos or videos

  • record_audio: To access the microphone when recording video. This permission is not required to take photos or video without audio

  • use_camera_desktop: To share the user's screen

Include the access_shared permission if you want to save images to the file system.

To grant an app the proper permissions, you must set each permission using the element in the application descriptor file. For example, use_camera. For more information on use_camera, record_audio, and use_camera_desktop, see App permissions.

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, autofocus, 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 or shooting a video — 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 that you comply with the laws and regulations for the countries in which you distribute your application. For more information, see the BlackBerry World Vetting Criteria at https://appworld.blackberry.com/isvportal/home.do.

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.

Whether you decide to use callback mode, event mode, or both, depends on the requirements of your application. Callback mode is simple to use and the code that it executes runs in its own thread. Callback allows you access to one buffer at a time. The access is read-only. Any memory allocated for the buffer is released when the callback completes its execution. Event mode allows you read/write access to the buffers and allows you to select your own threading model. Event mode permits you access to more than one buffer at a time because you can manage when the buffer is released. Event mode requires that you write your own event loop.

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_buffers() function processes the data appropriately, and then releases the buffer back to the camera service using camera_return_buffer() function.

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 an image or viewfinder event, your application can retrieve the buffer associated with this event by calling the corresponding get function:

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. You should use caution if your application needs to process frames within a set interval. If concurrent events occur in your application where the time to process one event could interfere with the deadline to complete processing another event, then you should consider handling the events in separate threads. For example, you might implement an algorithm to detect smiles in the viewfinder frames, but concurrently, the user may want to capture a still image to disk. Since it's possible to take more time to save this image to disk than the inter-frame period of the viewfinder frames, it's best to process the image-saving task in a different thread than the viewfinder-processing task. You can also use callback mode to resolve this problem because callbacks inherently execute in separate threads.

About callback mode

Callbacks are one mechanism of asynchronously accessing camera image data as well as status information. You provide custom code to be executed as a callback when performing camera operations such as taking a picture or encoding video. Using 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 to save 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 deregistered when the operation started by one of the above functions completes. For example, when the camera_stop_photo_viewfinder() function is invoked, any callbacks registered during the camera_start_photo_viewfinder() function call are deregistered.

These are the callback signatures for various 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 guaranteed to be valid only 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 activates 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 that you comply with the laws and regulations for the countries in which you distribute your application. For more information, see the BlackBerry World Vetting Criteria at https://appworld.blackberry.com/isvportal/home.do. 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 disk space 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_devstatus_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 that 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.

  • enc_video_callback: The callback is invoked when an encoded 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 encoded frame. This data is only guaranteed to be valid while your callback function is executing.

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

  • enc_audio_callback: The callback is invoked when an encoded audio 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 encoded frame. This data is only guaranteed to be valid while your callback function is executing.

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

Manual camera settings

You can configure various manual settings (i.e., ISO, shutter speed, white balance, and aperture) after you start the viewfinder on the camera. Changes in settings may not be visible for several frames due to latency in the image processing pipeline.

For example, when you use an exposure mode (camera_exposuremode_t) that has a manual component such as CAMERA_EXPOSUREMODE_ISO_PRIORITY and you change the ISO setting (camera_set_manual_iso()), you may not see the results of the ISO change until several frames later.

Last modified: 2014-01-16

comments powered by Disqus