Cocos Creator Shader —— 附录

💡 个人专栏 ShaderMyHead 的附录。

一、Cocos Creator 内置着色器变量

1.1 顶点着色器输入变量 (Vertex Attributes)

均是以 a_ 开头的变量：

基础顶点属性

a_position ：顶点位置，通常为 vec3 类型
a_normal ：顶点法线，通常为 vec3 类型
a_texCoord ：主纹理 UV 坐标，通常为 vec2 类型
a_tangent ：切线向量，通常为 vec4 类型
a_color ：顶点颜色，通常为 vec4 类型

次要UV和光照贴图

a_texCoord1 ：第二套 UV 坐标，用于光照贴图等

蒙皮动画相关

a_joints ：骨骼索引，通常为 vec4 或 u32vec4 类型
a_weights ：骨骼权重，通常为 vec4 类型
a_jointAnimInfo ：骨骼动画信息

实例化相关

a_matWorld0 、 a_matWorld1 、 a_matWorld2 ：实例化世界矩阵
a_lightingMapUVParam ：光照贴图UV参数
a_localShadowBiasAndProbeId ：阴影偏移和反射探针ID
a_reflectionProbeData ：反射探针数据
a_sh_linear_const_r/g/b ：球谐函数光照系数

形变动画相关

a_vertexId ：顶点ID，用于形变动画

粒子系统相关

a_position_starttime ：粒子中心位置和开始时间
a_size_uv ：粒子大小和 UV 信息
a_rotation_uv ：粒子旋转和 UV 信息
a_dir_life ：粒子初始速度和生命周期
a_rndSeed ：随机种子
a_texCoord1 ：粒子大小
a_texCoord2 ：粒子旋转
a_texCoord3 ：网格顶点
a_texCoord4 ：位置和帧索引
a_color1 ：速度和缩放

特殊用途

a_lineDistance ：线距离
a_dist ：距离
a_batch_id ：批处理 ID
a_batch_uv ：批处理 UV
a_color2 ：第二套颜色（用于 Spine 动画）

1.2 全局 Uniform 变量 (UBO)

指通过 Uniform Buffer Objects (UBO) 定义的全局变量，官方文档仅罗列了常用的几个。

该部分变量在使用时，需要先引入对应的着色器片段（Chunk）：
c 复制代码
//local uniforms 
#include <builtin/uniforms/cc-local> 
//global uniforms 
#include ><builtin/uniforms/cc-global>

CCGlobal UBO

cc_time ：时间信息
cc_screenSize ：屏幕尺寸
cc_nativeSize ：原生尺寸
cc_probeInfo ：探针信息
cc_debug_view_mode ：调试视图模式

CCCamera UBO

cc_matView ：视图矩阵
cc_matViewInv ：视图矩阵的逆
cc_matProj ：投影矩阵
cc_matProjInv ：投影矩阵的逆
cc_matViewProj ：视图投影矩阵
cc_matViewProjInv ：视图投影矩阵的逆
cc_cameraPos ：相机位置
cc_surfaceTransform ：表面变换
cc_screenScale ：屏幕缩放
cc_exposure ：曝光参数
cc_mainLitDir ：主光源方向
cc_mainLitColor ：主光源颜色
cc_ambientSky ：天空环境光
cc_ambientGround ：地面环境光
cc_fogColor、cc_fogBase、cc_fogAdd ：雾效参数
cc_nearFar ：近远平面
cc_viewPort ：视口信息

CCLocal UBO

cc_matWorld ：世界矩阵
cc_matWorldIT ：世界矩阵的逆转置
cc_lightingMapUVParam ：光照贴图UV参数
cc_localShadowBias ：本地阴影偏移
cc_reflectionProbeData1/2 ：反射探针数据
cc_reflectionProbeBlendData1/2 ：反射探针混合数据

CCShadow UBO

cc_matLightView ：光源视图矩阵
cc_matLightViewProj ：光源视图投影矩阵
cc_shadowInvProjDepthInfo ：阴影投影深度信息
cc_shadowProjDepthInfo ：阴影投影深度信息
cc_shadowProjInfo ：阴影投影信息
cc_shadowNFLSInfo ：阴影近远平面信息
cc_shadowWHPBInfo ：阴影宽高PCF偏移信息
cc_shadowLPNNInfo ：阴影光源类型信息
cc_shadowColor ：阴影颜色
cc_planarNDInfo ：平面法线深度信息

CCForwardLight UBO

cc_lightPos ：光源位置
cc_lightColor ：光源颜色
cc_lightSizeRangeAngle ：光源大小范围角度
cc_lightDir ：光源方向
cc_lightBoundingSizeVS ：光源包围盒大小

CCSH UBO (球谐函数)

cc_sh_linear_const_r/g/b ：线性球谐系数
cc_sh_quadratic_r/g/b/a ：二次球谐系数

CCCSM UBO (级联阴影映射)

cc_csmViewDir0/1/2 ：CSM视图方向
cc_csmAtlas ：CSM图集
cc_matCSMViewProj ：CSM视图投影矩阵
cc_csmProjDepthInfo ：CSM投影深度信息
cc_csmProjInfo ：CSM投影信息
cc_csmSplitsInfo ：CSM分割信息

CCSkinning UBO (蒙皮动画)

cc_jointTextureInfo ：关节纹理信息
cc_jointAnimInfo ：关节动画信息
cc_jointTexture ：关节纹理
cc_realtimeJoint ：实时关节纹理
cc_joints ：关节矩阵数组

CCMorph UBO (形变动画)

cc_displacementWeights ：位移权重
cc_displacementTextureInfo ：位移纹理信息
cc_PositionDisplacements ：位置位移纹理
cc_NormalDisplacements ：法线位移纹理
cc_TangentDisplacements ：切线位移纹理

二、GLSL 内置方法（持续完善中）

2.1 纹理相关

texture

对一个纹理进行采样，返回采样结果。

语法

c 复制代码

texture(sampler2D sampler, vec2 coord [, float bias])
texture(samplerCube sampler, vec3 coord [, float bias])

参数

名称	类型	描述
sampler	`sampler2D`/`samplerCube`	平面或立方体的纹理采样器
coord	`vec`	要采样的纹理坐标
$可选$ bias	`vec`	采样偏移量，如果没有提供则默认为 `0`

返回值

纹理的 RGBA 信息，vec4 类型。

2.2 计算相关

distance

计算两个点的欧几里得距离。

语法

distance(p0, p1)

参数

名称	类型	描述
p0	`vec`	第一个点的坐标
p1	`vec`	第二个点的坐标

返回值

两个点的欧几里得距离，float 类型。

step

用于返回 0.0 或 1.0 的规范化跃迁函数。

语法

step(edge, x)

参数

名称	类型	描述
edge	`float`	阈值
x	`float`	输入值

返回值

float 类型：

当 x < edge：返回 0.0；
当 x >= edge：返回 1.0；

smoothstep

smoothstep函数是用于实现平滑插值的函数之一，它可以在指定起止边界的范围内，将一个给定的值进行平滑插值。例如在着色器计算过程中，将颜色值进行平滑渐变，从而实现渐变效果。

与 step 函数的区别如下：

语法

smoothstep (edge0, edge1, x)

参数

名称	类型	描述
edge0	`float`	起始边界
edge1	`float`	终止边界，必须大于 `edge0`
x	`float`	输入值

返回值

float 类型：

当 x <= edge0：返回 0.0；
当 x >= edge1：返回 1.0；
当 x 在 (edge0, edge1) 之间时，返回一个范围在 [0, 1] 之间的平滑插值（非线性）。

三、GLSL 内置变量和常量

在 GLSL 中有许多由 gl_ 为前缀的内置变量/常量。

💡 不推荐在 Cocos Creator 中使用这些变量，因为会破坏引擎的抽象层，导致 WebGL、Vulkan、Metal 等后端渲染接口的兼容性问题。此处仅供读者了解 GLSL 底层知识。

3.1 顶点着色器（Vertex Shader）的 GLSL 内置变量

gl_Position
- 用途：定义顶点在裁剪空间中的最终位置（必须赋值）。
- 类型：vec4（向量类型，下一小节会介绍）。
gl_PointSize
- 用途：设置点的渲染大小（以像素为单位）。
- 类型：float。
gl_VertexID
- 用途：当前顶点的索引（从 0 开始递增）。
- 类型：int。
gl_InstanceID
- 用途：实例化渲染时的实例索引（需配合 gl.drawArraysInstanced 使用）。
- 类型：int。

3.2 片段着色器（Fragment Shader）的 GLSL 内置变量

gl_FragCoord
- 用途：当前片段的窗口相对坐标（x, y 为像素位置，z 为深度值）。
- 类型：vec4（只读）。
gl_FrontFacing
- 用途：判断当前片段是否属于正面（由顶点顺序决定）。
- 类型：bool（只读）。
gl_PointCoord
- 用途：在绘制 gl.POINTS 时，获取当前点在纹理坐标系中的坐标（范围 [0,1]）。
- 类型：vec2（只读）。
gl_FragDepth
- 用途：手动设置片段的深度值（默认由 gl_FragCoord.z 决定）。
- 类型：float。
- 注意：修改此值可能导致性能下降（需启用 EXT_frag_depth 扩展）。

3.3 GLSL 内置常量

GLSL 中存在一些只读的内置常量（较少情况会用上）：

gl_MaxVertexAttribs：支持的顶点属性最大数量。
gl_MaxCombinedTextureImageUnits ：所有着色器阶段（顶点+片段）可同时使用的总纹理单元数。
gl_MaxVertexTextureImageUnits：顶点着色器可单独使用的纹理单元数。
gl_MaxVaryingComponents ：顶点着色器和片元着色器之间可以传递的最大 varying 分量数。

Cocos Creator Shader —— 附录

一、Cocos Creator 内置着色器变量

1.1 顶点着色器输入变量 (Vertex Attributes)

基础顶点属性

次要UV和光照贴图

蒙皮动画相关

实例化相关

形变动画相关

粒子系统相关

特殊用途

1.2 全局 Uniform 变量 (UBO)

CCGlobal UBO

CCCamera UBO

CCLocal UBO

CCShadow UBO

CCForwardLight UBO

CCSH UBO (球谐函数)

CCCSM UBO (级联阴影映射)

CCSkinning UBO (蒙皮动画)

CCMorph UBO (形变动画)

二、GLSL 内置方法 （持续完善中）

2.1 纹理相关

texture

2.2 计算相关

distance

step

smoothstep

三、GLSL 内置变量和常量

3.1 顶点着色器（Vertex Shader）的 GLSL 内置变量

3.2 片段着色器（Fragment Shader）的 GLSL 内置变量

3.3 GLSL 内置常量

二、GLSL 内置方法（持续完善中）