SGL3D (sgl-3d)
Rust/wgpu 3D rendering for native and browser (WASM + WebGPU) games, extracted from Hyperdrive and consumed as part of SGL. The game supplies geometry, materials, lights, environments, camera data, and final presentation poses. The library retains GPU resources and encodes rendering on the game's device and command encoder.
Agents building a game start at SGL3D for game agents, which lists the features and settings. The SGL3D specification owns the contract and rendering validation rules. 3D development explains the integration, native and in the browser. This crate does not own a window, event loop, input, simulation, protocol, save schema, editor, or ECS. It does not depend on winit or an input package; wgpu supplies platform graphics dependencies.
FSR frame generation is unsupported. Native and browser clients use the same
caller-owned Renderer and View submission and presentation workflow. FSR2 and FSR3.1
temporal upscaling remain available on supported native devices.
Use View::output_encodes_srgb() when matching a directly composed UI to
the view's selected output transfer.
Reference map
Start with the agent guide for a short integration path. This page is the detailed reference:
- Frame lifecycle, data conventions, browser differences
- Lights and look, procedural sky, local lights, shadows, decals
- Reflections, TAA, SMAA and FSR, ambient occlusion, screen-space indirect light
- Exposure and grading, motion blur, fog
- Specular probes, diffuse lighting, irradiance volume, dynamic GI, asset limits
- Skinning and morphs, scrolling normals, programmable surfaces, mesh LOD, soft effects, heat shimmer
- Settings and fallbacks, binding tiers, GPU timing, diagnostics
Dependencies and data conventions
Use this workspace crate from the same SGL revision as other SGL packages.
Use the wgpu dependency in the workspace manifest. A game
may share one device/queue with the sgl-2d UI or 2D renderer; the game owns
pass ordering and presentation.
Use the public sgl_3d::glam re-export for matrices and vectors passed to this
crate. SGL3D, sgl-2d, and sgl-core share the workspace glam dependency,
so their matching vector and matrix types can cross package boundaries directly.
Dependency versions live in the workspace manifest; the
package manifest selects the features used here.
| Input | Convention |
|---|---|
| Positions, light ranges, atmosphere dimensions | Metres, +Y up |
| Camera | Right-handed, local forward -Z; reversed-Z depth (1 near, 0 far), perspective builds the infinite-far projection |
| Shadow maps | Reversed-Z (clear 0, nearer = greater). SGL3D fits directional cascades from the camera; the game gives their reach in metres of view depth |
| Matrix arrays | Column-major; view-projection is projection × view |
| Camera cuts | FrameInput::camera_cut restarts history; no renderer-owned camera movement |
| Pose | Final presentation transform, after game-owned interpolation |
| Light/material values | Linear RGB; base/emissive images are sampled as sRGB |
| Light directions | Where the light shines (directional lights, spots, rectangles' faces) |
| Light units | Point, spot and rectangle intensity in candela (a rectangle's along its normal), directional illuminance in lux, on one scale |
| Environment/backdrop yaw | Radians about +Y |
| Frame/history identity | Previous submitted rendered frame, independent of simulation ticks |
Instance poses may contain nonuniform or mirrored scale. Supply finite, nonsingular affine transforms; normals use the inverse transpose, and authored front/back sides are preserved across raster, shadow, and ray paths. Shadow casters cull as the camera does, for the directional light and local lights alike: a single-sided material casts from its front faces, a double-sided one from both. Author open single-sided geometry that must shadow from behind as double-sided. A masked material casts from the texels it keeps; a blended one casts no shadow (Alpha-masked and blended materials).
The game describes directional lights, the hemisphere fill, the environment's
lighting and backdrop, the atmosphere and shadow projections with typed
FrameInput values (Frame lights and look), and
SGL3D packs its GPU layout itself; point, spot and rectangle lights are
scene content. The same inputs feed raster, ray
and probe-capture shading. Visibility groups are required bits in the frame’s enabled mask (zero
is unconditional). Directional shadow casting is a separate material choice;
enabling a group does not silently disable its shadows.
Frame lights and look
use ;
frame.environment = Map; // from scene.add_environment
frame.directional_lights = Some;
frame.hemisphere_light = HemisphereLight ;
frame.diffuse_environment = EnvironmentLight ; // intensity 1
frame.reflection_environment = EnvironmentLight ;
frame.backdrop = Environment ;
- Up to two directional lights (Bevy's
DirectionalLight, Godot'sDirectionalLight3D). A light with zero illuminance, or a zero or non-finite direction, is off. The first light that is on and has ashadowcasts it and draws its cascades, even at ashadow_opacityof at most 0.001, which shows none; the other is unshadowed.fog_energyscales the light it scatters in the volumetric fog, andshadow_opacityhow dark its shadow is, as a scene light's do.DirectionalLight::default()is Godot'sDirectionalLight3D: white, shining along -Z, π lux (its light energy of 1, which it scales by π), no shadow (opacity 1 when it has one) and fog energy 1. - The shadow is Bevy's cascaded shadow map, which SGL3D fits from the camera
every frame: the view depth from the camera's near plane to
distanceis split intocascades, each a map of 2048 texels (1024 at the LowSettings::shadow_quality). SGL3D places the splits as Godot'sDirectionalLight3Ddoes by default: each cascade but the last ends 0.1, 0.2 and 0.5 of the way from the near plane todistance(two cascades split at 0.1, three at 0.1 and 0.2), and the last atdistance, which is kept at least 1 mm beyond the near plane, as Godot keeps it, and at most 8192 m, the top of Godot'sdirectional_shadow_max_distancerange;shadow: Nonealone turns the shadow off.DirectionalShadow::default()is Bevy's 150 m and 4 (cascades ending at about 15, 30, 75 and 150 m); aconstbuilds from..DirectionalShadow::DEFAULT, the same values. A cascade keeps one size and moves in whole texels, so a still shadow does not shimmer as the camera moves and turns (a change of field of view or of these values resizes it). Each cascade overlaps the next by a fifth of its far bound's distance from the camera, and surfaces blend between the two there. An orthographic camera's near plane may lie behind it: the cascades and the clustered lights then start there. Beyonddistancenothing is shadowed. Casters between the light and a cascade still cast into it: their depth is unclipped, throughwgpu::Features::DEPTH_CLIP_CONTROLwhere the device has it (graphics_device::features) and emulated in the caster's shader where it does not. Each cascade's map reaches 20 m toward the light beyond its part of the view (Godot's default pancake), so a caster within that margin is recorded at its own depth and one beyond it at the margin's edge. Receivers are offset along their geometry normal (not the normal map's) by Bevy's 1.8 texels (times √2) and toward the light by 2 cm, so no bias is authored. While TAA or FSR runs the camera's surfaces filter with Jimenez's 8-tap spiral, turned per pixel and per frame for them to resolve; otherwise, and in probe captures and ray hits, with Castaño's fixed 9-tap kernel. WithSettings::soft_shadows(on at the High preset) that spiral widens to the penumbra the sun's disc casts: eight taps find the casters between a surface and the sun, and the filter's radius isangular_diameter's half-angle tangent times the metres between them, never below the fixed spiral's, so a shadow is sharp where its caster touches and softens with height, the same in every cascade for the casters found. Each of those taps is compared at the depth the receiver's plane has there, so a slope under a wide sun neither shadows itself nor narrows its penumbrae. A sun of no angular diameter keeps the fixed spiral. At the Low shadow quality the camera's surfaces take one hardware 2×2 comparison instead, Godot's hard filter, with Godot's mobile map sizes. A probe capture fits its own cascades about its centre; it and world-space ray hits take the first cascade whose map holds a surface, which the pancake makes a nearer, finer one for a surface toward the light from a cascade's part of the view. Timing groupsdirectional shadow cascade 0to3, nearest first. Settings::contact_shadows(Offby default, in no preset;Short,Medium,Long) adds screen-space contact shadows for the light with the cascades: one compute pass over the camera's opaque depth marches 63, 127 or 191 render pixels toward the light (Bend Studio's screen-space shadows as Godot b130438 runs them), and the camera's opaque surfaces take the lesser of that and the cascades' shadow, at the light'sshadow_opacity. It finds the casters the cascades are too coarse for, a chair leg's or a kerb's, but only what the camera sees: an off-screen or hidden caster casts none, and a thick one may cast past its own thickness. A depth the march reads as an edge, one more than 2% from its neighbour across the march, casts none (Bend'sIgnoreEdgePixels, which Godot leaves out): a floor seen near edge-on and the frame's border, which read as edges, do not shadow themselves, and a caster's outline against a surface well behind it casts none, so a caster only a few pixels wide casts a thinner shadow away from where it stands (D-69). While it runs the opaque stage takes its two-pass form. It needs aperspectivecamera, and gives way to ray-traced shadows. Timing groupcontact shadows.hemisphere_lightis Three.js'sHemisphereLight: diffuse irradiance blended fromground_colorfacing down tosky_colorfacing up, which lights a surface as the environment's diffuse light does.- The frame environment lights each lobe through its own
EnvironmentLight(yaw and intensity, by default unturned at intensity 1, as Three.js's scene environment):diffuse_environmentthe diffuse lobe, andreflection_environmentthe specular lobe wherever no baked probe does (source completion beyond the probes, probe captures and ray hits, and the sky captures record). Bevy'sEnvironmentMapLightand Filament'sIndirectLightscale both lobes with one intensity; set both fields alike for that.backdropis what the camera sees where there is no surface: the environment's panorama or one colour. The sky's motion vectors follow a turn of the panorama's yaw between frames, so antialiasing and motion blur track a rotating backdrop; a change of its brightness, colour or environment is a shading change without motion, which antialiasing follows through its neighbourhood clamp. Keep its yaw consistent with authored directional lighting and the backdrop. An HDR environment containing a bright sun contributes that sun through image-based lighting too; a second analytic sun can duplicate energy or place reflections and mapped shadows in different directions. Explicitly separate sun and sky during content preparation when using a shadowed directional sun, retaining the original source and the export recipe. Global environment fill does not know which buildings occlude it. Nearby camera-space AO, a dynamic GI volume, or authored baked diffuse data provide different visibility approximations; increasing shadow-map opacity cannot occlude an unrelated environment contribution. See the controlled Bistro lighting workflow. fog(Fog) is the frame's participating medium (Volumetric fog) andmist(Mist) the look of the scene's mist billboards: their colours, opacity, size anddrift, how fast and which way their noise moves (Mist::default()hides them, and drifts them slowly up and to the left); both draw whileFrameInput::atmosphere(off by default, as Godot's fog) andSettings::atmosphere(which allows them, on by default) are on.
Procedural sky
use ;
frame.environment = Sky;
frame.directional_lights = Some;
FrameInput::environmentis aFrameEnvironment:None(black),Map(one of the scene's environment maps; an ended one isNone) orSky, a physically based sky (Hillaire 2020, ported from Bevy's atmosphere) lit by the frame's directional lights. No asset and no setting: the variant is the control, andNoneis the default.- Under a sky a directional light's
colorandilluminanceare its light above the air. Every consumer (surfaces, shadows, the fog, probe captures, ray hits, the dynamic GI volume) takes it as it reaches the camera: times the air's transmittance toward it from the camera's height, so the sun reddens and dims as it sets, and times the share of its disc above the horizon, so a sun below the horizon is off and casts no shadow. The backdrop shows the sky and each light's disc, sized by itsangular_diameterand scaled bySky::sun_disc(0 draws none). Skyis the game's look:ground_height(the camera stands at least 1 m above it),rayleigh,mieandozone(each medium's density as a scale of Earth's; 0 removes it),ground_albedo(the planet's ground, which also lights the sky) andsun_disc. Negative or non-finite scales are 0 and the albedo is clamped to 0..=1. The planet's radii, the media's coefficients and profiles and the tables are SGL3D's.Backdrop::Environment'sbrightnessscales the sky; itsyaw, and the yaws ofdiffuse_environmentandreflection_environment, do not turn it (its lights place it).Backdrop::Colorstill replaces it. The sky's motion vectors are the camera's rotation alone.- The sky lights the frame as an environment map does: surfaces' diffuse
and specular environment light (
diffuse_environmentandreflection_environmentscale it), the dynamic GI volume's misses, the fog's ambient share, probe captures and ray hits, through an environment atlas in a map's format. Lowerhemisphere_lightwhere it stood in for sky light. The atlas holds the sky without the lights' discs: each light's own highlight is its reflection. - The atlas follows a changing sky one refresh step a frame over a 16-step cycle, and at once in the first sky frame and after a cut. A cycle under way finishes before the next starts, so reflections (the sharp level) lag a moving sun or a climbing camera by up to 16 frames and diffuse environment light (the roughest level) by up to 31, and while a cycle runs the faces it has not yet refiltered still hold the cycle before.
- Aerial perspective: distant surfaces take the air's haze, fading toward
the sky's colour with distance, coherently with the sun and the sky behind
them.
Sky::aerial_perspective(default 1) is how much air each metre of view distance counts as: 1 is the planet's, 0 none, above 1 hazier, so a small world reads as a large one; negative or non-finite is 0. With Earth's air it is negligible at tens of metres (at 30 m along the ground it dims a surface by about 0.1 %) and builds over kilometres (about 10 % at 5 km). Opaque and blended surfaces, glow and mist take it through the fog volume (Volumetric fog); the sky does not take it again, since it already holds the air. It is independent ofFrameInput::atmosphereandSettings::atmosphere, which turn the fog and mist: with them off it still applies. It needsperspective's projection, as the fog does. Probe captures and ray hits (world-space reflections, the dynamic GI volume) take none, as they take no fog. It reaches 32 km of view distance; anything farther takes the haze at 32 km. - Up is +Y and the ground is flat around the camera.
- Cost: three small tables and the atlas per view (about 0.9 MB and
3.1 MB). The tables are computed on the first sky frame and again only
when their inputs change:
sky viewwhen a light or the camera's height changes, all three when aSkydensity or the albedo does. The atlas then runs one step a frame until it has caught up. Aerial perspective adds a 32³ volume (0.26 MB) computed every frame it is in effect, since it follows the camera, and 33 slices to the fog volume's integration. A frame at rest without aerial perspective pays only the backdrop's one table sample. Timing groupssky transmittance,sky multiscattering,sky view,aerial perspectiveandsky environment.
Exposure, bloom and colour grading
use ;
frame.exposure = Exposure ;
frame.local_exposure = LocalExposure ;
frame.bloom = BloomParameters ;
settings.tone_mapping = Agx; // default: KhronosPbrNeutral; also AcesFilmic
frame.color_grading = ColorGrading ;
- The frame has one exposure, which FSR and the tone map both read. With
automatic: Noneit isstops. Otherwise it is Bevy's auto exposure, metered from the complete HDR frame at the render size, before antialiasing: a 64-bin histogram of log2 luminance (afterstops) from -8 to 8, weighted bymetering_mask(a 16×16 grid), averaged without the darkest and brightest 10% of samples (Bevy's default range and filter, which SGL3D keeps). Samples below 2^-8 position that percentile window but do not enter the average; with no remaining samples it takes -8. This departs from the pinned Bevy port, following Wicked Engine's exclusion of its near-black bin (D-46). The target correction brings that average to 2 raised to the compensation curve's stops (-2.5 is about middle grey);stopsshifts the frame into the range. The correction follows it atspeed_brightenstops per second when the scene got brighter andspeed_darkenwhen it got darker, byFrameInput::frame_time_ms, slowing within 1.5 stops of it (Bevy's default) and never stepping past it however long the frame, and stays withincorrection_min..=correction_max. A camera cut, a target-changing resize, another scene or a switch from a fixed exposure sets it to its target. An abandoned encoder retains that switch for the next submitted frame. Timing groupexposure. - Local exposure (
FrameInput::local_exposure) draws large bright and dark regions toward middle grey (0.18 after the frame's exposure) before the tone map and keeps their detail, after Patry's Ghost of Tsushima tonemapping (D-63). From the image the tone map reads, at the frame's exposure, it builds a base of log2 luminance: 40% a bilateral grid (64 cells along the longer side, 13 slices over ±8 stops) and 60% a wide Gaussian of the cells' means. The tone map scales the base's distance from middle grey byhighlight_contrastabove it andshadow_contrastbelow; each pixel keeps its luminance over the base. Cost: one compute pass reading every scene texel once and six small passes over the grid (timing grouplocal exposure), under 1 MB of targets, and two filtered samples a pixel in the tone map (tone map). At 1 and 1, the default, nothing runs and no target exists. It keeps no history. - Bloom is Bevy's energy-conserving bloom: a mip chain 512 texels high (a
scene too wide for that, such as a window one pixel tall, takes the
device's widest texture instead), 13-tap downsamples (the first with a
Karis average against fireflies), 3×3 tent upsamples blended level by
level, and the result mixed into the scene.
intensityis how much light scatters, 0 none; SGL3D shapes the halo with Bevy'sBloom::NATURALlow-frequency boost and high-pass. Light only moves, so emitters bloom by being bright, with no threshold. The chain isRg11b10Ufloatwhere the device renders to it (graphics_device::features), else RGBA16F. Timing groupbloom. - The tone map multiplies by the exposure, applies Bevy's
ColorGrading(hue, white balance, and saturation, contrast and ASC CDL for shadows, midtones and highlights), thenSettings::tone_mapping, followed by the grading's post-saturation.KhronosPbrNeutral(default) preserves colour below its highlight knee;AcesFilmicis Three.js's ACES fit, including its standard viewing scale, with stronger contrast;Agxis Filament's AgX in Rec. 2020, withColorGrading::agx_look(None, base contrast;Punchy, more contrast and saturation;Golden, a golden tint). These are standard transforms, with no additional saturation or exposure boosts. Their ports and reference-vector tests live insrc/stages/post/tone_map(Khronos, Three.js r185, Filament). Sections crossfade over 0.1 either side ofmidtones_start(shadows with midtones) andmidtones_end(midtones with highlights), using the exposed RGB mean. Highlights do not affect the shadows-to-midtones transition. The default grading changes nothing. The output is dithered with Bevy's deband dither, up to half an 8-bit step per channel, so smooth gradients do not band on an 8-bit surface; the tone-mapped diagnostics capture is not. Timing grouptone map. ColorGrading::global.huerotates in radians, wrapping either direction every 2π; negative angles and multiple turns need no game-side wrapping.
Motion blur
use ;
let settings = Settings ;
frame.motion_blur.shutter_angle = 0.5; // the default, film's 180° shutter
- Each pixel blurs over
shutter_angleof its motion since the last frame, centred on it, timesSettings::motion_blur: Full 1, Reduced 0.5; Off (the default) does not run. The motion is the G-buffer's: the camera's, and moving and deforming instances' own. Like a shutter, the blur follows the frame rate: a faster frame moves less and blurs less. A frame that restarts history (a camera cut, a target-changing resize or another scene) is not blurred. It needsperspective's projection. - It is Wicked Engine's tile-max reconstruction filter (Jimenez 2014, after McGuire et al. 2012). The longest blur in each 32-pixel tile and in its 3×3 tile neighbourhood steers 16 samples per pixel along it, and depth and speed weight them: a moving silhouette blurs over what is behind it, and a slower surface in front, such as a craft the camera follows, stays sharp. A tile whose neighbourhood blurs less than a pixel is copied, and one of nearly even blur takes a plain average along each pixel's motion. A blur is at most two tiles (64 pixels) long, as McGuire clamps it, so the neighbourhood carries it.
- It runs on the antialiased frame at the scene size, after TAA or FSR and before bloom, SMAA and tone mapping, as Bevy and Wicked Engine place it. Blended surfaces write no motion, so they blur as what is behind them moves.
- Timing group
motion blur.
Volumetric fog
use Fog;
frame.atmosphere = true; // fog and mist are off by default
frame.fog = Fog ;
// Denser medium in a box, such as a tunnel's haze, added to the frame's.
scene.update_fog_volumes?;
The fog is Godot's volumetric fog (b130438 volumetric_fog_process.glsl and
fog.cpp, MIT), after Hillaire's "Physically Based and Unified Volumetric
Rendering in Frostbite" (2015). A volume of froxels fills the camera's
frustum out to length metres of view depth, more of its slices near the
camera (Godot's default detail spread, 2). Each frame, after shadows and
before opaque, the fog stage:
- sums each froxel's medium: the frame's, whose density halves every
1 / height_falloffmetres aboveheightand which is absent nearer the eye thanstartmetres, and that of every fog volume (Scene::update_fog_volumes, Godot's boxFogVolumewith its fog material's density, albedo and edge fade) it lies in, of the first 1,024 in the scene's order that reach the frame; - lights it with the directional lights through the one shadow cascade at
the froxel's depth, whose light fades with the metres the froxel lies
behind its occluder (Godot's fog; an occluder beyond the cascade's 20 m
pancake counts from the pancake's edge), the camera's clustered
point, spot and rectangle lights (baked ones too) through the local-light
atlas, each shadow one tap that the reprojection resolves (a local light's
one hardware 2×2 tap, as Bevy's volumetric fog samples them), and
ambient(0 by default, as Godot'svolumetric_fog_ambient_inject) of the hemisphere fill and environment diffuse, scattered toward the camera by Henyey–Greenstein's phase function ofanisotropy; each light'sfog_energyscales its share, and a light at or below 0.001 is skipped, attenuation and shadow lookup, as Godot does; - blends each froxel with where it lay in the last frame's volume, keeping
0.9 of it (Godot's default reprojection amount), and samples another
point of it each frame (Godot's 16 Halton offsets), so shafts and shadow
edges in the fog resolve over frames; this history restarts with the
camera's, and carries across a change of
Fog::length: each froxel finds its point among the last volume's slices of their own length, so density does not move when the volume covers a different range; - with
Settings::fog_filter(on by default, as Godot'suse_filter), blurs each slice with Godot's 7-tap Gaussian across x and then y, which smooths what one sample per froxel leaves; the next frame reprojects the unfiltered volume, as Godot keeps its history before it filters. A submitted frame retried withoutRenderer::finish_frameresets history when the filter overwrote the preceding frame's volume; - integrates each column front to back along its view ray into the light scattered toward the camera and the transmittance to each slice.
Under a procedural sky with aerial perspective (Procedural sky) the same
volume carries the air's haze, so every draw that fogs takes it with its
one sample: the integration composes the fog over the air, as Wicked
Engine composes its fog over its aerial perspective, in the fog's slices
and in 32 more from length to 32 km of view depth, and keeps a last slice
of the fog alone for the sky. With the fog off it runs alone, on a 32×32
volume of those slices, without injection or the filter.
Every draw then fogs from that volume where its point lies, as colour ×
transmittance + scattered light: source completion fogs opaque surfaces and
the sky (with the fog alone, never the air, as if at length, by
sky_affect: the sky mixed with its fogged
self, as Godot's volumetric_fog_sky_affect, 1 by default), and blended
surfaces, glow and mist fog themselves; glow adds only its light times the
transmittance, as the frame behind it already holds the scattered light.
Reflections composed over a surface take its transmittance, and screen-space
reflections trace the fogged frame.
Probe captures have no fog.
The offscreen example's --fog shows the frame's medium and a fog volume.
Light shafts are the medium's shadowed scattering: where an opening lets a
light's shadow map through, the medium lights, and forward scattering
(anisotropy above 0) brightens it toward the light. A frame
without a medium (no density and no fog volumes) runs no fog and pays
nothing for it, but for the integration of aerial perspective under a sky.
Settings::fog_quality picks the volume's resolution: 64 slices, and Low
is Godot's default of 64 froxels across the geometric mean of the frame's sides, High 128, in square froxels and no side past the device's 3D texture limit. Timing groups fog injection (the lights and shadows, which scale
with froxels and the lights reaching them), fog filter (with the filter)
and fog integration (also alone, for aerial perspective).
Each frame bounds the froxels every fog volume may reach from its corners,
as Godot does: a froxel evaluates only the volumes whose bounds hold it,
after testing those of every volume in view. A volume behind the camera,
beyond length, or wholly in front of the camera and beside the frame costs
nothing on the GPU. A volume that holds or crosses the camera's plane is
evaluated in every froxel of the frame up to its far end, so split a long
one, such as a tunnel's, into segments. A moving light's scattering trails
it by the history it keeps. Froxels are coarse: detail in the fog blurs
along the view, the more the farther.
Fog::start leaves the foreground clear: nearer the eye than start
metres, measured along each view ray, the frame's medium is absent (no
extinction, no scattered light, no shafts), and beyond it a surface d
metres away takes the medium's d - start metres, so the fog builds from
nothing with no edge to see; fog volumes are unaffected. Like any edge in
the medium, it takes effect up to one slice nearer the camera than set
(about 1 m at 20 m of a 60 m High volume, 9 m at 200 m of a 400 m one),
and Settings::fog_filter's blur across each slice spreads that edge
slightly sideways toward the frame's edges, within the same slice; a moving
camera's start trails it by the history the fog keeps. NaN,
infinite and negative starts are 0. The volume covers length of view
depth, length metres away at the frame's centre and farther toward its
corners, so a start at length still leaves the medium toward the edges and
fades it out continuously as it grows; a start at or beyond the corners'
distance leaves the frame's medium out, and with no fog volumes the fog does not run. Under
aerial perspective the fog still lies over the air in the volume, so with a
far start the air in front of the fog is dimmed by it too: about 1 % too
much at a 500 m start under Earth's air.
Where it differs from Godot's fog, and why:
- The frame's medium takes a fog material's height falloff
(
height_falloff), so height fog needs no volume. - The frame's medium has a start distance (
start), which Godot's volumetric fog lacks (its depth fog'sfog_depth_beginand Unreal's documented start distance are the practice): a hard start in density, not a smoothstep, since the integral along the ray is already continuous. - The detail spread and the share of history kept are SGL3D's, at Godot's
defaults, where Godot's
Environmentexposes them (S3D-6), and reprojection is always on. - Every medium scatters
albedo× density unquantized. Godot quantizes its fog volumes: it drops a volume at or below density 0.001, steps its density by 1/1024, caps its scattering at density 1 and truncates that scattering to 11/11/10 bits, so a dense volume here scatters more light than Godot's. albedo, the frame's and a volume's, is linear RGB, where Godot's fog colours are sRGB.- A fog volume is a box with a density, albedo and edge fade; its box's last
0.1 m fades under
edge_fadetoo, so a volume with none still ends at its box. Emission (the frame's medium's too), a volume's height falloff, density textures, negative density and other shapes are not ported, and there is no GI injection, which in Godot needs VoxelGI or SDFGI. - The lights are SGL3D's, in its units and falloff. The directional shadow has no fade toward the shadow distance: beyond it the fog is unshadowed, as surfaces are. A local light's light in the fog ends at its occluder instead of fading over about 10 cm behind it. A rectangle scatters by its face's solid angle, which stays bounded near it, so it takes no distance clamp against flicker as Godot's area lights do. A point or spot light's inverse square takes the squared diagonal of the froxel being lit in its denominator, as Unreal's volumetric fog biases its inverse-squared falloff by its voxel size and as the MIT Unity VolumetricLighting sample bounds its point lights' fog: one jittered sample of a froxel metres deep cannot integrate the falloff, so a sample landing centimetres from a light would take thousands of times the froxel's light and the history would hold it, pulsing about a still light and leaving puffs behind a moving one. A light's fog keeps its falloff where the froxels are small beside their distance to it; within about a froxel's diagonal of it, the fog falls short of the inverse square and holds steady, the more so where a long fog's slices are metres deep. Surfaces keep the physical falloff.
ambientscatters the mean of the hemisphere fill and environment diffuse over the sphere, which an isotropic medium scatters, where Godot samples its sky upward and along the view.- A froxel without history (the first fog frame, a new volume size or the camera's reset) keeps none, where Godot's fog fades in from a cleared volume and blends across cuts.
- The integration steps along each view ray, where Godot's steps view depth and so thins its fog toward the frame's edges.
- Fog needs
perspective's projection, whose froxels it places; with another camera nothing fogs, where Godot's also fogs an orthographic view.
Point, spot and rectangle lights
Point, spot and rectangle lights are scene content. Scene::add_light returns a
LightId; set_light replaces the light's description (a moving light is set
every frame) and remove_light ends it. Directional lights and the
hemisphere fill are frame input.
use ;
let lamp = scene.add_light?;
Light::default() is Godot's Light3D: a white point light at the origin
of π candela (its light energy of 1, which it scales by π) reaching 5 m,
live, physical specular, fog energy 1, no shadow (opacity 1 when cast) and
no cookie, with Wicked Engine's radius of 2.5 cm
(LightShape::DEFAULT_RADIUS). Set what differs and take the rest with
..Default::default().
A point or spot light's radius (metres) is the size of the sphere it
shines from. Its specular highlights spread over the sphere's reflection
(Karis's representative point, normalised so a smooth surface reflects
within about 20% of the sphere's light at any angle to it), so a large bulb
shows a broad highlight on a smooth surface; ray-traced shadows' rays and the
dynamic GI volume's visibility rays end on it, so a larger light casts a
softer shadow. Diffuse light and the shadow maps treat the light as a
point. A directional light's angular_diameter (radians, the sun's
0.00925, 0.53°, by default) does the same for its highlights and rays: the
sun on water shows a disc.
-
Light falls off with the inverse square of distance and fades smoothly to nothing at
range, Filament's punctual lights as Bevy shades them. A spot fades frominner_angletoouter_anglearound its direction; the outer angle stays below a right angle. Choose the range where the light stops mattering: each pixel pays for every light whose range reaches it. -
LightShape::Rect { direction, width_axis, width, height }is a one-sided rectangle centred onposition, facingdirection,widthmetres alongwidth_axis(its part acrossdirection) andheightacross both: a panel or strip fixture as Bevy'sRectLight. It lights the half-space in front of its face as a Lambertian emitter of even luminance, so nearby surfaces take soft light and stretched highlights; far away it acts as a spot light of the sameintensity(candela along its normal, its luminance times its area; Bevy takes π times this in lumens). Its face is integrated by linearly transformed cosines (Heitz et al. 2016), the GGX fit of selfshadow/ltc_code, and its light fades to nothing atrangefrom its centre. A rectangle costs more per pixel than a spot: it integrates its face once for diffuse light and once more for each specular lobe (base and coat) unlessspecularis 0. The lit pipelines shade rectangles only while the scene holds one, so a scene without them pays nothing for them; adding the first rectangle or removing the last selects the other specialization. Draws compile any missing variants when they first use them. -
bakedis Godot'sBAKE_STATIC. A baked light lights only receivers without baked lighting: moving instances, and static receivers with no baked map (baked lighting is off, or the material is not lightmapped and no irradiance atlas is installed or the lightmap UV is unassigned). A chart's black outside its cropped bounds is part of its bake. Static receivers with a baked map take the light from the game's lightmap or irradiance atlas, and its moving casters do not shadow them. A game that makes a baked fixture a baked light leaves that fixture out of its moving instances' ambient cubes, so its light counts once. A live light lights every receiver and is left out of the game's bake. -
specularscales the light's specular lobes, base, sheen and coat (Godot'slight_specular), and up to 1 the sheen's and coat's dimming of the base beneath them, so at 0 the light lights the base whole and above 1 it only brightens the lobes. Use 0 for a fixture whose emitter reflections and probes already show, so its highlight does not count twice. -
fog_energyscales the light it scatters in the volumetric fog (Godot'slight_volumetric_fog_energy): 1 is physical and 2 doubles it. At most 0.001 leaves the light out of the fog, which then skips its attenuation and shadow lookup, as Godot does: set 0 on fixtures whose light the fog does not need, to save fog injection time. The fog still visits the light's cluster entry, and its shadow is still drawn for surfaces, which take the light alike at any value. A baked light lights the fog too, which has no bake, and itsfog_energyscales that. -
casts_shadowgives the light a shadow in the local-light shadow atlas (Local-light shadows). -
shadow_opacityis how dark that shadow is, 0 to 1 (Godot'sshadow_opacity): its visibility is blended toward unshadowed, mix(1, shadow, opacity), on surfaces and in the volumetric fog alike, so 0.8 lets a fifth of the light through behind its casters, a cheap stand-in for bounced light. 1, the default, is the whole shadow; at most 0.001 draws none and skips the shadow lookup, as Godot does, though the light still takes its room in the atlas. The directional lights take it too. -
cookieprojects an image from a spot (a cookie or gobo: a window's panes, leaves, a stage pattern), as Godot's spot projector and Wicked Engine's light mask. The image comes fromScene::add_decal_imageand shares the decal atlas; it fills the spot's projector square, twice its outer angle across (the cone's circle is inscribed in it), its top towardup(any vector not parallel to the direction; its part across it is used) and its right the direction crossed with that. The light's radiance is multiplied by the image's linear colour times its alpha, the image sampled as sRGB colour: white leaves the light whole, black stops it, a colour tints it. Every receiver takes it: surfaces, probe captures, reflections' and the dynamic GI volume's ray hits and the volumetric fog, whose shafts carry the pattern; a shadow, if the light casts one, is unaffected. Its image's level follows the receiver's footprint as a decal's does. Abakedlight's pattern must be in the game's bake too, which holds that light. A cookie on a point or rectangle light, or with anupalong the direction, is refused withSceneError::InvalidLight, and an image a light projects cannot be removed (SceneError::DecalImageInUse). The lit pipelines sample cookies only while the scene holds a cookied light. Adding the first or removing the last selects the other specialization. Draws reuse its cached pipelines and compile any missing variants on first use.let panes = scene.add_decal_image?; scene.set_light?; -
Each frame the renderer assigns the lights, with the decals, to clusters of the camera's view on the CPU, as Bevy's clustered forward rendering does: a grid of render-target tiles and depth slices spaced logarithmically from 5 m to the farthest light's or decal's reach. A pixel loops over its cluster's lights, live ones first; a receiver with baked lighting stops there. Probe captures shade every light that is on; world-space ray hits shade the lights that reach the camera's view, as Wicked Engine's ray-traced reflections do. A cluster lists at most 8,192 lights and decals (the top of Godot's
max_clustered_elementsrange), live lights first, then baked lights, then decals, in the scene's order. A probe capture's list is the whole scene's, a world-space ray hit's that of the whole view and a dynamic GI probe ray's that of the whole volume, so for them this is a limit on the scene. -
Values must be finite, colour, intensity, specular and fog energy nonnegative, the range positive, a spot's direction nonzero, a rectangle's direction nonzero, its width axis not parallel to it and its size positive, and a cookie only on a spot of a positive outer angle; anything else is refused with
SceneError::InvalidLight. A light with zero intensity costs nothing.
Decals
Decals project images through a box onto the lit surfaces inside it, as
Godot's clustered decals do: road markings, signage, grime and damage placed
by the game instead of authored into every texture. They are scene content.
Scene::add_decal_image keeps an image (asset::Image; a compressed one's
level 0 is decoded) and returns a DecalImageId; Scene::add_decal returns a
DecalId, set_decal replaces a decal's description (a moving decal is set
when it moves) and remove_decal ends it. An image a decal or a spot
light's cookie uses cannot be removed
(SceneError::DecalImageInUse).
use ;
let paint = scene.add_decal_image?;
let matte = scene.add_decal_image?;
let marking = scene.add_decal?;
Decal::new(image) takes Godot's Decal defaults for the rest: a 2 m cube
at the origin, unturned, no normal or metallic-roughness map, a white
color, base_color_mix 1, fades of 0.3 toward the upper and lower faces
and no normal fade.
- The box spans
sizeaboutposition, turned byrotation. It projects down its local −Y: its images lie across its local X (U, left to right) and Z (V, top to bottom), and every point between its lower and upper faces takes the texel above or below it. Keep the box shallow so it reaches only the surface it marks: anything inside it, a passing vehicle included, takes the decal. - The base colour image is sampled as sRGB, times
color(linear RGB and alpha). Its alpha is the decal's coverage: it blendsbase_color_mixof the base colour, and weights the normal and metallic-roughness maps, as Godot does; a decal withbase_color_mix0 changes only what its maps change. normalis a tangent-space normal map in glTF's convention (+Y toward the image's top); the covered surface's normal turns toward it about the box's +Y.metallic_roughnessholds roughness in green and metallic in blue, as glTF's does, and replaces the surface's.upper_fadeandlower_fadefade coverage toward the box's faces ((1 − d)to their power,dthe fraction of the way from the centre plane; 0 does not fade).normal_fadefades it on surfaces turned from the box's +Y and removes it where(1 + n·Y) / 2is at or below its value (0 does not fade).- Decals change the surface before it is lit, so lighting, the G-buffer and every reflection see them: the camera's opaque and blended surfaces, probe captures (every decal) and world-space ray hits (the decals that reach the camera's view; they sample the atlas's first level, as hits sample material textures). Unlit materials take no decals. Overlapping decals apply in an order SGL3D chooses.
- The camera's clusters list decals after the lights, each as the sphere about its box, as Bevy clusters its decals, so a pixel pays only for the decals whose bounds reach its cluster. A cluster lists at most 8,192 lights and decals together, decals last (lights); a probe capture's list is the scene's, a ray hit's the view's and a dynamic GI probe ray's the volume's.
- The lit pipelines apply decals only while the scene holds one, so a scene
without them pays nothing for them. Adding the first decal or removing the
last selects the other specialisation. Geometry draws create any missing
pipelines as they bind them. Neither Godot (b130438, whose clustered
pass walks each cluster's decals whatever the scene holds) nor Bevy
(9d12036, whose
CLUSTERED_DECALS_ARE_USABLEfollows the device) specialises on decals; a game that adds its first decal mid-play and cannot afford that compile adds its decals at load. - The scene packs every image its decals and spot lights' cookies use into
one atlas of linear 16-bit texels with five mips, as Godot packs its decal
atlas with its projectors: each image once for each colour space it is
sampled in, with a border that keeps images apart at every mip. A decal
or light that brings in an image, or a colour space, the atlas lacks
places a new layout; the next frame (or probe capture) packs the atlas
anew and uploads every image once, however many brought images in, as
Godot packs its atlas once per frame. Add images, decals and cookies at
load. A removed decal's images stay in the atlas until it next packs. A
decal or light whose layout would be larger than the
device's textures, or take more memory to build than the target can
allocate, is refused when it is added, with
SceneError::DeviceLimit. SGL3D builds the atlas on the CPU at 8 bytes a texel, with its mips a third more, and allows 2 GiB for it in the browser and 8 GiB natively. An image's side and its 32-texel border round up to a power of two, and each map counts: one 4096-square image takes an 8192-square atlas (0.67 GiB), two or three 8192 by 16384 (1.33 GiB), and four, or one 8192-square image, 16384 square (2.66 GiB), which the browser refuses. 8160 square is the largest image an 8192-square atlas holds. - Values must be finite, the size positive, the rotation nonzero,
colorandbase_color_mixin [0, 1], the fades nonnegative andnormal_fadebelow 1; anything else is refused withSceneError::InvalidDecal.
Local-light shadows
Lights with casts_shadow share one 4096² depth atlas (2048² at the Low
Settings::shadow_quality, Godot's desktop and mobile atlas_size), split
as Godot's shadow atlas is into four quadrants, of 16 slots of 512 texels, 64
of 256, 256 of 128 and 1024 of 64 (half those sizes at Low). Each frame the casting lights whose range reaches the camera's view
are ranked by screen coverage and given slots of the size their coverage
wants, largest first. A light keeps its slots while it is seen, and moves to
another size only after holding them for half a second at 60 frames per
second; a light not seen gives up its slots, least recently seen first, to
lights that need them. Lights the atlas has no room for are lit without a
shadow. View::local_shadow_stats reports how many lights in the view
have a shadow, how many do not, and what the frame drew. With ray-traced
shadows the camera's opaque surfaces take up to fifteen of the placed
lights' shadows from rays instead
(Hardware ray tracing).
A point light has six cube faces around it, side by side in one quadrant as Wicked Engine lays them out; a spot light has one face covering its cone, or the cube faces its cone reaches when it is wider than 45°; a rectangle has a point shadow from its centre, as Godot shadows its area lights, in the cube faces that see the half-space in front of it (five for a face along an axis). Faces reach the light's range. A closed spot, or one so narrow that its projection is non-finite, remains valid content but releases its shadow slots until its projection is finite.
Each face keeps a static layer in a second atlas: its static instances,
drawn once. A frame draws only what changed. When a moving instance enters,
leaves or moves within a face, the frame copies the face's static layer and
draws the moving instances over it. The layer itself is drawn again when the
face is new to its slot, a static edit reaches it (adding, removing or
changing a static instance, or replacing a model one shows; each edit's own
bounds are tested, so streaming many chunks in one frame redraws only the
faces they reach, until more than 1024 edits in a frame merge in pairs),
the visibility mask changes, or a material's side, visibility group or
alpha mode changes
(or a masked material's cutoff or base alpha). A casting (not blended)
material whose shader may change what it casts (a displacement bound above
0, or a masked material's surface function) redraws the faces its instances
reach as the shader's inputs change: its parameters
(Scene::set_shader_parameters); the frame's time, where the shader reads
time or phase (SGL3D reads the module for them, as Godot marks a shader
animated by its code), which redraws those faces' static layers every frame
the time advances, so a large static field of a time-animated shader costs
a static-layer redraw of every face it reaches each frame; and a moving
instance's shader data. A light that
moved since the last frame, such as one following a craft, has no reusable
layer and draws every caster. A frame in which nothing moved in any shadowed
light's range draws no shadows at all. What a frame draws becomes reusable
only once it is submitted and finish_frame is called; a dropped or
unfinished frame is drawn again.
Shadows are filtered and biased as the directional cascades are, with
Bevy's filters (Castaño's 9-tap kernel, or the Jimenez spiral while TAA or
FSR resolves it, whether or not a directional light casts; one hardware
2×2 tap at Low) and Bevy's spot-light receiver offset for every face,
cube faces included: Bevy tunes its spot biases for these 2D filters and its
point biases for its cube-map filter, which the atlas does not use. Each
tap stays inside its face, as Wicked Engine clamps to its atlas
rectangles. With Settings::soft_shadows, under TAA or FSR, a point or
spot light's shadow widens with its radius as Godot's soft shadows do: the
penumbra is the radius times (receiver − blocker) / blocker, from casters
found within the radius at the receiver, as Godot, Bevy and Filament
search, never narrower than the fixed spiral. A caster nearer the light
than half way to the receiver casts a wider penumbra than that search
reaches, so its lit side is cut off about the radius from the hard edge. A spot's taps lie on its face; a point light's lie across the
direction to it, each in the cube face it falls in, so a shadow is the same
across a face's edge. Either's taps are compared at the depth the
receiver's plane has where they land, so a surface tilted to a large light
does not shadow itself; a cube whose penumbra is within the fixed filter's
radius keeps the fixed filter's one depth. A rectangle's shadow, cast from its centre, keeps the
fixed spiral. Probe
captures and world-space ray hits, which show static content, sample the
static layers: a capture places the lights it shades and draws their layers
itself, and ray hits see the camera's lights, except one that moved this
frame, which is unshadowed for them.
A baked light's shadow darkens only what it lights: moving instances and static receivers without baked lighting. Its moving casters therefore shadow other moving instances, and its static casters shadow moving instances that pass behind them.
Reflections
Source completion adds each lit receiver's environment specular to the forward beauty: the authored baked probes whose influence contains it, then the sky.
Settings::screen_space_reflections (settings::ScreenSpaceReflections: Off,
Half or Full resolution tracing; default Off) adds screen-space reflections,
traced by Settings::reflection_method (settings::ReflectionMethod). Each method
combines passes from several engines, listed with their licences under it.
Crystal(default): one ray per pixel along its lobe's peak, the mirror direction, through a hierarchical depth buffer, then a spatial, temporal and bilateral denoiser, below perceptual roughness 0.2. Reflections stay sharp. SGL3D sets its tracing and denoising parameters, the same at Half and Full resolution, and supplies the roughness input (src/view/post_fx.rs): DiligentFX'sScreenSpaceReflectionAttribsdefaults, with a perceptualRoughnessThresholdof 0.2 as in AMD's SSSR sample, Hydrogent's 64 traversal steps (MaxTraversalIntersections; a ray that has not confirmed a hit within them is a miss), the lobe peak (GGXImportanceSampleBias1) and 0.95 of temporal history (TemporalRadianceStabilityFactor): one stochastic ray per pixel leaves blotches on glossy receivers that the denoiser holds.- DiligentFX
SSR: AMD FidelityFX SSSR's tracing with a confidence output and
DiligentFX's denoiser. Apache-2.0, the basis of SGL's
sgl-post-fx(LICENSE.txt), with fixes and enhancements described in its PROVENANCE.md. - Godot's
mirror direction and depth tolerance (DFX-18, DFX-20). MIT,
sgl-post-fx/LICENSE-godot.txt. - Wicked Engine's
tone-mapped spatial resolve (DFX-16), history weight and 2-deviation
history clamp (
ssr_resolveCS.hlsl,ssr_temporalCS.hlsl, DFX-25). MIT,src/LICENSE-wicked.txt. - AMD's reflection denoiser's
virtual-point reprojection (DFX-25). Crystal accounts for the motion
of the receiver and the reflected source when weighting history. MIT,
sgl-post-fx/LICENSE-amd-fidelityfx-denoiser.txt. - Bevy's roughness fade. MIT OR Apache-2.0.
- DiligentFX
SSR: AMD FidelityFX SSSR's tracing with a confidence output and
DiligentFX's denoiser. Apache-2.0, the basis of SGL's
Velvet: one mirror ray per pixel through a hierarchical depth buffer, accumulated over frames, then blurred through a Gaussian mip chain: the resolve reads each pixel's mip from a cone that widens with its roughness and ray length. Nothing is stochastic. It traces below perceptual roughness 0.7, fading over the last 0.1, with Godot'sEnvironmentdefaults (64 steps, fade in 0.15, fade out 2, depth tolerance 0.5 m); unlike Godot, a ray that has not confirmed a hit within its steps is a miss. SGL3D converts its G-buffer to Godot's view-space normal-roughness and depth, and the rays read this frame's radiance. As in Godot, the trace tone maps radiance by luminance before RGBA16F storage and roughness filtering and the resolve inverts it, so a few very bright hits cannot dominate a blurred reflection. Reflected luminance saturates near 2048. TAA's jitter moves the trace's inputs every frame, so a hit on thin bright geometry lands on different pixels and the Gaussian mips spread each into a blob larger than TAA's neighbourhood; Godot itself flickers this way. The temporal pass (reprojection by motion and by reflection hit, depth disocclusion, a 3x3 colour clamp) therefore accumulates the traced hits before the mip chain, and restarts with the other histories. Velvet and world-space rays share hit reprojection along the normalised view ray, choose only in-bounds history candidates, and compare depths in the previous camera's space. It costs about 0.9 ms at 1920x1080 on an Apple M5.- Godot 4.7.2's
SSR (
screen_space_reflection*.glsl, asss_effects.cppruns them): the trace, mip chain and resolve, insrc/stages/reflections/velvet/. MIT,src/LICENSE-godot.txt. - Wicked Engine's
SSR temporal pass, in
src/stages/reflections/temporal_reprojection.wgsl(shared with world-space rays) andvelvet/godot_reflections_temporal.wgsl. MIT,src/LICENSE-wicked.txt.
- Godot 4.7.2's
SSR (
Each method returns the same premultiplied radiance and confidence, so a new one (hardware ray tracing) plugs in beside them.
The methods trace the surface: the nearest of the opaque surfaces and the blended receivers. Composition adds the opaque lobes; under a receiver, whose result it is, the opaque lobe keeps its environment and probe specular, and the receiver composes the result in its blended draw by the same formula.
View::new builds source completion for its settings' screen-space
reflections and ambient occlusion, so a first frame from a perspective
camera compiles none of it; turning either on or off later compiles it again
on the next frame.
SSR traces the lit beauty with effects and mist, emitters included. Probe
captures include emitters too, so hits and misses show the same fixtures. A
lobe is traced when its perceptual roughness is
below the threshold: the coat of a coated receiver, else the base. Source
completion leaves out that lobe's environment specular. SSR returns radiance
premultiplied by its confidence (sgl-post-fx DFX-17). Composition adds
response × (reflected × fade + environment × (1 − confidence × fade)),
fogged as completion fogs:
responseis the lobe's split-sum term.environmentis the receiver's own per-pixel probe or sky specular.fadefalls smoothly from 1 to 0 below the method's threshold: over the last 0.05 of perceptual roughness forCrystal, as Bevy's SSR fades out, and over the last 0.1 forVelvet, as Godot's forward pass does.
Bevy composites SSR this way, and AMD's SSSR likewise blends the environment
into each missed ray. Misses and low-confidence hits fall back to the same
specular the receiver gets with SSR off, whatever share of a pixel's rays hit.
The fade leaves no seam where a roughness crosses the threshold. Each lobe
counts once. Rougher receivers keep their own environment specular. The G-buffer roughness
includes geometric specular antialiasing (Filament's normalFiltering), as in
Filament, HDRP and Unreal.
History restarts on a camera cut, a resize that changes the targets and a different scene. Switching SSR off releases it. DiligentFX's camera has a finite far plane (10 km) where SGL3D's is infinite; surfaces beyond it are background to SSR and TAA.
Settings::world_space_reflections (with SSR on) traces what SSR misses, as
Lumen and HDRP's mixed tracing continue failed screen traces in world space:
Moving reaches moving objects, which baked probes cannot hold, and All
everything, static surfaces included, as Wicked Engine's RT reflections trace
the whole scene. Each traced lobe of an opaque
surface that SSR did not fully resolve, and that no blended receiver covers,
casts one GGX-sampled ray at half resolution through the portable scene BVHs,
or the scene's acceleration structures with
hardware ray tracing,
reaching 1000 m (Wicked Engine's default Postprocess_RTReflection
range). The BVHs are two-level, as hardware acceleration structures are: a BVH over
the static instances and one over the moving instances, rebuilt on the CPU
when static content changes and every traced frame respectively, then each
model's own BVH, so a ray's cost follows the instances it reaches rather than
how many the scene holds. Adding an instance reserves room for its kind's BVH
in the ray source, about 30 bytes an instance in doubling steps, so
add_instance can fail with SceneError::DeviceLimit when the ray source is
nearly full. All opaque geometry participates in closest-hit visibility. Under
Moving only a moving nearest hit supplies secondary radiance: a ray finds its
nearest moving hit, then tests static visibility to it, and a ray that meets no
moving object walks no static geometry. Under All a ray takes its nearest hit
of either kind, leaving the reflecting surface's own triangle, so an off-screen
static wall reflects as it stands rather than as its probe recorded it; every
ray then walks the static geometry, which is what All costs over Moving on
the portable BVHs, so it is meant for hardware ray tracing.
On an Apple M5, over a glossy 1 km strip with posts, boxes and 60 moving boxes
at 960×540 with full-resolution SSR, the world reflection rays pass took
0.49 ms under All against 0.22 ms under Moving on the portable BVHs, and
0.11 ms against 0.09 ms in hardware.
Neither is on by default or in a preset. Rays are traced only where a
pixel needs one: a classification pass lists the half-resolution pixels whose
surface takes world-space reflections and that screen-space reflections did
not resolve, and the trace runs over that list, as AMD FidelityFX SSSR traces
its rays, so a frame with no such pixel pays the classification (about
0.07 ms at 1920×1080 on an Apple M5) in place of the trace. The stage then
costs about 0.21 ms there with its denoise passes, with or without hardware
ray tracing, against 0.35 ms before with it, on the streaming example, which
traces no world-space ray. Wicked Engine's RT reflection resolve, temporal and
bilateral upsample passes denoise the rays. The result is
premultiplied radiance with the share of rays that hit in alpha, and it composites as
ssr.rgb + (world.rgb + environment * (1 - world.a)) * (1 - ssr.a), so misses
keep the probe and sky specular. Under Moving a static nearest hit also keeps
that fallback, while blocking moving objects behind it. Switching world reflections or SSR off
releases world history. Camera cuts, missed effect frames, a different scene and
resize restart accumulation from current data.
Temporal anti-aliasing
Settings::antialiasing (settings::Antialiasing) is TAA, SMAA, Off, FSR2 or FSR3;
Preset selects TAA on High and SMAA on Low. TAA is derived from DiligentFX in sgl-post-fx,
integrated as Diligent's Hydrogent renderer does:
- The frame renders with a 16-sample Halton jitter and a −0.5 texture mip bias. Motion vectors (the G-buffer's motion target) stay unjittered; the sky's follow the camera's rotation, as a background at infinity does. Motion is capped at two screens along its longer axis; a surface or sky direction that was behind the last frame's camera gets that length, so every temporal effect drops the history it reprojects by motion. The reflections' temporal passes likewise take no history by a reflection hit that was behind the last frame's camera, and Crystal's and TAA's depth tests none for a surface that was.
- SSR and TAA need
perspective's infinite reversed-Z projection; with any other camera SSR is off and SMAA replaces TAA. - TAA resolves the complete linear HDR frame, including reflections, fog, effects, mist and heat shimmer, before bloom and tone mapping.
- It uses Catmull-Rom history sampling, depth disocclusion and a variance
clip, with
sgl-post-fx's motion-adaptive history (Filament's): while the camera and the surface at a pixel are still, only partial rectification and slower feedback, which steadies subpixel detail; full rejection returns, held for twelve frames, across the view on camera motion (beyond f32 rounding of its matrices, wherever it is from the origin), an instance added, removed, shown or hidden, a static instance moved, a model or its geometry replaced, aScene::set_materialedit that changes what is drawn (faces, visibility group, alpha mode, cutoff, blending or shader) and a changedFrameInput::visibility_mask; and locally on motion, a moving instance's included, whose motion vectors arm the pixels it covers and leaves rather than the whole view, and on depth disocclusion, at any distance: the sky and far surfaces settle at rest like near ones, and sky revealed or covered counts as a disocclusion however far the surface. Depth disocclusion follows moving surfaces by the G-buffer's depth motion, so a surface the camera follows, or one moving towards it, keeps its history. - What changes at a pixel without a motion vector of its own is rejected
there as motion is, at rest too: blended surfaces, additive effects, mist,
heat shimmer, opaque surfaces whose
normal layers move and opaque surfaces whose
shader reads the time or whose shader's
parameters or instance data the game changed, by the reactive and
transparency-and-composition masks they write for FSR (in proportion to
them while they mark a pixel, and at full strength for a hold after, so
even dim content leaves no trail), and the pixels whose 3x3 neighbourhood
of 32-pixel tiles holds motion of a pixel a frame or more (at least 32 and
up to 63 pixels from it), by the largest motion in that neighbourhood
(motion blur's tile reduction, at the render size), so a deforming or
skinned surface leaves no ghost where it was. Slower motion is left to the
resolve's own closest-motion search.
Elsewhere at rest TAA keeps its resting stability. The masks are held
only while the frame can mark them; the reduction's tile targets, 1/32 of
the render size, while TAA runs (timing group
TAA motion reach).
SSR and TAA share DiligentFX's post-effect context. History restarts with
SSR's, and a restarted frame renders without jitter. As Godot's TAA, it keeps
history for fast motion that is consistent between frames, rejects it
gradually where motion changes by more than 2.5 pixels per frame (none left
at about 96 pixels), and clips it towards the neighbourhood mean within a
variance box that narrows with speed, to none at 2% of the screen per frame:
fast motion resolves softened rather than aliased. Upstream rejects by speed
(sgl-post-fx PROVENANCE.md DFX-14). As Filament's, the box never reaches
past the neighbourhood's own range, so the resolve creates no fringe
brighter or darker than the scene at an edge in motion.
SMAA
SMAA 1x runs on the tone-mapped scene at the scene size, before it is
resampled to the output and dithered
(src/stages/post/smaa/README.md), so the
exposure does not change which edges it finds. It runs at
Settings::smaa_quality (settings::SmaaQuality), SMAA 2.8's presets:
Low, Medium (the default), High and Ultra. They search up to 4, 8, 16 and
32 steps of two pixels each way along an edge, at a contrast threshold in
sRGB-encoded display colour of 0.15, 0.1, 0.1 and 0.05; High and Ultra also
detect diagonal lines and corners.
FSR
FSR2 and FSR3.1.4 come from the sp-fidelity port (SDK
1.1.4) on sp-fidelity-wgpu, integrated in
src/stages/antialiasing/fsr.rs as AMD's
documentation and FSR sample describe; that file's header lists each input and
its source. Choose Antialiasing::Fsr2 or Antialiasing::Fsr3; the single
antialiasing setting makes them mutually exclusive with each other, TAA and
SMAA. FSR3 supplies upscaling only, without frame generation. Both versions
share FsrQuality and the controls below. Defaults remain TAA on High and
SMAA on Low. They antialias like TAA while upscaling:
Settings::fsr_quality(settings::FsrQuality) sets the render size: Native AA renders every scene pixel; Quality, Balanced, Performance and Ultra Performance render 1/1.5, 1/1.7, 1/2 and 1/3 of it per dimension.View::render_size()is the size of every pass up to antialiasing;View::scene_size()stays theSceneResolutionsize, which FSR outputs and bloom and tone mapping use.- The frame renders with FSR's jitter sequence and a texture mip bias of
log2(render / scene) - 1. FSR reads the linear HDR frame, the unjittered motion vectors and depth, the frame's exposure, andFrameInput::frame_time_ms. FSR does not sharpen: post sharpens its frame as any other (Sharpening). The camera's blended surfaces, additive effects and mist also write the reactive and transparency-and-composition masks, as AMD's FSR documentation and sample write them from translucent draws (glow's reactivity from its light at the frame's exposure, so it follows what shows, not the scene's light units; a pixel's reactivity at most 0.9 however many draws overlap it), and heat shimmer marks its weight in the transparency-and-composition mask where it covers. Opaque and masked surfaces whose shading changes where they stand still mark the transparency-and-composition mask, as AMD's sample marks its animated textures: those whose material's normal layers move (a lit material, a layer moving at least a repeat per hour) or whose shader reads the frame's time, every frame, and those whose shader's parameters (Scene::set_shader_parameters) or an instance's shader data (Scene::set_instance_shader_data) differ from the last submitted frame's, in that frame alone (for instance data, every instance drawn with the same material; a masked one over its whole footprint, the texels the edit cut out included). The camera draws those materials' surfaces once more, at their depth, before its blended surfaces (timing grouptemporal composition; nothing in a scene without a moving or shaded material). A shader that reads no time, with inputs written unchanged, marks nothing. - Request
graphics_device::fsr_features(&adapter)when creating the device.antialiasingandfsr_qualitytake effect at the nextView::resize, which creates the selected FSR context. Switching versions destroys the previous context and resets temporal history, even at the same resolution. A failure is retained per version; switching to the other remains possible. Where the device lacks the features or the context cannot be created, TAA runs at the scene size:View::antialiasing_in_effect(&settings)reports it andfsr_error()says why. A frame whose FSR dispatch fails is scaled to the scene size without it, and TAA runs from the nextresize, withfsr_error()saying why. The saved choice is unchanged. - FSR needs
perspective's infinite reversed-Z projection; with any other camera the render-size frame is scaled to the scene size without FSR.
Portable spatial upscaling
Settings::upscaling (settings::Upscaling::Off, the default, or On)
controls spatial enlargement from the scene size to the output size. With
On and a smaller scene, SGL3D runs AMD FSR1 EASU after tone mapping
and SMAA, before the final pass, which sharpens it as Settings::sharpening
chooses (Sharpening). It needs no optional
WebGPU feature and adds no temporal history. Equal-size presentation bypasses
it; Off retains the existing linear presentation filter.
Choose the input size with Settings::scene_resolution, for example
SceneResolution::ThreeQuarter or Half, and call View::resize as
usual. UI drawn after SGL3D stays at output resolution. The game chooses
whether to upscale and the scene resolution; the filter's parameters remain
SGL3D's. Measure the combined rendering and upscaling cost
on the game's camera routes, including moving thin geometry and transparency.
This does not make FSR available in WebGPU. Native FSR still reconstructs the HDR frame from render size to scene size; spatial upscaling, when chosen, only enlarges the final scene to output size. Existing settings retain their presentation behavior because spatial upscaling is opt-in.
Sharpening
Settings::sharpening (settings::Sharpening::Preset, Off or On) and
Settings::sharpness (0..=1, AMD's scale, 0.8 by default as AMD's FSR
sample) sharpen the displayed image once, with AMD's RCAS in post's final
pass, after tone mapping, SMAA and spatial upscaling and before the output
encoding and dither: TAA, SMAA, unantialiased, FSR2/FSR3 and spatially
upscaled frames alike, natively and in the browser. Preset is on at High,
and at Low only where FSR is in effect or upscaling is On. It keeps no
history. Its cost is one full-screen pass of five texel loads at the output
size (timing group sharpening), and, without SMAA at the output size or
spatial upscaling, one output-size RGBA16F target the frame is tone mapped
or resampled into first. Under spatial upscaling or SMAA at the output size
it adds no pass: the final pass sharpens as it presents.
Ambient occlusion
use AmbientOcclusionQuality;
settings.ambient_occlusion = High; // Settings: a quality level
input.ambient_occlusion_radius = 0.5; // FrameInput: consumer-authored metres
The default is Off. Low/Medium/High/Ultra select XeGTAO's 4/8/18/54 samples at full render resolution with spatial and temporal denoising. The consumer persists this choice and includes it in complete Low/High preset bundles. Enabled AO adds no geometry pass: it adds XeGTAO's depth mip, visibility and denoise passes after opaque shading, over its depth and normals, and reflection source completion's read of the ambient light. Measure that complete cost.
Sky diffuse and surviving hemisphere fill are attenuated. Opaque shading records that ambient light beside its unoccluded colour, and reflection source completion takes the share the visibility hides out of the colour, never below zero, before adding specular: its diffuse share linearly, and the specular multiple scattering it carries, most of a rough metal's ambient light, by the base lobe's specular occlusion. Environment and baked-probe specular (including SSR's fallback where its rays miss) takes Filament's desktop specular occlusion: Lagarde's specular AO from the visibility, with GTAO multi-bounce on the base lobe's F0, so bright metals keep most of their reflection. Ambient occlusion reaches only its radius; beyond it, where the irradiance volume or the dynamic GI volume lights a surface, the volume's sky visibility multiplies the visibility for the sky's share of that specular alone. Screen-space reflection hits, direct light, emission and baked direct/bounced irradiance retain their existing ownership. Probe captures and secondary rays do not consume camera-space AO. There are no substitute contact shadows. A material's occlusion map joins it: each opaque receiver takes the lesser of the two visibilities, as Filament and Bevy take them, and every other view its material's alone; baked diffuse takes the material's alone. The map also shadows direct light, which the frame's ambient occlusion does not (asset limits).
The radius is clamped to 0.01–10000 m (XeGTAO's expected minimum and its
settings' maximum); Settings::ambient_occlusion
alone turns AO off. AO works with centered reversed-Z perspective cameras.
Its view-space reconstruction includes the actual raster jitter used by
TAA or FSR, so its camera rays match the frame's depth and normals.
XeGTAO's sample phase advances with submitted frames in every AA mode. Its
own DiligentFX-derived temporal filter accumulates visibility before lighting,
so noise reduction does not depend on the final TAA or FSR resolve. Reprojection
uses screen and depth motion (including moving receivers), raster jitter and depth rejection; a camera cut, skipped AO
frame, render-size, quality or radius change restarts accumulation. Inspect
moving and settled contacts: screen-space visibility still cannot retain
history where geometry becomes newly visible.
Orthographic, off-axis and forward-depth cameras leave it ineffective while
preserving the saved preference. Single-layer screen geometry cannot establish
offscreen or thin-occluder visibility; the pinned XeGTAO catalogue
details approximations and numerical evidence.
With diagnostics,
View::diagnostic_target(DiagnosticTarget::AmbientOcclusion) returns the
last frame's R32Uint visibility texture (0..255), or None when AO did not
run. It shares the dimensions and receiver correspondence of the Depth and
Normal targets; it does not perform readback.
Screen-space indirect light
use ScreenSpaceIndirect;
settings.screen_space_indirect = Low; // Settings: Off, Low or High
input.screen_space_indirect_radius = 5.; // FrameInput: reach in metres, 1–25
Off by default and in no preset. Diffuse light bouncing between nearby surfaces on screen, a lit wall onto the floor beside it, a coloured surface onto its neighbour: the scale the dynamic GI volume's probes are too far apart to hold. After ambient occlusion the opaque stage searches each half-size pixel's horizon (Low 24 samples, High 48) over ambient occlusion's depth pyramid, the G-buffer's normals and the frame's lit colour, which holds the last frame's bounce, so further bounces converge; denoises; and accumulates up to 16 frames. The next frame's opaque surfaces take that light as baked light, beneath their material's occlusion and outside the ambient light ambient occlusion occludes, and the share of their indirect diffuse light it covers (the environment's, the fill's, a bake's and the GI volumes') gives way to it, so no bounce is counted twice (Screen-space indirect light, D-65).
Its limits are part of what it is:
- It is screen-space. Light whose source is off screen, hidden or facing away from the receiver is absent, and appears and fades as the source enters and leaves the frame.
- The bounce is one frame late and follows a lighting change over about 16 frames.
- It reads lit colour, so an emissive fixture whose light a scene light
stands for (
emits_into_gi: false) still lights what is near it, as Godot's SSIL does.
Blended surfaces, probe captures and ray hits take none. It needs a centred
reversed-Z perspective camera, as ambient occlusion does; any other camera
leaves it off. A camera cut, a resize, a level or radius change and a frame
without it restart it (its history: SI-1 to SI-6).
It holds no targets while off, and while on 16 bytes a render pixel at half
size, with ambient occlusion's depth pyramid (about 5 bytes a render pixel)
where ambient occlusion is off. On an Apple M5 at 1920×1080 on Bistro (bistro-golden,
the least-contended of several runs on a shared machine) its passes took
2.2–2.9 ms at Low and 3.7–5.1 ms at High natively, the depth pyramid
included, against 2.2–2.7 ms for ambient occlusion at Medium, and the fused
opaque pass took about 1.1 ms longer to read the kept result; in Chrome the
passes took 2.7–3.2 and 3.4–4.2 ms. Measure the game's own routes.
The port's provenance and departures.
Baked specular probes
Receivers outside screen-space reflections, and rays SSR misses, take their environment specular from caller-authored static probes: local image-based lighting with parallax-corrected cubemaps (Lagarde and Zanuttini, SIGGRAPH 2012), as HDRP, Unreal, Godot, Wicked and Bevy layer it under SSR. The consumer owns validity across world, lighting, environment and GI variants, and clears the collection when it has no matching bake.
use ;
// Each probe: capture `center`, a rigid `world_to_local` frame, an
// `influence` box with per-axis `blend` distances, an optional `proxy` box
// for parallax, and its prefiltered `radiance`. SGL uploads without capturing.
scene.set_baked_specular_probes?;
// Clear after a content or lighting change the game has no bake for.
scene.set_baked_specular_probes?;
influenceandblend: where receivers use the probe. Its weight is one atblendinside each face on that local axis, falling linearly to zero at the face (Godot's blend distance, given per axis here, without Godot's squared weight or its clamp of the distance to the box's half extent, so a blend wider than the half extent on an axis caps the probe's weight below one); zero blend is a hard edge. Influences may and should overlap: a receiver's probes are normalised by their total weight, so neighbours whose blends meet partition it exactly, and where the total is below one, as at the collection's edge, the sky fills the rest. Each box (influence and proxy) needsmin < maxand a finitemax - minon every axis.proxy: the geometry the capture sees, for box projection. Keep it separate from the influence and as large as the space: a corridor's proxy spans the whole corridor, and an opening's proxy extends well past it.Nonetreats what the probe sees as distant, as for open outdoor spaces.radiance: a cube with perceptual roughness level/6 at miplevel, seven levels from a power-of-twoface_sizeof at least 64 (Filament and Bevy use the same roughness-to-mip mapping). Up to 256 probes of one face size and texel encoding, taking six array layers each, all within the device'smax_texture_array_layers(graphics_device::limitsrequests the adapter's; WebGPU's default of 256 layers holds 42 probes). Captures returnSpecularProbeTexels::Rgba16Float; shipBc6hUfloatblocks, an eighth of the size on disk and in memory, compressed offline with a BC6H encoder such as Intel's ISPC Texture Compressor (as Unreal compresses its captures). Installing BC6H needs the device featurewgpu::Features::TEXTURE_COMPRESSION_BC.
Capture faces must also fit their padded RGBA16F readback, all six faces and
roughness levels, within the device's max_buffer_size; oversized captures
return ProbeError::InvalidDimensions before rendering. Installed probes
have no readback-buffer requirement.
For authoring, offline or while a level loads, install the static instances'
fixed-light atlases, then
renderer.capture_specular_probe_async(&device, &queue, &mut scene, &mut view, &input, &settings, center, face_size).await?, which borrows view's shadow
maps and opaque stage and is not a frame (natively also the blocking
capture_specular_probe) renders six faces of the static capture-visible instances
and the reflection sky of input's environment with input's lights, and
GGX-prefilters them with filtered importance sampling. Each face renders at
2048 texels a side (or face_size, if larger) in its own submission and is
box-averaged to face_size, so mip 0 holds each texel's area-averaged
radiance and an emitter thinner than a texel keeps its energy rather than
filling the texel; a capture holds about 80 MB of targets while it runs.
It includes fixed emission and the scene's lights (baked ones only on
surfaces without baked lighting), with their static casters' shadows from
the local-light atlas, and excludes moving instances, effects and
atmospheric post; the camera is unused. A capture runs outside a frame,
after finish_frame and before the next render: it shares the renderer's
shadow face views, cascade layers and local-light atlas with the frame. It holds the renderer and the scene until it resolves, so
the game draws no frame meanwhile; in the browser it awaits WebGPU's map of
its readback and the page keeps running. That readback is its only
suspension: a capture dropped there has changed what a finished one changes
(the shadow maps at its quality, its static local-light layers, pipelines
specialised for it), and the next frame sets them for itself as after any
capture.
Like the frame, it draws only materials whose visibility group
input.visibility_mask selects, so a caller can leave geometry out of a
probe as a reflection probe's culling mask does.
Captured surfaces take their environment specular from the installed
collection, as source completion does at runtime, so capturing every probe
again with the first pass installed bakes one more bounce (Unity's reflection
bounces). The sky it records is the one reflections fall back to
(FrameInput::reflection_environment), not the camera backdrop, so probes and sky agree
where they blend. It never writes files: the game owns serialization, format
version and explicit refresh.
At runtime source completion first culls the collection per 32x32-pixel tile
(src/stages/reflections/probe_culling.wgsl, a port of Wicked Engine's tiled
light culling with its 2.5D depth mask), so each receiver walks only the probes
whose influence can reach its tile's depth range. The forward pass binds no
probes. Captures and world-space ray hits, which have no tiles, walk the probes
listed in their cell of a world grid built when the collection is installed
(src/scene/probe_grid.rs, following Wicked Engine's surfel grid), so each
walks only the probes whose influence can reach that cell.
Visible work and pass selection
The camera's opaque and masked surfaces and each directional shadow cascade
draw from lists the GPU builds every frame (GPU draw
lists), with nothing to configure. After the
deform pass, a cull stage tests each instance's meshes (the draw candidates
the scene keeps up as it is edited) for the view's population (the camera's
visible instances, a cascade's capture_visible ones whose material casts,
both under the frame's visibility mask), chooses the camera's level of
detail, tests the view's frustum, then tests each of the chosen mesh's
sections, the 128-triangle leaves of its range hierarchy, and appends those
that pass to their set's draw. A set is what draws with one pipeline and one
material: a material, whether its instances' poses mirror and whether they
deform, and the positions slab its meshes' positions lie in (one, unless the
scene's geometry passes a slab's size). Each set draws with one indirect
draw, whatever its instances and their mobility, so recording a view costs
the same at a hundred instances as at a hundred thousand. A cascade's
casters read each vertex's position from the 12-byte positions the scene
keeps for shadow casters, not the 32-byte vertex records the camera pulls,
and a cascade's opaque set draws a second, indexed draw of its sections
whose triangles pair as quads do (each even triangle and the next are
(a, b, c) and (a, c, d): quads split [0, 1, 2, 0, 2, 3] in index order,
as the examples' meshers and Blender give them), so the corners a pair
shares are shaded once: a depth-only pass is bound by the bytes and
vertices it fetches. Other index orders, and masked materials, keep the
pulled draw. The CPU walks no instance for these views: it builds
the camera's blended list (culled per instance, sorted back to front), the
local-light shadow faces and probe captures. Hardware culling preserves
authored single/double-sided and mirrored materials. Each probe face uses
its own camera; shadow and scene-ray populations are separate.
A GPU-built list draws its sets in their order and each set's sections in
the order the cull appended them, so two coplanar surfaces of different
draws have no defined winner at equal depth: give a coplanar overlay a depth
offset or make it a decal. wgpu validates indirect draws with a compute pass
before each render pass that issues them, on native backends, unless the
game creates its instance without InstanceFlags::VALIDATION_INDIRECT_CALL
(set by default); the lists' few draws need no validation, so a game may
clear the flag, and keeping it costs that small pass.
Settings::occlusion_culling (off by default) adds two-phase occlusion
culling to the camera's list, as Bevy's GPU culling runs it: the early phase
also tests each instance and section at its last frame's pose against the
last submitted frame's depth pyramid (each texel the farthest depth it
covers), and sets aside what lies behind it; the opaque stage draws the
rest into the G-buffer; the late phase builds the pyramid from that depth
and tests what was set aside again, at this frame's pose; the G-buffer pass
draws what it passes, and the pyramid is built once more from the complete
depth for the next frame. Lighting then shades both sets once. Something
hidden last frame and visible now is drawn in the same frame, so nothing
appears late; a camera cut or a resize tests nothing early. The opaque stage
runs as two passes while it is on (the fused pass cannot be split), so it
pays only where a frame submits much hidden geometry. On an Apple M5 at
1920×1080 it cost 0.2–0.5 ms a frame natively on Metal on the streaming
and irradiance_volume examples' routes, though it culled up to 92% of the
camera's triangles, and saved 0.9–1.4 ms in Chrome over a headroom-sized
window seen from a walker's eye (#24). It needs six storage textures a shader stage, which graphics_device::limits
requests from the adapter; a device with fewer culls by frustum alone, and
View::occlusion_culling_in_effect reports it. The directional cascades
cull by frustum alone.
The CPU-built lists draw instanced: the instances that draw the same mesh of a model with the same material, face culling and mobility, after their own culling and level-of-detail choice, share one draw per index range, as Bevy batches its phases. Shadow and capture draws merge wherever they are; blended ones only where they follow one another back to front. In every list each instance keeps its own pose, motion, ambient cube and source identity: a draw reads every instance's record from the scene's object buffer. The instances example places many props of three models and prints the camera's sections and the CPU time each frame took to record:
Devices with the attachments for it write stable geometry and primary lighting
in one eight-target pass, with ambient occlusion on or off. Only devices without
them draw a geometry pass before lighting. Use graphics_device::limits when
requesting the caller-owned device.
Material normal_scale, coat_normal_scale and bump_scale must be finite;
negative and zero scales are allowed. add_materials, add_asset and
set_material return SceneError::InvalidMaterialFactors for non-finite
scales; a rejected edit retains the previous material.
Scrolling normal layers
asset::Material::normal_layers and SurfaceMaterial::normal_layers draw a
material's normal map as two layers moving across its surface: water's
waves, with no geometry uploaded per frame. Each NormalLayer has a
velocity (the material's UV units per second along U and V), a scale
(repeats of the map per UV unit, positive) and a strength (how much of its
slopes the surface takes, with normal_scale). The layers' height fields
add, so their slopes add (Barré-Brisebois and Hill's partial derivative
blend), as Wicked Engine's water and Bevy's water example scroll one map
twice or more.
- Time.
FrameInput::elapsed_seconds, the game's presentation clock in seconds as anf64, places the layers, so every view of a frame (the G-buffer, the receiver pass, blended surfaces, probe captures and world-space ray hits) sees one surface. SGL3D reduces it modulo an hour on the CPU and rounds each layer's speed to whole repeats of its map per hour (steps of 1/(3600 ×scale) UV units per second, so at most 1/7200 of a repeat per second off, and a layer slower than that stands still), so the waves keep their precision however long a session runs and nothing jumps when the hour turns. - Requirements. A normal map that repeats on both axes, finite
velocities and strengths, positive finite scales, and at most 2^24
repeats of the map per hour (about 4660 a second) along each axis;
otherwise
add_materials,add_assetandset_materialrefuse the material withSceneError::InvalidNormalLayers.set_materialchanges the layers like any value; the glTF loader leaves themNone. - Cost. Two normal map samples in place of one in each pass that evaluates the material. Moving layers are no scene edit: a static instance can hold the material, and its shadow layers stay valid.
- History. The layers change shading, not geometry: they write no motion. TAA and the reflection methods' accumulation reject what they change by their colour clamps, as for any change of shading. FSR takes a blended surface's changing shading, a receiver's included, from the reactive and transparency-and-composition masks blended surfaces write, and an opaque or masked surface's from the transparency-and-composition mask its moving layers mark (FSR), as AMD documents for animated textures: FSR then keeps no detail locked there.
The water example scrolls a procedural wave map over its shader's waves.
Alpha-masked and blended materials
asset::Material::alpha and SurfaceMaterial::alpha are an AlphaMode; the
glTF loader reads alphaMode and alphaCutoff (0.5 when absent). A masked
cutoff must be finite and nonnegative, as glTF bounds it; the scene refuses
others with SceneError::InvalidAlphaCutoff. The base
alpha is the material's base alpha times the vertex colour's and the base
map's.
AlphaMode::Opaqueignores alpha.AlphaMode::Mask { cutoff }(foliage, fences, grilles) is opaque where the base alpha reachescutoffand cut out below it, as Bevy'salpha_discarddoes: in every opaque pass, probe capture and shadow (the directional cascades and the local-light faces and their cached layers), and at ray hits, where the portable ray traversal's nearest, any-hit and visibility queries pass through cut-out texels. Masked materials draw with their own pipelines, so opaque ones keep early depth testing.AlphaMode::Blend { receives_screen_space_reflections, keeps_specular }(glass, screens, holograms, water) is blended with its alpha over what lies behind it. Withkeeps_specular: false, as glTFBLENDloads, alpha is coverage and fades all of the surface's light, Filament'sfade; withtrue, Filament'stransparent, alpha fades its reflected and transmitted diffuse light and its emission, so its reflections and highlights keep their full strength, as glass's do: a windscreen at alpha 0.1 reflects as brightly as at 1. The transparent stage draws blended surfaces back to front, sorted by the view depth of each mesh's bounds centre as Bevy'sTransparent3dphase is, onto the composed frame and, while a screen-space reflection method traces it, into the reflection input, before additive effects and mist. They are lit as opaque surfaces are: the directional lights and their shadow, the clustered point, spot and rectangle lights, baked light, the environment, and the installed probes' and reflection sky's specular; then fogged. Unmarked (false, as glTF loads them), they write no depth, motion or G-buffer, so ambient occlusion, screen-space reflections and temporal antialiasing see what lies behind them. They cast no shadow and rays pass through them, as Godot leaves alpha-pass materials out of its shadow passes, and probe captures leave them out. Order is per mesh: split intersecting or interleaved blended meshes. Order-independent transparency is not provided.
Scene::set_material changes a material's alpha mode like its other values.
The offscreen example's --alpha shows both modes.
Transmissive glass and water
A material with transmission above 0 (KHR_materials_transmission, which
the glTF loader reads with KHR_materials_volume and
KHR_materials_dispersion) lets the light behind it through, refracted:
glass, water, clear plastic. Its values, on asset::Material and
SurfaceMaterial:
transmission(0..=1): the share of its diffuse light the transmitted light replaces;asset::Material::transmission_texture's red channel multiplies it.thickness: the depth of the volume beneath the surface in the mesh's units, which the instance's scale scales; 0 is a thin wall, which bends nothing;thickness_texture's green channel multiplies it. A volume draws its front faces alone, but for a material with a shader, which keeps itsdouble_sided.attenuation_distance(metres, positive,f32::INFINITYfor none) andattenuation_color(linear, 0..=1): white light takes the colour after that distance through the volume (Beer-Lambert).ior: its refraction too (1.33 water, 1.5 glass); its roughness blurs what it shows.dispersion(20 over the Abbe number: 0.33 crown glass, 0.36 water): each colour channel refracts at its own IOR.
let glass = SurfaceMaterial ;
A transmissive material is drawn with the blended surfaces whatever its
alpha mode, its alpha still covering as the mode says (whole when
Opaque). Like them, and unlike three.js and Bevy, it writes no depth or
G-buffer, takes no ambient occlusion and casts no shadow (no coloured
shadows), rays pass through it (reflections and global illumination see
what lies behind it) and probe captures leave it out. Moving glass has no
motion vectors unless it is a Blend receiver of screen-space
reflections, which writes depth and motion. What it shows through it is
the opaque frame behind it (surfaces, sky and their reflections), not other
blended or transmissive surfaces behind it. Give glass its own material: a
transmission map's zeros do not make the rest of a material opaque. Decals
change its diffuse colour, which tints what it transmits. Water seen from
below shows nothing, as only its front faces draw.
The transparent stage copies the composed frame, with its mips, in each
frame that shows a transmissive material, on a device of the Extended
binding tier (timing group transmission copy). On
Basic, and in what screen-space reflections see of it, a transmissive
surface blends the light behind it through unrefracted and unblurred,
dimmed by the mean over colour channels of what the refracted light would
pass, so without its tint.
Blended receivers
A blended material marked receives_screen_space_reflections: true is a
receiver: water or glass that reflects the scene in front of it. Where it is
the nearest receiver it is the surface that screen-space reflections trace
and temporal effects reproject, as HDRP's Receive SSR Transparent materials
are:
- After the opaque stage, a receiver pass draws the camera's receivers over a copy of the opaque depth, the nearest winning, with the frame's jitter: their depth, their traced lobe's normal and roughness (the coat on a coated receiver, else the base) and their motion.
- Crystal or Velvet traces them as it traces opaque surfaces, at the same resolution, cutoff and fade, through the same accumulation (Reflections).
- The blended draw composes the result into the traced lobe in place of its probe and sky specular, by the formula opaque composition uses. The opaque surface seen through a receiver keeps its own probe and sky specular, and world-space rays skip it.
- TAA, FSR and motion blur reproject and blur a receiver's pixels by the receiver's depth and motion. The pass runs while the scene holds a receiver and SSR, TAA, FSR or motion blur runs, so with SSR off and TAA on, TAA still reprojects a receiver by its own motion rather than by what lies behind it.
Limits: the nearest receiver at a pixel alone reflects; a receiver behind
another, and one seen in another's reflection, show their probe and sky
specular. The reflection is scaled by the receiver's alpha with the rest of
its colour (glTF's coverage blend, as Godot and Bevy blend), unless the
material keeps its specular, which stays full. What lies behind is blended
under it undistorted (refracted where the receiver is transmissive on the
Extended binding tier), and it reprojects and blurs by
the receiver's motion, so a receiver moving against its background trails the
background, not its reflection. World-space rays do not fill a receiver's
misses; probe and sky specular do. Unlit receivers, additive effects and mist
reflect nothing.
The game supplies the receiver as any surface: its mesh, the normals it
animates, and its material's roughness, F0 and coat. Move water's waves
with its material's shader, a vertex function
that displaces static chunks with the frame's time, and add their fine
detail with scrolling normal layers: neither
uploads anything per frame, so the receiver can be static instances, and
many water chunks cost nothing per frame beyond their vertices and pixels.
A mesh replaced every frame belongs on a moving instance, so that the
replacement is no static edit; each replacement prepares the model again
(PreparedModel::new, its BVH included) and Scene::set_model places and
copies it. A deforming model animated with set_instance_deformation is not
seen by rays, nor is a shader's displacement. The renderer allocates the
surface's targets (a depth and an RGBA16F layer, 12 bytes per render pixel)
in the first frame whose scene holds a receiver and keeps them from then
on; a renderer that has never rendered a receiver pays nothing. The water
example is a lake of shader water that receives
reflections; it prints the GPU time of the passes the water touches, what it
holds and uploads, and, with --morph, the same waves as morph targets, or
replaced every frame by set_model (set-model), with the CPU time
preparing and replacing it take:
Programmable surfaces
A game gives a material its own vertex and surface functions in WGSL: one
module added to the scene (Scene::add_shader), which a material names
once added (SurfaceMaterial::shader:
MaterialShader { shader, displacement_bound }, through
Scene::set_material; an authored asset::Material has none). SGL3D
composes the module into its own programs and calls the functions from
every pass that rasterises the material, so colour, depth, shadows, the reflections' surface,
temporal antialiasing and motion blur see one surface: water's waves,
vegetation in the wind, glass whose thickness varies across it or that
absorbs over the length of each view ray inside it. The
equations are the game's; SGL3D ships none (D-35).
A shader is content: it changes what a surface is, never how SGL3D renders
it, and nothing about it is a setting.
The module defines ShaderParams, material_vertex and material_surface,
over the contract SGL3D declares, shading/shader_contract.wgsl, verbatim:
// The shader contract (the package README's "Programmable surfaces";
// specs/sgl3d-architecture.md, Shader contract): what a game's WGSL module
// (Scene::add_shader) receives and returns. A game's module defines
// `struct ShaderParams`, `material_vertex` and `material_surface` over these
// structs, and from material_surface may call the scene depth functions its
// program's provider declares (shader_scene_depth_none.wgsl,
// shader_scene_depth.wgsl): scene_depth_available, scene_depth,
// scene_depth_behind and scene_volume_path; nothing else SGL3D declares is
// the contract. SGL3D's own programs compose shader_default.wgsl in its
// place, whose functions return their argument.
// The pattern is Filament ef1a133's materialVertex() and material()
// (shaders/src/surface_main.vs, surface_main.fs,
// surface_material_inputs.vs and .fs) and Godot b130438's vertex() and
// fragment() (scene_forward_clustered.glsl), which every pass of a material
// compiles.
// A vertex in and out of material_vertex, in the mesh's own units and axes,
// after SGL3D's skinning and morphing and before the instance's pose:
// `normal` unit and `tangent` xyz a unit vector in the normal's plane, w its
// handedness (+1 or -1), at rest and after skinning, while morph targets add
// their deltas without renormalising or re-orthogonalising (as Bevy's
// morph_vertex, which the deform stage ports), so a morphed vertex's frame
// is only approximately orthonormal; morphs that cancel a tangent, or a
// skin that collapses it, leave its xyz zero with its handedness, which a
// shader that normalises the tangent guards. A vertex without an authored
// tangent (none, along the normal, or handedness not +1 or -1) gets an
// arbitrary one in the normal's plane, handedness +1, never zero, which a
// shader cannot tell from an authored one: a shader used on meshes without
// authored tangents derives its frame itself, as from screen derivatives
// in material_surface (as SGL3D's own normal maps do), or has such meshes
// flagged through its ShaderParams or shader data; `color` linear RGB and
// alpha, as asset::Vertex::color;
// `shader_data` the mesh's per-vertex data (PreparedModel::with_shader_data),
// zero without any; `custom` what the shader passes to material_surface,
// interpolated, zero in.
struct MaterialVertex {
position:vec3<f32>,
normal:vec3<f32>,
tangent:vec4<f32>,
uv:vec2<f32>,
color:vec4<f32>,
shader_data:vec4<f32>,
custom:vec4<f32>,
}
// What material_vertex evaluates at: the instance's pose `model`, its
// shader data `instance` (Scene::set_instance_shader_data), the frame's
// `time` (FrameInput::elapsed_seconds in f32, which loses precision over a
// long session) and `phase` (where that time falls in the hour over which
// material animation repeats exactly, 0..1), and whether this is the
// evaluation at the last submitted frame (`previous`), whose time, phase,
// parameters, pose and instance data it then holds, from which motion is
// measured.
struct VertexContext {
model:mat4x4<f32>,
instance:vec4<f32>,
time:f32,
phase:f32,
previous:bool,
}
// A surface in and out of material_surface: the material's record and maps
// already evaluated at the fragment. `base_color` is linear RGB, the
// record's base times its base map and the vertex colour, its alpha the
// fragment's coverage; `roughness` perceptual; `normal` unit, in the render
// frame's world space on the shaded side, the mapped normal; `specular`
// KHR_materials_specular's strength; `transmission` KHR_materials_
// transmission's share; `thickness` KHR_materials_volume's, in the mesh's
// units; `attenuation` the Beer-Lambert coefficient per metre, finite and
// nonnegative; `ior` at least 1, 0 for an infinite one.
struct MaterialSurface {
base_color:vec4<f32>,
emission:vec3<f32>,
metallic:f32,
roughness:f32,
normal:vec3<f32>,
occlusion:f32,
specular:f32,
clearcoat:f32,
coat_roughness:f32,
transmission:f32,
thickness:f32,
attenuation:vec3<f32>,
ior:f32,
dispersion:f32,
}
// What material_surface evaluates at: the fragment's render-frame
// `position` (displaced), its interpolated `geometry_normal` on the shaded
// side, the unit direction toward the viewer `view` (toward the eye under a
// perspective projection, the camera's backward axis under an orthographic
// one), its `uv` and `color`, material_vertex's `custom`, the instance's
// data, pose and the pose's axis scales `model_scale`, the frame's `time`
// and `phase`, whether it is the material's authored `front`, its `pixel` in
// the pass's target in texels, and its linear `view_depth` in metres.
struct SurfaceContext {
position:vec3<f32>,
geometry_normal:vec3<f32>,
view:vec3<f32>,
uv:vec2<f32>,
color:vec4<f32>,
custom:vec4<f32>,
instance:vec4<f32>,
model:mat4x4<f32>,
model_scale:vec3<f32>,
time:f32,
phase:f32,
front:bool,
pixel:vec2<f32>,
view_depth:f32,
}
// What scene_depth returns at the sky.
const SCENE_DEPTH_FAR:f32=1e30;
// What scene_volume_path returns: the `length` in metres along the
// fragment's view ray inside the volume its material bounds, at most
// SCENE_DEPTH_FAR and never negative, and its `bound`, one of the VOLUME_*
// constants, which says what ends the path away from the fragment. SGL3D
// measures it in the camera's blended draws on the Extended binding tier
// while Settings::volume_paths is on, from depth layers of the meshes of
// the blended materials whose shader calls scene_volume_path, each a closed
// mesh around its volume: the nearest front faces, the nearest back faces
// and the nearest back faces behind those, at each pixel in front of the
// opaque surface.
struct VolumePath {
length:f32,
bound:u32,
}
// No path is measured (every other pass, the Basic binding tier, the
// setting off): length 0. The shader takes its own fallback, such as
// scene_depth_behind or an authored thickness.
const VOLUME_NONE:u32=0u;
// At a front fragment, where the view ray enters: the path ends at the
// nearest back face behind the fragment, where the ray leaves.
const VOLUME_EXIT:u32=1u;
// At a front fragment: the path ends at the opaque surface, with no back
// face between (the volume meets the opaque surface, or is open).
const VOLUME_OPAQUE:u32=2u;
// Where another volume's faces hide the fragment's own segment: at a front
// fragment behind two back faces, which leave its own exit unmeasured, the
// length is to the opaque surface; at a back fragment behind another back
// face, which hides where its segment starts, the length is from the eye.
// Either is an upper bound.
const VOLUME_HIDDEN:u32=3u;
// At a back fragment, seen from inside where the ray leaves: the path
// starts at the nearest front face in front of it, where the ray entered,
// where no other back face lies between.
const VOLUME_ENTRY:u32=4u;
// At a back fragment with no front face in front of it (the camera is
// inside, or the near plane cut the entry): the path starts at the eye.
const VOLUME_EYE:u32=5u;
Beside the contract, a program declares the scene depth functions, which
only material_surface and the functions it calls may call
(shader_scene_depth.wgsl in the camera's blended draws on the Extended
binding tier, shader_scene_depth_none.wgsl everywhere else), and the
game's module defines the rest:
// Declared by SGL3D. Whether this draw reads the scene depth: a blended
// draw of the camera on the Extended binding tier.
fn scene_depth_available()->bool
// The linear view depth in metres of the opaque surface at `pixel`:
// SCENE_DEPTH_FAR at the sky, 0 where unavailable.
fn scene_depth(pixel:vec2<f32>)->f32
// The metres along the fragment's view ray to the opaque surface behind
// it, 0 where it is in front or unavailable.
fn scene_depth_behind(ctx:SurfaceContext)->f32
// The metres of the fragment's view ray inside the volume its material
// bounds, and what ends it (a VOLUME_* constant): VOLUME_NONE and 0
// where the volume layers are not held.
fn scene_volume_path(ctx:SurfaceContext)->VolumePath
// Defined by the game's module. A function that changes nothing returns
// its argument.
struct ShaderParams { /* the game's fields, WGSL's uniform layout */ }
fn material_vertex(v:MaterialVertex,ctx:VertexContext,params:ShaderParams)->MaterialVertex
fn material_surface(s:MaterialSurface,ctx:SurfaceContext,params:ShaderParams)->MaterialSurface
-
The vertex function runs in every pass's vertex shader, after skinning and morphing and before the pose: the G-buffer, lighting and fused passes, the receiver pass, both blended draws, FSR's composition pass, probe-capture faces, the directional cascades and the local-light shadow faces. The camera's passes that write motion (all but the blended draws and FSR's composition mask) evaluate it again at the last submitted frame, with
ctx.previoustrue and that frame's time, phase, parameters, instance data and pose, so TAA, FSR and motion blur reproject what it moves; the game writes no motion. A function that displaces writes matching normals (and tangents, where a material is anisotropic); SGL3D makes a changed normal unit and the pose's transforms keep the frame perpendicular. -
The surface function runs where SGL3D has evaluated the material's record and maps at a fragment, before decals, roughness filtering and the coat's normal, in every pass that builds a surface (an unlit material's base colour and emission among them), and for coverage alone in FSR's composition pass and a masked material's shadow casters. Custom caster coverage receives the same mapped material fields and mapped base normal as camera coverage, on the device's material binding tier. Cached local shadows track changes to those fields and animated normal layers too. A field it does not set keeps the record's and maps' value. The pipelines are the record's: its alpha mode, transmission, side and receiver flag choose them, so
transmissionandthicknesstake effect only on a material whosetransmissionis above 0, where they drive SGL3D's one refraction per fragment (the base colour tints what it transmits,attenuationabsorbs it overthickness,iorandroughnessbend and blur it), andiorandspecularset its dielectric reflectance too; aclearcoatit gives a material whose record has none lies on the geometry normal, the coat's normal map being the record's. Coverage (base_color.a, under the record's alpha mode) and transmission are independent controls. A shader material keeps itsdouble_sidedas a volume, shading its back as the medium's exit byctx.front. -
Scene depth is the opaque depth, which holds no blended surface, receiver or effect, in the camera's blended draws on the Extended binding tier; elsewhere
scene_depth_available()is false and both functions return 0. Water's column behind a fragment (scene_depth_behind) gives depth-dependent absorption and a fade into the shore. Scene colour is never sampled: refraction stays SGL3D's. -
Volume paths. A blended or transmissive material whose
material_surfacereachesscene_volume_pathbounds a volume: SGL3D draws its meshes, as their vertex function places them, into three depth layers each frame (the nearest entry face, the nearest exit face and the next exit behind it), and the function returns the length in metres along the view ray inside the volume (VolumePath::length, at mostSCENE_DEPTH_FAR) and what ends it (VolumePath::bound). At an entry fragment (ctx.front):VOLUME_EXIT, to the volume's exit;VOLUME_OPAQUE, to the opaque surface, where no exit lies between (an opaque object inside, or an open volume);VOLUME_HIDDEN, a third crossing whose exit is unmeasured, the opaque bound as its length. At an exit fragment:VOLUME_ENTRY, from the nearest entry in front, with no other exit between;VOLUME_EYE, from the eye (the camera is inside, or the near plane cut the entry);VOLUME_HIDDEN, behind another exit, which hides where its segment starts, the eye's distance as its length.VOLUME_NONE, length 0, in every other pass, on theBasictier and withSettings::volume_pathsoff (Renderer::volume_paths_in_effect). Use it so:- absorb over it: set
thicknessto the length divided by the instance's scale (ctx.model_scale; exact under a uniform scale), the mesh's units the transmission refracts and absorbs over, or supplythicknessfrom the game's own data; take an authored thickness where the bound isVOLUME_NONEorVOLUME_HIDDEN; - never fade coverage by it: entry and exit meet at a finite volume's
silhouette, where the path is 0, so it would erase the surface and its
reflection there; fade into a shore by
scene_depth_behind; - a double-sided volume draws both its entry and exit faces, each
transmitting the opaque frame behind it, so absorb at one: at entry
faces, and at exit faces only for
VOLUME_EYE, giving an exit face behind an entry (VOLUME_ENTRY) no coverage underAlphaMode::Blend; an exit face atVOLUME_HIDDENkeeps its coverage with the authored thickness.
The layers follow the deformed surface and are drawn on the frame's jittered lattice; they keep no history. The path follows the view ray, not the refracted one; a volume inside another (ice in water) starts or ends the outer one's path at its faces; an opaque object inside a volume, seen from inside it, has no blended face in front of it and is not absorbed (cover it with the game's own effect, such as a fog volume while the camera is inside); a masked cut-out still bounds; rays and probe captures see no layers. Cost: in frames whose blended list holds such a material, three copies of the opaque depth and three depth passes over those materials' meshes (timing group
volume layers); three render-size depth targets, held from the first such frame until the setting is off; other frames and materials pay nothing. - absorb over it: set
-
Time and anchoring.
ctx.phaseis the exact long-session clock: a motion with a whole number of cycles per hour repeats exactly, as normal layers do;ctx.timeisf32and loses precision over long sessions. Positions are model-local, so an effect continuous across chunks and render-origin moves anchors on the instance's data (a chunk's world origin, or that origin modulo the effect's period), whichScene::move_originleaves as it is, never on the render frame. -
Culling grows the bounds of the material's meshes and sections, in their units before the pose, by
displacement_bound: the farthest the vertex function moves a vertex, finite and nonnegative (SceneError::InvalidDisplacementBoundotherwise). A vertex moved farther may be culled where it shows.
The Rust side:
Scene::add_shader(ShaderSource { wgsl, label })validates the module and returns itsShaderId, orSceneError::Shader(ShaderError)with why it refused it;remove_shaderrefuses one a material names (SceneError::ShaderInUse); an ended or another scene's identity isSceneError::UnknownShader, as is a material that names one.scene.set_material(queue, id, SurfaceMaterial { shader: Some(..), ..scene.material(id)? })names a shader afteradd_materialsoradd_asset.Scene::shader_parameters_layout(id)is naga's uniform layout ofShaderParams(shader::ShaderParamsLayout: its size and each member's name, offset and size) for the game's#[repr(C)]mirror to check itself against.Scene::set_shader_parameters(queue, material, bytes)replaces a material's block, of exactly that size (SceneError::ShaderParametersotherwise, and for a material without a shader); it starts as zeros when the material gains the shader. Time comes from the frame, so most blocks are set once. Where the material's shader may change what it casts, a new block redraws the local-light shadow faces its instances reach (Local-light shadows).Scene::set_instance_shader_data(queue, instance, [f32; 4])andinstance_shader_datahold an instance's data, zero when it is added; for a static instance a change is a static edit, which redraws the local-light layers its displaced bounds reach.PreparedModel::with_shader_data(meshes, data)prepares meshes with per-vertex data, oneVec<[f32; 4]>a mesh, empty or one entry per vertex (SceneError::ShaderDataLengthotherwise), held beside its vertices, 16 bytes a vertex;PreparedModel::newand glTF meshes carry none.
add_shader validates on native and in the browser with naga, composing
the module into every program the device's binding tier creates for it, so
a pipeline created later from an accepted module cannot fail WGSL
validation. It refuses, with a typed shader::ShaderError: a directive
(enable, requires, diagnostic); a name SGL3D's programs on either
binding tier declare, or a WGSL predeclared type, enumerant or built-in
function (smoothstep, saturate), which would replace it in SGL3D's
calls; a
parse or type error against the contract alone, its line and column in the
game's source (SGL3D's other declarations, such as view or frame, are
not the module's to read); a module-scope var, a binding, an override
or an entry point (the module declares const, struct, alias and fn);
a missing or mis-signed function or ShaderParams; discard (coverage is
base_color.a); a derivative in material_vertex or any other program
error; a scene depth function (scene_volume_path among them) called by
material_vertex or a function it calls (ShaderError::SceneDepthInVertex: scene depth is the surface
function's); a derivative (dpdx, dpdy, fwidth), or a call of a function
that takes one, within an if, a switch or a loop (the right of && and
|| among them) or after a return within one, since WGSL allows
derivatives only in uniform control flow and browsers refuse a program
that may take one elsewhere, where naga does not (take it at the
function's top level and select on it); ShaderParams over
shader::SHADER_PARAMS_MAX_BYTES (4096); and a
loop that is not a counted loop, or a function one call of which makes more
than shader::SHADER_LOOP_BUDGET (256) iterations in all (AR-12). A counted
loop is the for loop a counter of i32 or u32 makes, from a literal or
const start, tested with < or <= against a literal or const limit,
and changed only by its update, adding a positive literal or const step
(or loop { … continuing { i += step; break if i >= limit; } }, >= or
>), whose limit plus step and start plus step fit the counter's type, so
it cannot wrap (a break if loop runs once even from a start past its
limit).
The test and the step must read the counter in the loop's own test and
update statements (where a for loop puts them; break if after the
step); a value computed anywhere else is refused. A break if loop inside
another loop must set its counter's start just before it. Nested
loops' counts multiply, one loop after another's add, and a call within a
loop counts its callee's, so six Gerstner components cost six and a 16 × 16
nest the whole budget.
Limits. Rays (world-space reflections, dynamic GI, ray-traced shadows, the
hardware path's BLASes) see the rest geometry and the plain material, so an
opaque displaced surface reflects and bounces at rest, and a masked
shader's coverage is the base map's at ray hits. Probe captures hold the
capture's instant. A static instance's local-light shadow layers hold its
displacement at their draw while the cascades, drawn every frame, animate;
an instance whose local-light shadow must animate is a moving instance. A
material with a shader marks FSR's composition mask in the frames its
shading may change (FSR): every frame while its module reads the
time (ctx.time or ctx.phase, anywhere in the module), else only the
frame after an edit of its parameters or an instance's data. Adding a shader
validates its source. Each frame or probe draw creates the pipeline for its
pass, material and geometry on first use, including the shader module if it
has yet to be used. Views and captures share those pipelines. A
module's functions cost each pass that runs them, vertices twice in the
passes that write motion; a material without a shader costs nothing more,
its programs reading neither parameter blocks nor instance data, which
live beside the object records rather than in them. Consumer textures,
direct scene colour, ray-hit evaluation and a second custom are not part
of the contract.
The water example moves a lake of 16 m chunks with six
Gerstner waves (examples/sgl-3d/examples/support/gerstner.wgsl), anchored on their
period, with the column behind the water tinting and fading it, and
compares the same waves as morph targets (--morph); the shaders
example bends masked grass and tree cards in the wind
(support/wind.wgsl) under cascades and a spot light, and gives a glass pane
a thickness that varies across it (support/glass.wgsl); the volumes
example absorbs over the volume path in closed glass
(support/volume_glass.wgsl): a thin slab before a near and a far wall, a
block with an opaque object inside seen from outside and inside, a
wobbling blob and two boxes one behind the other, with --volume-paths off for the authored thickness:
Skinned meshes and morph targets
SGL3D renders the pose a game gives it; sampling and blending animation clips stay in the game (S3D-1).
- Loading.
asset::loadandload_sliceimport a glTF's skins and morph targets as eachCpuMesh::deformation(deformation::MeshDeformation): anInfluenceper vertex (four joints of the asset's joint list and their weights; a fifth influence set is refused) andMorphTargets (a displacement of each vertex's position, normal and tangent, scaled by one morph weight; a primitive without targets loads unmorphed, and a mesh whose morphed primitives differ in their number of targets is refused).Asset::rig(deformation::Rig) holds the node hierarchy with each node's rest transform, the joints (each skin's, in one list: a node and its inverse bind matrix), the morph weights (each morphed node's, with its rest weights) and the animation clips (Clip: channels of keyframe times and translation, rotation, scale or morph-weight values, with glTF's step, linear or cubic-spline interpolation). A skinned mesh's vertices stay in bind space, as glTF ignores its node's transform; a rigid node's transform is baked into its vertices and morph displacements, as before. Primitives batch by material, skin and morphed node. A node hierarchy loads without a depth limit within the asset load budget: traversal uses a heap stack, visiting roots and children depth-first in declared order, retained within each batch. A hierarchy that is not a set of trees (a node with two parents, or its own ancestor) fails the load, as do keyframe times that are not finite and strictly increasing. - Procedural.
ModelMesh::deformationtakes the same data; a model with any deforming mesh deforms.PreparedModel::newrefuses influences or targets that do not match their vertices, negative or non-finite weights, weights whose f32 sum is zero or non-finite, indices above 65535 and more than 256 morph targets on a mesh, as Bevy refuses (SceneError::InvalidDeformation). Weights are normalized; imported skins require the same finite positive sum. - Posing. A deforming model's instances are
Mobility::Moving. Each frame,Scene::set_instance_deformation(&queue, instance, &joints, &morph_weights)gives one joint matrix per joint the model's influences name (glTF's: the joint's transform in the model's space times its inverse bind matrix;Rig::joint_matricescomposes them from each node's local transform, and ends, with wrong matrices, on a built rig whose parents form a cycle) and one weight per morph weight its targets name; further ones are ignored, fewer are refused (SceneError::DeformationMismatch). A skinned normal faces the side its deformed triangles wind towards, as a mirrored joint's faces do. A joint matrix may scale an axis to zero, as a rig flattens or hides a part: a flattened surface takes the flattened surface's normal, and a vertex whose normal's plane collapses to a line or a point keeps its unskinned normal. An instance keeps its deformation until it is set again and starts at its bind pose. The instance's pose places the deformed model in the world. Every call counts as a change, whatever its values: the frame deforms the instance again and redraws the local-light shadow faces it reaches, so skip it for an instance whose pose did not change. - Rigid nodes. A rigid mesh's node is baked at its rest transform, so a
clip that animates it moves nothing; split such parts out by selecting
their nodes (
LoadOptions::nodes) and pose them as instances. - Rendering. Each frame the deform stage morphs and skins, in one compute
pass, every instance whose deformation changed since the last submitted
frame (Bevy's skinning and morph math, run once per frame as Wicked
Engine's
skinningCSruns it), into the instance's own vertices; the G-buffer, lighting, cascades, local-light faces and blended pass all draw them. Motion is measured from the deformed positions of the last submitted frame, under the same rules as a moving instance's pose. Culling uses each mesh's skinned bounds (Bevy's per-joint bounds under the joint matrices, grown by the weighted morph displacements). A deforming instance is never in a cached shadow layer, and redraws the local-light faces it reaches whenever its deformation changes. - Limits. A deforming instance keeps its model (
set_instanceto another model, or from a rigid model to a deforming one, is refused withSceneError::DeformingModel; remove and add it), and a deforming model takes no part in levels of detail. Scene rays (world-space reflections, the dynamic GI volume) see deforming instances only with hardware ray tracing, which traces each one's deformed positions; the portable BVHs leave them out, as Bevy's ray-traced scene leaves out meshes with joints. Screen-space reflections see them. Probe captures, which show static content, never contain them.
The skinned example generates a skinned, morphed glTF with a clip, and
samples, poses and renders it:
Retained scene and frame lifecycle
A game holds a Scene (content: geometry, materials, instances, lights,
decals, environments and bakes), a Renderer (what every view of the scene
shares: the geometry pipelines and bind group layouts, the deform and dynamic
GI stages and the frame boundary), a View for each image of the scene it
draws (its targets and sizes, its stages and every history kept in screen
space or fit to its camera) and its settings::Settings. Each frame it
describes each view's camera, the authored look and per-frame state in a
FrameInput.
-
Select an adapter and request the renderer's device requirements:
graphics_device::limitsgives its adapter-sized limits,graphics_device::featuresthe optional features SGL3D uses where the adapter has them,graphics_device::fsr_featuresthe features FSR needs, andgraphics_device::ray_tracing_featureshardware ray tracing's, which a game that opts in requests with wgpu's experimental token (Hardware ray tracing). The game owns surface acquisition, device failure, and window handling. -
Load assets through
asset::load(files) orasset::load_slice(embedded glTF/GLB bytes, as a browser fetches them), each with a_with_optionsform, or build anasset::AssetfromCpuMesh,Material(Material::default()is glTF's default material), and images: decoded RGBA8, or BC7 mip chains (Compressed material images). Apply game-specific adaptations explicitly;LoadOptionscan bound emissive strength when the game requests that behavior, supply any of the glTF's images (images) so the loader never reads or decodes them, and select mesh nodes (nodes). Default loading preserves authored strength, decodes each image a sampled map uses and loads every node. -
Scene::new(&device, &queue)starts empty. Add content between frames; each addition returns its identity (MaterialId,ModelId,InstanceId,LightId,DecalImageId,DecalId,EnvironmentId), and every operation that can fail returnsSceneError, changing nothing:-
A game that will not use world-space rays can instead create
Scene::with_options(&device, &queue, SceneOptions { ray_data: RayData::Disabled }). This immutable scene-lifetime policy skips ray-only image storage, model/instance BVHs and hardware acceleration. It retains packed raster geometry, deformation, culling and shadow maps; it does not remove the scene-source buffer or raise its binding limit.Scene::ray_data()reports the choice. Existing constructors useRayData::Enabled.add_assetchooses matching model preparation automatically. For manual preparation usePreparedModel::with_options(meshes, PreparedModelOptions { ray_data: scene.ray_data() }), orwith_shader_data_and_options(meshes, data, options). A prepared model with a different mode fails withSceneError::RayDataMismatchbefore content is retained. To add ray capability later, create and populate an enabled scene explicitly; this is not lazy ray loading. Disabled scenes keep screen-space reflections, probes, baked lighting and screen-space volume paths. World-space reflections, dynamic GI, hardware rays and traced shadows report off even if requested in saved settings. TheirRenderer::*_in_effect(&settings, &scene)queries include scene policy as well as device support. -
add_assetadds a loaded asset whole and returns its materials' and model's identities (AssetIds); its own indices do not outlive the call.add_materials(texture indices index the images passed with them) andadd_modeladd procedural content. A model's meshes (ModelMeshes naming materials already added) reachadd_modelandset_modelprepared:PreparedModel::new(meshes)validates them (a mesh holds at most 65,536 sections of 128 triangles, 8,388,608 triangles;SceneError::TooManySectionspast it), builds their culling hierarchies, shadow-caster clusters and ray-query BVH and packs their GPU data without a device or the scene, and the value isSend, so a game prepares on its own worker threads (SGL3D starts none) and the thread that edits the scene only places and copies it.add_modelandset_modelcheck what needs the scene (materials, an anisotropic material's tangents, a deforming model's static instances) and the device's limits; a failed operation places nothing, and the game prepares again for another try:// On a worker thread. let prepared = new?; // On the thread that edits the scene. let model = scene.add_model?; -
add_instance(&device, &queue, InstanceState { model, pose, visible, capture_visible }, mobility)places a model;InstanceState::new(model)is at the origin and shown in every view.Mobility::Staticinstances are what bakes and probe captures contain; they write no motion and take baked diffuse light from lightmap charts and the irradiance atlas.Mobility::Movinginstances are posed every frame; they take an ambient cube and write motion from their pose in the last submitted frame.visibleis the main camera;capture_visibleis every other view (shadows, rays and, for static instances, probe captures). -
add_lightadds a point, spot or rectangle light (Point, spot and rectangle lights). -
add_decal_imagekeeps an image for decals andadd_decalprojects images through a box onto surfaces (Decals). -
add_environmentadds a panorama and its PMREM atlas;FrameInput::environmentnames the one that lights a frame (FrameEnvironment::Map), or a procedural sky. With none, or a removed map, the frame has a black environment. -
set_material,set_model,set_instance,set_lightandset_decalreplace values, geometry, state and descriptions;remove_…ends an identity, and its index is reused under a new one. Content that other content uses (a material by a model, a model by an instance or as a level of detail, a decal image by a decal) cannot be removed, and a level of detail's model cannot be replaced; replacing a model clears the levels of detail registered on it. -
update_mist,update_fog_volumes,update_effectsandupdate_heat_distortionreplace transient geometry whole and returnResult<(), SceneError>. Oversized fog, mist and glow submissions returnDeviceLimitand keep the previous content: fog is limited by both the device's storage binding and buffer size; mist and glow by its buffer size. Counts must fit au32. Handle or propagate the result (?). -
move_origin(&device, &queue, to)moves the render origin toto, a finite position in the current render frame. Every position SGL3D takes isf32in that frame; a game whose world is larger thanf32renders precisely keeps its own coordinates and moves the origin to stay near what it renders, chunk-aligned in a streamed world. Every position the scene holds becomes what it was lessto: instances (with the pose their motion is measured from), lights, decals, fog volumes, mist, glow and heat geometry, installed probes, the dynamic GI volume (its probes kept) and the ray source. From then on the game gives the camera, the frame input and its edits in the new frame. It is not a static edit: moving instances keep their motion, static shadow layers stay valid, histories continue (each view translates what it keeps), and the directional cascades' texel grid stays put. Geometry, bakes and probe captures do not change. A translated position rounds once, at its magnitude in the new frame, so integer poses such as chunk origins stay exact and a game never re-poses its instances after a move. A game that never calls it pays nothing.
Buffers grow as content is added and reuse removed content's ranges; content beyond a device limit is refused. Models share their buffers: the ray source, and slabs that hold every mesh's shadow-caster positions and indices from 1 MiB up to 512 MiB each, grown by half again when full, so adding, replacing and removing models creates no buffer per mesh.
Renderer::new(&device)creates what the views share, andView::new(&renderer, &device, &queue, output_format, output_size, device_scale, &settings)a view's targets for an output ofoutput_sizephysical pixels in a window ofdevice_scalephysical pixels per logical pixel. It writes floating-point composition textures (Rgba16Float,Rgba32Float,Rg11b10Ufloat) in display-referred linear sRGB on both platforms. An sRGB attachment encodes on write; other unorm textures receive encoded sRGB. For direct window/canvas presentation useView::new_surface(&renderer, &device, &queue, &surface_config, &surface_caps, device_scale, &settings): it reads both the format and colour space. Browser Auto float canvases take encoded sRGB; native Auto RGBA16F surfaces take linear sRGB when supported, otherwise encoded sRGB. Passsurface.get_capabilities(&adapter)assurface_capsso SGL follows the actual surface. ExplicitSrgb/ExtendedSrgbtake encoded sRGB,ExtendedSrgbLinearlinear. A linear colour space with an sRGB attachment, or an unsupported colour space, returnsViewError::UnsupportedSurfaceOutput. Recreate the view when surface format or colour space changes. Composition samples float outputs as linear and applies its final display transfer once; no material or exposure gamma correction is needed. -
-
Each frame,
set_instanceeach moving instance with its pose and visibility, andset_instance_deformationeach deforming one (Skinned meshes and morph targets). A moving instance has no motion when it is new, its state names another model, or it was notvisiblein the last submitted frame; one that must not carry motion across a change is removed and added again.set_lighteach light that moves or changes. Fixed emitters light static surfaces through the baked lighting, and moving instances through it or as baked lights. -
Call
view.resize(&device, output_size, device_scale, &settings)for each view. It does nothing unless the output size, the scale or a size-affecting setting changed, so call it every frame. -
Build each view's
FrameInput(FrameInput::new(camera)holds the defaults) and callrenderer.render(&device, &queue, &mut encoder, &mut scene, &mut [ViewFrame { view: &mut view, input: &input, settings: &settings, output: &output_view, timing }])once, every view listed, the main view first. It encodes the scene's frame work once and then each view's whole frame into its output view, of that view's output format and size; the output may be offscreen, so no window or surface is required. Onerendercall is one frame of the scene: never render the scene twice for one finished frame. -
Draw game-owned HUD/UI afterward, submit the encoder, then call
renderer.finish_frame(&mut scene): each view's camera and the moving instances' poses and deformations, as the frame drew them, become the next frame's history, and the shadow faces it drew become reusable. Do not finish a frame that was not submitted; an abandoned encoder leaves history unchanged and its shadow faces are drawn again. A frame rendered and not finished, submitted or not, then rendered again as the same frame, restarts nothing but FSR and one frame of filtered fog's reprojection: the next frame continues every other history from the last finished frame. A cut in an unfinished frame holds until a frame is finished, and a stage switched off in it (antialiasing, a reflection method, another projection) restarts as it would after a finished frame without it. Scene edits upload through the queue, never the frame's encoder, so an abandoned frame loses none. Edit the scene beforerenderor after the submission, never between them: an edit made after the submission and beforefinish_framebelongs to the next frame.
A view's history restarts for FrameInput::camera_cut, a resize that changes
its targets (also one between a frame's render and finish_frame), a
different scene, and a finished frame of its scene that did not render it:
the scene keeps one frame of motion history, so list every view that keeps
temporal history in every frame (a view drawn every other frame should use
SMAA or no antialiasing). Submit each encoded frame before rendering the
next one with the same Scene and Renderer: frame uniforms and upload
storage are retained, so frames with different inputs cannot be queued in one
submission. Run probe captures between frames, never between a frame's
render and its finish_frame. Skip rendering zero-sized or minimized
outputs in the game.
A view builds its local exposure and presentation pipelines on their first
use and keeps them across toggles and resizes. To warm a known transition,
render, submit and finish a loading frame on the same view with the upcoming
FrameInput::local_exposure, settings and output path. A diagnostics capture
uses a different final pipeline from direct presentation. The loading frame
participates in the normal frame history.
Recreate the scene, renderer and views after replacing the device. Dropping them releases the library's GPU handles; the game still owns its device, queue, surface, and asset sources.
Several views
A split screen, an inset, a rear view or an editor's viewports are several
Views of one scene, each listed in the frame's Renderer::render with its
own FrameInput, Settings and output. The first listed is the frame's
primary view. The scene's frame work runs once, in its stage order: the
scene's uploads, its ray instances under the primary's visibility mask, the
acceleration structures (ordered from its eye, built when any view of the
frame traces), the deform pass, and the dynamic GI update from the primary's
lights, environment, time and frustum; every view then binds the probes.
The primary's settings choose what a scene has one of: hardware_ray_tracing,
dynamic_gi, anisotropic_filtering and the diagnostics layers, and the
Renderer::*_in_effect queries for them take its settings. Everything else
is each view's own: its antialiasing and sizes, shadows and their quality,
reflections, ambient occlusion, fog, exposure, culling and post. Each view
holds its own targets, FSR context, local-light shadow atlas, static layers
and cache, so memory and shadow-face draws grow with views, and creating one
compiles its own stage pipelines. One renderer shows one scene at a time:
another scene specialises its pipelines again and restarts its dynamic GI,
so a game showing two scenes at once holds a renderer for each. Known
limits: rays see the scene under the primary view's visibility mask, and a
view's output cannot yet be a scene texture (an in-world mirror or portal
needs a render-texture material first). The
views example draws a main view and a rear-view inset:
The offscreen example is the loop to copy, with procedural geometry, caller-created environments, animation and PNG output:
The streaming example is a block world at a block
game's scale: 16 m chunks, each one model placed as a static instance at its
integer chunk origin, added under a per-frame budget as a camera walks or
flies, replaced by block edits and remeshing waves, and removed behind it;
water as moving blended receivers; torches; and the render origin moved
every chunk or every 256 m. A block edit remeshes the chunk holding the
block it changed and the chunks of that block's solid neighbours across a
border, since a solid block owns its faces toward air. Once the first window
has streamed in, it prints each scene operation's CPU time by size, a frame's
time in scene calls apart from the game's meshing and preparing (on four
worker threads, whose build steps it prints apart from the placing and
writing on the thread that edits the scene), its recording time,
uploads by call site, buffers created, the scene's buffer
sizes, draws per view, the local-light shadow faces each frame redraws and
GPU time per pass, and writes each run's last frame to
target/streaming-example/. --check moves the origin under a still camera
and fails if static content shows motion or a shadow is redrawn, then
remeshes chunks holding shadowed torches and fails unless their static
shadow layers are redrawn once:
GPU pass timing
timing::GpuTiming::new(&device, &queue) returns None unless the device was
created with Features::TIMESTAMP_QUERY; pass None wherever a timing argument
is taken to render untimed. Each frame:
for frame in timing.begin_frame
renderer.render;
// Game passes may join: `timestamp_writes: timing.render_pass("HUD")`.
queue.submit;
timing.submitted;
begin_frame never blocks. It yields frames whose GPU work has completed,
usually two or three frames late; latest() keeps the most recent. A frame is
left untimed when all four query sets are still in flight. Only pass
timestamp_writes are used, so no inside-encoder timestamp feature is required.
Tile-based GPUs start a pass long before earlier fragments finish, so raw pass
spans overlap. Each pass is therefore charged from the later of its start and
the end of every earlier timed pass (including the previous frame's) to its
end; a group sums its passes, and groups sum to at most total_ms, which runs
from the frame's first charged start to its last timed end. Untimed work
between timed passes is charged to the next timed pass. SGL3D's groups, by
stage (each stage's documentation lists its own), are:
- prepare:
deform(the frame's skinning and morphing, while an instance's deformation changed) andcull(the GPU-built lists' early phase); - sky:
sky transmittance,sky multiscatteringandsky view, in a frame whose procedural sky's inputs changed,aerial perspective(every frame it is in effect) andsky environment(one atlas step a frame, the whole cycle on its first frame and after a cut); - dynamic GI:
dynamic GI allocation,dynamic GI raysanddynamic GI blend, while the scene holds a volume andSettings::dynamic_giruns it; - shadows:
directional shadow cascade 0todirectional shadow cascade 3(one per cascade the frame has),local shadow layers(static layers) andlocal shadows(the frame's faces); - volumetric fog:
fog injection,fog filterandfog integration(onlyfog integrationwhile aerial perspective runs without the fog); - opaque:
skyandopaque geometry + lighting, orgeometry,skyandopaque lightingwhere the device lacks the fused pass's colour attachments or occlusion culling, ray-traced shadows or contact shadows run; while occlusion culling runs,depth pyramid(twice),cull lateandgeometry latebetweengeometryandsky; thenambient occlusion(with the depth pyramid while it runs) andscreen-space indirect(with the depth pyramid while ambient occlusion is off); - ray-traced shadows, after the opaque stage's G-buffer passes and their
culling and before
skywhile they run:ray-traced shadow rays, the denoiser'sray-traced shadow tile classificationandray-traced shadow filter(three passes, two at Low),ray-traced shadow temporalandray-traced shadow upsample; - contact shadows, in the same place while they run:
contact shadows; - reflections:
probe culling,reflection source completion, Crystal'sSSRpasses (named after DiligentFX's debug groups), Velvet'sGodot SSRpasses,world reflection classify,world reflection rays,world reflection denoiseandreflection composition; - transparent:
receivers(the receiver pass, after opaque);blended(blended surfaces) andtransparent(additive effects and mist), each drawn into the reflection input while screen-space reflections run and onto the composed frame; andheat distortion; - exposure:
exposure, while automatic; - antialiasing:
TAA,FSR2orFSR3(all passes of the selected upscaler); - motion blur:
motion blur; - post:
bloom,SMAAandtone map; - DiligentFX's post-effect context, for TAA and Crystal:
DiligentFX inputs,DiligentFX blue noise,DiligentFX reprojected depthandDiligentFX previous depth.
Inactive work reports nothing.
Baked diffuse lighting
Optional permanent surface lighting uses static_lighting::Lightmap and
Scene::set_lightmap(device, queue, map, &material_ids). The map holds linear
irradiance divided by PI, before albedo, finite, nonnegative and within RGBA16F
range. The library uploads it as the uncompressed atlas below: an RGBA16F
texture, with an RGBA8Unorm one for its directionality, filtered bilinearly by
the hardware as Bevy, Godot and Wicked sample their lightmaps. Material UVs map
through the supplied finite scale/offset (SceneError::InvalidLightmap
otherwise); negative and zero scales are allowed. X clamps and Y repeats
(the sampler's address modes), so a chart can wrap around a closed loop. A wrapping chart
cannot be split, so each side must fit the device's max_texture_dimension_2d:
graphics_device::limits requests the adapter's value rather than wgpu's
default of 8192, and a larger chart is refused with SceneError::DeviceLimit.
This single chart lights the listed materials where static instances use them;
the eligibility belongs to each material, so a material added later is not
lightmapped. The caller must regenerate it when the static scene, source
radiance, UV chart, or caster visibility changes.
This opt-in application extension supplies Lambertian diffuse irradiance,
which adds to the frame's ambient (the environment's diffuse light and the
hemisphere fill): a charted surface takes both, as does a moving instance
with a cube where no volume lights it, so a bake excludes the sky and the
fill, or the game lowers FrameInput::hemisphere_light and
diffuse_environment where its bake holds them. A material reflects it as
it reflects the environment's: what its
specular does not scatter, plus its multiple scattering, the one rule every
indirect source follows. On a coated material the coat's Fresnel toward
the view dims it, and the irradiance atlas's and a moving instance's
ambient cube's light, as it dims the material's live light and emission
(up to the light's specular; probe hits take no coat)
(KHR_materials_clearcoat layers the coat over the whole base).
Static instances' other surfaces can additionally carry Vertex::lightmap_uv
and use Scene::set_static_irradiance_atlas(device, queue, &IrradianceAtlas).
Supply equally sized irradiance and back_irradiance RGB arrays in linear E/PI;
the library uploads two RGBA16F layers and selects the actual material side.
Cropped charts supply the same normalized min/max Vertex::lightmap_bounds
on all three triangle vertices; extrapolated UVs outside these bounds return
black before sampling, so a giant triangle need not allocate a full dark chart.
Charts need filtering gutters. Give unassigned surfaces UV (0,0) or negative
UVs: they have no baked lighting, so baked scene lights light them. Lightmapped
materials take precedence. The atlas
must capture illumination inside large triangles; vertex-color lighting is not
a substitute. The game owns chart authoring, physical integration and rebaking.
Ship the atlas block-compressed, as Unity and Godot ship HDR lightmaps:
Scene::set_compressed_static_irradiance_atlas(device, queue, &CompressedIrradianceAtlas) takes BC6H irradiance and BC7 directionality
(front then back layer, sizes multiples of 4), an eighth and a quarter of the
uncompressed GPU size. Its scale multiplies the decoded irradiance in the
shader, as Unreal's lightmap scale does, so a uniform source-power change needs
no re-encode. Compress offline with a BC6H/BC7 encoder such as Intel's ISPC
Texture Compressor; installing needs wgpu::Features::TEXTURE_COMPRESSION_BC.
On a device of the Extended binding tier, to retain
normal/bump detail under baked lamps (Basic validates directionality but
does not upload or read it), populate Lightmap::directionality
and the atlas's directionality / back_directionality with one [f32;4] per
texel holding a constant+linear irradiance lobe relative to the baked value: the
shader returns irradiance * max(a + dot(w, n), 0) for the mapped world normal
n, with packed xyz = w / 8 + .5 and w = a / 2. Choose a + dot(w, N) = 1
at the bake normal N so flat surfaces keep the bake; w is the irradiance
gradient toward the light. A distant source along N is w = N, a = 0; uniform
hemisphere light is w = N / 2, a = 1 / 2. Use [.5;4] for a neutral lobe or an
empty vector for a nondirectional layer; a lobe that rounds to all-zero RGBA8
is reserved internally for absent layers and refused. Values must be finite and
within [0,1]. The hardware
bilinearly filters the lobe.
Lobes use RGBA8Unorm layers (a map without them allocates only one zero texel
per layer); quantize w first and derive a from the quantized value to keep
flat surfaces exact.
For moving instances, interpolate a game-authored precomputed field and call
set_instance_baked_irradiance(queue, instance, AmbientCube { irradiance });
a static instance, which takes the charts above, refuses it with
SceneError::StaticInstance.
The six RGB E/PI entries are +X,-X,+Y,-Y,+Z,-Z in world axes, each channel
finite in 0..=65504 (SceneError::InvalidIrradiance otherwise). Invalid
cubes and lightmap charts retain the previous content.
The shader weights them with squared shading-normal components. This diffuse
approximation preserves world orientation but cannot represent sharp angular
variation, fine spatial shadow boundaries or fixed-source offscreen specular.
Measure its errors against physical samples in the game; ordinary IBL still
provides specular response. A state naming another model clears the cube, and
a new instance starts without one.
Neither alters material albedo or paints light into emission.
Irradiance volume
A game that computes its own light field, such as a voxel world's propagated sky and block light or a level's bake, lights its world from it through the irradiance volume: a lattice of cells the game places and writes by region, which every surface within it, static or moving, samples by its position (a port of Bevy's irradiance volume, after Valve's ambient cubes). Changing the light, a torch placed or a cave opened, is a region write: no geometry replaced, no static edit, no texture installed again.
let volume = IrradianceVolume ;
scene.set_irradiance_volume?;
// On any thread: validate and pack a box of cells, x fastest, then y, then z.
let region = new?;
// Between frames:
scene.write_irradiance_cells?;
- Cells.
IrradianceCell { irradiance: AmbientCube, sky_visibility: [f32; 6] }, both in the order +X, −X, +Y, −Y, +Z, −Z, each face what a surface facing that way receives.irradianceis the cell's own light, irradiance / PI on the directional lights' scale: its emitters, block light and whatever bounce the game's field carries.sky_visibility, 0 to 1, is how much of the frame's ambient (the environment's diffuse light and the hemisphere fill) reaches the cell from that side. A surface the volume lights takessky_visibility × ambient + irradiancein place of the ambient, so the sky can change with the frame (day and night) without a cell being rewritten. A cell never written isIrradianceCell::default(): the frame's ambient whole and no light of its own. - Writes. A region's corner is a cell's least corner on the volume's
lattice and the region lies within it, or the write is refused with
SceneError::IrradianceRegionOutsideand writes nothing.PreparedIrradianceRegionis plainSenddata: prepare relights on worker threads; the write only queues one texture write per face. - Sampling. A surface steps half a cell along its geometry normal, so a voxel face reads the cell in front of it, then takes three trilinear taps blended by its shading normal's squared components. Blending with dark solid cells darkens convex edges, as smooth voxel lighting does; fill solid cells from their air neighbours where that is unwanted.
- Which surfaces. Lightmap and irradiance atlas charts keep their bake,
with the frame's ambient added whole.
Within the volume it covers the dynamic GI volume and ambient cubes, its
share fading over the one cell past each face to what follows it: leave a
region uncovered to light it from the dynamic GI volume or cubes. A face
lying exactly on the volume's boundary and facing out samples half a cell
past it and takes half the volume's share, so let the volume reach a cell
past what it should light whole. Ambient
occlusion occludes it as it does the ambient, and
FrameInput::baked_lightingturns it off with the charts and cubes. Its own light is not a scene light: a fixture written into the field is not also added as a bakedLight, or the field leaves its light out. - Sky specular.
sky_visibilityalso darkens the sky's share of a surface's environment specular (Lagarde's specular occlusion), so a cave's walls stop reflecting the sky; specular probes, which a game captures where they are, keep theirs. A probe captured before a relight is the game's to capture again. - Scrolling. Install the same cell size and counts at a new origin: the
volume moves by the nearest whole number of cells (read the placement back
with
Scene::irradiance_volume), keeps the cells that stay, and starts the cells that enter asIrradianceCell::default(), for the game to write. The copy is submitted on the queue at once. Another cell size or count, or an origin off the lattice, is a new placement whose cells all start as the default.Scene::move_origintranslates the volume and keeps its cells. - Cost and limits. 48 bytes a cell (160 × 128 × 160 cells, 157 MB), three
3D taps per lit fragment, a region write's 48 bytes a cell through the
queue, and on a scroll the cells that stay copied in place through a
stripe 16 cells thick across the axis, which stays with a stripe of zeros
once for each axis scrolled along (each about 2% of a volume 160 cells
across it). The texture is
cells.x × 2 cells.y × 3 cells.ztexels within the device'smax_texture_dimension_3d(2048 at WebGPU's default: 2048, 1024 and 682 cells), elseSceneError::DeviceLimit; a placement that is not a lattice isSceneError::InvalidIrradianceVolumeand a region with invalid cellsSceneError::InvalidIrradianceRegion. The browser runs the same volume. - Example.
examples/irradiance_volume.rslights a block world's cave from a propagated sky and torch light field at a metre, relights a torch as a region write, scrolls the volume with the camera while the render origin follows it, and prints the per-pass GPU time and what relights, scrolls and whole installs cost.
Dynamic diffuse GI
A dynamic GI volume gives static and moving surfaces coloured bounce light
from the frame's lights, the scene's lights, emitters and the sky, kept up
by rays each frame without a bake: a port of Wicked Engine's DDGI (Majercik
et al. 2019). It runs on a device of the Extended
binding tier; on Basic, Settings::dynamic_gi resolves
to Off (Renderer::dynamic_gi_in_effect). The game places a lattice of
probes over the part of its world it wants lit by bounced light:
scene.set_dynamic_gi_volume?;
Each frame the dynamic GI stage, first after prepare, traces rays from the probes through the scene's ray source (static and moving instances that do not deform), from either side of every triangle. A hit is lit by one light drawn from the frame's directional lights and the scene lights whose range reaches the volume, with one ray toward it for its shadow at the light's shadow opacity where the light casts a shadow (no shadow map, so nothing it lights leaks through walls into the probes), by its emission, and by the volume's own last frame for further bounces; a miss takes the environment and the hemisphere fill along the ray. A ray that meets a single-sided surface from behind takes no light from it and counts the surface nearer, so the probe keeps out what lies behind it. Each probe keeps its irradiance and the distances to what surrounds it, so a surface takes light only from the probes that see it.
A glowing fixture that is also a scene light, such as a lamp's panel beside its rectangle light, would reach the probes twice: as the emitter their rays meet, and through the light, which already lights everything the fixture would. Mark its material so the probes' rays take none of the light it gives off itself (its emission, and an unlit material's whole colour):
for material in &mut asset.materials
SurfaceMaterial::emits_into_gi changes it later with Scene::set_material.
The surface still glows on screen, shows in reflections, blocks the probes'
rays and, when lit, reflects the light that reaches it, as Unity's emission
"Global Illumination: None" keeps a material's glow out of its GI while the
object stays in it.
Surfaces take their indirect diffuse light by one determination, in which
baked light adds to the frame's ambient (the environment's diffuse light and
the hemisphere fill) and only the volumes replace it: a lightmap or
irradiance atlas chart keeps its bake and adds the frame's ambient whole;
any other surface takes the irradiance volume where it
lights the surface, then the dynamic GI volume, each by its share, in place
of the frame's ambient, and ambient occlusion occludes them as it does it;
and, in the share they leave, the frame's ambient, to which a moving
instance adds its ambient cube. A bake therefore excludes the sky and the
fill, or the game lowers them where its bake holds them. The camera's
opaque and blended surfaces, probe captures, world-space ray hits and the
probes' own hits sample the same volume. SurfaceMaterial::environment_scale
scales the environment, not the volume. Beyond its extent the volume's share
fades out over one spacing; ambient cubes stay the moving instances'
fallback there, with Settings::dynamic_gi at Off, and without a volume.
Each probe also records how much of the sky its rays reach about each direction, a sky visibility from 1 under open sky to 0 in a closed room. Where the volume lights a surface it darkens the sky's share of the surface's environment specular by its share, as the irradiance volume's sky visibility does, so shade under an awning or inside an arch stops reflecting the sky at full strength; specular probes keep their reflections. It follows geometry over about 50 of a probe's turns, as its depths do, and resolves at the probe spacing.
Sparse turns keep a probe texel's light, sky visibility and depth history when no ray contributes to it. A fresh unobserved depth texel starts at the maximum ray distance; its irradiance starts at zero and its sky visibility at 1 until observed.
Placement:
- Cover every surface the volume should light: one to a few metres apart suits rooms and streets. A volume need not cover the world.
- Probes may lie beyond walls, inside closed geometry or outside a room built of single-sided walls facing inward: a probe that sees a single-sided surface from behind takes nothing from beyond it, and the receivers on the surface's other side weigh it as occluded. A probe more than a quarter of whose view is such backs is inactive: it lights nothing and traces few rays, so probes inside walls cost little. A probe with no surface within a spacing of it lights moving instances alone and traces few rays, unless a moving instance comes within that spacing: so a probe beyond a room's corner lights none of its walls, and probes in open air cost little yet light whatever moves among them. A static object so small that no probe about it finds it (a probe classifies from 32 fixed directions, all of them on its second turn and over each 8 of its turns after) takes its other indirect light. A probe's class follows a change in what it sees within 8 to 16 of its turns: 8 to 16 frames within a spacing of the camera, up to 128 at 128 spacings while the budget holds. Keep probes off the surfaces themselves, where a probe sees both sides at once: offset the lattice so walls fall between probes. Probes near a surface move off it, up to half a spacing, as they trace.
- A receiver tests which probes it sees from a point offset toward the viewer by about a quarter of the least spacing, so a surface does not shadow itself. A surface nearer a wall than that, facing it and seen head-on, can take light from beyond the wall; a closer spacing where surfaces face walls closely keeps it inside.
- A light that casts no shadow (
Light::casts_shadowfalse, or a directional light without the frame's cascades) lights the probes as it lights surfaces, unoccluded, through walls too: give a light that should stay in its room a shadow. - To keep a volume about a moving camera, install it again each frame with
its origin moved by whole spacings (round the camera's position on the
lattice): the scene scrolls it, the probes that stay keeping their light
and those that enter starting afresh. An origin off the lattice by more
than a small tolerance of the spacing, or another spacing or count, is
another placement, which starts every probe afresh, as does a frame that
does not run them (another scene, the setting
Off). Installing the same placement changes nothing; camera cuts, resizes andScene::move_originkeep the probes, and after a moveScene::dynamic_gi_volumegives the placement in the new frame to scroll from. - A restart, or a scroll's entering planes, starts as many probes a frame as the frame's ray budget holds beside the probes already started (at least half of it), nearest the camera first: 128 a frame at the tier's most rays near the camera, more farther out, where a probe starts with fewer rays. Until a probe has started it lights nothing, and the surfaces about it keep their other indirect light. Wicked starts every probe in one frame, a hitch on a large volume.
- Memory is about 9 KB a probe at High (7 KB at Low): its irradiance and
depth maps, its share of the frame's ray results and the blends'
history; and a ray list of the frame's budget, 256 KB at High (128 KB at
Low). A volume is refused with
SceneError::DeviceLimitwhere its probe texture (18 texels a probe along x times y) or its rays exceed the device's largest 2D texture, and withSceneError::InvalidDynamicGiVolumefor a spacing that is not positive or fewer than two probes on an axis.
Settings::dynamic_gi (DynamicGiQuality: Off, Low, High; High by
default) sets the most rays a probe traces on a turn, 256 or 128, and the
frame's budget of rays, fixed rays included, 32,768 or 16,384 (Wicked's
surfel GI budget). A probe traces on its turns: every frame within a
spacing of the camera, every eighth frame at 128 spacings and less often
beyond, with an eighth of the most rays out there. On a turn it traces
rays by how consistent its irradiance is, a tenth of that outside the
camera's view, at least four: a probe whose light settles traces few, and
one whose light changes traces up to its most, and takes extra turns from
the rays the frame's turns leave, so cost follows change and a moved light
is answered sooner. Where the turns ask for more than the budget, every
probe's turns are spaced out by the same power of two, so none starves and
near probes keep up the most. On Hyperdrive's 3,179-probe course at High
the rays pass costs about 3.4 ms a frame in motion and 1.7 ms with the
camera still on an Apple M5 at 1920x1080 (1.6 and 1.2 ms at Low).
Once its light has converged, the volume pauses: it traces nothing and its
probes hold their light, until something its light follows changes. That
is any edit to the scene that changes what rays see or light (an instance
that does not deform, a model, material, light, decal, environment, bake
or the irradiance volume), the frame's directional lights, hemisphere fill
or environment, Settings::dynamic_gi, or the volume's placement; the
camera and the clock are not, nor a deforming instance's animation unless
hardware ray tracing traces the volume's rays, which then see it. Setting a
pose or a value to what it already is changes nothing. A scene whose
opaque or masked materials' normal layers move (a lit material, a layer
moving at least a repeat per hour) changes every frame and never pauses;
still layers and unlit or blended materials' layers do not.
Frames that run the volume trace the ray source, so its instance BVHs
rebuild on them as for world-space reflections. Deforming instances are
lit by the volume, and block its rays only with hardware ray tracing. Per-pass cost is reported in
the dynamic GI * timing groups. The dynamic GI example
lights a room through a window and with a lamp, two boxes moving through
it; --timing prints the stage's GPU time in each frame as its probes
start and settle, --counters each frame's probes, rays, stride and BVH
node visits (Diagnostics::dynamic_gi), --still parks the boxes so the
volume pauses and --edit N moves the lamp at frame N, which starts it
again, --quality off renders the room without the volume, and
--scroll walks the camera along the room with a shorter volume that
scrolls to follow it:
Hardware ray tracing
A native device with wgpu's ray queries traces the scene's rays in
hardware: world-space reflections' rays and the dynamic GI volume's probe
rays and visibility rays go through the scene's acceleration structures
instead of the portable BVHs, through the same functions and the same hit,
so they see what they saw before and, in addition, skinned and morphed
instances. It is opt-in: off by default and in every preset, a game takes
it by requesting the feature and turning Settings::hardware_ray_tracing
on. Elsewhere, or with the setting off, rays traverse the portable BVHs.
No feature needs it (D-30): without it
world-space reflections and the dynamic GI volume trace the portable BVHs,
and the shadow maps stand in for ray-traced shadows, which run only in
hardware.
- Device. Request
graphics_device::ray_tracing_features(&adapter)withgraphics_device::limits(&adapter), which requests the adapter's acceleration-structure limits. wgpu 30 marks the feature experimental, so the descriptor'sexperimental_featuresmust beunsafe { wgpu::ExperimentalFeatures::enabled() }, the game's acceptance of it. Metal has it from macOS 15 on Apple silicon (in hardware from M3), Vulkan with ray queries, and DX12 at ray-tracing tier 1.1, which needs DXC: enable wgpu'sstatic-dxcin the game or shipdxcompiler.dllbeside its executable (wgpu's defaultDx12Compiler::Autotakes either, never FXC). No browser has it, nor Vulkan on a Mac.sgl-3denables nostatic-dxcitself. - Structures. While
Settings::hardware_ray_tracingis on, frames that trace rays (world-space reflections, the dynamic GI volume, ray-traced shadows) build, in the frame's encoder after the deform pass: a BLAS for each model that does not deform and has an opaque or masked mesh (under the baseline form, an opaque one and no masked one), over all its meshes' positions in the scene's ray source, a masked mesh's geometry not opaque under the candidate form, pending until such a frame and then built nearest the camera first under Bevy's budget of 400 000 vertices a frame (the first pending always, a replaced model at once), then compacted; a BLAS for each deforming instance over its deformed positions, rebuilt in each frame its deformation changed; and a TLAS over the capture-visible instances, rebuilt every such frame, each instance named by its entry's index with its kind (static or moving) as its mask. An instance of a model with a masked mesh under the baseline form, of one whose BLAS is pending, or that the device cannot hold (a model pastmax_blas_primitive_countormax_blas_geometry_countor whose indices start 4 GiB or more into the ray source, instances pastmax_tlas_instance_count, the farthest left out, or a structure its memory cannot hold) stays on the portable BVHs, which then cover those instances alone; a deforming instance the device cannot hold is seen by no ray, since the portable BVHs never hold deforming instances. Turning the setting off frees the structures; a scene on a device without the feature holds none. A mesh's indices past its last whole triangle are left out of its BLAS, as of its BVH. The one allocation no error scope reaches is the builds' scratch buffer, which wgpu allocates when the game finishes the frame's encoder: its out-of-memory error reaches the game's error handler, as any failure of its encoder does. - Tracing. Metal runs the candidate form and Vulkan and DX12 the baseline (below). In both, each ray asks the hardware for the nearest hit over the kinds it wants (any hit for a visibility ray), and the same acceptance rules as the portable path judge it: a back face a ray's side policy rejects (a camera-origin ray rejects a single-sided material's, judged from the triangle's own winding, so mirrored instances keep their sides), a blended mesh of a model that also has opaque ones, a hidden visibility group, the reflecting surface's own triangle, a cut-out texel of a masked deforming instance under the baseline. A rejected hit is traced past, within 256 steps a ray, after which the ray reports a miss. Under the candidate form, masked models join the acceleration structures with their masked meshes not opaque, and the hardware's candidate loop judges each of their triangles a ray crosses by the same rules, cut-out texels included, each a step: on an Apple M5 the most a ray took was 44 through a crowd of 24-card hair bundles and 84 grazing rows of dense cut-out hedges. Under the baseline, the software BVHs trace masked models that do not deform, and a ray through a deforming instance's hair cards spends a step for each cut-out card it crosses, at most 36 in that crowd. The portable BVHs trace the instances the TLAS does not hold, cut-out texels included, and the nearer hit wins. A deforming instance's hits take its deformed positions, normals and tangents, and a masked mesh on it cuts out at the hit. One limitation: a triangle at exactly the distance of a rejected one (back-to-back single-sided faces, coplanar meshes of a shown and a hidden group) may be skipped, since one opaque query cannot list ties. While hardware ray tracing traces the dynamic GI volume's rays, a capture-visible deforming instance's pose or deformation is an edit that wakes a converged volume, since its rays see it. Metal runs the candidate form: on an Apple M5 it cut the tracing passes by 35–60 % among cut-out foliage and cost up to 14 % of the ray-traced shadow rays (0.12–0.13 ms) where nothing is masked; Vulkan and DX12, whose shader compilers lower the loop too, run the baseline until it is measured on their hardware, which it has not run on yet. A device whose candidate programs fail to compile falls back to the baseline for good. On Metal the tracing passes cost more under wgpu 30 than under wgpu 29 (#221): naga 30's lowering drops the triangle-geometry hint naga 29 gave Metal, which leaves every pixel of a tracing pass on Metal's general ray-query path whether or not it traces. On an Apple M5 at 1920×1080, as #221 measured it before world-space rays were traced from a list (#223), the streaming example's world reflection rays, which trace nothing there, cost 0.20 ms against wgpu 29's 0.09 (since #223 they cost the classification, about 0.07 ms, in place of the trace), and its ray-traced shadow rays about 40–57 % more. SGL3D cannot restore the hint; it is naga's.
- Reporting.
Renderer::ray_tracing_in_effect(&settings, &scene)says whether the hardware path traces the scene's rays, asantialiasing_in_effectdoes for antialiasing, andRenderer::ray_tracing_error()why it did not trace the last frame that asked for it (the device has no ray queries, its memory could not hold the TLAS, or the scene permanently disabled ray data). Portable BVHs can stand in for supported world-ray effects only when the scene retains ray data; a disabled scene has no portable ray fallback. The error also reports why the device fell back from the candidate form to the baseline, which traced it.Renderer::ray_tracing_stats()returns the last rendered frame'sRayTracingStats: the instances the TLAS held, those that do not deform it did not hold (on the portable BVHs), and those the device left out. With thediagnosticsfeature,diagnostics::counterscounts the BLAS and TLAS builds and compactions, andScene::diagnostic_resourcesthe BLASes held and their triangles. - Ray-traced shadows. With
Settings::ray_traced_shadowson too (off by default and in every preset), the camera's opaque surfaces take their shadows from rays instead of the shadow maps, as Wicked Engine's ray-traced shadows do, for up to sixteen lights: the directional light with the frame's cascades, and up to fifteen of the casting local lights the local-light atlas places, in its ranking by screen coverage, each keeping its place while the atlas places it. At half the render size, each pixel casts one ray toward each of those lights that reaches it, from 1 cm past the surface to 1 cm short of a point drawn on the light, each frame another: on a point or spot light's sphere (LightShape'sradius), a rectangle's face, or, for the directional light, within its disc in the sky (DirectionalLight::angular_diameter), as far as the scene reaches, beyond the shadow's distance. A light with a size so casts a soft shadow, sharp near its caster and widening away from it; a size of 0 a hard one. Since a ray stops short of the light, the light's own fixture, a mesh whose face a rectangle lies on, never shadows it. A single-sided surface occludes from its back, as a map draws its front from the light, and a double-sided one from either side. Abakedlight casts no ray at a receiver with baked lighting, which it does not light; its place in the mask holds 1 there wherever it reaches, so the passes that follow, which blend neighbouring texels, carry no false shadow onto a moving instance beside that receiver, though that instance's edge may read slightly lighter where the light would have shadowed the receiver beside it. AMD's FidelityFX shadow denoiser filters the directional light's visibility and those of three of the local lights (the first three slots after it, each kept by the light that holds it), as Wicked Engine filters its first four; the others are blended with the previous frames'.Settings::ray_traced_shadow_qualityLow filters the directional light's alone, in two passes instead of three, and blends those three local lights' with the rest: noisier soft local shadows for about 1 ms a frame less. While no local light holds one of the three places, High filters the directional light's alone too: the same result within one 8-bit step, for less. A light that takes another's place, a light whosebakedchanges, and a camera cut start afresh. The rays leave from one pixel of each 2×2 block, its even one unless that shows no lit surface or another shows a feature in front that no even pixel sees, so a pole or wire one pixel wide gets its own shadow, against the sky or in front of a wall. The visibilities are upsampled to the render size by depth from the texels about each pixel that hold its surface, then the lighting pass takes them through the light's shadow opacity. A slit one pixel wide showing a far surface between features takes that surface's shadow from the texels about it, which is right where the shadow is coherent over a few pixels and not where it varies at pixel scale, or where the features either side are wider than about two pixels. The opaque stage takes its two-pass form while they run (a G-buffer pass, then a lighting pass), so the setting costs the second geometry pass besides the rays. The volumetric fog, blended surfaces, probe captures, reflections' ray hits and the lights beyond those sixteen keep the maps, which are still drawn.Renderer::ray_traced_shadows_in_effect(&settings, &primary, &scene)says whether the setting is in effect for a view whose frame's primary view hasprimary(whose hardware ray tracing the frame takes); they then run on the frames where a light holds a slot. Without hardware ray tracing in effect the maps shadow everything: SGL3D has no software path for these rays, since on its software BVHs they cost 3–5 times the hardware's with local lights (D-30).
The streaming example and the
dynamic GI example opt in with
--hardware-ray-tracing; the streaming example takes ray-traced shadows
with --ray-traced-shadows.
Settings and capability fallback
settings::Settings holds every rendering setting a game chooses in one serde
value the game stores and passes, per view, to View::new, View::resize
and Renderer::render;
Settings::default() is High with atmosphere allowed. Opt-in features no
preset turns on (hardware ray tracing, ray-traced shadows, occlusion culling,
screen-space indirect light) stay as the game sets them; screen-space
indirect light runs on every device, so it has no *_in_effect query.
Settings lists each field. The game owns its settings
record, file format, controls, defaults, and saving. settings::FrameRate
describes presentation cadence; the renderer does not run a frame limiter.
Keep a saved explicit choice distinct from Preset. Apply the preset only where
the option requests it. Low → High → Low and application restart must preserve
explicit values at the library boundary. A game may implement complete preset
bundles by explicitly replacing its settings fields when it applies one.
SceneResolution::Hd and FullHd fit the scene within 1280×720 and 1920×1080
physical pixels, preserving aspect ratio without upscaling. Full renders at
the full output size; ThreeQuarter/Half scale it. UI output is unaffected.
FSR upscales to that scene size from its quality's render size.
Settings::upscaling optionally enlarges the tone-mapped scene to output
size with the portable spatial filter.
Preserve the highest implemented fidelity as a selectable choice.
Binding tiers
What the lights and a material bind depends on the device's sampled
textures per shader stage, which graphics_device::limits requests from the
adapter, in two tiers (Binding tiers,
D-31). Renderer::binding_tier reports the
device's graphics_device::BindingTier; it is fixed for the device and no
setting chooses it.
| Tier | Sampled textures per stage | Lighting | Material maps |
|---|---|---|---|
Basic |
16 (WebGPU's default, S3D-1's floor) to 47: a browser's default WebGPU adapter, iOS GPUs older than Apple4 (23) | baked light non-directional; no dynamic GI; transmission blended through, unrefracted; no scene depth or volume path for a shader | base, metallic-roughness (with packed occlusion), emission, normal, bump |
Extended |
48 or more: Metal on macOS and Apple4 and later, DX12, Chrome's upper tier | directional baked light; dynamic GI; refracted transmission; scene depth and volume paths for a blended shader | those and the anisotropy, clearcoat, clearcoat roughness, clearcoat normal, iridescence, iridescence thickness, transmission, thickness, sheen colour, sheen roughness, diffuse transmission and diffuse transmission colour maps |
A Vulkan driver lands in either tier, by its maxPerStageResources.
On Basic, Settings::dynamic_gi resolves to Off, which
Renderer::dynamic_gi_in_effect reports without changing the saved
choice, and the renderer builds no dynamic GI stage; a lightmap's or
irradiance atlas's directionality is validated but neither uploaded nor
read.
A map a device does not bind gives way to its factors, as glTF defines a
material without that texture, in raster, probe captures and ray hits
alike; validation still reads every map, so content errors do not depend on
the device. A probe or other bake captured on an Extended device keeps
what its maps and lights did there.
Browser (WASM + WebGPU)
The browser is a first-class target in its own right
(D-20, D-27,
D-48): SGL3D supports there everything WebGPU
supports, and only a feature or speed-up the web platform cannot run falls
back or is absent. The same Scene, Renderer, views and frame run on the page's
WebGPU device, built for wasm32-unknown-unknown (sgl-3d enables wgpu's
webgpu backend). WebGL2 is not supported, since SGL3D needs compute; if
WebGL is ever added it will be a minimal fallback.
- Device. Request it as natively, with
graphics_device::limits(the adapter's limits; WebGPU's defaults are the floor, S3D-1) andgraphics_device::features. Desktop Chrome on Apple silicon reports 48 sampled textures and 10 storage buffers from Chromium 149, theExtendedbinding tier; an adapter at WebGPU's default 16, as Chromium 145 reported, runs onBasic. Render into an offscreen texture or a canvas surface; the page owns the canvas. - Optional features degrade as on any device: without
DEPTH_CLIP_CONTROLdirectional shadow casters emulate unclipped depth in their shader; withoutRG11B10UFLOAT_RENDERABLEbloom's chain is RGBA16F; requestgraphics_device::texture_compression_features(&adapter)for the supported BC, ETC2 and ASTC material formats, then select exported assets usingcompressed_image_feature(format). BC7, ETC2 RGBA8 and ASTC 4×4 each require their matching feature; ETC2/ASTC also carry the prepared ray/decal companion. BC6H probes and compressed baked lightmaps still require BC and are refused without it. Ship the appropriate fallback assets for the device. WithoutTIMESTAMP_QUERYGpuTiming::newreturnsNone. Chrome quantizes timestamps, so browser pass times are coarse. - FSR needs texture atomics, which WebGPU lacks, and subgroup operations,
16-bit normalized formats and storage formats beyond WebGPU's core set,
which wgpu's browser backend does not request: chosen in the browser it
resolves to TAA,
View::antialiasing_in_effectreports TAA andfsr_error()names the missing features. TAA, both screen-space reflection methods, world-space reflections, dynamic GI, ambient occlusion, screen-space indirect light, fog, motion blur, bloom and SMAA run. For reduced-resolution browser rendering, use an explicitSceneResolutionand opt into spatial upscaling. - Inputs, not clocks or files. Fetch asset bytes and load them with
asset::load_sliceorload_slice_with_options;asset::loadreads a file and fails in the browser. The frame time comes fromFrameInput::frame_time_ms; SGL3D reads no clock. - Readbacks are awaited. A browser cannot block on WebGPU, so it awaits
Renderer::capture_specular_probe_asyncand thediagnosticsfeature'sdiagnostics::read_async; their blocking forms,capture_specular_probeanddiagnostics::read, are native-only.
browser_smoke (examples/sgl-3d/examples/browser_smoke.rs) is the browser lane's test and a
minimal page integration: device creation; procedural content (a textured
ground, a shadow-casting box, a masked grate with a BC7 image, a blended
pane that receives screen-space reflections, a skinned and morphed box with an ambient cube, a box lit by a BC6H/BC7
static irradiance atlas, point, spot and rectangle lights, a decal, a BC6H
specular probe, a dynamic GI volume, an irradiance volume written by region,
glow, heat shimmer, mist, a fog volume, a glass pane through a game's shader,
which naga validates in the browser, and an environment);
frames under four settings configurations, read through
diagnostics::read_async; a specular probe capture, every texel of which
must hold the uniform emission of the enclosure around it; and error
scopes. It loads no glTF and sets no lightmap or mesh LODs.
For repeatable performance measurements, run
bun scripts/tasks.ts measure-browser --baseline --frames 180.
The browser baseline guide explains
its generated textured scene, moving content, separate chunk-upload phase,
prepared mip and spatial-upscaling variants, and JSON/capture output. Its
completion timings are offscreen workload measurements, not displayed frame
pacing or a browser Bistro result. The ordinary browser smoke lane verifies
ETC2/ASTC material sampling where the browser exposes those features.
For a real asset workload, follow the Bistro guide
and run measure-browser --bistro, or use --fixture FILE --asset-dir DIR
for another prepared embedded glTF. The same runner records fixed cameras,
requested/effective settings, source provenance, errors, partial resource
accounting and display-output PNGs. Motion sequences complement stills when
judging temporal quality. Keep output size, lighting and warm-up fixed for
controlled comparisons, distinguish partial allocation counts from total
memory, and repeat timing runs without concurrent builds or GPU workloads.
Assets and their licence notices are prepared explicitly, not bundled with
SGL or regenerated by its runtime.
Asset and environment limits
LoadOptions { nodes: Some(&|name| name == Some("head")), ..Default::default() }
selects mesh nodes, from a file or bytes, by a caller-owned predicate for
rigid-part animation. Each mesh node is tested independently; excluded
parents still contribute their transforms. Selection combines with the other
options and uses the same decoding, material support, validation, and
batching as a whole load. An empty selection is an error. Embedded imports
require embedded buffers, and embedded images unless the game supplies them
(LoadOptions::images); games add their asset label to errors. A
LoadOptions borrows its callbacks, which are Sync so one value can serve
loads on several threads: build it where it is used, or store a
LoadOptions<'static> of static or leaked callbacks.
The loader supports glTF triangle meshes, baked rigid node transforms,
skins with four influences per vertex, morph targets, animation clips as data
(Skinned meshes and morph targets),
UV0, TEXCOORD_1 as Vertex::lightmap_uv, metallic/roughness materials, the
opaque, masked and blended alpha modes,
normal and bump maps, an occlusion map packed in the red channel of the
metallic-roughness image (ORM), KHR_materials_clearcoat with its maps,
emissive strength, unlit materials, KHR_materials_anisotropy,
KHR_materials_iridescence, KHR_materials_sheen,
KHR_materials_diffuse_transmission, and the KHR_materials_ior and
KHR_materials_specular factors. A primitive whose material has any map
needs TEXCOORD_0. Each map SGL3D samples needs linear magnification and
trilinear minification (or none set); a map it leaves out may sample any
way. TEXCOORD_1 is the mesh's static irradiance atlas chart: on a static
instance while an atlas is installed, a vertex it charts samples the atlas
and takes no baked lights, so set lightmap_uv to [0, 0] on models the
bake does not chart (one exported with a second UV map for AO, say).
Malformed primitive or morph accessor references, animation target nodes or
paths, and image sources return an error naming the element. Each image must
have exactly one uri or bufferView, with mimeType for a buffer view.
Every accessor the load reads must hold at least one
element, within its buffer view and buffer, of a component type and shape
glTF 2.0 allows for its use (an attribute, indices, a morph target, inverse
bind matrices or keyframes), and as many elements as glTF requires: a
primitive's attributes and morph targets as many as its POSITION, inverse
bind matrices one a joint, and keyframe values as many as their times
need. Sparse indices must strictly increase and stay below the accessor's
count. A sparse accessor without a buffer view that nothing else counts
(POSITION, indices or keyframe times) may declare no more elements than
the file's buffers would hold in a buffer view. An embedded image's buffer view must lie within its
buffer. Any other fails the load with an error naming it.
External buffer and image URIs are percent-decoded relative paths beneath
the glTF's directory (including subdirectories), or embedded base64 data:
URIs. Schemes such as file:, absolute paths, every .. segment, symlinks
and non-regular files are refused with the authored URI in the error.
External buffers must contain exactly their declared byteLength; GLB BIN
chunks may include the format's alignment padding. The input document,
imported buffers and encoded images share a source-byte budget, defaulting to
4 GiB natively or 1 GiB in the browser. File sizes and data-URI decoded sizes are
checked before reading or decoding, and file reads are bounded even if a
file grows. Supplied and unused images are still never read. Move formerly
escaping references beside the glTF and replace symlinks with regular files.
LoadOptions::budget accepts an explicit asset::LoadBudget with independent
source and decoded caps. LoadBudget::new(source_bytes, decoded_bytes) rejects
zero and values above LoadBudget::maximum_bytes() (isize::MAX on the target);
it never clamps them or interprets zero as unlimited. For example, a browser
consumer can opt into two 1536 MiB caps with
LoadBudget::new(1536 << 20, 1536 << 20)?, retaining all other load validation.
Use load_slice_with_options or load_with_options and a default tail for
the remaining fields. These caps are independent, not a combined process
budget. Raising one neither reserves memory nor raises image dimensions or
GPU resource limits: fetch copies, source buffers, decoded assets, preparation
scratch and GPU allocations can coexist. Choose caps from measurements of the
actual consumer and device rather than setting them to the maximum.
Supplied images count toward the same decoded cap: stored compressed mip
bytes and any RGBA companion, or both prepared RGBA mip chains. The KTX2
constructors CompressedImage::from_ktx2_with_budget and
from_ktx2_with_decoded_level_0_and_budget accept the same policy. Their
ordinary counterparts preserve the target's default caps. Budget rejections
name the source/decoded budget, request, remaining bytes and configured limit.
A scene must list each root node once, and only nodes without a parent, as glTF requires. Before it decodes an image or reads an accessor, a load counts the bytes its scene produces from the counts its accessors declare, and fails beyond its configured decoded cap: for each of the scene's mesh nodes, selected or not, its mesh's vertices (88 bytes each, plus 32 for skin influences on a skinned node), indices (4 bytes) and morph target deltas (36 bytes a vertex and target); each skin's joints; and each animation channel's keyframe times and values. A mesh counts again for each node that uses it, so each instance counts. Split a file beyond the chosen cap or explicitly raise the policy after measuring it. Decoded PNG/JPEG images share that scene-data budget: the loader checks their headers before decoding pixels, refuses a side above 16384, and charges width × height × 4 for the retained RGBA8 image before decoding or converting it. Decoder allocation limits use the available budget. 16-bit pixels remain unsupported. The scene also checks the actual device texture limit when adding an image.
A clearcoat normal map tilts the coat alone, on the base normal map's
frame; without one the coat follows the geometry normal. An iridescent
film (iridescence, its iridescence_ior and its thinnest and thickest
iridescence_thickness in nanometres, which its thickness map mixes
between) tints the base's specular reflectance by thin-film interference
at the view, and dims the diffuse beneath it by its strongest channel, as
KHR_materials_iridescence defines it.
glTF 2.0 decides what an extension costs a load. A file that lists an
extension in extensionsRequired that SGL3D does not support fails to load
with an asset-path error. One it lists only in extensionsUsed is left out,
as glTF lets a loader do: a texture keeps its core image and a material its
core values, and Asset::ignored lists it (Ignored::Extension). The list
also names each material whose occlusion map SGL3D does not sample
(Ignored::OcclusionMap): one in an image of its own on TEXCOORD_0,
whose image stays in Material::occlusion_texture, or one on another UV
set, which the load leaves out (occlusion_texture None). It names each
material whose specular textures SGL3D does not sample
(Ignored::SpecularMap). To have occlusion drawn, pack it
into the metallic-roughness image's red channel on TEXCOORD_0 in the
export step. The load reads and decodes only the images a map it samples
uses; each other image, such as a texture extension's source or an
ignored map's image, is a one-texel placeholder that is never bound, and
the list names it (Ignored::Image). A vertex attribute nothing SGL3D
draws reads (TEXCOORD_2 on, COLOR_1 on, or an application-specific
_NAME) is neither checked nor read, and the list names it with its mesh
and primitive (Ignored::Attribute); a second joint and weight set still
fails the load. Other unsupported visible features return asset-path errors.
A dielectric's reflectance at normal incidence (F0) follows its index of
refraction, ((ior − 1) / (ior + 1))²: 0.04 at the default 1.5, 0.02 for water
at 1.33, 0.17 for diamond at 2.42. KHR_materials_specular tints it
(specular_color, at most 1 after the tint) and scales it (specular), as
asset::Material and SurfaceMaterial hold them. Reflectance at grazing
incidence (F90) is specular mixed toward 1 by metallic, as
KHR_materials_specular, Filament and three.js define it, so specular 0 turns
a dielectric's reflection off whole. The occlusion map's red channel, at
occlusion_strength (glTF's lerp), occludes a surface's ambient light, the
baked light of its lightmap, atlas chart or ambient cube (their specular
multiple scattering by specular occlusion) and its environment specular, as
three.js and Godot occlude a light map, never emission. It also shadows the
surface's direct light where a light arrives outside the cone the occlusion
leaves open (micro-shadowing, Filament's computeMicroShadowing), from every
light and in every view, so the cracks a normal map draws shadow under a
raking light; light passed through to a surface's other side takes none
(D-66). With
Settings::ambient_occlusion the camera's opaque surfaces take the lesser of
it and the frame's ambient occlusion for their ambient light and environment
specular, as Filament and Bevy do, while a bake keeps its own.
A sheen (sheen_color, sheen_roughness; KHR_materials_sheen) is a soft
layer for cloth and fabric, brightest toward grazing views: it dims the base
beneath it, including refracted transmission, by the light it takes itself
and lies beneath any clearcoat;
rectangle lights do not light it. Diffuse transmission
(diffuse_transmission, diffuse_transmission_color;
KHR_materials_diffuse_transmission) passes that share of the light the base
diffuses through to the surface's other side, in that colour: leaves, paper,
flags and lampshades lit from behind. The other side takes each light behind
the surface under its own shadow, and its ambient light, which ambient
occlusion does not darken; make such a material double_sided so both sides
draw and cast. With KHR_materials_volume's thickness the light passes
through that far behind the surface (a candle, an ear), its shadow taken
there, and the volume's attenuation colour and distance tint it over that
thickness; without one the surface is thin.
Shading follows one hybrid of references (D-32): glTF 2.0 and its KHR extensions define what a material's values mean, Filament's maths (as Bevy ports it) the BRDF, and three.js r185 what Filament lacks. Every specular lobe takes its multiple scattering under direct light as under the environment (Fdez-Agüera's gain), so a rough metal reflects as much under the sun as under an even sky of the same light, and a dielectric's diffuse under each light keeps what its specular's Fresnel leaves (glTF's dielectric BRDF).
On the GPU the scene keeps each asset::Vertex (88 bytes) in 32, packed by
PreparedModel::new after Godot's attribute compression: the position
exact; the normal and tangent as one rotation, each within 0.01°, the
tangent made perpendicular to the normal and unit; the UV as 16-bit
fractions of its mesh's UV rectangle, within the rectangle's extent over
131,070 per axis, so a mesh whose UVs span many repeats loses precision in
proportion; the colour as 8-bit sRGB with linear alpha, clamped to 0..1 as
glTF's COLOR_0 is; the lightmap UV as 16-bit fractions (a negative one is
unassigned, as before); and the lightmap chart bounds once per distinct
chart in a table of its mesh's. A vertex position, UV and lightmap UV
must be finite, a mesh's UVs must span less than f32::MAX, and a normal
must be finite and not zero (SceneError::NonFiniteGeometry), and a mesh's vertices may name at
most 65,536 distinct lightmap_bounds (SceneError::TooManyLightmapCharts,
which names the mesh's index); a model's meshes together may name any
number.
Material textures are filtered trilinearly with the material's glTF
wrapping, and anisotropically up to Settings::anisotropic_filtering
(settings::AnisotropicFiltering: Off, 2×, 4×, 8× by default, or 16×, as
Godot's levels).
Compressed material images
asset::Image accepts decoded RGBA8 texels (Image::Rgba8, what glTF
loading yields), whose mip chain the scene filters when the image is added;
prepared RGBA8 chains (Image::Rgba8Mips); or a block-compressed chain
(Image::Compressed), uploaded as stored with no mip generation. BC7,
ETC2 RGBA8 and ASTC 4×4 each use 16 bytes per 4×4 raster block, one quarter
of RGBA8's raster texel storage before allocation padding. Their ray and
CPU storage have different costs, described below. Games compress in their
export step and supply
the chains as the glTF loads, so its own images are never decoded:
use ;
// Each glTF image by its index, name and, for an external file, its URI;
// return the game's chain, or `Decode` for the glTF's own.
let sources = ;
let asset = load_with_options?;
The loader asks once per image a sampled map uses, in image order, as
Bevy's glTF loader resolves each image's source; a supplied image takes the glTF image's index,
which its materials address. An embedded glTF (load_slice_with_options)
may refer to external image files when each one a sampled map uses is
supplied.
CompressedImage::from_ktx2(bytes) rejects malformed data format descriptors
with an error, then reads a KTX2
file of one supported 2D compressed image, including BC7
(VK_FORMAT_BC7_UNORM_BLOCK or _SRGB_BLOCK).
from_ktx2_with_decoded_level_0(bytes, texels) accepts ETC2 RGBA8
(VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK or _SRGB_BLOCK) and ASTC 4×4
(VK_FORMAT_ASTC_4x4_UNORM_BLOCK or _SRGB_BLOCK) with a matching RGBA8
level-zero companion. ETC2/ASTC can also be loaded without a companion for
material use in a RayData::Disabled scene. All accept stored levels, uncompressed or
Zstandard-supercompressed, as Bevy reads
them. It refuses zero or non-block-aligned dimensions, sides above 16384,
more than a full mip chain, and declared or decoded level sizes that differ
from their format's block size. The decoded chain and any companion share
the chosen decoded budget (default 4 GiB native or 1 GiB browser), checked
before allocating levels; the whole KTX2 source is checked against its
source budget before parsing. Zstandard
decoded output length is capped at the expected level size plus one sentinel byte.
The decoder never allocates its advertised history window; regenerated
literals and sequences are checked against the format's 128 KiB block
maximum before growing buffers. The private decoder is vendored from zstd-rs under MIT OR Apache-2.0;
provenance and local adaptations identify
the reviewed source. Its notices ship with SGL3D’s bundled-code notices.
The budget counts decoded bytes; bounded decoder working buffers and
allocator capacity are additional, so it is not a peak-memory limit.
As for RGBA8, the channel picks the colour space: base and emissive
maps sample it as sRGB, the others as linear data. Filter a colour image's
levels in linear light. Its stored levels serve every channel that samples
it, so a data channel sampling an image also used as colour reads the
colour-filtered levels: a data use that needs its own filtering needs its
own image. An image sampled both ways is one texture with an sRGB view,
which needs DownlevelFlags::VIEW_FORMATS (wgpu's GL backend lacks it:
SceneError::CompressedImageViews). from_ktx2 reads bytes, so its caller
adds the asset's path to its errors. Request the adapter-supported
features returned by graphics_device::texture_compression_features at
device creation and select the export whose
graphics_device::compressed_image_feature(format) is enabled. Adding a
format without its feature returns SceneError::CompressionUnsupported.
Sides must be multiples of 4 and at most 16384, with one to a full chain
of exact-size levels (SceneError::InvalidCompressedImage).
BC7 rays read level zero's stored blocks, preserving the native compressed
path. ETC2/ASTC rays and decals use CompressedImage::decoded_level_0, an
RGBA8 image with matching dimensions, required by those consumers but not
by raster-only material textures. Export it from the decoded
compressed image if ray and raster texels must match exactly; the runtime
checks structure and byte budgets, not semantic agreement. It does not run
an ETC2/ASTC CPU decoder or Basis Universal transcoder. A malformed companion
is always rejected; a missing one yields SceneError::MissingDecodedImage
before ray-enabled material or decal mutation. BC7 needs no companion.
Ray-enabled ETC2/ASTC retain one compressed raster chain plus a
4-byte-per-texel ray copy and the caller's companion/download costs, so their
total saving is not the raster chain's fourfold reduction. No-ray consumers
should leave the companion out of their fetch/decode plan as well as GPU
upload to avoid paying its CPU/WASM cost unnecessarily.
For an uncompressed fallback prepared outside the render-critical thread,
construct Rgba8MipChain::new(image) and pass Image::Rgba8Mips(chain).
This pure Send value owns immutable full chains filtered separately in
linear-light colour and linear data, so one image can serve both roles.
Scene upload uses those stored levels without filtering them again. Preparing
both full chains retains roughly twice one RGBA8 mip chain; the constructor
checks its platform byte budget before expansion, with filter scratch memory
additional. The caller chooses the worker and when to prepare it; SGL3D
starts no thread.
Keep asset fetches and chunk selection game-owned: export independent bounded
GLB/KTX2 groups, prepare geometry with PreparedModel, and add each group
between frames rather than putting a whole large scene in one browser load.
The offscreen
example's --alpha grate is a BC7 KTX2 chain, which
cargo run -p sgl-3d-examples --example export_grate writes.
For anisotropic materials, supply Vertex::tangent = [tx, ty, tz, handedness]
with handedness +1 or -1, plus authored normals. Legacy meshes may leave the
appended tangent at [0.; 4]. Material::anisotropy_strength is finite 0..=1;
anisotropy_rotation is counter-clockwise radians; anisotropy_texture selects
linear RG direction (remapped to -1..1) and B strength. No texture means +T and
full texture strength, as on a device of the Basic binding tier,
which binds no anisotropy map. File and embedded glTF imports use the same rules.
Active anisotropy requires authored tangents; automatic tangent generation is
not implemented. Normal maps and anisotropy share that frame. A tangent
within 0.02° of its normal (as authored or after node transforms) spans no
frame: it fails the load of an anisotropic material and is absent
(Vertex::tangent zero, with no morph-target tangent delta) on any other.
Where skinning or morphing cancels a tangent or turns it along its normal,
shading takes an arbitrary tangent in the normal's plane, keeping the
authored handedness (+1 where there is none), as for a vertex without one.
Node and instance transforms preserve mirrored handedness, nonuniform scaling and shear.
Scene::set_material exposes SurfaceMaterial::anisotropy_strength and
anisotropy_rotation; the anisotropy map, like every map, stays as the
material was added. Invalid values, or activation
while any mesh drawn with the material (in any model, or as a level of detail)
lacks tangent frames, return an error without changing CPU/GPU material state.
Tangent-capable LOD replacements must preserve tangent frames, including when
strength is currently zero. Adding a material with invalid anisotropy, or a
mesh without tangent frames drawn with an anisotropic material, returns a
SceneError.
Directional, point and spot lights and secondary hit shading use anisotropic GGX;
rectangle lights use the isotropic GGX fit, as Bevy's do. The base
lobe in environment and connected probes uses the KHR bent-normal approximation;
clearcoat and screen-space rays remain isotropic. The isotropic multiple-scattering
gain and reflection filters remain approximations: narrow reflected lights can
have large errors. Receiver transport adds one
RGBA16F target (8 bytes/pixel); fused rendering needs eight color attachments and
64 attachment-budget bytes, with separate material rendering on lower limits.
Both paths derive the anisotropic tangent from the decal-adjusted base normal.
The procedural example supports --anisotropy 0.5 to exercise this path.
Stable normal RGBA16F stores signed octahedral world-space base normals in RG and coat
normals (the clearcoat normal map's, else the geometry normal) in BA. Each pair uses Bevy's signed [-1, 1] octahedral
coordinates and gbuffer_octahedral_decode (see src/shading/gbuffer.wgsl);
there is no unsigned remapping, preserving binary16 precision around zero.
Stable material RGBA16F stores coat roughness, base
roughness, coat strength and the base's grazing reflectance (F90). Metallic
reflectance is already carried by F0 and F90; the material target does not
duplicate metallic. The anisotropy RGBA16F stores the tangent in signed
octahedral RG, its strength and the environment scale. The mapped base
normal controls base environment/probe lighting; the coat normal controls
coat lighting and the traced coat lobe, including when SSR is off.
environment::EnvironmentMap holds a caller-selected panorama and its matching
Three-compatible prefiltered PMREM atlas; Scene::add_environment adds one,
and FrameInput::environment names the frame's (FrameEnvironment::Map). PMREM data is RGBA16F with
explicit width/height; the library uploads supplied data rather than reading
game paths or requiring a browser at runtime. Environment authoring/export remains with the
game. The current representation is an extracted renderer boundary, not a
complete environment asset pipeline.
Code structure
SGL3D architecture is the shape this code
follows: its layers, the stage order, the shared contracts and the rules for
changing them. World-space reflection and dynamic GI rendering trace pipelines retain
only the current and previous lighting specialisations, including their reach
variants and ray forms. src/lib.rs declares the layers and re-exports the public
surface. The layers, in order: src/content/ (CPU data and loading: asset
and its glTF import, lighting, light, decal, static_lighting, environment,
probe descriptions, ...; no wgpu), src/shading/ (the WGSL library composed by
shading::compose, the geometry and caster programs (shading::programs),
a game shader's contract and validation (shading::shader), and its Rust
mirrors), src/scene/ (Scene, its GPU
buffers and the ray-query structure built from its geometry), src/view/
(views, draw lists, the geometry pipeline cache, and what the renderer lends
stages: the frame's context, the effective configuration, the shared targets,
group 0 and DiligentFX's context), src/stages/ (one module per stage, whose
documentation states what it reads, writes and honours) and src/renderer/
(Renderer and its shared part in shared.rs, View in view.rs, the
frame's order in frame.rs, the effective configuration's
resolution in effective.rs and the probe capture's order in
probe_capture.rs).
Validation and diagnostics
From the SGL root:
The required check also builds the crate for wasm32-unknown-unknown and runs
its pure tests there, and its browser lane renders the browser_smoke
example on WebGPU in headless Chromium
(Browser). GPU/reference tests marked ignored require their documented adapter/tools or
retained capture inputs; the ordinary test command does not establish those
results. Run relevant cases explicitly when changing their boundary. The
diagnostics feature adds Settings::diagnostics (settings::Diagnostics,
not serialized: switches that turn a layer off, the numerical frame probe
and the tone-target capture), View::diagnostic_target (the frame's
targets: depth, normals, motion, source identity, the composite, ambient
occlusion, the captured tone-mapped target, the exposure, and Antialiased,
the completed linear HDR scene as antialiasing leaves it, before motion blur,
bloom and tone mapping),
View::take_frame_probe_reports (source-to-black comparisons run only
when the actual observed textures have equal dimensions, including FSR
fallbacks),
View::geometry_stats_by_model and View::geometry_stats_for_model (the
camera's submitted geometry by model, read back with geometry_stats),
diagnostics::read_async (natively
also the blocking diagnostics::read),
diagnostics::source_id, the value the source-identity target holds for an
instance's pixels, diagnostics::crystal_roughness_threshold, where
Crystal stops tracing, diagnostics::counters (what sgl-3d itself counted on
the thread: uploads by file and line, buffers created, the steps of
preparing and placing models and of building instance BVHs, ray-source and
geometry-slab growths, static-edit boxes and the hardware path's
acceleration-structure builds and compactions; subtract
two with Counters::since, and compare versions by totals since lines move),
Scene::diagnostic_resources (the scene's buffer sizes and BLASes, and the
draw candidates', sets', level chains' and each GPU-built view's cluster
list's bytes), View::diagnostic_draws (the last frame's camera, blended
and cascade draws as encoded: a GPU-built view's one per set and phase,
and a cascade's second per opaque set, its paired sections' indexed draw),
View::diagnostic_view_times (the CPU time the camera's and each
cascade's draw list took to build, preparing and encoding its cull, and to
record), and Diagnostics::dynamic_gi with
Renderer::take_dynamic_gi_reports (diagnostics::DynamicGiReport: each
observed frame's number, its dynamic GI probes, rays, BVH node visits and
budget stride and what kept the volume awake, read back without blocking;
take them each frame once its work completes, or a report counts the
frames skipped while 8 readbacks waited). The streaming and
irradiance_volume examples print these for their routes, the
dynamic_gi example's --counters its volume's reports, and
bun scripts/tasks.ts measure-browser the view times of the streaming world
in headless Chromium.
Diagnostics are
configuration: the library reads no environment variables and writes no files.
Normal rendering does not require the feature.
Follow the rendering development rules. Existing reference fixtures and diagnostics may be deleted or regenerated when the implementation they pin is replaced.
First-party code is MIT OR Apache-2.0. Retained SMAA and Three.js components
keep their original notices; see third-party notices.
Ported code keeps its licence text beside the source and is listed in
scripts/license-notices.ts.
Spatial mesh LOD
Games can split a large model's mesh into spatial chunks and add authored
alternatives as other models that no instance places (a model draws all its
meshes, so an alternative never comes from the model it details). Then
register each chunk's detailed-to-coarse alternatives, at most
lod::MAX_MESH_LODS (8) a mesh (SceneError::TooManyLods past it):
scene.set_mesh_lods?;
max_error bounds displacement in the original mesh's local metres. Alternatives
must use the same coordinate system and preserve interpolated UVs, vertex colors,
normals and baked-light charts; geometric error alone does not bound shading error.
The game owns simplification and its numerical evidence. An empty alternative
can remove a tiny feature only when its error bounds the entire feature.
set_mesh_lods(..., Vec::new()) restores the detailed mesh, and replacing the
base model's geometry clears its alternatives. A model named as an alternative
cannot be replaced or removed while it is.
While world-space reflections are inactive, all primary raster passes choose the
last alternative whose conservative projected error is at most 0.5 pixels, using
the FrameInput camera and the render size. With effective world-space reflections
(Moving or All), the opaque/masked GPU list and blended CPU list retain full
detail so raster receiver identities match the geometry scene rays trace, including
at grazing angles. This increases primary raster work for registered LOD meshes;
it adds no ray geometry or storage. Asking for world-space reflections while their
screen-space prerequisite is off keeps LOD selection active.
The bound includes scale, perspective division and
distance to the nearest chunk corner; chunks crossing the near plane retain full
detail. The camera's opaque and masked surfaces choose on the GPU, by the
same bound computed in f32 under margins that cover its rounding, so they
never draw an alternative coarser than the CPU bound admits, and may keep a
finer one at the margin; the blended list chooses on the CPU. Original object/material bindings retain lightmap and atlas lighting. Pulled
reflection-source geometry uses the selected alternative's actual triangle words,
not the original triangle IDs. Probes, shadows and scene rays deliberately retain
the original geometry: this feature reduces primary raster work, not ray geometry
storage or offscreen capture costs. No LOD registration leaves rendering unchanged.
View::geometry_stats(&device) returns static- and moving-instance
(draws, triangles) pairs (GeometryStats, summed by total()) for the
primary raster population of the most recent completed frame, after
visibility, frustum, material and level-of-detail culling and before GPU
backface culling: its opaque and masked surfaces counted on the GPU, a draw
per section of at most 128 triangles, read back without blocking (the map is
requested at finish_frame), with its blended surfaces' instanced draws
from the same frame, a draw per batch and range, whose triangles count once
per instance. It is None until a frame's readback has arrived, a few
frames after the first. It excludes shadow, probe and ray work. With the
diagnostics feature, View::geometry_stats_for_model(&device, &scene, model) counts the same frame's sections of one model's instances and the
blended draws that hold one, with their triangles. For several models, call
View::geometry_stats_by_model(&device) once and use report.for_model(model)
for each model. The borrowed report holds one completed camera frame while
those lookups run. None means no readback has completed. When a newer
readback is pending, the previous completed report remains available.
Soft additive effects
Scene::update_effects takes a triangle list of effects::Glow vertices,
each with its kind (GlowKind), the same across a triangle:
Uniform: the interpolated colour.Tapered { uv, profile }: alpha shaped overuvby aGlowProfile, whole at v = 0 and gone at v = 1 (taper), rippling in bands across u that slant along v (ripple_frequency,ripple_amplitude).GlowProfile::default()is SGL3D's own tapered sine.Line { other, offset }: a line one pixel wide toward the endpointother, the vertexoffsetpixels across it (-0.5 and 0.5 span it).
use ;
let flame = ;
Set Glow::soft_distance to a positive distance in metres for a linear
intersection fade against opaque primary geometry; use 0.0 for hard edges and
screen-space motion lines. Keep this field constant across each triangle.
Glow::default() is uniform, hard-edged and colourless.
The renderer honors it both where effects are drawn into the reflection input
and onto the composed frame, including own-depth volume transmission. Geometry
generation remains game-owned. See the reference and numerical
evidence for the supported projection and composition
boundaries.
Bounded heat shimmer
Scene::update_heat_distortion(queue, &[heat_distortion::HeatDistortion])
accepts a world-space triangle list. The game authors coverage,
vertex displacement in scene pixels (X right/Y down), edge weights and animation:
use HeatDistortion;
let plume = positions.map;
scene.update_heat_distortion?;
settings.heat_distortion = true; // Settings: on or off; default is Off.
The retained list holds at most 6,144 vertices (2,048 triangles), with finite positions, displacement within +/-32 pixels per axis and weights in 0..=1. Invalid or oversized submissions return an error and retain the previous list; an empty list clears it. Use zero weights on silhouette vertices. The library adds no noise, clock, simulation, geometry generation or temporal history.
Composition snapshots the complete camera HDR source after reflections, fog, blended surfaces, additive effects and mist, then overwrites only submitted triangle coverage before bloom, antialiasing, tone mapping and the game's HUD. Medium transport and additive attenuation are not applied again. Displacement is scaled to render pixels, so it keeps its scene-pixel size under FSR. Each displacement samples the immutable snapshot; overlapping triangles use submission order, without repeated refraction. Off/empty skips the copy and draw. One full-size HDR snapshot is retained and replaced on resize; geometry storage is retained. Thus Off avoids a full-frame copy plus bounded raster work.
The method follows Tiago Sousa, GPU Gems 2 (2005), chapter 19,
§19.1 and §19.2,
reviewed 2026-09-25. Conformance mapping: immutable scene texture corresponds to
S; submitted interpolated vectors replace the sampled normal-map XY field;
opaque depth replaces the alpha refraction mask. Every contributing bilinear
tap must be behind the plume's interpolated device depth, including at foreground
edges. Offscreen footprints fall back to the undisplaced pixel rather than clamp.
Zero weight and pixels outside coverage remain exact. This is approximate
camera-path shimmer, not physical refraction or reflected-ray distortion; already
composited medium is warped too. It does not reconstruct hidden scene layers,
refract successive overlapping surfaces, or contribute to reflection sources.
stages::transparent::heat::tests::bounded_sampling numerically exercises the actual shader
against a linear radiance ramp and independently rasterized foreground stripe,
including resize, zero displacement/weight and viewport rejection.