camera_start_burst()

Start to take pictures in burst mode.

Synopsis:

#include <camera/camera_api.h>
 
camera_error_t camera_start_burst(camera_handle_t handle, 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)

Arguments:

handle

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

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 gets 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 gets invoked when the post-view (review) image data 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 that is called when the final 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.

Library:

libcamapi

Description:

Before you take a photo, 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_CONTINUOUSBURST is available. You can determine whether the feature is available by calling the camera_can_feature() function.

This function does not block. To terminate a continuous burst capture, call the camera_stop_burst() function.

Unlike the camera_take_burst function, there is no upper limit to the number of pictures you can take. Buffers are only valid for the duration of the callback to prevent memory exhaustion. To prevent memory exhaustion, you can:
  • Maintain a circular buffer in order to implement negative-shutter lag.
  • Maintain a growing heap of buffers after capture begins in order to select your favorite photo — after the fact.
  • Only capture images where certain criteria has been met. For example, capture images that contain only smiles or three faces are seen in the photo.

Burst runs as close as possible to the preview frame rate specified by in the camera_set_photovf_property() function divided by the burst divisor specified in the camera_set_photo_property() function. Use the camera_start_burst() function when image-capture latency is a concern or when your application cannot tolerate brief disruptions to the viewfinder. Brief disruptions can occur when using the camera_take_photo() function.

You should make copies of the frames as they arrive and exit the callback as quickly as possible. You should avoid saving the files within the image_callback function because writing to disk may take more time that is available before the next frame arrives. For this reason, buffers are only valid until the callback function returns. Memory that was valid before a callback started is unmapped from user's process when the callback completes. Attempts to access memory buffers after the end of a callback function yields undefined results, such as bus errors.

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 should choose an appropriate moment to play the shutter sound rather than play the shutter sound repeatedly.

Returns:

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

Last modified: 2013-12-21

comments powered by Disqus