1 <html devsite> 2 <head> 3 <title>Request creation and submission</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 26 <h2 id="request-creation">Request creation and submission</h2> 27 <h3 id="default-settings">construct_default_request_settings</h3> 28 <p>Create capture settings for standard camera use cases. The device must return a 29 settings buffer that is configured to meet the requested use case, which must be 30 one of the <code>CAMERA3_TEMPLATE_*</code> enums. All request control fields must be 31 included.</p> 32 <p>The HAL retains ownership of this structure, but the pointer to the structure 33 must be valid until the device is closed. The framework and the HAL may not 34 modify the buffer once it is returned by this call. The same buffer may be 35 returned for subsequent calls for the same template, or for other templates.</p> 36 <h4><strong>Return values</strong></h4> 37 <ul> 38 <li>Valid metadata: On successful creation of a default settings buffer.</li> 39 <li><code>NULL</code>: In case of a fatal error. After this is returned, only the <code>close()</code> 40 method can be called successfully by the framework.</li> 41 </ul> 42 <h3 id="process-request">process_capture_request</h3> 43 <p>Send a new capture request to the HAL. The HAL should not return from this call 44 until it is ready to accept the next request to process. Only one call to 45 <code>process_capture_request()</code> will be made at a time by the framework, and the calls 46 will all be from the same thread. The next call to <code>process_capture_request()</code> 47 will be made as soon as a new request and its associated buffers are available. 48 In a normal preview scenario, this means the function will be called again by 49 the framework almost instantly.</p> 50 <p>The actual request processing is asynchronous, with the results of capture being 51 returned by the HAL through the <code>process_capture_result()</code> call. This call 52 requires the result metadata to be available, but output buffers may simply 53 provide sync fences to wait on. Multiple requests are expected to be in flight 54 at once, to maintain full output frame rate.</p> 55 <p>The framework retains ownership of the request structure. It is only guaranteed 56 to be valid during this call. The HAL device must make copies of the information 57 it needs to retain for the capture processing. The HAL is responsible for 58 waiting on and closing the buffers' fences and returning the buffer handles to 59 the framework.</p> 60 <p>The HAL must write the file descriptor for the input buffer's release sync fence 61 into <code>input_buffer</code>-><code>release_fence</code>, if <code>input_buffer</code> is not <code>NULL</code>. If the HAL 62 returns <code>-1</code> for the input buffer release sync fence, the framework is free to 63 immediately reuse the input buffer. Otherwise, the framework will wait on the 64 sync fence before refilling and reusing the input buffer.</p> 65 <h4><strong>Return values</strong></h4> 66 <ul> 67 <li><code>0</code>: On a successful start to processing the capture request</li> 68 <li><code>-EINVAL</code>: If the input is malformed (the settings are <code>NULL</code> when not allowed, 69 there are 0 output buffers, etc) and capture processing cannot start. Failures 70 during request processing should be handled by calling 71 <code>camera3_callback_ops_t.notify()</code>. In case of this error, the framework will 72 retain responsibility for the stream buffers' fences and the buffer handles; 73 the HAL should not close the fences or return these buffers with 74 <code>process_capture_result</code>.</li> 75 <li><code>-ENODEV</code>: If the camera device has encountered a serious error. After this 76 error is returned, only the <code>close()</code> method can be successfully called by the 77 framework.</li> 78 </ul> 79 <h2 id="misc-methods">Miscellaneous methods</h2> 80 <h3 id="get-metadata">get_metadata_vendor_tag_ops</h3> 81 <p>Get methods to query for vendor extension metadata tag information. The HAL 82 should fill in all the vendor tag operation methods, or leave ops unchanged if 83 no vendor tags are defined. The definition of <code>vendor_tag_query_ops_t</code> can be 84 found in <code>system/media/camera/include/system/camera_metadata.h</code>.</p> 85 <h3 id="dump">dump</h3> 86 <p>Print out debugging state for the camera device. This will be called by the 87 framework when the camera service is asked for a debug dump, which happens when 88 using the dumpsys tool, or when capturing a bugreport. The passed-in file 89 descriptor can be used to write debugging text using <code>dprintf()</code> or <code>write()</code>. The 90 text should be in ASCII encoding only.</p> 91 <h3 id="flush">flush</h3> 92 <p>Flush all currently in-process captures and all buffers in the pipeline on the 93 given device. The framework will use this to dump all state as quickly as 94 possible in order to prepare for a <code>configure_streams()</code> call.</p> 95 <p>No buffers are required to be successfully returned, so every buffer held at the 96 time of <code>flush()</code> (whether successfully filled or not) may be returned with 97 <code>CAMERA3_BUFFER_STATUS_ERROR</code>. Note the HAL is still allowed to return valid 98 (<code>STATUS_OK</code>) buffers during this call, provided they are successfully filled.</p> 99 <p>All requests currently in the HAL are expected to be returned as soon as 100 possible. Not-in-process requests should return errors immediately. Any 101 interruptible hardware blocks should be stopped, and any uninterruptible blocks 102 should be waited on.</p> 103 <p><code>flush()</code> should only return when there are no more outstanding buffers or 104 requests left in the HAL. The framework may call <code>configure_streams</code> (as the HAL 105 state is now quiesced) or may issue new requests.</p> 106 <p>A <code>flush()</code> call should only take 100ms or less. The maximum time it can take is 1 107 second.</p> 108 <h4><strong>Version information</strong></h4> 109 <p>This is available only if device version >= <code>CAMERA_DEVICE_API_VERSION_3_1</code>.</p> 110 <h4><strong>Return values</strong></h4> 111 <ul> 112 <li><code>0</code>: On a successful flush of the camera HAL.</li> 113 <li><code>-EINVAL</code>: If the input is malformed (the device is not valid).</li> 114 <li><code>-ENODEV</code>: If the camera device has encountered a serious error. After this 115 error is returned, only the <code>close()</code> method can be successfully called by the 116 framework.</li> 117 </ul> 118 119 </body> 120 </html> 121
