自定义着色器效果

命名效果

效果的名称由以下属性确定

• category — 效果的类型。
• group — 效果的组。如果未提供，Solar2D 将假定为 custom。
• name — 给定类别中的名称。

在显示对象上设置效果时，您必须提供完全限定的字符串，方法是将上述值连接起来，并用 . 分隔每个值，如下所示

local effectName = "[category].[group].[name]"

定义内核

Solar2D 将着色器代码片段打包成**内核**的形式. 通过在内核中构建特定的顶点和片段处理任务，可以大大简化自定义效果的创建。

本质上，内核是主要着色器程序依赖的用于处理特定处理任务的着色器代码。Solar2D 支持顶点内核和片段内核。您必须在效果中至少指定一种内核类型（或两者）。如果未指定顶点/片段内核，Solar2D 将分别插入默认的顶点/片段内核。

时间

顶点内核可以访问以下时间统一变量

• P_DEFAULT float CoronaTotalTime — 应用程序运行时间（以秒为单位）。
• P_DEFAULT float CoronaDeltaTime — 自上一帧以来的时间（以秒为单位）。

如果在内核的着色器代码中使用这些变量，则您的内核隐式地与时间相关。换句话说，您的内核将输出不同的结果并随着时间的推移而演变。

使用这些变量时，您需要告诉 Solar2D 您的着色器需要 GPU重新渲染场景，即使场景中显示对象没有其他更改也是如此。您可以通过在内核定义中设置 kernel.isTimeDependent 属性来做到这一点，如下所示。请注意，只有当您的着色器代码真正与时间相关与时间相关重新渲染时才应设置此属性，因为它会强制 GPU

kernel.isTimeDependent = true

大小

顶点内核可以访问以下大小统一变量

• P_POSITION vec2 CoronaContentScale — 沿 **x** 和 **y** 轴的每个屏幕像素的内容像素数。内容像素是指 Solar2D 的坐标系，由项目的内容缩放设置决定。

• P_UV vec4 CoronaTexelSize — 这些值可帮助您了解归一化纹理像素（纹素）与实际像素的关系。这很有用，因为纹理坐标是归一化的（0 到 1），通常您只有关于比例的信息（纹理宽度或高度的百分比）。实际上，这些值可以帮助您根据实际屏幕/内容像素距离创建效果。

坐标

• P_UV vec2 CoronaTexCoord — 顶点的纹理坐标。

示例

以下示例使图像的底部边缘以固定幅度摆动

local kernel = {}

-- "filter.custom.myWobble"
kernel.category = "filter"
kernel.name = "myWobble"

-- Shader code uses time environment variable CoronaTotalTime
kernel.isTimeDependent = true

kernel.vertex =
[[
P_POSITION vec2 VertexKernel( P_POSITION vec2 position )
{
    P_POSITION float amplitude = 10;
    position.y += sin( 3.0 * CoronaTotalTime + CoronaTexCoord.x ) * amplitude * CoronaTexCoord.y;

    return position;
}
]]

时间

片段内核可以访问与顶点内核时间相同的统一变量。

大小

片段内核可以访问与顶点内核大小相同的统一变量。

采样器

• P_COLOR sampler2D CoronaSampler0 — 第一个纹理的纹理采样器。
• P_COLOR sampler2D CoronaSampler1 — 第二个纹理的纹理采样器（需要复合绘画）。

Alpha/颜色

所有显示对象都有一个alpha属性。此外，形状对象有一个颜色，可以通过object:setFillColor()或颜色通道属性设置（r，g，b，a）对象的fill属性。

通常，您的着色器应将这些属性的效果合并到片段内核返回的颜色中。您可以通过调用以下函数来计算正确的颜色来做到这一点

P_COLOR vec4 CoronaColorScale( P_COLOR vec4 color );

此函数接受一个输入颜色向量（红色、绿色、蓝色和 alpha 通道），并返回一个由显示对象的 alpha 和颜色调制后的颜色向量，如片段内核示例所示。通常，您应该在片段内核的末尾调用此函数，以便正确计算片段内核应返回的颜色向量。

示例

以下示例通过每个颜色分量的固定量使图像变亮

local kernel = {}

-- "filter.custom.myBrighten"
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( texColor );
}
]]

示例

以下示例结合了 wobble 顶点内核和 brighten 片段内核。与上面 "myBrighten" 片段示例不同，此版本不使用固定的亮度值。相反，顶点着色器为每个顶点计算一个振荡亮度值，片段着色器根据其着色的像素线性插值亮度值。

local kernel = {}
kernel.category = "filter"
kernel.name = "wobbleAndBrighten"

-- Shader code uses time environment variable CoronaTotalTime
kernel.isTimeDependent = true

kernel.vertex =
[[
varying P_COLOR float delta; // Custom varying variable

P_POSITION vec2 VertexKernel( P_POSITION vec2 position )
{
    P_POSITION float amplitude = 10;

    position.y += sin( 3.0 * CoronaTotalTime + CoronaTexCoord.x ) * amplitude * CoronaTexCoord.y;

    // Calculate value for varying
    delta = 0.4*(CoronaTexCoord.y + sin( 3.0 * CoronaTotalTime + 2.0 * CoronaTexCoord.x ));

    return position;
}
]]

kernel.fragment =
[[
varying P_COLOR float delta; // Matches declaration in vertex shader

P_COLOR vec4 FragmentKernel( P_UV vec2 texCoord )
{
    // Brightness changes based on interpolated value of custom varying variable
    P_COLOR float brightness = delta;

    P_COLOR vec4 texColor = texture2D( CoronaSampler0, texCoord );

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

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

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

顶点用户数据

使用顶点用户数据传递效果参数时，会为每个顶点复制效果参数。为了最大限度地减少数据大小的影响，效果参数被限制为 vec4（4 个浮点数的向量）。这在顶点和片段内核中作为以下只读向量变量提供

P_DEFAULT vec4 CoronaVertexUserData

例如，假设您要修改上面的 "filter.custom.myBrighten" 效果示例，以便在 Lua 中，效果有一个 "brightness" 参数

object.fill.effect = "filter.custom.myBrighten"
object.fill.effect.brightness = 0.3

要实现这一点，您必须指示 Solar2D 将 Lua 中的参数名称与 CoronaVertexUserData 返回的向量中的相应组件映射。以下代码告诉 Solar2D "brightness" 参数是第一个组件（index = 0）的 CoronaVertexUserData 向量。

kernel.vertexData =
{
    {
        name = "brightness",
        default = 0, 
        min = 0,
        max = 1,
        index = 0,  -- This corresponds to "CoronaVertexUserData.x"
    },
}

在上面的数组 (kernel.vertexData) 中，每个元素都是一个表，每个表指定

• name — 在 Lua 中公开的参数的 字符串 名称。
• default — 默认值。
• min — 最小值。
• max — 最大值。

• index — CoronaVertexUserData 中相应向量组件的索引

  index = 0 → CoronaVertexUserData.x
index = 1 → CoronaVertexUserData.y
index = 2 → CoronaVertexUserData.z
index = 3 → CoronaVertexUserData.w

最后，修改 FragmentKernel 以读取参数值，通过 CoronaVertexUserData 访问参数值

kernel.fragment =
[[
P_COLOR vec4 FragmentKernel( P_UV vec2 texCoord )
{
    P_COLOR float brightness = CoronaVertexUserData.x;

    ...
}
]]

统一用户数据

（即将推出的功能）

Solar2D 模拟器与设备

精度限定符宏

与其他风格的 GLSL 不同，GLSL ES(OpenGL ES 2.0)通常要求在变量声明中指定精度限定符。因此，明确精度是一个好习惯.

您应该使用以下精度限定符宏之一，而不是使用像 lowp 这样的原始精度限定符。默认值针对数据类型进行了优化

• P_DEFAULT — 对于通用值；默认值为 highp。
• P_RANDOM — 对于随机值；默认值为 highp。
• P_POSITION — 对于位置；默认值为 mediump。
• P_NORMAL — 对于法线；默认值为 mediump。
• P_UV — 对于纹理坐标；默认值为 mediump。
• P_COLOR — 对于像素颜色；默认值为 lowp。

我们强烈建议您使用 Solar2D 的默认着色器精度设置，所有这些设置都经过优化以平衡性能和保真度。但是，您的项目可以在 config.lua 中覆盖这些设置（指南）。

高精度设备

并非所有设备都支持高精度。因此，如果您的内核需要高精度，则应使用 GL_FRAGMENT_PRECISION_HIGH 宏。如果设备支持高精度，则为 1，否则为未定义。

如果设备不支持 highp，您的内核可以通过编写两个实现来优雅地降级

P_COLOR vec4 FragmentKernel( P_UV vec2 texCoord )
{
#ifdef GL_FRAGMENT_PRECISION_HIGH
    // Code path for high precision calculations
#else
    // Code path for fallback
#endif
}

预乘 Alpha

Solar2D 提供具有 预乘 alpha 的纹理。因此，您可能需要除以 alpha 来恢复原始 RGB 值。但是，出于性能原因，您应尝试执行计算以避免除法。比较以下两个使图像变亮的内核

1. 在以下内容中，通过撤消预乘alpha 来恢复原始 RGB 值，稍后将重新应用alpha。这并不理想，因为它会为每个像素在 GPU 上生成大量额外的操作。

// Non-optimal Version
P_COLOR vec4 FragmentKernel( P_UV vec2 texCoord )
{
    P_COLOR float brightness = 0.5;
    P_COLOR vec4 texColor = texture2D( CoronaSampler0, texCoord );

    // BAD: Recover original RGBs via divide
    texColor.rgb /= texColor.a;

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

    // BAD: Re-apply the pre-multiplied alpha
    texColor.rgb *= texColor.a;

    return CoronaColorScale( texColor );
}

2. 此版本将纹理的 alpha 预乘到 brightness 变量，以便可以直接将其添加到纹理的 RGB 值。这规避了上述实现的缺陷.

// Optimal Version
P_COLOR vec4 FragmentKernel( P_UV vec2 texCoord )
{
    P_COLOR float brightness = 0.5;
    P_COLOR vec4 texColor = texture2D( CoronaSampler0, texCoord );

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

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

    return CoronaColorScale( texColor );
}

向量计算

某些设备没有配备矢量处理器的 GPU。在这些情况下，矢量计算可以在标量处理器上执行。通常，您应仔细考虑着色器中的运算顺序，以确保在标量处理器上避免不必要的计算。

P_DEFAULT float f0, f1;
P_DEFAULT vec4 v0, v1;
v0 = (v1 * f0) * f1; // BAD: Multiply each scalar to a vector

highp float f0, f1;
highp vec4 v0, v1;
v0 = v1 * (f0 * f1); // GOOD: Multiply scalars first

highp vec4 v0;
highp vec4 v1;
highp vec4 v2;
v2.xz = v0 * v1; // GOOD: Write mask limits calculations

避免动态纹理查找

当片段着色器在与传递到着色器的纹理坐标不同的位置采样纹理时，会导致动态纹理查找，也称为“依赖纹理读取”。在OpenGL-ES 2.0中，依赖纹理读取会延迟纹素数据加载并降低性能。这就是为什么某些对纹素区域进行采样的效果（例如模糊效果）较慢的原因。

相反，没有依赖纹理读取的效果使 GPU 能够在预取着色器执行之前获取纹素数据，从而减少 I/O 延迟。

避免分支和循环

分支指令（if 条件）开销很大。在可能的情况下，for 循环应该展开或替换为向量运算。