Optional Pass Parameters
Default value is in bold, all parameters are case-insensitive.
Name | Options |
---|---|
switch | *undefined, could be any valid macro name that's not defined in the shader |
priority | default(128), could be any number between max(255) and min(0) |
stage | default, could be the name of any registered stage in your runtime pipeline |
customization | [], could be the name of any registered runtime customization |
properties | *see the following section |
migrations | *see the following section |
primitive | point_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. cullMode |
front, back, none |
depthStencilState. depthTest |
true, false |
depthStencilState. depthWrite |
true, false |
depthStencilState. depthFunc |
never, less, equal, less_equal, greater, not_equal, greater_equal, always |
blendState.targets[i]. blend |
true, false |
blendState.targets[i]. blendEq |
add, sub, rev_sub |
blendState.targets[i]. blendSrc |
one, 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]. blendDst |
one, 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]. blendSrcAlpha |
one, 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]. blendDstAlpha |
one, 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]. blendAlphaEq |
add, sub, rev_sub |
blendState.targets[i]. blendColorMask |
all, none, r, g, b, a, rg, rb, ra, gb, ga, ba, rgb, rga, rba, gba |
blendState. blendColor |
0 or [0, 0, 0, 0] |
depthStencilState. stencilTest |
true, false |
depthStencilState. stencilFunc |
never, less, equal, less_equal, greater, not_equal, greater_equal, always |
depthStencilState. stencilReadMask |
0xffffffff or [1, 1, 1, 1] |
depthStencilState. stencilWriteMask |
0xffffffff or [1, 1, 1, 1] |
depthStencilState. stencilFailOp |
keep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert |
depthStencilState. stencilZFailOp |
keep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert |
depthStencilState. stencilPassOp |
keep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert |
depthStencilState. stencilRef |
1 or [0, 0, 0, 1] |
depthStencilState. stencil*Front/Back |
\set above stencil properties for specific side* |
Switch
Specifies a power switch for the current pass, if not enabled, the pass with be skipped completely.
the macro name shouldn't collide with any existing macros inside the shader.
This property doesn't exist by default, which means the pass is executed unconditionally.
Priority
Specifies the rendering priority of the current pass, the bigger the number, the lower the priority;
default is (128), min is (0), max is (255), arithmetic operations between these constants and integer constants are supported.
Stage
Specifies which render stage the current pass belongs to.
Customization
Specifies the callback functions when the material is attached to/detached from model.
Callbacks can be registered by cc.customizationManager.register
.
Properties
Specifies the public interfaces exposed to material instector and runtime API.
It can be a direct mapping to shader uniforms, or specific channels of the uniform:
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
Runtime reference is straightforward:
// as long as it is a real uniform
// it doesn't matter whether it is specified in the property list or not
mat.setProperty('emissive', cc.Color.GREY); // this works
mat.setProperty('albedo', cc.Color.RED); // directly set uniform
mat.setProperty('roughness', 0.2); // set certain component
const h = mat.passes[0].getHandle('offset'); // or just take the handle,
mat.passes[0].setUniform(h, new Vec2(0.5, 0.5)); // and use Pass.setUniform interface instead
Shader uniforms that are not in the properties
list will be given a default value.
For quick setup and experiment, the __metadata__
feature is provided, which will be the 'base class' for all other properties:
properties:
__metadata__: { editor: { visible: false } }
a: { value: [1, 1, 0, 0] }
b: { editor: { type: color } }
c: { editor: { visible: true } }
Here a
and b
will no longer appear in the inspector, while c
stays visible.
Migrations
Ideally the public interface of an effect should always be backward-compatible,
but occasionally introducing breaking changes might become the only option as the project iterate.
A smooth data transition would be much desired during the process, which leads to the migration system:
After an effect with migrations is successfully compiled, all the dependent material assets will be immediately updated,
new property will be automatically generated from existing data using specified rules.
The migration process will not delete any data, and if the new data is visible in inspector, flag the source data as deprecated
.
If the new property already exists, no migration will be performed to prevent accidental data override. (except in force mode)
For a existing effect, declares the following migration rules:
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 }
Say we have a dependent material, with the following data:
{
"oldVec4": {
"__type__": "cc.Vec4",
"x": 1,
"y": 1,
"z": 1,
"w": 0.5
}
}
After the effect is compiled, the material will be automatically updated to:
{
"oldVec4": {
"__type__": "cc.Vec4",
"x": 1,
"y": 1,
"z": 1,
"w": 0.5
},
"newFloat": 0.5
}
And after the next save operation on this material: (say the content is actually not changed)
{
"newFloat": 0.5
}
We are just using the w
channel here, while in fact arbitrary shuffle is supported too:
newColor: { formerlySerializedAs: someOldColor.yxx }
Or even based on a target macro:
occlusion: { formerlySerializedAs: pbrParams.<OCCLUSION_CHANNEL|z> }
This means the new occlusion
data will be extracted from pbrParams
data,
the specific channel depend on the OCCLUSION_CHANNEL
macro of current pass,
and default to channel z
if macro data not present.
If newFloat
property already exists before migration, nothing will happen, unless in force mode:
newFloat: { formerlySerializedAs: oldVec4.w! }
Then the migration is guaranteed to execute, regardless of the existing data.
Note: Migration in force mode will execute in every database event, which is basically every mouse click in editor. So use it as a quick-and-dirty test measure, and be sure not to submit effect files with force mode migrations into version control.
Property Parameter List
All parameters are optional, with its default value in bold.
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, less_equal, 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 |
editor | \see the next section* |
editor. displayName |
(any string), *property name |
editor. type |
vector, color |
editor. visible |
true, false |
editor. tooltip |
(any string), *property name |
editor. range |
undefined, [ min, max, [step] ] |
editor. deprecated |
true, false, \for any material using this effect, delete the existing data for this property after next saving* |
Default Values
Type | Default Value / Options |
---|---|
int | 0 |
ivec2 | [0, 0] |
ivec3 | [0, 0, 0] |
ivec4 | [0, 0, 0, 0] |
float | 0 |
vec2 | [0, 0] |
vec3 | [0, 0, 0] |
vec4 | [0, 0, 0, 0] |
sampler2D | black, grey, white, normal, default |
samplerCube | black-cube, white-cube, default-cube |
For macros:
Macros with explicit tag declaration default to the first element of the tag parameter.
All other macros default to 0.