Camera Library

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

About the Camera API

To use the Camera 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 camera roll directory on 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" in the "Developing with the Native SDK" guide.

Using the Camera library, you can perform operations such as:
  • Connect and disconnect from a camera.

  • Start and stop the viewfinder.

  • Use features on the camera, such as scene modes, zoom, autofocus, auto white balance, and auto exposure.

  • Adjust focus, exposure, and white balance algorithms by defining regions of interest, or applying manual controls.

  • Take pictures individually or in burst mode.

  • Encode video and save recordings to file.

  • 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 operating system 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. Callbacks give you access to one buffer at a time. The access is readonly. 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 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, your application should perform the following actions:
  1. Call the corresponding get-buffer function (camera_get_viewfinder_buffers(), for example).

  2. Process the image data appropriately.

  3. Release the buffer back to the camera using the 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:

After your application is finished processing the buffer, (e.g., you have saved the image to disk) the buffer must be returned to the camera 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 from the viewfinder-processing task. You can also use callback mode to resolve this problem because callbacks inherently execute in separate threads.

It is important that your application follows the guidelines for resource management outlined in Camera resource management. If you do not observe these guidelines, your application is at risk of crashing due to memory access errors when resource arbitration is performed by the operating system.

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_viewfinder() function is invoked, any callbacks registered during the camera_start_viewfinder() function call are deregistered.

These are the callback signatures for various Camera library functions:

  • image_callback: This callback is invoked when the final image data becomes available. This is typically a full-resolution photograph. 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 arg argument.

  • postview_callback: This 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-sized image instead of decompressing and down-sampling 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 arg argument.

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

  • shutter_callback: This 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 arg argument.

  • status_callback: This callback is invoked when non-image data relevant to the state of the camera is being reported. For example, a change in autofocus state, or a disk space warning. 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 arg argument.

  • video_callback: This 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 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: This callback is invoked when a viewfinder buffer becomes available. The viewfinder is rendered to a screen window by the operating system. 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 arg argument.

  • enc_video_callback: This 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 arg argument.

  • enc_audio_callback: This 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.

It is important that your application follows the guidelines for resource management outlined in Camera resource management. If you do not observe these guidelines, your application is at risk of crashing due to memory access errors when resource arbitration is performed by the operating system.

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.

Not all cameras may support all manual settings. You should call the camera_get_exposure_modes() to determine which manual exposure settings can be adjusted.

Viewfinder modes

Viewfinder modes are only supported in CAMERA_API_VERSION 3 (BlackBerry 10.3.0) and higher. Use the camera_get_api_version() function to determine the API version of the device your application is running on.

A viewfinder mode is used to specify the major operating mode of the camera. For more information about the defined viewfinder modes, see camera_vfmode_t. Using viewfinder modes enables the operating system to optimize configuration of the camera hardware to provide the best user experience and image quality. Using viewfinder modes also allows for easier discovery of camera capabilities and available modes and settings. For example, by selecting the CAMERA_VFMODE_FIXED_BURST, you are indicating that your application needs to capture photos in rapid succession. Once you have selected a viewfinder mode, all of the other capability query functions (e.g., camera_get_supported_vf_resolutions(), camera_get_scene_modes(), camera_has_feature(), etc.) will properly return lists which are guaranteed to work with your intended use case.

You must select a viewfinder mode prior to configuring and starting the viewfinder. Use the camera_set_vf_mode() function to select the appropriate mode for your specific use case. After selecting a mode, you can modify the viewfinder settings using the camera_set_vf_property() function. Start the viewfinder using the camera_start_viewfinder() function. When finished using the camera, stop the viewfinder using the camera_stop_viewfinder() function. You may only switch between viewfinder modes when the viewfinder is not running.

Releases of the Camera library prior CAMERA_API_VERSION 3 (BlackBerry 10.3.0) do not support viewfinder modes. Instead, the viewfinder functions were divided into photovf and videovf variants (e.g., camera_set_photovf_property()). This usage pattern is now, deprecated, however, for backwards compatibility purposes, it is still possible to operate the camera using these deprecated functions. When using the deprecated functions, the viewfinder mode is equivalent to CAMERA_VFMODE_DEFAULT. Once you change the viewfinder mode using the camera_set_vf_mode() function, you can no longer use the deprecated functions until you close and re-open the camera. If your application does not need to use more advanced viewfinder modes, then you can continue using the legacy photovf and videovf functions for backwards compatibility.

Certain advanced functionality is only available using viewfinder modes, so if your application requires any of this new functionality, you must use viewfinder modes in your application. Your application will not run on devices that are running BlackBerry 10.2.1 or older. The viewfinder modes listed in camera_vfmode_t have notes which indicate whether the functionality can be accessed on older software versions using alternate configuration means.

Camera resource management

System resources are limited in a mobile device environment. Since users may run multiple applications concurrently in a multitasking environment, it is not always possible to satisfy all of the resourcing needs of all applications simultaneously. For this reason, system resources may be revoked from a running application when they are needed elsewhere.

At any point in time, it is possible that the resources used by the camera are required by a higher priority application. When this situation occurs, the viewfinder is stopped by the operating system and your application will receive a CAMERA_STATUS_POWERDOWN status event. If buffers are still in use by your application when the viewfinder is stopped, this can cause your application to crash if it is accessing buffer memory when it is unmapped.

Your application can call the camera_register_resource() function to request that the operating system defer the unmapping of buffer memory temporarily.

Whenever resources are needed elsewhere by higher priority applications, or when the camera is about to be powered off for any reason, your application will now receive a CAMERA_STATUS_RESOURCENOTAVAIL status event. When your application receives this status event, you must immediately cease processing all camera buffers and then call the camera_deregister_resource() function to let the operating system know that it can proceed to unmap allocated buffer memory. A timeout is in place that limits the amount of time your application has before resources will be forcefully revoked. For this reason, it is important that your application respond as soon as possible after receiving the #CAMERA_STATUS_RESOURCENOTAVAILABLE status event.

Please see camera_register_resource() and camera_deregister_resource() for further information.

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus