Preview
public
class
Preview
extends UseCase
| java.lang.Object | ||
| ↳ | androidx.camera.core.UseCase | |
| ↳ | androidx.camera.core.Preview | |
A use case that provides a camera preview stream for displaying on-screen.
The preview stream is connected to an underlying SurfaceTexture. This SurfaceTexture
is created by the Preview use case and provided as an output after it is configured and attached
to the camera. The application receives the SurfaceTexture by setting an output listener with
setOnPreviewOutputUpdateListener(OnPreviewOutputUpdateListener). When the
lifecycle becomes active, the camera will start and images will be streamed to the
SurfaceTexture.
Preview.OnPreviewOutputUpdateListener.onUpdated(PreviewOutput) is called when a
new SurfaceTexture is created. A SurfaceTexture is created each time the use case becomes
active and no previous SurfaceTexture exists.
The application can then decide how this texture is shown. The texture data is as received
by the camera system with no rotation applied. To display the SurfaceTexture with the correct
orientation, the rotation parameter sent to Preview.OnPreviewOutputUpdateListener can
be used to create a correct transformation matrix for display. See
setTargetRotation(int) and PreviewConfig.Builder.setTargetRotation(int) for
details. See setOnPreviewOutputUpdateListener(OnPreviewOutputUpdateListener) for
notes if attaching the SurfaceTexture to TextureView.
The application is responsible for managing SurfaceTexture after receiving it. See
setOnPreviewOutputUpdateListener(OnPreviewOutputUpdateListener) for notes on
if overriding TextureView.SurfaceTextureListener.onSurfaceTextureDestroyed(SurfaceTexture).
Summary
Nested classes | |
|---|---|
interface |
Preview.OnPreviewOutputUpdateListener
A listener of |
class |
Preview.PreviewOutput
A bundle containing a |
interface |
Preview.PreviewSurfaceCallback
A callback to access the Preview Surface. |
enum |
Preview.UseCaseError
Describes the error that occurred during preview operation. |
Public constructors | |
|---|---|
Preview(PreviewConfig config)
Creates a new preview use case from the given configuration. |
|
Inherited methods | |
|---|---|
Public constructors
Preview
public Preview (PreviewConfig config)
Creates a new preview use case from the given configuration.
| Parameters | |
|---|---|
config |
PreviewConfig: for this use case instance
|
Public methods
enableTorch
public void enableTorch (boolean torch)
Sets torch on/off.
When the torch is on, the torch will remain on during photo capture regardless of flash
setting. When the torch is off, flash will function as set by ImageCapture.
| Parameters | |
|---|---|
torch |
boolean: True if turn on torch, otherwise false
|
getOnPreviewOutputUpdateListener
public Preview.OnPreviewOutputUpdateListener getOnPreviewOutputUpdateListener ()
Gets Preview.OnPreviewOutputUpdateListener
| Returns | |
|---|---|
Preview.OnPreviewOutputUpdateListener |
the last set listener or null if no listener is set |
| Throws | |
|---|---|
IllegalStateException |
If not called on main thread. |
getPreviewSurfaceCallback
public Preview.PreviewSurfaceCallback getPreviewSurfaceCallback ()
Gets Preview.PreviewSurfaceCallback
| Returns | |
|---|---|
Preview.PreviewSurfaceCallback |
the last set callback or null if no listener is set
|
isTorchOn
public boolean isTorchOn ()
True if the torch is on
| Returns | |
|---|---|
boolean |
|
removePreviewOutputListener
public void removePreviewOutputListener ()
Un-register a listener previously registered via
setOnPreviewOutputUpdateListener(OnPreviewOutputUpdateListener).
It will signal to the camera that the camera should no longer stream data to the last
Preview.PreviewOutput.
| Throws | |
|---|---|
IllegalStateException |
If not called on main thread. |
removePreviewSurfaceCallback
public void removePreviewSurfaceCallback ()
Removes the Preview.PreviewSurfaceCallback.
Removing the callback will signal to the camera that the camera should no longer stream data.
setOnPreviewOutputUpdateListener
public void setOnPreviewOutputUpdateListener (Executor executor,
Preview.OnPreviewOutputUpdateListener newListener)
Sets a listener and its executor to get the Preview.PreviewOutput updates.
See setOnPreviewOutputUpdateListener(OnPreviewOutputUpdateListener) for
more information.
| Parameters | |
|---|---|
executor |
Executor: The executor on which the listener should be invoked. |
newListener |
Preview.OnPreviewOutputUpdateListener: The listener which will receive Preview.PreviewOutput updates. |
| Throws | |
|---|---|
IllegalStateException |
If not called on main thread. |
setOnPreviewOutputUpdateListener
public void setOnPreviewOutputUpdateListener (Preview.OnPreviewOutputUpdateListener newListener)
Sets a listener to get the Preview.PreviewOutput updates.
Setting this listener will signal to the camera that the use case is ready to receive data.
Once Preview.OnPreviewOutputUpdateListener.onUpdated(PreviewOutput) is called,
ownership of the Preview.PreviewOutput and its contents is transferred to the application. It
is the application's responsibility to release the last SurfaceTexture returned by
Preview.PreviewOutput.getSurfaceTexture() when a new SurfaceTexture is provided via an update
or when the user is finished with the use case. A SurfaceTexture is created each time the
use case becomes active and no previous SurfaceTexture exists.
Preview.OnPreviewOutputUpdateListener.onUpdated(PreviewOutput) is called when a new
SurfaceTexture is created.
Calling TextureView.setSurfaceTexture(SurfaceTexture) when the
TextureView's SurfaceTexture is already created, should be preceded by calling
ViewGroup.removeView(View) and
ViewGroup.addView(View) on the parent view of the TextureView to ensure
the setSurfaceTexture() call succeeds.
Since Preview.OnPreviewOutputUpdateListener.onUpdated(PreviewOutput) is called when the
underlying SurfaceTexture is created, applications that override and return false from TextureView.SurfaceTextureListener.onSurfaceTextureDestroyed(SurfaceTexture)
should be sure to call TextureView.setSurfaceTexture(SurfaceTexture)
with the output from the previous Preview.PreviewOutput to attach it to a new TextureView,
such as on resuming the application.
The listener will run on the UI thread. See
setOnPreviewOutputUpdateListener(Executor, OnPreviewOutputUpdateListener)
to set the updates run on the given executor.
| Parameters | |
|---|---|
newListener |
Preview.OnPreviewOutputUpdateListener: The listener which will receive Preview.PreviewOutput updates.
|
setPreviewSurfaceCallback
public void setPreviewSurfaceCallback (Preview.PreviewSurfaceCallback previewSurfaceCallback)
Sets a Preview.PreviewSurfaceCallback to provide Surface for Preview.
Setting the callback will signal to the camera that the use case is ready to receive data.
| Parameters | |
|---|---|
previewSurfaceCallback |
Preview.PreviewSurfaceCallback: PreviewSurfaceCallback that provides a Preview.
|
setTargetRotation
public void setTargetRotation (int rotation)
Sets the target rotation.
This informs the use case so it can adjust the rotation value sent to
Preview.OnPreviewOutputUpdateListener.
In most cases this should be set to the current rotation returned by Display.getRotation(). In that case, the rotation values output by the use case will be
the rotation, which if applied to the output image, will make the image match the display
orientation.
If no target rotation is set by the application, it is set to the value of
Display.getRotation() of the default display at the time the
use case is created.
| Parameters | |
|---|---|
rotation |
int: Rotation of the surface texture consumer expressed as one of
Surface.ROTATION_0, Surface.ROTATION_90,
Surface.ROTATION_180, or Surface.ROTATION_270.
|
toString
public String toString ()
| Returns | |
|---|---|
String |
|
zoom
public void zoom (Rect crop)
Adjusts the preview to zoom to a local region.
Setting the zoom is equivalent to setting a scalar crop region (digital zoom), and zoom occurs about the center of the image.
Dimensions of the sensor coordinate frame can be found using Camera2.
| Parameters | |
|---|---|
crop |
Rect: rectangle with dimensions in sensor coordinate frame for zooming
|
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.