java.lang.Object | ||
↳ | android.hardware.camera2.CameraMetadata<TKey> | |
↳ | android.hardware.camera2.CaptureRequest |
An immutable package of settings and outputs needed to capture a single image from the camera device.
Contains the configuration for the capture hardware (sensor, lens, flash), the processing pipeline, the control algorithms, and the output buffers. Also contains the list of target Surfaces to send image data to for this capture.
CaptureRequests can be created by using a CaptureRequest.Builder
instance,
obtained by calling createCaptureRequest(int)
CaptureRequests are given to capture(CaptureRequest, CameraCaptureSession.CaptureListener, Handler)
or
setRepeatingRequest(CaptureRequest, CameraCaptureSession.CaptureListener, Handler)
to capture images from a camera.
Each request can specify a different subset of target Surfaces for the
camera to send the captured data to. All the surfaces used in a request must
be part of the surface list given to the last call to
createCaptureSession(List
, when the request is submitted to the
session.
For example, a request meant for repeating preview might only include the Surface for the preview SurfaceView or SurfaceTexture, while a high-resolution still capture would also include a Surface from a ImageReader configured for high-resolution JPEG images.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
CaptureRequest.Builder | A builder for capture requests. | ||||||||||
CaptureRequest.Key<T> | A Key is used to do capture request field lookups with
get(CaptureResult.Key or to set fields with
set(Key, Object) . |
[Expand]
Inherited Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.hardware.camera2.CameraMetadata
| |||||||||||
From interface
android.os.Parcelable
|
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
BLACK_LEVEL_LOCK | Whether black-level compensation is locked to its current values, or is free to vary. |
||||||||||
COLOR_CORRECTION_GAINS | Gains applying to Bayer raw color channels for white-balance. |
||||||||||
COLOR_CORRECTION_MODE | The mode control selects how the image data is converted from the sensor's native color into linear sRGB color. |
||||||||||
COLOR_CORRECTION_TRANSFORM | A color transform matrix to use to transform from sensor RGB color space to output linear sRGB color space. |
||||||||||
CONTROL_AE_ANTIBANDING_MODE | The desired setting for the camera device's auto-exposure algorithm's antibanding compensation. |
||||||||||
CONTROL_AE_EXPOSURE_COMPENSATION | Adjustment to auto-exposure (AE) target image brightness. |
||||||||||
CONTROL_AE_LOCK | Whether auto-exposure (AE) is currently locked to its latest calculated values. |
||||||||||
CONTROL_AE_MODE | The desired mode for the camera device's auto-exposure routine. |
||||||||||
CONTROL_AE_PRECAPTURE_TRIGGER | Whether the camera device will trigger a precapture metering sequence when it processes this request. |
||||||||||
CONTROL_AE_REGIONS | List of areas to use for metering. |
||||||||||
CONTROL_AE_TARGET_FPS_RANGE | Range over which fps can be adjusted to maintain exposure. |
||||||||||
CONTROL_AF_MODE | Whether auto-focus (AF) is currently enabled, and what mode it is set to. |
||||||||||
CONTROL_AF_REGIONS | List of areas to use for focus estimation. |
||||||||||
CONTROL_AF_TRIGGER | Whether the camera device will trigger autofocus for this request. |
||||||||||
CONTROL_AWB_LOCK | Whether auto-white balance (AWB) is currently locked to its latest calculated values. |
||||||||||
CONTROL_AWB_MODE | Whether auto-white balance (AWB) is currently setting the color transform fields, and what its illumination target is. |
||||||||||
CONTROL_AWB_REGIONS | List of areas to use for illuminant estimation. |
||||||||||
CONTROL_CAPTURE_INTENT | Information to the camera device 3A (auto-exposure, auto-focus, auto-white balance) routines about the purpose of this capture, to help the camera device to decide optimal 3A strategy. |
||||||||||
CONTROL_EFFECT_MODE | A special color effect to apply. |
||||||||||
CONTROL_MODE | Overall mode of 3A control routines. |
||||||||||
CONTROL_SCENE_MODE | A camera mode optimized for conditions typical in a particular capture setting. |
||||||||||
CONTROL_VIDEO_STABILIZATION_MODE | Whether video stabilization is active. |
||||||||||
CREATOR | |||||||||||
EDGE_MODE | Operation mode for edge enhancement. |
||||||||||
FLASH_MODE | The desired mode for for the camera device's flash control. |
||||||||||
HOT_PIXEL_MODE | Set operational mode for hot pixel correction. |
||||||||||
JPEG_GPS_LOCATION | A location object to use when generating image GPS metadata. |
||||||||||
JPEG_ORIENTATION | Orientation of JPEG image to write |
||||||||||
JPEG_QUALITY | Compression quality of the final JPEG image. |
||||||||||
JPEG_THUMBNAIL_QUALITY | Compression quality of JPEG thumbnail. |
||||||||||
JPEG_THUMBNAIL_SIZE | Resolution of embedded JPEG thumbnail. |
||||||||||
LENS_APERTURE | The ratio of lens focal length to the effective aperture diameter. |
||||||||||
LENS_FILTER_DENSITY | State of lens neutral density filter(s). |
||||||||||
LENS_FOCAL_LENGTH | The current lens focal length; used for optical zoom. |
||||||||||
LENS_FOCUS_DISTANCE | Distance to plane of sharpest focus, measured from frontmost surface of the lens. |
||||||||||
LENS_OPTICAL_STABILIZATION_MODE | Sets whether the camera device uses optical image stabilization (OIS) when capturing images. |
||||||||||
NOISE_REDUCTION_MODE | Mode of operation for the noise reduction algorithm. |
||||||||||
SCALER_CROP_REGION | The region of the sensor to read out for this capture. |
||||||||||
SENSOR_EXPOSURE_TIME | Duration each pixel is exposed to light. |
||||||||||
SENSOR_FRAME_DURATION | Duration from start of frame exposure to start of next frame exposure. |
||||||||||
SENSOR_SENSITIVITY | The amount of gain applied to sensor data before processing. |
||||||||||
SENSOR_TEST_PATTERN_DATA | A pixel |
||||||||||
SENSOR_TEST_PATTERN_MODE | When enabled, the sensor sends a test pattern instead of doing a real exposure from the camera. |
||||||||||
SHADING_MODE | Quality of lens shading correction applied to the image data. |
||||||||||
STATISTICS_FACE_DETECT_MODE | Control for the face detector unit. |
||||||||||
STATISTICS_HOT_PIXEL_MAP_MODE | Operating mode for hotpixel map generation. |
||||||||||
STATISTICS_LENS_SHADING_MAP_MODE | Whether the camera device will output the lens shading map in output result metadata. |
||||||||||
TONEMAP_CURVE | Tonemapping / contrast / gamma curve to use when |
||||||||||
TONEMAP_MODE | High-level global contrast/gamma/tonemapping control. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Describe the kinds of special objects contained in this Parcelable's
marshalled representation.
| |||||||||||
Determine whether this CaptureRequest is equal to another CaptureRequest.
| |||||||||||
Get a capture request field value.
| |||||||||||
Returns a list of the keys contained in this map.
| |||||||||||
Retrieve the tag for this request, if any.
| |||||||||||
Returns an integer hash code for this object.
| |||||||||||
Flatten this object in to a Parcel.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.hardware.camera2.CameraMetadata
| |||||||||||
From class
java.lang.Object
| |||||||||||
From interface
android.os.Parcelable
|
Whether black-level compensation is locked to its current values, or is free to vary.
When set to ON, the values used for black-level compensation will not change until the lock is set to OFF.
Since changes to certain capture parameters (such as exposure time) may require resetting of black level compensation, the camera device must report whether setting the black level lock was successful in the output result metadata.
For example, if a sequence of requests is as follows:
And the exposure change in Request 4 requires the camera device to reset the black level offsets, then the output result metadata is expected to be:
This indicates to the application that on frame 4, black levels were reset due to exposure value changes, and pixel values may not be consistent across captures.
The camera device will maintain the lock to the extent possible, only overriding the lock to OFF when changes to other request parameters require a black level recalculation or reset.
Gains applying to Bayer raw color channels for white-balance.
These per-channel gains are either set by the camera device
when the request android.colorCorrection.mode
is not
TRANSFORM_MATRIX, or directly by the application in the
request when the android.colorCorrection.mode
is
TRANSFORM_MATRIX.
The gains in the result metadata are the gains actually applied by the camera device to the current frame.
The mode control selects how the image data is converted from the sensor's native color into linear sRGB color.
When auto-white balance (AWB) is enabled with android.control.awbMode
, this
control is overridden by the AWB routine. When AWB is disabled, the
application controls how the color mapping is performed.
We define the expected processing pipeline below. For consistency across devices, this is always the case with TRANSFORM_MATRIX.
When either FULL or HIGH_QUALITY is used, the camera device may
do additional processing but android.colorCorrection.gains
and
android.colorCorrection.transform
will still be provided by the
camera device (in the results) and be roughly correct.
Switching to TRANSFORM_MATRIX and using the data provided from FAST or HIGH_QUALITY will yield a picture with the same white point as what was produced by the camera device in the earlier frame.
The expected processing pipeline is as follows:
The white balance is encoded by two values, a 4-channel white-balance gain vector (applied in the Bayer domain), and a 3x3 color transform matrix (applied after demosaic).
The 4-channel white-balance gains are defined as:
android.colorCorrection.gains
= [ R G_even G_odd B ]
where G_even
is the gain for green pixels on even rows of the
output, and G_odd
is the gain for green pixels on the odd rows.
These may be identical for a given camera device implementation; if
the camera device does not support a separate gain for even/odd green
channels, it will use the G_even
value, and write G_odd
equal to
G_even
in the output result metadata.
The matrices for color transforms are defined as a 9-entry vector:
android.colorCorrection.transform
= [ I0 I1 I2 I3 I4 I5 I6 I7 I8 ]
which define a transform from input sensor colors, P_in = [ r g b ]
,
to output linear sRGB, P_out = [ r' g' b' ]
,
with colors as follows:
r' = I0r + I1g + I2b
g' = I3r + I4g + I5b
b' = I6r + I7g + I8b
Both the input and output value ranges must match. Overflow/underflow values are clipped to fit within the range.
A color transform matrix to use to transform from sensor RGB color space to output linear sRGB color space.
This matrix is either set by the camera device when the request
android.colorCorrection.mode
is not TRANSFORM_MATRIX, or
directly by the application in the request when the
android.colorCorrection.mode
is TRANSFORM_MATRIX.
In the latter case, the camera device may round the matrix to account
for precision issues; the final rounded matrix should be reported back
in this matrix result metadata. The transform should keep the magnitude
of the output color values within [0, 1.0]
(assuming input color
values is within the normalized range [0, 1.0]
), or clipping may occur.
The desired setting for the camera device's auto-exposure algorithm's antibanding compensation.
Some kinds of lighting fixtures, such as some fluorescent lights, flicker at the rate of the power supply frequency (60Hz or 50Hz, depending on country). While this is typically not noticeable to a person, it can be visible to a camera device. If a camera sets its exposure time to the wrong value, the flicker may become visible in the viewfinder as flicker or in a final captured image, as a set of variable-brightness bands across the image.
Therefore, the auto-exposure routines of camera devices include antibanding routines that ensure that the chosen exposure value will not cause such banding. The choice of exposure time depends on the rate of flicker, which the camera device can detect automatically, or the expected rate can be selected by the application using this control.
A given camera device may not support all of the possible
options for the antibanding mode. The
android.control.aeAvailableAntibandingModes
key contains
the available modes for a given camera device.
The default mode is AUTO, which must be supported by all camera devices.
If manual exposure control is enabled (by setting
android.control.aeMode
or android.control.mode
to OFF),
then this setting has no effect, and the application must
ensure it selects exposure times that do not cause banding
issues. The android.statistics.sceneFlicker
key can assist
the application in this.
Adjustment to auto-exposure (AE) target image brightness.
The adjustment is measured as a count of steps, with the
step size defined by android.control.aeCompensationStep
and the
allowed range by android.control.aeCompensationRange
.
For example, if the exposure value (EV) step is 0.333, '6'
will mean an exposure compensation of +2 EV; -3 will mean an
exposure compensation of -1 EV. One EV represents a doubling
of image brightness. Note that this control will only be
effective if android.control.aeMode
!=
OFF. This control
will take effect even when android.control.aeLock
== true
.
In the event of exposure compensation value being changed, camera device
may take several frames to reach the newly requested exposure target.
During that time, android.control.aeState
field will be in the SEARCHING
state. Once the new exposure target is reached, android.control.aeState
will
change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or
FLASH_REQUIRED (if the scene is too dark for still capture).
Whether auto-exposure (AE) is currently locked to its latest calculated values.
Note that even when AE is locked, the flash may be
fired if the android.control.aeMode
is ON_AUTO_FLASH / ON_ALWAYS_FLASH /
ON_AUTO_FLASH_REDEYE.
When android.control.aeExposureCompensation
is changed, even if the AE lock
is ON, the camera device will still adjust its exposure value.
If AE precapture is triggered (see android.control.aePrecaptureTrigger
)
when AE is already locked, the camera device will not change the exposure time
(android.sensor.exposureTime
) and sensitivity (android.sensor.sensitivity
)
parameters. The flash may be fired if the android.control.aeMode
is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the
android.control.aeMode
is ON_ALWAYS_FLASH, the scene may become overexposed.
See android.control.aeState
for AE lock related state transition details.
The desired mode for the camera device's auto-exposure routine.
This control is only effective if android.control.mode
is
AUTO.
When set to any of the ON modes, the camera device's
auto-exposure routine is enabled, overriding the
application's selected exposure time, sensor sensitivity,
and frame duration (android.sensor.exposureTime
,
android.sensor.sensitivity
, and
android.sensor.frameDuration
). If one of the FLASH modes
is selected, the camera device's flash unit controls are
also overridden.
The FLASH modes are only available if the camera device
has a flash unit (android.flash.info.available
is true
).
If flash TORCH mode is desired, this field must be set to
ON or OFF, and android.flash.mode
set to TORCH.
When set to any of the ON modes, the values chosen by the camera device auto-exposure routine for the overridden fields for a given capture will be available in its CaptureResult.
Whether the camera device will trigger a precapture metering sequence when it processes this request.
This entry is normally set to IDLE, or is not included at all in the request settings. When included and set to START, the camera device will trigger the autoexposure precapture metering sequence.
The precapture sequence should triggered before starting a high-quality still capture for final metering decisions to be made, and for firing pre-capture flash pulses to estimate scene brightness and required final capture flash power, when the flash is enabled.
Normally, this entry should be set to START for only a single request, and the application should wait until the sequence completes before starting a new one.
The exact effect of auto-exposure (AE) precapture trigger
depends on the current AE mode and state; see
android.control.aeState
for AE precapture state transition
details.
List of areas to use for metering.
The coordinate system is based on the active pixel array,
with (0,0) being the top-left pixel in the active pixel array, and
(android.sensor.info.activeArraySize
.width - 1,
android.sensor.info.activeArraySize
.height - 1) being the
bottom-right pixel in the active pixel array.
The weight must range from 0 to 1000, and represents a weight for every pixel in the area. This means that a large metering area with the same weight as a smaller area will have more effect in the metering result. Metering areas can partially overlap and the camera device will add the weights in the overlap region.
If all regions have 0 weight, then no specific metering area
needs to be used by the camera device. If the metering region is
outside the used android.scaler.cropRegion
returned in capture result metadata,
the camera device will ignore the sections outside the region and output the
used sections in the result metadata.
Range over which fps can be adjusted to maintain exposure.
Only constrains auto-exposure (AE) algorithm, not
manual control of android.sensor.exposureTime
Whether auto-focus (AF) is currently enabled, and what mode it is set to.
Only effective if android.control.mode
= AUTO and the lens is not fixed focus
(i.e.
).android.lens.info.minimumFocusDistance
> 0
If the lens is controlled by the camera device auto-focus algorithm,
the camera device will report the current AF status in android.control.afState
in result metadata.
List of areas to use for focus estimation.
The coordinate system is based on the active pixel array,
with (0,0) being the top-left pixel in the active pixel array, and
(android.sensor.info.activeArraySize
.width - 1,
android.sensor.info.activeArraySize
.height - 1) being the
bottom-right pixel in the active pixel array.
The weight must range from 0 to 1000, and represents a weight for every pixel in the area. This means that a large metering area with the same weight as a smaller area will have more effect in the metering result. Metering areas can partially overlap and the camera device will add the weights in the overlap region.
If all regions have 0 weight, then no specific metering area
needs to be used by the camera device. If the metering region is
outside the used android.scaler.cropRegion
returned in capture result metadata,
the camera device will ignore the sections outside the region and output the
used sections in the result metadata.
Whether the camera device will trigger autofocus for this request.
This entry is normally set to IDLE, or is not included at all in the request settings.
When included and set to START, the camera device will trigger the autofocus algorithm. If autofocus is disabled, this trigger has no effect.
When set to CANCEL, the camera device will cancel any active trigger, and return to its initial AF state.
Generally, applications should set this entry to START or CANCEL for only a single capture, and then return it to IDLE (or not set at all). Specifying START for multiple captures in a row means restarting the AF operation over and over again.
See android.control.afState
for what the trigger means for each AF mode.
Whether auto-white balance (AWB) is currently locked to its latest calculated values.
Note that AWB lock is only meaningful when
android.control.awbMode
is in the AUTO mode; in other modes,
AWB is already fixed to a specific setting.
Whether auto-white balance (AWB) is currently setting the color transform fields, and what its illumination target is.
This control is only effective if android.control.mode
is AUTO.
When set to the ON mode, the camera device's auto-white balance
routine is enabled, overriding the application's selected
android.colorCorrection.transform
, android.colorCorrection.gains
and
android.colorCorrection.mode
.
When set to the OFF mode, the camera device's auto-white balance
routine is disabled. The application manually controls the white
balance by android.colorCorrection.transform
, android.colorCorrection.gains
and android.colorCorrection.mode
.
When set to any other modes, the camera device's auto-white
balance routine is disabled. The camera device uses each
particular illumination target for white balance
adjustment. The application's values for
android.colorCorrection.transform
,
android.colorCorrection.gains
and
android.colorCorrection.mode
are ignored.
COLOR_CORRECTION_GAINS
COLOR_CORRECTION_MODE
COLOR_CORRECTION_TRANSFORM
CONTROL_MODE
CONTROL_AWB_MODE_OFF
CONTROL_AWB_MODE_AUTO
CONTROL_AWB_MODE_INCANDESCENT
CONTROL_AWB_MODE_FLUORESCENT
CONTROL_AWB_MODE_WARM_FLUORESCENT
CONTROL_AWB_MODE_DAYLIGHT
CONTROL_AWB_MODE_CLOUDY_DAYLIGHT
CONTROL_AWB_MODE_TWILIGHT
CONTROL_AWB_MODE_SHADE
List of areas to use for illuminant estimation.
The coordinate system is based on the active pixel array,
with (0,0) being the top-left pixel in the active pixel array, and
(android.sensor.info.activeArraySize
.width - 1,
android.sensor.info.activeArraySize
.height - 1) being the
bottom-right pixel in the active pixel array.
The weight must range from 0 to 1000, and represents a weight for every pixel in the area. This means that a large metering area with the same weight as a smaller area will have more effect in the metering result. Metering areas can partially overlap and the camera device will add the weights in the overlap region.
If all regions have 0 weight, then no specific metering area
needs to be used by the camera device. If the metering region is
outside the used android.scaler.cropRegion
returned in capture result metadata,
the camera device will ignore the sections outside the region and output the
used sections in the result metadata.
Information to the camera device 3A (auto-exposure, auto-focus, auto-white balance) routines about the purpose of this capture, to help the camera device to decide optimal 3A strategy.
This control (except for MANUAL) is only effective if
and any 3A routine is active.android.control.mode
!= OFF
ZERO_SHUTTER_LAG will be supported if android.request.availableCapabilities
contains ZSL. MANUAL will be supported if android.request.availableCapabilities
contains MANUAL_SENSOR.
A special color effect to apply.
When this mode is set, a color effect will be applied to images produced by the camera device. The interpretation and implementation of these color effects is left to the implementor of the camera device, and should not be depended on to be consistent (or present) across all devices.
A color effect will only be applied if
android.control.mode
!= OFF.
Overall mode of 3A control routines.
High-level 3A control. When set to OFF, all 3A control by the camera device is disabled. The application must set the fields for capture parameters itself.
When set to AUTO, the individual algorithm controls in
android.control.* are in effect, such as android.control.afMode
.
When set to USE_SCENE_MODE, the individual controls in android.control.* are mostly disabled, and the camera device implements one of the scene mode settings (such as ACTION, SUNSET, or PARTY) as it wishes. The camera device scene mode 3A settings are provided by android.control.sceneModeOverrides.
When set to OFF_KEEP_STATE, it is similar to OFF mode, the only difference is that this frame will not be used by camera device background 3A statistics update, as if this frame is never captured. This mode can be used in the scenario where the application doesn't want a 3A manual control capture to affect the subsequent auto 3A capture results.
A camera mode optimized for conditions typical in a particular capture setting.
This is the mode that that is active when
. Aside from FACE_PRIORITY,
these modes will disable android.control.mode
== USE_SCENE_MODEandroid.control.aeMode
,
android.control.awbMode
, and android.control.afMode
while in use.
The scene modes available for a given camera device are listed in
android.control.availableSceneModes
.
The interpretation and implementation of these scene modes is left to the implementor of the camera device. Their behavior will not be consistent across all devices, and any given device may only implement a subset of these modes.
CONTROL_AE_MODE
CONTROL_AF_MODE
CONTROL_AVAILABLE_SCENE_MODES
CONTROL_AWB_MODE
CONTROL_MODE
CONTROL_SCENE_MODE_DISABLED
CONTROL_SCENE_MODE_FACE_PRIORITY
CONTROL_SCENE_MODE_ACTION
CONTROL_SCENE_MODE_PORTRAIT
CONTROL_SCENE_MODE_LANDSCAPE
CONTROL_SCENE_MODE_NIGHT
CONTROL_SCENE_MODE_NIGHT_PORTRAIT
CONTROL_SCENE_MODE_THEATRE
CONTROL_SCENE_MODE_BEACH
CONTROL_SCENE_MODE_SNOW
CONTROL_SCENE_MODE_SUNSET
CONTROL_SCENE_MODE_STEADYPHOTO
CONTROL_SCENE_MODE_FIREWORKS
CONTROL_SCENE_MODE_SPORTS
CONTROL_SCENE_MODE_PARTY
CONTROL_SCENE_MODE_CANDLELIGHT
CONTROL_SCENE_MODE_BARCODE
Whether video stabilization is active.
Video stabilization automatically translates and scales images from the camera in order to stabilize motion between consecutive frames.
If enabled, video stabilization can modify the
android.scaler.cropRegion
to keep the video stream
stabilized
Operation mode for edge enhancement.
Edge/sharpness/detail enhancement. OFF means no enhancement will be applied by the camera device.
This must be set to one of the modes listed in android.edge.availableEdgeModes
.
FAST/HIGH_QUALITY both mean camera device determined enhancement will be applied. HIGH_QUALITY mode indicates that the camera device will use the highest-quality enhancement algorithms, even if it slows down capture rate. FAST means the camera device will not slow down capture rate when applying edge enhancement.
The desired mode for for the camera device's flash control.
This control is only effective when flash unit is available
(
).android.flash.info.available
== true
When this control is used, the android.control.aeMode
must be set to ON or OFF.
Otherwise, the camera device auto-exposure related flash control (ON_AUTO_FLASH,
ON_ALWAYS_FLASH, or ON_AUTO_FLASH_REDEYE) will override this control.
When set to OFF, the camera device will not fire flash for this capture.
When set to SINGLE, the camera device will fire flash regardless of the camera
device's auto-exposure routine's result. When used in still capture case, this
control should be used along with auto-exposure (AE) precapture metering sequence
(android.control.aePrecaptureTrigger
), otherwise, the image may be incorrectly exposed.
When set to TORCH, the flash will be on continuously. This mode can be used for use cases such as preview, auto-focus assist, still capture, or video recording.
The flash status will be reported by android.flash.state
in the capture result metadata.
Set operational mode for hot pixel correction.
Valid modes for this camera device are listed in
android.hotPixel.availableHotPixelModes
.
Hotpixel correction interpolates out, or otherwise removes, pixels that do not accurately encode the incoming light (i.e. pixels that are stuck at an arbitrary value).
A location object to use when generating image GPS metadata.
Compression quality of the final JPEG image.
85-95 is typical usage range.
Resolution of embedded JPEG thumbnail.
When set to (0, 0) value, the JPEG EXIF will not contain thumbnail, but the captured JPEG will still be a valid image.
When a jpeg image capture is issued, the thumbnail size selected should have the same aspect ratio as the jpeg image.
If the thumbnail image aspect ratio differs from the JPEG primary image aspect ratio, the camera device creates the thumbnail by cropping it from the primary image. For example, if the primary image has 4:3 aspect ratio, the thumbnail image has 16:9 aspect ratio, the primary image will be cropped vertically (letterbox) to generate the thumbnail image. The thumbnail image will always have a smaller Field Of View (FOV) than the primary image when aspect ratios differ.
The ratio of lens focal length to the effective aperture diameter.
This will only be supported on the camera devices that
have variable aperture lens. The aperture value can only be
one of the values listed in android.lens.info.availableApertures
.
When this is supported and android.control.aeMode
is OFF,
this can be set along with android.sensor.exposureTime
,
android.sensor.sensitivity
, and android.sensor.frameDuration
to achieve manual exposure control.
The requested aperture value may take several frames to reach the
requested value; the camera device will report the current (intermediate)
aperture size in capture result metadata while the aperture is changing.
While the aperture is still changing, android.lens.state
will be set to MOVING.
When this is supported and android.control.aeMode
is one of
the ON modes, this will be overridden by the camera device
auto-exposure algorithm, the overridden values are then provided
back to the user in the corresponding result.
State of lens neutral density filter(s).
This will not be supported on most camera devices. On devices
where this is supported, this may only be set to one of the
values included in android.lens.info.availableFilterDensities
.
Lens filters are typically used to lower the amount of light the sensor is exposed to (measured in steps of EV). As used here, an EV step is the standard logarithmic representation, which are non-negative, and inversely proportional to the amount of light hitting the sensor. For example, setting this to 0 would result in no reduction of the incoming light, and setting this to 2 would mean that the filter is set to reduce incoming light by two stops (allowing 1/4 of the prior amount of light to the sensor).
It may take several frames before the lens filter density changes
to the requested value. While the filter density is still changing,
android.lens.state
will be set to MOVING.
The current lens focal length; used for optical zoom.
This setting controls the physical focal length of the camera device's lens. Changing the focal length changes the field of view of the camera device, and is usually used for optical zoom.
Like android.lens.focusDistance
and android.lens.aperture
, this
setting won't be applied instantaneously, and it may take several
frames before the lens can change to the requested focal length.
While the focal length is still changing, android.lens.state
will
be set to MOVING.
This is expected not to be supported on most devices.
Distance to plane of sharpest focus, measured from frontmost surface of the lens.
0 means infinity focus. Used value will be clamped
to [0, android.lens.info.minimumFocusDistance
].
Like android.lens.focalLength
, this setting won't be applied
instantaneously, and it may take several frames before the lens
can move to the requested focus distance. While the lens is still moving,
android.lens.state
will be set to MOVING.
Sets whether the camera device uses optical image stabilization (OIS) when capturing images.
OIS is used to compensate for motion blur due to small
movements of the camera during capture. Unlike digital image
stabilization (android.control.videoStabilizationMode
), OIS
makes use of mechanical elements to stabilize the camera
sensor, and thus allows for longer exposure times before
camera shake becomes apparent.
Not all devices will support OIS; see
android.lens.info.availableOpticalStabilization
for
available controls.
Mode of operation for the noise reduction algorithm.
Noise filtering control. OFF means no noise reduction will be applied by the camera device.
This must be set to a valid mode from
android.noiseReduction.availableNoiseReductionModes
.
FAST/HIGH_QUALITY both mean camera device determined noise filtering will be applied. HIGH_QUALITY mode indicates that the camera device will use the highest-quality noise filtering algorithms, even if it slows down capture rate. FAST means the camera device will not slow down capture rate when applying noise filtering.
The region of the sensor to read out for this capture.
The crop region coordinate system is based off
android.sensor.info.activeArraySize
, with (0, 0)
being the
top-left corner of the sensor active array.
Output streams use this rectangle to produce their output, cropping to a smaller region if necessary to maintain the stream's aspect ratio, then scaling the sensor input to match the output's configured resolution.
The crop region is applied after the RAW to other color space (e.g. YUV) conversion. Since raw streams (e.g. RAW16) don't have the conversion stage, they are not croppable. The crop region will be ignored by raw streams.
For non-raw streams, any additional per-stream cropping will be done to maximize the final pixel area of the stream.
For example, if the crop region is set to a 4:3 aspect ratio, then 4:3 streams will use the exact crop region. 16:9 streams will further crop vertically (letterbox).
Conversely, if the crop region is set to a 16:9, then 4:3 outputs will crop horizontally (pillarbox), and 16:9 streams will match exactly. These additional crops will be centered within the crop region.
The width and height of the crop region cannot
be set to be smaller than
floor( activeArraySize.width /
and
android.scaler.availableMaxDigitalZoom
)floor( activeArraySize.height /
, respectively.android.scaler.availableMaxDigitalZoom
)
The camera device may adjust the crop region to account for rounding and other hardware requirements; the final crop region used will be included in the output capture result.
Duration each pixel is exposed to light.
If the sensor can't expose this exact duration, it should shorten the duration exposed to the nearest possible value (rather than expose longer).
Duration from start of frame exposure to start of next frame exposure.
The maximum frame rate that can be supported by a camera subsystem is a function of many factors:
Since these factors can vary greatly between different ISPs and sensors, the camera abstraction tries to represent the bandwidth restrictions with as simple a model as possible.
The model presented has the following characteristics:
The necessary information for the application, given the model above,
is provided via the android.scaler.streamConfigurationMap
field
using StreamConfigurationMap#getOutputMinFrameDuration(int, Size).
These are used to determine the maximum frame rate / minimum frame
duration that is possible for a given stream configuration.
Specifically, the application can use the following rules to determine the minimum frame duration it can request from the camera device:
S
.S
, by
looking it up in android.scaler.streamConfigurationMap
using
StreamConfigurationMap#getOutputMinFrameDuration(int, Size) (with
its respective size/format). Let this set of frame durations be called
F
.R
, the minimum frame duration allowed
for R
is the maximum out of all values in F
. Let the streams
used in R
be called S_r
.If none of the streams in S_r
have a stall time (listed in
StreamConfigurationMap#getOutputStallDuration(int,Size) using its
respective size/format), then the frame duration in
F
determines the steady state frame rate that the application will
get if it uses R
as a repeating request. Let this special kind
of request be called Rsimple
.
A repeating request Rsimple
can be occasionally interleaved
by a single capture of a new request Rstall
(which has at least
one in-use stream with a non-0 stall time) and if Rstall
has the
same minimum frame duration this will not cause a frame rate loss
if all buffers from the previous Rstall
have already been
delivered.
For more details about stalling, see StreamConfigurationMap#getOutputStallDuration(int,Size).
The amount of gain applied to sensor data before processing.
The sensitivity is the standard ISO sensitivity value, as defined in ISO 12232:2006.
The sensitivity must be within android.sensor.info.sensitivityRange
, and
if if it less than android.sensor.maxAnalogSensitivity
, the camera device
is guaranteed to use only analog amplification for applying the gain.
If the camera device cannot apply the exact sensitivity requested, it will reduce the gain to the nearest supported value. The final sensitivity used will be available in the output capture result.
A pixel [R, G_even, G_odd, B]
that supplies the test pattern
when android.sensor.testPatternMode
is SOLID_COLOR.
Each color channel is treated as an unsigned 32-bit integer. The camera device then uses the most significant X bits that correspond to how many bits are in its Bayer raw sensor output.
For example, a sensor with RAW10 Bayer output would use the 10 most significant bits from each color channel.
Optional - This value may be null
on some devices.
When enabled, the sensor sends a test pattern instead of doing a real exposure from the camera.
When a test pattern is enabled, all manual sensor controls specified by android.sensor.* will be ignored. All other controls should work as normal.
For example, if manual flash is enabled, flash firing should still occur (and that the test pattern remain unmodified, since the flash would not actually affect it).
Optional - This value may be null
on some devices.
Quality of lens shading correction applied to the image data.
When set to OFF mode, no lens shading correction will be applied by the
camera device, and an identity lens shading map data will be provided
if
. For example, for lens
shading map with size specified as android.statistics.lensShadingMapMode
== ONandroid.lens.info.shadingMapSize = [ 4, 3 ]
,
the output android.statistics.lensShadingMap for this case will be an identity map
shown below:
[ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ]
When set to other modes, lens shading correction will be applied by the
camera device. Applications can request lens shading map data by setting
android.statistics.lensShadingMapMode
to ON, and then the camera device will provide
lens shading map data in android.statistics.lensShadingMap, with size specified
by android.lens.info.shadingMapSize; the returned shading map data will be the one
applied by the camera device for this capture request.
The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore the reliability
of the map data may be affected by the AE and AWB algorithms. When AE and AWB are in
AUTO modes(android.control.aeMode
!=
OFF and android.control.awbMode
!=
OFF),
to get best results, it is recommended that the applications wait for the AE and AWB to
be converged before using the returned shading map data.
Control for the face detector unit.
Whether face detection is enabled, and whether it
should output just the basic fields or the full set of
fields. Value must be one of the
android.statistics.info.availableFaceDetectModes
.
Operating mode for hotpixel map generation.
If set to ON, a hotpixel map is returned in android.statistics.hotPixelMap
.
If set to OFF, no hotpixel map will be returned.
This must be set to a valid mode from android.statistics.info.availableHotPixelMapModes
.
Whether the camera device will output the lens shading map in output result metadata.
When set to ON, android.statistics.lensShadingMap will be provided in the output result metadata.
Tonemapping / contrast / gamma curve to use when android.tonemap.mode
is CONTRAST_CURVE.
The tonemapCurve consist of three curves for each of red, green, and blue channels respectively. The following example uses the red channel as an example. The same logic applies to green and blue channel. Each channel's curve is defined by an array of control points:
curveRed =
[ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ]
2 <= N <= android.tonemap.maxCurvePoints
These are sorted in order of increasing Pin
; it is always
guaranteed that input values 0.0 and 1.0 are included in the list to
define a complete mapping. For input values between control points,
the camera device must linearly interpolate between the control
points.
Each curve can have an independent number of points, and the number
of points can be less than max (that is, the request doesn't have to
always provide a curve with number of points equivalent to
android.tonemap.maxCurvePoints
).
A few examples, and their corresponding graphical mappings; these only specify the red channel and the precision is limited to 4 digits, for conciseness.
Linear mapping:
curveRed = [ (0, 0), (1.0, 1.0) ]
Invert mapping:
curveRed = [ (0, 1.0), (1.0, 0) ]
Gamma 1/2.2 mapping, with 16 control points:
curveRed = [
(0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812),
(0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072),
(0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685),
(0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ]
Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:
curveRed = [
(0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845),
(0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130),
(0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721),
(0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ]
High-level global contrast/gamma/tonemapping control.
When switching to an application-defined contrast curve by setting
android.tonemap.mode
to CONTRAST_CURVE, the curve is defined
per-channel with a set of (in, out)
points that specify the
mapping from input high-bit-depth pixel value to the output
low-bit-depth value. Since the actual pixel ranges of both input
and output may change depending on the camera pipeline, the values
are specified by normalized floating-point numbers.
More-complex color mapping operations such as 3D color look-up
tables, selective chroma enhancement, or other non-linear color
transforms will be disabled when android.tonemap.mode
is
CONTRAST_CURVE.
This must be set to a valid mode in
android.tonemap.availableToneMapModes
.
When using either FAST or HIGH_QUALITY, the camera device will
emit its own tonemap curve in android.tonemap.curve
.
These values are always available, and as close as possible to the
actually used nonlinear/nonglobal transforms.
If a request is sent with CONTRAST_CURVE with the camera device's provided curve in FAST or HIGH_QUALITY, the image's tonemap will be roughly the same.
Describe the kinds of special objects contained in this Parcelable's marshalled representation.
Determine whether this CaptureRequest is equal to another CaptureRequest.
A request is considered equal to another is if it's set of key/values is equal, it's list of output surfaces is equal, and the user tag is equal.
other | Another instance of CaptureRequest. |
---|
Get a capture request field value.
The field definitions can be found in CaptureRequest
.
Querying the value for the same key more than once will return a value which is equal to the previous queried value.
key | The result field to read. |
---|
null
if the field is not set.
IllegalArgumentException | if the key was not valid |
---|
Returns a list of the keys contained in this map.
The list returned is not modifiable, so any attempts to modify it will throw
a UnsupportedOperationException
.
All values retrieved by a key from this list with #get
are guaranteed to be
non-null
. Each key is only listed once in the list. The order of the keys
is undefined.
Retrieve the tag for this request, if any.
This tag is not used for anything by the camera device, but can be
used by an application to easily identify a CaptureRequest when it is
returned by
CaptureListener.onCaptureCompleted
null
if
no tag has been set.Returns an integer hash code for this object. By contract, any two
objects for which equals(Object)
returns true
must return
the same hash code value. This means that subclasses of Object
usually override both methods or neither method.
Note that hash values must not change over time unless information used in equals comparisons also changes.
See Writing a correct
hashCode
method
if you intend implementing your own hashCode
method.
Flatten this object in to a Parcel.
dest | The Parcel in which the object should be written. |
---|---|
flags | Additional flags about how the object should be written.
May be 0 or PARCELABLE_WRITE_RETURN_VALUE .
|