FrameOutputOptions

interface FrameOutputOptions

Configuration options for a CameraFrameOutput.

See

• CameraFrameOutput
• useFrameOutput(...)

Properties

allowDeferredStart

allowDeferredStart: boolean

Allow this output to start later in the capture pipeline startup process.

Enabling this lets the camera prioritize outputs needed for preview first, then start the CameraFrameOutput shortly afterwards.

This can improve startup behavior when preview responsiveness is more important than receiving frame-processor frames immediately.

dropFramesWhileBusy

dropFramesWhileBusy: boolean

Whether to drop new Frames when they arrive while the Frame Processor is still executing.

• If set to true, the CameraFrameOutput will automatically drop any Frames that arrive while your Frame Processor is still executing to avoid exhausting resources, at the risk of loosing information since Frames may be dropped.
• If set to false, the CameraFrameOutput will queue up any Frames that arrive while your Frame Processor is still executing and immediatelly call it once it is free again, at the risk of exhausting resources and growing RAM.

Default

true

enableCameraMatrixDelivery

enableCameraMatrixDelivery: boolean

Gets or sets whether the CameraFrameOutput attaches a Camera Intrinsic Matrix to the Frames it produces.

Intrinsic Matrixes are only supported if video stabilization is 'off'.

See

Frame.cameraIntrinsicMatrix

Default

false

enablePhysicalBufferRotation

enablePhysicalBufferRotation: boolean

Enable (or disable) physical buffer rotation.

• When enablePhysicalBufferRotation is set to true, and the CameraFrameOutput's outputOrientation is set to any value different than the Camera sensor's native orientation, the Camera pipeline will physically rotate the buffers to apply the orientation. The resulting Frame's orientation will then always be 'up', meaning it no longer needs to be rotated by the consumer.
• When enablePhysicalBufferRotation is set to false, the Camera pipeline will not physically rotate buffers, but instead only provide the Frame's orientation relative to the CameraFrameOutput's target outputOrientation as metadata (see Frame.orientation), meaning the consumers have to handle orientation themselves - e.g. by reading pixels in a different order, or applying orientation in a GPU rendering pass, depending on the use-case.

Setting enablePhysicalBufferRotation to true introduces processing overhead.

Default

false

enablePreviewSizedOutputBuffers

enablePreviewSizedOutputBuffers: boolean

Deliver smaller, preview-sized output buffers for Frame Processing.

This is useful for ML and computer vision workloads where full-resolution buffers are unnecessary and would only increase memory bandwidth and processing costs.

Other camera outputs (for example CameraVideoOutput) keep using the selected full-resolution CameraFormat.

Default

false

pixelFormat

pixelFormat: TargetVideoPixelFormat

Sets the TargetVideoPixelFormat of the CameraFrameOutput.

• The most efficient format is 'native', which internally just uses the currently selected CameraFormat's nativePixelFormat.
• Some CameraFormats may support natively streaming in a YUV format (e.g. if CameraFormat.nativePixelFormat == 'yuv-420-8-bit-video'), in which case 'yuv' can also be zero overhead.
• If your Frame Processor absolutely requires to run in RGB, you may set pixelFormat to 'rgb', which comes with additional processing overhead as the Camera pipeline will convert native frames to RGB (e.g. to 'rgb-bgra-8-bit').

Discussion

It is recommended to use 'native' if possible, as this will use a zero-copy GPU-only path. Other formats almost always require conversion at some point, especially on Android.

If you need CPU-access to pixels, use 'yuv' instead of 'rgb' as a next best alternative, as 'rgb' uses ~2.6x more bandwidth than 'yuv' and requires additional conversions as it is not a Camera-native format.

Only use 'rgb' if you really need to stream Frames in an RGB format.

Discussion

It is recommended to use 'native' and design your Frame Processing pipeline to be fully GPU-based, such as performing ML model processing on the GPU/NPU and rendering via Metal/Vulkan/OpenGL by importing the Frame as an external sampler/texture (or via Skia/WebGPU which use NativeBuffer zero-copy APIs), as the Frame's data will already be on the GPU then. If you use a non-'native' pixelFormat in a GPU pipeline, your pipeline will be noticeably slower as CPU <-> GPU downloads/uploads will be performed on every frame.