Skip to content

Most visited

Recently visited

navigation

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.

See also:

Summary

Constants

int SURFACE_GROUP_ID_NONE

Invalid surface group ID.

Inherited constants

From interface android.os.Parcelable

Fields

public static final Creator<OutputConfiguration> CREATOR

Public constructors

OutputConfiguration(Surface surface)

Create a new OutputConfiguration instance with a Surface.

OutputConfiguration(int surfaceGroupId, Surface surface)

Create a new OutputConfiguration instance with a Surface, with a surface group ID.

OutputConfiguration(Size surfaceSize, Class<T> klass)

Create a new OutputConfiguration instance, with desired Surface size and Surface source class.

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 createCaptureSession(List, CameraCaptureSession.StateCallback, Handler).

boolean equals(Object obj)

Check if this OutputConfiguration is equal to another OutputConfiguration.

Surface getSurface()

Get the Surface associated with this OutputConfiguration.

int getSurfaceGroupId()

Get the surface group ID associated with this OutputConfiguration.

List<Surface> getSurfaces()

Get the immutable list of surfaces associated with this OutputConfiguration.

int hashCode()

Returns a hash code value for the object.

void writeToParcel(Parcel dest, int flags)

Flatten this object in to a Parcel.

Inherited methods

From class java.lang.Object
From interface android.os.Parcelable

Constants

SURFACE_GROUP_ID_NONE

added in API level 24
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)

Fields

CREATOR

added in API level 24
Creator<OutputConfiguration> CREATOR

Public constructors

OutputConfiguration

added in API level 24
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 .SURFACE_GROUP_ID_NONE.

This value must never be null.

OutputConfiguration

added in API level 24
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 must never be null.

OutputConfiguration

added in API level 26
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 finalizeOutputConfigurations(List) before submitting a request with this Surface target. The deferred Surface can only be obtained either from SurfaceView by calling getSurface(), or from SurfaceTexture via Surface(android.graphics.SurfaceTexture)).

Parameters
surfaceSize Size: Size for the deferred surface.

This value must never 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.

Throws
IllegalArgumentException if the Surface source class is not supported, or Surface size is zero.

Public methods

addSurface

added in API level 26
void addSurface (Surface surface)

Add a surface to this OutputConfiguration.

This function can be called before or after createCaptureSessionByOutputConfigurations(List, CameraCaptureSession.StateCallback, Handler). If it's called after, the application must finalize the capture session with finalizeOutputConfigurations(List).

If the OutputConfiguration was constructed with a deferred surface by OutputConfiguration(Size, Class), the added surface must be obtained from SurfaceView by calling getSurface(), or from SurfaceTexture via 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 must never 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.

describeContents

added in API level 24
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(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.

enableSurfaceSharing

added in API level 26
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 createCaptureSession(List, CameraCaptureSession.StateCallback, Handler). 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.

Two surfaces are compatible in the below cases:

  • Surfaces with the same size, format, dataSpace, and Surface source class. In this case, createCaptureSessionByOutputConfigurations(List, CameraCaptureSession.StateCallback, Handler) is guaranteed to succeed.
  • Surfaces with the same size, format, and dataSpace, but different Surface source classes that are generally not compatible. However, on some devices, the underlying camera device is able to use the same buffer layout for both surfaces. The only way to discover if this is the case is to create a capture session with that output configuration. For example, if the camera device uses the same private buffer format between a SurfaceView/SurfaceTexture and a MediaRecorder/MediaCodec, createCaptureSessionByOutputConfigurations(List, CameraCaptureSession.StateCallback, Handler) will succeed. Otherwise, it fails with onConfigureFailed(CameraCaptureSession).

    To enable surface sharing, this function must be called before createCaptureSessionByOutputConfigurations(List, CameraCaptureSession.StateCallback, Handler). Calling this function after createCaptureSessionByOutputConfigurations(List, CameraCaptureSession.StateCallback, Handler) has no effect.

    Up to 2 surfaces can be shared for an OutputConfiguration. The supported surfaces for sharing must be of type SurfaceTexture, SurfaceView, MediaRecorder, MediaCodec, or implementation defined ImageReader.

  • equals

    added in API level 24
    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

    getSurface

    added in API level 24
    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 addSurface(Surface).

    Returns
    Surface

    This value may be null.

    getSurfaceGroupId

    added in API level 24
    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

    added in API level 26
    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 addSurface(Surface). The list should not be modified.

    This value will never be null.

    hashCode

    added in API level 24
    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 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.
    • If two objects are equal according to the equals(Object) method, then calling the hashCode 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(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.

    writeToParcel

    added in API level 24
    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_WRITE_RETURN_VALUE.

    This site uses cookies to store your preferences for site-specific language and display options.

    Get the latest Android developer news and tips that will help you find success on Google Play.

    * Required Fields

    Hooray!

    Browse this site in ?

    You requested a page in , but your language preference for this site is .

    Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

    This class requires API level or higher

    This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

    For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

    Take a short survey?
    Help us improve the Android developer experience.
    (Sep 2017 survey)