Material & Shader System

All materials extend Material. It defines the GPU rendering state: blending, depth, stencil, culling.

Appearance

Blending

Depth Buffer

Hooks

Three.js doesn't write monolithic GLSL files. Instead it composes shaders from small named chunks using #include <chunk_name> directives.

// Simplified excerpt: MeshStandardMaterial vertex shader
#include <common>
#include <uv_pars_vertex>
#include <normal_pars_vertex>
#include <shadowmap_pars_vertex>

void main() {
  #include <uv_vertex>
  #include <beginnormal_vertex>
  #include <defaultnormal_vertex>
  #include <begin_vertex>
  #include <project_vertex>       // ← clips position to screen
  #include <shadowmap_vertex>
}

Each chunk is a string stored in ShaderChunk.js. The renderer replaces #include directives with the chunk source before compilation.

Why This Design?

Chunks let onBeforeCompile hooks surgically inject code:

material.onBeforeCompile = ( shader ) => {
  // Add a custom uniform
  shader.uniforms.myTime = { value: 0 };

  // Inject code into a specific chunk's slot
  shader.vertexShader = shader.vertexShader.replace(
    '#include <begin_vertex>',
    `
    #include <begin_vertex>
    // Vertex displacement using wave
    transformed.y += sin( position.x * 5.0 + myTime ) * 0.1;
    `
  );
};

// Update the uniform each frame
material.userData.shader = null;
material.onBeforeCompile = ( shader ) => {
  material.userData.shader = shader;
};
// In animate():
if ( material.userData.shader ) {
  material.userData.shader.uniforms.myTime.value = performance.now() / 1000;
}

Three.js never compiles duplicate programs. The cache key encodes every factor that changes shader code:

This means adding a single point light causes all materials to recompile (one-time cost, then cached). The cache survives across frames but is per-scene and per-camera-depth-level.

Uniforms are variables that are constant for a single draw call but can change between draws. Three.js uploads them via the WebGLUniforms system.

// For MeshStandardMaterial, three.js sends ~40+ uniforms automatically:
//   Matrices:
//     modelMatrix, viewMatrix, projectionMatrix, normalMatrix
//   Material appearance:
//     diffuse (color), roughness, metalness, opacity
//   Textures (each bound to a texture unit):
//     map, roughnessMap, metalnessMap, normalMap, aoMap, ...
//   Lighting (from RenderState):
//     ambientLightColor
//     directionalLights[N] { direction, color }
//     directionalLightShadows[N] { shadowBias, shadowMapSize, ... }
//     directionalShadowMap[N]  (sampler2D)
//     directionalShadowMatrix[N] (mat4)
//     pointLights[N], spotLights[N], ...
//   Environment:
//     envMap (samplerCube), envMapIntensity
//   Fog:
//     fogColor, fogNear, fogFar (or fogDensity for FogExp2)

Custom Uniforms in ShaderMaterial

const material = new THREE.ShaderMaterial({
  uniforms: {
    time:  { value: 0.0 },
    color: { value: new THREE.Color( 0xff0000 ) },
    tex:   { value: new THREE.TextureLoader().load('img.png') },
  },
  vertexShader: `
    uniform float time;
    void main() {
      vec3 pos = position;
      pos.y += sin( pos.x + time ) * 0.1;
      gl_Position = projectionMatrix * modelViewMatrix * vec4( pos, 1.0 );
    }
  `,
  fragmentShader: `
    uniform vec3 color;
    void main() {
      gl_FragColor = vec4( color, 1.0 );
    }
  `,
});

// Animate:
function animate( t ) {
  material.uniforms.time.value = t / 1000;
  renderer.render( scene, camera );
}

• LearnOpenGL — Basic Lighting
• LearnOpenGL — PBR Theory
• Three.js Docs — ShaderMaterial

• Khronos — GLSL Shader Objects — compile/link lifecycle
• WebGL Fundamentals — Shaders and GLSL
• LearnOpenGL — Blending
• Three.js Docs — MeshStandardMaterial
• src/renderers/shaders/ShaderLib.js — built-in shader entry points
• src/renderers/shaders/ShaderChunk.js — all chunk names & sources