表面着色器（Surface Shader）

随着渲染对画面要求越来越高，着色器的实现也更加复杂，为了提供高效、统一的着色器流程，在 v3.5.1 中，我们新增了 Surface Shader 框架。开发者可以在 资源管理器 -> internal -> effect -> surfaces 以及 资源管理器 -> internal -> chunk -> surfaces 中找到对应的着色器以及着色器片段。

Surface Shader 使用统一渲染流程和结构，可以让用户以简洁的代码创建表面材质信息，指定用于组合的光照和着色模型。相比旧版（Legacy Shader）的优点是更易书写和维护，有更好的版本兼容性，也更不容易产生渲染错误。并且可以从统一流程中获取很多公共特性，如统一的全场景光照和 Debug View 调试功能等。

Creator 也更易扩展出多种常见的复杂材质提供给用户，未来还会支持 Shader Graph 自动生成 Effect 代码，可以极大提高 Shader 开发者的效率。但代价是无法定制光照和着色运算的具体内容，一旦指定了光照和着色模式，流程将按照既定路径来进行，不支持临时屏蔽或更改一些内部计算。如有这样的需求，请使用 Legacy Shader。

Surface Shader 仍然是基于 Cocos Effect 的语法，以前的材质参数、technique、pass 及渲染状态等的定义完全可以复用。

相关概念

在了解 Surface Shader 之前，有几个概念需要说明一下：

1、渲染用途

说明了物体需要被渲染到哪里。

我们有很多渲染 Pass 用于渲染同一个物体到不同的纹理数据上，这些数据分别有内置的用途。比如说最常用的 渲染到场景 可以直接用于屏幕显示，或者把阴影投射物 渲染到阴影贴图，或者 渲染到动态环境反射 来生成反射贴图等。

这部分内容可以在 资源管理器 -> internal -> chunk -> shading-entries -> main-functions 内找到。

2、光照模型

说明物体表面的微观结构与固有光学属性是如何对光线产生影响和作用的。

比如说塑料会产生各向同性的圆形高光，头发会产生各向异性的条纹状高光，光线在皮肤上会发生散射，而在镜子这种更接近理想光学表面的物体上，绝大多数光线只会沿着反射角发生反射等。

3、表面材质模型

说明物体表面的一些物理参数（反照率、粗糙度等）是如何影响光照结果的。

通常材质与光照模型必须关联使用，我们会逐渐扩展常用的材质与光照模型。

4、Shader Stage

渲染是由不同的着色器来完成的，有处理顶点、像素或通用计算的不同阶段，如下表所示：

代码框架

除了和 Cocos Effect 相同的 CCEffect 参数、technique 和 UBO 内存布局等定义之外，再也无需考虑各种内部宏定义的处理、着色器输入输出变量、Instancing¹、繁琐的顶点变换、全局像素效果和每种渲染用途的细节计算等。

典型的 Surface Shader 代码通常由三个部分组成：

• Macro Remapping：将用户在 Effect 中声明或使用的宏名（部分）映射为 Surface 内部宏名。
• Surface Functions：用于声明表面材质信息相关的 Surface 函数。
• Shader Assembly：用于组装每个顶点着色器（Vertex Shader）和片元着色器（Fragment Shader）的代码模块。

此处以内置着色器 surfaces/standard.effect 为例，说明 Surface Shader 的代码框架。

Macro Remapping

Surface Shader 内部计算时会用到一些宏开关，需要根据 Effect 中对应含义的宏名来指定。考虑到 Effect 中的宏名会直接显示在材质面板上，这样做的好处是 Effect 中的名称可以自由开放给用户而不影响 Surface 内部计算。

这些宏以 CC_SURFACES_ 开头，以下是完整的宏列表：

注意： 这些宏可以不定义，系统内部会自动定义为默认值 0；也可以直接定义为 0 或其他值，表示在此 Effect 中强制关闭或打开，禁止用户调节。

搜索 CCProgram macro-remapping 一段，可以看到内容有如下三部分组成：

1、在 Surface 函数中未使用过的宏

// ui displayed macros not used in this effect file
#pragma define-meta HAS_SECOND_UV
#pragma define-meta USE_TWOSIDE
#pragma define-meta USE_REFLECTION_DENOISE
#pragma define-meta IS_ANISOTROPY
#pragma define-meta USE_COMPATIBLE_LIGHTING

#define CC_SURFACES_USE_SECOND_UV HAS_SECOND_UV
#define CC_SURFACES_USE_TWO_SIDED USE_TWOSIDE
#define CC_SURFACES_USE_REFLECTION_DENOISE USE_REFLECTION_DENOISE
#define CC_SURFACES_LIGHTING_ANISOTROPIC IS_ANISOTROPY
#define CC_SURFACES_USE_LEGACY_COMPATIBLE_LIGHTING USE_COMPATIBLE_LIGHTING

由于 Surface Shader 精简了很多不必要的公共流程代码，如 VS FS 传参的定义等等，之前存在于旧流程中的 #if HAS_SECOND_UV 这样的代码也就不存在了。对于此类宏，必须要在此处预先定义 #pragma define-meta MACRONAME，这样才可以显示在材质面板上。 定义好之后，下一行就可以使用标准 GLSL 预定义 #define CC_SURFACES_MACRONAME MACRONAME。

2、在 Surface 函数中使用过的宏

// ui displayed macros used in this effect file
#define CC_SURFACES_USE_VERTEX_COLOR USE_VERTEX_COLOR
#if IS_ANISOTROPY || USE_NORMAL_MAP
  #define CC_SURFACES_USE_TANGENT_SPACE 1
#endif

这部分简单多了，直接按照 #define CC_SURFACES_MACRONAME MACRONAME 定义即可。 不过 CC_SURFACES_USE_TANGENT_SPACE 宏要特别注意，通常开了法线贴图或各向异性，都要开启该宏，否则可能会出现编译错误。

3、内部功能性的宏

// functionality for each effect
#define CC_SURFACES_LIGHTING_ANISOTROPIC_ENVCONVOLUTION_COUNT 31

直接定义想要的值即可。

Surface Function

每个材质函数的功能类似于 DCC（Digital Content Creation） 软件的材质编辑器中输出一个材质参数到指定的材质节点。类似于：

1、定义

可以使用 CCProgram 或单独的 chunk 来定义 Surface 材质函数块。

注意：VS 和 FS 使用的函数块必须分开。通常来讲所有的 VS 共享一个，所有的 FS 共享一个。在我们的例子中 standard-vs 和shadow-caster-vs 共用 surface-vertex 块，而 standard-fs 和 shadow-caster-fs 共用 surface-fragment 块。

用这种方式的好处是所有的用户自定义动画与材质的代码只需要写一份，却可以在各种渲染用途中保持统一。

Surface Shader 在内部提供了简单的默认函数，所以 这些函数并不是必须定义的，如果你想重载某函数，需要预定义该函数对应的宏来完成。这些函数命名以 Surfaces + ShaderStage 名 打头，后跟功能描述。可以在 editor/assets/chunks/surfaces/default-functions 中查看不同材质模型中各 Surface 函数的具体定义与实现，如：

#define CC_SURFACES_VERTEX_MODIFY_WORLD_POS
vec3 SurfacesVertexModifyWorldPos(in SurfacesStandardVertexIntermediate In)
{
  vec3 worldPos = In.worldPos;
  worldPos.x += sin(cc_time.x * worldPos.z);
  worldPos.y += cos(cc_time.x * worldPos.z);
  return worldPos;
}

预先定义 CC_SURFACES_VERTEX_MODIFY_WORLD_POS 宏，可以忽略掉内部默认函数，让 Surface Shader 使用你定义的函数来计算材质参数。

注意：用这种方式的好处是方便扩展多种不同的材质模型和代码版本升级，新版增加的函数可以用新的名称和参数，仍然可以调用旧版定义的函数获取计算结果，无需写重复代码，也不用担心升级后编译报错。

2、VS 对应的函数列表

VS 中的处理和材质模型关系相对比较小，所以这里都使用通用函数，函数参数均为 SurfacesStandardVertexIntermediate 结构体，存放的是 VS 输入输出的数据。用户无需再关心具体的顶点输入输出流程处理，只需要聚焦到某个数据是否需要及如何修改。

3、FS 对应的函数列表

FS 中的函数大部分是只修改一项，在 Surface 函数中直接返回即可。有些函数可能会修改多项（如 UV 和切空间向量），此时会在参数列表中传入多个值用于修改。具体属于哪种情况请参考函数定义。

4、VS 输入值的获取

VS 输入值都在 SurfacesStandardVertexIntermediate 结构体中，作为 Surface 函数参数传入

5、FS 输入值的获取

FS 的输入值目前作为宏来使用，大部分输入值在内部做了容错处理，可以无视对应宏条件随意访问。

Shader Assembly

我们使用 include 不同模块头文件的形式，按顺序组装每个 Pass 的 Shader。

搜索 standard-fs 一段，可以看到整个 Fragment Shader 的组装过程分为 6 个部分

1、宏

首先需要包含必要的内部宏映射和通用宏定义。

宏映射使用在 Macro Remapping 一段中描述的自定义 CCProgram 代码块或 chunk 文件。

接下来需要包含通用宏定义文件 common-macros，如下所示：

Pass standard-fs:
#include <macro-remapping>
#include <surfaces/effect-macros/common-macros>

对于特殊渲染用途的 Pass 而言，很多 Shader 功能是关掉的，因此无需包含 common-macros，直接包含对应渲染用途的宏定义文件即可：

Pass shadow-caster-fs:
#include <surfaces/effect-macros/render-to-shadowmap>

2、Shader 通用头文件

根据 当前的 Shader Stage 名称 来选择对应的通用头文件，如下所示：

Vertex Shader：
#include <surfaces/includes/common-vs>
Fragement Shader：
#include <surfaces/includes/common-fs>

3、用户 Surface 功能函数

使用在 Surface Function 一段中描述的自定义 CCProgram 代码块或 chunk 文件。

由于 Surface 功能函数可能还会用到 Effect 参数相关的 UBO 内存布局，因此它也要提前被 Include，否则会编译出错。

如下所示：

#include <shared-ubos>
#include <surface-fragment>

4、光照模型

此部分为可选项，只限渲染到场景的默认用途及 Fragment Shader 使用。

使用 光照模型名称 来选择对应的头文件，如下所示：

Standard PBR Lighting：
#include <lighting-models/includes/standard>
Toon Lighting：
#include <lighting-models/includes/toon>

5、表面材质和着色模型

此部分为 可选项，只限渲染到场景的默认用途使用。

材质模型名称 + Shader Stage 名称 来选择对应的头文件，如下所示：

Vertex Shader：
#include <surfaces/includes/standard-vs>
Fragement Shader：
#include <surfaces/includes/standard-fs>

6、Shader 主函数

使用当前 Pass 的渲染用途名称 + Shader Stage 名称 来选择对应的主函数头文件。

Pass standard-fs:
#include <shading-entries/main-functions/render-to-scene/fs>
Pass shadow-caster-fs:
#include <shading-entries/main-functions/render-to-shadowmap/fs>

渲染调试功能

注意：只有使用 Surface Shader 框架的材质，内置的渲染调试功能才可以生效。

通过在编辑器的场景预览窗口右上角按钮选择对应的调试模式即可同屏查看模型、材质、光照及其他计算数据，在渲染效果异常的时候可以快速定位问题。

为了方便逐像素对比，我们使用全屏调试而非画中画的显示方式，可以快速在同一幅画面中切换不同数据来定位渲染错误所在，也可使用取色器来探知像素的具体数值。

另外 Surface Shader 还内置了 无理数可视化 的功能，一旦有一些像素出现异常的 红色(255, 0, 51) 和 绿色(0, 255, 51) 交替闪烁，则说明这些像素的渲染计算出现了无理数，请使用单项调试模式来检查模型切线或其他相关数据。

渲染调试功能细分为如下三种：

1、公共选项

无论单项还是组合模式中都生效的调试选项，包括：

2、单项模式

调试重点聚焦在某个需要测试的数据上，整个场景都将此数据可视化输出。

可调试的数据包括四大类：

I、原始模型数据

II、原始材质数据

III、光照结果数据

IV、其他数据

3、组合模式

调试重点聚焦在总体的渲染表现上，可以屏蔽或打开每个模块，模块之间互不关联，可查看不同模块之间对渲染效果的影响。

单项模式优先级高于组合模式，如果想使用组合模式的话，必须选中无单项模式。

包括：

进阶使用方法

1. 自行添加 vs 输出与 fs 输入：VS新定义 varying 变量之后在某个 Surface 函数中计算并输出该值
2. FS 新定义 varying 变量之后在某个 Surface 函数中获取并使用该值
3. 甚至可以在不同的 Shader 主函数中混用 Surface Shader 和 Legacy Shader（但是要保证 varying 顶点数据在两个阶段一致）。

公共函数库

可以在 资源管理器 -> internal -> chunks -> common 文件夹下找到不同分类的函数库头文件。

库中的函数不依赖任何内部数据（引擎相关 uniform 和贴图等），可以当作工具函数直接使用。

Surface 内部已经自动包含了常用的公共函数头文件，根据类型可分为：

¹. 不支持自定义几何体实例化属性。 ↩