Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

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 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
open Bitmap?

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

open PreviewView.ImplementationMode

Returns the ImplementationMode.

open MeteringPointFactory

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

open LiveData<PreviewView.StreamState!>

Gets a LiveData for the preview StreamState.

open PreviewView.ScaleType

Returns the ScaleType currently applied to the preview.

open Preview.SurfaceProvider

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

open ViewPort?

Gets a ViewPort based on the current status of PreviewView.

open ViewPort?
getViewPort(targetRotation: Int)

Gets a ViewPort with custom target rotation.

open Boolean
onTouchEvent(@NonNull event: MotionEvent)

open Boolean

open Unit

Sets the ImplementationMode for the PreviewView.

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

getBitmap

@UiThread @Nullable open 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.

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.

getImplementationMode

@UiThread @NonNull open 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 open 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.

When the PreviewView has a width and/or height equal to zero, or when a preview Surface is not yet requested by the camera, 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 the application to crash.

Return
MeteringPointFactory a MeteringPointFactory

getPreviewStreamState

@UiThread @NonNull open 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!> A LiveData of the preview's StreamState. Apps can get the current state with LiveData#getValue(), or register an observer with LiveData#observe .

getScaleType

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

getSurfaceProvider

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

Gets a Preview.SurfaceProvider to be used with Preview#setSurfaceProvider(Executor, Preview.SurfaceProvider). This allows the camera feed to start when the Preview use case is bound to a lifecycle.

The returned Preview.SurfaceProvider will provide a preview Surface to the camera that's either managed by a TextureView or SurfaceView depending on the ImplementationMode and the device's attributes (e.g. API level, camera hardware support level).

Return
Preview.SurfaceProvider A Preview.SurfaceProvider to attach to a Preview use case.

getViewPort

@UiThread @Nullable open fun getViewPort(): ViewPort?

Gets a ViewPort based on the current status of PreviewView.

Returns a ViewPort instance based on the PreviewView's current width, height, layout direction, scale type and display rotation. By using the ViewPort, all the UseCases in the UseCaseGroup will have the same output image that also matches the aspect ratio of the PreviewView.

getViewPort

@UiThread @Nullable open fun getViewPort(targetRotation: Int): ViewPort?

Gets a ViewPort with custom target rotation.

Returns a ViewPort instance based on the PreviewView's current width, height, layout direction, scale type and the given target rotation.

Use this method if Preview's desired rotation is not the default display rotation. For example, when remote display is in use and the desired rotation for the remote display is based on the accelerometer reading. In that case, use android.view.OrientationEventListener to obtain the target rotation and create ViewPort as 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

Once the target rotation is obtained, use it with Preview#setTargetRotation to update the rotation. Example:

<code>
      Preview preview = new Preview.Builder().setTargetRotation(targetRotation).build();
      ViewPort viewPort = previewView.getViewPort(targetRotation);
      UseCaseGroup useCaseGroup =
          new UseCaseGroup.Builder().setViewPort(viewPort).addUseCase(preview).build();
      cameraProvider.bindToLifecycle(lifecycleOwner, cameraSelector, useCaseGroup);
      </code>

Note that for non-display rotation to work, the mode must be set to ImplementationMode#COMPATIBLE.

Parameters
targetRotation Int: A rotation value, expressed as one of Surface#ROTATION_0, Surface#ROTATION_90, Surface#ROTATION_180, or Surface#ROTATION_270.

onTouchEvent

open fun onTouchEvent(@NonNull event: MotionEvent): Boolean

performClick

open fun performClick(): Boolean

setImplementationMode

@UiThread open fun setImplementationMode(@NonNull implementationMode: PreviewView.ImplementationMode): Unit

Sets the ImplementationMode for the PreviewView.

PreviewView displays the preview with a TextureView when the mode is ImplementationMode#COMPATIBLE, and tries to use a SurfaceView if it is ImplementationMode#PERFORMANCE when possible, which depends on the device's attributes (e.g. API level, camera hardware support level). If not set, the default mode is ImplementationMode#PERFORMANCE.

setScaleType

@UiThread 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