Skip to content

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.

glsl
#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.

MacroFunctionMaterial TypeDescription
CC_SURFACES_VERTEX_MODIFY_LOCAL_POSvec3 SurfacesVertexModifyLocalPosCommonUsed to modify local position
CC_SURFACES_VERTEX_MODIFY_LOCAL_NORMALvec3 SurfacesVertexModifyLocalNormalCommonUsed to modify local normal
CC_SURFACES_VERTEX_MODIFY_LOCAL_TANGENTvec4 SurfacesVertexModifyLocalTangentCommonUsed to modify local tangent and mirror normal marker
CC_SURFACES_VERTEX_MODIFY_LOCAL_SHARED_DATAvoid SurfacesVertexModifyLocalSharedDataCommonIf 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_POSvec3 SurfacesVertexModifyWorldPosCommonUsed to modify world position.
CC_SURFACES_VERTEX_MODIFY_CLIP_POSvec4 SurfacesVertexModifyClipPosCommonUsed to modify position in clip space (projected position)
CC_SURFACES_VERTEX_MODIFY_UVvoid SurfacesVertexModifyUVCommonUsed to modify uv coordinates
CC_SURFACES_VERTEX_MODIFY_WORLD_NORMALvec3 SurfacesVertexModifyWorldNormalCommonUsed to modify world normal
CC_SURFACES_VERTEX_MODIFY_ SHARED_DATAvoid SurfacesVertexModify SharedDataCommonIf 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.

MacroFunctionMaterial TypeDescription
CC_SURFACES_FRAGMENT_MODIFY_ BASECOLOR_AND_TRANSPARENCYvec4 SurfacesFragmentModify BaseColorAndTransparencyCommonUsed to modify the base color, including alpha channel
CC_SURFACES_FRAGMENT_ALPHA_CLIP_ONLYvec4 SurfacesFragmentModify AlphaClipOnlyCommonUsed to process alpha test
CC_SURFACES_FRAGMENT_MODIFY_ WORLD_NORMALvec3 SurfacesFragmentModify WorldNormalCommonUsed to modify world normal
CC_SURFACES_FRAGMENT_MODIFY_ SHARED_DATAvoid SurfacesFragmentModify SharedDataCommonIf 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
CC_SURFACES_FRAGMENT_MODIFY_ WORLD_TANGENT_AND_BINORMALvoid SurfacesFragmentModify WorldTangentAndBinormalStandard PBRUsed modify world tangent
CC_SURFACES_FRAGMENT_MODIFY_ EMISSIVEvec3 SurfacesFragmentModify EmissiveStandard PBRUsed to modify emissive
CC_SURFACES_FRAGMENT_MODIFY_ PBRPARAMSvec4 SurfacesFragmentModify PBRParamsStandard PBRUsed to modify PBR parameters vec4(ao, roughness, metallic, specularIntensity)
CC_SURFACES_FRAGMENT_MODIFY_ ANISOTROPY_PARAMSvec4 SurfacesFragmentModify AnisotropyParamsStandard PBRUsed to modify anisotropy-related parameters vec4(rotation, shape, unused, unused)
CC_SURFACES_FRAGMENT_MODIFY_ BASECOLOR_AND_TOONSHADEvoid SurfacesFragmentModify BaseColorAndToonShadeToonUsed to modify the base color and toon shade
CC_SURFACES_FRAGMENT_MODIFY_ TOON_STEP_AND_FEATHERvec4 SurfacesFragmentModify ToonStepAndFeatherToonUsed to modify step and feather
CC_SURFACES_FRAGMENT_MODIFY_ TOON_SHADOW_COVERvec4 SurfacesFragmentModify ToonShadowCoverToonUsed to modify toon shadow cover
CC_SURFACES_FRAGMENT_MODIFY_ TOON_SPECULARvec4 SurfacesFragmentModify ToonSpecularToonUsed to modify toon specular
CC_SURFACES_LIGHTING_MODIFY_FINAL_RESULTvoid SurfacesLightingModifyFinalResultCommonCustom 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.