# Print output for @column tags ?>
Developers

- Design
- Develop
- Distribute

Developer Console

## Most visited

## Recently visited

## Results for

Summary: Constants | Inherited Constants | Fields | Ctors | Methods | Inherited Methods

# 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 to `CameraDevice#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 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.
- 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 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.
- 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 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.
- 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 from `MultiResolutionStreamConfigurationMap.getOutputInfo(int)` and `MultiResolutionImageReader` 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:

- `CameraDevice.createCaptureSessionByOutputConfigurations(List, CameraCaptureSession.StateCallback, Handler)`
- `CameraCharacteristics.SCALER_MULTI_RESOLUTION_STREAM_CONFIGURATION_MAP`

## Summary

### Constants
`int` | `SURFACE_GROUP_ID_NONE` Invalid surface group ID.

### Inherited constants
From interface `android.os.Parcelable`
`int` | `CONTENTS_FILE_DESCRIPTOR` Descriptor bit used with `describeContents()`: indicates that the Parcelable object's flattened representation includes a file descriptor.
`int` | `PARCELABLE_WRITE_RETURN_VALUE` Flag for use with `writeToParcel(Parcel, int)`: the object being written is a return value, that is the result of a function such as "`Parcelable someFunction()`", "`void someFunction(out Parcelable)`", or "`void someFunction(inout 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` | `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 Collection<OutputConfiguration>` | `createInstancesForMultiResolutionOutput(MultiResolutionImageReader multiResolutionImageReader)` Create a list of `OutputConfiguration` instances for the outputs used by a `MultiResolutionImageReader`.
`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 `CameraDevice#createCaptureSession`.
`boolean` | `equals(Object obj)` Check if this `OutputConfiguration` is equal to another `OutputConfiguration`.
`int` | `getMaxSharedSurfaceCount()` Get the maximum supported shared `Surface` count.
`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` | `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` | `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
From class `java.lang.Object`
`Object` | `clone()` Creates and returns a copy of this object.
`boolean` | `equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void` | `finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>` | `getClass()` Returns the runtime class of this `Object`.
`int` | `hashCode()` Returns a hash code value for the object.
`final void` | `notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void` | `notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String` | `toString()` Returns a string representation of the object.
`final void` | `wait(long timeout, int nanos)` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
`final void` | `wait(long timeout)` Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.
`final void` | `wait()` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.
From interface `android.os.Parcelable`
`abstract int` | `describeContents()` Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.
`abstract void` | `writeToParcel(Parcel dest, int flags)` Flatten this object in to a Parcel.

## Constants

### 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)

## Fields

### CREATOR

    public static final Creator<OutputConfiguration> CREATOR

## Public constructors

### 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 `.SURFACE_GROUP_ID_NONE`. This value cannot be `null`.

### 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 (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(List)` 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 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, CameraCaptureSession.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 the OutputConfiguration was constructed with a deferred surface by `OutputConfiguration(android.util.Size, java.lang.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.

### 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:

- Surfaces with the same size, format, dataSpace, and Surface source class. In this case, `CameraDevice#createCaptureSessionByOutputConfigurations` 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, `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, CameraCaptureSession.StateCallback, Handler)` or `CameraDevice.createReprocessableCaptureSessionByConfigurations(InputConfiguration, List, CameraCaptureSession.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 OuptutConfigurations 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

### 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:

- `enableSurfaceSharing()`

### 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`.

### 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 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.

### 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 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)`.

### 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, CameraCaptureSession.StateCallback, Handler)` or `CameraDevice.createReprocessableCaptureSessionByConfigurations(InputConfiguration, List, CameraCaptureSession.StateCallback, Handler)`. Calling this function after `CameraDevice#createCaptureSessionByOutputConfigurations` or `CameraDevice.createReprocessableCaptureSessionByConfigurations(InputConfiguration, List, CameraCaptureSession.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`.

### 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.
`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

Full name *
Email address *
Company / developer name
One of your Play Store app URLs *
Which best describes your business:*
Apps
Games
Apps & Games
*
*