Using 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 becoming available.

When an imaging event is received, your application should perform the following actions:

Call the corresponding get-buffer function, by calling camera_get_viewfinder_buffers(), for example.
Process the image data appropriately.
Release the buffer back to the camera using the camera_return_buffer() function.

To bind an event to a given point in the camera datapath, use one of the following functions:

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 a 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.

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