Expand description
Caller-driven 3D rendering for SGL, native and in the browser (WASM + WebGPU). Games own composition, simulation and content.
Re-exports§
pub use settings::ToneMapping;pub use glam;
Modules§
- asset
- glTF 2.0 mesh loading for the SGL renderer.
- baked_
specular_ probe - Caller-authored static specular probes: local image-based lighting with parallax-corrected cubemaps (Lagarde and Zanuttini, SIGGRAPH 2012), as HDRP, Unreal, Godot, Wicked and Bevy use under screen-space reflections. Each probe is a prefiltered cube with an influence box, where receivers use it, and an optional proxy box, which corrects parallax. Capture is a blocking authoring operation; installing a collection only uploads it.
- deformation
- What deforms a mesh (a skin, morph targets or both), and the rig and
animation clips a loaded asset is posed by, as plain data. The game
samples and blends clips, poses the rig’s nodes and gives each deforming
instance its joint matrices and morph weights every frame
(
Scene::set_instance_deformation); SGL3D renders the pose it is given. - effects
- Caller-authored additive geometry.
- environment
- Original browser skies and exact Three PMREM atlases; see native-sky-export.html.
- geometry
- CPU triangle extraction and ray intersections for caller-owned scene geometry.
- graphics_
device - Device limits and features for the 3D renderer, native or WebGPU.
- heat_
distortion - Caller-authored heat shimmer geometry.
- lod
- Caller-authored spatial mesh alternatives, bounded in primary-camera
pixels (
Scene::set_mesh_lods). - settings
- The game’s rendering settings: one
Settingsvalue the game chooses, stores and passes to the renderer, offering players as many of them as it wants. Preset choices leave explicit overrides intact. - shader
- A game’s material shaders (
Scene::add_shader): their source, what a material names, the parameter block’s layout, why a module is refused, and the contract’s limits. - static_
lighting - Caller-baked, camera-independent diffuse light on static instances’ UV charts. Values are irradiance / PI, separate from albedo and visible emission.
- timing
- Per-pass GPU time from render/compute pass
timestamp_writes.
Structs§
- Asset
Ids - The identities
Scene::add_assetgave an asset’s content: its materialiismaterials[i], and its meshes aremodel’s, in order. - Auto
Exposure - Bevy’s auto exposure: a 64-bin histogram of the frame’s log2 luminance
(after
Exposure::stops) from -8 to 8 through a metering mask, whose average without the darkest and brightest 10% of samples sets a target that makes that average the compensation curve’s stops above 1. Luminance below the range positions the 10-90% window but stays out of the average (-8 where nothing else is left); above it counts in the highest bin. The correction moves toward the target at the authored speeds, linearly while far from it and exponentially within 1.5 stops, against jitter when the target keeps moving slightly, never stepping past it however long the frame, and restarts at the target when history does.frame_time_mstimes it. The range, filter and 1.5 stops are Bevy’s defaults and SGL3D’s. - Baked
Specular Probe - One probe of a collection.
- Bloom
Parameters - Bevy’s energy-conserving bloom: the scene downsampled through a mip
chain and upsampled back, each level blended into the next finer one,
and the result blended into the scene. SGL3D shapes the halo as Bevy’s
Bloom::NATURALdoes. - Camera
- A render camera. Projection uses reversed-Z device depth (1 near, 0 far),
normally from
perspective, in Y-up world space. - Color
Grading - Bevy’s colour grading, applied to the exposed scene before tone mapping,
except
global.post_saturation, after it. The default adjustments are neutral.Settings::tone_mappingselects the display transform. - Color
Grading Global - Grading of the whole image.
- Color
Grading Section - Grading of one section: saturation and contrast, then the ASC CDL
(colour × gain + lift)^(1 / gamma). - Compensation
Curve - Bevy’s exposure compensation curve: stops added to the target for the frame’s metered average log2 luminance. Linear between its points and constant beyond its ends; with none it adds nothing.
- Decal
- A box that projects images onto the lit surfaces inside it, changing their
base colour and, with the maps it has, their normal, roughness and
metallic before they are lit, so reflections and every view see the
change: scene content, added with
Scene::add_decal. Godot’sDecal. - DecalId
- A decal of a scene: a box that projects images onto surfaces.
- Decal
Image Id - An image a scene’s decals project.
- Directional
Light - A light at infinity, such as the sun or the moon (Bevy’s
DirectionalLight, Godot’sDirectionalLight3D, Filament’s directional light). - Directional
Shadow - A directional light’s cascaded shadow, which SGL3D splits and fits from
the camera (Godot’s
DirectionalLight3Dsplits, Bevy’s cascade fit). The camera’s view depth from its near plane todistanceis split intocascades, each a shadow map of the same size covering a farther and larger part of the view, so texels near the camera are small. SGL3D places the splits as Godot does by default: each cascade but the last ends 0.1, 0.2 and 0.5 of the way from the near plane todistance, and the last atdistance. - Dynamic
GiVolume - Where a scene’s dynamic diffuse GI probes lie: a lattice of probes the
game places over the part of its world it wants lit by bounced light, as
RTXGI’s and Wicked Engine’s DDGI volumes are. Each frame traces rays
from the probes through the scene, keeping each probe’s irradiance and
the distances to what surrounds it up to date, and surfaces within the
lattice take their indirect diffuse light from the probes about them
(
Settings::dynamic_gisets how many rays). How the probes are kept up is SGL3D’s. - Environment
Id - An environment map of a scene.
- Environment
Light - The frame environment’s map turned about +Y and scaled where it lights
one lobe:
FrameInput::diffuse_environmentorreflection_environment. Bevy’sEnvironmentMapLightand Filament’sIndirectLightcarry the same rotation and intensity but scale diffuse and specular together. - Exposure
- The frame’s one exposure, which the tone map and FSR both take.
- Fog
- The frame’s participating medium, which the volumetric fog lights with
the frame’s directional lights and their cascades, the scene’s point, spot
and rectangle lights with their shadows, and the frame’s ambient light.
The fields are Godot’s volumetric fog (
EnvironmentandFogMaterial): the medium’s density falls off aboveheightas Godot’s fog material’s does, and the camera’s froxel volume reacheslengthmetres. The scene’s fog volumes (Scene::update_fog_volumes) add medium where they lie. - FogVolume
- A box of medium added to the frame’s fog (
FrameInput::fog) where it lies: Godot’s boxFogVolumewith itsFogMaterial’s density, albedo and edge fade. Volumes add their density where they overlap. - Frame
Input - One frame’s camera, authored look and per-frame state.
- Geometry
Stats - The camera’s submitted geometry by instance mobility, after visibility, culling and LOD selection and before GPU backface culling: (draws, triangles). Its opaque and masked surfaces are GPU-built, counted on the GPU, one section of at most 128 triangles a draw; its blended ones are CPU-built, one instanced draw a draw, which holds instances of one mobility and submits its triangles once per instance.
- Hemisphere
Light - A sky and ground fill (Three.js’s
HemisphereLight): a surface facing straight up receivessky_colorand one facing straight downground_color, blended by the normal’s height, timesintensity, as irradiance on the directional lights’ scale. It lights diffuse surfaces only. - Instance
Id - An instance of a scene: a model placed in the world.
- Instance
State - What a scene shows of an instance.
Scene::add_instanceandScene::set_instancetake it;Scene::instancereturns it. - Irradiance
Cell - One cell of an irradiance volume: an ambient cube of its own light and how much of the frame’s ambient reaches it, each in the cube’s face order +X, −X, +Y, −Y, +Z, −Z. A face is what a surface facing that way receives: a surface takes the three faces its normal points to, weighted by the normal’s squared components (Valve’s ambient cube, as Bevy’s irradiance volume samples it).
- Irradiance
Volume - Where a scene’s irradiance volume lies: a lattice of cells the game
places over the part of its world it lights from a field it computes,
such as a voxel world’s propagated sky and block light at a metre or a
level’s bake, and keeps up by region (
Scene::write_irradiance_cells). Every surface within the lattice, static or moving, takes its indirect diffuse light from the cells about it unless a lightmap or irradiance atlas chart lights it; across the lattice the volume stands in for the dynamic GI volume and ambient cubes. A cell the game has not written reads as the frame’s ambient whole with no light of its own. - Light
- A point, spot or rectangle light: scene content, added with
Scene::add_light. Its light falls off with the inverse square of distance (a rectangle’s, of its distance to each point of its face) and fades smoothly to nothing atrangefrom its position (Filament’s punctual lights, Bevy’s rectangle lights). - LightId
- A point or spot light of a scene.
- Local
Shadow Stats - The last rendered frame’s local-light shadows
(
View::local_shadow_stats). - Material
Id - A material of a scene: its surface values and the textures they sample.
- Material
Shader - A material’s shader and what culling must allow for it
(
SurfaceMaterial::shader). - Metering
Mask - Bevy’s metering mask as a 16×16 grid over the frame, rows top to bottom: each weight scales how much the pixels under it count in metering, from 0 (not at all) to 255 (fully), quantized to 16 levels as Bevy does.
- Mist
- The look of the mist billboards at the scene’s mist positions
(
Scene::update_mist), shaded by animated noise. - ModelId
- A model of a scene: an ordered list of meshes, each with one material.
- Model
Mesh - One mesh of a model: an indexed triangle list drawn with one material of the scene.
- Motion
Blur Parameters - Motion blur’s authored strength, which
settings::MotionBlurscales. - Normal
Layer - One layer of a material’s scrolling normals
(
SurfaceMaterial::normal_layers): the material’s normal map drawn at its own scale, moving across the surface. - Prepared
Irradiance Region - A box of irradiance volume cells packed for
Scene::write_irradiance_cells: validated and encoded as the volume’s texture holds them, without a device, on whichever thread the game chooses, so a relight’s packing stays off the thread that renders. The write then only copies it to the queue. - Prepared
Model - A model’s geometry, prepared for
Scene::add_modelorScene::set_modelbyPreparedModel::new, which needs no device and no scene: build it on any thread and give it to the scene on the one that edits it. The operation consumes it. - Prepared
Model Options - Capabilities of a prepared model. Its ray-data mode must match the scene that takes it; existing constructors retain ray data.
- RayTracing
Stats - What the last rendered frame’s hardware ray tracing held
(
Renderer::ray_tracing_stats), counted over the capture-visible instances rays stop at (those whose model has a mesh that is not blended); zero for a frame that built no acceleration structures. - Renderer
- What every view of a
Sceneshares: the geometry pipelines and the bind group layouts, the deform stage, the dynamic GI stage with its probes, the device’s ray-query form, and the frame boundary. Each frame, after editing the scene:View::resizeeach view (cheap when nothing changed),Renderer::renderthe scene’s views into an encoder, submit it, thenRenderer::finish_frame. It reads the scene and does not change its content. It shows one scene at a time: another scene specialises its pipelines again and restarts its dynamic GI, so a game that shows two scenes at once holds a renderer for each. - Scene
- Retained content and the GPU buffers mirroring it, which a
Rendererrenders. A scene starts empty; the game adds, edits and removes content between frames, and each addition returns the content’s identity. Content only: rendering settings aresettings::Settingsand each frame’s camera and look are aFrameInput. All dimensions are metres, Y-up. - Scene
Options - Immutable retained-scene capabilities, chosen before adding content.
- Shader
Id - A shader of a scene: a game’s WGSL module its materials name.
- Shader
Source - A game’s WGSL module:
material_vertex,material_surfaceandstruct ShaderParams, over the contract’s structs, declaring onlyconst,struct,aliasandfn.Scene::add_shadervalidates it. - Specular
Probe Box - An axis-aligned box in a probe’s local frame.
- Specular
Probe Radiance - A GGX-prefiltered cube: perceptual roughness level/6 at mip
level, seven levels fromface_sizedown.texelsrun level-major, then the six faces in WebGPU cube order, then rows. Faces follow the capture views’ Z-mirrored convention. - Surface
Material - A material’s values, read by
Scene::materialand replaced byScene::set_material. Author initial content withasset::Material; the textures it was added with stay as they were. - View
- One camera’s frame of a scene: its targets and sizes, its stages with
their state, group 0’s bindings, and every history kept in screen space
or fit to its camera. A game creates one for each image of the scene it
draws (a window, each half of a split screen, an inset, a rear view, an
editor’s viewports), sizes it with
View::resize, lists it inRenderer::renderand drops it when it is done, which releases everything it held. Its history continues only from its scene’s last finished frame, so a view that a finished frame of its scene did not render restarts, as on a cut. - View
Frame - One view’s part of a frame (
Renderer::render): the view, its camera and frame values, its settings and the texture it renders into, a view of its output format and size (offscreen or a surface’s). Scene work is timed with the primary view’stiming.
Enums§
- AgxLook
- Filament’s AgX looks (
AgxToneMapper::AgxLook): a creative contrast and saturation within AgX, after its curve. - Alpha
Mode - How a material uses its alpha: glTF’s
alphaMode, with Bevy’sAlphaModenames (Bevy 9d12036, its phases and pipeline keys incrates/bevy_pbr/src/material.rs). - Backdrop
- What the camera sees where no surface is (Godot’s background mode,
Filament’s
Skybox). - Compensation
Curve Error - Why a compensation curve was refused.
- Light
Shape - Where a light shines.
- Mobility
- Whether an instance moves, chosen when it is added.
- Probe
Error - Invalid caller data or failure of the explicit GPU authoring operation.
- RayData
- Whether a scene retains data used only by ray queries. Raster geometry, deformation and shadow maps are available in both modes.
- Scene
Error - A
Sceneoperation’s refusal. - Specular
Probe Texels - A probe’s stored radiance.
- View
Error - Why a view could not be created.
Functions§
- perspective
- Reversed-Z, infinite-far, right-handed perspective. Device depth is
near / distance: 1 at the near plane, approaching 0 at infinity.