Image Buffer Access

The Camera library supports read-only and read-write access to the image from different stages in the imaging datapath. Applications access image buffers by binding callback functions or events to a particular stage of the imaging datapath. Alternatively, applications can use streams from the Screen API to access buffers. In this guide, 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 succeeds, 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 pass in callback functions if you want to use callback mode.

The Camera library is widely adaptable to specific design patterns that may be 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 streams (stream mode) from Screen. Using any of the three together is possible; they aren't mutually exclusive.

Regardless of the mechanism that you pick, your application is expected to handle at least one image buffer at a time. You can check the CAMERA_IMGPROP_NUMUSERBUFFERS property to determine how many buffers your application requires for processing. This property can also be accessed in your callback. You can configure more buffers by setting the same property, which is settable only if the CAMERA_FEATURE_VFNUMUSERBUFFER feature is available on your camera.

The Sensor service won't hold more than CAMERA_IMGPROP_NUMUSERBUFFERS buffers for the application; however, if another buffer arrives in the application before one buffer is read, an overflow condition occurs. This means that the application hasn't set CAMERA_IMGPROP_NUMUSERBUFFERS to a value that accommodates the application's latency. To fix this, you can either increase the value that's set in the property, or change how the application processes buffers to reduce the latency.

Whether you decide to use callback mode, event mode, stream mode, or a combination of the three depends on your application requirements. Here's a 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 a 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 gives you read/write access to buffers and allows you to define your own threading model. It also allows you to access 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. These streams provide direct access to screen_buffer_t structures. Working with these structures makes it easier for you to work with other graphics technology. For more information, see “Using stream mode.”