Android Hardware Abstraction Layer
Data Structures | Typedefs | Enumerations
camera2.h File Reference
#include "camera_common.h"
#include "system/camera_metadata.h"

Go to the source code of this file.

Data Structures

struct  camera2_stream_ops
 
struct  camera2_jpeg_blob
 
struct  camera2_stream_in_ops
 
struct  camera2_request_queue_src_ops
 
struct  camera2_frame_queue_dst_ops
 
struct  camera2_device_ops
 
struct  camera2_device
 

Typedefs

typedef struct camera2_stream_ops camera2_stream_ops_t
 
typedef struct
camera2_stream_in_ops 
camera2_stream_in_ops_t
 
typedef struct
camera2_request_queue_src_ops 
camera2_request_queue_src_ops_t
 
typedef struct
camera2_frame_queue_dst_ops 
camera2_frame_queue_dst_ops_t
 
typedef void(* camera2_notify_callback )(int32_t msg_type, int32_t ext1, int32_t ext2, int32_t ext3, void *user)
 
typedef struct camera2_device_ops camera2_device_ops_t
 
typedef struct camera2_device camera2_device_t
 

Enumerations

enum  { CAMERA2_HAL_PIXEL_FORMAT_OPAQUE = HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, CAMERA2_HAL_PIXEL_FORMAT_ZSL = -1 }
 
enum  { CAMERA2_JPEG_BLOB_ID = 0x00FF }
 
enum  { CAMERA2_REQUEST_QUEUE_IS_BOTTOMLESS = -1 }
 
enum  {
  CAMERA2_MSG_ERROR = 0x0001, CAMERA2_MSG_SHUTTER = 0x0010, CAMERA2_MSG_AUTOFOCUS = 0x0020, CAMERA2_MSG_AUTOEXPOSURE = 0x0021,
  CAMERA2_MSG_AUTOWB = 0x0022
}
 
enum  {
  CAMERA2_MSG_ERROR_HARDWARE = 0x0001, CAMERA2_MSG_ERROR_DEVICE, CAMERA2_MSG_ERROR_REQUEST, CAMERA2_MSG_ERROR_FRAME,
  CAMERA2_MSG_ERROR_STREAM, CAMERA2_MSG_NUM_ERRORS
}
 
enum  { CAMERA2_TRIGGER_AUTOFOCUS = 0x0001, CAMERA2_TRIGGER_CANCEL_AUTOFOCUS, CAMERA2_TRIGGER_PRECAPTURE_METERING }
 
enum  {
  CAMERA2_TEMPLATE_PREVIEW = 1, CAMERA2_TEMPLATE_STILL_CAPTURE, CAMERA2_TEMPLATE_VIDEO_RECORD, CAMERA2_TEMPLATE_VIDEO_SNAPSHOT,
  CAMERA2_TEMPLATE_ZERO_SHUTTER_LAG, CAMERA2_TEMPLATE_COUNT
}
 

Typedef Documentation

Frame output queue protocol:

The framework holds the queue and its contents. At start, the queue is empty.

  1. When the device is ready to fill an output metadata frame, it must dequeue a metadata buffer of the required size.
  2. It should then fill the metadata buffer, and place it on the frame queue using enqueue_frame. The framework takes ownership of the frame.
  3. In case of an error, a request to flush the pipeline, or shutdown, the device must return any affected dequeued frames to the framework by calling cancel_frame.
typedef void(* camera2_notify_callback)(int32_t msg_type, int32_t ext1, int32_t ext2, int32_t ext3, void *user)

Asynchronous notification callback from the HAL, fired for various reasons. Only for information independent of frame capture, or that require specific timing. The user pointer must be the same one that was passed to the device in set_notify_callback().

Definition at line 297 of file camera2.h.

Request input queue protocol:

The framework holds the queue and its contents. At start, the queue is empty.

  1. When the first metadata buffer is placed into the queue, the framework signals the device by calling notify_request_queue_not_empty().
  2. After receiving notify_request_queue_not_empty, the device must call dequeue() once it's ready to handle the next buffer.
  3. Once the device has processed a buffer, and is ready for the next buffer, it must call dequeue() again instead of waiting for a notification. If there are no more buffers available, dequeue() will return NULL. After this point, when a buffer becomes available, the framework must call notify_request_queue_not_empty() again. If the device receives a NULL return from dequeue, it does not need to query the queue again until a notify_request_queue_not_empty() call is received from the source.
  4. If the device calls buffer_count() and receives 0, this does not mean that the framework will provide a notify_request_queue_not_empty() call. The framework will only provide such a notification after the device has received a NULL from dequeue, or on initial startup.
  5. The dequeue() call in response to notify_request_queue_not_empty() may be on the same thread as the notify_request_queue_not_empty() call, and may be performed from within the notify call.
  6. All dequeued request buffers must be returned to the framework by calling free_request, including when errors occur, a device flush is requested, or when the device is shutting down.

Input reprocess stream queue management. A set of these methods is provided to the HAL device in allocate_reprocess_stream(); they are used to interact with the reprocess stream's input gralloc buffer queue.

Output image stream queue interface. A set of these methods is provided to the HAL device in allocate_stream(), and are used to interact with the gralloc buffer queue for that stream. They may not be called until after allocate_stream returns.

Enumeration Type Documentation

anonymous enum

Temporary definition during transition.

These formats will be removed and replaced with HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED. To maximize forward compatibility, HAL implementations are strongly recommended to treat FORMAT_OPAQUE and FORMAT_ZSL as equivalent to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, and return HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED in the format_actual output parameter of allocate_stream, allowing the gralloc module to select the specific format based on the usage flags from the camera and the stream consumer.

Enumerator
CAMERA2_HAL_PIXEL_FORMAT_OPAQUE 
CAMERA2_HAL_PIXEL_FORMAT_ZSL 

Definition at line 121 of file camera2.h.

anonymous enum
Enumerator
CAMERA2_JPEG_BLOB_ID 

Definition at line 147 of file camera2.h.

anonymous enum
Enumerator
CAMERA2_REQUEST_QUEUE_IS_BOTTOMLESS 

Definition at line 180 of file camera2.h.

anonymous enum

Possible message types for camera2_notify_callback

Enumerator
CAMERA2_MSG_ERROR 

An error has occurred. Argument ext1 contains the error code, and ext2 and ext3 contain any error-specific information.

CAMERA2_MSG_SHUTTER 

The exposure of a given request has begun. Argument ext1 contains the frame number, and ext2 and ext3 contain the low-order and high-order bytes of the timestamp for when exposure began. (timestamp = (ext3 << 32 | ext2))

CAMERA2_MSG_AUTOFOCUS 

The autofocus routine has changed state. Argument ext1 contains the new state; the values are the same as those for the metadata field android.control.afState. Ext2 contains the latest trigger ID passed to trigger_action(CAMERA2_TRIGGER_AUTOFOCUS) or trigger_action(CAMERA2_TRIGGER_CANCEL_AUTOFOCUS), or 0 if trigger has not been called with either of those actions.

CAMERA2_MSG_AUTOEXPOSURE 

The autoexposure routine has changed state. Argument ext1 contains the new state; the values are the same as those for the metadata field android.control.aeState. Ext2 contains the latest trigger ID value passed to trigger_action(CAMERA2_TRIGGER_PRECAPTURE_METERING), or 0 if that method has not been called.

CAMERA2_MSG_AUTOWB 

The auto-whitebalance routine has changed state. Argument ext1 contains the new state; the values are the same as those for the metadata field android.control.awbState. Ext2 contains the latest trigger ID passed to trigger_action(CAMERA2_TRIGGER_PRECAPTURE_METERING), or 0 if that method has not been called.

Definition at line 306 of file camera2.h.

anonymous enum

Error codes for CAMERA_MSG_ERROR

Enumerator
CAMERA2_MSG_ERROR_HARDWARE 

A serious failure occured. Camera device may not work without reboot, and no further frames or buffer streams will be produced by the device. Device should be treated as closed.

CAMERA2_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.

CAMERA2_MSG_ERROR_REQUEST 

An error has occurred in processing a request. No output (metadata or buffers) will be produced for this request. ext2 contains the frame number of the request. Subsequent requests are unaffected, and the device remains operational.

CAMERA2_MSG_ERROR_FRAME 

An error has occurred in producing an output frame metadata buffer for a request, but image buffers for it will still be available. Subsequent requests are unaffected, and the device remains operational. ext2 contains the frame number of the request.

CAMERA2_MSG_ERROR_STREAM 

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. ext2 contains the frame number of the request, and ext3 contains the stream id.

CAMERA2_MSG_NUM_ERRORS 

Number of error types

Definition at line 349 of file camera2.h.

anonymous enum

Possible trigger ids for trigger_action()

Enumerator
CAMERA2_TRIGGER_AUTOFOCUS 

Trigger an autofocus cycle. The effect of the trigger depends on the autofocus mode in effect when the trigger is received, which is the mode listed in the latest capture request to be dequeued by the HAL. If the mode is OFF, EDOF, or FIXED, the trigger has no effect. In AUTO, MACRO, or CONTINUOUS_* modes, see below for the expected behavior. The state of the autofocus cycle can be tracked in android.control.afMode and the corresponding notifications.

In AUTO or MACRO mode, the AF state transitions (and notifications) when calling with trigger ID = N with the previous ID being K are:

Initial state Transitions INACTIVE (K) -> ACTIVE_SCAN (N) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) AF_FOCUSED (K) -> ACTIVE_SCAN (N) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) AF_NOT_FOCUSED (K) -> ACTIVE_SCAN (N) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) ACTIVE_SCAN (K) -> AF_FOCUSED(N) or AF_NOT_FOCUSED(N) PASSIVE_SCAN (K) Not used in AUTO/MACRO mode PASSIVE_FOCUSED (K) Not used in AUTO/MACRO mode

In CONTINUOUS_PICTURE mode, triggering AF must lock the AF to the current lens position and transition the AF state to either AF_FOCUSED or NOT_FOCUSED. If a passive scan is underway, that scan must complete and then lock the lens position and change AF state. TRIGGER_CANCEL_AUTOFOCUS will allow the AF to restart its operation.

Initial state Transitions INACTIVE (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) PASSIVE_FOCUSED (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) PASSIVE_SCAN (K) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) AF_FOCUSED (K) no effect except to change next notification ID to N AF_NOT_FOCUSED (K) no effect except to change next notification ID to N

In CONTINUOUS_VIDEO mode, triggering AF must lock the AF to the current lens position and transition the AF state to either AF_FOCUSED or NOT_FOCUSED. If a passive scan is underway, it must immediately halt, in contrast with CONTINUOUS_PICTURE mode. TRIGGER_CANCEL_AUTOFOCUS will allow the AF to restart its operation.

Initial state Transitions INACTIVE (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) PASSIVE_FOCUSED (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) PASSIVE_SCAN (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) AF_FOCUSED (K) no effect except to change next notification ID to N AF_NOT_FOCUSED (K) no effect except to change next notification ID to N

Ext1 is an ID that must be returned in subsequent auto-focus state change notifications through camera2_notify_callback() and stored in android.control.afTriggerId.

CAMERA2_TRIGGER_CANCEL_AUTOFOCUS 

Send a cancel message to the autofocus algorithm. The effect of the cancellation depends on the autofocus mode in effect when the trigger is received, which is the mode listed in the latest capture request to be dequeued by the HAL. If the AF mode is OFF or EDOF, the cancel has no effect. For other modes, the lens should return to its default position, any current autofocus scan must be canceled, and the AF state should be set to INACTIVE.

The state of the autofocus cycle can be tracked in android.control.afMode and the corresponding notification. Continuous autofocus modes may resume focusing operations thereafter exactly as if the camera had just been set to a continuous AF mode.

Ext1 is an ID that must be returned in subsequent auto-focus state change notifications through camera2_notify_callback() and stored in android.control.afTriggerId.

CAMERA2_TRIGGER_PRECAPTURE_METERING 

Trigger a pre-capture metering cycle, which may include firing the flash to determine proper capture parameters. Typically, this trigger would be fired for a half-depress of a camera shutter key, or before a snapshot capture in general. The state of the metering cycle can be tracked in android.control.aeMode and the corresponding notification. If the auto-exposure mode is OFF, the trigger does nothing.

Ext1 is an ID that must be returned in subsequent auto-exposure/auto-white balance state change notifications through camera2_notify_callback() and stored in android.control.aePrecaptureId.

Definition at line 393 of file camera2.h.

anonymous enum

Possible template types for construct_default_request()

Enumerator
CAMERA2_TEMPLATE_PREVIEW 

Standard camera preview operation with 3A on auto.

CAMERA2_TEMPLATE_STILL_CAPTURE 

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

CAMERA2_TEMPLATE_VIDEO_RECORD 

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

CAMERA2_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.

CAMERA2_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.

CAMERA2_TEMPLATE_COUNT 

Definition at line 485 of file camera2.h.