three.js Documentation: 3D Graphics, TSL, and WebGPU

TSL is an approach to productive and maintainable shader creation designed to replace manual GLSL manipulation (like .onBeforeCompile()) with a node-based system.

Key benefits include:

• Renderer Agnostic: TSL can encode code into different outputs such as WGSL (for WebGPU) or GLSL (for WebGL2).
• Automatic Optimization: The system automatically optimizes the shader graph and ensures that shared calculations (e.g., positionWorld, normalWorld) are only performed once.
• Tree Shaking: Material complexity can be imported into different modules and tree-shaken without breaking the shader process.
• Order Independence: You do not need to worry about the sequence in which components are created; the Node System manages declarations and inclusions.

The extension provides the following debugging capabilities:

• Scene Hierarchy Visualization: A tree view to browse the complete scene graph.
• Object Inspection: View basic properties of objects, such as type and name.
• Renderer Details: A collapsible section showing properties, render statistics, and memory usage for WebGLRenderer instances.

A UniformsGroup is a class used to manage multiple uniforms within a single group. When used with a ShaderMaterial, the WebGLRenderer processes the group as a single Uniform Buffer Object (UBO).

Key constraints:

• It can only be used in the context of ShaderMaterial.
• It is only supported by WebGLRenderer.

FlipNode is a core module within the Three.js Shading Language (TSL) used during the shader generation process. It represents a mathematical flip operation where normalized values are inverted using the formula x = 1 - x.

Note: This module is part of the TSL core and is typically used internally. End-users should generally not use FlipNode directly in application-level code. Instead, use the high-level convenience methods provided on node objects, such as flipXYZW(), flipRGBA(), or flipSTPQ().

// Instead of using FlipNode directly, use convenience methods:
uvNode = uvNode.flipY();

A Vector2 class represents a 2D vector, which is an ordered pair of numbers (x, y). In three.js, it is commonly used to represent:

• A point in 2D space: A position on a plane.
• A direction and length: The direction is measured from (0, 0) towards (x, y), and the length is the Euclidean distance from (0, 0) to (x, y).
• Arbitrary pairs: Any ordered pair of numbers (e.g., for momentum or complex numbers).

Iterating through a Vector2 instance yields its components (x, y) in order.

const a = new THREE.Vector2( 0, 1 );
//no arguments; will be initialised to (0, 0)
const b = new THREE.Vector2( );
const d = a.distanceTo( b );

An InterleavedBuffer is used when multiple attributes (such as position, normal, uv, and color) are packed into a single, shared TypedArray instead of having separate buffers for each attribute. This is often done to improve memory locality and performance.

To use it, you must define a stride, which is the number of typed-array elements that represent a single vertex's worth of data.

A ShadowMesh is a specialized mesh that follows a shadow-casting mesh in the scene but is confined to a single plane.

Use Case: It serves as a highly performant alternative to classic shadow mapping when you only need shadows on flat surfaces.

Limitations:

• Shadows can only be cast onto flat planes.
• It does not support soft shadows.

const cubeShadow = new ShadowMesh( cube );
scene.add( cubeShadow );

A SplitNode is a core TSL (Three Shading Language) module used to represent property access operations on node objects. It is primarily used to implement component access such as .xyzw, .rgba, or .stpq.

While it is a fundamental part of the TSL core, it is typically used by the engine rather than in high-level application code. It allows you to extract specific channels from a multi-component node (like a color or a vector).

// Example of the logic SplitNode implements:
const redValue = color.r;

A LightProbe is an alternative way to add light to a 3D scene. Unlike classical light sources (directional, point, or spot lights) that emit light from a specific origin, light probes do not emit light. Instead, they store information about light passing through 3D space.

During rendering, the light hitting a 3D object is approximated using the data stored in the probe. In the current three.js implementation, LightProbe supports diffuse light probes, which are functionally equivalent to an irradiance environment map. This is commonly used to make objects react to environment lighting, such as data provided by WebXR for augmented reality.

A Frustum represents the volume of space within a camera's field of view. It is primarily used to optimize rendering performance by performing visibility testing: objects located outside the frustum can be excluded from the rendering pipeline to save processing power.

Common use cases include:

• Determining if a point is visible to the camera.
• Checking if a bounding box (Box3), sphere (Sphere), or sprite (Sprite) intersects the camera's view.
• Checking if a Object3D is visible (based on its bounding sphere).