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.

      CCProgram standard-vs %{
          precision highp float;  
    
          // Include your headfile
    
          #include <cc-fog-vs> // Note the change in the header file name here
    
          // Fill in your data here
    
          void main () {
    
              // Fill in your data here
    
              gl_Position = fill in your data result;
          }
      }%
    

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().

      CCProgram standard-fs %{
    
          // Include your headfile
    
          #include <cc-fog-fs> // Note the change in the header file name here
          #include <standard-surface-entry> // Note the change in the name of the standard shader header file here
    
          // Fill in your data here
    
          void surf (out StandardSurface s) {
    
              // Fill in your data here
    
          }
          CC_STANDARD_SURFACE_ENTRY() // Standard shader output function
      }%
    

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:

CCEffect %{
    techniques:

    // Fill in your data here

        - &deferred
        vert: // your Vertex shader
        frag: // your Fragment shader
        phase: deferred
        propertyIndex: 0
        blendState:
            targets: // turn off blending
            - blend: false
            - blend: false
            - blend: false
            - blend: false
            properties: // your properties name

    // Fill in your data here

}%

// fill in your data here

CCProgram standard-fs %{
    precision highp float;
    #include <cc-global>
    #include <shared-ubos>
    #include <cc-fog-fs> // Note the change in the header file name here.
    #include <standard-surface-entry> // Note the change in the name of the standard shader header file here

    // Fill in your data here
    void surf (out StandardSurface s) {

        // Fill in your data here

    }
    CC_STANDARD_SURFACE_ENTRY() // Standard shader output function
}%

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

#define CC_STANDARD_SURFACE_ENTRY()                                 
#if CC_FORWARD_ADD                                                 
  #include <shading-standard-additive>

  // Fill in your data here

#elif CC_PIPELINE_TYPE == CC_PIPELINE_TYPE_FORWARD  // Determine if it is the forward render pipeline

  // Fill in your data here

#elif CC_PIPELINE_TYPE == CC_PIPELINE_TYPE_DEFERRED  // Determine if it is the deferred render pipeline

 // Fill in your data here

#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

      v_fog_factor = CC_TRANSFER_FOG(pos);
      CCPassShadowParams(pos);
    
  • v3.1

      CC_TRANSFER_FOG(pos);
      CC_TRANSFER_SHADOW(pos);
    

results matching ""

    No results matching ""