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