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 the Surface provided via PreviewSurfaceProvider. 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, SurfaceTexture#getTransformMatrix(float[]) can be used to transform the preview to natural orientation. The value is available after a frame is pushed to the SurfaceTexture and its SurfaceTexture.OnFrameAvailableListener#onFrameAvailable(SurfaceTexture) 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:

<code>
          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);
      </code>

Summary

Nested classes

Builder for a Preview.

abstract

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

Public methods

open Preview.PreviewSurfaceProvider?

Gets PreviewSurfaceProvider

open Unit
setPreviewSurfaceProvider(@NonNull executor: Executor, @Nullable previewSurfaceProvider: Preview.PreviewSurfaceProvider?)

Sets a PreviewSurfaceProvider to provide Surface for Preview.

open Unit
setPreviewSurfaceProvider(@Nullable previewSurfaceProvider: Preview.PreviewSurfaceProvider?)

Sets a PreviewSurfaceProvider to provide Surface for Preview.

open String

Public methods

getPreviewSurfaceProvider

@UiThread @Nullable open fun getPreviewSurfaceProvider(): Preview.PreviewSurfaceProvider?

Gets PreviewSurfaceProvider

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

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

setPreviewSurfaceProvider

@UiThread open fun setPreviewSurfaceProvider(@NonNull executor: Executor, @Nullable previewSurfaceProvider: Preview.PreviewSurfaceProvider?): Unit

Sets a PreviewSurfaceProvider to provide Surface for Preview.

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

Parameters
executor Executor: on which the previewSurfaceProvider will be triggered.
previewSurfaceProvider Executor: PreviewSurfaceProvider that provides a Preview.

setPreviewSurfaceProvider

@UiThread open fun setPreviewSurfaceProvider(@Nullable previewSurfaceProvider: Preview.PreviewSurfaceProvider?): Unit

Sets a PreviewSurfaceProvider to provide 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.

Parameters
previewSurfaceProvider Preview.PreviewSurfaceProvider?: PreviewSurfaceProvider that provides a Preview.

toString

@NonNull open fun toString(): String