Preview.Builder
public
static
final
class
Preview.Builder
extends Object
implements
ExtendableBuilder<T extends UseCase>
java.lang.Object | |
↳ | androidx.camera.core.Preview.Builder |
Builder for a Preview
.
Summary
Public constructors | |
---|---|
Builder()
Creates a new Builder object. |
Public methods | |
---|---|
Preview
|
build()
Builds an immutable |
Preview.Builder
|
setTargetAspectRatio(int aspectRatio)
Sets the aspect ratio of the intended target for images from this configuration. |
Preview.Builder
|
setTargetName(String targetName)
Sets the name of the target object being configured, used only for debug logging. |
Preview.Builder
|
setTargetResolution(Size resolution)
Sets the resolution of the intended target from this configuration. |
Preview.Builder
|
setTargetRotation(int rotation)
Sets the rotation that the intended target resolution is expressed in. |
Inherited methods | |
---|---|
Public constructors
Builder
public Builder ()
Creates a new Builder object.
Public methods
build
public Preview build ()
Builds an immutable Preview
from the current state.
Returns | |
---|---|
Preview |
A Preview populated with the current state. |
Throws | |
---|---|
IllegalArgumentException |
if attempting to set both target aspect ratio and target resolution. |
setTargetAspectRatio
public Preview.Builder setTargetAspectRatio (int aspectRatio)
Sets the aspect ratio of the intended target for images from this configuration.
The aspect ratio is the ratio of width to height in the sensor orientation.
It is not allowed to set both target aspect ratio and target resolution on the same use case. Attempting so will throw an IllegalArgumentException when building the Config.
The target aspect ratio is used as a hint when determining the resulting output aspect ratio which may differ from the request, possibly due to device constraints. Application code should check the resulting output's resolution and the resulting aspect ratio may not be exactly as requested.
For Preview, the value will be used to calculate the suggested resolution size in
SurfaceRequest.getResolution()
.
If not set, resolutions with aspect ratio 4:3 will be considered in higher priority.
For the following devices, the aspect ratio will be forced to
AspectRatio.RATIO_16_9
regardless of the config. On these devices, the
camera HAL produces a preview with a 16:9 aspect ratio regardless of the aspect ratio
of the preview surface.
- SM-J710MN, Samsung Galaxy J7 (2016)
- SM-T580, Samsung Galaxy Tab A J7 (2016)
Parameters | |
---|---|
aspectRatio |
int : The desired Preview AspectRatio |
Returns | |
---|---|
Preview.Builder |
The current Builder. |
setTargetName
public Preview.Builder setTargetName (String targetName)
Sets the name of the target object being configured, used only for debug logging.
The name should be a value that can uniquely identify an instance of the object being configured.
If not set, the target name will default to an unique name automatically generated with the class canonical name and random UUID.
Parameters | |
---|---|
targetName |
String : A unique string identifier for the instance of the class being
configured. |
Returns | |
---|---|
Preview.Builder |
the current Builder. |
setTargetResolution
public Preview.Builder setTargetResolution (Size resolution)
Sets the resolution of the intended target from this configuration.
The target resolution attempts to establish a minimum bound for the preview
resolution. The actual preview resolution will be the closest available resolution in
size that is not smaller than the target resolution, as determined by the Camera
implementation. However, if no resolution exists that is equal to or larger than the
target resolution, the nearest available resolution smaller than the target resolution
will be chosen. Resolutions with the same aspect ratio of the provided Size
will
be considered in higher priority before resolutions of different aspect ratios.
It is not allowed to set both target aspect ratio and target resolution on the same use case. Attempting so will throw an IllegalArgumentException when building the Config.
The resolution Size
should be expressed in the coordinate frame after
rotating the supported sizes by the target rotation. For example, a device with
portrait natural orientation in natural target rotation requesting a portrait image
may specify 480x640, and the same device, rotated 90 degrees and targeting landscape
orientation may specify 640x480.
The maximum available resolution that could be selected for a Preview
is
limited to be under 1080p. The limitation of 1080p for Preview
has considered
both performance and quality factors that users can obtain reasonable quality and smooth
output stream under 1080p.
If not set, the default selected resolution will be the best size match to the device's screen resolution, or to 1080p (1920x1080), whichever is smaller.
Parameters | |
---|---|
resolution |
Size : The target resolution to choose from supported output sizes list. |
Returns | |
---|---|
Preview.Builder |
The current Builder. |
setTargetRotation
public Preview.Builder setTargetRotation (int rotation)
Sets the rotation that the intended target resolution is expressed in.
This sets the rotation that is used when specifying a target resolution using
setTargetResolution(Size)
, which accepts a resolution at the target orientation.
rotation is one of four valid values: Surface.ROTATION_0
, Surface.ROTATION_90
, Surface.ROTATION_180
, Surface.ROTATION_270
.
Rotation values are relative to the "natural" rotation, Surface.ROTATION_0
.
For example a portrait natural device may specify a portrait image target resolution
as 480x640, and the same device rotated to and displaying in landscape (i.e. as
returned by Display.getRotation()
) may set the target rotation to
Surface.ROTATION_90
and resolution to 640x480.
If not set, the target rotation will default to the value of
Display.getRotation()
of the default display at the time the use case is created.
The use case is fully created once it has been attached to a camera.
Note that SurfaceView
does not support non-display rotation. If the target
rotation is different than the value of Display.getRotation()
,
SurfaceView
should not be used to provide the Surface
in
SurfaceRequest.provideSurface(Surface, Executor, Consumer)
Parameters | |
---|---|
rotation |
int : The rotation of the intended target. |
Returns | |
---|---|
Preview.Builder |
The current Builder. |
See also: