Image Buffer Access

Updated: April 19, 2023

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: