See also:

• CameraDevice.createCaptureSessionByOutputConfigurations
• CameraCharacteristics.SCALER_MULTI_RESOLUTION_STREAM_CONFIGURATION_MAP

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 frames. An output target of SurfaceView uses this time base by default. Note that the timestamp override is done for fixed camera frame 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, 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.

Note that the reduction of frame 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)

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().

Starting from Android C, the ImageReader deferred Surface can be obtained from ImageReader.getSurface(). Do note that you should use OutputConfiguration.OutputConfiguration(int,int,Size,long) to instantiate a deferred ImageReader output configuration or by calling makeDeferredAndRemoveSurfaces() on an output configuration that has a non-deferred ImageReader surface.

• Surfaces for SurfaceView and SurfaceTexture can be deferred until after CameraDevice.createCaptureSession. In that case, the output Surface must be set via addSurface(Surface), and the Surface configuration must be finalized via CameraCaptureSession.finalizeOutputConfigurations before submitting a request with the Surface target.
• For all other target types, the output Surface must be set by addSurface(Surface), and CameraCaptureSession.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.

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

OutputConfiguration

public OutputConfiguration (Surface surface)

Create a new OutputConfiguration instance with a Surface.

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.

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

addSurface

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 this function is called before session creation, CameraCaptureSession.finalizeOutputConfigurations doesn't need to be called.

If the OutputConfiguration was constructed by OutputConfiguration.OutputConfiguration(Size,Class), the added surface must be obtained:

• from SurfaceView by calling SurfaceHolder.getSurface()
• from SurfaceTexture by calling Surface.Surface(android.graphics.SurfaceTexture)
• from MediaRecorder by calling MediaRecorder.getSurface() or MediaCodec.createPersistentInputSurface()
• from MediaCodec by calling MediaCodec.createInputSurface() or MediaCodec.createPersistentInputSurface()

If the OutputConfiguration was constructed by OutputConfiguration(int,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.

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(Parcel,int), the return value of this method must include the CONTENTS_FILE_DESCRIPTOR bit.

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:

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.

getMaxSharedSurfaceCount

public int getMaxSharedSurfaceCount ()

Get the maximum supported shared Surface count.

getStreamUseCase

public long getStreamUseCase ()

Get the current stream use case

If no setStreamUseCase(long) is called first, this function returns DEFAULT.

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

isReadoutTimestampEnabled

public boolean isReadoutTimestampEnabled ()

Whether readout timestamp is used for this OutputConfiguration.

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.OutputConfiguration(int,Size), OutputConfiguration.OutputConfiguration(int,Size,long), OutputConfiguration.OutputConfiguration(int,int,Size), OutputConfiguration.OutputConfiguration(int,int,Size,long).

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 setMirrorMode(Surface,int). Prior to Android 16, this function is only applicable if surface sharing is not enabled.

setMirrorMode

public void setMirrorMode (Surface surface, 
                int mirrorMode)

Set the mirroring mode for a surface belonging to this OutputConfiguration

This function is identical to setMirrorMode(int) if surface is the only surface belonging to this OutputConfiguration.

If this OutputConfiguration contains a deferred surface, the application can either call setMirrorMode(int), or call this function after calling addSurface(Surface).

If this OutputConfiguration contains shared surfaces, the application can set different mirroring modes for different surfaces.

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.

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 frame rate, the timestamp intervals between frames 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.

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. Calling this function after CameraDevice.createCaptureSession or CameraDevice.createCaptureSessionByOutputConfigurations has no effect to the camera session.