Android Hardware Abstraction Layer
Data Fields
camera3_device_ops Struct Reference

#include <camera3.h>

Data Fields

int(* initialize )(const struct camera3_device *, const camera3_callback_ops_t *callback_ops)
int(* configure_streams )(const struct camera3_device *, camera3_stream_configuration_t *stream_list)
int(* register_stream_buffers )(const struct camera3_device *, const camera3_stream_buffer_set_t *buffer_set)
const camera_metadata_t *(* construct_default_request_settings )(const struct camera3_device *, int type)
int(* process_capture_request )(const struct camera3_device *, camera3_capture_request_t *request)
void(* get_metadata_vendor_tag_ops )(const struct camera3_device *, vendor_tag_query_ops_t *ops)
void(* dump )(const struct camera3_device *, int fd)
int(* flush )(const struct camera3_device *)
void * reserved [8]

Detailed Description

Definition at line 1800 of file camera3.h.

Field Documentation

int(* configure_streams)(const struct camera3_device *, camera3_stream_configuration_t *stream_list)


Reset the HAL camera device processing pipeline and set up new input and output streams. This call replaces any existing stream configuration with the streams defined in the stream_list. This method will be called at least once after initialize() before a request is submitted with process_capture_request().

The stream_list must contain at least one output-capable stream, and may not contain more than one input-capable stream.

The stream_list may contain streams that are also in the currently-active set of streams (from the previous call to configure_stream()). These streams will already have valid values for usage, max_buffers, and the private pointer. If such a stream has already had its buffers registered, register_stream_buffers() will not be called again for the stream, and buffers from the stream can be immediately included in input requests.

If the HAL needs to change the stream configuration for an existing stream due to the new configuration, it may rewrite the values of usage and/or max_buffers during the configure call. The framework will detect such a change, and will then reallocate the stream buffers, and call register_stream_buffers() again before using buffers from that stream in a request.

If a currently-active stream is not included in stream_list, the HAL may safely remove any references to that stream. It will not be reused in a later configure() call by the framework, and all the gralloc buffers for it will be freed after the configure_streams() call returns.

The stream_list structure is owned by the framework, and may not be accessed once this call completes. The address of an individual camera3_stream_t structure will remain valid for access by the HAL until the end of the first configure_stream() call which no longer includes that camera3_stream_t in the stream_list argument. The HAL may not change values in the stream structure outside of the private pointer, except for the usage and max_buffers members during the configure_streams() call itself.

If the stream is new, the usage, max_buffer, and private pointer fields of the stream structure will all be set to 0. The HAL device must set these fields before the configure_streams() call returns. These fields are then used by the framework and the platform gralloc module to allocate the gralloc buffers for each stream.

Before such a new stream can have its buffers included in a capture request, the framework will call register_stream_buffers() with that stream. However, the framework is not required to register buffers for all streams before submitting a request. This allows for quick startup of (for example) a preview stream, with allocation for other streams happening later or concurrently.


The framework will only call this method when no captures are being processed. That is, all results have been returned to the framework, and all in-flight input and output buffers have been returned and their release sync fences have been signaled by the HAL. The framework will not submit new requests for capture while the configure_streams() call is underway.


The HAL device must configure itself to provide maximum possible output frame rate given the sizes and formats of the output streams, as documented in the camera device's static metadata.

Performance expectations:

This call is expected to be heavyweight and possibly take several hundred milliseconds to complete, since it may require resetting and reconfiguring the image sensor and the camera processing pipeline. Nevertheless, the HAL device should attempt to minimize the reconfiguration delay to minimize the user-visible pauses during application operational mode changes (such as switching from still capture to video recording).

Return values:

0: On successful stream configuration

-EINVAL: If the requested stream configuration is invalid. Some examples of invalid stream configurations include:

  • Including more than 1 input-capable stream (INPUT or BIDIRECTIONAL)
  • Not including any output-capable streams (OUTPUT or BIDIRECTIONAL)
  • Including streams with unsupported formats, or an unsupported size for that format.
  • Including too many output streams of a certain format.

Note that the framework submitting an invalid stream configuration is not normal operation, since stream configurations are checked before configure. An invalid configuration means that a bug exists in the framework code, or there is a mismatch between the HAL's static metadata and the requirements on streams.

-ENODEV: If there has been a fatal error and the device is no longer operational. Only close() can be called successfully by the framework after this error is returned.

Definition at line 1930 of file camera3.h.

const camera_metadata_t*(* construct_default_request_settings)(const struct camera3_device *, int type)


Create capture settings for standard camera use cases.

The device must return a settings buffer that is configured to meet the requested use case, which must be one of the CAMERA3_TEMPLATE_* enums. All request control fields must be included.

The HAL retains ownership of this structure, but the pointer to the structure must be valid until the device is closed. The framework and the HAL may not modify the buffer once it is returned by this call. The same buffer may be returned for subsequent calls for the same template, or for other templates.

Return values:

Valid metadata: On successful creation of a default settings buffer.

NULL: In case of a fatal error. After this is returned, only the close() method can be called successfully by the framework.

Definition at line 2004 of file camera3.h.

void(* dump)(const struct camera3_device *, int fd)


Print out debugging state for the camera device. This will be called by the framework when the camera service is asked for a debug dump, which happens when using the dumpsys tool, or when capturing a bugreport.

The passed-in file descriptor can be used to write debugging text using dprintf() or write(). The text should be in ASCII encoding only.

Definition at line 2088 of file camera3.h.

int(* flush)(const struct camera3_device *)


Flush all currently in-process captures and all buffers in the pipeline on the given device. The framework will use this to dump all state as quickly as possible in order to prepare for a configure_streams() call.

No buffers are required to be successfully returned, so every buffer held at the time of flush() (whether sucessfully filled or not) may be returned with CAMERA3_BUFFER_STATUS_ERROR. Note the HAL is still allowed to return valid (STATUS_OK) buffers during this call, provided they are succesfully filled.

All requests currently in the HAL are expected to be returned as soon as possible. Not-in-process requests should return errors immediately. Any interruptible hardware blocks should be stopped, and any uninterruptible blocks should be waited on.

flush() should only return when there are no more outstanding buffers or requests left in the HAL. The framework may call configure_streams (as the HAL state is now quiesced) or may issue new requests.

A flush() call should only take 100ms or less. The maximum time it can take is 1 second.

Version information:

only available if device version >= CAMERA_DEVICE_API_VERSION_3_1.

Return values:

0: On a successful flush of the camera HAL.

-EINVAL: If the input is malformed (the device is not valid).

-ENODEV: If the camera device has encountered a serious error. After this error is returned, only the close() method can be successfully called by the framework.

Definition at line 2129 of file camera3.h.

void(* get_metadata_vendor_tag_ops)(const struct camera3_device *, vendor_tag_query_ops_t *ops)


Get methods to query for vendor extension metadata tag information. The HAL should fill in all the vendor tag operation methods, or leave ops unchanged if no vendor tags are defined.

The definition of vendor_tag_query_ops_t can be found in system/media/camera/include/system/camera_metadata.h.

Definition at line 2075 of file camera3.h.

int(* initialize)(const struct camera3_device *, const camera3_callback_ops_t *callback_ops)


One-time initialization to pass framework callback function pointers to the HAL. Will be called once after a successful open() call, before any other functions are called on the camera3_device_ops structure.

Return values:

0: On successful initialization

-ENODEV: If initialization fails. Only close() can be called successfully by the framework after this.

Definition at line 1816 of file camera3.h.

int(* process_capture_request)(const struct camera3_device *, camera3_capture_request_t *request)


Send a new capture request to the HAL. The HAL should not return from this call until it is ready to accept the next request to process. Only one call to process_capture_request() will be made at a time by the framework, and the calls will all be from the same thread. The next call to process_capture_request() will be made as soon as a new request and its associated buffers are available. In a normal preview scenario, this means the function will be called again by the framework almost instantly.

The actual request processing is asynchronous, with the results of capture being returned by the HAL through the process_capture_result() call. This call requires the result metadata to be available, but output buffers may simply provide sync fences to wait on. Multiple requests are expected to be in flight at once, to maintain full output frame rate.

The framework retains ownership of the request structure. It is only guaranteed to be valid during this call. The HAL device must make copies of the information it needs to retain for the capture processing. The HAL is responsible for waiting on and closing the buffers' fences and returning the buffer handles to the framework.

The HAL must write the file descriptor for the input buffer's release sync fence into input_buffer->release_fence, if input_buffer is not NULL. If the HAL returns -1 for the input buffer release sync fence, the framework is free to immediately reuse the input buffer. Otherwise, the framework will wait on the sync fence before refilling and reusing the input buffer.

Return values:

0: On a successful start to processing the capture request

-EINVAL: If the input is malformed (the settings are NULL when not allowed, there are 0 output buffers, etc) and capture processing cannot start. Failures during request processing should be handled by calling camera3_callback_ops_t.notify(). In case of this error, the framework will retain responsibility for the stream buffers' fences and the buffer handles; the HAL should not close the fences or return these buffers with process_capture_result.

-ENODEV: If the camera device has encountered a serious error. After this error is returned, only the close() method can be successfully called by the framework.

Definition at line 2057 of file camera3.h.

int(* register_stream_buffers)(const struct camera3_device *, const camera3_stream_buffer_set_t *buffer_set)


Register buffers for a given stream with the HAL device. This method is called by the framework after a new stream is defined by configure_streams, and before buffers from that stream are included in a capture request. If the same stream is listed in a subsequent configure_streams() call, register_stream_buffers will not be called again for that stream.

The framework does not need to register buffers for all configured streams before it submits the first capture request. This allows quick startup for preview (or similar use cases) while other streams are still being allocated.

This method is intended to allow the HAL device to map or otherwise prepare the buffers for later use. The buffers passed in will already be locked for use. At the end of the call, all the buffers must be ready to be returned to the stream. The buffer_set argument is only valid for the duration of this call.

If the stream format was set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, the camera HAL should inspect the passed-in buffers here to determine any platform-private pixel format information.

Return values:

0: On successful registration of the new stream buffers

-EINVAL: If the stream_buffer_set does not refer to a valid active stream, or if the buffers array is invalid.

-ENOMEM: If there was a failure in registering the buffers. The framework must consider all the stream buffers to be unregistered, and can try to register again later.

-ENODEV: If there is a fatal error, and the device is no longer operational. Only close() can be called successfully by the framework after this error is returned.

Definition at line 1973 of file camera3.h.

void* reserved[8]

Definition at line 2132 of file camera3.h.

The documentation for this struct was generated from the following file: