Pass 可选配置参数

Pass 中的参数主要分两个部分：

• 开发者可自定义的 属性检查器 面板参数 properties
• 引擎提供的用于控制渲染管线状态的 PipelineStates

Properties

properties 用于将 Shader 中定义的 uniform 进行别名映射。这个映射可以是某个 uniform 的完整映射，也可以是具体某个分量的映射（使用 target 参数），代码示例如下：

properties:
  albedo: { value: [1, 1, 1, 1] } # uniform vec4 albedo
  roughness: { value: 0.8, target: pbrParams.g } # uniform vec4 pbrParams
  offset: { value: [0, 0], target: tilingOffset.zw } # uniform vec4 tilingOffset
# say there is another uniform, vec4 emissive, that doesn't appear here
# so it will be assigned a default value of [0, 0, 0, 0] and will not appear in the inspector

默认情况下，properties 中定义的属性参数会暴露并显示在编辑器的 属性检查器 面板中，方便进行可视化控制。

如果不想显示在 属性检查器 面板上，可在定义属性时加上 editor: { visible: false }，代码示例如下：

properties:
  factor: { value: 1.0, editor: { visible: false } }

在 TypeScript 中可以使用 Material 类的 setProperty 方法以及 Pass 的 setUniform 方法进行设置，代码示例如下：

mat.setProperty('emissive', Color.GREY); // 直接设置对应的 Uniform 变量
mat.setProperty('albedo', Color.RED); 
mat.setProperty('roughness', 0.2); // 仅设置对应的分量
const h = mat.passes[0].getHandle('offset'); // 获取对应的 Uniform 的句柄
mat.passes[0].setUniform(h, new Vec2(0.5, 0.5)); // 使用 ‘Pass.setUniform’ 设置 Uniform 属性

注意：在 Shader 中定义的 uniform 也可以使用上述代码进行设置，即使没有在 properties 中定义。

未指定的 uniform，引擎将会在运行时根据自动分析出的数据类型给予默认值。更多关于默认值的内容，请参考下文说明。

为方便声明各 property 子属性，可以直接在 properties 内声明 __metadata__ 项，所有 property 都会继承它声明的内容，如：

properties:
  __metadata__: { editor: { visible: false } }
  a: { value: [1, 1, 0, 0] }
  b: { editor: { type: color } }
  c: { editor: { visible: true } }

这样 uniform a 和 b 已声明的各项参数都不会受到影响，但都不会显示在 属性检查器 中（visible 为 false），而 uniform c 仍会正常显示。

Property 参数列表

Property 中可配置的参数如下表所示，任何可配置的字段如果和默认值相同都可以省掉。

Property 默认值

对于 Property 的默认值， Cocos Effect 做出了如下的规定：

对于 defines：

• boolean 类型默认值为 false。
• number 类型默认值为 0，默认取值范围为 [0, 3]。
• string 类型默认值为 options 数组第一个元素。

PipelineStates

以下为 PipelineStates 相关参数，所有参数不区分大小写。

Migrations

一般情况下，在使用材质资源时都希望底层的 effect 接口能始终向前兼容，但有时面对新的需求最好的解决方案依然是含有一定 breaking change 的，这时为了保持项目中已有的材质资源数据不受影响，或者至少能够更平滑地升级，就可以使用 effect 的迁移系统。

在 effect 导入成功后会 立即更新工程内所有 依赖于此 effect 的材质资源，对每个材质资源，会尝试寻找所有指定的旧参数数据（包括 property 和 宏定义 两类），然后将其复制或迁移到新属性中。

注意：使用迁移功能前请一定先备份好项目工程，以免丢失数据！

对于一个现有的 effect，迁移字段声明如下：

migrations:
  # macros: # macros follows the same rule as properties, without the component-wise features
  # USE_MIAN_TEXTURE: { formerlySerializedAs: USE_MAIN_TEXTURE }
  properties:
    newFloat: { formerlySerializedAs: oldVec4.w }

对于一个依赖于这个 effect，并在对应 pass 中持有属性的材质：

{
  "oldVec4": {
    "__type__": "cc.Vec4",
    "x": 1,
    "y": 1,
    "z": 1,
    "w": 0.5
  }
}

在 effect 导入成功后，这些数据会被立即转换成：

{
  "oldVec4": {
    "__type__": "cc.Vec4",
    "x": 1,
    "y": 1,
    "z": 1,
    "w": 0.5
  },
  "newFloat": 0.5
}

在 编辑器 内重新编辑并保存这个材质资源后会变成（假设 effect 和 property 数据本身并没有改变）：

{
  "newFloat": 0.5
}

当然如果希望在导入时就直接删除旧数据，可以再加一条迁移信息来专门指定这点：

oldVec4: { removeImmediately: true }

这对于在项目有大量旧材质，又能够确定这个属性的数据已经完全冗余时会比较有用。

更多地，注意这里的通道指令只是简单的取 w 分量，事实上还可以做任意的 shuffle：

newColor: { formerlySerializedAs: someOldColor.yxx }

甚至基于某个宏定义：

occlusion: { formerlySerializedAs: pbrParams.<OCCLUSION_CHANNEL|z> }

这里声明了新的 occlusion 属性会从旧的 pbrParams 中获取，而具体的分量取决于 OCCLUSION_CHANNEL 宏定义。并且如果材质资源中未定义这个宏，则默认取 z 通道。
但如果某个材质在迁移升级前就已经存着 newFloat 字段的数据，则不会对其做任何修改，除非指定为强制更新模式：

newFloat: { formerlySerializedAs: oldVec4.w! }

强制更新模式会强制更新所有材质的属性，无论这个操作是否会覆盖数据。

注意：强制更新操作会在编辑器的每次资源事件中都执行（几乎对应每一次鼠标点击，相对高频），因此只是一个快速测试和调试的手段，一定不要将处于强制更新模式的 effect 提交到版本控制。

再次总结一下为防止数据丢失所设置的相关规则：

• 为避免有效旧数据丢失，只要没有显式指定 removeImmediately 规则，就不会在导入时自动删除旧数据；
• 为避免有效的新数据被覆盖，如果没有指定为强制更新模式，对于那些既有旧数据，又有对应的新数据的材质，不会做任何迁移操作。

RasterizerState

DepthStencilState

BlendState

Targets