Skip to content

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:

yaml
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:

yaml
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:

js
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:

yaml
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.

parameterdefault valueoptionremark
targetundefinedundefinedAny valid uniform channel, which can specify a single or multiple consecutive channels, but cannot be randomly rearranged
valueSee the introduction in the Default Values section below
sampler.
minFilter
linearnone, point, linear, anisotropic
sampler.
magFilter
linearnone, point, linear, anisotropic
sampler.
mipFilter
nonenone, point, linear, anisotropic
sampler.
addressU
wrapwrap, mirror, clamp, border
sampler.
addressV
wrapwrap, mirror, clamp, border
sampler.
addressW
wrapwrap, mirror, clamp, border
sampler.
maxAnisotropy
1616
sampler.
cmpFunc
nevernever, less, equal, less_equal, greater, not_equal, greater_equal, always
sampler.
borderColor
[0, 0, 0, 0][0, 0, 0, 0]
sampler.
minLOD
00
sampler.
maxLOD
00If mipmap is allowed, the maximum mip value should be modified according to the map
sampler.
mipLODBias
00
editor.
displayName
*property name*property nameany string
editor.
type
vectorvector, color
editor.
visible
truetrue, false
editor.
tooltip
*property name*property nameany string
editor.
range
undefinedundefined, [ min, max, [step] ]
editor.
deprecated
falsetrue, falseData 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:

typesdefault valuesoptional items
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]
sampler2Ddefaultblack, grey, white, normal, default
samplerCubedefault-cubeblack-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.

parameterdescriptiondefault valueremark
switchSpecifies 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 usedundefinedThis field does not exist by default, meaning this pass is executed unconditionally
prioritySpecify the rendering priority of this pass. The smaller the value, the higher the rendering priority. The value range is 0 ~ 255128The relative value can be specified in combination with four operators
stageSpecifies which stage of the pipeline this pass belongs to. Can be any registered stage name in the runtime pipelinedefaultFor the default forward pipeline, there is only one stage default
phaseSpecifies which phase of the pipeline this pass belongs to. Can be any registered Phase name in the runtime pipelinedefaultFor the default forward pipeline, can be default, forward-add or shadow-caster
propertyIndexSpecify 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 indexundefinedOnce this parameter is specified, no further properties for this pass will be displayed on the material panel
embeddedMacrosSpecifies 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 pairundefinedThis parameter can be used to reuse shader resources in multiple passes only when the macro definitions are different
propertiesProperties stores the customizable parameters of this pass that need to be displayed on the InspectorSee the Properties section above for details
migrationsMigrate old material dataSee the introduction in the Migrations section below for detail
primitiveCreate material vertex datatriangle_listOptions 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
RasterizerStateOptional render state when rasterizingSee the introduction in the RasterizerState section below
DepthStencilStateTesting and Status of Depth and Stencil CachesSee the introduction of the DepthStencilState section below
BlendStateMaterial blend statefalseSee 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:

yaml
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:

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

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

json
{
  "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):

json
{
  "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:

yaml
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:

yaml
newColor: { formerlySerializedAs: someOldColor.yxx }

Even based on a certain macro definition:

yaml
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.

yaml
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 NameDescriptionDefaultOptional
isDiscardEngine Reservedfalsetrue, false
polygonModePolygon drawing modefillpoint,line,fill
shadeModelShading modelflatflat, gourand
cullModeCulling mode on rasterizationbackfront, back, none
isFrontFaceCCWCounterclockwise (CCW) forward or nottruetrue,false
depthBiasDepth bias0
depthBiasSlopSlope of depth deviation0
depthBiasClampDepth bias clamp0
isDepthClipAllows depth clipping operations.
Work only on Vulkan
truetrue, false
isMultisampleWhether to enable multisamplingfalsetrue, false
lineWidthline1

DepthStencilState

Parameter NameDescriptionDefaultOptional
depthTestWhether to open the depth testtruetrue,false
depthWriteWhether to enable deep buffer writingtruetrue, false
depthFuncDepth buffer comparison functionlessnever, less, equal, less_equal, greater, not_equal, greater_equal, always
stencilTestFrontWhether to enable the front stencil buffer testfalsetrue, false
stencilFuncFrontFront stencil comparison functionalwaysnever, less, equal, less_equal, greater, not_equal, greater_equal, always
stencilReadMaskFrontFront stencil read mask0xffffffff0xffffffff, [1, 1, 1, 1]
stencilWriteMaskFrontFront stencil write mask0xffffffff0xffffffff, [1, 1, 1, 1]
stencilFailOpFrontHow to handle buffer values when front stencil buffer test failskeepkeep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert
stencilZFailOpFrontHow to handle buffer values when front stencil buffer depth test failskeepkeep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert
stencilPassOpFrontHow to handle the buffer values when the stencil buffer test passeskeepkeep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert
stencilRefFrontThe comparison function in the front stencil buffer is used to compare the values11, [0, 0, 0, 1]
stencilTestBackWhether to open the back stencil buffer testfalsetrue, false
stencilFuncBackBack stencil buffer comparison functionalwaysnever, less, equal, less_equal, greater, not_equal, greater_equal, always
stencilReadMaskBackBack stencil buffer read mask0xffffffff0xffffffff, [1, 1, 1, 1]
stencilWriteMaskBackBack stencil buffer write mask0xffffffff0xffffffff, [1, 1, 1, 1]
stencilFailOpBackHow to handle the buffer value when the back stencil buffer test failskeepkeep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert
stencilZFailOpBackHow to handle the buffer value when the back stencil buffer depth test failskeepkeep, zero, replace, incr, incr_wrap, decr, decr_wrap, invert
stencilRefBackThe values used for comparison by the compare function in the back stencil buffer11, [0, 0, 0, 1]

BlendState

Parameter NameDescriptionDefaultOptional
isA2CWhether to enable translucent anti-aliasing (Alpha To Coverage)falsetrue, false
isIndependwhether RGB and Alpha are blended separatelyfalsetrue, false
blendColorSpecifies the blend color00, [0, 0, 0, 0]
targetsBlending configuration, please refer to Targets below[]

Targets

Parameter NameDescriptionDefaultOptional
Targets[i].
blend
Whether to enable Blendfalsetrue, false
Targets[i].
blendEq
Specify the blend function for RGB for blend source and blend destinationaddadd, sub, rev_sub
Targets[i].
blendSrc
Specifies the RGB blend factor of the blend source.oneone, 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.zeroone, 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.oneone, 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 destinationzeroone, 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 destinationaddadd, sub, rev_sub
Targets[i].
blendColorMask
Specifies whether the RGB, Alpha component can be written to the frame bufferallall, none, r, g, b, a, rg, rb, ra, gb, ga, ba, rgb, rga, rba, gba
dynamicsDynamically updatable pipeline status[]LINE_WIDTH, DEPTH_BIAS, BLEND_CONSTANTS, DEPTH_BOUNDS, STENCIL_WRITE_MASK, STENCIL_COMPARE_MASK