fill.blendMode

Type String
Object Paint
Library display.*
Revision Release 2022.3683
Keywords additive blends, blend mode, blending, Porter-Duff
See also Paint
object.fill
object.blendMode

Overview

Allows you to change the blend mode on a specific object.

Standard Blend Modes

Standard blend modes can be specified via one of the following strings:

Porter-Duff Presets

Porter-Duff blend modes can be specified via one of the strings listed below.

Custom Blend Modes

Custom blend modes allow you to control how the source and destination factors are used in the blending calculation. They follow the blend factors discussed in the OpenGL-ES 2 specification.

You can specify custom blend modes via a Lua table that specifies the source and destination factors as key-value pairs.

Keys

srcColor (required)

String. See values below for a list of valid string values.

srcAlpha (optional)

String. By default, same as srcColor.

dstColor (required)

String. See values below for a list of valid string values.

dstAlpha (optional)

String. By default, same as dstColor.

Values

  • "zero"
  • "one"
  • "srcColor"
  • "oneMinusSrcColor"
  • "dstColor"
  • "oneMinusDstColor"
  • "srcAlpha"
  • "oneMinusSrcAlpha"
  • "dstAlpha"
  • "oneMinusDstAlpha"
  • "srcAlphaSaturate"

Limitations

Premultiplied Alpha

Some Android devices do not consistently load images as premultiplied alpha. We have applied workarounds but they are not foolproof. On those devices, the "multiply" and "screen" blend modes will not work correctly, and you should see a single warning message in the console about it.

Porter-Duff blend modes will only work with images that have been loaded as premultiplied alpha.

Examples

Additive Blend
local laser = display.newImage( "blendmode_laser.png" )
laser.fill.blendMode = "add"
Porter-Duff Preset
local laser = display.newImage( "blendmode_laser.png" )
laser.fill.blendMode = "srcAtop"
Custom Blend
local laser = display.newImage( "blendmode_laser.png" )

local customBlend = {
    srcColor = "srcColor",
    srcAlpha = "oneMinusDstColor",
    dstColor = "dstAlpha",
    dstAlpha = "srcAlphaSaturate"
}

laser.fill.blendMode = customBlend