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

PreviewView

public class PreviewView
extends FrameLayout

java.lang.Object
   ↳ 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 TextureView or SurfaceView to display the camera feed.

Summary

Nested classes

enum PreviewView.ImplementationMode

The implementation mode of a PreviewView

enum PreviewView.ScaleType

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

enum PreviewView.StreamState

Definitions for current preview stream state. 

Inherited constants

Inherited fields

Public constructors

PreviewView(Context context)
PreviewView(Context context, AttributeSet attrs)
PreviewView(Context context, AttributeSet attrs, int defStyleAttr)
PreviewView(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes)

Public methods

MeteringPointFactory createMeteringPointFactory(CameraSelector cameraSelector)

Creates a MeteringPointFactory by a given CameraSelector

The returned MeteringPointFactory is capable of creating MeteringPoints from (x, y) coordinates in the PreviewView.

Preview.SurfaceProvider createSurfaceProvider()

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

Bitmap getBitmap()

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

int getDeviceRotationForRemoteDisplayMode()

Returns the device rotation value currently applied to the preview.

PreviewView.ImplementationMode getPreferredImplementationMode()

Returns the preferred PreviewView.ImplementationMode for preview.

LiveData<PreviewView.StreamState> getPreviewStreamState()

Gets the LiveData of current preview PreviewView.StreamState.

PreviewView.ScaleType getScaleType()

Returns the PreviewView.ScaleType currently applied to the preview.

void setDeviceRotationForRemoteDisplayMode(int deviceRotation)

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

void setPreferredImplementationMode(PreviewView.ImplementationMode preferredMode)

Specifies the preferred PreviewView.ImplementationMode to use for preview.

void setScaleType(PreviewView.ScaleType scaleType)

Applies a PreviewView.ScaleType to the preview.

Protected methods

void onAttachedToWindow()
void onDetachedFromWindow()

Inherited methods

Public constructors

PreviewView

public PreviewView (Context context)

Parameters
context Context

PreviewView

public PreviewView (Context context, 
                AttributeSet attrs)

Parameters
context Context

attrs AttributeSet

PreviewView

public PreviewView (Context context, 
                AttributeSet attrs, 
                int defStyleAttr)

Parameters
context Context

attrs AttributeSet

defStyleAttr int

PreviewView

public PreviewView (Context context, 
                AttributeSet attrs, 
                int defStyleAttr, 
                int defStyleRes)

Parameters
context Context

attrs AttributeSet

defStyleAttr int

defStyleRes int

Public methods

createMeteringPointFactory

public MeteringPointFactory createMeteringPointFactory (CameraSelector cameraSelector)

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 PreviewView.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 CameraControl.startFocusAndMetering(FocusMeteringAction) but it won't cause any crash.

Parameters
cameraSelector CameraSelector: the CameraSelector which the Preview is bound to.

Returns
MeteringPointFactory a MeteringPointFactory

createSurfaceProvider

public Preview.SurfaceProvider createSurfaceProvider ()

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

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

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

getBitmap

public Bitmap getBitmap ()

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 PreviewView.ScaleType. When the PreviewView.ScaleType is PreviewView.ScaleType.FILL_START, PreviewView.ScaleType.FILL_CENTER or PreviewView.ScaleType.FILL_END, the returned Bitmap has the same size as the PreviewView. However, when the PreviewView.ScaleType is PreviewView.ScaleType.FIT_START, PreviewView.ScaleType.FIT_CENTER or PreviewView.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.

Returns
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

public int getDeviceRotationForRemoteDisplayMode ()

Returns the device rotation value currently applied to the preview.

Returns
int The device rotation value currently applied to the preview.

getPreferredImplementationMode

public PreviewView.ImplementationMode getPreferredImplementationMode ()

Returns the preferred PreviewView.ImplementationMode for preview.

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

Returns
PreviewView.ImplementationMode The preferred PreviewView.ImplementationMode for preview.

getPreviewStreamState

public LiveData<PreviewView.StreamState> getPreviewStreamState ()

Gets the LiveData of current preview PreviewView.StreamState.

There are two states, PreviewView.StreamState.IDLE and PreviewView.StreamState.STREAMING. PreviewView.StreamState.IDLE represents the preview is currently not visible and streaming is stopped. PreviewView.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(PreviewView.ImplementationMode).

Returns
LiveData<PreviewView.StreamState> A LiveData containing the PreviewView.StreamState. Apps can either get current value by LiveData.getValue() or register a observer by LiveData.observe(LifecycleOwner, Observer) .

getScaleType

public PreviewView.ScaleType getScaleType ()

Returns the PreviewView.ScaleType currently applied to the preview.

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

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

setDeviceRotationForRemoteDisplayMode

public void setDeviceRotationForRemoteDisplayMode (int deviceRotation)

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

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

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

public void setPreferredImplementationMode (PreviewView.ImplementationMode preferredMode)

Specifies the preferred PreviewView.ImplementationMode to use for preview.

When the preferred PreviewView.ImplementationMode is PreviewView.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 CameraMetadata.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY), the actual implementation mode will be PreviewView.ImplementationMode.TEXTURE_VIEW.

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

setScaleType

public void setScaleType (PreviewView.ScaleType scaleType)

Applies a PreviewView.ScaleType to the preview.

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

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

Protected methods

onAttachedToWindow

protected void onAttachedToWindow ()

onDetachedFromWindow

protected void onDetachedFromWindow ()