xref: /hardware/interfaces/camera/device/3.2/types.hal

/*
 * Copyright (C) 2016 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.
 */

package android.hardware.camera.device@3.2;

import android.hardware.graphics.common@1.0::types;

typedef vec<uint8_t> CameraMetadata;
typedef bitfield<BufferUsage> BufferUsageFlags;
typedef bitfield<Dataspace> DataspaceFlags;

/**
 * StreamType:
 *
 * The type of the camera stream, which defines whether the camera HAL device is
 * the producer or the consumer for that stream, and how the buffers of the
 * stream relate to the other streams.
 */
enum StreamType : uint32_t {
    /**
     * This stream is an output stream; the camera HAL device must fill buffers
     * from this stream with newly captured or reprocessed image data.
     */
    OUTPUT = 0,

    /**
     * This stream is an input stream; the camera HAL device must read buffers
     * from this stream and send them through the camera processing pipeline,
     * as if the buffer was a newly captured image from the imager.
     *
     * The pixel format for input stream can be any format reported by
     * android.scaler.availableInputOutputFormatsMap. The pixel format of the
     * output stream that is used to produce the reprocessing data may be any
     * format reported by android.scaler.availableStreamConfigurations. The
     * supported input/output stream combinations depends the camera device
     * capabilities, see android.scaler.availableInputOutputFormatsMap for
     * stream map details.
     *
     * This kind of stream is generally used to reprocess data into higher
     * quality images (that otherwise would cause a frame rate performance
     * loss), or to do off-line reprocessing.
     *
     * The typical use cases are OPAQUE (typically ZSL) and YUV reprocessing,
     * see S8.2, S8.3 and S10 for more details.
     */
    INPUT = 1

};

/**
 * StreamRotation:
 *
 * The required counterclockwise rotation of camera stream.
 */
enum StreamRotation : uint32_t  {
    /** No rotation */
    ROTATION_0 = 0,

    /** Rotate by 90 degree counterclockwise */
    ROTATION_90 = 1,

    /** Rotate by 180 degree counterclockwise */
    ROTATION_180 = 2,

    /** Rotate by 270 degree counterclockwise */
    ROTATION_270 = 3

};

/**
 * StreamConfigurationMode:
 *
 * This defines the general operation mode for the HAL (for a given stream
 * configuration) where modes besides NORMAL have different semantics, and
 * usually limit the generality of the API in exchange for higher performance in
 * some particular area.
 */
enum StreamConfigurationMode : uint32_t {
    /**
     * Normal stream configuration operation mode. This is the default camera
     * operation mode, where all semantics of HAL APIs and metadata controls
     * apply.
     */
    NORMAL_MODE = 0,

    /**
     * Special constrained high speed operation mode for devices that can not
     * support high speed output in NORMAL mode. All streams in this
     * configuration are operating at high speed mode and have different
     * characteristics and limitations to achieve high speed output. The NORMAL
     * mode can still be used for high speed output if the HAL can support high
     * speed output while satisfying all the semantics of HAL APIs and metadata
     * controls. It is recommended for the HAL to support high speed output in
     * NORMAL mode (by advertising the high speed FPS ranges in
     * android.control.aeAvailableTargetFpsRanges) if possible.
     *
     * This mode has below limitations/requirements:
     *
     *   1. The HAL must support up to 2 streams with sizes reported by
     *      android.control.availableHighSpeedVideoConfigurations.
     *   2. In this mode, the HAL is expected to output up to 120fps or
     *      higher. This mode must support the targeted FPS range and size
     *      configurations reported by
     *      android.control.availableHighSpeedVideoConfigurations.
     *   3. The HAL must support IMPLEMENTATION_DEFINED output
     *      stream format.
     *   4. To achieve efficient high speed streaming, the HAL may have to
     *      aggregate multiple frames together and send to camera device for
     *      processing where the request controls are same for all the frames in
     *      this batch (batch mode). The HAL must support max batch size and the
     *      max batch size requirements defined by
     *      android.control.availableHighSpeedVideoConfigurations.
     *   5. In this mode, the HAL must override aeMode, awbMode, and afMode to
     *      ON, ON, and CONTINUOUS_VIDEO, respectively. All post-processing
     *      block mode controls must be overridden to be FAST. Therefore, no
     *      manual control of capture and post-processing parameters is
     *      possible. All other controls operate the same as when
     *      android.control.mode == AUTO. This means that all other
     *      android.control.* fields must continue to work, such as
     *
     *      android.control.aeTargetFpsRange
     *      android.control.aeExposureCompensation
     *      android.control.aeLock
     *      android.control.awbLock
     *      android.control.effectMode
     *      android.control.aeRegions
     *      android.control.afRegions
     *      android.control.awbRegions
     *      android.control.afTrigger
     *      android.control.aePrecaptureTrigger
     *
     *      Outside of android.control.*, the following controls must work:
     *
     *      android.flash.mode (TORCH mode only, automatic flash for still
     *          capture must not work since aeMode is ON)
     *      android.lens.opticalStabilizationMode (if it is supported)
     *      android.scaler.cropRegion
     *      android.statistics.faceDetectMode (if it is supported)
     *   6. To reduce the amount of data passed across process boundaries at
     *      high frame rate, within one batch, camera framework only propagates
     *      the last shutter notify and the last capture results (including partial
     *      results and final result) to the app. The shutter notifies and capture
     *      results for the other requests in the batch are derived by
     *      the camera framework. As a result, the HAL can return empty metadata
     *      except for the last result in the batch.
     *
     * For more details about high speed stream requirements, see
     * android.control.availableHighSpeedVideoConfigurations and
     * CONSTRAINED_HIGH_SPEED_VIDEO capability defined in
     * android.request.availableCapabilities.
     *
     * This mode only needs to be supported by HALs that include
     * CONSTRAINED_HIGH_SPEED_VIDEO in the android.request.availableCapabilities
     * static metadata.
     */
    CONSTRAINED_HIGH_SPEED_MODE = 1,

    /**
     * A set of vendor-defined operating modes, for custom default camera
     * application features that can't be implemented in the fully flexible fashion
     * required for NORMAL_MODE.
     */
    VENDOR_MODE_0 = 0x8000,
    VENDOR_MODE_1,
    VENDOR_MODE_2,
    VENDOR_MODE_3,
    VENDOR_MODE_4,
    VENDOR_MODE_5,
    VENDOR_MODE_6,
    VENDOR_MODE_7
};

/**
 * Stream:
 *
 * A descriptor for a single camera input or output stream. A stream is defined
 * by the framework by its buffer resolution and format, and additionally by the
 * HAL with the gralloc usage flags and the maximum in-flight buffer count.
 *
 * If a configureStreams() call returns a non-fatal error, all active streams
 * remain valid as if configureStreams() had not been called.
 *
 */
struct Stream {
    /**
     * Stream ID - a nonnegative integer identifier for a stream.
     *
     * The identical stream ID must reference the same stream, with the same
     * width/height/format, across consecutive calls to configureStreams.
     *
     * If previously-used stream ID is not used in a new call to
     * configureStreams, then that stream is no longer active. Such a stream ID
     * may be reused in a future configureStreams with a new
     * width/height/format.
     *
     */
    int32_t id;

    /**
     * The type of the stream (input vs output, etc).
     */
    StreamType streamType;

    /**
     * The width in pixels of the buffers in this stream
     */
    uint32_t width;

    /**
     * The height in pixels of the buffers in this stream
     */
    uint32_t height;

    /**
     * The pixel format for the buffers in this stream.
     *
     * If IMPLEMENTATION_DEFINED is used, then the platform
     * gralloc module must select a format based on the usage flags provided by
     * the camera device and the other endpoint of the stream.
     *
     */
    android.hardware.graphics.common@1.0::PixelFormat format;

    /**
     * The gralloc usage flags for this stream, as needed by the consumer of
     * the stream.
     *
     * The usage flags from the producer and the consumer must be combined
     * together and then passed to the platform gralloc HAL module for
     * allocating the gralloc buffers for each stream.
     *
     * The HAL may use these consumer flags to decide stream configuration. For
     * streamType INPUT, the value of this field is always 0. For all streams
     * passed via configureStreams(), the HAL must set its own
     * additional usage flags in its output HalStreamConfiguration.
     *
     * The usage flag for an output stream may be bitwise combination of usage
     * flags for multiple consumers, for the purpose of sharing one camera
     * stream between those consumers. The HAL must fail configureStreams call
     * with ILLEGAL_ARGUMENT if the combined flags cannot be supported due to
     * imcompatible buffer format, dataSpace, or other hardware limitations.
     */
    BufferUsageFlags usage;

    /**
     * A field that describes the contents of the buffer. The format and buffer
     * dimensions define the memory layout and structure of the stream buffers,
     * while dataSpace defines the meaning of the data within the buffer.
     *
     * For most formats, dataSpace defines the color space of the image data.
     * In addition, for some formats, dataSpace indicates whether image- or
     * depth-based data is requested. See
     * android.hardware.graphics.common (at) 1.0::types for details of formats and
     * valid dataSpace values for each format.
     *
     * The HAL must use this dataSpace to configure the stream to the correct
     * colorspace, or to select between color and depth outputs if
     * supported. The dataspace values are set using the V0 dataspace
     * definitions.
     */
    DataspaceFlags dataSpace;

    /**
     * The required output rotation of the stream.
     *
     * This must be inspected by HAL along with stream width and height. For
     * example, if the rotation is 90 degree and the stream width and height is
     * 720 and 1280 respectively, camera service must supply buffers of size
     * 720x1280, and HAL must capture a 1280x720 image and rotate the image by
     * 90 degree counterclockwise. The rotation field must be ignored when the
     * stream type is input.
     *
     * The HAL must inspect this field during stream configuration and return
     * IllegalArgument if HAL cannot perform such rotation. HAL must always
     * support ROTATION_0, so a configureStreams() call must not fail for
     * unsupported rotation if rotation field of all streams is ROTATION_0.
     *
     */
    StreamRotation rotation;

};

/**
 * StreamConfiguration:
 *
 * A structure of stream definitions, used by configureStreams(). This
 * structure defines all the output streams and the reprocessing input
 * stream for the current camera use case.
 */
struct StreamConfiguration {
    /**
     * An array of camera stream pointers, defining the input/output
     * configuration for the camera HAL device.
     *
     * At most one input-capable stream may be defined.
     * At least one output-capable stream must be defined.
     */
    vec<Stream> streams;

    /**
     * The operation mode of streams in this configuration. The HAL can use this
     * mode as an indicator to set the stream property (e.g.,
     * HalStream::maxBuffers) appropriately. For example, if the
     * configuration is
     * CONSTRAINED_HIGH_SPEED_MODE, the HAL may
     * want to set aside more buffers for batch mode operation (see
     * android.control.availableHighSpeedVideoConfigurations for batch mode
     * definition).
     *
     */
    StreamConfigurationMode operationMode;

};

/**
 * HalStream:
 *
 * The camera HAL's response to each requested stream configuration.
 *
 * The HAL may specify the desired format, maximum buffers, and
 * usage flags for each stream.
 *
 */
struct HalStream {
    /**
     * Stream ID - a nonnegative integer identifier for a stream.
     *
     * The ID must be one of the stream IDs passed into configureStreams.
     */
    int32_t id;

    /**
     * An override pixel format for the buffers in this stream.
     *
     * The HAL must respect the requested format in Stream unless it is
     * IMPLEMENTATION_DEFINED, in which case the override format here must be
     * used by the client instead, for this stream. This allows cross-platform
     * HALs to use a standard format since IMPLEMENTATION_DEFINED formats often
     * require device-specific information. In all other cases, the
     * overrideFormat must match the requested format.
     *
     * When HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED is used, then the platform
     * gralloc module must select a format based on the usage flags provided by
     * the camera device and the other endpoint of the stream.
     */
    android.hardware.graphics.common@1.0::PixelFormat overrideFormat;

    /**
     * The gralloc usage flags for this stream, as needed by the HAL.
     *
     * For output streams, these are the HAL's producer usage flags. For input
     * streams, these are the HAL's consumer usage flags. The usage flags from
     * the producer and the consumer must be combined together and then passed
     * to the platform graphics allocator HAL for allocating the gralloc buffers
     * for each stream.
     *
     * If the stream's type is INPUT, then producerUsage must be 0, and
     * consumerUsage must be set. For other types, producerUsage must be set,
     * and consumerUsage must be 0.
     */
    BufferUsageFlags producerUsage;
    BufferUsageFlags consumerUsage;

    /**
     * The maximum number of buffers the HAL device may need to have dequeued at
     * the same time. The HAL device may not have more buffers in-flight from
     * this stream than this value.
     */
    uint32_t maxBuffers;

};

/**
 * HalStreamConfiguration:
 *
 * A structure of stream definitions, returned by configureStreams(). This
 * structure defines the HAL's desired parameters for each stream.
 *
 * All streams that were defined in the input to configureStreams() must have a
 * corresponding entry in this structure when returned by configureStreams().
 */
struct HalStreamConfiguration {
    vec<HalStream> streams;
};

/**
 * BufferStatus:
 *
 * The current status of a single stream buffer.
 */
enum BufferStatus : uint32_t {
    /**
     * The buffer is in a normal state, and can be used after waiting on its
     * sync fence.
     */
    OK = 0,

    /**
     * The buffer does not contain valid data, and the data in it must not be
     * used. The sync fence must still be waited on before reusing the buffer.
     */
    ERROR = 1
};

/**
 * StreamBuffer:
 *
 * 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.
 */
struct StreamBuffer {
    /**
     * The ID of the stream this buffer is associated with. -1 indicates an
     * invalid (empty) StreamBuffer, in which case buffer must also point to
     * null and bufferId must be 0.
     */
    int32_t streamId;

    /**
     * The unique ID of the buffer within this StreamBuffer. 0 indicates this
     * StreamBuffer contains no buffer.
     * For StreamBuffers sent to the HAL in a CaptureRequest, this ID uniquely
     * identifies a buffer. When a buffer is sent to HAL for the first time,
     * both bufferId and buffer handle must be filled. HAL must keep track of
     * the mapping between bufferId and corresponding buffer until the
     * corresponding stream is removed from stream configuration or until camera
     * device session is closed. After the first time a buffer is introduced to
     * HAL, in the future camera service must refer to the same buffer using
     * only bufferId, and keep the buffer handle null.
     */
    uint64_t bufferId;

    /**
     * The graphics buffer handle to the buffer.
     *
     * For StreamBuffers sent to the HAL in a CaptureRequest, if the bufferId
     * is not seen by the HAL before, this buffer handle is guaranteed to be a
     * valid handle to a graphics buffer, with dimensions and format matching
     * that of the stream. If the bufferId has been sent to the HAL before, this
     * buffer handle must be null and HAL must look up the actual buffer handle
     * to use from its own bufferId to buffer handle map.
     *
     * For StreamBuffers returned in a CaptureResult, this must be null, since
     * the handle to the buffer is already known to the client (since the client
     * sent it in the matching CaptureRequest), and the handle can be identified
     * by the combination of frame number and stream ID.
     */
    handle buffer;

    /**
     * Current state of the buffer. The framework must 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 ERROR when returned to the
     * framework with processCaptureResult().
     */
    BufferStatus status;

    /**
     * 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.
     *
     * In a buffer included in a CaptureRequest, the client may set this to null
     * to indicate that no waiting is necessary for this buffer.
     *
     * When the HAL returns an input or output buffer to the framework with
     * processCaptureResult(), the acquireFence must be set to null. If the HAL
     * never waits on the acquireFence due to an error in filling or reading a
     * buffer, when calling processCaptureResult() the HAL must set the
     * releaseFence of the buffer to be the acquireFence passed to it by the
     * client. This allows the client to wait on the fence before reusing the
     * buffer.
     */
    handle acquireFence;

    /**
     * The release sync fence for this buffer. The HAL must set this to a valid
     * fence fd when returning the input buffer or output buffers to the client
     * in a CaptureResult, or set it to null to indicate that no waiting is
     * required for this buffer.
     *
     * The client must set this to be null for all buffers included in a
     * processCaptureRequest call.
     *
     * After signaling the releaseFence for this buffer, the HAL
     * must not make any further attempts to access this buffer as the
     * ownership has been fully transferred back to the client.
     *
     * If this is null, then the ownership of this buffer is transferred back
     * immediately upon the call of processCaptureResult.
     */
    handle releaseFence;

};

/**
 * CameraBlob:
 *
 * Transport header for camera blob types; generally compressed JPEG buffers in
 * output streams.
 *
 * To capture JPEG images, a stream is created using the pixel format
 * HAL_PIXEL_FORMAT_BLOB and dataspace HAL_DATASPACE_V0_JFIF. The buffer size
 * for the stream is calculated by the framework, based on the static metadata
 * field android.jpeg.maxSize. Since compressed JPEG images are of variable
 * size, the HAL needs to include the final size of the compressed image using
 * this structure inside the output stream buffer. The camera blob ID field must
 * be set to CameraBlobId::JPEG.
 *
 * The transport header must be at the end of the JPEG output stream
 * buffer. That means the jpegBlobId must start at byte[buffer_size -
 * sizeof(CameraBlob)], where the buffer_size is the size of gralloc
 * buffer. Any HAL using this transport header must account for it in
 * android.jpeg.maxSize. The JPEG data itself starts at the beginning of the
 * buffer and must be blobSize bytes long.
 */
enum CameraBlobId : uint16_t {
    JPEG = 0x00FF,
};

struct CameraBlob {
    CameraBlobId blobId;

    uint32_t blobSize;
};

/**
 * MsgType:
 *
 * Indicates the type of message sent, which specifies which member of the
 * message union is valid.
 *
 */
enum MsgType : uint32_t {
    /**
     * An error has occurred. NotifyMsg::Message::Error contains the
     * error information.
     */
    ERROR = 1,

    /**
     * The exposure of a given request or processing a reprocess request has
     * begun. NotifyMsg::Message::Shutter contains the information
     * the capture.
     */
    SHUTTER = 2
};

/**
 * Defined error codes for MsgType::ERROR
 */
enum ErrorCode : uint32_t {
    /**
     * A serious failure occured. No further frames or buffer streams must
     * be produced by the device. Device must be treated as closed. The
     * client must reopen the device to use it again. The frameNumber field
     * is unused.
     */
    ERROR_DEVICE = 1,

    /**
     * An error has occurred in processing a request. No output (metadata or
     * buffers) must be produced for this request. The frameNumber field
     * specifies which request has been dropped. Subsequent requests are
     * unaffected, and the device remains operational.
     */
    ERROR_REQUEST = 2,

    /**
     * An error has occurred in producing an output result metadata buffer
     * for a request, but output stream buffers for it must still be
     * available. Subsequent requests are unaffected, and the device remains
     * operational. The frameNumber field specifies the request for which
     * result metadata won't be available.
     */
    ERROR_RESULT = 3,

    /**
     * An error has occurred in placing an output buffer into a stream for a
     * request. The frame metadata and other buffers may still be
     * available. Subsequent requests are unaffected, and the device remains
     * operational. The frameNumber field specifies the request for which the
     * buffer was dropped, and errorStreamId indicates the stream
     * that dropped the frame.
     */
    ERROR_BUFFER = 4,
};

/**
 * ErrorMsg:
 *
 * Message contents for MsgType::ERROR
 */
struct ErrorMsg {
    /**
     * Frame number of the request the error applies to. 0 if the frame number
     * isn't applicable to the error.
     */
    uint32_t frameNumber;

    /**
     * Pointer to the stream that had a failure. -1 if the stream isn't
     * applicable to the error.
     */
    int32_t errorStreamId;

    /**
     * The code for this error.
     */
    ErrorCode errorCode;

};

/**
 * ShutterMsg:
 *
 * Message contents for MsgType::SHUTTER
 */
struct ShutterMsg {
    /**
     * Frame number of the request that has begun exposure or reprocessing.
     */
    uint32_t frameNumber;

    /**
     * Timestamp for the start of capture. For a reprocess request, this must
     * be input image's start of capture. This must match the capture result
     * metadata's sensor exposure start timestamp.
     */
    uint64_t timestamp;

};

/**
 * NotifyMsg:
 *
 * The message structure sent to ICameraDevice3Callback::notify()
 */
struct NotifyMsg {
    /**
     * The message type.
     */
    MsgType type;

    union Message {
        /**
         * Error message contents. Valid if type is MsgType::ERROR
         */
        ErrorMsg error;

        /**
         * Shutter message contents. Valid if type is MsgType::SHUTTER
         */
        ShutterMsg shutter;
    } msg;

};

/**
 * RequestTemplate:
 *
 * Available template types for
 * ICameraDevice::constructDefaultRequestSettings()
 */
enum RequestTemplate : uint32_t {
    /**
     * Standard camera preview operation with 3A on auto.
     */
    PREVIEW = 1,

    /**
     * Standard camera high-quality still capture with 3A and flash on auto.
     */
    STILL_CAPTURE = 2,

    /**
     * Standard video recording plus preview with 3A on auto, torch off.
     */
    VIDEO_RECORD = 3,

    /**
     * High-quality still capture while recording video. Applications typically
     * include preview, video record, and full-resolution YUV or JPEG streams in
     * request. Must not cause stuttering on video stream. 3A on auto.
     */
    VIDEO_SNAPSHOT = 4,

    /**
     * Zero-shutter-lag mode. Application typically request preview and
     * full-resolution data for each frame, and reprocess it to JPEG when a
     * still image is requested by user. Settings must provide highest-quality
     * full-resolution images without compromising preview frame rate. 3A on
     * auto.
     */
    ZERO_SHUTTER_LAG = 5,

    /**
     * A basic template for direct application control of capture
     * parameters. All automatic control is disabled (auto-exposure, auto-white
     * balance, auto-focus), and post-processing parameters are set to preview
     * quality. The manual capture parameters (exposure, sensitivity, etc.)
     * are set to reasonable defaults, but may be overridden by the
     * application depending on the intended use case.
     */
    MANUAL = 6,

    /**
     * First value for vendor-defined request templates
     */
    VENDOR_TEMPLATE_START = 0x40000000,

};

/**
 * CaptureRequest:
 *
 * A single request for image capture/buffer reprocessing, sent to the Camera
 * HAL device by the framework in processCaptureRequest().
 *
 * 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 frameNumber.
 *
 * In response, the camera HAL device must send a CaptureResult
 * structure asynchronously to the framework, using the processCaptureResult()
 * callback.
 */
struct CaptureRequest {
    /**
     * 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 ICameraDevice3Callback::notify().
     */
    uint32_t frameNumber;

    /**
     * If non-zero, read settings from request queue instead
     * (see ICameraDeviceSession.getCaptureRequestMetadataQueue).
     * If zero, read settings from .settings field.
     */
    uint64_t fmqSettingsSize;

    /**
     * If fmqSettingsSize is zero,
     * the settings buffer contains the capture and processing parameters for
     * the request. As a special case, an empty settings buffer indicates that
     * the settings are identical to the most-recently submitted capture
     * request. A empty buffer cannot be used as the first submitted request
     * after a configureStreams() call.
     *
     * This field must be used if fmqSettingsSize is zero. It must not be used
     * if fmqSettingsSize is non-zero.
     */
    CameraMetadata settings;

    /**
     * The input stream buffer to use for this request, if any.
     *
     * An invalid inputBuffer is signified by a null inputBuffer::buffer, in
     * which case the value of all other members of inputBuffer must be ignored.
     *
     * If inputBuffer is invalid, then the request is for a new capture from the
     * imager. If inputBuffer is valid, the request is for reprocessing the
     * image contained in inputBuffer, and the HAL must release the inputBuffer
     * back to the client in a subsequent processCaptureResult call.
     *
     * The HAL is required to wait on the acquire sync fence of the input buffer
     * before accessing it.
     *
     */
    StreamBuffer inputBuffer;

    /**
     * An array of at least 1 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 handles in outputBuffers; the client
     * must not access them until they are returned in a CaptureResult.
     *
     * Any or all of the buffers included here may be brand new in this
     * request (having never before seen by the HAL).
     */
    vec<StreamBuffer> outputBuffers;

};

/**
 * CaptureResult:
 *
 * The result of a single capture/reprocess by the camera HAL device. This is
 * sent to the framework asynchronously with processCaptureResult(), in
 * response to a single capture request sent to the HAL with
 * processCaptureRequest(). Multiple processCaptureResult() calls may be
 * performed by the HAL for each request.
 *
 * Each call, all with the same frame
 * number, may contain some subset of the output buffers, and/or the result
 * metadata.
 *
 * The result structure contains the output metadata from this capture, and the
 * set of output buffers that have been/will be filled for this capture. Each
 * output buffer may come with a release sync fence that the framework must wait
 * on before reading, in case the buffer has not yet been filled by the HAL.
 *
 * The metadata may be provided multiple times for a single frame number. The
 * framework must accumulate together the final result set by combining each
 * partial result together into the total result set.
 *
 * If an input buffer is given in a request, the HAL must return it in one of
 * the processCaptureResult calls, and the call may be to just return the
 * input buffer, without metadata and output buffers; the sync fences must be
 * handled the same way they are done for output buffers.
 *
 * Performance considerations:
 *
 * Applications receive these partial results immediately, so sending partial
 * results is a highly recommended performance optimization to avoid the total
 * pipeline latency before sending the results for what is known very early on
 * in the pipeline.
 *
 * A typical use case might be calculating the AF state halfway through the
 * pipeline; by sending the state back to the framework immediately, we get a
 * 50% performance increase and perceived responsiveness of the auto-focus.
 *
 */
struct CaptureResult {
    /**
     * The frame number is an incrementing integer set by the framework in the
     * submitted request to uniquely identify this capture. It is also used to
     * identify the request in asynchronous notifications sent to
     * ICameraDevice3Callback::notify().
     */
    uint32_t frameNumber;

    /**
     * If non-zero, read result from result queue instead
     * (see ICameraDeviceSession.getCaptureResultMetadataQueue).
     * If zero, read result from .result field.
     */
    uint64_t fmqResultSize;

    /**
     * The result metadata for this capture. This contains information about the
     * final capture parameters, the state of the capture and post-processing
     * hardware, the state of the 3A algorithms, if enabled, and the output of
     * any enabled statistics units.
     *
     * If there was an error producing the result metadata, result must be an
     * empty metadata buffer, and notify() must be called with
     * ErrorCode::ERROR_RESULT.
     *
     * Multiple calls to processCaptureResult() with a given frameNumber
     * may include (partial) result metadata.
     *
     * Partial metadata submitted must not include any metadata key returned
     * in a previous partial result for a given frame. Each new partial result
     * for that frame must also set a distinct partialResult value.
     *
     * If notify has been called with ErrorCode::ERROR_RESULT, all further
     * partial results for that frame are ignored by the framework.
     */
    CameraMetadata result;

    /**
     * The completed output stream buffers for this capture.
     *
     * They may not yet be filled at the time the HAL calls
     * processCaptureResult(); the framework must wait on the release sync
     * fences provided by the HAL before reading the buffers.
     *
     * The StreamBuffer::buffer handle must be null for all returned buffers;
     * the client must cache the handle and look it up via the combination of
     * frame number and stream ID.
     *
     * The number of output buffers returned must be less than or equal to the
     * matching capture request's count. If this is less than the buffer count
     * in the capture request, at least one more call to processCaptureResult
     * with the same frameNumber must be made, to return the remaining output
     * buffers to the framework. This may only be zero if the structure includes
     * valid result metadata or an input buffer is returned in this result.
     *
     * The HAL must set the stream buffer's release sync fence to a valid sync
     * fd, or to null if the buffer has already been filled.
     *
     * If the HAL encounters an error while processing the buffer, and the
     * buffer is not filled, the buffer's status field must be set to ERROR. If
     * the HAL did not wait on the acquire fence before encountering the error,
     * the acquire fence must be copied into the release fence, to allow the
     * framework to wait on the fence before reusing the buffer.
     *
     * The acquire fence must be set to null for all output buffers.
     *
     * This vector may be empty; if so, at least one other processCaptureResult
     * call must be made (or have been made) by the HAL to provide the filled
     * output buffers.
     *
     * When processCaptureResult is called with a new buffer for a frame,
     * all previous frames' buffers for that corresponding stream must have been
     * already delivered (the fences need not have yet been signaled).
     *
     * Buffers for a frame may be sent to framework before the corresponding
     * SHUTTER-notify call is made by the HAL.
     *
     * Performance considerations:
     *
     * Buffers delivered to the framework are not dispatched to the
     * application layer until a start of exposure timestamp has been received
     * via a SHUTTER notify() call. It is highly recommended to
     * dispatch that call as early as possible.
     */
    vec<StreamBuffer> outputBuffers;

    /**
     * The handle for the input stream buffer for this capture, if any.
     *
     * It may not yet be consumed at the time the HAL calls
     * processCaptureResult(); the framework must wait on the release sync fence
     * provided by the HAL before reusing the buffer.
     *
     * The HAL must handle the sync fences the same way they are done for
     * outputBuffers.
     *
     * Only one input buffer is allowed to be sent per request. Similarly to
     * output buffers, the ordering of returned input buffers must be
     * maintained by the HAL.
     *
     * Performance considerations:
     *
     * The input buffer should be returned as early as possible. If the HAL
     * supports sync fences, it can call processCaptureResult to hand it back
     * with sync fences being set appropriately. If the sync fences are not
     * supported, the buffer can only be returned when it is consumed, which
     * may take long time; the HAL may choose to copy this input buffer to make
     * the buffer return sooner.
     */
    StreamBuffer inputBuffer;

    /**
     * In order to take advantage of partial results, the HAL must set the
     * static metadata android.request.partialResultCount to the number of
     * partial results it sends for each frame.
     *
     * Each new capture result with a partial result must set
     * this field to a distinct inclusive value between
     * 1 and android.request.partialResultCount.
     *
     * HALs not wishing to take advantage of this feature must not
     * set an android.request.partialResultCount or partial_result to a value
     * other than 1.
     *
     * This value must be set to 0 when a capture result contains buffers only
     * and no metadata.
     */
    uint32_t partialResult;

};

/**
 * BufferCache:
 *
 * A list of cached bufferIds associated with a certain stream.
 * Buffers are passed between camera service and camera HAL via bufferId except
 * the first time a new buffer is being passed to HAL in CaptureRequest. Camera
 * service and camera HAL therefore need to maintain a cached map of bufferId
 * and corresponing native handle.
 *
 */
struct BufferCache {
    /**
     * The ID of the stream this list is associated with.
     */
    int32_t streamId;

    /**
     * A cached buffer ID associated with streamId.
     */
    uint64_t bufferId;
};