BackpressureStrategy

class BackpressureStrategy
androidx.camera.core.ImageAnalysis.BackpressureStrategy

How to apply backpressure to the source producing images for analysis.

Sometimes, images may be produced faster than they can be analyzed. Since images generally reserve a large portion of the device's memory, they cannot be buffered unbounded and indefinitely. The backpressure strategy defines how to deal with this scenario.

The receiver of the ImageProxy is responsible for explicitly closing the image by calling ImageProxy#close(). However, the image will only be valid when the ImageAnalysis instance is bound to a camera.

Summary

Constants

static Int

Block the producer from generating new images.

static Int

Only deliver the latest image to the analyzer, dropping images as they arrive.

Public constructors

How to apply backpressure to the source producing images for analysis.

Constants

BLOCK_PRODUCER

static val BLOCK_PRODUCER: Int

Block the producer from generating new images.

Once the producer has produced the number of images equal to the image queue depth, and none have been closed, the producer will stop producing images. Note that images may be queued internally and not be delivered to the analyzer until the last delivered image has been closed with ImageProxy#close(). These internally queued images will count towards the total number of images that the producer can provide at any one time.

When the producer stops producing images, it may also stop producing images for other use cases, such as Preview, so it is important for the analyzer to keep up with frame rate, on average. Failure to keep up with frame rate may lead to jank in the frame stream and a diminished user experience. If more time is needed for analysis on some frames, consider increasing the image queue depth with Builder#setImageQueueDepth(int).

Value: 1

KEEP_ONLY_LATEST

static val KEEP_ONLY_LATEST: Int

Only deliver the latest image to the analyzer, dropping images as they arrive.

This strategy ignores the value set by Builder#setImageQueueDepth(int). Only one image will be delivered for analysis at a time. If more images are produced while that image is being analyzed, they will be dropped and not queued for delivery. Once the image being analyzed is closed by calling ImageProxy#close(), the next latest image will be delivered.

Internally this strategy may make use of an internal Executor to receive and drop images from the producer. A performance-tuned executor will be created internally unless one is explicitly provided by Builder#setBackgroundExecutor(Executor). In order to ensure smooth operation of this backpressure strategy, any user supplied Executor must be able to quickly respond to tasks posted to it, so setting the executor manually should only be considered in advanced use cases.

Value: 0

Public constructors

<init>

BackpressureStrategy()

How to apply backpressure to the source producing images for analysis.

Sometimes, images may be produced faster than they can be analyzed. Since images generally reserve a large portion of the device's memory, they cannot be buffered unbounded and indefinitely. The backpressure strategy defines how to deal with this scenario.

The receiver of the ImageProxy is responsible for explicitly closing the image by calling ImageProxy#close(). However, the image will only be valid when the ImageAnalysis instance is bound to a camera.