graphics.defineEffect()

Type Function
Library graphics.*
Return value none
Revision Release 2024.3703
Keywords shaders, effects, graphics
See also Custom Shader Effects (guide)
Filters / Generators / Composites (guide)
customFilter (sample)

Overview

This function allows you to extend Corona and define a custom shader effect. Your custom effect can define either a vertex kernel or a fragment kernel (or both). These kernels are similar to shaders, except that they must define functions with a specific name and which conform to specific function signatures.

See the Custom Shader Effects guide for a detailed explanation of how to write shader code for these kernels.

Note

Custom effects are supported on iOS, Android, macOS desktop, and Win32 desktop.

Syntax

graphics.defineEffect( effect )
effect (required)

Table. Table which defines a shader effect — see the next section for details.

Effect Table Reference

The effect table can contain the following properties:

category (required)

String. The category for the effect. This determines the number of input textures:

  • "generator" — Assumes 0 input textures.
  • "filter" — Assumes 1 input texture.
  • "composite" — Assumes 2 input textures.
group (optional)

String. The name of the group that the effect belongs to. While built-in effects have no name, custom effects are placed in the "custom" group by default. You can override this default by passing in a different group name.

name (required)

String. A name which uniquely identifies the effect within a category. This must not conflict with a pre-existing name within a given category and group. Together with the category property and group property, this determines the full name of the effect that you assign to a Paint object as "<category>.<group>.<name>".

fragment (required)

String. The shader code for the fragment kernel. See Fragment Kernels in the Custom Shader Effects guide. Note that this is not required if the vertex property is set.

vertex (required)

String. The shader code for the vertex kernel. See Vertex Kernels in the Custom Shader Effects guide. Note that this is not required if the fragment property is set.

isTimeDependent (optional)

Boolean. If the vertex or fragment kernel depends on time (the output varies with time), set this to true. The default (if not provided) assumes a value of false, meaning the kernel does not use time in its calculations.

timeTransform (optional)

Table. If the vertex or fragment kernel depends on time, you can use this to mitigate potentially large time values. See Time Transforms in the Custom Shader Effects guide.

vertexData (optional)

Table. This allows you to specify named parameters for your effect. You can specify up to four parameters, each of which is a scalar (float). See Effect Parameters in the Custom Shader Effects guide for more information. Note that you can specify either vertexData or uniformData but not both.

uniformData (optional)

Table. This allows you to specify named parameters for your effect. You can specify up to four parameters, each of which can be a different type: scalar (float), vec2 vec3, vec4, mat3, or mat4. See Effect Parameters in the Custom Shader Effects guide for more information. Note that you can specify either vertexData or uniformData but not both.

Example

-- An effect that brightens each pixel
-- Usage: object.fill.effect = "filter.custom.myBrighten"
local kernel = {}
kernel.category = "filter"
kernel.name = "myBrighten"

kernel.fragment =
[[
P_COLOR vec4 FragmentKernel( P_UV vec2 texCoord )
{
    P_COLOR float brightness = 0.5;
    P_COLOR vec4 texColor = texture2D( CoronaSampler0, texCoord );

    // Pre-multiply the alpha to brightness
    brightness = brightness * texColor.a;

    // Add the brightness
    texColor.rgb += brightness;

    // Modulate by the display object's combined alpha/tint
    return CoronaColorScale( result );
}
]]

graphics.defineEffect( kernel )