diff options
Diffstat (limited to 'en/devices/camera/camera3_requests_methods.html')
| -rw-r--r-- | en/devices/camera/camera3_requests_methods.html | 134 |
1 files changed, 67 insertions, 67 deletions
diff --git a/en/devices/camera/camera3_requests_methods.html b/en/devices/camera/camera3_requests_methods.html index d75376f3..55c0db6b 100644 --- a/en/devices/camera/camera3_requests_methods.html +++ b/en/devices/camera/camera3_requests_methods.html @@ -25,94 +25,94 @@ <h2 id="request-creation">Request creation and submission</h2> <h3 id="default-settings">construct_default_request_settings</h3> -<p>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.<br/> - 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 +<p>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 <code>CAMERA3_TEMPLATE_*</code> enums. All request control fields must be + included.</p> +<p>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.</p> <h4><strong>Return values</strong></h4> <ul> <li>Valid metadata: On successful creation of a default settings buffer.</li> - <li>NULL: In case of a fatal error. After this is returned, only the close() + <li><code>NULL</code>: In case of a fatal error. After this is returned, only the <code>close()</code> method can be called successfully by the framework.</li> </ul> <h3 id="process-request">process_capture_request</h3> -<p>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.<br/> - 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.<br/> - 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.<br/> - 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 +<p>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 + <code>process_capture_request()</code> will be made at a time by the framework, and the calls + will all be from the same thread. The next call to <code>process_capture_request()</code> + 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.</p> +<p>The actual request processing is asynchronous, with the results of capture being +returned by the HAL through the <code>process_capture_result()</code> 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.</p> +<p>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.</p> + The HAL must write the file descriptor for the input buffer's release sync fence + into <code>input_buffer</code>-><code>release_fence</code>, if <code>input_buffer</code> is not <code>NULL</code>. If the HAL + returns <code>-1</code> 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.</p> <h4><strong>Return values</strong></h4> <ul> - <li>0: On a successful start to processing the capture request</li> - <li>-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.</li> - <li>-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 + <li><code>0</code>: On a successful start to processing the capture request</li> + <li><code>-EINVAL</code>: If the input is malformed (the settings are <code>NULL</code> when not allowed, + there are 0 output buffers, etc) and capture processing cannot start. Failures + during request processing should be handled by calling + <code>camera3_callback_ops_t.notify()</code>. 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 + <code>process_capture_result</code>.</li> + <li><code>-ENODEV</code>: If the camera device has encountered a serious error. After this + error is returned, only the <code>close()</code> method can be successfully called by the framework.</li> </ul> <h2 id="misc-methods">Miscellaneous methods</h2> <h3 id="get-metadata">get_metadata_vendor_tag_ops</h3> -<p>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.</p> +<p>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 <code>vendor_tag_query_ops_t</code> can be + found in <code>system/media/camera/include/system/camera_metadata.h</code>.</p> <h3 id="dump">dump</h3> -<p>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 +<p>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 <code>dprintf()</code> or <code>write()</code>. The text should be in ASCII encoding only.</p> <h3 id="flush">flush</h3> -<p>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.<br/> - 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 - (STATUS_OK) buffers during this call, provided they are successfully filled.<br/> - 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.<br/> - 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.<br/> - A flush() call should only take 100ms or less. The maximum time it can take is 1 +<p>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 <code>configure_streams()</code> call.</p> +<p>No buffers are required to be successfully returned, so every buffer held at the +time of <code>flush()</code> (whether successfully filled or not) may be returned with +<code>CAMERA3_BUFFER_STATUS_ERROR</code>. Note the HAL is still allowed to return valid +(<code>STATUS_OK</code>) buffers during this call, provided they are successfully filled.</p> +<p>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.</p> +<p><code>flush()</code> should only return when there are no more outstanding buffers or +requests left in the HAL. The framework may call <code>configure_streams</code> (as the HAL + state is now quiesced) or may issue new requests.</p> +<p>A <code>flush()</code> call should only take 100ms or less. The maximum time it can take is 1 second.</p> <h4><strong>Version information</strong></h4> -<p>This is available only if device version >= CAMERA_DEVICE_API_VERSION_3_1.</p> +<p>This is available only if device version >= <code>CAMERA_DEVICE_API_VERSION_3_1</code>.</p> <h4><strong>Return values</strong></h4> <ul> - <li>0: On a successful flush of the camera HAL.</li> - <li>-EINVAL: If the input is malformed (the device is not valid).</li> - <li>-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 + <li><code>0</code>: On a successful flush of the camera HAL.</li> + <li><code>-EINVAL</code>: If the input is malformed (the device is not valid).</li> + <li><code>-ENODEV</code>: If the camera device has encountered a serious error. After this + error is returned, only the <code>close()</code> method can be successfully called by the framework.</li> </ul> |