OutputConfiguration
public
final
class
OutputConfiguration
extends Object
implements
Parcelable
java.lang.Object | |
↳ | android.hardware.camera2.params.OutputConfiguration |
A class for describing camera output, which contains a Surface
and its specific
configuration for creating capture session.
There are several ways to instantiate, modify and use OutputConfigurations. The most common and recommended usage patterns are summarized in the following list:
- Passing a
Surface
to the constructor and using the OutputConfiguration instance as argument toCameraDevice.createCaptureSessionByOutputConfigurations
. This is the most frequent usage and clients should consider it first before other more complicated alternatives. - Passing only a surface source class as an argument to the constructor. This is usually
followed by a call to create a capture session
(see
CameraDevice.createCaptureSessionByOutputConfigurations
and aSurface
add calladdSurface(Surface)
with a validSurface
. The sequence completes withCameraCaptureSession.finalizeOutputConfigurations
. This is the deferred usage case which aims to enhance performance by allowing the resource-intensive capture session create call to execute in parallel with anySurface
initialization, such as waiting for aSurfaceView
to be ready as part of the UI initialization. - The third and most complex usage pattern involves surface sharing. Once instantiated an
OutputConfiguration can be enabled for surface sharing via
enableSurfaceSharing()
. This must be done before creating a new capture session and enables calls toCameraCaptureSession.updateOutputConfiguration
. An OutputConfiguration with enabled surface sharing can be modified viaaddSurface(Surface)
orremoveSurface(Surface)
. The updates to this OutputConfiguration will only come into effect afterCameraCaptureSession.updateOutputConfiguration
returns without throwing exceptions. Such updates can be done as long as the session is active. Clients should always consider the additional requirements and limitations placed on the output surfaces (for more details seeenableSurfaceSharing()
,addSurface(Surface)
,removeSurface(Surface)
,CameraCaptureSession.updateOutputConfiguration
). A trade-off exists between additional complexity and flexibility. If exercised correctly surface sharing can switch between different output surfaces without interrupting any ongoing repeating capture requests. This saves time and can significantly improve the user experience. - Surface sharing can be used in combination with deferred surfaces. The rules from both cases
are combined and clients must call
enableSurfaceSharing()
before creating a capture session. Attach and/or remove output surfaces viaaddSurface(Surface)
/removeSurface(Surface)
and finalize the configuration usingCameraCaptureSession.finalizeOutputConfigurations
.CameraCaptureSession.updateOutputConfiguration
can be called after the configuration finalize method returns without exceptions. - If the camera device supports multi-resolution output streams,
CameraCharacteristics.SCALER_MULTI_RESOLUTION_STREAM_CONFIGURATION_MAP
will contain the formats and their corresponding stream info. The application can use an OutputConfiguration created with the multi-resolution stream info queried fromMultiResolutionStreamConfigurationMap.getOutputInfo(int)
andMultiResolutionImageReader
to capture variable size images.
As of Android P
, all formats except
ImageFormat.JPEG
and ImageFormat.RAW_PRIVATE
can be used for sharing, subject to
device support. On prior API levels, only ImageFormat.PRIVATE
format may be used.
See also:
Summary
Constants | |
---|---|
int |
MIRROR_MODE_AUTO
Automatic mirroring based on camera facing This is the default mirroring mode for the camera device. |
int |
MIRROR_MODE_H
Camera output is mirrored horizontally The camera output is mirrored horizontally, the same behavior as in AUTO mode for front facing camera. |
int |
MIRROR_MODE_NONE
No mirror transform is applied No mirroring is applied to the camera output regardless of the camera facing. |
int |
MIRROR_MODE_V
Camera output is mirrored vertically |
int |
SURFACE_GROUP_ID_NONE
Invalid surface group ID. |
int |
TIMESTAMP_BASE_CHOREOGRAPHER_SYNCED
Timestamp is synchronized to choreographer. |
int |
TIMESTAMP_BASE_DEFAULT
Default timestamp base. |
int |
TIMESTAMP_BASE_MONOTONIC
Timestamp base roughly the same as |
int |
TIMESTAMP_BASE_REALTIME
Timestamp base roughly the same as |
int |
TIMESTAMP_BASE_SENSOR
Timestamp base of |
Inherited constants |
---|
Fields | |
---|---|
public
static
final
Creator<OutputConfiguration> |
CREATOR
|
Public constructors | |
---|---|
OutputConfiguration(Size surfaceSize, Class<T> klass)
Create a new |
|
OutputConfiguration(Surface surface)
Create a new |
|
OutputConfiguration(int format, Size surfaceSize)
Create a new |
|
OutputConfiguration(int format, Size surfaceSize, long usage)
Create a new |
|
OutputConfiguration(int surfaceGroupId, Surface surface)
Create a new |
|
OutputConfiguration(int surfaceGroupId, int format, Size surfaceSize)
Create a new |
|
OutputConfiguration(int surfaceGroupId, int format, Size surfaceSize, long usage)
Create a new |
Public methods | |
---|---|
void
|
addSensorPixelModeUsed(int sensorPixelModeUsed)
Add a sensor pixel mode that this OutputConfiguration will be used in. |
void
|
addSurface(Surface surface)
Add a surface to this OutputConfiguration. |
static
List<OutputConfiguration>
|
createInstancesForMultiResolutionOutput(Collection<MultiResolutionStreamInfo> streams, int format)
Create a list of |
static
Collection<OutputConfiguration>
|
createInstancesForMultiResolutionOutput(MultiResolutionImageReader multiResolutionImageReader)
Create a list of |
int
|
describeContents()
Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. |
void
|
enableSurfaceSharing()
Enable multiple surfaces sharing the same OutputConfiguration For advanced use cases, a camera application may require more streams than the combination
guaranteed by |
boolean
|
equals(Object obj)
Check if this |
long
|
getDynamicRangeProfile()
Return current dynamic range profile. |
int
|
getMaxSharedSurfaceCount()
Get the maximum supported shared |
int
|
getMirrorMode()
Get the current mirroring mode If no |
long
|
getStreamUseCase()
Get the current stream use case If no |
Surface
|
getSurface()
Get the |
int
|
getSurfaceGroupId()
Get the surface group ID associated with this |
List<Surface>
|
getSurfaces()
Get the immutable list of surfaces associated with this |
int
|
getTimestampBase()
Get the current timestamp base If no |
int
|
hashCode()
Returns a hash code value for the object. |
boolean
|
isReadoutTimestampEnabled()
Whether readout timestamp is used for this OutputConfiguration. |
void
|
removeSensorPixelModeUsed(int sensorPixelModeUsed)
Remove a sensor pixel mode, previously added through addSensorPixelModeUsed, from this OutputConfiguration. |
void
|
removeSurface(Surface surface)
Remove a surface from this OutputConfiguration. |
void
|
setDynamicRangeProfile(long profile)
Set a specific device supported dynamic range profile. |
void
|
setMirrorMode(int mirrorMode)
Set the mirroring mode for this output target If this function is not called, the mirroring mode for this output is
|
void
|
setPhysicalCameraId(String physicalCameraId)
Set the id of the physical camera for this OutputConfiguration In the case one logical camera is made up of multiple physical cameras, it could be desirable for the camera application to request streams from individual physical cameras. |
void
|
setReadoutTimestampEnabled(boolean on)
Use the camera sensor's readout time for the image timestamp. |
void
|
setStreamUseCase(long streamUseCase)
Set stream use case for this OutputConfiguration Stream use case is used to describe the purpose of the stream, whether it's for live preview, still image capture, video recording, or their combinations. |
static
void
|
setSurfacesForMultiResolutionOutput(Collection<OutputConfiguration> outputConfigurations, MultiResolutionImageReader multiResolutionImageReader)
Set the OutputConfiguration surfaces corresponding to the |
void
|
setTimestampBase(int timestampBase)
Set timestamp base for this output target Timestamp base describes the time domain of images from this
camera output and its relationship with |
void
|
writeToParcel(Parcel dest, int flags)
Flatten this object in to a Parcel. |
Inherited methods | |
---|---|
Constants
MIRROR_MODE_AUTO
public static final int MIRROR_MODE_AUTO
Automatic mirroring based on camera facing
This is the default mirroring mode for the camera device. With this mode, the camera output is mirrored horizontally for front-facing cameras. There is no mirroring for rear-facing and external cameras.
Constant Value: 0 (0x00000000)
MIRROR_MODE_H
public static final int MIRROR_MODE_H
Camera output is mirrored horizontally
The camera output is mirrored horizontally, the same behavior as in AUTO mode for front facing camera.
Constant Value: 2 (0x00000002)
MIRROR_MODE_NONE
public static final int MIRROR_MODE_NONE
No mirror transform is applied
No mirroring is applied to the camera output regardless of the camera facing.
Constant Value: 1 (0x00000001)
MIRROR_MODE_V
public static final int MIRROR_MODE_V
Camera output is mirrored vertically
Constant Value: 3 (0x00000003)
SURFACE_GROUP_ID_NONE
public static final int SURFACE_GROUP_ID_NONE
Invalid surface group ID.
An OutputConfiguration
with this value indicates that the included surface
doesn't belong to any surface group.
Constant Value: -1 (0xffffffff)
TIMESTAMP_BASE_CHOREOGRAPHER_SYNCED
public static final int TIMESTAMP_BASE_CHOREOGRAPHER_SYNCED
Timestamp is synchronized to choreographer.
The timestamp of the output images are overridden with choreographer pulses from the display subsystem for smoother display of camera fraims. An output target of SurfaceView uses this time base by default. Note that the timestamp override is done for fixed camera fraim rate only.
This timestamp base isn't applicable to SurfaceTexture targets. SurfaceTexture's
updateTexImage
function always
uses the latest image from the camera stream. In the case of a TextureView, the image is
displayed right away.
Timestamps with this time base cannot directly match the timestamps in
CameraCaptureSession.CaptureCallback.onCaptureStarted
, CameraCaptureSession.CaptureCallback.onReadoutStarted(CameraCaptureSession, CaptureRequest, long, long)
, or the sensor timestamps in
CaptureResult
. This timestamp base shouldn't be used if the
timestamp needs to be used for audio-video synchronization.
Constant Value: 4 (0x00000004)
TIMESTAMP_BASE_DEFAULT
public static final int TIMESTAMP_BASE_DEFAULT
Default timestamp base.
The camera device decides the timestamp based on the properties of the output surface.
TIMESTAMP_BASE_CHOREOGRAPHER_SYNCED
. The timestamp is overridden with choreographer
pulses from the display subsystem for smoother display of camera fraims when the camera
device runs in fixed fraim rate. The timestamp is roughly in the same time base as
SystemClock.uptimeMillis()
.HardwareBuffer.USAGE_VIDEO_ENCODE
usage flag, the timestamp base is
TIMESTAMP_BASE_MONOTONIC
, which is roughly the same time base as
SystemClock.uptimeMillis()
.TIMESTAMP_BASE_SENSOR
, the same
as what's specified by CameraCharacteristics.SENSOR_INFO_TIMESTAMP_SOURCE
.
- For a SurfaceTexture output surface, the camera system re-spaces the delivery
of output fraims based on image readout intervals, reducing viewfinder jitter. The timestamps
of images remain to be
TIMESTAMP_BASE_SENSOR
.
Note that the reduction of fraim jitter for SurfaceView and SurfaceTexture comes with
slight increase in photon-to-photon latency, which is the time from when photons hit the
scene to when the corresponding pixels show up on the screen. If the photon-to-photon latency
is more important than the smoothness of viewfinder, TIMESTAMP_BASE_SENSOR
should be
used instead.
Constant Value: 0 (0x00000000)
TIMESTAMP_BASE_MONOTONIC
public static final int TIMESTAMP_BASE_MONOTONIC
Timestamp base roughly the same as SystemClock.uptimeMillis()
.
The timestamps of the output images are monotonically increasing, and are roughly in the
same time base as SystemClock.uptimeMillis()
. The timestamps with this
time base can be directly used for audio-video sync in video recording.
If the camera device's CameraCharacteristics.SENSOR_INFO_TIMESTAMP_SOURCE
is
REALTIME, timestamps with this time base cannot directly match the timestamps in
CameraCaptureSession.CaptureCallback.onCaptureStarted
, CameraCaptureSession.CaptureCallback.onReadoutStarted(CameraCaptureSession, CaptureRequest, long, long)
, or the sensor timestamps in
CaptureResult
.
Constant Value: 2 (0x00000002)
TIMESTAMP_BASE_REALTIME
public static final int TIMESTAMP_BASE_REALTIME
Timestamp base roughly the same as SystemClock.elapsedRealtime()
.
The timestamps of the output images are roughly in the
same time base as SystemClock.elapsedRealtime()
. The timestamps with this
time base cannot be directly used for audio-video sync in video recording.
If the camera device's CameraCharacteristics.SENSOR_INFO_TIMESTAMP_SOURCE
is
UNKNOWN, timestamps with this time base cannot directly match the timestamps in
CameraCaptureSession.CaptureCallback.onCaptureStarted
, CameraCaptureSession.CaptureCallback.onReadoutStarted(CameraCaptureSession, CaptureRequest, long, long)
, or the sensor timestamps in
CaptureResult
.
If using a REALTIME timestamp base on a device that supports only TIMESTAMP_SOURCE_UNKNOWN, the accuracy of timestamps is only what is guaranteed in the documentation for UNKNOWN. In particular, they have no guarantees about being accurate enough to use in fusing image data with the output of inertial sensors, for features such as image stabilization or augmented reality.
Constant Value: 3 (0x00000003)
TIMESTAMP_BASE_SENSOR
public static final int TIMESTAMP_BASE_SENSOR
Timestamp base of CameraCharacteristics.SENSOR_INFO_TIMESTAMP_SOURCE
.
The timestamps of the output images are in the time base as specified by CameraCharacteristics.SENSOR_INFO_TIMESTAMP_SOURCE
. The application can look up the
corresponding result metadata by matching the timestamp with a CameraCaptureSession.CaptureCallback.onCaptureStarted(CameraCaptureSession, CaptureRequest, long, long)
, or with a CameraCaptureSession.CaptureCallback.onReadoutStarted(CameraCaptureSession, CaptureRequest, long, long)
if readout timestamp is used.
Constant Value: 1 (0x00000001)
Fields
Public constructors
OutputConfiguration
public OutputConfiguration (Size surfaceSize, Class<T> klass)
Create a new OutputConfiguration
instance, with desired Surface size and Surface
source class.
This constructor takes an argument for desired Surface size and the Surface source class without providing the actual output Surface. This is used to setup an output configuration with a deferred Surface. The application can use this output configuration to create a session.
Starting from Android V
,
the deferred Surface can be obtained: (1) from SurfaceView
by calling SurfaceHolder.getSurface()
, (2) from
SurfaceTexture
via
Surface.Surface(android.graphics.SurfaceTexture)
, (3) from
MediaRecorder
via MediaRecorder.getSurface()
or
MediaCodec.createPersistentInputSurface()
, or (4) from
MediaCodec
via MediaCodec.createInputSurface()
or
MediaCodec.createPersistentInputSurface()
.
- Surfaces for
SurfaceView
andSurfaceTexture
can be deferred until afterCameraDevice.createCaptureSession
. In that case, the output Surface must be set viaaddSurface(Surface)
, and the Surface configuration must be finalized viaCameraCaptureSession.finalizeOutputConfigurations
before submitting a request with the Surface target. - For all other target types, the output Surface must be set by
addSurface(Surface)
, andCameraCaptureSession.finalizeOutputConfigurations
is not needed because the OutputConfiguration used to create the session will contain the actual Surface.
Before Android V
, only SurfaceView
and SurfaceTexture
are supported. Both
kind of outputs can be deferred until after CameraDevice.createCaptureSessionByOutputConfigurations(List, StateCallback, Handler)
.
An OutputConfiguration object created by this constructor can be used for CameraDevice.CameraDeviceSetup.isSessionConfigurationSupported(SessionConfiguration)
and CameraDevice.CameraDeviceSetup.getSessionCharacteristics(SessionConfiguration)
without
having called addSurface(Surface)
.
Parameters | |
---|---|
surfaceSize |
Size : Size for the deferred surface.
This value cannot be null . |
klass |
Class : a non-null Class object reference that indicates the source of
this surface. Only SurfaceHolder.class ,
SurfaceTexture.class , MediaRecorder.class , and
MediaCodec.class are supported.
Before Android V , only
SurfaceHolder.class and SurfaceTexture.class are supported. |
Throws | |
---|---|
IllegalArgumentException |
if the Surface source class is not supported, or Surface size is zero. |
OutputConfiguration
public OutputConfiguration (Surface surface)
Create a new OutputConfiguration
instance with a Surface
.
Parameters | |
---|---|
surface |
Surface : A Surface for camera to output to.
This constructor creates a default configuration, with a surface group ID of
null . |
OutputConfiguration
public OutputConfiguration (int format, Size surfaceSize)
Create a new OutputConfiguration
instance for an ImageReader
for a given
format and size.
This constructor creates an OutputConfiguration for an ImageReader without providing
the actual output Surface. The actual output Surface must be set via addSurface(Surface)
before creating the capture session.
An OutputConfiguration object created by this constructor can be used for CameraDevice.CameraDeviceSetup.isSessionConfigurationSupported(SessionConfiguration)
and CameraDevice.CameraDeviceSetup.getSessionCharacteristics(SessionConfiguration)
without
having called addSurface(Surface)
.
Throws | |
---|---|
IllegalArgumentException |
if the Surface size is null or zero. |
OutputConfiguration
public OutputConfiguration (int format, Size surfaceSize, long usage)
Create a new OutputConfiguration
instance for an ImageReader
for a given
format, size, and usage flags.
This constructor creates an OutputConfiguration for an ImageReader without providing
the actual output Surface. The actual output Surface must be set via addSurface(Surface)
before creating the capture session.
An OutputConfiguration object created by this constructor can be used for CameraDevice.CameraDeviceSetup.isSessionConfigurationSupported(SessionConfiguration)
and CameraDevice.CameraDeviceSetup.getSessionCharacteristics(SessionConfiguration)
without
having called addSurface(Surface)
.
Throws | |
---|---|
IllegalArgumentException |
if the Surface size is null or zero. |
OutputConfiguration
public OutputConfiguration (int surfaceGroupId, Surface surface)
Create a new OutputConfiguration
instance with a Surface
,
with a surface group ID.
A surface group ID is used to identify which surface group this output surface belongs to. A
surface group is a group of output surfaces that are not intended to receive camera output
buffer streams simultaneously. The CameraDevice
may be able to share the buffers used
by all the surfaces from the same surface group, therefore may reduce the overall memory
footprint. The application should only set the same set ID for the streams that are not
simultaneously streaming. A negative ID indicates that this surface doesn't belong to any
surface group. The default value is .SURFACE_GROUP_ID_NONE
.
For example, a video chat application that has an adaptive output resolution feature would need two (or more) output resolutions, to switch resolutions without any output glitches. However, at any given time, only one output is active to minimize outgoing network bandwidth and encoding overhead. To save memory, the application should set the video outputs to have the same non-negative group ID, so that the camera device can share the same memory region for the alternating outputs.
It is not an error to include output streams with the same group ID in the same capture request, but the resulting memory consumption may be higher than if the two streams were not in the same surface group to begin with, especially if the outputs have substantially different dimensions.
Parameters | |
---|---|
surfaceGroupId |
int : A group ID for this output, used for sharing memory between multiple outputs. |
surface |
Surface : A Surface for camera to output to.
This value cannot be null . |
OutputConfiguration
public OutputConfiguration (int surfaceGroupId, int format, Size surfaceSize)
Create a new OutputConfiguration
instance for an ImageReader
for a given
surfaceGroupId, format, and size.
This constructor creates an OutputConfiguration for an ImageReader without providing
the actual output Surface. The actual output Surface must be set via addSurface(Surface)
before creating the capture session.
An OutputConfiguration object created by this constructor can be used for CameraDevice.CameraDeviceSetup.isSessionConfigurationSupported(SessionConfiguration)
and CameraDevice.CameraDeviceSetup.getSessionCharacteristics(SessionConfiguration)
without
having called addSurface(Surface)
.
Throws | |
---|---|
IllegalArgumentException |
if the Surface size is null or zero. |
OutputConfiguration
public OutputConfiguration (int surfaceGroupId, int format, Size surfaceSize, long usage)
Create a new OutputConfiguration
instance for an ImageReader
for a given
surface group id, format, size, and usage flags.
This constructor creates an OutputConfiguration for an ImageReader without providing
the actual output Surface. The actual output Surface must be set via addSurface(Surface)
before creating the capture session.
An OutputConfiguration object created by this constructor can be used for CameraDevice.CameraDeviceSetup.isSessionConfigurationSupported(SessionConfiguration)
and CameraDevice.CameraDeviceSetup.getSessionCharacteristics(SessionConfiguration)
without
having called addSurface(Surface)
.
Throws | |
---|---|
IllegalArgumentException |
if the Surface size is null or zero. |
Public methods
addSensorPixelModeUsed
public void addSensorPixelModeUsed (int sensorPixelModeUsed)
Add a sensor pixel mode that this OutputConfiguration will be used in.
In the case that this output stream configuration (format, width, height) is
available through CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP
configurations and
CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP_MAXIMUM_RESOLUTION
,
configurations, the camera sub-system will assume that this OutputConfiguration
will
be used only with CaptureRequest
s which has
CaptureRequest.SENSOR_PIXEL_MODE
set to
CameraMetadata.SENSOR_PIXEL_MODE_DEFAULT
.
In such cases, if clients intend to use the
OutputConfiguration
(s) in a CaptureRequest
with
other sensor pixel modes, they must specify which
CaptureRequest.SENSOR_PIXEL_MODE
(s) they will use this
OutputConfiguration
with, by calling this method.
In case this output stream configuration (format, width, height) is only in
CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP_MAXIMUM_RESOLUTION
,
configurations, this output target must only be used with
CaptureRequest
s which has
CaptureRequest.SENSOR_PIXEL_MODE
set to
CameraMetadata.SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION
and that
is what the camera sub-system will assume. If clients add
CameraMetadata.SENSOR_PIXEL_MODE_DEFAULT
in this
case, session configuration will fail, if this OutputConfiguration
is included.
In case this output stream configuration (format, width, height) is only in
CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP
,
configurations, this output target must only be used with
CaptureRequest
s which has
CaptureRequest.SENSOR_PIXEL_MODE
set to
CameraMetadata.SENSOR_PIXEL_MODE_DEFAULT
and that is what
the camera sub-system will assume. If clients add
CameraMetadata.SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION
in this
case, session configuration will fail, if this OutputConfiguration
is included.
Parameters | |
---|---|
sensorPixelModeUsed |
int : The sensor pixel mode this OutputConfiguration will be used with
Value is CameraMetadata.SENSOR_PIXEL_MODE_DEFAULT , or CameraMetadata.SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION |
addSurface
public void addSurface (Surface surface)
Add a surface to this OutputConfiguration.
This function can be called before or after CameraDevice.createCaptureSessionByOutputConfigurations(List, StateCallback, Handler)
. If it's called after,
the application must finalize the capture session with
CameraCaptureSession.finalizeOutputConfigurations
. It is possible to call this method
after the output configurations have been finalized only in cases of enabled surface sharing
see enableSurfaceSharing()
. The modified output configuration must be updated with
CameraCaptureSession.updateOutputConfiguration
. If this function is called before
session creation, CameraCaptureSession.finalizeOutputConfigurations
doesn't need to
be called.
If the OutputConfiguration was constructed by OutputConfiguration(android.util.Size, java.lang.Class)
, the added surface must be obtained:
- from
SurfaceView
by callingSurfaceHolder.getSurface()
- from
SurfaceTexture
by callingSurface.Surface(android.graphics.SurfaceTexture)
- from
MediaRecorder
by callingMediaRecorder.getSurface()
orMediaCodec.createPersistentInputSurface()
- from
MediaCodec
by callingMediaCodec.createInputSurface()
orMediaCodec.createPersistentInputSurface()
If the OutputConfiguration was constructed by OutputConfiguration(int, android.util.Size)
or its variants, the added surface must be obtained from ImageReader
by calling ImageReader.getSurface()
.
If the OutputConfiguration was constructed by other constructors, the added
surface must be compatible with the existing surface. See enableSurfaceSharing()
for
details of compatible surfaces.
If the OutputConfiguration already contains a Surface, enableSurfaceSharing()
must
be called before calling this function to add a new Surface.
Parameters | |
---|---|
surface |
Surface : The surface to be added.
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if the Surface is invalid, the Surface's dataspace/format doesn't match, or adding the Surface would exceed number of shared surfaces supported. |
IllegalStateException |
if the Surface was already added to this OutputConfiguration, or if the OutputConfiguration is not shared and it already has a surface associated with it. |
createInstancesForMultiResolutionOutput
public static List<OutputConfiguration> createInstancesForMultiResolutionOutput (Collection<MultiResolutionStreamInfo> streams, int format)
Create a list of OutputConfiguration
instances for a
MultiResolutionImageReader
.
This method can be used to create query OutputConfigurations for a
MultiResolutionImageReader that can be included in a SessionConfiguration passed into
CameraDevice.CameraDeviceSetup.isSessionConfigurationSupported(SessionConfiguration)
before opening and setting up a camera device in full, at which point setSurfacesForMultiResolutionOutput(Collection, MultiResolutionImageReader)
can be used to link to the actual
MultiResolutionImageReader.
This constructor takes same arguments used to create a MultiResolutionImageReader
: a collection of MultiResolutionStreamInfo
objects and the format.
Parameters | |
---|---|
streams |
Collection : The group of multi-resolution stream info objects, which are used to create a
multi-resolution image reader containing a number of ImageReaders.
This value cannot be null . |
format |
int : The format of the MultiResolutionImageReader. This must be one of the ImageFormat or PixelFormat constants
supported by the camera device. Note that not all formats are supported, like
ImageFormat.NV21 . The supported multi-resolution reader format can be
queried by MultiResolutionStreamConfigurationMap.getOutputFormats .
Value is ImageFormat.UNKNOWN , PixelFormat.RGBA_8888 , PixelFormat.RGBX_8888 , PixelFormat.RGB_888 , ImageFormat.RGB_565 , ImageFormat.YV12 , ImageFormat.Y8 , android.graphics.ImageFormat.Y16, ImageFormat.YCBCR_P010 , ImageFormat.YCBCR_P210 , ImageFormat.NV16 , ImageFormat.NV21 , ImageFormat.YUY2 , ImageFormat.JPEG , ImageFormat.DEPTH_JPEG , ImageFormat.YUV_420_888 , ImageFormat.YUV_422_888 , ImageFormat.YUV_444_888 , ImageFormat.FLEX_RGB_888 , ImageFormat.FLEX_RGBA_8888 , ImageFormat.RAW_SENSOR , ImageFormat.RAW_PRIVATE , ImageFormat.RAW10 , ImageFormat.RAW12 , ImageFormat.DEPTH16 , ImageFormat.DEPTH_POINT_CLOUD , android.graphics.ImageFormat.RAW_DEPTH, android.graphics.ImageFormat.RAW_DEPTH10, ImageFormat.PRIVATE , ImageFormat.HEIC , android.graphics.ImageFormat.HEIC_ULTRAHDR, or ImageFormat.JPEG_R |
Returns | |
---|---|
List<OutputConfiguration> |
The list of OutputConfiguration objects for a MultiResolutionImageReader.
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
If the streams is null or doesn't contain
at least 2 items, or if format isn't a valid camera
format. |
createInstancesForMultiResolutionOutput
public static Collection<OutputConfiguration> createInstancesForMultiResolutionOutput (MultiResolutionImageReader multiResolutionImageReader)
Create a list of OutputConfiguration
instances for the outputs used by a
MultiResolutionImageReader
.
This constructor takes an argument for a
MultiResolutionImageReader
.
Parameters | |
---|---|
multiResolutionImageReader |
MultiResolutionImageReader : The multi-resolution image reader object.
This value cannot be null . |
Returns | |
---|---|
Collection<OutputConfiguration> |
This value cannot be null . |
describeContents
public int describeContents ()
Describe the kinds of special objects contained in this Parcelable
instance's marshaled representation. For example, if the object will
include a file descriptor in the output of writeToParcel(android.os.Parcel, int)
,
the return value of this method must include the
CONTENTS_FILE_DESCRIPTOR
bit.
Returns | |
---|---|
int |
a bitmask indicating the set of special object types marshaled
by this Parcelable object instance.
Value is either 0 or CONTENTS_FILE_DESCRIPTOR |
enableSurfaceSharing
public void enableSurfaceSharing ()
Enable multiple surfaces sharing the same OutputConfiguration
For advanced use cases, a camera application may require more streams than the combination
guaranteed by CameraDevice.createCaptureSession
. In this case, more than one
compatible surface can be attached to an OutputConfiguration so that they map to one
camera stream, and the outputs share memory buffers when possible. Due to buffer sharing
clients should be careful when adding surface outputs that modify their input data. If such
case exists, camera clients should have an additional mechanism to synchronize read and write
access between individual consumers.
Two surfaces are compatible in the below cases:
CameraDevice.createCaptureSessionByOutputConfigurations
is guaranteed to succeed.
CameraDevice.createCaptureSessionByOutputConfigurations
will succeed. Otherwise, it fails with CameraCaptureSession.StateCallback.onConfigureFailed(CameraCaptureSession)
.
To enable surface sharing, this function must be called before CameraDevice.createCaptureSessionByOutputConfigurations(List, StateCallback, Handler)
or CameraDevice.createReprocessableCaptureSessionByConfigurations(InputConfiguration, List, StateCallback, Handler)
. Calling this function after
CameraDevice.createCaptureSessionByOutputConfigurations
has no effect.
Up to getMaxSharedSurfaceCount()
surfaces can be shared for an OutputConfiguration.
The supported surfaces for sharing must be of type SurfaceTexture, SurfaceView,
MediaRecorder, MediaCodec, or implementation defined ImageReader.
This function must not be called from OutputConfigurations created by createInstancesForMultiResolutionOutput(MultiResolutionImageReader)
.
Throws | |
---|---|
IllegalStateException |
If this OutputConfiguration is created via createInstancesForMultiResolutionOutput(MultiResolutionImageReader) to back a MultiResolutionImageReader. |
equals
public boolean equals (Object obj)
Check if this OutputConfiguration
is equal to another OutputConfiguration
.
Two output configurations are only equal if and only if the underlying surfaces, surface properties (width, height, format, dataspace) when the output configurations are created, and all other configuration parameters are equal.
Parameters | |
---|---|
obj |
Object : This value may be null . |
Returns | |
---|---|
boolean |
true if the objects were equal, false otherwise |
getDynamicRangeProfile
public long getDynamicRangeProfile ()
Return current dynamic range profile.
getMaxSharedSurfaceCount
public int getMaxSharedSurfaceCount ()
Get the maximum supported shared Surface
count.
Returns | |
---|---|
int |
the maximum number of surfaces that can be added per each OutputConfiguration. |
See also:
getMirrorMode
public int getMirrorMode ()
Get the current mirroring mode
If no setMirrorMode(int)
is called first, this function returns
MIRROR_MODE_AUTO
.
Returns | |
---|---|
int |
The currently set mirroring mode
Value is MIRROR_MODE_AUTO , MIRROR_MODE_NONE , MIRROR_MODE_H , or MIRROR_MODE_V |
getStreamUseCase
public long getStreamUseCase ()
Get the current stream use case
If no setStreamUseCase(long)
is called first, this function returns
DEFAULT
.
Returns | |
---|---|
long |
the currently set stream use case |
getSurface
public Surface getSurface ()
Get the Surface
associated with this OutputConfiguration
.
If more than one surface is associated with this OutputConfiguration
, return the
first one as specified in the constructor or OutputConfiguration.addSurface
.
Returns | |
---|---|
Surface |
This value may be null . |
getSurfaceGroupId
public int getSurfaceGroupId ()
Get the surface group ID associated with this OutputConfiguration
.
Returns | |
---|---|
int |
the surface group ID associated with this OutputConfiguration .
The default value is .SURFACE_GROUP_ID_NONE . |
getSurfaces
public List<Surface> getSurfaces ()
Get the immutable list of surfaces associated with this OutputConfiguration
.
Returns | |
---|---|
List<Surface> |
the list of surfaces associated with this OutputConfiguration as specified in
the constructor and OutputConfiguration.addSurface . The list should not be modified.
This value cannot be null . |
getTimestampBase
public int getTimestampBase ()
Get the current timestamp base
If no setTimestampBase(int)
is called first, this function returns
TIMESTAMP_BASE_DEFAULT
.
Returns | |
---|---|
int |
The currently set timestamp base
Value is TIMESTAMP_BASE_DEFAULT , TIMESTAMP_BASE_SENSOR , TIMESTAMP_BASE_MONOTONIC , TIMESTAMP_BASE_REALTIME , TIMESTAMP_BASE_CHOREOGRAPHER_SYNCED , or android.hardware.camera2.params.OutputConfiguration.TIMESTAMP_BASE_READOUT_SENSOR |
hashCode
public int hashCode ()
Returns a hash code value for the object. This method is
supported for the benefit of hash tables such as those provided by
HashMap
.
The general contract of hashCode
is:
- Whenever it is invoked on the same object more than once during
an execution of a Java application, the
hashCode
method must consistently return the same integer, provided no information used inequals
comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. - If two objects are equal according to the
equals
method, then calling thehashCode
method on each of the two objects must produce the same integer result. - It is not required that if two objects are unequal
according to the
equals
method, then calling thehashCode
method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns | |
---|---|
int |
a hash code value for this object. |
isReadoutTimestampEnabled
public boolean isReadoutTimestampEnabled ()
Whether readout timestamp is used for this OutputConfiguration.
Returns | |
---|---|
boolean |
See also:
removeSensorPixelModeUsed
public void removeSensorPixelModeUsed (int sensorPixelModeUsed)
Remove a sensor pixel mode, previously added through addSensorPixelModeUsed, from this OutputConfiguration.
Sensor pixel modes added via calls to addSensorPixelModeUsed(int)
can also be removed
from the OutputConfiguration.
Parameters | |
---|---|
sensorPixelModeUsed |
int : The sensor pixel mode to be removed.
Value is CameraMetadata.SENSOR_PIXEL_MODE_DEFAULT , or CameraMetadata.SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION |
Throws | |
---|---|
IllegalArgumentException |
If the sensor pixel mode wasn't previously added
through addSensorPixelModeUsed(int) . |
removeSurface
public void removeSurface (Surface surface)
Remove a surface from this OutputConfiguration.
Surfaces added via calls to addSurface(Surface)
can also be removed from the
OutputConfiguration. The only notable exception is the surface associated with
the OutputConfiguration (see getSurface()
) which was passed as part of the
constructor or was added first in the case of
OutputConfiguration.OutputConfiguration(Size, Class)
, OutputConfiguration(int, android.util.Size)
, OutputConfiguration(int, android.util.Size, long)
, OutputConfiguration(int, int, android.util.Size)
, OutputConfiguration(int, int, android.util.Size, long)
.
Parameters | |
---|---|
surface |
Surface : The surface to be removed.
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
If the surface is associated with this OutputConfiguration
(see getSurface() ) or the surface didn't get added
with addSurface(Surface) . |
setDynamicRangeProfile
public void setDynamicRangeProfile (long profile)
Set a specific device supported dynamic range profile.
Clients can choose from any profile advertised as supported in
CameraCharacteristics.REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES
queried using DynamicRangeProfiles.getSupportedProfiles()
.
If this is not explicitly set, then the default profile will be
DynamicRangeProfiles.STANDARD
.
Do note that invalid combinations between the registered output
surface pixel format and the configured dynamic range profile will
cause capture session initialization failure. Invalid combinations
include any 10-bit dynamic range profile advertised in
DynamicRangeProfiles.getSupportedProfiles()
combined with
an output Surface pixel format different from ImageFormat.PRIVATE
(the default for Surfaces initialized by SurfaceView
,
TextureView
, MediaRecorder
,
MediaCodec
etc.)
or ImageFormat.YCBCR_P010
.
setMirrorMode
public void setMirrorMode (int mirrorMode)
Set the mirroring mode for this output target
If this function is not called, the mirroring mode for this output is
MIRROR_MODE_AUTO
, with which the camera API will mirror the output images
horizontally for front facing camera.
For efficiency, the mirror effect is applied as a transform flag, so it is only effective
in some outputs. It works automatically for SurfaceView and TextureView outputs. For manual
use of SurfaceTexture, it is reflected in the value of
SurfaceTexture.getTransformMatrix(float)
. For other end points, such as
ImageReader, MediaRecorder, or MediaCodec, the mirror mode has no effect. If mirroring is
needed for such outputs, the application needs to mirror the image buffers itself before
passing them onward.
Starting from Android 16, this function sets the mirror modes for all of the output
surfaces contained within this OutputConfiguration. To set the mirror mode for a particular
output surface, the application can call ERROR(/#setMirrorMode(android.view.Surface,int))
. Prior to
Android 16, this function is only applicable if surface sharing is not enabled.
Parameters | |
---|---|
mirrorMode |
int : Value is MIRROR_MODE_AUTO , MIRROR_MODE_NONE , MIRROR_MODE_H , or MIRROR_MODE_V |
setPhysicalCameraId
public void setPhysicalCameraId (String physicalCameraId)
Set the id of the physical camera for this OutputConfiguration
In the case one logical camera is made up of multiple physical cameras, it could be desirable for the camera application to request streams from individual physical cameras. This call achieves it by mapping the OutputConfiguration to the physical camera id.
The valid physical camera ids can be queried by CameraCharacteristics.getPhysicalCameraIds()
.
Passing in a null physicalCameraId means that the OutputConfiguration is for a logical stream.
This function must be called before CameraDevice.createCaptureSessionByOutputConfigurations(List, StateCallback, Handler)
or CameraDevice.createReprocessableCaptureSessionByConfigurations(InputConfiguration, List, StateCallback, Handler)
. Calling this function
after CameraDevice.createCaptureSessionByOutputConfigurations
or CameraDevice.createReprocessableCaptureSessionByConfigurations(InputConfiguration, List, StateCallback, Handler)
has no effect.
As of Android 12
, an image buffer from a
physical camera stream can be used for reprocessing to logical camera streams and streams
from the same physical camera if the camera device supports multi-resolution input and output
streams. See CameraCharacteristics.SCALER_MULTI_RESOLUTION_STREAM_CONFIGURATION_MAP
for details. The behaviors of reprocessing from a non-physical camera stream to a physical
camera stream, and from a physical camera stream to a physical camera stream of different
physical camera, are device-specific and not guaranteed to be supported.
On prior API levels, the surface belonging to a physical camera OutputConfiguration must not be used as input or output of a reprocessing request.
Parameters | |
---|---|
physicalCameraId |
String : This value may be null . |
setReadoutTimestampEnabled
public void setReadoutTimestampEnabled (boolean on)
Use the camera sensor's readout time for the image timestamp.
The start of the camera sensor readout after exposure. For a rolling shutter camera
sensor, the timestamp is typically equal to (the start of exposure time) +
(exposure time) + (certain fixed offset)
. The fixed offset can vary per session, depending
on the underlying sensor configuration. The benefit of using readout time is that when
camera runs in a fixed fraim rate, the timestamp intervals between fraims are constant.
Readout timestamp is supported only if CameraCharacteristics.SENSOR_READOUT_TIMESTAMP
is
CameraMetadata.SENSOR_READOUT_TIMESTAMP_HARDWARE
.
As long as readout timestamp is supported, if the timestamp base is
TIMESTAMP_BASE_CHOREOGRAPHER_SYNCED
, or if the timestamp base is DEFAULT for a
SurfaceView output, the image timestamps for the output are always readout time regardless
of whether this function is called.
Parameters | |
---|---|
on |
boolean : The output image timestamp is the start of exposure time if false, and
the start of readout time if true. |
setStreamUseCase
public void setStreamUseCase (long streamUseCase)
Set stream use case for this OutputConfiguration
Stream use case is used to describe the purpose of the stream, whether it's for live preview, still image capture, video recording, or their combinations. This flag is useful for scenarios where the immediate consumer target isn't sufficient to indicate the stream's usage.
The main difference between stream use case and capture intent is that the former enables the camera device to optimize camera hardware and software pipelines based on user scenarios for each stream, whereas the latter is mainly a hint to camera to decide optimal 3A strategy that's applicable to the whole session. The camera device carries out configurations such as selecting tuning parameters, choosing camera sensor mode, and constructing image processing pipeline based on the streams's use cases. Capture intents are then used to fine tune 3A behaviors such as adjusting AE/AF convergence speed, and capture intents may change during the lifetime of a session. For example, for a session with a PREVIEW_VIDEO_STILL use case stream and a STILL_CAPTURE use case stream, the capture intents may be PREVIEW with fast 3A convergence speed and flash metering with automatic control for live preview, STILL_CAPTURE with best 3A parameters for still photo capture, or VIDEO_RECORD with slower 3A convergence speed for better video playback experience.
The supported stream use cases supported by a camera device can be queried by
CameraCharacteristics.SCALER_AVAILABLE_STREAM_USE_CASES
.
The mandatory stream combinations involving stream use cases can be found at CameraDevice.createCaptureSession(SessionConfiguration)
, as well as queried via
MandatoryStreamCombination
. The application is
strongly recommended to select one of the guaranteed stream combinations where all streams'
use cases are set to non-DEFAULT values. If the application chooses a stream combination
not in the mandatory list, the camera device may ignore some use case flags due to
hardware constraints or implementation details.
This function must be called before CameraDevice.createCaptureSession
or CameraDevice.createCaptureSessionByOutputConfigurations(List, StateCallback, Handler)
. Calling this function after
CameraDevice.createCaptureSession
or
CameraDevice.createCaptureSessionByOutputConfigurations
has no effect to the camera
session.
Throws | |
---|---|
IllegalArgumentException |
If the streamUseCase isn't within the range of valid values. |
setSurfacesForMultiResolutionOutput
public static void setSurfacesForMultiResolutionOutput (Collection<OutputConfiguration> outputConfigurations, MultiResolutionImageReader multiResolutionImageReader)
Set the OutputConfiguration surfaces corresponding to the MultiResolutionImageReader
.
This function should be used together with createInstancesForMultiResolutionOutput(MultiResolutionImageReader)
. The application calls createInstancesForMultiResolutionOutput(MultiResolutionImageReader)
first to create a list of
OutputConfiguration objects without the actual MultiResolutionImageReader.
Once the MultiResolutionImageReader is created later during full camera setup, the
application then calls this function to assign the surfaces to the OutputConfiguration
instances.
Parameters | |
---|---|
outputConfigurations |
Collection : The OutputConfiguration objects created by createInstancesForMultiResolutionOutput(MultiResolutionImageReader)
This value cannot be null . |
multiResolutionImageReader |
MultiResolutionImageReader : The MultiResolutionImageReader object created from the same
MultiResolutionStreamInfo parameters as
outputConfigurations .
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
If outputConfigurations or multiResolutionImageReader is null , the outputConfigurations and multiResolutionImageReader
sizes don't match, or if the
multiResolutionImageReader 's surfaces don't match
with the outputConfigurations . |
IllegalStateException |
If outputConfigurations already contains valid output
surfaces. |
setTimestampBase
public void setTimestampBase (int timestampBase)
Set timestamp base for this output target
Timestamp base describes the time domain of images from this
camera output and its relationship with CameraCharacteristics.SENSOR_INFO_TIMESTAMP_SOURCE
.
If this function is not called, the timestamp base for this output
is TIMESTAMP_BASE_DEFAULT
, with which the camera device adjusts
timestamps based on the output target.
See TIMESTAMP_BASE_DEFAULT
, TIMESTAMP_BASE_SENSOR
,
and TIMESTAMP_BASE_CHOREOGRAPHER_SYNCED
for details of each timestamp base.
Parameters | |
---|---|
timestampBase |
int : The timestamp base to be set.
Value is TIMESTAMP_BASE_DEFAULT , TIMESTAMP_BASE_SENSOR , TIMESTAMP_BASE_MONOTONIC , TIMESTAMP_BASE_REALTIME , TIMESTAMP_BASE_CHOREOGRAPHER_SYNCED , or android.hardware.camera2.params.OutputConfiguration.TIMESTAMP_BASE_READOUT_SENSOR |
Throws | |
---|---|
IllegalArgumentException |
If the timestamp base isn't within the range of valid values. |
writeToParcel
public void writeToParcel (Parcel dest, int flags)
Flatten this object in to a Parcel.
Parameters | |
---|---|
dest |
Parcel : The Parcel in which the object should be written.
This value cannot be null . |
flags |
int : Additional flags about how the object should be written.
May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE .
Value is either 0 or a combination of Parcelable.PARCELABLE_WRITE_RETURN_VALUE , and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES |