Android APIs
public final class

StreamConfigurationMap

extends Object
java.lang.Object
   ↳ android.hardware.camera2.params.StreamConfigurationMap

Class Overview

Immutable class to store the available stream configurations to set up Surfaces for creating a capture session with createCaptureSession(List, CameraCaptureSession.StateCallback, Handler).

This is the authoritative list for all output formats (and sizes respectively for that format) that are supported by a camera device.

This also contains the minimum frame durations and stall durations for each format/size combination that can be used to calculate effective frame rate when submitting multiple captures.

An instance of this object is available from CameraCharacteristics using the SCALER_STREAM_CONFIGURATION_MAP key and the get(CameraCharacteristics.Key) method.

CameraCharacteristics characteristics = cameraManager.getCameraCharacteristics(cameraId);
 StreamConfigurationMap configs = characteristics.get(
         CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP);
 

Summary

Public Methods
boolean equals(Object obj)
Check if this StreamConfigurationMap is equal to another StreamConfigurationMap.
Range[]<Integer> getHighSpeedVideoFpsRanges()
Get a list of supported high speed video recording FPS ranges.
Range[]<Integer> getHighSpeedVideoFpsRangesFor(Size size)
Get the frame per second ranges (fpsMin, fpsMax) for input high speed video size.
Size[] getHighSpeedVideoSizes()
Get a list of supported high speed video recording sizes.
Size[] getHighSpeedVideoSizesFor(Range<Integer> fpsRange)
Get the supported video sizes for input FPS range.
final int[] getOutputFormats()
Get the image format output formats in this stream configuration.
<T> long getOutputMinFrameDuration(Class<T> klass, Size size)
Get the minimum frame duration for the class/size combination (in nanoseconds).
long getOutputMinFrameDuration(int format, Size size)
Get the minimum frame duration for the format/size combination (in nanoseconds).
<T> Size[] getOutputSizes(Class<T> klass)
Get a list of sizes compatible with klass to use as an output.
Size[] getOutputSizes(int format)
Get a list of sizes compatible with the requested image format.
<T> long getOutputStallDuration(Class<T> klass, Size size)
Get the stall duration for the class/size combination (in nanoseconds).
long getOutputStallDuration(int format, Size size)
Get the stall duration for the format/size combination (in nanoseconds).
int hashCode()
Returns an integer hash code for this object.
boolean isOutputSupportedFor(int format)
Determine whether or not output surfaces with a particular user-defined format can be passed createCaptureSession.
boolean isOutputSupportedFor(Surface surface)
Determine whether or not the surface in its current state is suitable to be included in a capture session as an output.
static <T> boolean isOutputSupportedFor(Class<T> klass)
Determine whether or not output streams can be configured with a particular class as a consumer.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public boolean equals (Object obj)

Added in API level 21

Check if this StreamConfigurationMap is equal to another StreamConfigurationMap.

Two vectors are only equal if and only if each of the respective elements is equal.

Parameters
obj the object to compare this instance with.
Returns
  • true if the objects were equal, false otherwise

public Range[]<Integer> getHighSpeedVideoFpsRanges ()

Added in API level 21

Get a list of supported high speed video recording FPS ranges.

When HIGH_SPEED_VIDEO is supported in available scene modes, this method will list the supported high speed video FPS range configurations. Application can then use getHighSpeedVideoSizesFor(Range) to query available sizes for one of returned FPS range.

To enable high speed video recording, application must set CONTROL_SCENE_MODE to HIGH_SPEED_VIDEO in capture requests and select the video size from getHighSpeedVideoSizesFor(Range) and FPS range from this method to configure the recording and preview streams and setup the recording requests. For example, if the application intends to do high speed recording, it can select one FPS range reported by this method, query the video sizes corresponding to this FPS range by getHighSpeedVideoSizesFor(Range) and select one of reported sizes to configure output streams. Note that for the use case of multiple output streams, application must select one unique size from getHighSpeedVideoSizesFor(Range), and use it for all output streams. Otherwise a request error might occur when attempting to enable HIGH_SPEED_VIDEO. Once the stream is configured, application can set the FPS range in the recording requests.

Returns
  • an array of supported high speed video recording FPS ranges The upper bound of returned ranges is guaranteed to be larger or equal to 60.

public Range[]<Integer> getHighSpeedVideoFpsRangesFor (Size size)

Added in API level 21

Get the frame per second ranges (fpsMin, fpsMax) for input high speed video size.

See getHighSpeedVideoSizes() for how to enable high speed recording.

For normal video recording use case, where some application will NOT set CONTROL_SCENE_MODE to HIGH_SPEED_VIDEO in capture requests, the FPS ranges reported in this method must not be used to setup capture requests, or it will cause request error.

Parameters
size one of the sizes returned by getHighSpeedVideoSizes()
Returns
  • An array of FPS range to use with TARGET_FPS_RANGE when using HIGH_SPEED_VIDEO scene mode. The upper bound of returned ranges is guaranteed to be larger or equal to 60.
Throws
IllegalArgumentException if input size does not exist in the return value of getHighSpeedVideoSizes

public Size[] getHighSpeedVideoSizes ()

Added in API level 21

Get a list of supported high speed video recording sizes.

When HIGH_SPEED_VIDEO is supported in available scene modes, this method will list the supported high speed video size configurations. All the sizes listed will be a subset of the sizes reported by getOutputSizes(int) for processed non-stalling formats (typically ImageFormat#YUV_420_888, ImageFormat#NV21, ImageFormat#YV12)

To enable high speed video recording, application must set CONTROL_SCENE_MODE to HIGH_SPEED_VIDEO in capture requests and select the video size from this method and FPS range from getHighSpeedVideoFpsRangesFor(Size) to configure the recording and preview streams and setup the recording requests. For example, if the application intends to do high speed recording, it can select the maximum size reported by this method to configure output streams. Note that for the use case of multiple output streams, application must select one unique size from this method to use. Otherwise a request error might occur. Once the size is selected, application can get the supported FPS ranges by getHighSpeedVideoFpsRangesFor(Size), and use these FPS ranges to setup the recording requests.

Returns
  • an array of supported high speed video recording sizes

public Size[] getHighSpeedVideoSizesFor (Range<Integer> fpsRange)

Added in API level 21

Get the supported video sizes for input FPS range.

See getHighSpeedVideoFpsRanges() for how to enable high speed recording.

For normal video recording use case, where the application will NOT set CONTROL_SCENE_MODE to HIGH_SPEED_VIDEO in capture requests, the FPS ranges reported in this method must not be used to setup capture requests, or it will cause request error.

Parameters
fpsRange one of the FPS range returned by getHighSpeedVideoFpsRanges()
Returns
  • An array of video sizes to configure output stream when using HIGH_SPEED_VIDEO scene mode.
Throws
IllegalArgumentException if input FPS range does not exist in the return value of getHighSpeedVideoFpsRanges

public final int[] getOutputFormats ()

Added in API level 21

Get the image format output formats in this stream configuration.

All image formats returned by this function will be defined in either ImageFormat or in PixelFormat (and there is no possibility of collision).

Formats listed in this array are guaranteed to return true if queried with isOutputSupportedFor(int).

Returns
  • an array of integer format

public long getOutputMinFrameDuration (Class<T> klass, Size size)

Added in API level 21

Get the minimum frame duration for the class/size combination (in nanoseconds).

This assumes a the klass is set up to use an implementation-defined format. For user-defined formats, use getOutputMinFrameDuration(int, Size).

klass should be one of the ones which is supported by isOutputSupportedFor(Class).

size should be one of the ones returned by getOutputSizes(int).

This should correspond to the frame duration when only that stream is active, with all processing (typically in android.*.mode) set to either OFF or FAST.

When multiple streams are used in a request, the minimum frame duration will be max(individual stream min durations).

For devices that do not support manual sensor control (REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR), this function may return 0.

Parameters
klass a class which is supported by isOutputSupportedFor(Class) and has a non-empty array returned by getOutputSizes(Class)
size an output-compatible size
Returns
  • a minimum frame duration > 0 in nanoseconds, or 0 if the minimum frame duration is not available.
Throws
IllegalArgumentException if klass or size was not supported
NullPointerException if size or klass was null

public long getOutputMinFrameDuration (int format, Size size)

Added in API level 21

Get the minimum frame duration for the format/size combination (in nanoseconds).

format should be one of the ones returned by getOutputFormats().

size should be one of the ones returned by getOutputSizes(int).

This should correspond to the frame duration when only that stream is active, with all processing (typically in android.*.mode) set to either OFF or FAST.

When multiple streams are used in a request, the minimum frame duration will be max(individual stream min durations).

For devices that do not support manual sensor control (REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR), this function may return 0.

Parameters
format an image format from ImageFormat or PixelFormat
size an output-compatible size
Returns
  • a minimum frame duration > 0 in nanoseconds, or 0 if the minimum frame duration is not available.
Throws
IllegalArgumentException if format or size was not supported
NullPointerException if size was null

public Size[] getOutputSizes (Class<T> klass)

Added in API level 21

Get a list of sizes compatible with klass to use as an output.

Since some of the supported classes may support additional formats beyond an opaque/implementation-defined (under-the-hood) format; this function only returns sizes for the implementation-defined format.

Some classes such as ImageReader may only support user-defined formats; in particular isOutputSupportedFor(Class) will return true for that class and this method will return an empty array (but not null).

If a well-defined format such as NV21 is required, use getOutputSizes(int) instead.

The klass should be a supported output, that querying #isOutputSupportedFor(Class) should return true.

Parameters
klass a non-null Class object reference
Returns
  • an array of supported sizes for implementation-defined formats, or null iff the klass is not a supported output
Throws
NullPointerException if klass was null

public Size[] getOutputSizes (int format)

Added in API level 21

Get a list of sizes compatible with the requested image format.

The format should be a supported format (one of the formats returned by getOutputFormats()).

Parameters
format an image format from ImageFormat or PixelFormat
Returns
  • an array of supported sizes, or null if the format is not a supported output

public long getOutputStallDuration (Class<T> klass, Size size)

Added in API level 21

Get the stall duration for the class/size combination (in nanoseconds).

This assumes a the klass is set up to use an implementation-defined format. For user-defined formats, use getOutputMinFrameDuration(int, Size).

klass should be one of the ones with a non-empty array returned by getOutputSizes(Class).

size should be one of the ones returned by getOutputSizes(Class).

See getOutputStallDuration(int, Size) for a definition of a stall duration.

Parameters
klass a class which is supported by isOutputSupportedFor(Class) and has a non-empty array returned by getOutputSizes(Class)
size an output-compatible size
Returns
  • a minimum frame duration >= 0 in nanoseconds
Throws
IllegalArgumentException if klass or size was not supported
NullPointerException if size or klass was null

public long getOutputStallDuration (int format, Size size)

Added in API level 21

Get the stall duration for the format/size combination (in nanoseconds).

format should be one of the ones returned by getOutputFormats().

size should be one of the ones returned by getOutputSizes(int).

A stall duration is how much extra time would get added to the normal minimum frame duration for a repeating request that has streams with non-zero stall.

For example, consider JPEG captures which have the following characteristics:

  • JPEG streams act like processed YUV streams in requests for which they are not included; in requests in which they are directly referenced, they act as JPEG streams. This is because supporting a JPEG stream requires the underlying YUV data to always be ready for use by a JPEG encoder, but the encoder will only be used (and impact frame duration) on requests that actually reference a JPEG stream.
  • The JPEG processor can run concurrently to the rest of the camera pipeline, but cannot process more than 1 capture at a time.

In other words, using a repeating YUV request would result in a steady frame rate (let's say it's 30 FPS). If a single JPEG request is submitted periodically, the frame rate will stay at 30 FPS (as long as we wait for the previous JPEG to return each time). If we try to submit a repeating YUV + JPEG request, then the frame rate will drop from 30 FPS.

In general, submitting a new request with a non-0 stall time stream will not cause a frame rate drop unless there are still outstanding buffers for that stream from previous requests.

Submitting a repeating request with streams (call this S) is the same as setting the minimum frame duration from the normal minimum frame duration corresponding to S, added with the maximum stall duration for S.

If interleaving requests with and without a stall duration, a request will stall by the maximum of the remaining times for each can-stall stream with outstanding buffers.

This means that a stalling request will not have an exposure start until the stall has completed.

This should correspond to the stall duration when only that stream is active, with all processing (typically in android.*.mode) set to FAST or OFF. Setting any of the processing modes to HIGH_QUALITY effectively results in an indeterminate stall duration for all streams in a request (the regular stall calculation rules are ignored).

The following formats may always have a stall duration:

The following formats will never have a stall duration:

All other formats may or may not have an allowed stall duration on a per-capability basis; refer to android.request.availableCapabilities for more details.

See android.sensor.frameDuration for more information about calculating the max frame rate (absent stalls).

Parameters
format an image format from ImageFormat or PixelFormat
size an output-compatible size
Returns
  • a stall duration >= 0 in nanoseconds
Throws
IllegalArgumentException if format or size was not supported
NullPointerException if size was null

public int hashCode ()

Added in API level 21

Returns an integer hash code for this object. By contract, any two objects for which equals(Object) returns true must return the same hash code value. This means that subclasses of Object usually override both methods or neither method.

Note that hash values must not change over time unless information used in equals comparisons also changes.

See Writing a correct hashCode method if you intend implementing your own hashCode method.

Returns
  • this object's hash code.

public boolean isOutputSupportedFor (int format)

Added in API level 21

Determine whether or not output surfaces with a particular user-defined format can be passed createCaptureSession.

This method determines that the output format is supported by the camera device; each output surface target may or may not itself support that format. Refer to the class which provides the surface for additional documentation.

Formats for which this returns true are guaranteed to exist in the result returned by getOutputSizes(int).

Parameters
format an image format from either ImageFormat or PixelFormat
Returns
Throws
IllegalArgumentException if the image format was not a defined named constant from either ImageFormat or PixelFormat

public boolean isOutputSupportedFor (Surface surface)

Added in API level 21

Determine whether or not the surface in its current state is suitable to be included in a capture session as an output.

Not all surfaces are usable with the CameraDevice, and not all configurations of that surface are compatible. Some classes that provide the surface are compatible with the CameraDevice in general (see isOutputSupportedFor(Class), but it is the caller's responsibility to put the surface into a state that will be compatible with the CameraDevice.

Reasons for a surface being specifically incompatible might be:

  • Using a format that's not listed by getOutputFormats()
  • Using a format/size combination that's not listed by getOutputSizes(int)
  • The surface itself is not in a state where it can service a new producer.

Surfaces from flexible sources will return true even if the exact size of the Surface does not match a camera-supported size, as long as the format (or class) is supported and the camera device supports a size that is equal to or less than 1080p in that format. If such as Surface is used to create a capture session, it will have its size rounded to the nearest supported size, below or equal to 1080p. Flexible sources include SurfaceView, SurfaceTexture, and ImageReader.

This is not an exhaustive list; see the particular class's documentation for further possible reasons of incompatibility.

Parameters
surface a non-null Surface object reference
Returns
  • true if this is supported, false otherwise
Throws
NullPointerException if surface was null
IllegalArgumentException if the Surface endpoint is no longer valid

public static boolean isOutputSupportedFor (Class<T> klass)

Added in API level 21

Determine whether or not output streams can be configured with a particular class as a consumer.

The following list is generally usable for outputs:

Generally speaking this means that creating a Surface from that class may provide a producer endpoint that is suitable to be used with createCaptureSession(List, CameraCaptureSession.StateCallback, Handler).

Since not all of the above classes support output of all format and size combinations, the particular combination should be queried with isOutputSupportedFor(Surface).

Parameters
klass a non-null Class object reference
Returns
  • true if this class is supported as an output, false otherwise
Throws
NullPointerException if klass was null