Renderer · interface

LightVolumeDrawOptions

The two things a volume of light can have beyond its shape. See drawLightVolume.

interface LightVolumeDrawOptions

import type { LightVolumeDrawOptions } from '@driftengine/core';

In depth

Both default to nothing, and that is not only compatibility: a torch beam is a smooth cone and should stay one. These are what turn a beam into a shaft of daylight, which is a different phenomenon that happens to be drawn by the same pass.

Properties

Name	Type	Description
`dust`readonlyoptional	`number`	How much structure the air in the beam has, 0 to 1. Zero computes nothing. More A shaft of sun through a window is not smooth: what is lit is the dust in it, and the dust is uneven. Useful values are low, around 0.2 to 0.5; past that the beam reads as smoke.
`dustScaleM`readonlyoptional	`number`	Metres per cell of the dust field. Around a metre for motes, several for weather.
`driftM`readonlyoptional	`Vec3`	Where the dust field has drifted to, in metres. Defaults to standing still. More A position rather than a rate, so this pass never reads a clock and a caller asking for the same instant twice gets the same frame. Air moves with the scene's wind, so the drift to hand it is the one `WindField` has already accumulated — the same value the smoke and the grass are answering to, which is what stops a shaft of dust drifting one way while the smoke beside it goes another.
`sunShadow`readonlyoptional	`number`	How much the sun's own shadow map cuts the volume, 0 to 1. Zero samples nothing. More The directional light, which is to say the sun. A shaft through a window carries the bars of that window because the light did; without this the floor under a mullioned window is barred and the shaft above it is smooth, and one frame disagreeing with itself about where the light went is most of what reads as fake. A beam from a lamp is not sunlight and wants this left at 0, which is why it is a per-draw amount and not a renderer setting. Needs `env`, and needs the renderer built with `directionalShadows`. Without either it is ignored rather than throwing, because this is a frame-loop call. The occlusion is evaluated at every step of the march, so this is a shadow carried through the air rather than stamped on a surface. What it still does not do is let one volume shadow another behind it: each is integrated on its own.
`env`readonlyoptional	`Environment`	Where the sun's shadow map is. Required by `sunShadow` and unused without it.
`medium`readonlyoptional	`{ readonly atmosphere: Atmosphere; readonly fullAtDensity: number; }`	The air this volume stands in, and the density at which it reads at full strength. More A beam is only as visible as the medium it is lighting, and until 2026-08-28 nothing here knew what the weather was: the same headlight cone was drawn in clear air and in thick fog, because `strength` is a number a caller authored once. Given this, the cone fades out as the air clears and blooms as it thickens, which is what turns fog from a filter over the frame into something that changes how the road is read. `fullAtDensity` is in the units of `Atmosphere.fogDensity` and is the density at which the beam is drawn exactly as authored; below it the beam is proportionally dimmer, above it nothing further happens. Absent means the beam ignores the weather, which is every volume drawn before this existed and every torch beam indoors. Density is read at the volume's own height rather than the camera's, so a car in a valley of fog seen from the ridge above carries its own weather.
`nearM`readonlyoptional	`number`	Where the drawn volume starts along its own +Z, matching the `nearM` its hull was built with. Defaults to the apex. More The march is clipped to the same slab the hull covers, so a shaft that is a slice taken far down a very wide cone has to say where its slice begins or the walk starts at an apex above the roof and integrates air that was never drawn.