# CameraEffect

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/CameraEffect.java+class:androidx.camera.core.CameraEffect) Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/camera#1.3.0)

*** ** * ** ***


```
public abstract class CameraEffect
```

<br />

Known direct subclasses [Media3Effect](https://developer.android.com/reference/androidx/camera/media3/effect/Media3Effect), [OverlayEffect](https://developer.android.com/reference/androidx/camera/effects/OverlayEffect)

|---|---|
| `https://developer.android.com/reference/androidx/camera/media3/effect/Media3Effect` | A CameraEffect that applies media3 `https://developer.android.com/reference/androidx/media3/common/Effect` to the CameraX pipeline |
| `https://developer.android.com/reference/androidx/camera/effects/OverlayEffect` | A `https://developer.android.com/reference/androidx/camera/core/CameraEffect` for drawing overlay on top of the camera frames. |

*** ** * ** ***

An effect for one or multiple camera outputs.

This API allows the implementer to inject code into CameraX pipeline and apply visual effects, such as a portrait effect. The `https://developer.android.com/reference/androidx/camera/core/CameraEffect` class contains two types of information, the processor and the configuration.

- The processor is an implementation of either `https://developer.android.com/reference/androidx/camera/core/SurfaceProcessor` or `https://developer.android.com/reference/androidx/camera/core/ImageProcessor`. It consumes original camera frames from CameraX, applies the effect, and returns the processed frames back to CameraX.
- The configuration provides information on how the processor should be injected into the pipeline. For example, the target `https://developer.android.com/reference/androidx/camera/core/UseCase`s where the effect should be applied. It may also contain information about camera configuration. For example, the exposure level.

If CameraX fails to send frames to the `https://developer.android.com/reference/androidx/camera/core/CameraEffect`, the error will be delivered to the app via error callbacks such as `https://developer.android.com/reference/androidx/camera/core/ImageCapture.OnImageCapturedCallback#onError(androidx.camera.core.ImageCaptureException)`. If `https://developer.android.com/reference/androidx/camera/core/CameraEffect` fails to process and return the frames, for example, unable to allocate the resources for image processing, it must throw `https://developer.android.com/reference/java/lang/Throwable.html` in the processor implementation. The `https://developer.android.com/reference/java/lang/Throwable.html` will be caught and forwarded to the app via error callbacks. Please see the Javadoc of the processor interfaces for details.

Extend this class to create specific effects. The `https://developer.android.com/reference/java/util/concurrent/Executor.html` provided in the constructors will be used by CameraX to call the processors.

Code sample for a portrait effect that targets the `https://developer.android.com/reference/androidx/camera/core/Preview``https://developer.android.com/reference/androidx/camera/core/UseCase`:

```
class PortraitPreviewEffect extends CameraEffect {
    PortraitPreviewEffect() {
        super(PREVIEW, getExecutor(), getSurfaceProcessor());
    }

    private static Executor getExecutor() {
        // Returns an executor for calling the SurfaceProcessor
    }

    private static SurfaceProcessor getSurfaceProcessor() {
        // Return a SurfaceProcessor implementation that applies a portrait effect.
    }
}
```

## Summary

| ### Constants |
|---|---|
| `static final int` | `https://developer.android.com/reference/androidx/camera/core/CameraEffect#IMAGE_CAPTURE() = 4` Bitmask option to indicate that CameraX should apply this effect to `https://developer.android.com/reference/androidx/camera/core/ImageCapture`. |
| `static final int` | `https://developer.android.com/reference/androidx/camera/core/CameraEffect#PREVIEW() = 1` Bitmask option to indicate that CameraX should apply this effect to `https://developer.android.com/reference/androidx/camera/core/Preview`. |
| `static final int` | `https://developer.android.com/reference/androidx/camera/core/CameraEffect#VIDEO_CAPTURE() = 2` Bitmask option to indicate that CameraX should apply this effect to `VideoCapture`. |

| ### Protected constructors |
|---|
| `https://developer.android.com/reference/androidx/camera/core/CameraEffect#CameraEffect(int,java.util.concurrent.Executor,androidx.camera.core.ImageProcessor,androidx.core.util.Consumer<java.lang.Throwable>)( int targets, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageProcessor imageProcessor, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/core/util/Consumer<https://developer.android.com/reference/java/lang/Throwable.html> errorListener )` |
| `https://developer.android.com/reference/androidx/camera/core/CameraEffect#CameraEffect(int,java.util.concurrent.Executor,androidx.camera.core.SurfaceProcessor,androidx.core.util.Consumer<java.lang.Throwable>)( int targets, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/SurfaceProcessor surfaceProcessor, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/core/util/Consumer<https://developer.android.com/reference/java/lang/Throwable.html> errorListener )` |

| ### Public methods |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/core/util/Consumer<https://developer.android.com/reference/java/lang/Throwable.html>` | `https://developer.android.com/reference/androidx/camera/core/CameraEffect#getErrorListener()()` Gets the Error listener associated with this effect. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html` | `https://developer.android.com/reference/androidx/camera/core/CameraEffect#getExecutor()()` Gets the `https://developer.android.com/reference/java/util/concurrent/Executor.html` associated with this effect. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/camera/core/SurfaceProcessor` | `https://developer.android.com/reference/androidx/camera/core/CameraEffect#getSurfaceProcessor()()` Gets the `https://developer.android.com/reference/androidx/camera/core/SurfaceProcessor` associated with this effect. |
| `int` | `https://developer.android.com/reference/androidx/camera/core/CameraEffect#getTargets()()` Ges the target `https://developer.android.com/reference/androidx/camera/core/UseCase`s of this effect. |

## Constants

### IMAGE_CAPTURE

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

```
public static final int IMAGE_CAPTURE = 4
```

Bitmask option to indicate that CameraX should apply this effect to `https://developer.android.com/reference/androidx/camera/core/ImageCapture`.

### PREVIEW

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

```
public static final int PREVIEW = 1
```

Bitmask option to indicate that CameraX should apply this effect to `https://developer.android.com/reference/androidx/camera/core/Preview`.

### VIDEO_CAPTURE

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

```
public static final int VIDEO_CAPTURE = 2
```

Bitmask option to indicate that CameraX should apply this effect to `VideoCapture`.

## Protected constructors

### CameraEffect

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

```
protected CameraEffect(
    int targets,
    @NonNull Executor executor,
    @NonNull ImageProcessor imageProcessor,
    @NonNull Consumer<Throwable> errorListener
)
```

| Parameters |
|---|---|
| `int targets` | the target `https://developer.android.com/reference/androidx/camera/core/UseCase` to which this effect should be applied. Currently, `https://developer.android.com/reference/androidx/camera/core/ImageProcessor` can only target `https://developer.android.com/reference/androidx/camera/core/CameraEffect#IMAGE_CAPTURE()`. Targeting other `https://developer.android.com/reference/androidx/camera/core/UseCase` will throw `https://developer.android.com/reference/java/lang/IllegalArgumentException.html`. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor` | the `https://developer.android.com/reference/java/util/concurrent/Executor.html` on which the {@param imageProcessor} and {@param errorListener} will be invoked. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageProcessor imageProcessor` | a `https://developer.android.com/reference/androidx/camera/core/ImageProcessor` implementation. Once the effect is active, CameraX will send frames to the `https://developer.android.com/reference/androidx/camera/core/ImageProcessor` on the {@param executor}, and deliver the processed frames to the app. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/core/util/Consumer<https://developer.android.com/reference/java/lang/Throwable.html> errorListener` | invoked if the effect runs into unrecoverable errors. This is invoked on the provided {@param executor}. |

### CameraEffect

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

```
protected CameraEffect(
    int targets,
    @NonNull Executor executor,
    @NonNull SurfaceProcessor surfaceProcessor,
    @NonNull Consumer<Throwable> errorListener
)
```

| Parameters |
|---|---|
| `int targets` | the target `https://developer.android.com/reference/androidx/camera/core/UseCase` to which this effect should be applied. Currently `https://developer.android.com/reference/androidx/camera/core/SurfaceProcessor` can target the following combinations: - `https://developer.android.com/reference/androidx/camera/core/CameraEffect#PREVIEW()` - `https://developer.android.com/reference/androidx/camera/core/CameraEffect#PREVIEW()` \| `https://developer.android.com/reference/androidx/camera/core/CameraEffect#VIDEO_CAPTURE()` - `https://developer.android.com/reference/androidx/camera/core/CameraEffect#PREVIEW()` \| `https://developer.android.com/reference/androidx/camera/core/CameraEffect#VIDEO_CAPTURE()` \| `https://developer.android.com/reference/androidx/camera/core/CameraEffect#IMAGE_CAPTURE()` Targeting other `https://developer.android.com/reference/androidx/camera/core/UseCase` combinations will throw `https://developer.android.com/reference/java/lang/IllegalArgumentException.html`. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor` | the `https://developer.android.com/reference/java/util/concurrent/Executor.html` on which the {@param imageProcessor} and {@param errorListener} will be invoked. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/SurfaceProcessor surfaceProcessor` | a `https://developer.android.com/reference/androidx/camera/core/SurfaceProcessor` implementation. Once the effect is active, CameraX will send frames to the `https://developer.android.com/reference/androidx/camera/core/SurfaceProcessor` on the {@param executor}, and deliver the processed frames to the app. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/core/util/Consumer<https://developer.android.com/reference/java/lang/Throwable.html> errorListener` | invoked if the effect runs into unrecoverable errors. The `https://developer.android.com/reference/java/lang/Throwable.html` will be the error thrown by this `https://developer.android.com/reference/androidx/camera/core/CameraEffect`. For example, `https://developer.android.com/reference/androidx/camera/core/ProcessingException`. This is invoked on the provided {@param executor}. |

## Public methods

### getErrorListener

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

```
public @NonNull Consumer<Throwable> getErrorListener()
```

Gets the Error listener associated with this effect.

This method returns the value set in the constructor. The `https://developer.android.com/reference/java/lang/Throwable.html` will be the error thrown by this `https://developer.android.com/reference/androidx/camera/core/CameraEffect`. For example, `https://developer.android.com/reference/androidx/camera/core/ProcessingException`.

### getExecutor

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

```
public @NonNull Executor getExecutor()
```

Gets the `https://developer.android.com/reference/java/util/concurrent/Executor.html` associated with this effect.

This method returns the value set in the constructor.

### getSurfaceProcessor

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

```
public @Nullable SurfaceProcessor getSurfaceProcessor()
```

Gets the `https://developer.android.com/reference/androidx/camera/core/SurfaceProcessor` associated with this effect.

### getTargets

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

```
public int getTargets()
```

Ges the target `https://developer.android.com/reference/androidx/camera/core/UseCase`s of this effect.