Pass 可配置参数

默认值为加粗项,并可在Effect文件中直接省略。所有参数不区分大小写。

NameOptions
switch*undefined, could be any valid macro name that's not defined in the shader
prioritydefault(128), could be any number between max(255) and min(0)
stagedefault, could be the name of any registered stage in your runtime pipeline
customization[], could be the name of any registered runtime customization
propertysee the following section
primitivepoint_list, line_list, line_strip, line_loop,triangle_list, triangle_strip, triangle_fan,line_list_adjacency, line_strip_adjacency,triangle_list_adjacency, triangle_strip_adjacency,triangle_patch_adjacency, quad_patch_list, iso_line_list
dynamics[], an array containing any of the following:viewport, scissor, line_width, depth_bias, blend_constants,depth_bounds, stencil_write_mask, stencil_compare_mask
rasterizerState.cullModefront, back, none
depthStencilState.depthTesttrue, false
depthStencilState.depthWritetrue, false
depthStencilState.depthFuncnever, less, equal, less_equal, greater, not_equal, greater_equal, always
blendState.targets[i].blendtrue, false
blendState.targets[i].blendEqadd, sub, rev_sub
blendState.targets[i].blendSrcone, zero, src_alpha_saturate,src_alpha, one_minus_src_alpha,dst_alpha, one_minus_dst_alpha,src_color, one_minus_src_color,dst_color, one_minus_dst_color,constant_color, one_minus_constant_color,constant_alpha, one_minus_constant_alpha
blendState.targets[i].blendDstone, zero, src_alpha_saturate,src_alpha, one_minus_src_alpha,dst_alpha, one_minus_dst_alpha,src_color, one_minus_src_color,dst_color, one_minus_dst_color,constant_color, one_minus_constant_color,constant_alpha, one_minus_constant_alpha
blendState.targets[i].blendSrcAlphaone, zero, src_alpha_saturate,src_alpha, one_minus_src_alpha,dst_alpha, one_minus_dst_alpha,src_color, one_minus_src_color,dst_color, one_minus_dst_color,constant_color, one_minus_constant_color,constant_alpha, one_minus_constant_alpha
blendState.targets[i].blendDstAlphaone, zero, src_alpha_saturate,src_alpha, one_minus_src_alpha,dst_alpha, one_minus_dst_alpha,src_color, one_minus_src_color,dst_color, one_minus_dst_color,constant_color, one_minus_constant_color,constant_alpha, one_minus_constant_alpha
blendState.targets[i].blendAlphaEqadd, sub, rev_sub
blendState.targets[i].blendColorMaskall, none, r, g, b, a, rg, rb, ra, gb, ga, ba, rgb, rga, rba, gba
blendState.blendColor0 or [0, 0, 0, 0]
depthStencilState.stencilTesttrue, false
depthStencilState.stencilFuncnever, less, equal, less_equal, greater, not_equal, greater_equal, always
depthStencilState.stencilReadMask0xffffffff or [1, 1, 1, 1]
depthStencilState.stencilWriteMask0xffffffff or [1, 1, 1, 1]
depthStencilState.stencilFailOpkeep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert
depthStencilState.stencilZFailOpkeep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert
depthStencilState.stencilPassOpkeep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert
depthStencilState.stencilRef1 or [0, 0, 0, 1]
depthStencilState.stencilFront/Back__set above stencil properties for specific side*

Switch

指定这个 pass 的执行依赖于哪个 define,它不应与使用到的 shader 中定义的任何 define 重名。这个字段默认是不存在的,意味着这个 pass 是无条件执行的。

Priority

指定这个 pass 的渲染优先级,数值越小越优先渲染;default 代表默认优先级 (128),min 代表最小(0),max 代表最大(255),可结合四则运算符指定相对值。

Stage

指定这个 pass 归属于管线的哪个 stage,对 forward 管线,只有 default 一个 stage。

Customization

指定当这个 pass 被应用到场景模型上后执行的自定义回调函数,用于实现显示相关的特殊逻辑需求,可在脚本中通过 cc.customizationManager.register 注册。

Properties

properties 存储着这个 Pass 有哪些可定制的参数需要在 Inspector 上显示,这些参数可以是 shader 中的某个 uniform 的完整映射,也可以是具体某个分量的映射 (使用 target 参数):

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

运行时可以这样使用:

  1. // as long as it is a real uniform
  2. // it doesn't matter whether it is specified in the property list or not
  3. mat.setProperty('emissive', cc.Color.GREY); // this works
  4. mat.setProperty('albedo', cc.Color.RED); // direct set uniform
  5. mat.setProperty('roughness', 0.2); // set certain component
  6. const h = mat.passes[0].getHandle('offset'); // or just take the handle,
  7. mat.passes[0].setUniform(h, new Vec2(0.5, 0.5)); // and use Pass.setUniform interface instead

未指定的 uniform 将由引擎在运行时根据自动分析出的数据类型给予默认初值

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

  1. properties:
  2. __metadata__: { inspector: { visible: false } }
  3. a: { value: [1, 1, 0, 0] }
  4. b: { inspector: { type: color } }
  5. c: { inspector: { visible: true } }

这样 uniform a 和 b 已声明的各项参数都不受影响,但全部不会显示在 inspector 上(visible 为 false),而 uniform c 还会正常显示。

数据迁移升级:formerlySerializedAs

当指定了 inspector.deprecated 时,工程内所有材质资源内的对应属性数据,在下一次编辑保存这个材质时会被自动剔除掉。当指定了 inspector.formerlySerializedAs 时,在 effect 导入成功后会 立即更新工程内所有 依赖于此 effect 的材质资源,尝试寻找所有指定旧参数数据,复制或重组到新属性名下。这个过程不会删除旧数据,但是会将旧属性标为 deprecated。如果一个材质资源内既有旧数据,又有新数据,则不会做任何迁移(强制更新模式除外)。

对于一个现有 effect,修改它的某个属性为:

  1. width: { value: 1, inspector: { formerlySerializedAs: shapeParam.x } }

对于一个依赖于这个 effect,并持有这样的属性的材质:

  1. {
  2. "shapeParam": {
  3. "__type__": "cc.Vec4",
  4. "x": 3,
  5. "y": 1,
  6. "z": 0,
  7. "w": 0
  8. }
  9. }

在 effect 重新导入后,这些数据会被立即转换成:

  1. {
  2. "shapeParam": {
  3. "__type__": "cc.Vec4",
  4. "x": 3,
  5. "y": 1,
  6. "z": 0,
  7. "w": 0
  8. },
  9. "width": 3
  10. }

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

  1. {
  2. "width": 3
  3. }

但如果某个材质在迁移升级前就已经存着 width 数据,则不会对其做任何修改,除非指定为强制更新模式:

  1. width: { value: 1, inspector: { formerlySerializedAs: shapeParam.x! } }

这会强制更新所有材质的属性,无论这个操作是否会覆盖数据。注意强制更新操作会在编辑器的每次资源事件中都执行(几乎对应每一次鼠标点击,相对高频),因此只是一个快速测试和调试的手段,一定不要将处于强制更新模式的 effect 提交版本控制。

Property Param List

同样地,任何可配置字段如与默认值相同都可以省掉。| Param | Options ||:————————————-:|:——————————————————:|| target | undefined, (any valid uniform components, no random swizzle) || value | _see the next section || sampler.minFilter | none, point, linear, anisotropic || sampler.magFilter | none, point, linear, anisotropic || sampler.mipFilter | none, point, linear, anisotropic || sampler.addressU | wrap, mirror, clamp, border || sampler.addressV | wrap, mirror, clamp, border || sampler.addressW | wrap, mirror, clamp, border || sampler.maxAnisotropy | 16 || sampler.cmpFunc | never, less, equal, lessequal, greater, not_equal, greater_equal, always || sampler.borderColor | [0, 0, 0, 0] || sampler.minLOD | 0 || sampler.maxLOD | 0, remember to override this when enabling mip filter_ || sampler.mipLODBias | 0 || inspector.displayName | (any string), _property name || inspector.type | vector, color || inspector.visible | true, false || inspector.tooltip | (any string), **property name || inspector.range | undefined, [ min, max, [step] ] || inspector.deprecated | true, false || inspector.formerlySerializedAs | undefined**, (any valid uniform components, random swizzle allowed) |

Default Values

TypeDefault Value / Options
int0
ivec2[0, 0]
ivec3[0, 0, 0]
ivec4[0, 0, 0, 0]
float0
vec2[0, 0]
vec3[0, 0, 0]
vec4[0, 0, 0, 0]
sampler2Dblack, grey, white, normal, default
samplerCubeblack-cube, white-cube, default-cube

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