blob: 39891616679968ed5a7b6258866c73d59a32156a [file] [log] [blame] [edit]
/*
* 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@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 output, 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.
*
* For private reprocessing, the HAL must not override the input stream's
* IMPLEMENTATION_DEFINED format.
*/
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;
};