object.blendMode

Type String
Object DisplayObject
Library display.*
Revision Current Public Release (2014.2511)
Keywords additive blends, blend mode, blending

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.

Note

This feature is restricted to CoronaCards and the Corona SDK Pro and Corona Enterprise subscription tiers.

Custom Blend Modes

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

Note

This feature is restricted to CoronaCards and the Corona SDK Pro and Corona Enterprise subscription tiers.

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.blendMode = "add"
Porter-Duff Preset
local laser = display.newImage( "blendmode_laser.png" )
laser.blendMode = "srcAtop"
Custom Blend
local laser = display.newImage( "blendmode_laser.png" )

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

laser.blendMode = customBlend