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

PreviewView

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 preview Surface's lifecycle. It internally uses either a TextureView or SurfaceView to display the camera feed, and applies required transformations on them to correctly display the preview, this involves correcting their aspect ratio, scale and rotation.

If PreviewView uses a SurfaceView to display the preview stream, be careful when overlapping a View that's initially not visible (either View#INVISIBLE or View#GONE) on top of it. When the SurfaceView is attached to the display window, it calls android.view.ViewParent#requestTransparentRegion(View) which requests a computation of the transparent regions on the display. At this point, the View isn't visible, causing the overlapped region between the SurfaceView and the View to be considered transparent. Later if the View becomes visible, it will not be displayed on top of SurfaceView. A way around this is to call android.view.ViewParent#requestTransparentRegion(View) right after making the View visible, or initially hiding the View by setting its opacity to 0, then setting it to 1.0F to show it.

Summary

Nested classes

The implementation mode of a PreviewView.

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

Definitions for the 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
Bitmap?

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

CameraController?

Get the CameraController.

PreviewView.ImplementationMode

Returns the ImplementationMode.

MeteringPointFactory

Gets the MeteringPointFactory for the camera currently connected to the PreviewView, if any.

LiveData<PreviewView.StreamState!>

Gets a LiveData for the preview StreamState.

PreviewView.ScaleType

Returns the ScaleType currently applied to the preview.

Preview.SurfaceProvider

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

ViewPort?

Gets a ViewPort based on the current status of PreviewView.

ViewPort?
getViewPort(targetRotation: Int)

Gets a ViewPort with custom target rotation.

Boolean
onTouchEvent(@NonNull event: MotionEvent)

Boolean

Unit
setController(@Nullable cameraController: CameraController?)

Sets the CameraController.

Unit

Sets the ImplementationMode for the PreviewView.

Unit
setScaleType(@NonNull scaleType: PreviewView.ScaleType)

Applies a ScaleType to the preview.

Protected methods
Unit

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

getBitmap

@UiThread @Nullable fun getBitmap(): Bitmap?

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

The returned Bitmap uses the Bitmap.Config#ARGB_8888 pixel format and its dimensions are the same as this view's.

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.

If the preview hasn't started yet, the method may return null or an empty Bitmap. Use getPreviewStreamState() to get the StreamState and wait for StreamState#STREAMING to make sure the preview is started.

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

getController

@Nullable @UiThread fun getController(): CameraController?

Get the CameraController.

getImplementationMode

@UiThread @NonNull fun getImplementationMode(): PreviewView.ImplementationMode

Returns the ImplementationMode.

If nothing is set via setImplementationMode, the default value is ImplementationMode#PERFORMANCE.

Return
PreviewView.ImplementationMode The ImplementationMode for PreviewView.

getMeteringPointFactory

@UiThread @NonNull fun getMeteringPointFactory(): MeteringPointFactory

Gets the MeteringPointFactory for the camera currently connected to the PreviewView, if any.

The returned MeteringPointFactory is capable of creating MeteringPoints from (x, y) coordinates in the PreviewView. This conversion takes into account its ScaleType. The MeteringPointFactory is automatically adjusted if the PreviewView layout or the ScaleType changes.

The MeteringPointFactory returns invalid MeteringPoint if the preview is not ready, or the PreviewView dimension is zero. The invalid MeteringPoint will cause CameraControl#startFocusAndMetering(FocusMeteringAction) to fail but it won't crash the application. Wait for the StreamState#STREAMING state to make sure the preview is ready.

Return
MeteringPointFactory a MeteringPointFactory

getPreviewStreamState

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

Gets a LiveData for the preview StreamState.

There are two preview stream states, StreamState#IDLE and StreamState#STREAMING. StreamState#IDLE indicates the preview is currently not visible and streaming is stopped. StreamState#STREAMING means the preview is streaming or is about to start streaming. This state guarantees the preview is visible only when the ImplementationMode is ImplementationMode#COMPATIBLE. When in ImplementationMode#PERFORMANCE mode, it is possible the preview becomes visible slightly after the state changes to StreamState#STREAMING.

Apps that require a precise signal for when the preview starts should set the implementation mode to ImplementationMode#COMPATIBLE.

Return
LiveData<PreviewView.StreamState