Preview


public final class Preview extends UseCase


A use case that provides a camera preview stream for displaying on-screen.

The preview stream is connected to the Surface provided via SurfaceProvider. The application decides how the Surface is shown, and is responsible for managing the Surface lifecycle after providing it.

To display the preview with the correct orientation, app needs to take different actions based on the source of the Surface. If the Surface is backed by a SurfaceView, it will always be in the device's display orientation. If the Surface is backed by ImageReader, MediaCodec or other objects, it's the application's responsibility to calculate the rotation. If the Surface is backed by a SurfaceTexture, getTransformMatrix can be used to transform the preview to natural orientation. The value is available after a frame is pushed to the SurfaceTexture and its onFrameAvailable has been called. TextureView handles this automatically and always puts the preview in the natural orientation. To further transform the TextureView to display orientation, the app needs to apply the current display rotation. Example:

        switch (getWindowManager().getDefaultDisplay().getRotation()) {
            case Surface.ROTATION_0:
                displayRotation = 0;
                break;
            case Surface.ROTATION_90:
                displayRotation = 90;
                break;
            case Surface.ROTATION_180:
                displayRotation = 180;
                break;
            case Surface.ROTATION_270:
                displayRotation = 270;
                break;
            default:
                throw new UnsupportedOperationException(
                        "Unsupported display rotation: " + displayRotation);
        }
        matrix.postRotate(-displayRotation, centerX, centerY);
        textureView.setTransform(matrix);
    

Summary

Nested types

public final class Preview.Builder implements ExtendableBuilder

Builder for a Preview.

public interface Preview.SurfaceProvider

A interface implemented by the application to provide a Surface for Preview.

Public methods

@NonNull DynamicRange

Returns the dynamic range.

static @NonNull PreviewCapabilities

Returns PreviewCapabilities to query preview stream related device capability.

@Nullable ResolutionInfo

Gets selected resolution information of the Preview.

@Nullable ResolutionSelector

Returns the resolution selector setting.

@NonNull Range<Integer>

Returns the target frame rate range, in frames per second, for the associated Preview use case.

int

Returns the rotation that the intended target resolution is expressed in.

boolean

Returns whether video stabilization is enabled for preview stream.

void

Sets a SurfaceProvider to provide a Surface for Preview.

void
@UiThread
setSurfaceProvider(
    @NonNull Executor executor,
    @Nullable Preview.SurfaceProvider surfaceProvider
)

Sets a SurfaceProvider to provide a Surface for Preview.

void
setTargetRotation(int targetRotation)

Sets the target rotation.

@NonNull String

Inherited methods

From androidx.camera.core.UseCase
static int
snapToSurfaceRotation(@IntRange(from = 0, to = 359) int orientation)

A utility function that can convert the orientation degrees of OrientationEventListener to the nearest Surface rotation.

Public methods

getDynamicRange

Added in 1.4.0
public @NonNull DynamicRange getDynamicRange()

Returns the dynamic range.

The dynamic range is set by setDynamicRange. If the dynamic range set is not a fully defined dynamic range, such as HDR_UNSPECIFIED_10_BIT, then it will be returned just as provided, and will not be returned as a fully defined dynamic range. The fully defined dynamic range, which is determined by resolving the combination of requested dynamic ranges from other use cases according to the device capabilities, will be communicated to the Preview.SurfaceProvider via getDynamicRange}.

If the dynamic range was not provided to setDynamicRange, this will return the default of UNSPECIFIED

Returns
@NonNull DynamicRange

the dynamic range set for this Preview use case.

See also
setDynamicRange

getPreviewCapabilities

Added in 1.4.0
public static @NonNull PreviewCapabilities getPreviewCapabilities(@NonNull CameraInfo cameraInfo)

Returns PreviewCapabilities to query preview stream related device capability.

getResolutionInfo

Added in 1.1.0
public @Nullable ResolutionInfo getResolutionInfo()

Gets selected resolution information of the Preview.

The returned ResolutionInfo will be expressed in the coordinates of the camera sensor. It will be the same as the resolution inside a SurfaceRequest to request a surface for Preview.

The resolution information might change if the use case is unbound and then rebound or setTargetRotation is called to change the target rotation setting. The application needs to call getResolutionInfo again to get the latest ResolutionInfo for the changes.

Returns
@Nullable ResolutionInfo

the resolution information if the use case has been bound by the bindToLifecycle API, or null if the use case is not bound yet.

getResolutionSelector

Added in 1.3.0
public @Nullable ResolutionSelector getResolutionSelector()

Returns the resolution selector setting.

This setting is set when constructing a Preview using setResolutionSelector.

getTargetFrameRate

Added in 1.3.0
public @NonNull Range<IntegergetTargetFrameRate()

Returns the target frame rate range, in frames per second, for the associated Preview use case.

The target frame rate can be set prior to constructing a Preview using setTargetFrameRate. If not set, the target frame rate defaults to the value of FRAME_RATE_RANGE_UNSPECIFIED.

This is just the frame rate range requested by the user, and may not necessarily be equal to the range the camera is actually operating at.

Returns
@NonNull Range<Integer>

the target frame rate range of this Preview.

getTargetRotation

Added in 1.0.0
public int getTargetRotation()

Returns the rotation that the intended target resolution is expressed in.

The rotation is set when constructing an Preview instance using setTargetRotation. If not set, the target rotation defaults to the value of 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.

Returns
int

The rotation of the intended target.

isPreviewStabilizationEnabled

Added in 1.4.0
public boolean isPreviewStabilizationEnabled()

Returns whether video stabilization is enabled for preview stream.

setSurfaceProvider

Added in 1.0.0
@UiThread
public void setSurfaceProvider(@Nullable Preview.SurfaceProvider surfaceProvider)

Sets a SurfaceProvider to provide a Surface for Preview.

Setting the provider will signal to the camera that the use case is ready to receive data. The provider will be triggered on main thread. If the provider is removed by calling this again with a null SurfaceProvider then the camera will stop producing data for this Preview instance.

Parameters
@Nullable Preview.SurfaceProvider surfaceProvider

SurfaceProvider that provides a Surface for Preview. This will replace the previous SurfaceProvider set either this method or setSurfaceProvider.

setSurfaceProvider

Added in 1.0.0
@UiThread
public void setSurfaceProvider(
    @NonNull Executor executor,
    @Nullable Preview.SurfaceProvider surfaceProvider
)

Sets a SurfaceProvider to provide a Surface for Preview.

Setting the provider will signal to the camera that the use case is ready to receive data. If the provider is removed by calling this again with a null SurfaceProvider then the camera will stop producing data for this Preview instance.

Parameters
@NonNull Executor executor

on which the surfaceProvider will be invoked.

@Nullable Preview.SurfaceProvider surfaceProvider

SurfaceProvider that provides a Surface for Preview. This will replace the previous SurfaceProvider set either this method or setSurfaceProvider.

setTargetRotation

Added in 1.0.0
public void setTargetRotation(int targetRotation)

Sets the target rotation.

This adjust the getTargetRotation, which once applied will update the output to match target rotation specified here.

While rotation can also be set via setTargetRotation , using setTargetRotation allows the target rotation to be set without rebinding new use cases. When this function is called, value set by setTargetResolution will be updated automatically to make sure the suitable resolution can be selected when the use case is bound.

If not set here or by configuration, the target rotation will default to the value of 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.

Parameters
int targetRotation

Target rotation of the output image, expressed as one of ROTATION_0, ROTATION_90, ROTATION_180, or ROTATION_270.

toString

public @NonNull String toString()