Lighting

Related reference: Scene API / Lighting

The advanced Web API lets you read the default lights and also create new light objects at runtime.

Get the Default Lights

Default Ambient Light

const ambient = await api.getDefaultAmbientLight();

Default Directional Lights

const left = await api.getDefaultDirectionalLightLeft();
const right = await api.getDefaultDirectionalLightRight();

These defaults are built-in scene light handles and are a good place for lightweight adjustments.

Create New Lights

Ambient Light

const ambient = await api.createAmbientLight('#ffffff', 1.2);
await api.add(ambient);

Directional Light

const directional = await api.createDirectionalLight('#ffffff', 2);
await api.add(directional);

Read Light Color and Intensity

// Floating-point numbers in the [0-1] range. Multiply by 255 for 8-bit RGB.
const [r, g, b] = await api.getLightColor(directional);
const intensity = await api.getLightIntensity(directional);

Update Light Color and Intensity

await api.setLightColor(directional, '#ffd27f');
await api.setLightIntensity(directional, 1.5);

Directional Light Targets

A directional light also has a target object that controls the lighting direction:

const target = await api.getDirectionalLightTarget(directional);
await api.setPosition(target, 0, 0, 0);

Recommended Usage

Adjust the Default Lights First

If you only want to make a model slightly brighter, cooler, or warmer, start by changing the default lights.

Add New Lights Only When Necessary

Adding lights at runtime is flexible, but it also increases debugging complexity and performance cost. Too many lights will hurt performance significantly.

Pairing with Models

Lighting usually needs to be tuned together with:

• glTF Models
• Environment Maps
• Tone Mapping

In PBR model scenes, these three usually need to be adjusted as a set.