diff options
Diffstat (limited to 'en/devices/camera/camera3_error_stream.html')
| -rw-r--r-- | en/devices/camera/camera3_error_stream.html | 204 |
1 files changed, 102 insertions, 102 deletions
diff --git a/en/devices/camera/camera3_error_stream.html b/en/devices/camera/camera3_error_stream.html index 68b83a68..aebb325c 100644 --- a/en/devices/camera/camera3_error_stream.html +++ b/en/devices/camera/camera3_error_stream.html @@ -24,137 +24,137 @@ <h2 id="error-mgmt">Error management</h2> -<p>Camera HAL device ops functions that have a return value will all return -ENODEV - / NULL in case of a serious error. This means the device cannot continue - operation, and must be closed by the framework. Once this error is returned by - some method, or if notify() is called with ERROR_DEVICE, only the close() method - can be called successfully. All other methods will return -ENODEV / NULL.<br/> - If a device op is called in the wrong sequence, for example if the framework - calls configure_streams() is called before initialize(), the device must return - -ENOSYS from the call, and do nothing.<br/> - Transient errors in image capture must be reported through notify() as follows:</p> +<p>Camera HAL device ops functions that have a return value will all return <code>-ENODEV + / NULL</code> in case of a serious error. This means the device cannot continue + operation and must be closed by the framework. Once this error is returned by + some method, or if <code>notify()</code> is called with <code>ERROR_DEVICE</code>, only the <code>close()</code> method + can be called successfully. All other methods will return <code>-ENODEV / NULL</code>.</p> +<p>If a device op is called in the wrong sequence, for example if the framework +calls <code>configure_streams()</code> before <code>initialize()</code>, the device must return +<code>-ENOSYS</code> from the call, and do nothing.</p> +<p>Transient errors in image capture must be reported through <code>notify()</code> as follows:</p> <ul> - <li>The failure of an entire capture to occur must be reported by the HAL by - calling notify() with ERROR_REQUEST. Individual errors for the result metadata + <li>The failure of an entire capture to occur must be reported by the HAL by + calling <code>notify()</codE> with <code>ERROR_REQUEST</code>. Individual errors for the result metadata or the output buffers must not be reported in this case.</li> - <li>If the metadata for a capture cannot be produced, but some image buffers were - filled, the HAL must call notify() with ERROR_RESULT.</li> - <li>If an output image buffer could not be filled, but either the metadata was - produced or some other buffers were filled, the HAL must call notify() with - ERROR_BUFFER for each failed buffer.</li> + <li>If the metadata for a capture cannot be produced, but some image buffers were + filled, the HAL must call <code>notify()</code> with <code>ERROR_RESULT</code>.</li> + <li>If an output image buffer could not be filled, but either the metadata was + produced or some other buffers were filled, the HAL must call <code>notify()</code> with + <code>ERROR_BUFFER</code> for each failed buffer.</li> </ul> -<p>In each of these transient failure cases, the HAL must still call - process_capture_result, with valid output buffer_handle_t. If the result - metadata could not be produced, it should be NULL. If some buffers could not be - filled, their sync fences must be set to the error state.<br/> - Invalid input arguments result in -EINVAL from the appropriate methods. In that +<p>In each of these transient failure cases, the HAL must still call +<code>process_capture_result</code>, with valid output <code>buffer_handle_t</code>. If the result +metadata could not be produced, it should be <code>NULL</code>. If some buffers could not be + filled, their sync fences must be set to the error state.</p> +<p>Invalid input arguments result in <code>-EINVAL</code> from the appropriate methods. In that case, the framework must act as if that call had never been made.</p> <h2 id="stream-mgmt">Stream management</h2> <h3 id="configure_streams">configure_streams</h3> -<p>Reset the HAL camera device processing pipeline and set up new input and output - streams. This call replaces any existing stream configuration with the streams - defined in the stream_list. This method will be called at least once after - initialize() before a request is submitted with process_capture_request().<br/> - The stream_list must contain at least one output-capable stream, and may not - contain more than one input-capable stream.<br/> - The stream_list may contain streams that are also in the currently-active set of - streams (from the previous call to configure_stream()). These streams will - already have valid values for usage, maxbuffers, and the private pointer. If - such a stream has already had its buffers registered, register_stream_buffers() - will not be called again for the stream, and buffers from the stream can be - immediately included in input requests.<br/> - If the HAL needs to change the stream configuration for an existing stream due - to the new configuration, it may rewrite the values of usage and/or maxbuffers - during the configure call. The framework will detect such a change, and will - then reallocate the stream buffers, and call register_stream_buffers() again - before using buffers from that stream in a request.<br/> - If a currently-active stream is not included in stream_list, the HAL may safely - remove any references to that stream. It will not be reused in a later - configure() call by the framework, and all the gralloc buffers for it will be - freed after the configure_streams() call returns.<br/> - The stream_list structure is owned by the framework, and may not be accessed - once this call completes. The address of an individual camera3streamt - structure will remain valid for access by the HAL until the end of the first - configure_stream() call which no longer includes that camera3streamt in the - stream_list argument. The HAL may not change values in the stream structure - outside of the private pointer, except for the usage and maxbuffers members - during the configure_streams() call itself.<br/> - If the stream is new, the usage, maxbuffer, and private pointer fields of the - stream structure will all be set to 0. The HAL device must set these fields - before the configure_streams() call returns. These fields are then used by the - framework and the platform gralloc module to allocate the gralloc buffers for - each stream.<br/> - Before such a new stream can have its buffers included in a capture request, the - framework will call register_stream_buffers() with that stream. However, the - framework is not required to register buffers for _all streams before - submitting a request. This allows for quick startup of (for example) a preview +<p>Reset the HAL camera device processing pipeline and set up new input and output + streams. This call replaces any existing stream configuration with the streams + defined in the <code>stream_list</code>. This method will be called at least once after + <code>initialize()</code> before a request is submitted with <code>process_capture_request()</code>.</p> +<p>The <code>stream_list</code> must contain at least one output-capable stream, and may not + contain more than one input-capable stream. + The <code>stream_list</code> may contain streams that are also in the currently-active set of + streams (from the previous call to <code>configure_stream()</code>). These streams will + already have valid values for usage, maxbuffers, and the private pointer. If + such a stream has already had its buffers registered, <code>register_stream_buffers()</code> + will not be called again for the stream, and buffers from the stream can be + immediately included in input requests.</p> +<p>If the HAL needs to change the stream configuration for an existing stream due + to the new configuration, it may rewrite the values of usage and/or maxbuffers + during the configure call. The framework will detect such a change, and will + then reallocate the stream buffers, and call <code>register_stream_buffers()</code> again + before using buffers from that stream in a request.</p> +<p>If a currently-active stream is not included in <code>stream_list</code>, the HAL may safely + remove any references to that stream. It will not be reused in a later + <code>configure()</code> call by the framework, and all the gralloc buffers for it will be + freed after the <code>configure_streams()</code> call returns.</p> +<p>The <code>stream_list</code> structure is owned by the framework, and may not be accessed +once this call completes. The address of an individual <code>camera3streamt</code> + structure will remain valid for access by the HAL until the end of the first + <code>configure_stream()</code> call which no longer includes that <code>camera3streamt</code> in the + <code>stream_list</code> argument. The HAL may not change values in the stream structure + outside of the private pointer, except for the usage and maxbuffers members + during the <code>configure_streams()</code> call itself.</p> +<p>If the stream is new, the usage, maxbuffer, and private pointer fields of the + stream structure will all be set to 0. The HAL device must set these fields + before the <code>configure_streams()</code> call returns. These fields are then used by the + framework and the platform gralloc module to allocate the gralloc buffers for + each stream.</p> +<p>Before such a new stream can have its buffers included in a capture request, the +framework will call <code>register_stream_buffers()</code> with that stream. However, the + framework is not required to register buffers for _all streams before + submitting a request. This allows for quick startup of (for example) a preview stream, with allocation for other streams happening later or concurrently.</p> <h4><strong>Preconditions</strong></h4> -<p>The framework will only call this method when no captures are being processed. - That is, all results have been returned to the framework, and all in-flight - input and output buffers have been returned and their release sync fences have - been signaled by the HAL. The framework will not submit new requests for capture - while the configure_streams() call is underway.</p> +<p>The framework will only call this method when no captures are being processed. + That is, all results have been returned to the framework, and all in-flight + input and output buffers have been returned and their release sync fences have + been signaled by the HAL. The framework will not submit new requests for capture + while the <code>configure_streams()</code> call is underway.</p> <h4><strong>Postconditions</strong></h4> -<p>The HAL device must configure itself to provide maximum possible output frame - rate given the sizes and formats of the output streams, as documented in the +<p>The HAL device must configure itself to provide maximum possible output frame + rate given the sizes and formats of the output streams, as documented in the camera device's static metadata.</p> <h4><strong>Performance expectations</strong></h4> -<p>This call is expected to be heavyweight and possibly take several hundred - milliseconds to complete, since it may require resetting and reconfiguring the - image sensor and the camera processing pipeline. Nevertheless, the HAL device - should attempt to minimize the reconfiguration delay to minimize the - user-visible pauses during application operational mode changes (such as +<p>This call is expected to be heavyweight and possibly take several hundred + milliseconds to complete, since it may require resetting and reconfiguring the + image sensor and the camera processing pipeline. Nevertheless, the HAL device + should attempt to minimize the reconfiguration delay to minimize the + user-visible pauses during application operational mode changes (such as switching from still capture to video recording).</p> <h4><strong>Return values</strong></h4> <ul> - <li>0: On successful stream configuration</li> - <li>undefined</li> - <li>-EINVAL: If the requested stream configuration is invalid. Some examples of + <li><code>0</code>: On successful stream configuration</li> + <li><code>undefined</code></li> + <li><code>-EINVAL</code>: If the requested stream configuration is invalid. Some examples of invalid stream configurations include: <ul> - <li>Including more than 1 input-capable stream (INPUT or BIDIRECTIONAL)</li> - <li>Not including any output-capable streams (OUTPUT or BIDIRECTIONAL)</li> - <li>Including streams with unsupported formats, or an unsupported size for + <li>Including more than 1 input-capable stream (<code>INPUT</code> or <code>BIDIRECTIONAL</code>)</li> + <li>Not including any output-capable streams (<code>OUTPUT</code> or <code>BIDIRECTIONAL</code>)</li> + <li>Including streams with unsupported formats, or an unsupported size for that format.</li> <li>Including too many output streams of a certain format.</li> - <li>Note that the framework submitting an invalid stream configuration is not - normal operation, since stream configurations are checked before - configure. An invalid configuration means that a bug exists in the - framework code, or there is a mismatch between the HAL's static metadata + <li>Note that the framework submitting an invalid stream configuration is not + normal operation, since stream configurations are checked before + configure. An invalid configuration means that a bug exists in the + framework code, or there is a mismatch between the HAL's static metadata and the requirements on streams.</li> </ul> </li> - <li>-ENODEV: If there has been a fatal error and the device is no longer - operational. Only close() can be called successfully by the framework after + <li><code>-ENODEV</code>: If there has been a fatal error and the device is no longer + operational. Only <code>close()</code> can be called successfully by the framework after this error is returned.</li> </ul> <h3 id="register-stream">register_stream_buffers</h3> -<p>Register buffers for a given stream with the HAL device. This method is called - by the framework after a new stream is defined by configure_streams, and before - buffers from that stream are included in a capture request. If the same stream - is listed in a subsequent configure_streams() call, register_stream_buffers will - not be called again for that stream.<br/> - The framework does not need to register buffers for all configured streams - before it submits the first capture request. This allows quick startup for - preview (or similar use cases) while other streams are still being allocated.<br/> - This method is intended to allow the HAL device to map or otherwise prepare the - buffers for later use. The buffers passed in will already be locked for use. At - the end of the call, all the buffers must be ready to be returned to the stream. - The bufferset argument is only valid for the duration of this call.<br/> - If the stream format was set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, the - camera HAL should inspect the passed-in buffers here to determine any +<p>Register buffers for a given stream with the HAL device. This method is called +by the framework after a new stream is defined by <code>configure_streams</code>, and before + buffers from that stream are included in a capture request. If the same stream + is listed in a subsequent <code>configure_streams()</code> call, <code>register_stream_buffers</code> will + not be called again for that stream.</p> +<p>The framework does not need to register buffers for all configured streams + before it submits the first capture request. This allows quick startup for + preview (or similar use cases) while other streams are still being allocated.</p> +<p>This method is intended to allow the HAL device to map or otherwise prepare the + buffers for later use. The buffers passed in will already be locked for use. At + the end of the call, all the buffers must be ready to be returned to the stream. + The bufferset argument is only valid for the duration of this call.</p> +<p>If the stream format was set to <code>HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED</code>, the + camera HAL should inspect the passed-in buffers here to determine any platform-private pixel format information.</p> <h4><strong>Return values</strong></h4> <ul> - <li>0: On successful registration of the new stream buffers</li> - <li>-EINVAL: If the streambufferset does not refer to a valid active stream, or + <li><code>0</code>: On successful registration of the new stream buffers</li> + <li><code>-EINVAL</code>: If the streambufferset does not refer to a valid active stream, or if the buffers array is invalid.</li> - <li>-ENOMEM: If there was a failure in registering the buffers. The framework must - consider all the stream buffers to be unregistered, and can try to register + <li><code>-ENOMEM</code>: If there was a failure in registering the buffers. The framework must + consider all the stream buffers to be unregistered, and can try to register again later.</li> - <li>-ENODEV: If there is a fatal error, and the device is no longer operational. - Only close() can be called successfully by the framework after this error is + <li><code>-ENODEV</code>: If there is a fatal error, and the device is no longer operational. + Only <code>close()</code> can be called successfully by the framework after this error is returned.</li> </ul> |