# Print output for @column tags ?>
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:
Surface
to the constructor and using the OutputConfiguration instance as
argument to CameraDevice#createCaptureSessionByOutputConfigurations
. This is the most
frequent usage and clients should consider it first before other more complicated alternatives.
CameraDevice#createCaptureSessionByOutputConfigurations
and a Surface
add
call addSurface(Surface)
with a valid Surface
. The sequence completes with
CameraCaptureSession#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 any Surface
initialization, such as waiting for a
SurfaceView
to be ready as part of the UI initialization.enableSurfaceSharing()
. This
must be done before creating a new capture session and enables calls to
CameraCaptureSession#updateOutputConfiguration
. An OutputConfiguration with enabled
surface sharing can be modified via addSurface(Surface)
or removeSurface(Surface)
. The updates
to this OutputConfiguration will only come into effect after
CameraCaptureSession#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 see
enableSurfaceSharing()
, 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.enableSurfaceSharing()
before creating a capture
session. Attach and/or remove output surfaces via addSurface(Surface)
/removeSurface(Surface)
and
finalize the configuration using CameraCaptureSession#finalizeOutputConfigurations
.
CameraCaptureSession#updateOutputConfiguration
can be called after the configuration
finalize method returns without exceptions. 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.
Constants | |
---|---|
int |
SURFACE_GROUP_ID_NONE
Invalid surface group ID. |
Inherited constants |
---|
Fields | |
---|---|
public
static
final
Creator<OutputConfiguration> |
CREATOR
|
Public constructors | |
---|---|
OutputConfiguration(Surface surface)
Create a new |
|
OutputConfiguration(int surfaceGroupId, Surface surface)
Create a new |
|
OutputConfiguration(Size surfaceSize, Class<T> klass)
Create a new |
Public methods | |
---|---|
void
|
addSurface(Surface surface)
Add a surface to this OutputConfiguration. |
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 |
int
|
getMaxSharedSurfaceCount()
Get the maximum supported shared |
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
|
hashCode()
Returns a hash code value for the object. |
void
|
removeSurface(Surface surface)
Remove a surface from this OutputConfiguration. |
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
|
writeToParcel(Parcel dest, int flags)
Flatten this object in to a Parcel. |
Inherited methods | |
---|---|
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)
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 . |
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 . |
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.
However, the actual output Surface must be set via addSurface(Surface)
and the deferred
Surface configuration must be finalized via CameraCaptureSession#finalizeOutputConfigurations
before submitting a request with this
Surface target. The deferred Surface can only be obtained either from SurfaceView
by calling SurfaceHolder.getSurface()
, or from
SurfaceTexture
via
Surface.Surface(android.graphics.SurfaceTexture)
).
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 and
SurfaceTexture.class are supported.
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if the Surface source class is not supported, or Surface size is zero. |
public void addSurface (Surface surface)
Add a surface to this OutputConfiguration.
This function can be called before or after CameraDevice#createCaptureSessionByOutputConfigurations
. 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 the OutputConfiguration was constructed with a deferred surface by OutputConfiguration#OutputConfiguration(Size, Class)
, the added surface must be obtained
from SurfaceView
by calling SurfaceHolder.getSurface()
,
or from SurfaceTexture
via
Surface.Surface(android.graphics.SurfaceTexture)
).
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. |
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 |
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
.
To enable surface sharing, this function must be called before CameraDevice#createCaptureSessionByOutputConfigurations
or CameraDevice#createReprocessableCaptureSessionByConfigurations
. 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.
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 : the reference object with which to compare. |
Returns | |
---|---|
boolean |
true if the objects were equal, false otherwise |
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:
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 . |
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 . |
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 . |
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:
hashCode
method
must consistently return the same integer, provided no information
used in equals
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.
equals(Object)
method, then calling the hashCode
method on each of
the two objects must produce the same integer result.
equals(java.lang.Object)
method, then calling the hashCode
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.
As much as is reasonably practical, the hashCode method defined by
class Object
does return distinct integers for distinct
objects. (This is typically implemented by converting the internal
address of the object into an integer, but this implementation
technique is not required by the
Java™ programming language.)
Returns | |
---|---|
int |
a hash code value for this object. |
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 OutputConfigration see getSurface()
which was passed as part of the constructor
or was added first in the deferred case
OutputConfiguration#OutputConfiguration(Size, Class)
.
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) . |
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
or CameraDevice#createReprocessableCaptureSessionByConfigurations
. Calling this function
after CameraDevice#createCaptureSessionByOutputConfigurations
or CameraDevice#createReprocessableCaptureSessionByConfigurations
has no effect.
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 . |
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. |
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 |