CameraEffect

@RequiresApi(value = 21)
public abstract class CameraEffect

Known direct subclasses
OverlayEffect

A 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 CameraEffect class contains two types of information, the processor and the configuration.

  • The processor is an implementation of either SurfaceProcessor or 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 UseCases 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 CameraEffect, the error will be delivered to the app via error callbacks such as onError. If CameraEffect fails to process and return the frames, for example, unable to allocate the resources for image processing, it must throw Throwable in the processor implementation. The Throwable 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 Executor provided in the constructors will be used by CameraX to call the processors.

Code sample for a portrait effect that targets the PreviewUseCase:

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

Bitmask option to indicate that CameraX should apply this effect to ImageCapture.

static final int

Bitmask option to indicate that CameraX should apply this effect to Preview.

static final int

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

Protected constructors

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

Public methods

@NonNull Consumer<Throwable>

Gets the Error listener associated with this effect.

@NonNull Executor

Gets the Executor associated with this effect.

@Nullable SurfaceProcessor

Gets the SurfaceProcessor associated with this effect.

int

Ges the target UseCases of this effect.

Constants

IMAGE_CAPTURE

Added in 1.3.0
public static final int IMAGE_CAPTURE = 4

Bitmask option to indicate that CameraX should apply this effect to ImageCapture.

PREVIEW

Added in 1.3.0
public static final int PREVIEW = 1

Bitmask option to indicate that CameraX should apply this effect to Preview.

VIDEO_CAPTURE

Added in 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
protected CameraEffect(
    int targets,
    @NonNull Executor executor,
    @NonNull ImageProcessor imageProcessor,
    @NonNull Consumer<Throwable> errorListener
)
Parameters
int targets

the target UseCase to which this effect should be applied. Currently, ImageProcessor can only target IMAGE_CAPTURE. Targeting other UseCase will throw IllegalArgumentException.

@NonNull Executor executor

the Executor on which the {@param imageProcessor} and {@param errorListener} will be invoked.

@NonNull ImageProcessor imageProcessor

a ImageProcessor implementation. Once the effect is active, CameraX will send frames to the ImageProcessor on the {@param executor}, and deliver the processed frames to the app.

@NonNull Consumer<Throwable> errorListener

invoked if the effect runs into unrecoverable errors. This is invoked on the provided {@param executor}.

CameraEffect

Added in 1.3.0
protected CameraEffect(
    int targets,
    @NonNull Executor executor,
    @NonNull SurfaceProcessor surfaceProcessor,
    @NonNull Consumer<Throwable> errorListener
)
Parameters
int targets

the target UseCase to which this effect should be applied. Currently SurfaceProcessor can target the following combinations:

Targeting other UseCase combinations will throw IllegalArgumentException.
@NonNull Executor executor

the Executor on which the {@param imageProcessor} and {@param errorListener} will be invoked.

@NonNull SurfaceProcessor surfaceProcessor

a SurfaceProcessor implementation. Once the effect is active, CameraX will send frames to the SurfaceProcessor on the {@param executor}, and deliver the processed frames to the app.

@NonNull Consumer<Throwable> errorListener

invoked if the effect runs into unrecoverable errors. The Throwable will be the error thrown by this CameraEffect. For example, ProcessingException. This is invoked on the provided {@param executor}.

Public methods

getErrorListener

Added in 1.3.0
public @NonNull Consumer<ThrowablegetErrorListener()

Gets the Error listener associated with this effect.

This method returns the value set in the constructor. The Throwable will be the error thrown by this CameraEffect. For example, ProcessingException.

getExecutor

Added in 1.3.0
public @NonNull Executor getExecutor()

Gets the Executor associated with this effect.

This method returns the value set in the constructor.

getSurfaceProcessor

Added in 1.3.0
public @Nullable SurfaceProcessor getSurfaceProcessor()

Gets the SurfaceProcessor associated with this effect.

getTargets

Added in 1.3.0
public int getTargets()

Ges the target UseCases of this effect.