Lighting

kit.lighting

module

Creates lighting with a sun, sky and fog.

lighting.create(root, { points?, shadow?, pointShadow?, … }?) → Lighting

rootborrows

the root

points?takes

point lights from a table or a 'use gpu' function. Every lit point visits each slot up to the table's highest live one, or count with a function, unless candidates names the slots that may reach it

shadow?takes

the sun's shadow, with a depth pass per cascade

pointShadow?takes

shadows that cast gives to lights of points.table, with a depth pass per face

Lightingreturns

lighting you destroy

GPU functions

cone

schemas

LightSpotSettingsSpan

constants

defaultsWHITE

helpers

MovingPointLightMovingSpotLightPointLightSpotLightWHITE_SPOT

types

ShadingLightTableTablePointsLightPointsSpotPointsCandidatesPointLightsMovingPointLightsSpotLightsMovingSpotLightsLightingLightingOf

Optionscreate · 5 fields

settings?

Partial<d.InferInput<typeof Settings>>= defaults, which has no fog

Sets initial sun, sky and fog values over defaults.

shading?

Shading= pbr, hemisphere, heightFog, filtered and reaching

Sets the functions that shading.shade calls.

points?

PointsOptions= none

Enables point lights from a table or a function.

shadow?

ShadowOptions= none

Enables and configures the shadow from the sun.

pointShadow?

PointShadowOptions= none

Gives up to count point or spot lights a shadow each, which light.pointShadow.cast assigns.

PointsOptionspoints in create · 5 fields

table?

LightTable= none, lights from light or spot

Supplies a table of lighting.PointLight, MovingPointLight, SpotLight or MovingSpotLight.

candidates?

Candidates= every live slot

Limits the loop to lights that may reach each shaded point.

light?

(slot: number) => Light= none, lights from table or spot

Returns the light at a slot.

spot?

(slot: number) => Spot= none, lights from table or light

Returns the spot light at a slot, whose cone comes from lighting.cone.

count?

number= none, the slots candidates names

Sets how many slots, from 0, every lit point visits.

ShadowOptionsshadow in create · 13 fields

extent?

number= 20

Sets the width of the square covered by the map in world units.

center?

Vec3= the origin

Centres the square here at first.

eye?

CpuView= none, a fixed map

Fits the map to this camera's view, in cascades layers that reach far from the eye.

cascades?

1 | 2 | 3 | 4= 1

Splits the view into 1 to 4 cascades, each a layer of the map drawn in a pass of its own.

far?

number= 50

Sets how far from the eye the cascades reach, in world units.

splits?

readonly number[]= (k / cascades)² after cascade k, 0.11 and 0.44 for three

Places the splits between cascades as fractions of far, cascades - 1 rising values between 0 and 1.

size?

number= 2048

Sets the width and height of each layer of the map in texels.

reach?

number= twice the extent, or far with an eye

Sets how far the map reaches towards the sun in world units: from the point it follows, or beyond each cascade with an eye.

filter?

1 | 4 | 9= 4

Sets the number of comparisons per shaded point to 1, 4 or 9.

format?

'depth16unorm' | 'depth24plus' | 'depth32float'= 'depth16unorm'

Sets the depth format of the map.

bias?

{ readonly constant?: number; readonly slope?: number }= { constant: 2, slope: 2 }

Offsets depth written by caster pipelines to prevent self-shadowing.

lift?

number= 1

Moves a shaded point along its normal before comparison, in texels.

enabled?

() => boolean= always

Controls whether record draws the shadow in the current frame.

PointShadowOptionspointShadow in create · 7 fields

count?

number= 1

Sets how many lights can cast a shadow at once, each with six layers of the map.

size?

number= 512

Sets the width and height of each layer in texels.

filter?

1 | 4 | 9= 4

Sets the number of comparisons per shaded point to 1, 4 or 9.

format?

'depth16unorm' | 'depth24plus' | 'depth32float'= 'depth16unorm'

Sets the depth format of the map.

bias?

{ readonly constant?: number; readonly slope?: number }= { constant: 2, slope: 2 }

Offsets depth written by caster pipelines to prevent self-shadowing.

lift?

number= 1

Moves a shaded point along its normal before comparison, in texels at its distance from the light.

enabled?

() => boolean= always

Controls whether record draws the shadows in the current frame.

records

• shadow.record→encoder
• pointShadow.record→encoder

shadow.record and pointShadow.record with what was added to them, before the passes that shade.

owns

1 to 3 buffers ·a sampler ·targets ·a cameras.layered ·passes

The sun, sky and fog; with a shadow, its light space, the views of its cascades, a comparison sampler, the depth array and the passes that draw it; with pointShadow, the same for the lights' faces.

lifecycle

✓destroy()✓[Symbol.dispose]

injects

• hook

  The shading hooks its options name: reflect, ambient, fog, sunShadow and attenuation.

• definition

  The sun, sky and fog, the shadows and the point lights, which shading reads.

binds

• 1 uniform

  shading.shade, the sun, sky and fog.

• 2 storage · 1 uniform

  shading.shade with a table of point lights.

• 3 storage · 1 uniform

  shading.shade with a table of lights whose positions are on the device, the table's two parts.

• 1 uniform

  shading.shade with points.light or points.spot, plus what the function binds.

• none

  shading.shade with points.candidates, plus what their functions bind, 2 storage for a neighbour grid's range and slot.

• 1 uniform

  shading.shade with a shadow, the sun's light space and cascades, beside the depth array and its comparison sampler.

• 1 uniform

  shading.shade with pointShadow, each shadow's light, layers and views, beside their depth array and the comparison sampler.

used by

AfterimageBlockfallCenserClassroomCloisterDomino runFireworksFish tankForestHex isleKineticNight marketQuiver treesRobot armSkeletonsSPH SculptSpiderStampedeSurvey model

• matte
• glossy
• metal
• glow

pbrlambert

roughness

0.35

sun

-40

°

Lower roughness to shrink and brighten highlights. Select lambert to remove highlights and give even metals diffuse lighting.

Copying a light loop into each fragment shader duplicates work. Capturing lights as constants creates pipelines when lights move or are added. Store the sun, sky, fog and point lights as data in a lighting. Fill it into each pipeline and call shading.shade(material, point).

import { lighting, materials, shading, table } from '@typegpu/kit';

const lamps = table.create(root, lighting.PointLight, {
  capacity: 16,
  defaults: { ...lighting.WHITE },
});
lamps.add({ position: [1.5, 1, 1], color: [1, 0.6, 0.3], intensity: 3, range: 5 });
const light = lighting.create(root, {
  settings: { sunDirection: [0.4, 1, 0.3], sunIntensity: 2 },
  points: { table: lamps },
});

const fragment = tgpu.fragmentFn({
  in: { world: d.vec3f, normal: d.vec3f },
  out: d.vec4f,
})(({ world, normal }) => {
  'use gpu';
  const brick = materials.glossy(d.vec3f(0.62, 0.24, 0.16), 0.4);
  return d.vec4f(shading.shade(brick, shading.pointAt(world, normal)), 1);
});

const pipeline = root
  .pipe(view.inject())
  .pipe(light.inject())
  .createRenderPipeline({ vertex, fragment, targets: { format: 'rgba16float' } });

frames.animate(
  frames.create(root, (frame) => {
    lamps.flush(); // uploads lamps changed since the last frame
    // Record passes here
  }),
);

• shade sums ambient sky light, sunlight past its shadow, live point lights and emission, and applies fog last. The result is linear and can exceed 1 for bloom and tone mapping. Every channel stays at or below 65 504, the largest half float.
• shading.pointAt reads the kit’s cameras.current to find the direction toward the eye. Fill the camera into the pipeline too.
• A lighting without a shadow or point lights holds only its settings uniform, so shading a surface of your own, such as a raymarched field, takes one small buffer.
• Light from a panorama or a sky goes through the ambient hook as an environment. Supply other baked or changing light through it too. See Light from textures.
• Intensity 1 lights a white matte surface facing the light to about 1, with no exposure, so daylight and lamps share units. Lights omit 1/π; divide intensities from a renderer that keeps it by π.

What a surface is made of

kit.materials

shader

These 'use gpu' functions create materials for shading.shade, with colours or mesh textures.

kind

shader

reads

meshPool

GPU functions

matteglossymetalglowuvOftexturedantialiasedmaskedmappedNormal

used by

BlockfallCenserDomino runFireworksFish tankForestKineticNight marketQuiver treesRobot armSkeletonsSpiderStampedeSurvey model

A material uses glTF’s metallic-roughness model, with linear colour, roughness, metallic factor, emission and occlusion. Presets run on the CPU as well as the GPU.

Preset
matte(color)	Diffuse reflection for chalk, clay and cloth.
glossy(color, roughness)	A dielectric with a highlight, such as paint, plastic or wet stone.
metal(color, roughness)	Tints its reflections and has no diffuse colour.
glow(color, strength)	Gives off strength times color, and reflects almost nothing.

Create a material with shading.Material({ color, roughness, emission, metallic, occlusion }), or copy a preset and change the fields you need:

const ember = (heat: number) => {
  'use gpu';
  const base = materials.matte(d.vec3f(0.3, 0.1, 0.05));
  const lit = shading.Material(base);
  lit.emission = base.emission + d.vec3f(1, 0.4, 0.1) * heat;
  return lit;
};

• Convert screen colours to linear light first with srgbToLinear from @typegpu/color.
• occlusion is the share of ambient light that reaches the surface, from 0 in a crevice to 1 in the open. hemisphere and an environment’s ambient apply it; presets set 1.
• A shading.Point gives the shading position in world space, unit normal and view toward the eye, and uv and uv1 coordinates, the second from a mesh’s uvs1. shading.pointAt(position, normal) normalizes the normal and sets both to zero. An instance’s material function receives mesh UV coordinates.
• Apply model textures with materials.textured, mappedNormal and masked. textured reads occlusion from the red channel of glTF’s occlusion texture. See mesh-pool textures.
• A smooth surface’s highlight can be smaller than a pixel and sparkle as it moves. materials.antialiased(material, normal) widens roughness where the normal turns within a pixel. Kit renderers apply it unless their specularAntialiasing option is false; call it in your own fragment shaders.

Point lights

Pauselights

6

range

4

Change range to set where light falls to zero. Each ball carries a row of a lighting.MovingPointLight table, and one kernel moves balls and lights without CPU position writes.

points reads lights from a table you own or from a function. Without points, the shader has no point-light loop. A table’s fields start at zero, so give it lighting.WHITE as defaults: white, intensity 1 and range 10.

const lamps = table.create(root, lighting.PointLight, {
  capacity: 16,
  defaults: { ...lighting.WHITE },
});
const light = lighting.create(root, { points: { table: lamps } });

const torch = lamps.add({ position: [0, 2, 0], color: [1, 0.55, 0.2], intensity: 4 });
lamps.fields.position.set(torch, 0.5, 2, 0);
lamps.remove(torch);

• Call lamps.flush() each frame before shading. Flush and destroy the table yourself.
• A light falls off with the inverse square of distance, eased to zero at range.
• shading.falloff and shading.beam run on the CPU as well as in shaders, so code outside shaders gets the GPU’s numbers for how much of a light reaches a point, before shadows.

Lights your kernels move

A table of lighting.MovingPointLight keeps positions on the GPU for kernels to write. The balls in the figure use this. Build the kernel from root.pipe(lamps.inject()) and find slots with lamps.slotOf(id).

const { MovingPointLight } = lighting;
const lamps = table.create(root, MovingPointLight, {
  capacity: 64,
  defaults: { ...lighting.WHITE },
});
const light = lighting.create(root, { points: { table: lamps } });

const circle = tgpu.computeFn({ workgroupSize: [64], in: { id: d.builtin.globalInvocationId } })(({
  id,
}) => {
  'use gpu';
  if (id.x >= MovingPointLight.span()) return;
  const angle = time.$ + d.f32(id.x);
  MovingPointLight.device.$[id.x]!.position = d.vec3f(std.cos(angle) * 4, 2, std.sin(angle) * 4);
});
const circling = root.pipe(lamps.inject()).createComputePipeline({ compute: circle });

• A position supplied to add or write overwrites the kernel’s. Colour and intensity updates leave it unchanged.
• The CPU can’t read a moving light’s position back.

Lights a function gives

fireworksEach burst is a point light over a castle reflected in a lake.

PauseOpen the full example

Click the sky to launch a shell, change the rate, or lower burst light. Each flash lights the castle and the smoke, and the lake reflects it; the readout counts live lights.

If another buffer already stores lights, supply points.light, a 'use gpu' function that returns a lighting.Light per slot, and count, the slots to visit. A range of 0 disables a slot. Use pipe to fill its dependencies. These flashes read their particles directly without a table or copy:

const lightOf = (slot: number) => {
  'use gpu';
  const flash = flashes.particle(slot);
  return lighting.Light({
    position: flash.position,
    range: std.select(d.f32(0), 320, flashes.alive(slot)),
    color: flash.color.xyz,
    intensity: std.exp(-flash.age * 3) * flash.size * flash.size,
  });
};
const light = lighting.create(root, {
  points: { light: tgpu.fn(lightOf).pipe(flashes.inject()), count: flashes.span },
});

Particles lit in a kernel, such as smoke beside the flashes, read shading.incoming(position) from a pipeline filled with light.inject(): the sun past its shadow, each point light through attenuation and the mean sky, arriving from every direction. Multiply a colour by it.

To light them by the point lights without the sun, fill shading.sunShadow with 0 on their pipeline alone. The fireworks’ smoke shows only in the bursts’ light this way, while the moon still lights the lake:

const sunless: shading.SunShadowHook = () => {
  'use gpu';
  return d.f32(0);
};

const smoke = particles.create(root, view, {
  capacity: 1024,
  step: sim.step,
  update: tgpu
    .fn((puff: Particle) => {
      'use gpu';
      let next = Particle(puff);
      next.color = d.vec4f(shading.incoming(puff.position) * 0.6, puff.color.w);
      return next;
    })
    .pipe(light.inject())
    .with(shading.sunShadow, sunless),
});

The mean sky still arrives, as skyIntensity sets it.

Only the lights that reach

Every lit pixel visits each light slot: up to a table’s highest live slot, or count slots of a function. Out-of-range lights still cost loads and a distance test, so size tables to the lights you use. If many lights each cover a small area, supply points.candidates to visit only slots that may reach the point.

A neighbour grid with sight at least the longest light range finds nearby lamps in 27 cells:

const lamps = table.create(root, lighting.PointLight, {
  capacity: 64,
  defaults: { ...lighting.WHITE, color: [1, 0.8, 0.6], range: 8 },
});
const rows = lamps.inject();

const cells = grid.create(root, {
  ...lamps.live(),
  low: d.vec3f(-40, 0, -40),
  size: d.vec3f(80, 8, 80),
  sight: 8, // must cover every lamp's range
  item: d.u32,
  position: lighting.PointLight.position.pipe(rows),
  itemOf: (i) => {
    'use gpu';
    return d.u32(i);
  },
});

const light = lighting.create(root, {
  points: { table: lamps, candidates: cells.candidates() },
});

• Each frame, call lamps.flush() and then cells.sort(pass) in a compute pass before shading.
• cells.candidates() returns nine ranges covering the surrounding cells. Its range and slot add two storage buffers to each shading stage.
• Lights beyond sight can be missed. Repeating a slot in candidates adds its light twice.
• Custom candidates supply ranges, a range(position, r) function returning first and count, and slot(index) to map indices to light slots. They also work with a light function. For a single list, return one range with lighting.Span({ first: 0, count }).

Spot lights

A spot light is a point light with a cone. A table of lighting.SpotLight gives every light an aim and a cone, so points and spots share one table, one loop and one candidate list:

import { lighting, table } from '@typegpu/kit';

const lamps = table.create(root, lighting.SpotLight, {
  capacity: 32,
  defaults: { ...lighting.WHITE_SPOT },
});
const light = lighting.create(root, { points: { table: lamps } });

const lamp = lamps.add({
  position: [0, 7, 3],
  aim: [0, -1, -0.4], // any length
  cone: lighting.cone(0.18, 0.24), // inner and outer half-angles in radians
  color: [1, 0.92, 0.8],
  intensity: 60,
  range: 16,
});
lamps.fields.aim.set(lamp, 0.2, -1, -0.4);
lamps.add({ position: [4, 1, 0], intensity: 2 }); // the default cone: a point light

• Light is full inside the inner half-angle and falls to none at the outer one, as in glTF. lighting.cone(inner, outer) stores glTF’s scale and offset, and runs on the CPU and in shaders.
• lighting.WHITE_SPOT aims straight down with the cone [0, 1], which lights every direction.
• The loop reads a light’s aim and cone only once its range test passes.
• lighting.MovingSpotLight moves only the position to the device part.
• points.spot takes a function that returns a lighting.Spot, a Light with aim and cone, beside count or candidates.
• shading.beam(toLight, aim, cone) gives the share of a spot light along toLight, a unit direction from the point towards the light.

Changing the light

light.settings is a lighting.Settings uniform containing sun, sky and fog values. patch uploads supplied fields. A moving sun can update once per frame, and the shadow follows a new sunDirection at its next record:

const direction: [number, number, number] = [Math.cos(t), Math.sin(t), 0.3];

light.settings.patch({
  sunDirection: direction,
  sunColor: [1, 0.7, 0.45],
  fogDensity: 0.04,
  fogFalloff: 0.3,
});

• Shaders normalize the direction and multiply colours by their intensities. Pass slider values directly.
• A zero direction turns the sun off and leaves the shadow where it was.
• environment.sunAt(hour, latitude, declination) gives the sun’s direction at an hour of the day, and environment.sunColor(direction) its colour through the air.
• fogDensity is per world unit at y = 0, and falls by a factor of e per 1 / fogFalloff units of height. A falloff of 0 gives uniform fog. Negative falloff is treated as 0.
• fogStart is the distance from the eye, in world units, where fog begins, so a near island stays clear while the far sea hazes. It is 0 by default.
• skyReflection scales sky reflections in addition to skyIntensity. Values above 1 brighten glass and clear-plastic rims without changing matte surfaces.
• points, shadow, pointShadow and shading are fixed at creation.

Your own shading

kit.shading

shader

These 'use gpu' functions shade surfaces with the lighting injected into their pipeline.

kind

shader

reads

cameraslighting

GPU functions

pointAtsettingstowardsSunfalloffbeambeamOfpbrlambertreflectancespecularOcclusionreflectionOfsurroundedhemispherehazeheightFogreachingsunSharesundirectunfoggedshadeshadeClearincoming

accessors

reflectambientfogsunShadowattenuation

schemas

MaterialPoint

types

ReflectHookAmbientHookFogHookSunShadowHookAttenuationHook

used by

AfterimageBlockfallCenserClassroomCloisterDomino runFireworksForestHex isleKineticNight marketQuiver treesRobot armSkeletonsSolar systemSPH SculptSpiderStampedeSurvey model

shade calls five functions, which the shading options replace:

Slot	Called	Type	Its arguments	Default
shading.reflect	For the sun and each point light	shading.ReflectHook	material, point, direction, radiance	shading.pbr
shading.ambient	Once, for the light from elsewhere	shading.AmbientHook	material, point	shading.hemisphere
shading.fog	Last, on the sum	shading.FogHook	color, point	shading.heightFog
shading.sunShadow	Once, for how much sun reaches	shading.SunShadowHook	point	shadows.filtered
shading.attenuation	For each point light in range	shading.AttenuationHook	point, toLight, distance, range, slot	shading.reaching

• reflect, ambient and fog return linear d.v3f colours. direction is a unit vector toward the light. radiance is colour times intensity and attenuation, with the shadow also applied to the sun.
• sunShadow returns 0 for shadow and 1 for full sunlight. Values above 1 can represent focused light. See your own sun shadow.
• attenuation returns the share of a light’s intensity reaching the point. The loop reads the light’s colour and calls reflect only where it is above 0. reaching multiplies shading.falloff(distance, range), shading.beamOf(toLight, slot) and, where that is above 0, shadows.shadowed(point, toLight, distance, slot). Use slot to read data of your own, such as a flicker per light or a cookie texture.

const toon: shading.ReflectHook = (material, point, direction, radiance) => {
  'use gpu';
  const lit = std.step(0.3, std.dot(point.normal, direction));
  return material.color * radiance * lit;
};

const horizon: shading.FogHook = (color, point) => {
  'use gpu';
  const away = std.saturate(point.view.y * -4 + 0.5);
  const air = std.mix(d.vec3f(0.9, 0.6, 0.4), d.vec3f(0.4, 0.55, 0.8), away);
  return std.mix(color, air, shading.haze(point));
};

const light = lighting.create(root, {
  shading: { reflect: toon, fog: horizon },
  settings: { fogDensity: 0.02, fogFalloff: 0.2 },
});

• shading.haze(point) is how much the lighting’s height fog hides the point, from 0 to 1. heightFog mixes towards fogColor by it; mix towards a colour of your own, as above.
• shading.settings() reads sun, sky and fog values from light.settings. Changing a value needs no new pipeline.
• shading.lambert omits highlights for cheaper shading on phones and flat-shaded art. It tints all reflection with the surface colour, including metals.
• shading.surrounded(material, point, irradiance, reflection) combines diffuse and reflected light for an ambient hook of your own. It applies the material’s occlusion to the reflected light only. See lightmaps.
• shading.reflectionOf(point, roughness) returns the direction to sample reflected light along.
• shading.reflectance and shading.specularOcclusion are the terms surrounded uses.
• shading.unfogged, direct, sun and towardsSun are the parts of shade, for shaders that combine them differently.

A hook for one renderer

Every pipeline built from light.inject() binds the resources its hooks read. A hook passed to lighting.create reaches every lit renderer, so a fog that reads a ground paint texture and its uniforms adds those bindings to every figure and prop pipeline too. Each stage has 8 storage and 12 uniform buffers to share, so give a hook that only some renderers need to those renderers alone:

const ground = terrain.renderer().pipe((cfg) => cfg.with(shading.fog, paintedFog));

Renderer pipe runs after the lighting, so its fill replaces the lighting’s. Fill your own pipelines the same way, root.pipe(light.inject()).with(shading.reflect, shading.lambert). Pipelines lists what each pipeline binds.

Clear surfaces

Glass that hides only a tenth of its background can still show full-strength highlights and sky reflections. Use shading.shadeClear(material, point, opacity) for this behavior. It returns premultiplied colour for pipelines.blend.over:

const pane = (world: d.v3f, normal: d.v3f) => {
  'use gpu';
  const glass = materials.glossy(d.vec3f(0.8, 0.9, 1), 0.05);
  return shading.shadeClear(glass, shading.pointAt(world, normal), 0.1);
};

• opacity scales the diffuse light, the emission and the fog over the surface; the reflected light is added whole. w is opacity.
• A metal reflects all it shows, so opacity only fades its fog.
• An instances renderer with blend: 'clear' shades through it.

Tearing down

Call light.destroy() when nothing draws with its resources. It frees the settings uniform and the shadow maps. Methods that would use them for GPU work then throw The lighting was destroyed. A table of lights is yours to destroy.

Limits

• Without candidates, every shaded pixel visits each light slot. There is no tile or cluster culling.
• shadeClear is exact for dielectrics and metals. It approximates intermediate metallic values and custom fog hooks that do more than mix toward a colour.
• Two lightings in one frame, such as a lit room seen through a window, need two sets of pipelines.