# Preview

Artifact: [androidx.camera:camera-core](https://developer.android.com/jetpack/androidx/releases/camera) [View Source](https://cs.android.com/search?q=file:androidx/camera/core/Preview.java+class:androidx.camera.core.Preview) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

*** ** * ** ***


```
class Preview : UseCase
```

<br />

|---|---|---|
| [kotlin.Any](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html) |||
| ↳ | [androidx.camera.core.UseCase](https://developer.android.com/reference/kotlin/androidx/camera/core/UseCase) ||
|   | ↳ | [androidx.camera.core.Preview](https://developer.android.com/reference/kotlin/androidx/camera/core/Preview) |

*** ** * ** ***

A use case that provides a camera preview stream for displaying on-screen.

The preview stream is connected to the `https://developer.android.com/reference/android/view/Surface.html` provided via `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.SurfaceProvider`. The application decides how the `https://developer.android.com/reference/android/view/Surface.html` is shown, and is responsible for managing the `https://developer.android.com/reference/android/view/Surface.html` lifecycle after providing it.

To display the preview with the correct orientation, app needs to take different actions based on the source of the Surface. If the `https://developer.android.com/reference/android/view/Surface.html` is backed by a `https://developer.android.com/reference/android/view/SurfaceView.html`, it will always be in the device's display orientation. If the `https://developer.android.com/reference/android/view/Surface.html` is backed by `https://developer.android.com/reference/android/media/ImageReader.html`, `https://developer.android.com/reference/android/media/MediaCodec.html` or other objects, it's the application's responsibility to calculate the rotation. If the `https://developer.android.com/reference/android/view/Surface.html` is backed by a `https://developer.android.com/reference/android/graphics/SurfaceTexture.html`, `https://developer.android.com/reference/android/graphics/SurfaceTexture.html#getTransformMatrix(float[])` can be used to transform the preview to natural orientation. The value is available after a frame is pushed to the `https://developer.android.com/reference/android/graphics/SurfaceTexture.html` and its `https://developer.android.com/reference/android/graphics/SurfaceTexture.OnFrameAvailableListener.html#onFrameAvailable(android.graphics.SurfaceTexture)` has been called. `https://developer.android.com/reference/android/view/TextureView.html` handles this automatically and always puts the preview in the natural orientation. To further transform the `https://developer.android.com/reference/android/view/TextureView.html` to display orientation, the app needs to apply the current display rotation. Example:

```kotlin
        switch (getWindowManager().getDefaultDisplay().getRotation()) {
            case Surface.ROTATION_0:
                displayRotation = 0;
                break;
            case Surface.ROTATION_90:
                displayRotation = 90;
                break;
            case Surface.ROTATION_180:
                displayRotation = 180;
                break;
            case Surface.ROTATION_270:
                displayRotation = 270;
                break;
            default:
                throw new UnsupportedOperationException(
                        "Unsupported display rotation: " + displayRotation);
        }
        matrix.postRotate(-displayRotation, centerX, centerY);
        textureView.setTransform(matrix);
    
```

## Summary

| ### Nested types |
|---|
| `class https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.Builder : https://developer.android.com/reference/kotlin/androidx/camera/core/ExtendableBuilder, https://developer.android.com/reference/kotlin/androidx/camera/core/UseCase.InteropConfigurable<https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.Builder!>` Builder for a `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview`. |
| `interface https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.SurfaceProvider` A interface implemented by the application to provide a `https://developer.android.com/reference/android/view/Surface.html` for `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview`. |

| ### Constants |
|---|---|
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#STREAM_STATE_IDLE() = 0` The preview is not yet producing frames, is being recreated, or has been stopped. |
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#STREAM_STATE_STREAMING() = 1` The camera is actively producing frames for the provided `https://developer.android.com/reference/android/view/Surface.html`. |

| ### Public functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/core/DynamicRange` | `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#getDynamicRange()()` Returns the dynamic range. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#getMirrorMode()()` Returns the mirror mode. |
| `java-static https://developer.android.com/reference/kotlin/androidx/camera/core/PreviewCapabilities` | `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#getPreviewCapabilities(androidx.camera.core.CameraInfo)(cameraInfo: https://developer.android.com/reference/kotlin/androidx/camera/core/CameraInfo)` Returns `https://developer.android.com/reference/kotlin/androidx/camera/core/PreviewCapabilities` to query preview stream related device capability. |
| `https://developer.android.com/reference/kotlin/androidx/camera/core/ResolutionInfo?` | `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#getResolutionInfo()()` Gets selected resolution information of the `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview`. |
| `https://developer.android.com/reference/kotlin/androidx/camera/core/resolutionselector/ResolutionSelector?` | `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#getResolutionSelector()()` Returns the resolution selector setting. |
| `https://developer.android.com/reference/android/util/Range.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html!>` | `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#getTargetFrameRate()()` Returns the target frame rate range, in frames per second, for the associated Preview use case. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#getTargetRotation()()` Returns the rotation that the intended target resolution is expressed in. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#isPreviewStabilizationEnabled()()` Returns whether video stabilization is enabled for preview stream. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#setMirrorMode(int)(mirrorMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Sets the mirror mode. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/UiThread https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#setSurfaceProvider(androidx.camera.core.Preview.SurfaceProvider)(surfaceProvider: https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.SurfaceProvider?)` Sets a `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.SurfaceProvider` to provide a `https://developer.android.com/reference/android/view/Surface.html` for Preview. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/UiThread https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#setSurfaceProvider(java.util.concurrent.Executor,androidx.camera.core.Preview.SurfaceProvider)( executor: https://developer.android.com/reference/java/util/concurrent/Executor.html, surfaceProvider: https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.SurfaceProvider? )` Sets a `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.SurfaceProvider` to provide a `https://developer.android.com/reference/android/view/Surface.html` for Preview. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#setTargetRotation(int)(targetRotation: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Sets the target rotation. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#toString()()` |

### Inherited functions

From [androidx.camera.core.UseCase](https://developer.android.com/reference/kotlin/androidx/camera/core/UseCase) `java-static https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` `https://developer.android.com/reference/kotlin/androidx/camera/core/UseCase#snapToSurfaceRotation(int)(orientation: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = 0, to = 359) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)`

A utility function that can convert the orientation degrees of `https://developer.android.com/reference/android/view/OrientationEventListener.html` to the nearest `https://developer.android.com/reference/android/view/Surface.html` rotation.

## Constants

### STREAM_STATE_IDLE

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
const val STREAM_STATE_IDLE = 0: Int
```

The preview is not yet producing frames, is being recreated, or has been stopped.

### STREAM_STATE_STREAMING

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
const val STREAM_STATE_STREAMING = 1: Int
```

The camera is actively producing frames for the provided `https://developer.android.com/reference/android/view/Surface.html`.

## Public functions

### getDynamicRange

Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/camera#1.4.0)

```
fun getDynamicRange(): DynamicRange
```

Returns the dynamic range.

The dynamic range is set by `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.Builder#setDynamicRange(androidx.camera.core.DynamicRange)`. If the dynamic range set is not a fully defined dynamic range, such as `https://developer.android.com/reference/kotlin/androidx/camera/core/DynamicRange#HDR_UNSPECIFIED_10_BIT()`, then it will be returned just as provided, and will not be returned as a fully defined dynamic range. The fully defined dynamic range, which is determined by resolving the combination of requested dynamic ranges from other use cases according to the device capabilities, will be communicated to the `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.SurfaceProvider` via `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceRequest#getDynamicRange()`}.

If the dynamic range was not provided to `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.Builder#setDynamicRange(androidx.camera.core.DynamicRange)`, this will return the default of `https://developer.android.com/reference/kotlin/androidx/camera/core/DynamicRange#UNSPECIFIED()`

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/core/DynamicRange` | the dynamic range set for this `Preview` use case. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.Builder#setDynamicRange(androidx.camera.core.DynamicRange)` |   |

### getMirrorMode

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
fun getMirrorMode(): Int
```

Returns the mirror mode.

If not set, it defaults to `https://developer.android.com/reference/kotlin/androidx/camera/core/MirrorMode#MIRROR_MODE_ON_FRONT_ONLY()`.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The mirror mode. |

### getPreviewCapabilities

Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/camera#1.4.0)

```
java-static fun getPreviewCapabilities(cameraInfo: CameraInfo): PreviewCapabilities
```

Returns `https://developer.android.com/reference/kotlin/androidx/camera/core/PreviewCapabilities` to query preview stream related device capability.

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/core/PreviewCapabilities` | `https://developer.android.com/reference/kotlin/androidx/camera/core/PreviewCapabilities` |

### getResolutionInfo

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/camera#1.1.0)

```
fun getResolutionInfo(): ResolutionInfo?
```

Gets selected resolution information of the `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview`.

The returned `https://developer.android.com/reference/kotlin/androidx/camera/core/ResolutionInfo` will be expressed in the coordinates of the camera sensor. It will be the same as the resolution inside a `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceRequest` to request a surface for `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview`.

The resolution information might change if the use case is unbound and then rebound or `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#setTargetRotation(int)` is called to change the target rotation setting. The application needs to call `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#getResolutionInfo()` again to get the latest `https://developer.android.com/reference/kotlin/androidx/camera/core/ResolutionInfo` for the changes.

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/core/ResolutionInfo?` | the resolution information if the use case has been bound by the `https://developer.android.com/reference/kotlin/androidx/camera/lifecycle/ProcessCameraProvider#bindToLifecycle(androidx.lifecycle.LifecycleOwner,androidx.camera.core.CameraSelector,androidx.camera.core.UseCase...)` API, or null if the use case is not bound yet. |

### getResolutionSelector

Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/camera#1.3.0)

```
fun getResolutionSelector(): ResolutionSelector?
```

Returns the resolution selector setting.

This setting is set when constructing a Preview using `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.Builder#setResolutionSelector(androidx.camera.core.resolutionselector.ResolutionSelector)`.

### getTargetFrameRate

Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/camera#1.3.0)

```
fun getTargetFrameRate(): Range<Int!>
```

Returns the target frame rate range, in frames per second, for the associated Preview use case.

The target frame rate can be set prior to constructing a Preview using `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.Builder#setTargetFrameRate(android.util.Range<java.lang.Integer>)`. If not set, the target frame rate defaults to the value of .

This is just the frame rate range requested by the user, and may not necessarily be equal to the range the camera is actually operating at.

| Returns |
|---|---|
| `https://developer.android.com/reference/android/util/Range.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html!>` | the target frame rate range of this Preview. |

### getTargetRotation

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
fun getTargetRotation(): Int
```

Returns the rotation that the intended target resolution is expressed in.

The rotation is set when constructing an `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview` instance using `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.Builder#setTargetRotation(int)`. If not set, the target rotation defaults to the value of `https://developer.android.com/reference/android/view/Display.html#getRotation()` of the default display at the time the use case is created. The use case is fully created once it has been attached to a camera.

Value is one of the following:

- `Surface.ROTATION_0`
- `Surface.ROTATION_90`
- `Surface.ROTATION_180`
- `Surface.ROTATION_270`

<br />

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The rotation of the intended target. |

### isPreviewStabilizationEnabled

Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/camera#1.4.0)

```
fun isPreviewStabilizationEnabled(): Boolean
```

Returns whether video stabilization is enabled for preview stream.

### setMirrorMode

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
fun setMirrorMode(mirrorMode: Int): Unit
```

Sets the mirror mode.

Valid values include: `https://developer.android.com/reference/kotlin/androidx/camera/core/MirrorMode#MIRROR_MODE_OFF()`, `https://developer.android.com/reference/kotlin/androidx/camera/core/MirrorMode#MIRROR_MODE_ON()` and `https://developer.android.com/reference/kotlin/androidx/camera/core/MirrorMode#MIRROR_MODE_ON_FRONT_ONLY()`. If not set, it defaults to `https://developer.android.com/reference/kotlin/androidx/camera/core/MirrorMode#MIRROR_MODE_ON_FRONT_ONLY()`.

For API 32 and below, it will be no-op.

| Parameters |
|---|---|
| `mirrorMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The mirror mode. |

### setSurfaceProvider

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
@UiThread
fun setSurfaceProvider(surfaceProvider: Preview.SurfaceProvider?): Unit
```

Sets a `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.SurfaceProvider` to provide a `https://developer.android.com/reference/android/view/Surface.html` for Preview.

Setting the provider will signal to the camera that the use case is ready to receive data. The provider will be triggered on main thread. If the provider is removed by calling this again with a `null` SurfaceProvider then the camera will stop producing data for this Preview instance.

| Parameters |
|---|---|
| `surfaceProvider: https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.SurfaceProvider?` | SurfaceProvider that provides a `https://developer.android.com/reference/android/view/Surface.html` for Preview. This will replace the previous SurfaceProvider set either this method or `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#setSurfaceProvider(java.util.concurrent.Executor,androidx.camera.core.Preview.SurfaceProvider)`. |

### setSurfaceProvider

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
@UiThread
fun setSurfaceProvider(
    executor: Executor,
    surfaceProvider: Preview.SurfaceProvider?
): Unit
```

Sets a `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.SurfaceProvider` to provide a `https://developer.android.com/reference/android/view/Surface.html` for Preview.

Setting the provider will signal to the camera that the use case is ready to receive data. If the provider is removed by calling this again with a `null` SurfaceProvider then the camera will stop producing data for this Preview instance.

| Parameters |
|---|---|
| `executor: https://developer.android.com/reference/java/util/concurrent/Executor.html` | on which the surfaceProvider will be invoked. |
| `surfaceProvider: https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.SurfaceProvider?` | SurfaceProvider that provides a `https://developer.android.com/reference/android/view/Surface.html` for Preview. This will replace the previous SurfaceProvider set either this method or `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#setSurfaceProvider(androidx.camera.core.Preview.SurfaceProvider)`. |

### setTargetRotation

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
fun setTargetRotation(targetRotation: Int): Unit
```

Sets the target rotation.

This adjust the `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#getTargetRotation()`, which once applied will update the output to match target rotation specified here.

While rotation can also be set via `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.Builder#setTargetRotation(int)` , using `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview#setTargetRotation(int)` allows the target rotation to be set without rebinding new use cases. When this function is called, value set by `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.Builder#setTargetResolution(android.util.Size)` will be updated automatically to make sure the suitable resolution can be selected when the use case is bound.

If not set here or by configuration, the target rotation will default to the value of `https://developer.android.com/reference/android/view/Display.html#getRotation()` of the default display at the time the use case is created. The use case is fully created once it has been attached to a camera.

| Parameters |
|---|---|
| `targetRotation: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | Target rotation of the output image, expressed as one of `https://developer.android.com/reference/android/view/Surface.html#ROTATION_0`, `https://developer.android.com/reference/android/view/Surface.html#ROTATION_90`, `https://developer.android.com/reference/android/view/Surface.html#ROTATION_180`, or `https://developer.android.com/reference/android/view/Surface.html#ROTATION_270`. Value is one of the following: - `Surface.ROTATION_0` - `Surface.ROTATION_90` - `Surface.ROTATION_180` - `Surface.ROTATION_270` <br /> |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview.Builder#setTargetRotation(int)` |   |

### toString

```
fun toString(): String
```