Platform Android Studio Google Play Jetpack Kotlin Docs News
Overview Guides Reference Samples Design & Quality

Preview

public class Preview
extends UseCase

java.lang.Object
   ↳ androidx.camera.core.UseCase
     ↳ androidx.camera.core.Preview

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

The preview stream is connected to an underlying SurfaceTexture. This SurfaceTexture is created by the Preview use case and provided as an output after it is configured and attached to the camera. The application receives the SurfaceTexture by setting an output listener with setOnPreviewOutputUpdateListener(OnPreviewOutputUpdateListener). When the lifecycle becomes active, the camera will start and images will be streamed to the SurfaceTexture. Preview.OnPreviewOutputUpdateListener.onUpdated(PreviewOutput) is called when a new SurfaceTexture is created. A SurfaceTexture is created each time the use case becomes active and no previous SurfaceTexture exists.

The application can then decide how this texture is shown. The texture data is as received by the camera system with no rotation applied. To display the SurfaceTexture with the correct orientation, the rotation parameter sent to Preview.OnPreviewOutputUpdateListener can be used to create a correct transformation matrix for display. See setTargetRotation(int) and PreviewConfig.Builder.setTargetRotation(int) for details. See setOnPreviewOutputUpdateListener(OnPreviewOutputUpdateListener) for notes if attaching the SurfaceTexture to TextureView.

The application is responsible for managing SurfaceTexture after receiving it. See setOnPreviewOutputUpdateListener(OnPreviewOutputUpdateListener) for notes on if overriding TextureView.SurfaceTextureListener.onSurfaceTextureDestroyed(SurfaceTexture).

Summary

Nested classes

interface Preview.OnPreviewOutputUpdateListener

A listener of Preview.PreviewOutput. 

class Preview.PreviewOutput

A bundle containing a SurfaceTexture and properties needed to display a Preview. 

enum Preview.UseCaseError

Describes the error that occurred during preview operation. 

Public constructors

Preview(PreviewConfig config)

Creates a new preview use case from the given configuration.

Public methods

void enableTorch(boolean torch)

Sets torch on/off.

void focus(Rect focus, Rect metering)

Adjusts the preview according to the properties in some local regions.

void focus(Rect focus, Rect metering, OnFocusListener listener)

Adjusts the preview according to the properties in some local regions with a callback called once focus scan has completed.

Preview.OnPreviewOutputUpdateListener getOnPreviewOutputUpdateListener()

Gets Preview.OnPreviewOutputUpdateListener

boolean isTorchOn()

True if the torch is on

void removePreviewOutputListener()

Removes previously PreviewOutput listener.

void setOnPreviewOutputUpdateListener(Preview.OnPreviewOutputUpdateListener newListener)

Sets a listener to get the Preview.PreviewOutput updates.

void setTargetRotation(int rotation)

Sets the target rotation.

String toString()
void zoom(Rect crop)

Adjusts the preview to zoom to a local region.

Inherited methods

Public constructors

Preview

public Preview (PreviewConfig config)

Creates a new preview use case from the given configuration.

Parameters
config PreviewConfig: for this use case instance

Public methods

enableTorch

public void enableTorch (boolean torch)

Sets torch on/off. When the torch is on, the torch will remain on during photo capture regardless of flash setting. When the torch is off, flash will function as set by ImageCapture.

Parameters
torch boolean: True if turn on torch, otherwise false

focus

public void focus (Rect focus, 
                Rect metering)

Adjusts the preview according to the properties in some local regions.

The auto-focus (AF) and auto-exposure (AE) properties will be recalculated from the local regions.

Dimensions of the sensor coordinate frame can be found using Camera2.

Parameters
focus Rect: rectangle with dimensions in sensor coordinate frame for focus
metering Rect: rectangle with dimensions in sensor coordinate frame for metering

focus

public void focus (Rect focus, 
                Rect metering, 
                OnFocusListener listener)

Adjusts the preview according to the properties in some local regions with a callback called once focus scan has completed.

The auto-focus (AF) and auto-exposure (AE) properties will be recalculated from the local regions.

Dimensions of the sensor coordinate frame can be found using Camera2.

Parameters
focus Rect: rectangle with dimensions in sensor coordinate frame for focus
metering Rect: rectangle with dimensions in sensor coordinate frame for metering
listener OnFocusListener: listener for when focus has completed

getOnPreviewOutputUpdateListener

public Preview.OnPreviewOutputUpdateListener getOnPreviewOutputUpdateListener ()

Gets Preview.OnPreviewOutputUpdateListener

Returns
Preview.OnPreviewOutputUpdateListener the last set listener or null if no listener is set

isTorchOn

public boolean isTorchOn ()

True if the torch is on

Returns
boolean

removePreviewOutputListener

public void removePreviewOutputListener ()

Removes previously PreviewOutput listener.

This is equivalent to calling setOnPreviewOutputUpdateListener(null).

setOnPreviewOutputUpdateListener

public void setOnPreviewOutputUpdateListener (Preview.OnPreviewOutputUpdateListener newListener)

Sets a listener to get the Preview.PreviewOutput updates.

Setting this listener will signal to the camera that the use case is ready to receive data. Setting the listener to null will signal to the camera that the camera should no longer stream data to the last Preview.PreviewOutput.

Once Preview.OnPreviewOutputUpdateListener.onUpdated(PreviewOutput) is called, ownership of the Preview.PreviewOutput and its contents is transferred to the application. It is the application's responsibility to release the last SurfaceTexture returned by Preview.PreviewOutput.getSurfaceTexture() when a new SurfaceTexture is provided via an update or when the user is finished with the use case. A SurfaceTexture is created each time the use case becomes active and no previous SurfaceTexture exists. Preview.OnPreviewOutputUpdateListener.onUpdated(PreviewOutput) is called when a new SurfaceTexture is created.

Calling TextureView.setSurfaceTexture(SurfaceTexture) when the TextureView's SurfaceTexture is already created, should be preceded by calling ViewGroup.removeView(View) and ViewGroup.addView(View) on the parent view of the TextureView to ensure the setSurfaceTexture() call succeeds.

Since Preview.OnPreviewOutputUpdateListener.onUpdated(PreviewOutput) is called when the underlying SurfaceTexture is created, applications that override and return false from TextureView.SurfaceTextureListener.onSurfaceTextureDestroyed(SurfaceTexture) should be sure to call TextureView.setSurfaceTexture(SurfaceTexture) with the output from the previous Preview.PreviewOutput to attach it to a new TextureView, such as on resuming the application.

Parameters
newListener Preview.OnPreviewOutputUpdateListener: The listener which will receive Preview.PreviewOutput updates.

setTargetRotation

public void setTargetRotation (int rotation)

Sets the target rotation.

This informs the use case so it can adjust the rotation value sent to Preview.OnPreviewOutputUpdateListener.

In most cases this should be set to the current rotation returned by Display.getRotation(). In that case, the rotation values output by the use case will be the rotation, which if applied to the output image, will make the image match the display orientation.

If no target rotation is set by the application, it is set to the value of Display.getRotation() of the default display at the time the use case is created.

Parameters
rotation int: Rotation of the surface texture consumer expressed as one of Surface.ROTATION_0, Surface.ROTATION_90, Surface.ROTATION_180, or Surface.ROTATION_270.

toString

public String toString ()

Returns
String

zoom

public void zoom (Rect crop)

Adjusts the preview to zoom to a local region.

Setting the zoom is equivalent to setting a scalar crop region (digital zoom), and zoom occurs about the center of the image.

Dimensions of the sensor coordinate frame can be found using Camera2.

Parameters
crop Rect: rectangle with dimensions in sensor coordinate frame for zooming