camera_take_burst()

Take a fixed number of photos in rapid succession.

Synopsis:

#include <camera/camera_api.h>

camera_error_t camera_take_burst(camera_handle_t handle,                 
                                 int burst_count,                 
                                 void(*shutter_callback)(camera_handle_t, void *),                 
                                 void(*raw_callback)(camera_handle_t, camera_buffer_t *, void *),                 
                                 void(*postview_callback)(camera_handle_t, camera_buffer_t *, void *),                 
                                 void(*image_callback)(camera_handle_t, camera_buffer_t *, void *),                 
                                 void *arg,                 
                                 bool wait)

Since:

BlackBerry 10.0.0

Arguments:

handle: The handle returned by a call to the camera_open() function.

burst_count: The number of photos to capture in a single burst.

shutter_callback

A function pointer to a function with the following signature:

 void function_name( camera_handle_t,
                     void* );

The function is a callback that is invoked when the shutter activates. Typically, the callback function plays a shutter sound. You can use NULL if no function needs to be called. For information about the callback arguments, see About callback mode.

raw_callback: Use NULL. Reserved for future use.

postview_callback

A function pointer to a function with the following signature:

 void function_name( camera_handle_t,
                     camera_buffer_t*,
                     void* );

The function is a callback that is invoked when a postview (review) image is available. This callback is used to provide a preview-sized copy of the photo. Typically, the preview-sized photo is used to provide visual feedback before the final image is available. You can use NULL if no function needs to be called. For information about the callback arguments, see About callback mode.

image_callback

A function pointer to a function with the following signature:

 void function_name( camera_handle_t,
                     camera_buffer_t*,
                     void* );

The function is a callback that is invoked when a full-resolution image is available. You can use NULL if no function needs to be called. For information about the callback arguments, see About callback mode.

arg: The argument passed to all callback functions, which is the last argument in the callback functions.

wait: A boolean value that indicates whether the function blocks or not. If set to true, this function is blocking and will return once all specified callbacks have returned. If set to false, this function call is non-blocking and returns before all specified callbacks have returned.

Library:

libcamapi (For the qcc command, use the -l camapi option to link against this library)

Description:

Before you take photos, ensure that you have configured the viewfinder, set the output properties for the photo, and started the viewfinder. This function can only be called if the CAMERA_FEATURE_BURST feature is available. You can determine whether this feature is available by calling the camera_can_feature() function.

The viewfinder must be started in CAMERA_VFMODE_FIXED_BURST mode or CAMERA_VFMODE_EV_BRACKETING mode. Burst capture is also possible using the deprecated photo viewfinder with CAMERA_IMGPROP_BURSTMODE set to 1. For more information about viewfinder modes, see Viewfinder modes.

If you want an application to save the photos to a file, then this function should be invoked with the image_callback argument set. When the image_callback is set, the image buffer is provided as the second argument to the callback function. When your image_callback function is invoked, you can save the buffer to a file.

Note: While in burst mode, you should not save files in the callback for performance reasons. Instead, you should buffer the images and save them at a later time.

The callbacks that you set for this function are invoked for each photo and therefore, are called multiple times.

Note: 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 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.

Since burst mode captures images in rapid succession, you can choose an appropriate moment to play the shutter sound rather than play the shutter sound repeatedly.

A CAMERA_STATUS_CAPTURECOMPLETE status event is emitted once the burst capture is completed.

Note: 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.

Returns:

CAMERA_EOK when the function successfully completes, otherwise another camera_error_t value that provides the reason that the call failed.