camera3_capture_result Struct Reference
#include <
camera3.h
>
Data Fields |
|
| uint32_t | frame_number |
| const camera_metadata_t * | result |
| uint32_t | num_output_buffers |
| const camera3_stream_buffer_t * | output_buffers |
| const camera3_stream_buffer_t * | input_buffer |
| uint32_t | partial_result |
Detailed Description
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.
Field Documentation
| uint32_t frame_number |
The frame number is an incrementing integer set by the framework in the submitted request to uniquely identify this capture. It is also used to identify the request in asynchronous notifications sent to camera3_callback_ops_t.notify() .
| const camera3_stream_buffer_t * input_buffer |
>= CAMERA_DEVICE_API_VERSION_3_2:
The handle for the input stream buffer for this capture. It may not yet be consumed at the time the HAL calls process_capture_result(); the framework will wait on the release sync fences provided by the HAL before reusing the buffer.
The HAL should handle the sync fences the same way they are done for output_buffers.
Only one input buffer is allowed to be sent per request. Similarly to output buffers, the ordering of returned input buffers must be maintained by the HAL.
Performance considerations:
The input buffer should be returned as early as possible. If the HAL supports sync fences, it can call process_capture_result to hand it back with sync fences being set appropriately. If the sync fences are not supported, the buffer can only be returned when it is consumed, which may take long time; the HAL may choose to copy this input buffer to make the buffer return sooner.
| uint32_t num_output_buffers |
The number of output buffers returned in this result structure. Must be less than or equal to the matching capture request's count. If this is less than the buffer count in the capture request, at least one more call to process_capture_result with the same frame_number must be made, to return the remaining output buffers to the framework. This may only be zero if the structure includes valid result metadata or an input buffer is returned in this result.
| const camera3_stream_buffer_t * output_buffers |
The handles for the output stream buffers for this capture. They may not yet be filled at the time the HAL calls process_capture_result(); the framework will wait on the release sync fences provided by the HAL before reading the buffers.
The HAL must set the stream buffer's release sync fence to a valid sync fd, or to -1 if the buffer has already been filled.
If the HAL encounters an error while processing the buffer, and the buffer is not filled, the buffer's status field must be set to CAMERA3_BUFFER_STATUS_ERROR. If the HAL did not wait on the acquire fence before encountering the error, the acquire fence should be copied into the release fence, to allow the framework to wait on the fence before reusing the buffer.
The acquire fence must be set to -1 for all output buffers. If num_output_buffers is zero, this may be NULL. In that case, at least one more process_capture_result call must be made by the HAL to provide the output buffers.
When process_capture_result is called with a new buffer for a frame, all previous frames' buffers for that corresponding stream must have been already delivered (the fences need not have yet been signaled).
>= CAMERA_DEVICE_API_VERSION_3_2:
Gralloc buffers for a frame may be sent to framework before the corresponding SHUTTER-notify.
Performance considerations:
Buffers delivered to the framework will not be dispatched to the application layer until a start of exposure timestamp has been received via a SHUTTER notify() call. It is highly recommended to dispatch that call as early as possible.
| uint32_t partial_result |
>= CAMERA_DEVICE_API_VERSION_3_2:
In order to take advantage of partial results, the HAL must set the static metadata android.request.partialResultCount to the number of partial results it will send for each frame.
Each new capture result with a partial result must set this field (partial_result) to a distinct inclusive value between 1 and android.request.partialResultCount.
HALs not wishing to take advantage of this feature must not set an android.request.partialResultCount or partial_result to a value other than 1.
This value must be set to 0 when a capture result contains buffers only and no metadata.
| const camera_metadata_t * result |
The result metadata for this capture. This contains information about the final capture parameters, the state of the capture and post-processing hardware, the state of the 3A algorithms, if enabled, and the output of any enabled statistics units.
Only one call to process_capture_result() with a given frame_number may include the result metadata. All other calls for the same frame_number must set this to NULL.
If there was an error producing the result metadata, result must be an empty metadata buffer, and notify() must be called with ERROR_RESULT.
>= CAMERA_DEVICE_API_VERSION_3_2:
Multiple calls to process_capture_result() with a given frame_number may include the result metadata.
Partial metadata submitted should not include any metadata key returned in a previous partial result for a given frame. Each new partial result for that frame must also set a distinct partial_result value.
If notify has been called with ERROR_RESULT, all further partial results for that frame are ignored by the framework.
The documentation for this struct was generated from the following file:
- hardware/libhardware/include/hardware/ camera3.h