CameraCaptureSession.Prepare(Surface) Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Pre-allocate all buffers for an output Surface.
[Android.Runtime.Register("prepare", "(Landroid/view/Surface;)V", "GetPrepare_Landroid_view_Surface_Handler", ApiSince=23)]
public abstract void Prepare (Android.Views.Surface surface);[<Android.Runtime.Register("prepare", "(Landroid/view/Surface;)V", "GetPrepare_Landroid_view_Surface_Handler", ApiSince=23)>]
abstract member Prepare : Android.Views.Surface -> unitParameters
- surface
- Surface
the output Surface for which buffers should be pre-allocated. Must be one of the output Surfaces used to create this session.
- Attributes
Remarks
Pre-allocate all buffers for an output Surface.
Normally, the image buffers for a given output Surface are allocated on-demand, to minimize startup latency and memory overhead.
However, in some cases, it may be desirable for the buffers to be allocated before any requests targeting the Surface are actually submitted to the device. Large buffers may take some time to allocate, which can result in delays in submitting requests until sufficient buffers are allocated to reach steady-state behavior. Such delays can cause bursts to take longer than desired, or cause skips or stutters in preview output.
The prepare() method can be used to perform this preallocation. It may only be called for a given output Surface before that Surface is used as a target for a request. The number of buffers allocated is the sum of the count needed by the consumer providing the output Surface, and the maximum number needed by the camera device to fill its pipeline. Since this may be a larger number than what is actually required for steady-state operation, using prepare may result in higher memory consumption than the normal on-demand behavior results in. Prepare() will also delay the time to first output to a given Surface, in exchange for smoother frame rate once the allocation is complete.
For example, an application that creates an android.media.ImageReader#newInstance ImageReader with a maxImages argument of 10, but only uses 3 simultaneous Images at once would normally only cause those 3 images to be allocated (plus what is needed by the camera device for smooth operation). But using prepare() on the ImageReader Surface will result in all 10 Images being allocated. So applications using this method should take care to request only the number of buffers actually necessary for their application.
If the same output Surface is used in consecutive sessions (without closing the first session explicitly), then its already-allocated buffers are carried over, and if it was used as a target of a capture request in the first session, prepare cannot be called on it in the second session.
Once allocation is complete, StateCallback#onSurfacePrepared will be invoked with the Surface provided to this method. Between the prepare call and the onSurfacePrepared call, the Surface provided to prepare must not be used as a target of a CaptureRequest submitted to this session.
Note that if 2 surfaces share the same stream via OutputConfiguration#enableSurfaceSharing and OutputConfiguration#addSurface, prepare() only needs to be called on one surface, and StateCallback#onSurfacePrepared will be triggered for both surfaces.
android.hardware.camera2.CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY devices cannot pre-allocate output buffers; for those devices, StateCallback#onSurfacePrepared will be immediately called, and no preallocation is done.
Java documentation for android.hardware.camera2.CameraCaptureSession.prepare(android.view.Surface).
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.