camera3.h File Reference
#include <system/camera_metadata.h>
#include "camera_common.h"

Go to the source code of this file.

Data Structures

struct  camera3_stream
 
struct  camera3_stream_configuration
 
struct  camera3_stream_buffer
 
struct  camera3_stream_buffer_set
 
struct  camera3_jpeg_blob
 
struct  camera3_error_msg
 
struct  camera3_shutter_msg
 
struct  camera3_notify_msg
 
struct  camera3_capture_request
 
struct  camera3_capture_result
 
struct  camera3_callback_ops
 
struct  camera3_device_ops
 
struct  camera3_device
 

Typedefs

typedef enum camera3_stream_type camera3_stream_type_t
 
typedef enum
camera3_stream_rotation 
camera3_stream_rotation_t
 
typedef enum
camera3_stream_configuration_mode 
camera3_stream_configuration_mode_t
 
typedef struct camera3_stream camera3_stream_t
 
typedef struct
camera3_stream_configuration 
camera3_stream_configuration_t
 
typedef enum camera3_buffer_status camera3_buffer_status_t
 
typedef struct
camera3_stream_buffer 
camera3_stream_buffer_t
 
typedef struct
camera3_stream_buffer_set 
camera3_stream_buffer_set_t
 
typedef struct camera3_jpeg_blob camera3_jpeg_blob_t
 
typedef enum camera3_msg_type camera3_msg_type_t
 
typedef enum camera3_error_msg_code camera3_error_msg_code_t
 
typedef struct camera3_error_msg camera3_error_msg_t
 
typedef struct camera3_shutter_msg camera3_shutter_msg_t
 
typedef struct camera3_notify_msg camera3_notify_msg_t
 
typedef enum
camera3_request_template 
camera3_request_template_t
 
typedef struct
camera3_capture_request 
camera3_capture_request_t
 
typedef struct
camera3_capture_result 
camera3_capture_result_t
 
typedef struct camera3_callback_ops camera3_callback_ops_t
 
typedef struct camera3_device_ops camera3_device_ops_t
 
typedef struct camera3_device camera3_device_t
 

Enumerations

enum  camera3_stream_type { CAMERA3_STREAM_OUTPUT = 0, CAMERA3_STREAM_INPUT = 1, CAMERA3_STREAM_BIDIRECTIONAL = 2, CAMERA3_NUM_STREAM_TYPES }
 
enum  camera3_stream_rotation { CAMERA3_STREAM_ROTATION_0 = 0, CAMERA3_STREAM_ROTATION_90 = 1, CAMERA3_STREAM_ROTATION_180 = 2, CAMERA3_STREAM_ROTATION_270 = 3 }
 
enum  camera3_stream_configuration_mode { CAMERA3_STREAM_CONFIGURATION_NORMAL_MODE = 0, CAMERA3_STREAM_CONFIGURATION_CONSTRAINED_HIGH_SPEED_MODE = 1, CAMERA3_VENDOR_STREAM_CONFIGURATION_MODE_START = 0x8000 }
 
enum  camera3_buffer_status { CAMERA3_BUFFER_STATUS_OK = 0, CAMERA3_BUFFER_STATUS_ERROR = 1 }
 
enum  { CAMERA3_JPEG_BLOB_ID = 0x00FF }
 
enum  camera3_msg_type { CAMERA3_MSG_ERROR = 1, CAMERA3_MSG_SHUTTER = 2, CAMERA3_NUM_MESSAGES }
 
enum  camera3_error_msg_code {
  CAMERA3_MSG_ERROR_DEVICE = 1, CAMERA3_MSG_ERROR_REQUEST = 2, CAMERA3_MSG_ERROR_RESULT = 3, CAMERA3_MSG_ERROR_BUFFER = 4,
  CAMERA3_MSG_NUM_ERRORS
}
 
enum  camera3_request_template {
  CAMERA3_TEMPLATE_PREVIEW = 1, CAMERA3_TEMPLATE_STILL_CAPTURE = 2, CAMERA3_TEMPLATE_VIDEO_RECORD = 3, CAMERA3_TEMPLATE_VIDEO_SNAPSHOT = 4,
  CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG = 5, CAMERA3_TEMPLATE_MANUAL = 6, CAMERA3_TEMPLATE_COUNT, CAMERA3_VENDOR_TEMPLATE_START = 0x40000000
}
 

Typedef Documentation

camera3_buffer_status_t:

The current status of a single stream buffer.

camera3_capture_request_t:

A single request for image capture/buffer reprocessing, sent to the Camera HAL device by the framework in process_capture_request().

The request contains the settings to be used for this capture, and the set of output buffers to write the resulting image data in. It may optionally contain an input buffer, in which case the request is for reprocessing that input buffer instead of capturing a new image with the camera sensor. The capture is identified by the frame_number.

In response, the camera HAL device must send a camera3_capture_result structure asynchronously to the framework, using the process_capture_result() callback.

camera3_capture_result_t:

The result of a single capture/reprocess by the camera HAL device. This is sent to the framework asynchronously with process_capture_result(), in response to a single capture request sent to the HAL with process_capture_request(). Multiple process_capture_result() calls may be performed by the HAL for each request.

Each call, all with the same frame number, may contain some subset of the output buffers, and/or the result metadata. The metadata may only be provided once for a given frame number; all other calls must set the result metadata to NULL.

The result structure contains the output metadata from this capture, and the set of output buffers that have been/will be filled for this capture. Each output buffer may come with a release sync fence that the framework will wait on before reading, in case the buffer has not yet been filled by the HAL.

>= CAMERA_DEVICE_API_VERSION_3_2:

The metadata may be provided multiple times for a single frame number. The framework will accumulate together the final result set by combining each partial result together into the total result set.

If an input buffer is given in a request, the HAL must return it in one of the process_capture_result calls, and the call may be to just return the input buffer, without metadata and output buffers; the sync fences must be handled the same way they are done for output buffers.

Performance considerations:

Applications will also receive these partial results immediately, so sending partial results is a highly recommended performance optimization to avoid the total pipeline latency before sending the results for what is known very early on in the pipeline.

A typical use case might be calculating the AF state halfway through the pipeline; by sending the state back to the framework immediately, we get a 50% performance increase and perceived responsiveness of the auto-focus.

Defined error codes for CAMERA_MSG_ERROR

camera3_error_msg_t:

Message contents for CAMERA3_MSG_ERROR

camera3_jpeg_blob:

Transport header for compressed JPEG buffers in output streams.

To capture JPEG images, a stream is created using the pixel format HAL_PIXEL_FORMAT_BLOB. The buffer size for the stream is calculated by the framework, based on the static metadata field android.jpeg.maxSize. Since compressed JPEG images are of variable size, the HAL needs to include the final size of the compressed image using this structure inside the output stream buffer. The JPEG blob ID field must be set to CAMERA3_JPEG_BLOB_ID.

Transport header should be at the end of the JPEG output stream buffer. That means the jpeg_blob_id must start at byte[buffer_size - sizeof(camera3_jpeg_blob)], where the buffer_size is the size of gralloc buffer. Any HAL using this transport header must account for it in android.jpeg.maxSize The JPEG data itself starts at the beginning of the buffer and should be jpeg_size bytes long.

camera3_msg_type:

Indicates the type of message sent, which specifies which member of the message union is valid.

camera3_notify_msg_t:

The message structure sent to camera3_callback_ops_t.notify()

camera3_request_template_t:

Available template types for camera3_device_ops.construct_default_request_settings()

camera3_shutter_msg_t:

Message contents for CAMERA3_MSG_SHUTTER

camera3_stream_buffer_set_t:

The complete set of gralloc buffers for a stream. This structure is given to register_stream_buffers() to allow the camera HAL device to register/map/etc newly allocated stream buffers.

>= CAMERA_DEVICE_API_VERSION_3_2:

Deprecated (and not used). In particular, register_stream_buffers is also deprecated and will never be invoked.

camera3_stream_buffer_t:

A single buffer from a camera3 stream. It includes a handle to its parent stream, the handle to the gralloc buffer itself, and sync fences

The buffer does not specify whether it is to be used for input or output; that is determined by its parent stream type and how the buffer is passed to the HAL device.

camera3_stream_configuration_mode_t:

This defines the general operation mode for the HAL (for a given stream configuration), where modes besides NORMAL have different semantics, and usually limit the generality of the API in exchange for higher performance in some particular area.

camera3_stream_configuration_t:

A structure of stream definitions, used by configure_streams(). This structure defines all the output streams and the reprocessing input stream for the current camera use case.

camera3_stream_rotation_t:

The required counterclockwise rotation of camera stream.

camera3_stream_t:

A handle to a single camera input or output stream. A stream is defined by the framework by its buffer resolution and format, and additionally by the HAL with the gralloc usage flags and the maximum in-flight buffer count.

The stream structures are owned by the framework, but pointers to a camera3_stream passed into the HAL by configure_streams() are valid until the end of the first subsequent configure_streams() call that does not include that camera3_stream as an argument, or until the end of the close() call.

All camera3_stream framework-controlled members are immutable once the camera3_stream is passed into configure_streams(). The HAL may only change the HAL-controlled parameters during a configure_streams() call, except for the contents of the private pointer.

If a configure_streams() call returns a non-fatal error, all active streams remain valid as if configure_streams() had not been called.

The endpoint of the stream is not visible to the camera HAL device. In DEVICE_API_VERSION_3_1, this was changed to share consumer usage flags on streams where the camera is a producer (OUTPUT and BIDIRECTIONAL stream types) see the usage field below.

camera3_stream_type_t:

The type of the camera stream, which defines whether the camera HAL device is the producer or the consumer for that stream, and how the buffers of the stream relate to the other streams.

Enumeration Type Documentation

anonymous enum
Enumerator
CAMERA3_JPEG_BLOB_ID 

Definition at line 1860 of file camera3.h.

camera3_buffer_status_t:

The current status of a single stream buffer.

Enumerator
CAMERA3_BUFFER_STATUS_OK 

The buffer is in a normal state, and can be used after waiting on its sync fence.

CAMERA3_BUFFER_STATUS_ERROR 

The buffer does not contain valid data, and the data in it should not be used. The sync fence must still be waited on before reusing the buffer.

Definition at line 1700 of file camera3.h.

Defined error codes for CAMERA_MSG_ERROR

Enumerator
CAMERA3_MSG_ERROR_DEVICE 

A serious failure occured. No further frames or buffer streams will be produced by the device. Device should be treated as closed. The client must reopen the device to use it again. The frame_number field is unused.

CAMERA3_MSG_ERROR_REQUEST 

An error has occurred in processing a request. No output (metadata or buffers) will be produced for this request. The frame_number field specifies which request has been dropped. Subsequent requests are unaffected, and the device remains operational.

CAMERA3_MSG_ERROR_RESULT 

An error has occurred in producing an output result metadata buffer for a request, but output stream buffers for it will still be available. Subsequent requests are unaffected, and the device remains operational. The frame_number field specifies the request for which result metadata won't be available.

CAMERA3_MSG_ERROR_BUFFER 

An error has occurred in placing an output buffer into a stream for a request. The frame metadata and other buffers may still be available. Subsequent requests are unaffected, and the device remains operational. The frame_number field specifies the request for which the buffer was dropped, and error_stream contains a pointer to the stream that dropped the frame.u

CAMERA3_MSG_NUM_ERRORS 

Number of error types

Definition at line 1904 of file camera3.h.

camera3_msg_type:

Indicates the type of message sent, which specifies which member of the message union is valid.

Enumerator
CAMERA3_MSG_ERROR 

An error has occurred. camera3_notify_msg.message.error contains the error information.

CAMERA3_MSG_SHUTTER 

The exposure of a given request or processing a reprocess request has begun. camera3_notify_msg.message.shutter contains the information the capture.

CAMERA3_NUM_MESSAGES 

Number of framework message types

Definition at line 1880 of file camera3.h.

camera3_request_template_t:

Available template types for camera3_device_ops.construct_default_request_settings()

Enumerator
CAMERA3_TEMPLATE_PREVIEW 

Standard camera preview operation with 3A on auto.

CAMERA3_TEMPLATE_STILL_CAPTURE 

Standard camera high-quality still capture with 3A and flash on auto.

CAMERA3_TEMPLATE_VIDEO_RECORD 

Standard video recording plus preview with 3A on auto, torch off.

CAMERA3_TEMPLATE_VIDEO_SNAPSHOT 

High-quality still capture while recording video. Application will include preview, video record, and full-resolution YUV or JPEG streams in request. Must not cause stuttering on video stream. 3A on auto.

CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG 

Zero-shutter-lag mode. Application will request preview and full-resolution data for each frame, and reprocess it to JPEG when a still image is requested by user. Settings should provide highest-quality full-resolution images without compromising preview frame rate. 3A on auto.

CAMERA3_TEMPLATE_MANUAL 

A basic template for direct application control of capture parameters. All automatic control is disabled (auto-exposure, auto-white balance, auto-focus), and post-processing parameters are set to preview quality. The manual capture parameters (exposure, sensitivity, etc.) are set to reasonable defaults, but should be overridden by the application depending on the intended use case.

CAMERA3_TEMPLATE_COUNT 
CAMERA3_VENDOR_TEMPLATE_START 

First value for vendor-defined request templates

Definition at line 2037 of file camera3.h.

camera3_stream_configuration_mode_t:

This defines the general operation mode for the HAL (for a given stream configuration), where modes besides NORMAL have different semantics, and usually limit the generality of the API in exchange for higher performance in some particular area.

Enumerator
CAMERA3_STREAM_CONFIGURATION_NORMAL_MODE 

Normal stream configuration operation mode. This is the default camera operation mode, where all semantics of HAL APIs and metadata controls apply.

CAMERA3_STREAM_CONFIGURATION_CONSTRAINED_HIGH_SPEED_MODE 

Special constrained high speed operation mode for devices that can not support high speed output in NORMAL mode. All streams in this configuration are operating at high speed mode and have different characteristics and limitations to achieve high speed output. The NORMAL mode can still be used for high speed output if the HAL can support high speed output while satisfying all the semantics of HAL APIs and metadata controls. It is recommended for the HAL to support high speed output in NORMAL mode (by advertising the high speed FPS ranges in android.control.aeAvailableTargetFpsRanges) if possible.

This mode has below limitations/requirements:

  1. The HAL must support up to 2 streams with sizes reported by android.control.availableHighSpeedVideoConfigurations.
  2. In this mode, the HAL is expected to output up to 120fps or higher. This mode must support the targeted FPS range and size configurations reported by android.control.availableHighSpeedVideoConfigurations.
  3. The HAL must support HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED output stream format.
  4. To achieve efficient high speed streaming, the HAL may have to aggregate multiple frames together and send to camera device for processing where the request controls are same for all the frames in this batch (batch mode). The HAL must support max batch size and the max batch size requirements defined by android.control.availableHighSpeedVideoConfigurations.
  5. In this mode, the HAL must override aeMode, awbMode, and afMode to ON, ON, and CONTINUOUS_VIDEO, respectively. All post-processing block mode controls must be overridden to be FAST. Therefore, no manual control of capture and post-processing parameters is possible. All other controls operate the same as when android.control.mode == AUTO. This means that all other android.control.* fields must continue to work, such as

    android.control.aeTargetFpsRange android.control.aeExposureCompensation android.control.aeLock android.control.awbLock android.control.effectMode android.control.aeRegions android.control.afRegions android.control.awbRegions android.control.afTrigger android.control.aePrecaptureTrigger

    Outside of android.control.*, the following controls must work:

    android.flash.mode (TORCH mode only, automatic flash for still capture will not work since aeMode is ON) android.lens.opticalStabilizationMode (if it is supported) android.scaler.cropRegion android.statistics.faceDetectMode (if it is supported)

For more details about high speed stream requirements, see android.control.availableHighSpeedVideoConfigurations and CONSTRAINED_HIGH_SPEED_VIDEO capability defined in android.request.availableCapabilities.

This mode only needs to be supported by HALs that include CONSTRAINED_HIGH_SPEED_VIDEO in the android.request.availableCapabilities static metadata.

CAMERA3_VENDOR_STREAM_CONFIGURATION_MODE_START 

First value for vendor-defined stream configuration modes.

Definition at line 1408 of file camera3.h.

camera3_stream_rotation_t:

The required counterclockwise rotation of camera stream.

Enumerator
CAMERA3_STREAM_ROTATION_0 
CAMERA3_STREAM_ROTATION_90 
CAMERA3_STREAM_ROTATION_180 
CAMERA3_STREAM_ROTATION_270 

Definition at line 1387 of file camera3.h.

camera3_stream_type_t:

The type of the camera stream, which defines whether the camera HAL device is the producer or the consumer for that stream, and how the buffers of the stream relate to the other streams.

Enumerator
CAMERA3_STREAM_OUTPUT 

This stream is an output stream; the camera HAL device will be responsible for filling buffers from this stream with newly captured or reprocessed image data.

CAMERA3_STREAM_INPUT 

This stream is an input stream; the camera HAL device will be responsible for reading buffers from this stream and sending them through the camera processing pipeline, as if the buffer was a newly captured image from the imager.

The pixel format for input stream can be any format reported by android.scaler.availableInputOutputFormatsMap. The pixel format of the output stream that is used to produce the reprocessing data may be any format reported by android.scaler.availableStreamConfigurations. The supported input/output stream combinations depends the camera device capabilities, see android.scaler.availableInputOutputFormatsMap for stream map details.

This kind of stream is generally used to reprocess data into higher quality images (that otherwise would cause a frame rate performance loss), or to do off-line reprocessing.

CAMERA_DEVICE_API_VERSION_3_3: The typical use cases are OPAQUE (typically ZSL) and YUV reprocessing, see S8.2, S8.3 and S10 for more details.

CAMERA3_STREAM_BIDIRECTIONAL 

This stream can be used for input and output. Typically, the stream is used as an output stream, but occasionally one already-filled buffer may be sent back to the HAL device for reprocessing.

This kind of stream is meant generally for Zero Shutter Lag (ZSL) features, where copying the captured image from the output buffer to the reprocessing input buffer would be expensive. See S8.1 for more details.

Note that the HAL will always be reprocessing data it produced.

CAMERA3_NUM_STREAM_TYPES 

Total number of framework-defined stream types

Definition at line 1329 of file camera3.h.