Image Buffer Access

The Camera library supports read-only and read-write access to the image from different stages in the imaging datapath (image buffers). Applications access buffers by binding callback functions or events to a particular stage of the imaging datapath. Alternatively, an application can use streams from the Screen API to access buffers. Throughout the documentation, access to the imaging datapath is referred to as image buffers.

To begin accessing image buffers, you must call start_camera_viewfinder(). After this function successfully completes, a viewfinder window is created for you by default. This viewfinder window is configured to get the image buffers from the camera. You can join that viewfinder to your application using a Screen Graphics Subsystem GROUP ID. When you call start_camera_viewfinder(), you can choose to pass functions that are used as callbacks.

The Camera library is widely adaptable to the specific design patterns required for your application. The library provides the option of using either threaded callbacks (callback mode), events received in an event-loop (event mode), or using streams (stream mode) from the Screen. Using any of the three together is possible, they aren't mutually exclusive.

Regardless of the mechanism that you choose to use, it's expected that your application handles at least one image buffer at a time. You can check the CAMERA_IMGPROP_NUMUSERBUFFERS property to determine the number of buffers that your application requires for processing. This buffer can also be accessed in your callback. It's possible to configure more buffers by setting the CAMERA_IMGPROP_NUMUSERBUFFERS property, which is settable only if the CAMERA_FEATURE_VFNUMUSERBUFFER feature is available on your camera. You can use the CAMERA_IMGPROP_NUMUSERBUFFERS property to set the number of the buffers that are held for the application. The Sensor service won't buffer more than the number of buffers specified by CAMERA_IMGPROP_NUMUSERBUFFERS to the application, however if another buffer arrives to the application before that buffer is read, an overflow condition occurs. If an overflow condition occurs, it indicates that application hasn't set the CAMERA_IMGPROP_NUMUSERBUFFERS to a value that accommodates the latency of the application. To fix this, you can either increase the value that's set to on CAMERA_IMGPROP_NUMUSERBUFFERS, or you can change the way the processing of buffers is done in the application to reduce the latency.

Whether you decide to use callback mode, event mode,streams, or a combination of the three, depends on the requirements of your application. Here's brief comparison:

Callback mode is simple to use and the code that it executes runs in its own thread. Callbacks give you read-only access to buffers. Any memory allocated for the buffer is released when the callback completes its execution. In callback mode, you access one buffer at a time when the callback executes. The next buffer is available only when you execute the next callback. For more information, see “Using callback mode.”
Event mode allows you to have read/write access to the buffers and allows you to define your own threading model. Event mode permits you to access to more than one buffer at a time because you can manage when a buffer is released. Event mode requires that you implement your own event loop. For more information, see “Using event mode.”
Stream mode allows you to work with Screen streams. Streams provide access to screen_buffer_t structures directly. Working with screen_buffer_t structures makes it easier to work with than other graphics technology. For more information, see “Using stream mode.”