Skip to main content

Crate sgl_3d

Crate sgl_3d 

Source
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 Settings value 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§

AssetIds
The identities Scene::add_asset gave an asset’s content: its material i is materials[i], and its meshes are model’s, in order.
AutoExposure
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_ms times it. The range, filter and 1.5 stops are Bevy’s defaults and SGL3D’s.
BakedSpecularProbe
One probe of a collection.
BloomParameters
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::NATURAL does.
Camera
A render camera. Projection uses reversed-Z device depth (1 near, 0 far), normally from perspective, in Y-up world space.
ColorGrading
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_mapping selects the display transform.
ColorGradingGlobal
Grading of the whole image.
ColorGradingSection
Grading of one section: saturation and contrast, then the ASC CDL (colour × gain + lift)^(1 / gamma).
CompensationCurve
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’s Decal.
DecalId
A decal of a scene: a box that projects images onto surfaces.
DecalImageId
An image a scene’s decals project.
DirectionalLight
A light at infinity, such as the sun or the moon (Bevy’s DirectionalLight, Godot’s DirectionalLight3D, Filament’s directional light).
DirectionalShadow
A directional light’s cascaded shadow, which SGL3D splits and fits from the camera (Godot’s DirectionalLight3D splits, Bevy’s cascade fit). The camera’s view depth from its near plane to distance is split into cascades, 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 to distance, and the last at distance.
DynamicGiVolume
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_gi sets how many rays). How the probes are kept up is SGL3D’s.
EnvironmentId
An environment map of a scene.
EnvironmentLight
The frame environment’s map turned about +Y and scaled where it lights one lobe: FrameInput::diffuse_environment or reflection_environment. Bevy’s EnvironmentMapLight and Filament’s IndirectLight carry 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 (Environment and FogMaterial): the medium’s density falls off above height as Godot’s fog material’s does, and the camera’s froxel volume reaches length metres. 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 box FogVolume with its FogMaterial’s density, albedo and edge fade. Volumes add their density where they overlap.
FrameInput
One frame’s camera, authored look and per-frame state.
GeometryStats
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.
HemisphereLight
A sky and ground fill (Three.js’s HemisphereLight): a surface facing straight up receives sky_color and one facing straight down ground_color, blended by the normal’s height, times intensity, as irradiance on the directional lights’ scale. It lights diffuse surfaces only.
InstanceId
An instance of a scene: a model placed in the world.
InstanceState
What a scene shows of an instance. Scene::add_instance and Scene::set_instance take it; Scene::instance returns it.
IrradianceCell
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).
IrradianceVolume
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 at range from its position (Filament’s punctual lights, Bevy’s rectangle lights).
LightId
A point or spot light of a scene.
LocalShadowStats
The last rendered frame’s local-light shadows (View::local_shadow_stats).
MaterialId
A material of a scene: its surface values and the textures they sample.
MaterialShader
A material’s shader and what culling must allow for it (SurfaceMaterial::shader).
MeteringMask
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.
ModelMesh
One mesh of a model: an indexed triangle list drawn with one material of the scene.
MotionBlurParameters
Motion blur’s authored strength, which settings::MotionBlur scales.
NormalLayer
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.
PreparedIrradianceRegion
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.
PreparedModel
A model’s geometry, prepared for Scene::add_model or Scene::set_model by PreparedModel::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.
PreparedModelOptions
Capabilities of a prepared model. Its ray-data mode must match the scene that takes it; existing constructors retain ray data.
RayTracingStats
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 Scene shares: 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::resize each view (cheap when nothing changed), Renderer::render the scene’s views into an encoder, submit it, then Renderer::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 Renderer renders. 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 are settings::Settings and each frame’s camera and look are a FrameInput. All dimensions are metres, Y-up.
SceneOptions
Immutable retained-scene capabilities, chosen before adding content.
ShaderId
A shader of a scene: a game’s WGSL module its materials name.
ShaderSource
A game’s WGSL module: material_vertex, material_surface and struct ShaderParams, over the contract’s structs, declaring only const, struct, alias and fn. Scene::add_shader validates it.
SpecularProbeBox
An axis-aligned box in a probe’s local frame.
SpecularProbeRadiance
A GGX-prefiltered cube: perceptual roughness level/6 at mip level, seven levels from face_size down. texels run level-major, then the six faces in WebGPU cube order, then rows. Faces follow the capture views’ Z-mirrored convention.
SurfaceMaterial
A material’s values, read by Scene::material and replaced by Scene::set_material. Author initial content with asset::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 in Renderer::render and 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.
ViewFrame
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’s timing.

Enums§

AgxLook
Filament’s AgX looks (AgxToneMapper::AgxLook): a creative contrast and saturation within AgX, after its curve.
AlphaMode
How a material uses its alpha: glTF’s alphaMode, with Bevy’s AlphaMode names (Bevy 9d12036, its phases and pipeline keys in crates/bevy_pbr/src/material.rs).
Backdrop
What the camera sees where no surface is (Godot’s background mode, Filament’s Skybox).
CompensationCurveError
Why a compensation curve was refused.
LightShape
Where a light shines.
Mobility
Whether an instance moves, chosen when it is added.
ProbeError
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.
SceneError
A Scene operation’s refusal.
SpecularProbeTexels
A probe’s stored radiance.
ViewError
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.