Cocos Creator 3.1 Material Upgrade Guide

This article will detail the considerations for upgrading Cocos Creator 3.0 materials to v3.1.

1. Shader upgrades and changes

1.1 Built-in header file changes

The standard shader header shading-standard from v3.0 has become standard-surface-entry from v3.1, making the effect compatible with both the forward render pipeline and the deferred render pipeline.

The cc-fog header file from v3.0 is now cc-fog-vs/fs from v3.1, split into vertex shader and fragment shader versions.

1.2 Vertex shaders

  • gl_Position

    The main function name of VS in v3.1 has been changed from vert to main, and a new macro gl_Position has been added to assign a value to the return value.

    1.   CCProgram standard-vs %{
    2.       precision highp float;  
    4.       // Include your headfile
    6.       #include <cc-fog-vs> // Note the change in the header file name here
    8.       // Fill in your data here
    10.       void main () {
    12.           // Fill in your data here
    14.           gl_Position = fill in your data result;
    15.       }
    16.   }%

1.3 Fragment shaders

  • CC_STANDARD_SURFACE_ENTRY()

    Load the standard shader header file standard-surface-entry and use the v3.1 standard shader output function CC_STANDARD_SURFACE_ENTRY() to replace the original v3.0 shader output function frag().

    1.   CCProgram standard-fs %{
    3.       // Include your headfile
    5.       #include <cc-fog-fs> // Note the change in the header file name here
    6.       #include <standard-surface-entry> // Note the change in the name of the standard shader header file here
    8.       // Fill in your data here
    10.       void surf (out StandardSurface s) {
    12.           // Fill in your data here
    14.       }
    15.       CC_STANDARD_SURFACE_ENTRY() // Standard shader output function
    16.   }%

2. Deferred Render Pipeline

2.1 Deferred Render Pipeline

The biggest difference between v3.1 and v3.0 is that v3.1 supports the deferred render pipeline. The engine comes with a standard standard-surface-entry header file that supports both the forward render pipeline and the deferred render pipeline, which is used as follows:

  1. CCEffect %{
  2.     techniques:
  4.     // Fill in your data here
  6.         - &deferred
  7.         vert: // your Vertex shader
  8.         frag: // your Fragment shader
  9.         phase: deferred
  10.         propertyIndex: 0
  11.         blendState:
  12.             targets: // turn off blending
  13.             - blend: false
  14.             - blend: false
  15.             - blend: false
  16.             - blend: false
  17.             properties: // your properties name
  19.     // Fill in your data here
  21. }%
  23. // fill in your data here
  25. CCProgram standard-fs %{
  26.     precision highp float;
  27.     #include <cc-global>
  28.     #include <shared-ubos>
  29.     #include <cc-fog-fs> // Note the change in the header file name here.
  30.     #include <standard-surface-entry> // Note the change in the name of the standard shader header file here
  32.     // Fill in your data here
  33.     void surf (out StandardSurface s) {
  35.         // Fill in your data here
  37.     }
  38.     CC_STANDARD_SURFACE_ENTRY() // Standard shader output function
  39. }%
  41. // fill in your data here

2.2 Render pipeline determination

The header file standard-surface-entry determines which render pipeline is selected, and the lighting calculation is in the file shading-standard-additive.

If it is a deferred render pipeline, the deferred-lighting effect file is called first, followed by the light calculation file shading-standard-additive.

  1. #define CC_STANDARD_SURFACE_ENTRY()                                 
  2. #if CC_FORWARD_ADD                                                 
  3.   #include <shading-standard-additive>
  5.   // Fill in your data here
  7. #elif CC_PIPELINE_TYPE == CC_PIPELINE_TYPE_FORWARD  // Determine if it is the forward render pipeline
  9.   // Fill in your data here
  11. #elif CC_PIPELINE_TYPE == CC_PIPELINE_TYPE_DEFERRED  // Determine if it is the deferred render pipeline
  13.  // Fill in your data here
  15. #endif

3. Parameter transfer upgrade

The macro for passing shadow parameters from vertex shaders to fragment shaders was originally CCPassShadowParams in v3.0, but was changed to CC_TRANSFER_SHADOW in v3.1.

The v3.1 vertex shader transfers FOG parameters to the fragment shader, using the CC_TRANSFER_FOG macro directly.

Version comparison:

  • v3.0

    1.   v_fog_factor = CC_TRANSFER_FOG(pos);
    2.   CCPassShadowParams(pos);

  • v3.1

    1.   CC_TRANSFER_FOG(pos);
    2.   CC_TRANSFER_SHADOW(pos);