The Android Developer Challenge is back! Submit your idea before December 2.

Preview

open class Preview : UseCase
kotlin.Any
   ↳ 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 Preview#setOnPreviewOutputUpdateListener(OnPreviewOutputUpdateListener). When the lifecycle becomes active, the camera will start and images will be streamed to the SurfaceTexture. 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 Preview#setOnPreviewOutputUpdateListener(OnPreviewOutputUpdateListener) for notes if attaching the SurfaceTexture to android.view.TextureView.

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

Summary

Nested classes

abstract

A listener of PreviewOutput.

abstract

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

abstract

A callback to access the Preview Surface.

Describes the error that occurred during preview operation.

Public constructors

<init>(@NonNull config: PreviewConfig)

Creates a new preview use case from the given configuration.

Public methods

open Unit

Sets torch on/off.

open Preview.OnPreviewOutputUpdateListener?

Gets OnPreviewOutputUpdateListener

open Preview.PreviewSurfaceCallback?

Gets PreviewSurfaceCallback

open Boolean

True if the torch is on

open Unit

Un-register a listener previously registered via Preview#setOnPreviewOutputUpdateListener(OnPreviewOutputUpdateListener).

open Unit

Removes the PreviewSurfaceCallback.

open Unit

Sets a listener to get the PreviewOutput updates.

open Unit

Sets a listener and its executor to get the PreviewOutput updates.

open Unit

Sets a PreviewSurfaceCallback to provide Surface for Preview.

open Unit

Sets the target rotation.

open String

open Unit
zoom(crop: Rect!)

Adjusts the preview to zoom to a local region.

Inherited functions

Public constructors

<init>

Preview(@NonNull config: PreviewConfig)

Creates a new preview use case from the given configuration.

Parameters
config PreviewConfig: for this use case instance

Public methods

enableTorch

open fun enableTorch(torch: Boolean): Unit

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

getOnPreviewOutputUpdateListener

@UiThread @Nullable open fun getOnPreviewOutputUpdateListener(): Preview.OnPreviewOutputUpdateListener?

Gets OnPreviewOutputUpdateListener

Return
Preview.OnPreviewOutputUpdateListener?: the last set listener or null if no listener is set
Exceptions
IllegalStateException If not called on main thread.

getPreviewSurfaceCallback

@UiThread @Nullable open fun getPreviewSurfaceCallback(): Preview.PreviewSurfaceCallback?

Gets PreviewSurfaceCallback

Return
Preview.PreviewSurfaceCallback?: the last set callback or null if no listener is set

isTorchOn

open fun isTorchOn(): Boolean

True if the torch is on

removePreviewOutputListener

@UiThread open fun removePreviewOutputListener(): Unit

Un-register a listener previously registered via Preview#setOnPreviewOutputUpdateListener(OnPreviewOutputUpdateListener). It will signal to the camera that the camera should no longer stream data to the last PreviewOutput.

Exceptions
IllegalStateException If not called on main thread.

removePreviewSurfaceCallback

@UiThread open fun removePreviewSurfaceCallback(): Unit

Removes the PreviewSurfaceCallback.

Removing the callback will signal to the camera that the camera should no longer stream data.

setOnPreviewOutputUpdateListener

@UiThread open fun setOnPreviewOutputUpdateListener(@NonNull newListener: Preview.OnPreviewOutputUpdateListener): Unit

Sets a listener to get the PreviewOutput updates.

Setting this listener will signal to the camera that the use case is ready to receive data.

Once OnPreviewOutputUpdateListener#onUpdated(PreviewOutput) is called, ownership of the PreviewOutput and its contents is transferred to the application. It is the application's responsibility to release the last SurfaceTexture returned by 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. OnPreviewOutputUpdateListener#onUpdated(PreviewOutput) is called when a new SurfaceTexture is created.

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

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

The listener will run on the UI thread. See Preview#setOnPreviewOutputUpdateListener(Executor, OnPreviewOutputUpdateListener) to set the updates run on the given executor.

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

setOnPreviewOutputUpdateListener

@UiThread open fun setOnPreviewOutputUpdateListener(@NonNull executor: Executor, @NonNull newListener: Preview.OnPreviewOutputUpdateListener): Unit

Sets a listener and its executor to get the PreviewOutput updates.

See Preview#setOnPreviewOutputUpdateListener(OnPreviewOutputUpdateListener) for more information.

Parameters
executor Executor: The executor on which the listener should be invoked.
newListener Executor: The listener which will receive PreviewOutput updates.
Exceptions
IllegalStateException If not called on main thread.

setPreviewSurfaceCallback

@UiThread open fun setPreviewSurfaceCallback(@NonNull previewSurfaceCallback: Preview.PreviewSurfaceCallback): Unit

Sets a PreviewSurfaceCallback to provide Surface for Preview.

Setting the callback will signal to the camera that the use case is ready to receive data.

Parameters
previewSurfaceCallback Preview.PreviewSurfaceCallback: PreviewSurfaceCallback that provides a Preview.

setTargetRotation

open fun setTargetRotation(rotation: Int): Unit

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 . 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

@NonNull open fun toString(): String

zoom

open fun zoom(crop: Rect!): Unit

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