CameraEffect

@RequiresApi(value = 21)
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

const Int

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

const Int

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

const Int

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

Protected constructors

CameraEffect(
    targets: Int,
    executor: Executor,
    imageProcessor: ImageProcessor,
    errorListener: Consumer<Throwable!>
)
CameraEffect(
    targets: Int,
    executor: Executor,
    surfaceProcessor: SurfaceProcessor,
    errorListener: Consumer<Throwable!>
)

Public functions

Consumer<Throwable!>

Gets the Error listener associated with this effect.

Executor

Gets the Executor associated with this effect.

SurfaceProcessor?

Gets the SurfaceProcessor associated with this effect.

Int

Ges the target UseCases of this effect.

Constants

IMAGE_CAPTURE

Added in 1.3.0
const val IMAGE_CAPTURE = 4: Int

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

PREVIEW

Added in 1.3.0
const val PREVIEW = 1: Int

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

VIDEO_CAPTURE

Added in 1.3.0
const val VIDEO_CAPTURE = 2: Int

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

Protected constructors

CameraEffect

Added in 1.3.0
protected CameraEffect(
    targets: Int,
    executor: Executor,
    imageProcessor: ImageProcessor,
    errorListener: Consumer<Throwable!>
)
Parameters
targets: Int

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

executor: Executor

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

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.

errorListener: Consumer<Throwable!>

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

CameraEffect

Added in 1.3.0
protected CameraEffect(
    targets: Int,
    executor: Executor,
    surfaceProcessor: SurfaceProcessor,
    errorListener: Consumer<Throwable!>
)
Parameters
targets: Int

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

Targeting other UseCase combinations will throw IllegalArgumentException.
executor: Executor

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

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.

errorListener: Consumer<Throwable!>

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 functions

getErrorListener

Added in 1.3.0
fun getErrorListener(): Consumer<Throwable!>

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
fun getExecutor(): Executor

Gets the Executor associated with this effect.

This method returns the value set in the constructor.

getSurfaceProcessor

Added in 1.3.0
fun getSurfaceProcessor(): SurfaceProcessor?

Gets the SurfaceProcessor associated with this effect.

getTargets

Added in 1.3.0
fun getTargets(): Int

Ges the target UseCases of this effect.