java.lang.Object | |
↳ | android.hardware.camera2.params.StreamConfigurationMap |
Immutable class to store the available stream
configurations
to set up
Surfaces
for creating a
capture session
with
createCaptureSession(List
.
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);
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Check if this
StreamConfigurationMap is equal to another
StreamConfigurationMap .
| |||||||||||
Get a list of supported high speed video recording FPS ranges.
| |||||||||||
Get the frame per second ranges (fpsMin, fpsMax) for input high speed video size.
| |||||||||||
Get a list of supported high speed video recording sizes.
| |||||||||||
Get the supported video sizes for input FPS range.
| |||||||||||
Get the image
format output formats in this stream configuration.
| |||||||||||
Get the minimum
frame duration
for the class/size combination (in nanoseconds).
| |||||||||||
Get the minimum
frame duration
for the format/size combination (in nanoseconds).
| |||||||||||
Get a list of sizes compatible with
klass to use as an output.
| |||||||||||
Get a list of sizes compatible with the requested image
format .
| |||||||||||
Get the stall duration for the class/size combination (in nanoseconds).
| |||||||||||
Get the stall duration for the format/size combination (in nanoseconds).
| |||||||||||
Returns an integer hash code for this object.
| |||||||||||
Determine whether or not output surfaces with a particular user-defined format can be passed
createCaptureSession .
| |||||||||||
Determine whether or not the
surface in its current state is suitable to be included
in a capture session as an output.
| |||||||||||
Determine whether or not output streams can be configured with a particular class
as a consumer.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
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.
obj | the object to compare this instance with. |
---|
true
if the objects were equal, false
otherwise
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.
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.
size | one of the sizes returned by getHighSpeedVideoSizes() |
---|
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.IllegalArgumentException | if input size does not exist in the return value of getHighSpeedVideoSizes |
---|
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.
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.
fpsRange | one of the FPS range returned by getHighSpeedVideoFpsRanges() |
---|
HIGH_SPEED_VIDEO
scene
mode.IllegalArgumentException | if input FPS range does not exist in the return value of getHighSpeedVideoFpsRanges |
---|
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)
.
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.
klass | a class which is supported by isOutputSupportedFor(Class) and has a
non-empty array returned by getOutputSizes(Class) |
---|---|
size | an output-compatible size |
>
0 in nanoseconds, or
0 if the minimum frame duration is not available.IllegalArgumentException | if klass or size was not supported |
---|---|
NullPointerException | if size or klass was null |
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.
format | an image format from ImageFormat or PixelFormat |
---|---|
size | an output-compatible size |
>
0 in nanoseconds, or
0 if the minimum frame duration is not available.IllegalArgumentException | if format or size was not supported |
---|---|
NullPointerException | if size was null |
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
.
klass | a non-null Class object reference |
---|
null
iff the klass
is not a supported outputNullPointerException | if klass was null |
---|
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()
).
format | an image format from ImageFormat or PixelFormat |
---|
null
if the format
is not a supported outputGet 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.
klass | a class which is supported by isOutputSupportedFor(Class) and has a
non-empty array returned by getOutputSizes(Class) |
---|---|
size | an output-compatible size |
>=
0 in nanosecondsIllegalArgumentException | if klass or size was not supported |
---|---|
NullPointerException | if size or klass was null |
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:
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).
format | an image format from ImageFormat or PixelFormat |
---|---|
size | an output-compatible size |
>=
0 in nanosecondsIllegalArgumentException | if format or size was not supported |
---|---|
NullPointerException | if size was null |
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.
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)
.
format | an image format from either ImageFormat or PixelFormat |
---|
true
iff using a surface
with this format
will be
supported with createCaptureSession(List, CameraCaptureSession.StateCallback, Handler)
IllegalArgumentException | if the image format was not a defined named constant
from either ImageFormat or PixelFormat |
---|
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:
getOutputFormats()
getOutputSizes(int)
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.
surface | a non-null Surface object reference |
---|
true
if this is supported, false
otherwiseNullPointerException | if surface was null |
---|---|
IllegalArgumentException | if the Surface endpoint is no longer valid |
Determine whether or not output streams can be configured with a particular class as a consumer.
The following list is generally usable for outputs:
ImageReader
-
Recommended for image processing or streaming to external resources (such as a file or
network)
MediaRecorder
-
Recommended for recording video (simple to use)
MediaCodec
-
Recommended for recording video (more complicated to use, with more flexibility)
Allocation
-
Recommended for image processing with RenderScript
SurfaceHolder
-
Recommended for low-power camera preview with SurfaceView
SurfaceTexture
-
Recommended for OpenGL-accelerated preview processing or compositing with
TextureView
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
.
Since not all of the above classes support output of all format and size combinations,
the particular combination should be queried with isOutputSupportedFor(Surface)
.
klass | a non-null Class object reference |
---|
true
if this class is supported as an output, false
otherwiseNullPointerException | if klass was null |
---|