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.

Property default value

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

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.

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_MIAN_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

DepthStencilState

BlendState

Targets