OutputConfigurationCompat

class OutputConfigurationCompat
kotlin.Any
   ↳ androidx.camera.camera2.impl.compat.params.OutputConfigurationCompat

Helper for accessing features in OutputConfiguration in a backwards compatible fashion.

Summary

Constants

static Int

Invalid surface group ID.

Public constructors

<init>(@NonNull surface: Surface)

<init>(@NonNull surfaceSize: Size, @NonNull klass: Class<T>)

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

Public methods

Unit
addSurface(@NonNull surface: Surface)

Add a surface to this OutputConfiguration.

Unit

Enable multiple surfaces sharing the same OutputConfiguration.

Boolean
equals(other: Any?)

Check if this OutputConfigurationCompat is equal to another OutputConfigurationCompat.

Int

Get the maximum supported shared Surface count.

Surface?

Get the Surface associated with this OutputConfigurationCompat.

Int

Get the surface group ID associated with this OutputConfigurationCompat.

MutableList<Surface!>

Get the immutable list of surfaces associated with this OutputConfigurationCompat.

Int

Unit
removeSurface(@NonNull surface: Surface)

Remove a surface from this OutputConfiguration.

Unit
setPhysicalCameraId(@Nullable physicalCameraId: String?)

Set the id of the physical camera for this OutputConfiguration.

Any?

Gets the underlying framework android.

static OutputConfigurationCompat?
wrap(@Nullable outputConfiguration: Any?)

Creates an instance from a framework android.

Constants

SURFACE_GROUP_ID_NONE

static val SURFACE_GROUP_ID_NONE: Int

Invalid surface group ID.

An OutputConfiguration with this value indicates that the included surface doesn't belong to any surface group.

Value: -1

Public constructors

<init>

OutputConfigurationCompat(@NonNull surface: Surface)

<init>

OutputConfigurationCompat(@NonNull surfaceSize: Size, @NonNull klass: Class<T>)

Create a new OutputConfigurationCompat 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 and the deferred Surface configuration must be finalized via before submitting a request with this Surface target. The deferred Surface can only be obtained either from by calling android.view.SurfaceHolder#getSurface, or from android.graphics.SurfaceTexture via android.view.Surface#Surface(android.graphics.SurfaceTexture)).

Parameters
surfaceSize Size: Size for the deferred surface.
klass Size: a non-null Class object reference that indicates the source of this surface. Only SurfaceHolder and SurfaceTexture.class are supported.
Exceptions
IllegalArgumentException if the Surface source class is not supported, or Surface size is zero.

Public methods

addSurface

fun addSurface(@NonNull surface: Surface): Unit

Add a surface to this OutputConfiguration.

This method will always throw on API <= 25, as these API levels do not support surface sharing. Users should always check getMaxSharedSurfaceCount before attempting to add a surface.

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 , the added surface must be obtained from android.view.SurfaceView by calling android.view.SurfaceHolder#getSurface, or from android.graphics.SurfaceTexture via android.view.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.
Exceptions
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.

enableSurfaceSharing

fun enableSurfaceSharing(): Unit

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 .

    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.

  • equals

    fun equals(other: Any?): Boolean

    Check if this OutputConfigurationCompat is equal to another OutputConfigurationCompat.

    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.

    Return
    Boolean: true if the objects were equal, false otherwise

    getMaxSharedSurfaceCount

    fun getMaxSharedSurfaceCount(): Int

    Get the maximum supported shared Surface count.

    Return
    Int: the maximum number of surfaces that can be added per each OutputConfiguration.

    getSurface

    @Nullable fun getSurface(): Surface?

    Get the Surface associated with this OutputConfigurationCompat. If more than one surface is associated with this OutputConfigurationCompat, return the first one as specified in the constructor or OutputConfigurationCompat#addSurface.

    getSurfaceGroupId

    fun getSurfaceGroupId(): Int

    Get the surface group ID associated with this OutputConfigurationCompat.

    Return
    Int: the surface group ID associated with this OutputConfigurationCompat. The default value is {@value #SURFACE_GROUP_ID_NONE}.

    getSurfaces

    @NonNull fun getSurfaces(): MutableList<Surface!>

    Get the immutable list of surfaces associated with this OutputConfigurationCompat.

    Return
    MutableList<Surface!>: the list of surfaces associated with this OutputConfigurationCompat as specified in the constructor and OutputConfigurationCompat#addSurface. The list should not be modified.

    hashCode

    fun hashCode(): Int

    removeSurface

    fun removeSurface(@NonNull surface: Surface): Unit

    Remove a surface from this OutputConfiguration.

    Surfaces added via calls to addSurface 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 OutputConfigurationCompat#OutputConfigurationCompat(Size, Class).

    Parameters
    surface Surface: The surface to be removed.
    Exceptions
    IllegalArgumentException If the surface is associated with this OutputConfiguration (see getSurface) or the surface didn't get added with addSurface.

    setPhysicalCameraId

    fun setPhysicalCameraId(@Nullable physicalCameraId: String?): Unit

    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 on API >= 28.

    On API <= 27, the physical camera id will be ignored since logical camera is not supported on these API levels.

    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.

    unwrap

    @Nullable fun unwrap(): Any?

    Gets the underlying framework android.hardware.camera2.params.OutputConfiguration object.

    This method always returns null on API <= 23.

    Return
    Any?: an equivalent android.hardware.camera2.params.OutputConfiguration object, or null if not supported.

    wrap

    @Nullable static fun wrap(@Nullable outputConfiguration: Any?): OutputConfigurationCompat?

    Creates an instance from a framework android.hardware.camera2.params.OutputConfiguration object.

    This method always returns null on API <= 23.

    Parameters
    outputConfiguration Any?: an android.hardware.camera2.params.OutputConfiguration object, or null if none.
    Return
    OutputConfigurationCompat?: an equivalent OutputConfigurationCompat object, or null if not supported.