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 INVISIBLE or GONE) on top of it. When the SurfaceView is attached to the display window, it calls requestTransparentRegion 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 requestTransparentRegion 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.
There are some limitations of transition animations to SurfaceView and TextureView, which applies to PreviewView as well.
| See also | |
|---|---|
Limitations |
Summary
Nested types |
|---|
|
The implementation mode of a |
|
Options for scaling the preview vis-à-vis its container |
|
Definitions for the preview stream state. |
Public constructors |
|---|
@UiThread |
@UiThread |
@UiThread |
@UiThread |
Public functions |
|
|---|---|
Bitmap? |
Returns a |
CameraController? |
Get the |
PreviewView.ImplementationMode |
Returns the |
MeteringPointFactory |
Gets the |
OutputTransform? |
Gets the |
LiveData<PreviewView.StreamState!> |
Gets a |
PreviewView.ScaleType |
Returns the |
ImageCapture.ScreenFlash? |
Returns an |
Matrix? |
Gets the transformation matrix from camera sensor to |
Preview.SurfaceProvider |
Gets a |
ViewPort? |
Gets a |
ViewPort? |
@UiThreadGets a |
Boolean |
onTouchEvent(event: MotionEvent) |
Boolean |
|
Unit |
@UiThreadSets the |
Unit |
@UiThreadSets the |
Unit |
@UiThreadApplies a |
Unit |
setScreenFlashOverlayColor(color: @ColorInt Int)Sets the color of the top overlay view during screen flash. |
Unit |
@UiThreadSets a |
Inherited Constants |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Public constructors
PreviewView
@UiThread
PreviewView(context: Context, attrs: AttributeSet?, defStyleAttr: Int)
PreviewView
@UiThread
PreviewView(
context: Context,
attrs: AttributeSet?,
defStyleAttr: Int,
defStyleRes: Int
)
Public functions
getBitmap
@UiThread
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 ARGB_8888 pixel format and its dimensions are the same as this view's.
Do not invoke this method from a drawing method (onDraw 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 STREAMING to make sure the preview is started.
| Returns | |
|---|---|
Bitmap? |
A |
getController
@UiThread
fun getController(): CameraController?
Get the CameraController.
getImplementationMode
@UiThread
fun getImplementationMode(): PreviewView.ImplementationMode
Returns the ImplementationMode.
If nothing is set via setImplementationMode, the default value is PERFORMANCE.
| Returns | |
|---|---|
PreviewView.ImplementationMode |
The |
getMeteringPointFactory
@UiThread
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 startFocusAndMetering to fail but it won't crash the application. Wait for the STREAMING state to make sure the preview is ready.
| Returns | |
|---|---|
MeteringPointFactory |
| See also | |
|---|---|
getPreviewStreamState |
getOutputTransform
fun getOutputTransform(): OutputTransform?
Gets the OutputTransform associated with the PreviewView.
Returns a OutputTransform object that represents the transform being applied to the associated Preview use case. Returns null if the transform info is not ready. For example, when the associated Preview has not been bound or the PreviewView's layout is not ready.
PreviewView needs to be in COMPATIBLE mode for the transform to work correctly. For example, the returned OutputTransform may not respect the value of getMatrix when PERFORMANCE mode is used.
| Returns | |
|---|---|
OutputTransform? |
the transform applied on the preview by this |
| See also | |
|---|---|
CoordinateTransform |
getPreviewStreamState
fun getPreviewStreamState(): LiveData<PreviewView.StreamState!>
Gets a LiveData for the preview StreamState.
There are two preview stream states, IDLE and STREAMING. IDLE indicates the preview is currently not visible and streaming is stopped. STREAMING means the preview is streaming or is about to start streaming. This state guarantees the preview is visible only when the ImplementationMode is COMPATIBLE. When in PERFORMANCE mode, it is possible the preview becomes visible slightly after the state changes to STREAMING.
Apps that require a precise signal for when the preview starts should set the implementation mode to COMPATIBLE.
| Returns | |
|---|---|
LiveData<PreviewView.StreamState!> |
A |
getScaleType
@UiThread
fun getScaleType(): PreviewView.ScaleType
Returns the ScaleType currently applied to the preview.
The default value is FILL_CENTER.
| Returns | |
|---|---|
PreviewView.ScaleType |
The |
getScreenFlash
@UiThread
fun getScreenFlash(): ImageCapture.ScreenFlash?
Returns an ImageCapture.ScreenFlash implementation based on the Window instance set via setScreenFlashWindow.
This API uses an internally managed ScreenFlashView to provide the ImageCapture.ScreenFlash implementation which can be passed to the setScreenFlash API. The following example shows the API usage.
mPreviewView.setScreenFlashWindow(activity.getWindow()); mImageCapture.setScreenFlash(mPreviewView.getScreenFlash()); mImageCapture.setFlashMode(ImageCapture.FLASH_MODE_SCREEN); mImageCapture.takePhoto(mCameraExecutor, mOnImageSavedCallback);
| Returns | |
|---|---|
ImageCapture.ScreenFlash? |
An |
| See also | |
|---|---|
getScreenFlash |
|
FLASH_MODE_SCREEN |
getSensorToViewTransform
@UiThread
fun getSensorToViewTransform(): Matrix?
Gets the transformation matrix from camera sensor to PreviewView.
The value is a mapping from sensor coordinates to PreviewView coordinates, which is, from the rect of SENSOR_INFO_ACTIVE_ARRAY_SIZE to the rect defined by (0, 0, PreviewView#getWidth(), PreviewView#getHeight()). The app can use the matrix to map the coordinates from one UseCase to another. For example, detecting face with ImageAnalysis, and then highlighting the face in PreviewView.
This method returns null if the transformation is not ready. It happens when PreviewView layout has not been measured, or the associated Preview use case is not yet bound to a camera. For the former case, the app can listen to the layout change via e.g. addOnLayoutChangeListener. For the latter case, the app wait until the Preview or CameraController is bound and the LifecycleOwner is in the STARTED state. The app should call this method to get the latest value before performing coordinates transformation.
The return value does not include the custom transform applied by the app via methods like setScaleX.
getSurfaceProvider
@UiThread
fun getSurfaceProvider(): Preview.SurfaceProvider
Gets a Preview.SurfaceProvider to be used with setSurfaceProvider. 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).
| Returns | |
|---|---|
Preview.SurfaceProvider |
A |
| See also | |
|---|---|
PreviewView.ImplementationMode |
getViewPort
@UiThread
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.
| Returns | |
|---|---|
ViewPort? |
null if the view is not currently attached or the view's width/height is zero. |
| See also | |
|---|---|
ViewPort |
|
UseCaseGroup |
getViewPort
@UiThread
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:
ORIENTATION_UNKNOWN: orientation == -1
ROTATION_0: orientation >= 315 || orientation <45
ROTATION_90: orientation >= 225 &&orientation <315
ROTATION_180: orientation >= 135 &&orientation <225
ROTATION_270: orientation >= 45 &&orientation <135
Once the target rotation is obtained, use it with setTargetRotation to update the rotation. Example:
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);
Note that for non-display rotation to work, the mode must be set to COMPATIBLE.
| Parameters | |
|---|---|
targetRotation: Int |
A rotation value, expressed as one of |
| Returns | |
|---|---|
ViewPort? |
null if the view's width/height is zero. |
| See also | |
|---|---|
PreviewView.ImplementationMode |
setController
@UiThread
fun setController(cameraController: CameraController?): Unit
Sets the CameraController.
Once set, the controller will use PreviewView to display camera preview feed. It also uses the PreviewView's layout dimension to set the crop rect for all the use cases so that the output from other use cases match what the end user sees in PreviewView. It also enables features like tap-to-focus and pinch-to-zoom.
Setting it to null or to a different CameraController stops the previous CameraController from working. The previous CameraController will remain detached until it's set on the PreviewView again.
| Throws | |
|---|---|
java.lang.IllegalArgumentException |
If the |
| See also | |
|---|---|
CameraController |
setImplementationMode
@UiThread
fun setImplementationMode(
implementationMode: PreviewView.ImplementationMode
): Unit
Sets the ImplementationMode for the PreviewView.
PreviewView displays the preview with a TextureView when the mode is COMPATIBLE, and tries to use a SurfaceView if it is 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 PERFORMANCE.
This method needs to be called before the Preview.SurfaceProvider is set on Preview. Once changed, Preview.SurfaceProvider needs to be set again. e.g. preview.setSurfaceProvider(previewView.getSurfaceProvider()).
setScaleType
@UiThread
fun setScaleType(scaleType: PreviewView.ScaleType): Unit
Applies a ScaleType to the preview.
If a CameraController is attached to PreviewView, the change will take immediate effect. It also takes immediate effect if getViewPort is not set in the bound UseCaseGroup. Otherwise, the UseCases need to be bound again with the latest value of getViewPort.
This value can also be set in the layout XML file via the app:scaleType attribute.
The default value is FILL_CENTER.
name app:scaleType
| Parameters | |
|---|---|
scaleType: PreviewView.ScaleType |
A |
setScreenFlashOverlayColor
fun setScreenFlashOverlayColor(color: @ColorInt Int): Unit
Sets the color of the top overlay view during screen flash.
| See also | |
|---|---|
getScreenFlash |
|
FLASH_MODE_SCREEN |
setScreenFlashWindow
@UiThread
fun setScreenFlashWindow(screenFlashWindow: Window?): Unit
Sets a Window instance for subsequent photo capture requests with FLASH_MODE_SCREEN set.
The calling of this API will take effect for FLASH_MODE_SCREEN only and the Window will be ignored for other flash modes. During screen flash photo capture, the window is used for the purpose of changing brightness.
If the implementation provided by the user is no longer valid (e.g. due to any android.app.Activity or android.view.View reference used in the implementation becoming invalid), user needs to re-set a new valid window or clear the previous one with setScreenFlashWindow(null), whichever appropriate.
For most app scenarios, a Window instance can be obtained from getWindow. In case of a fragment, getActivity can first be used to get the activity instance.