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