Google is committed to advancing racial equity for Black communities. See how.

PreviewView

open class PreviewView : FrameLayout
kotlin.Any
   ↳ android.view.View
   ↳ android.view.ViewGroup
   ↳ android.widget.FrameLayout
   ↳ androidx.camera.view.PreviewView

Custom View that displays the camera feed for CameraX's Preview use case.

This class manages the Surface lifecycle, as well as the preview aspect ratio and orientation. Internally, it uses either a android.view.TextureView or android.view.SurfaceView to display the camera feed.

Summary

Nested classes

The implementation mode of a PreviewView.

Options for scaling the preview vis-à-vis its container PreviewView.

Definitions for current preview stream state.

Public constructors

<init>(@NonNull context: Context)

<init>(@NonNull context: Context, @Nullable attrs: AttributeSet?)

<init>(@NonNull context: Context, @Nullable attrs: AttributeSet?, defStyleAttr: Int)

<init>(@NonNull context: Context, @Nullable attrs: AttributeSet?, defStyleAttr: Int, defStyleRes: Int)

Public methods

open MeteringPointFactory
createMeteringPointFactory(@NonNull cameraSelector: CameraSelector)

Creates a MeteringPointFactory by a given CameraSelector

open Preview.SurfaceProvider

Gets the Preview.SurfaceProvider to be used with Preview#setSurfaceProvider(Executor, Preview.SurfaceProvider).

open Bitmap?

Returns a Bitmap representation of the content displayed on the preview Surface, or null if the camera preview hasn't started yet.

open Int

Returns the device rotation value currently applied to the preview.

open PreviewView.ImplementationMode

Returns the preferred ImplementationMode for preview.

open LiveData<PreviewView.StreamState!>

Gets the LiveData of current preview StreamState.

open PreviewView.ScaleType

Returns the ScaleType currently applied to the preview.

open Unit

Provides the device rotation value to the preview in remote display mode.

open Unit

Specifies the preferred ImplementationMode to use for preview.

open Unit
setScaleType(@NonNull scaleType: PreviewView.ScaleType)

Applies a ScaleType to the preview.

Protected methods

open Unit

open Unit

Public constructors

<init>

PreviewView(@NonNull context: Context)

<init>

PreviewView(
    @NonNull context: Context,
    @Nullable attrs: AttributeSet?)

<init>

PreviewView(
    @NonNull context: Context,
    @Nullable attrs: AttributeSet?,
    defStyleAttr: Int)

<init>

PreviewView(
    @NonNull context: Context,
    @Nullable attrs: AttributeSet?,
    defStyleAttr: Int,
    defStyleRes: Int)

Public methods

createMeteringPointFactory

@NonNull open fun createMeteringPointFactory(@NonNull cameraSelector: CameraSelector): MeteringPointFactory

Creates a MeteringPointFactory by a given CameraSelector

The returned MeteringPointFactory is capable of creating MeteringPoints from (x, y) coordinates in the PreviewView. This conversion takes into account its ScaleType. It is recommended to call this method to create a new factory every time you start a focus and metering action, instead of caching the factory instance.

When the PreviewView has a width and/or height equal to zero, or when a preview Surface is not yet requested, the returned factory will always create invalid MeteringPoints which could lead to the failure of androidx.camera.core.CameraControl#startFocusAndMetering(FocusMeteringAction) but it won't cause any crash.

Parameters
cameraSelector CameraSelector: the CameraSelector which the Preview is bound to.
Return
MeteringPointFactory a MeteringPointFactory

createSurfaceProvider

@NonNull @UiThread open fun createSurfaceProvider(): Preview.SurfaceProvider

Gets the Preview.SurfaceProvider to be used with Preview#setSurfaceProvider(Executor, Preview.SurfaceProvider).

The returned Preview.SurfaceProvider will provide a preview android.view.Surface to the camera that's either managed by a android.view.TextureView or android.view.SurfaceView. This option is determined by the preferred implementation mode and the device's capabilities.

Return
Preview.SurfaceProvider A Preview.SurfaceProvider used to start the camera preview.

getBitmap

@Nullable open fun getBitmap(): Bitmap?

Returns a Bitmap representation of the content displayed on the preview Surface, or null if the camera preview hasn't started yet.

The returned Bitmap uses the Bitmap.Config#ARGB_8888 pixel format, and its dimensions depend on the PreviewView's ScaleType. When the ScaleType is ScaleType#FILL_START, ScaleType#FILL_CENTER or ScaleType#FILL_END, the returned Bitmap has the same size as the PreviewView. However, when the ScaleType is ScaleType#FIT_START, ScaleType#FIT_CENTER or ScaleType#FIT_END, the returned Bitmap might be smaller than the PreviewView, since it doesn't also include its background.

Do not invoke this method from a drawing method (View#onDraw(Canvas) for instance).

If an error occurs during the copy, an empty Bitmap will be returned.

Return
Bitmap? A Bitmap.Config#ARGB_8888 Bitmap representing the content displayed on the preview Surface, or null if the camera preview hasn't started yet.

getDeviceRotationForRemoteDisplayMode

open fun getDeviceRotationForRemoteDisplayMode(): Int

Returns the device rotation value currently applied to the preview.

Return
Int The device rotation value currently applied to the preview.

getPreferredImplementationMode

@NonNull open fun getPreferredImplementationMode(): PreviewView.ImplementationMode

Returns the preferred ImplementationMode for preview.

If the preferred ImplementationMode hasn't been set using setPreferredImplementationMode(ImplementationMode), it defaults to ImplementationMode#SURFACE_VIEW.

Return
PreviewView.ImplementationMode The preferred ImplementationMode for preview.

getPreviewStreamState

@NonNull open fun getPreviewStreamState(): LiveData<PreviewView.StreamState!>

Gets the LiveData of current preview StreamState.

There are two states, StreamState#IDLE and StreamState#STREAMING. StreamState#IDLE represents the preview is currently not visible and streaming is stopped. StreamState#STREAMING means the preview is streaming.

When it's in STREAMING state, it guarantees preview is visible only when implementationMode is TEXTURE_VIEW. When in SURFACE_VIEW implementationMode, it is possible that preview becomes visible slightly after state changes to STREAMING. For apps relying on the preview visible signal to be working correctly, please set TEXTURE_VIEW mode by setPreferredImplementationMode.

Return
LiveData<PreviewView.StreamState!> A LiveData containing the StreamState. Apps can either get current value by LiveData#getValue() or register a observer by LiveData#observe .

getScaleType

@NonNull open fun getScaleType(): PreviewView.ScaleType

Returns the ScaleType currently applied to the preview.

By default, ScaleType#FILL_CENTER is applied to the preview.

Return
PreviewView.ScaleType The ScaleType currently applied to the preview.

setDeviceRotationForRemoteDisplayMode

open fun setDeviceRotationForRemoteDisplayMode(deviceRotation: Int): Unit

Provides the device rotation value to the preview in remote display mode.

The device rotation value will only take effect when detecting current view is on a remote display. If current view is on the device builtin display, PreviewView will directly use view's rotation value to do the transformation related calculations.

The preview transform calculations have strong dependence on the device rotation value. When a application is running in remote display, the rotation value obtained from current view will cause incorrect transform calculation results. To make the preview output result correct in remote display mode, the developers need to provide the device rotation value obtained from android.view.OrientationEventListener.

The mapping between the device rotation value and the orientation value obtained from android.view.OrientationEventListener are listed as the following.

android.view.OrientationEventListener#ORIENTATION_UNKNOWN: orientation == -1

Surface#ROTATION_0: orientation >= 315 || orientation < 45

Surface#ROTATION_90: orientation >= 225 && orientation < 315

Surface#ROTATION_180: orientation >= 135 && orientation < 225

Surface#ROTATION_270: orientation >= 45 && orientation < 135

Parameters
deviceRotation Int: The device rotation value, expressed as one of Surface#ROTATION_0, Surface#ROTATION_90, Surface#ROTATION_180, or Surface#ROTATION_270.

setPreferredImplementationMode

open fun setPreferredImplementationMode(@NonNull preferredMode: PreviewView.ImplementationMode): Unit

Specifies the preferred ImplementationMode to use for preview.

When the preferred ImplementationMode is ImplementationMode#SURFACE_VIEW but the device doesn't support this mode (e.g. devices with API level not newer than Android 7.0 or a supported camera hardware level android.hardware.camera2.CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY), the actual implementation mode will be ImplementationMode#TEXTURE_VIEW.

Parameters
preferredMode PreviewView.ImplementationMode: SURFACE_VIEW if a android.view.SurfaceView should be used to display the camera feed -when possible-, or TEXTURE_VIEW to use a android.view.TextureView.

setScaleType

open fun setScaleType(@NonNull scaleType: PreviewView.ScaleType): Unit

Applies a ScaleType to the preview.

Note that the ScaleType#FILL_CENTER is applied to the preview by default.

Parameters
scaleType PreviewView.ScaleType: A ScaleType to apply to the preview.

Protected methods

onAttachedToWindow

protected open fun onAttachedToWindow(): Unit

onDetachedFromWindow

protected open fun onDetachedFromWindow(): Unit