| <html devsite> |
| <head> |
| <title>Request creation and submission</title> |
| <meta name="project_path" value="/_project.yaml" /> |
| <meta name="book_path" value="/_book.yaml" /> |
| </head> |
| <body> |
| <!-- |
| Copyright 2017 The Android Open Source Project |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| |
| |
| <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 <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><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 |
| <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> |
| <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><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 <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 <code>dumpsys</code> 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 <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 >= <code>CAMERA_DEVICE_API_VERSION_3_1</code>.</p> |
| <h4><strong>Return values</strong></h4> |
| <ul> |
| <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> |
| |
| </body> |
| </html> |