Optional Pass Parameters

The parameters in Pass are mainly divided into two parts:

  • Developer-customizable Inspector panel parameter properties.
  • PipelineStates provided by the engine to control the rendering pipeline state.

Properties

properties is used to alias the uniform defined in the shader. This mapping can be a complete mapping of a uniform, or a mapping of a specific component (using the target parameter), the code example is as follows:

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

By default, property parameters defined in properties are exposed and displayed in the Inspector panel of the editor for easy visual control.

If you don't want to show the properties on the Inspector panel, you can add editor: { visible: false } when defining the property, the code example is as follows:

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

In TypeScript, you can use the setProperty method of the Material class and the setUniform method of Pass to set pass properties, the code example is as follows:

mat.setProperty('emissive', Color.GREY); // Directly set the corresponding ‘Uniform’ variable
mat.setProperty('albedo', Color.RED); 
mat.setProperty('roughness', 0.2); // Set only the corresponding component
const h = mat.passes[0].getHandle('offset'); // Get the handle of the corresponding Uniform
mat.passes[0].setUniform(h, new Vec2(0.5, 0.5)); // Use 'Pass.setUniform' to set the Uniform property

Note: uniform defined in Effect can also be set using the above code, even if not defined in properties.

If uniform is not specified, Engine will give a default value at runtime based on the automatically parsed data type. For more information on default values, please refer to the description below.

In order to conveniently declare each property sub-property, you can directly declare the __metadata__ item in properties, and all property will inherit its declared content, such as:

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

In this way, the declared parameters of uniform a and b will not be affected, but will not be displayed in the Inspector (visible is false), and uniform c will still be displayed normally .

Property parameter list

The configurable parameters in Property are shown in the table below. Any configurable fields can be omitted if they are the same as the default values.

parameter default value option remark
target undefined undefined Any valid uniform channel, which can specify a single or multiple consecutive channels, but cannot be randomly rearranged
value See the introduction in the Default Values section below
sampler.
minFilter
linear none, point, linear, anisotropic
sampler.
magFilter
linear none, point, linear, anisotropic
sampler.
mipFilter
none none, point, linear, anisotropic
sampler.
addressU
wrap wrap, mirror, clamp, border
sampler.
addressV
wrap wrap, mirror, clamp, border
sampler.
addressW
wrap wrap, mirror, clamp, border
sampler.
maxAnisotropy
16 16
sampler.
cmpFunc
never never, less, equal, less_equal, greater, not_equal, greater_equal, always
sampler.
borderColor
[0, 0, 0, 0] [0, 0, 0, 0]
sampler.
minLOD
0 0
sampler.
maxLOD
0 0 If mipmap is allowed, the maximum mip value should be modified according to the map
sampler.
mipLODBias
0 0
editor.
displayName
*property name *property name any string
editor.
type
vector vector, color
editor.
visible
true true, false
editor.
tooltip
*property name *property name any string
editor.
range
undefined undefined, [ min, max, [step] ]
editor.
deprecated
false true, false Data marked deprecated means that it was updated when imported or deprecated in the current version, and its contents are automatically deleted when saved

Property default value

For the default value of Property, Cocos Effect makes the following provisions:

types default values optional items
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 default black, grey, white, normal, default
samplerCube default-cube black-cube, white-cube, default-cube

For defines, there are the following provisions:

  • boolean: The default value of boolean type is false.
  • number: The default value of the number type is 0, and the default value range is [0, 3].
  • string: The default value of type string is the first element of the options array.

PipelineStates

The following are PipelineStates related parameters, all parameters are case insensitive.

parameter description default value remark
switch Specifies which define the execution of this pass depends on. Can be any valid macro name, but should not have the same name as any define defined in the shader used undefined This field does not exist by default, meaning this pass is executed unconditionally
priority Specify the rendering priority of this pass. The smaller the value, the higher the rendering priority. The value range is 0 ~ 255 128 The relative value can be specified in combination with four operators
stage Specifies which stage of the pipeline this pass belongs to. Can be any registered stage name in the runtime pipeline default For the default forward pipeline, there is only one stage default
phase Specifies which phase of the pipeline this pass belongs to. Can be any registered Phase name in the runtime pipeline default For the default forward pipeline, can be default, forward-add or shadow-caster
propertyIndex Specify which pass the uniform attribute data of this pass runtime should be consistent with. For example, the pass such as forward add needs to be consistent with the base pass to ensure the correct rendering effect. Can be any valid pass index undefined Once this parameter is specified, no further properties for this pass will be displayed on the material panel
embeddedMacros Specifies a constant macro that is additionally defined on the basis of the shader of this pass, which can be an object containing any macro key-value pair undefined This parameter can be used to reuse shader resources in multiple passes only when the macro definitions are different
properties Properties stores the customizable parameters of this pass that need to be displayed on the Inspector See the Properties section above for details
migrations Migrate old material data See the introduction in the Migrations section below for detail
primitive Create material vertex data triangle_list Options include: 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
RasterizerState Optional render state when rasterizing See the introduction in the RasterizerState section below
DepthStencilState Testing and Status of Depth and Stencil Caches See the introduction of the DepthStencilState section below
BlendState Material blend state false See the introduction in the BlendState section below

Migrations

In general, when using material system, it is hoped that the underlying effect interface will always be forward compatible, but sometimes the best solution for new requirements still contains certain breaking changes. The material resource data is not affected, or at least can be updated more smoothly, using the effect's migration system.

After the effect is imported successfully, it will immediately update all the material resources in the project that depend on this effect. For each material asset, it will try to find all the specified old parameter data (including property and macro definitions) and then copy or migrate it into the new property.

Note: Please back up the project before using the migration function to avoid data loss!

For an existing effect, the migration field is declared as follows:

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

For a material that depends on this effect and holds properties in the corresponding pass:

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

Immediately after the effect is imported, the data is converted into:

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

After re-editing and saving this material asset in the editor it will become (assuming the effect and property data themselves have not changed):

{
  "newFloat": 0.5
}

Of course, if you want to delete the old data directly when importing, you can add a migration message to specify this:

oldVec4: { removeImmediately: true }

This can be useful when the project has a lot of old materials and you can be sure that the data for this property is completely redundant.

Further, note that the channel instruction here simply takes the w component, and in fact can do arbitrary shuffles:

newColor: { formerlySerializedAs: someOldColor.yxx }

Even based on a certain macro definition:

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

It is declared here that the new occlusion property is taken from the old pbrParams, and the exact component depends on the OCCLUSION_CHANNEL macro definition. And if this macro is not defined in the material resource, the z channel will be taken by default.
However, if a material already has data in the newFloat field before the migration upgrade, no changes will be made to it, unless forced update mode is specified.

newFloat: { formerlySerializedAs: oldVec4.w! }

The forced update mode forces the properties of all materials to be updated, regardless of whether this operation overwrites the data.

Note: The force update operation is performed on every resource event of the editor (corresponding to almost every mouse click, relatively high frequency), so it is just a means for quick testing and debugging, be sure not to submit the effect in force update mode to version control.

To again summarize the relevant rules set to prevent data loss.

  • To avoid loss of valid old data, old data will not be automatically deleted on import, as long as the removeImmediately rule is not explicitly specified.
  • To avoid valid new data being overwritten, no migration operation will be done for materials that have both old data and corresponding new data if they are not specified as forced update mode.

RasterizerState

Parameter Name Description Default Optional
isDiscard Engine Reserved false true, false
polygonMode Polygon drawing mode fill point,line,fill
shadeModel Shading model flat flat, gourand
cullMode Culling mode on rasterization back front, back, none
isFrontFaceCCW Counterclockwise (CCW) forward or not true true,false
depthBias Depth bias 0
depthBiasSlop Slope of depth deviation 0
depthBiasClamp Depth bias clamp 0
isDepthClip Allows depth clipping operations.
Work only on Vulkan
true true, false
isMultisample Whether to enable multisampling false true, false
lineWidth line 1

DepthStencilState

Parameter Name Description Default Optional
depthTest Whether to open the depth test true true,false
depthWrite Whether to enable deep buffer writing true true, false
depthFunc Depth buffer comparison function less never, less, equal, less_equal, greater, not_equal, greater_equal, always
stencilTestFront Whether to enable the front stencil buffer test false true, false
stencilFuncFront Front stencil comparison function always never, less, equal, less_equal, greater, not_equal, greater_equal, always
stencilReadMaskFront Front stencil read mask 0xffffffff 0xffffffff, [1, 1, 1, 1]
stencilWriteMaskFront Front stencil write mask 0xffffffff 0xffffffff, [1, 1, 1, 1]
stencilFailOpFront How to handle buffer values when front stencil buffer test fails keep keep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert
stencilZFailOpFront How to handle buffer values when front stencil buffer depth test fails keep keep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert
stencilPassOpFront How to handle the buffer values when the stencil buffer test passes keep keep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert
stencilRefFront The comparison function in the front stencil buffer is used to compare the values 1 1, [0, 0, 0, 1]
stencilTestBack Whether to open the back stencil buffer test false true, false
stencilFuncBack Back stencil buffer comparison function always never, less, equal, less_equal, greater, not_equal, greater_equal, always
stencilReadMaskBack Back stencil buffer read mask 0xffffffff 0xffffffff, [1, 1, 1, 1]
stencilWriteMaskBack Back stencil buffer write mask 0xffffffff 0xffffffff, [1, 1, 1, 1]
stencilFailOpBack How to handle the buffer value when the back stencil buffer test fails keep keep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert
stencilZFailOpBack How to handle the buffer value when the back stencil buffer depth test fails keep keep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert
stencilRefBack The values used for comparison by the compare function in the back stencil buffer 1 1, [0, 0, 0, 1]

BlendState

Parameter Name Description Default Optional
isA2C Whether to enable translucent anti-aliasing (Alpha To Coverage) false true, false
isIndepend whether RGB and Alpha are blended separately false true, false
blendColor Specifies the blend color 0 0, [0, 0, 0, 0]
targets Blending configuration, please refer to Targets below []

Targets

Parameter Name Description Default Optional
Targets[i].
blend
Whether to enable Blend false true, false
Targets[i].
blendEq
Specify the blend function for RGB for blend source and blend destination add add, sub, rev_sub
Targets[i].
blendSrc
Specifies the RGB blend factor of the blend source. one 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
Targets[i].
blendDst
Specifies the RGB blend factor for the blend destination. zero 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
Targets[i].
blendSrcAlpha
Specifies the alpha blend factor of the blend source. one 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
Targets[i].
blendDstAlpha
Specify the alpha blend factor for the blend destination zero 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
Targets[i].
blendAlphaEq
Specifies the alpha blending function for blend source and blend destination add add, sub, rev_sub
Targets[i].
blendColorMask
Specifies whether the RGB, Alpha component can be written to the frame buffer all all, none, r, g, b, a, rg, rb, ra, gb, ga, ba, rgb, rga, rba, gba
dynamics Dynamically updatable pipeline status [] LINE_WIDTH, DEPTH_BIAS, BLEND_CONSTANTS, DEPTH_BOUNDS, STENCIL_WRITE_MASK, STENCIL_COMPARE_MASK

results matching ""

    No results matching ""