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, the shutter has fired, or 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 imaging 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 datapath, use the camera_disable_event() function.

When a non-status event occurs, such as a viewfinder event, your application can retrieve the associated buffer by calling the corresponding get function, one of:

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 defined interval. If concurrent events occur in your application where the time to process one event could interfere with the deadline to finish processing another one, 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 also want to record the video to a file. Because it's possible to take more time to save the file than the inter-frame period of the viewfinder frames, it's best to process the recording task in a different thread from the viewfinder-processing task thread. You can also use callback mode to resolve this problem because callbacks inherently execute in separate threads.

Note: It is important that your application follow the resource management guidelines outlined in “Resource Management”. If you don't observe these guidelines, your application is at risk of crashing due to memory access errors when resource arbitration is performed by the operating system.