Chapter 124: LightProbeGrid

Core Idea

A 3D grid of L2 Spherical Harmonic irradiance probes that provides position-dependent diffuse global illumination.

Note that this class can only be used with WebGLRenderer. A version for WebGPURenderer will be added at a later point.

All seven packed SH sub-volumes are stored in a single RGBA WebGL3DRenderTarget using a texture-atlas layout along the Z axis. Each sub-volume occupies ( nz + 2 ) atlas slices: one padding slice at each end (a copy of the nearest edge data slice) to prevent color bleeding when the hardware trilinear filter reads across a sub-volume boundary.

Atlas layout (nz = resolution.z, PADDING = 1):

Total atlas depth = 7 * ( nz + 2 ).

Baking is fully GPU-resident: cubemap rendering, SH projection, and texture packing all happen on the GPU with zero CPU readback.

Key Concepts

• boundingBox : Box3: The world-space bounding box for the grid. Updated automatically by LightProbeGrid#bake.
• depth : number: The full depth of the volume along Z.
• height : number: The full height of the volume along Y.
• isLightProbeGrid : boolean (readonly): This flag can be used for type testing.
• resolution : Vector3: The number of probes along each axis.
• texture : Data3DTexture: The single RGBA atlas 3D texture storing all seven packed SH sub-volumes.
• width : number: The full width of the volume along X.

Code Examples

slice   0              : padding  (copy of sub-volume 0, data slice 0)
  slices  1 … nz         : sub-volume 0 data
  slice   nz + 1         : padding  (copy of sub-volume 0, data slice nz-1)
  slice   nz + 2         : padding  (copy of sub-volume 1, data slice 0)
  slices  nz+3 … 2*nz+2  : sub-volume 1 data
  …

• What it demonstrates: Typical usage of LightProbeGrid.

Reference Tables

Constructor

Signature
new LightProbeGrid( width : number, height : number, depth : number, widthProbes : number, heightProbes : number, depthProbes : number )

Properties

Property	Description
.boundingBox : Box3	The world-space bounding box for the grid. Updated automatically by LightProbeGrid#bake.
.depth : number	The full depth of the volume along Z.
.height : number	The full height of the volume along Y.
.isLightProbeGrid : boolean (readonly)	This flag can be used for type testing.
.resolution : Vector3	The number of probes along each axis.
.texture : Data3DTexture	The single RGBA atlas 3D texture storing all seven packed SH sub-volumes.
.width : number	The full width of the volume along X.

Methods

Method	Description
.bake( renderer : WebGLRenderer, scene : Scene, options : Object )	Bakes all probes by rendering cubemaps at each probe position and projecting to L2 SH. Optionally iterates additional passes to capture indirect bounces — each extra pass samples the previous pass's …
.dispose()	Frees GPU resources.
.getProbePosition( ix : number, iy : number, iz : number, target : Vector3 ) : Vector3	Returns the world-space position of the probe at grid indices (ix, iy, iz).
.updateBoundingBox()	Updates the world-space bounding box from the current position and size.

Key Takeaways

1. Most relevant properties: boundingBox, depth, height, isLightProbeGrid.
2. Key methods: bake, dispose, getProbePosition, updateBoundingBox.

Connects To

• Source: examples/jsm/lighting/LightProbeGrid.js