一文看懂Camera request、buffer、stream、surface关系 独家原创

目录

一、request vs buffer vs stream vs surface

二、数据结构定义及注释

camera3_capture_request_t

camera3_buffer_status_t

---

网上博客说一堆，看半小时结果说得不清不楚。本人习惯简明精要，几句话能解释清楚绝不说一堆。

一、request vs buffer vs stream vs surface

很简单嘛！看结构定义不就完了。

request是这个接口里的camera3_capture_request_t：

static int process_capture_request(const camera3_device_t *dev, camera3_capture_request_t *request)

写2个调用立马变得清楚：

request.input_buffer->stream

request.output_buffers[0]->stream

很简单，一个request只有最多一个input_buffer，至少一个output_buffer，看到input_buffer和output_buffers（复数）了嘛。一个buffer指向一个stream。当然，几个buffer可以指向一个stream，stream是有格式的，一种格式当然可以几个buffer，比如预览时候是需要几个buffer轮转的，这叫做队列。

至于surface，就是buffer载体，一个buffer一个surface。

二、数据结构定义及注释

我把定义贴上，加上简单明了的注释。

camera3_capture_request_t

/**
 * camera3_capture_request_t:
 *
 * A single request for image capture/buffer reprocessing, sent to the Camera
 * HAL device by the framework in process_capture_request().
 *
 * The request contains the settings to be used for this capture, and the set of
 * output buffers to write the resulting image data in. It may optionally
 * contain an input buffer, in which case the request is for reprocessing that
 * input buffer instead of capturing a new image with the camera sensor. The
 * capture is identified by the frame_number.
 *
 * In response, the camera HAL device must send a camera3_capture_result
 * structure asynchronously to the framework, using the process_capture_result()
 * callback.
 */
typedef struct camera3_capture_request {
    /**
     * The frame number is an incrementing integer set by the framework to
     * uniquely identify this capture. It needs to be returned in the result
     * call, and is also used to identify the request in asynchronous
     * notifications sent to camera3_callback_ops_t.notify().
     */
    uint32_t frame_number; // 本次capture的id，唯一

    /**
     * The settings buffer contains the capture and processing parameters for
     * the request. As a special case, a NULL settings buffer indicates that the
     * settings are identical to the most-recently submitted capture request. A
     * NULL buffer cannot be used as the first submitted request after a
     * configure_streams() call.
     * `
     */
    const camera_metadata_t *settings; // metadata设置，为null表示与上一次一致

    /**
     * The input stream buffer to use for this request, if any.
     *
     *
     * If input_buffer is NULL, then the request is for a new capture from the
     * imager. If input_buffer is valid, the request is for reprocessing the
     * image contained in input_buffer.
     *
     * In the latter case, the HAL must set the release_fence of the
     * input_buffer to a valid sync fence, or to -1 if the HAL does not support
     * sync, before process_capture_request() returns.
     *
     * The HAL is required to wait on the acquire sync fence of the input buffer
     * before accessing it.
     *
     * <= CAMERA_DEVICE_API_VERSION_3_1:
     *
     * Any input buffer included here will have been registered with the HAL
     * through register_stream_buffers() before its inclusion in a request.
     *
     * >= CAMERA_DEVICE_API_VERSION_3_2:
     *
     * The buffers will not have been pre-registered with the HAL.
     * Subsequent requests may reuse buffers, or provide entirely new buffers.
     */
    camera3_stream_buffer_t *input_buffer; // 如果非空，表示对这个input_buffer重处理

    /**
     * The number of output buffers for this capture request. Must be at least
     * 1.
     */
    uint32_t num_output_buffers; // >=1

    /**
     * An array of num_output_buffers stream buffers, to be filled with image
     * data from this capture/reprocess. The HAL must wait on the acquire fences
     * of each stream buffer before writing to them.
     *
     * The HAL takes ownership of the actual buffer_handle_t entries in
     * output_buffers; the framework does not access them until they are
     * returned in a camera3_capture_result_t.
     *
     * <= CAMERA_DEVICE_API_VERSION_3_1:
     *
     * All the buffers included  here will have been registered with the HAL
     * through register_stream_buffers() before their inclusion in a request.
     *
     * >= CAMERA_DEVICE_API_VERSION_3_2:
     *
     * Any or all of the buffers included here may be brand new in this
     * request (having never before seen by the HAL).
     */
    const camera3_stream_buffer_t *output_buffers; // n个output_buffer的array

    /**
     * <= CAMERA_DEVICE_API_VERISON_3_4:
     *
     *    Not defined and must not be accessed.
     *
     * >= CAMERA_DEVICE_API_VERSION_3_5:
     *    The number of physical camera settings to be applied. If 'num_physcam_settings'
     *    equals 0 or a physical device is not included, then Hal must decide the
     *    specific physical device settings based on the default 'settings'.
     */
    uint32_t num_physcam_settings; // 物理相机的setting数量

    /**
     * <= CAMERA_DEVICE_API_VERISON_3_4:
     *
     *    Not defined and must not be accessed.
     *
     * >= CAMERA_DEVICE_API_VERSION_3_5:
     *    The physical camera ids. The array will contain 'num_physcam_settings'
     *    camera id strings for all physical devices that have specific settings.
     *    In case some id is invalid, the process capture request must fail and return
     *    -EINVAL.
     */
    const char **physcam_id; // 物理相机id array

    /**
     * <= CAMERA_DEVICE_API_VERISON_3_4:
     *
     *    Not defined and must not be accessed.
     *
     * >= CAMERA_DEVICE_API_VERSION_3_5:
     *    The capture settings for the physical cameras. The array will contain
     *    'num_physcam_settings' settings for invididual physical devices. In
     *    case the settings at some particular index are empty, the process capture
     *    request must fail and return -EINVAL.
     */
    const camera_metadata_t **physcam_settings; // 物理相机setting array

#if defined(CAMX_ANDROID_API) && (CAMX_ANDROID_API >= 31) //Android-S or better

    /**
     * <= CAMERA_DEVICE_API_VERISON_3_6:
     *
     *    Not defined and must not be accessed.
     *
     * >= CAMERA_DEVICE_API_VERSION_3_7:
     * The width and height of the input buffer for this capture request.
     *
     * These fields will be [0, 0] if no input buffer exists in the capture
     * request.
     *
     * If the stream configuration contains an input stream and has the
     * multiResolutionInputImage flag set to true, the camera client may submit a
     * reprocessing request with input buffer size different than the
     * configured input stream size. In that case, the inputWith and inputHeight
     * fields will be the actual size of the input image.
     *
     * If the stream configuration contains an input stream and the
     * multiResolutionInputImage flag is false, the inputWidth and inputHeight must
     * match the input stream size.
     */
     uint32_t inputWidth;
     uint32_t inputHeight;
#endif
} camera3_capture_request_t;

camera3_buffer_status_t

/**
 * camera3_stream_buffer_t:
 *
 * A single buffer from a camera3 stream. It includes a handle to its parent
 * stream, the handle to the gralloc buffer itself, and sync fences
 *
 * The buffer does not specify whether it is to be used for input or output;
 * that is determined by its parent stream type and how the buffer is passed to
 * the HAL device.
 */
typedef struct camera3_stream_buffer {
    /**
     * The handle of the stream this buffer is associated with
     */
    camera3_stream_t *stream; // 这个buffer关联的stream的handle

    /**
     * The native handle to the buffer
     */
    buffer_handle_t *buffer; // 该buffer在不同进程中共享的handle

    /**
     * Current state of the buffer, one of the camera3_buffer_status_t
     * values. The framework will not pass buffers to the HAL that are in an
     * error state. In case a buffer could not be filled by the HAL, it must
     * have its status set to CAMERA3_BUFFER_STATUS_ERROR when returned to the
     * framework with process_capture_result().
     */
    int status; // buffer状态

    /**
     * The acquire sync fence for this buffer. The HAL must wait on this fence
     * fd before attempting to read from or write to this buffer.
     *
     * The framework may be set to -1 to indicate that no waiting is necessary
     * for this buffer.
     *
     * When the HAL returns an output buffer to the framework with
     * process_capture_result(), the acquire_fence must be set to -1. If the HAL
     * never waits on the acquire_fence due to an error in filling a buffer,
     * when calling process_capture_result() the HAL must set the release_fence
     * of the buffer to be the acquire_fence passed to it by the framework. This
     * will allow the framework to wait on the fence before reusing the buffer.
     *
     * For input buffers, the HAL must not change the acquire_fence field during
     * the process_capture_request() call.
     *
     * >= CAMERA_DEVICE_API_VERSION_3_2:
     *
     * When the HAL returns an input buffer to the framework with
     * process_capture_result(), the acquire_fence must be set to -1. If the HAL
     * never waits on input buffer acquire fence due to an error, the sync
     * fences should be handled similarly to the way they are handled for output
     * buffers.
     */
     int acquire_fence; // framework通知hal buffer可以开始处理了

    /**
     * The release sync fence for this buffer. The HAL must set this fence when
     * returning buffers to the framework, or write -1 to indicate that no
     * waiting is required for this buffer.
     *
     * For the output buffers, the fences must be set in the output_buffers
     * array passed to process_capture_result().
     *
     * <= CAMERA_DEVICE_API_VERSION_3_1:
     *
     * For the input buffer, the release fence must be set by the
     * process_capture_request() call.
     *
     * >= CAMERA_DEVICE_API_VERSION_3_2:
     *
     * For the input buffer, the fences must be set in the input_buffer
     * passed to process_capture_result().
     *
     * After signaling the release_fence for this buffer, the HAL
     * should not make any further attempts to access this buffer as the
     * ownership has been fully transferred back to the framework.
     *
     * If a fence of -1 was specified then the ownership of this buffer
     * is transferred back immediately upon the call of process_capture_result.
     */
    int release_fence; // hal通知framework buffer可用了

} camera3_stream_buffer_t;