Replaceable Built-in Functions in Surface Shader

Surface Shader has unified the shading process and provides a loft custom functions to users. You can use the macro mechanism to rewrite related functions according to your needs.

1. Principle

The custom functions provided by Surface Shader have a default version internally and are called at the right time. You can refer to Surface Shader Execution Flow.

These functions are usually named in the way of Surfaces+Shader+ShaderTypeName+Modify+Attribute, such as.

  • SurfacesVertexModifyLocalPos
  • SurfacesVertexModifyLocalNormal
  • SurfacesVertexModifyLocalTangent

All functions can be viewed at internal/chunks/surfaces/default-functions/.

If you want to replace the implementation of a function, you can do so by pre-defining the macro corresponding to that function..

For example, you can pre-define the CC_SURFACES_VERTEX_MODIFY_WORLD_POS macro, so that Surface Shader can use your defined function to calculate the world position. The sample code is as follows.

#define CC_SURFACES_VERTEX_MODIFY_WORLD_POS
vec3 SurfacesVertexModifyWorldPos(in SurfacesStandardVertexIntermediate In)
{
  vec3 worldPos = In.worldPos;
  worldPos.x += sin(cc_time.x * worldPos.z);
  worldPos.y += cos(cc_time.x * worldPos.z);
  return worldPos;
}

If you are not familiar with the function replacement mechanism in Surface Shader, you can first refer to Function Replacement Using Macros.

The advantage of this method is that it can easily extend a variety of different material data structures, lighting models, and render usages, and does not need to modify the built-in Surface Shader code.

2. Common Replaceable Functions for VS

The replaceable functions for vs are defined in the internal/chunks/surfaces/default-functions/common-vs.chunk file.

The built-in functions for vs all have the SurfacesStandardVertexIntermediate structure as parameter, which stores the data of vs inputs and outputs. Shader writers don't need to worry about the specific vertex input and output processing, they just need to focus on the modification of certain data.

Macro Function Material Type Description
CC_SURFACES_VERTEX_MODIFY_LOCAL_POS vec3 SurfacesVertexModifyLocalPos Common Used to modify local position
CC_SURFACES_VERTEX_MODIFY_LOCAL_NORMAL vec3 SurfacesVertexModifyLocalNormal Common Used to modify local normal
CC_SURFACES_VERTEX_MODIFY_LOCAL_TANGENT vec4 SurfacesVertexModifyLocalTangent Common Used to modify local tangent and mirror normal marker
CC_SURFACES_VERTEX_MODIFY_LOCAL_SHARED_DATA void SurfacesVertexModifyLocalSharedData Common If some textures and calculations need to be used in multiple material nodes, they can be performed in this function, called before world transformation, directly modifying the three local parameters inside the SurfaceStandardVertexIntermediate structure.
CC_SURFACES_VERTEX_MODIFY_WORLD_POS vec3 SurfacesVertexModifyWorldPos Common Used to modify world position.
CC_SURFACES_VERTEX_MODIFY_CLIP_POS vec4 SurfacesVertexModifyClipPos Common Used to modify position in clip space (projected position)
CC_SURFACES_VERTEX_MODIFY_UV void SurfacesVertexModifyUV Common Used to modify uv coordinates
CC_SURFACES_VERTEX_MODIFY_WORLD_NORMAL vec3 SurfacesVertexModifyWorldNormal Common Used to modify world normal
CCSURFACES_VERTEX_MODIFY SHARED_DATA void SurfacesVertexModify SharedData Common If some textures and calculations need to be used in multiple material nodes, they can be performed in this function, directly modifying the parameters inside the SurfaceStandardVertexIntermediate structure, reducing performance consumption

3. Common Replaceable Functions for FS

The replaceable functions for FS are composed of PBR and Toon, which are located in the following two files.

  • internal/chunks/surfaces/default-functions/standard-fs.chunk
  • internal/chunks/surfaces/default-functions/toon-vs.chunk

Most of the replaceable functions for FS don't have parameter. Shader writers need to process them in combination with FS Inputs. For some special-purpose functions, corresponding parameters are also provided. For which situation they belong to, please refer to the function definition.

Macro Function Material Type Description
CCSURFACES_FRAGMENT_MODIFY BASECOLOR_AND_TRANSPARENCY vec4 SurfacesFragmentModify BaseColorAndTransparency Common Used to modify the base color, including alpha channel
CC_SURFACES_FRAGMENT_ALPHA_CLIP_ONLY vec4 SurfacesFragmentModify AlphaClipOnly Common Used to process alpha test
CCSURFACES_FRAGMENT_MODIFY WORLD_NORMAL vec3 SurfacesFragmentModify WorldNormal Common Used to modify world normal
CCSURFACES_FRAGMENT_MODIFY SHARED_DATA void SurfacesFragmentModify SharedData Common If some textures and calculations need to be used in multiple material nodes, they can be performed in this function, directly modifying the parameters inside the Surface structure, reducing performance consumption, similar to the surf() function in legacy shader. Necessary header files need to be included before defining the function
CCSURFACES_FRAGMENT_MODIFY WORLD_TANGENT_AND_BINORMAL void SurfacesFragmentModify WorldTangentAndBinormal Standard PBR Used modify world tangent
CCSURFACES_FRAGMENT_MODIFY EMISSIVE vec3 SurfacesFragmentModify Emissive Standard PBR Used to modify emissive
CCSURFACES_FRAGMENT_MODIFY PBRPARAMS vec4 SurfacesFragmentModify PBRParams Standard PBR Used to modify PBR parameters vec4(ao, roughness, metallic, specularIntensity)
CCSURFACES_FRAGMENT_MODIFY ANISOTROPY_PARAMS vec4 SurfacesFragmentModify AnisotropyParams Standard PBR Used to modify anisotropy-related parameters vec4(rotation, shape, unused, unused)
CCSURFACES_FRAGMENT_MODIFY BASECOLOR_AND_TOONSHADE void SurfacesFragmentModify BaseColorAndToonShade Toon Used to modify the base color and toon shade
CCSURFACES_FRAGMENT_MODIFY TOON_STEP_AND_FEATHER vec4 SurfacesFragmentModify ToonStepAndFeather Toon Used to modify step and feather
CCSURFACES_FRAGMENT_MODIFY TOON_SHADOW_COVER vec4 SurfacesFragmentModify ToonShadowCover Toon Used to modify toon shadow cover
CCSURFACES_FRAGMENT_MODIFY TOON_SPECULAR vec4 SurfacesFragmentModify ToonSpecular Toon Used to modify toon specular
CC_SURFACES_LIGHTING_MODIFY_FINAL_RESULT void SurfacesLightingModifyFinalResult Common Custom lighting model, can modify the previously calculated lighting result, such as adding outline light, necessary header files need to be included before defining the function.

results matching ""

    No results matching ""