Using callback mode

Callbacks are used to asynchronously access camera image data and status information.

You can use callbacks to provide custom code to execute when performing camera operations such as accessing encoded video or viewfinder frames. Using callbacks provides a lot 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:

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* );

where:

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.

Note: 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 when your callback function executes.
void*: The user-specified arg argument.

Note: It's important that your application follows the guidelines for resource management outlined in “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.