Documentation / scene / CubemapSHProjector

Class: CubemapSHProjector

Defined in: libs/scene/src/utility/shprojector.ts:34

CubemapSHProjector is responsible for projecting a cubemap texture into spherical harmonics (SH) coefficients. This is commonly used for efficient environment lighting approximation in real-time rendering.

The class uses Monte Carlo sampling to compute the first 9 spherical harmonics coefficients (up to order 2) from a cubemap texture, which can then be used for ambient lighting calculations.

Example

const projector = new CubemapSHProjector(10000);
const shBuffer = device.createBuffer(4 * 4 * 9, { usage: 'uniform' });
projector.projectCubemap(environmentCubemap, shBuffer);
// shBuffer now contains the 9 SH coefficients as RGB values
projector.dispose();

Extends

• Disposable

Constructors

Constructor

new CubemapSHProjector(numSamples?): CubemapSHProjector

Defined in: libs/scene/src/utility/shprojector.ts:48

Creates a new CubemapSHProjector instance.

Parameters

numSamples?

number = 10000

Number of Monte Carlo samples to use for SH projection. Higher values provide better accuracy but slower computation. Default is 10000.

Returns

CubemapSHProjector

Overrides

Disposable.constructor

Accessors

disposed

Get Signature

get disposed(): boolean

Defined in: libs/base/dist/index.d.ts:6065

Returns

boolean

Inherited from

Disposable.disposed

Methods

on()

on<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:594

IEventTarget.on

Type Parameters

K

K extends "dispose"

Parameters

type

K

listener

EventListener<{ dispose: []; }, K>

context?

unknown

Returns

void

Inherited from

Disposable.on

---

once()

once<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:598

IEventTarget.once

Type Parameters

K

K extends "dispose"

Parameters

type

K

listener

EventListener<{ dispose: []; }, K>

context?

unknown

Returns

void

Inherited from

Disposable.once

---

off()

off<K>(type, listener?, context?): void

Defined in: libs/base/dist/index.d.ts:602

IEventTarget.off

Type Parameters

K

K extends "dispose"

Parameters

type

K

listener?

EventListener<{ dispose: []; }>

context?

unknown

Returns

void

Inherited from

Disposable.off

---

dispatchEvent()

dispatchEvent<K>(type, ...args): void

Defined in: libs/base/dist/index.d.ts:606

IEventTarget.dispatchEvent

Type Parameters

K

K extends "dispose"

Parameters

type

K

args

...object[K]

Returns

void

Inherited from

Disposable.dispatchEvent

---

dispose()

dispose(): void

Defined in: libs/base/dist/index.d.ts:6066

Returns

void

Inherited from

Disposable.dispose

---

projectCubemap()

projectCubemap(cubemap, outBuffer, radianceSource?): void

Defined in: libs/scene/src/utility/shprojector.ts:74

Projects a cubemap texture into spherical harmonics coefficients and stores them in a GPUBuffer.

The method performs Monte Carlo integration over the sphere to compute the first 9 SH coefficients. The results are written to a 3x3 render target where each pixel contains RGB values for one SH coefficient. The layout is:

• (0,0): Y₀₀ (0,1): Y₁₋₁ (0,2): Y₁₀
• (1,0): Y₁₁ (1,1): Y₂₋₂ (1,2): Y₂₋₁
• (2,0): Y₂₀ (2,1): Y₂₁ (2,2): Y₂₂

Parameters

cubemap

TextureCube

The input cubemap texture to project

outBuffer

GPUDataBuffer

GPU data buffer to receive the computed SH coefficients. Must be large enough to hold 9 RGB values (36 floats for RGBA32F format).

radianceSource?

boolean = true

Returns

void

Example

const shBuffer = device.createDataBuffer(9 * 4 * 4); // 9 coefficients * 4 components * 4 bytes
projector.projectCubemap(environmentMap, shBuffer);

---

projectCubemapToTexture()

projectCubemapToTexture(cubemap, framebuffer, radianceSource?): void

Defined in: libs/scene/src/utility/shprojector.ts:98

Projects a cubemap texture into spherical harmonics coefficients and stores them in a 3x3 texture.

The method performs Monte Carlo integration over the sphere to compute the first 9 SH coefficients. The results are written to a 3x3 render target where each pixel contains RGB values for one SH coefficient. The layout is:

• (0,0): Y₀₀ (0,1): Y₁₋₁ (0,2): Y₁₀
• (1,0): Y₁₁ (1,1): Y₂₋₂ (1,2): Y₂₋₁
• (2,0): Y₂₀ (2,1): Y₂₁ (2,2): Y₂₂

Parameters

cubemap

TextureCube

The input cubemap texture to project

framebuffer

FrameBuffer

radianceSource?

boolean = true

Returns

void

Example

const shTexture = device.createTexture2D('rgba32f', 3, 3); // 9 coefficients * 4 components * 4 bytes
const shFramebuffer = device.createFrameBuffer([shTexture], null);
projector.projectCubemapToTexture(environmentMap, shFramebuffer);

---

onDispose()

protected onDispose(): void

Defined in: libs/scene/src/utility/shprojector.ts:118

Disposes of all resources allocated by this projector instance. Should be called when the projector is no longer needed to prevent memory leaks.

Returns

void

Overrides

Disposable.onDispose