Google is committed to advancing racial equity for Black communities. See how.

BlendMode

enum class BlendMode
kotlin.Any
   ↳ kotlin.Enum<androidx.compose.ui.graphics.BlendMode>
   ↳ androidx.compose.ui.graphics.BlendMode

Algorithms to use when painting on the canvas.

When drawing a shape or image onto a canvas, different algorithms can be used to blend the pixels. The different values of BlendMode specify different such algorithms.

Each algorithm has two inputs, the source, which is the image being drawn, and the destination, which is the image into which the source image is being composited. The destination is often thought of as the background. The source and destination both have four color channels, the red, green, blue, and alpha channels. These are typically represented as numbers in the range 0.0 to 1.0. The output of the algorithm also has these same four channels, with values computed from the source and destination.

The horizontal and vertical bars in these images show the red, green, and blue channels with varying opacity levels, then all three color channels together with those same varying opacity levels, then all three color channels set to zero with those varying opacity levels, then two bars showing a red/green/blue repeating gradient, the first with full opacity and the second with partial opacity, and finally a bar with the three color channels set to zero but the opacity varying in a repeating gradient.

Application to the Canvas API

When using Canvas.saveLayer and Canvas.restore, the blend mode of the Paint given to the Canvas.saveLayer will be applied when Canvas.restore is called. Each call to Canvas.saveLayer introduces a new layer onto which shapes and images are painted; when Canvas.restore is called, that layer is then composited onto the parent layer, with the source being the most-recently-drawn shapes and images, and the destination being the parent layer. (For the first Canvas.saveLayer call, the parent layer is the canvas itself.)

See also:

Summary

Enum values

Drop both the source and destination images, leaving nothing.

Take the hue and saturation of the source image, and the luminosity of the destination image.

Divide the inverse of the destination by the the source, and inverse the result.

Divide the destination by the inverse of the source.

Composite the source and destination image by choosing the lowest value from each color channel.

Subtract the smaller value from the bigger value for each channel.

Drop the source image, only paint the destination image.

Composite the destination image over the source image, but only where it overlaps the source.

Show the destination image, but only where the two images overlap.

Show the destination image, but only where the two images do not overlap.

Composite the source image under the destination image.

Subtract double the product of the two images from the sum of the two images.

Multiply the components of the source and destination images after adjusting them to favor the source.

Take the hue of the source image, and the saturation and luminosity of the destination image.

Composite the source and destination image by choosing the highest value from each color channel.

Take the luminosity of the source image, and the hue and saturation of the destination image.

Multiply the color components of the source and destination images.

Multiply the components of the source and destination images, including the alpha channel.

Multiply the components of the source and destination images after adjusting them to favor the destination.

Sum the components of the source and destination images.

Take the saturation of the source image, and the hue and luminosity of the destination image.

Multiply the inverse of the components of the source and destination images, and inverse the result.

Use ColorDodge for source values below 0.

Drop the destination image, only paint the source image.

Composite the source image over the destination image, but only where it overlaps the destination.

Show the source image, but only where the two images overlap.

Show the source image, but only where the two images do not overlap.

Composite the source image over the destination image.

Apply a bitwise xor operator to the source and destination images.

Extension functions
From androidx.compose.ui.graphics
actual Boolean

Helper method to determine if the appropriate BlendMode is supported on the given Android API level this provides an opportunity for consumers to fallback on an alternative user experience for devices that do not support the corresponding blend mode.

Inherited extension functions
From androidx.core.util
infix Range<T>
T.rangeTo(that: T)

Creates a range from this Comparable value to that.

Enum values

Clear

enum val Clear : BlendMode

Drop both the source and destination images, leaving nothing.

Color

enum val Color : BlendMode

Take the hue and saturation of the source image, and the luminosity of the destination image.

The effect is to tint the destination image with the source image.

The opacity of the output image is computed in the same way as for SrcOver. Regions that are entirely transparent in the source image take their hue and saturation from the destination.

NOTE This BlendMode can only be used on Android API level 29 and above

See also:

  • Hue, which is a similar but weaker effect.
  • Softlight, which is a similar tinting effect but also tints white.
  • Saturation, which only applies the saturation of the source image.

ColorBurn

enum val ColorBurn : BlendMode

Divide the inverse of the destination by the the source, and inverse the result.

Inverting the components means that a fully saturated channel (opaque white) is treated as the value 0.0, and values normally treated as 0.0 (black, transparent) are treated as 1.0.

NOTE This BlendMode can only be used on Android API level 29 and above

ColorDodge

enum val ColorDodge : BlendMode

Divide the destination by the inverse of the source.

Inverting the components means that a fully saturated channel (opaque white) is treated as the value 0.0, and values normally treated as 0.0 (black, transparent) are treated as 1.0.

NOTE This BlendMode can only be used on Android API level 29 and above

Darken

enum val Darken : BlendMode

Composite the source and destination image by choosing the lowest value from each color channel.

The opacity of the output image is computed in the same way as for SrcOver.

Difference

enum val Difference : BlendMode

Subtract the smaller value from the bigger value for each channel.

Compositing black has no effect; compositing white inverts the colors of the other image.

The opacity of the output image is computed in the same way as for SrcOver.

NOTE This BlendMode can only be used on Android API level 29 and above

The effect is similar to Exclusion but harsher.

Dst

enum val Dst : BlendMode

Drop the source image, only paint the destination image.

Conceptually, the source image is discarded, leaving the destination untouched.

DstAtop

enum val DstAtop : BlendMode

Composite the destination image over the source image, but only where it overlaps the source.

This is essentially the DstOver operator, but with the output's opacity channel being set to that of the source image instead of being a combination of both image's opacity channels.

For a variant with the source on top instead of the destination, see SrcAtop.

DstIn

enum val DstIn : BlendMode

Show the destination image, but only where the two images overlap. The source image is not rendered, it is treated merely as a mask. The color channels of the source are ignored, only the opacity has an effect.

To show the source image instead, consider SrcIn.

To reverse the semantic of the mask (only showing the source where the destination is present, rather than where it is absent), consider DstOut.

DstOut

enum val DstOut : BlendMode

Show the destination image, but only where the two images do not overlap. The source image is not rendered, it is treated merely as a mask. The color channels of the source are ignored, only the opacity has an effect.

To show the source image instead, consider SrcOut.

To reverse the semantic of the mask (only showing the destination where the source is present, rather than where it is absent), consider DstIn.

This corresponds to the "Destination out Source" Porter-Duff operator.

DstOver

enum val DstOver : BlendMode

Composite the source image under the destination image.

This is the opposite of SrcOver.

This is useful when the source image should have been painted before the destination image, but could not be.

Exclusion

enum val Exclusion : BlendMode

Subtract double the product of the two images from the sum of the two images.

Compositing black has no effect; compositing white inverts the colors of the other image.

The opacity of the output image is computed in the same way as for SrcOver.

NOTE This BlendMode can only be used on Android API level 29 and above

The effect is similar to Difference but softer.

Hardlight

enum val Hardlight : BlendMode

Multiply the components of the source and destination images after adjusting them to favor the source.

Specifically, if the source value is smaller, this multiplies it with the destination value, whereas is the destination value is smaller, it multiplies the inverse of the destination value with the inverse of the source value, then inverts the result.

Inverting the components means that a fully saturated channel (opaque white) is treated as the value 0.0, and values normally treated as 0.0 (black, transparent) are treated as 1.0.

NOTE This BlendMode can only be used on Android API level 29 and above

See also:

  • Modulate, which always multiplies the values.
  • Screen, which always multiplies the inverses of the values.
  • Overlay, which is similar to Hardlight but favors the destination image instead of the source image.

Hue

enum val Hue : BlendMode

Take the hue of the source image, and the saturation and luminosity of the destination image.

The effect is to tint the destination image with the source image.

The opacity of the output image is computed in the same way as for SrcOver. Regions that are entirely transparent in the source image take their hue from the destination.

NOTE This BlendMode can only be used on Android API level 29 and above

Lighten

enum val Lighten : BlendMode

Composite the source and destination image by choosing the highest value from each color channel.

The opacity of the output image is computed in the same way as for SrcOver.

Luminosity

enum val Luminosity : BlendMode

Take the luminosity of the source image, and the hue and saturation of the destination image.

The opacity of the output image is computed in the same way as for SrcOver. Regions that are entirely transparent in the source image take their luminosity from the destination.

NOTE This BlendMode can only be used on Android API level 29 and above

See also:

  • Saturation, which applies the saturation of the source image to the destination.

Modulate

enum val Modulate :