Android Hardware Abstraction Layer
Data Structures | Typedefs | Enumerations
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 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_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_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.

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, and the static metadata field android.jpeg.maxSize is used as the buffer size. 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[android.jpeg.maxSize - sizeof(camera3_jpeg_blob)]. 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.

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_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_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 1329 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 1199 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 1373 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 has begun. camera3_notify_msg.message.shutter contains the information the capture.

CAMERA3_NUM_MESSAGES 

Number of framework message types

Definition at line 1349 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_COUNT 
CAMERA3_VENDOR_TEMPLATE_START 

First value for vendor-defined request templates

Definition at line 1505 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.

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 features, where copying the captured image from the output buffer to the reprocessing input buffer would be expensive. The stream will be used by the framework as follows:

  1. The framework includes a buffer from this stream as output buffer in a request as normal.
  2. Once the HAL device returns a filled output buffer to the framework, the framework may do one of two things with the filled buffer:
  1. a. The framework uses the filled data, and returns the now-used buffer to the stream queue for reuse. This behavior exactly matches the OUTPUT type of stream.
  1. b. The framework wants to reprocess the filled data, and uses the buffer as an input buffer for a request. Once the HAL device has used the reprocessing buffer, it then returns it to the framework. The framework then returns the now-used buffer to the stream queue for reuse.
  2. The HAL device will be given the buffer again as an output buffer for a request at some future point.

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 996 of file camera3.h.