camera3_device_ops Struct Reference

configure_streams:

CAMERA_DEVICE_API_VERSION_3_0 only:

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.

---

CAMERA_DEVICE_API_VERSION_3_1 only:

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, max_buffer, and private pointer fields of the stream structure will all be set to 0. The usage will be set to the consumer usage flags. 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.

---

>= CAMERA_DEVICE_API_VERSION_3_2:

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 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 may then reallocate the stream buffers 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, max_buffer, and private pointer fields of the stream structure will all be set to 0. The usage will be set to the consumer usage flags. 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.

Newly allocated buffers may be included in a capture request at any time by the framework. Once a gralloc buffer is returned to the framework with process_capture_result (and its respective release_fence has been signaled) the framework may free or reuse it at any time.

---

Preconditions:

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.

Postconditions:

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 requirements:

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

The HAL should return from this call in 500ms, and must return from this call in 1000ms.

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.
• Unsupported rotation configuration (only applies to devices with version >= CAMERA_DEVICE_API_VERSION_3_3)
• Stream sizes/formats don't satisfy the camera3_stream_configuration_t->operation_mode requirements for non-NORMAL mode, or the requested operation_mode is not supported by the HAL. (only applies to devices with version >= CAMERA_DEVICE_API_VERSION_3_3)

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

construct_default_request_settings:

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.

Performance requirements:

This should be a non-blocking call. The HAL should return from this call in 1ms, and must return from this call in 5ms.

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

dump:

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.

Performance requirements:

This must be a non-blocking call. The HAL should return from this call in 1ms, must return from this call in 10ms. This call must avoid deadlocks, as it may be called at any point during camera operation. Any synchronization primitives used (such as mutex locks or semaphores) should be acquired with a timeout.

Definition at line 2971 of file camera3.h .

flush:

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 successfully filled or not) may be returned with CAMERA3_BUFFER_STATUS_ERROR. Note the HAL is still allowed to return valid (CAMERA3_BUFFER_STATUS_OK) buffers during this call, provided they are successfully 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() may be called concurrently to process_capture_request() , with the expectation that process_capture_request will return quickly and the request submitted in that process_capture_request call is treated like all other in-flight requests. Due to concurrency issues, it is possible that from the HAL's point of view, a process_capture_request() call may be started after flush has been invoked but has not returned yet. If such a call happens before flush() returns, the HAL should treat the new capture request like other in-flight pending requests (see #4 below).

More specifically, the HAL must follow below requirements for various cases:

1. For captures that are too late for the HAL to cancel/stop, and will be completed normally by the HAL; i.e. the HAL can send shutter/notify and process_capture_result and buffers as normal.
2. For pending requests that have not done any processing, the HAL must call notify CAMERA3_MSG_ERROR_REQUEST, and return all the output buffers with process_capture_result in the error state (CAMERA3_BUFFER_STATUS_ERROR). The HAL must not place the release fence into an error state, instead, the release fences must be set to the acquire fences passed by the framework, or -1 if they have been waited on by the HAL already. This is also the path to follow for any captures for which the HAL already called notify() with CAMERA3_MSG_SHUTTER but won't be producing any metadata/valid buffers for. After CAMERA3_MSG_ERROR_REQUEST, for a given frame, only process_capture_results with buffers in CAMERA3_BUFFER_STATUS_ERROR are allowed. No further notifys or process_capture_result with non-null metadata is allowed.

3. For partially completed pending requests that will not have all the output buffers or perhaps missing metadata, the HAL should follow below:

   3.1. Call notify with CAMERA3_MSG_ERROR_RESULT if some of the expected result metadata (i.e. one or more partial metadata) won't be available for the capture.

   3.2. Call notify with CAMERA3_MSG_ERROR_BUFFER for every buffer that won't be produced for the capture.

   3.3 Call notify with CAMERA3_MSG_SHUTTER with the capture timestamp before any buffers/metadata are returned with process_capture_result.

   3.4 For captures that will produce some results, the HAL must not call CAMERA3_MSG_ERROR_REQUEST, since that indicates complete failure.

   3.5. Valid buffers/metadata should be passed to the framework as normal.

   3.6. Failed buffers should be returned to the framework as described for case 2. But failed buffers do not have to follow the strict ordering valid buffers do, and may be out-of-order with respect to valid buffers. For example, if buffers A, B, C, D, E are sent, D and E are failed, then A, E, B, D, C is an acceptable return order.

   3.7. For fully-missing metadata, calling CAMERA3_MSG_ERROR_RESULT is sufficient, no need to call process_capture_result with NULL metadata or equivalent.

4. If a flush() is invoked while a process_capture_request() invocation is active, that process call should return as soon as possible. In addition, if a process_capture_request() call is made after flush() has been invoked but before flush() has returned, the capture request provided by the late process_capture_request call should be treated like a pending request in case #2 above.

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.

Note that it's sufficient to only support fully-succeeded and fully-failed result cases. However, it is highly desirable to support the partial failure cases as well, as it could help improve the flush call overall performance.

Performance requirements:

The HAL should return from this call in 100ms, and must return from this call in 1000ms. And this call must not be blocked longer than pipeline latency (see S7 for definition).

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

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

>= CAMERA_DEVICE_API_VERSION_3_2: DEPRECATED. This function has been deprecated and should be set to NULL by the HAL. Please implement get_vendor_tag_ops in camera_common.h instead.

Definition at line 2950 of file camera3.h .

initialize:

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.

Performance requirements:

This should be a non-blocking call. The HAL should return from this call in 5ms, and must return from this call in 10ms.

Return values:

0: On successful initialization

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

Definition at line 2530 of file camera3.h .

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

>= CAMERA_DEVICE_API_VERSION_3_2:

The input/output buffers provided by the framework in each request may be brand new (having never before seen by the HAL).

---

Performance considerations:

Handling a new buffer should be extremely lightweight and there should be no frame rate degradation or frame jitter introduced.

This call must return fast enough to ensure that the requested frame rate can be sustained, especially for streaming cases (post-processing quality settings set to FAST). The HAL should return this call in 1 frame interval, and must return from this call in 4 frame intervals.

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

register_stream_buffers:

>= CAMERA_DEVICE_API_VERSION_3_2:

DEPRECATED. This will not be called and must be set to NULL.

<= CAMERA_DEVICE_API_VERSION_3_1:

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.

Performance requirements:

This should be a non-blocking call. The HAL should return from this call in 1ms, and must return from this call in 5ms.

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

Definition at line 3080 of file camera3.h .