# SGL3D features
What SGL3D renders, the API to reach for, and where the detail is. The
settings a game chooses are listed in [settings](settings.md).
## Platforms
Native (Metal, Vulkan, DX12) and the browser (WASM + WebGPU) run the same
features, with two exceptions: FSR2 needs native-only device features, so the
browser runs TAA in its place and `Renderer::fsr2_error` says why, and
`Renderer::capture_specular_probe`, an authoring tool that blocks for its
readback, runs natively only. Hardware ray tracing is native too, where the
device has ray queries; elsewhere rays trace the software BVHs. WebGL2 is not a target:
SGL3D needs compute.
[Browser](../README.md#browser-wasm--webgpu).
## Content
- **glTF 2.0 meshes**: triangles with metallic/roughness, normal and
bump maps, clearcoat, emission, unlit and `KHR_materials_anisotropy`.
`asset::load` (a file), `load_slice` (bytes; the browser's way),
`load_with_options` and `load_slice_with_options` (`LoadOptions`: an
emissive strength cap, images the game supplies, which are never decoded,
and a selection of mesh nodes for named rigid parts), or a
procedural `asset::Asset` (`asset::Material::default()` is glTF's default
material). Unsupported features return errors rather than
partial models. [Limits](../README.md#asset-and-environment-limits).
- **Compressed material textures**: a material image is decoded RGBA8, whose
mips SGL3D filters when it is added, or a BC7 mip chain uploaded as stored
(`asset::Image::Compressed`, read from KTX2 with
`CompressedImage::from_ktx2`; needs `TEXTURE_COMPRESSION_BC`). Games compress
in their export step and supply the chains while a glTF loads
(`LoadOptions::images`). Rays decode a compressed image's level 0 from its
stored blocks.
[Compressed material images](../README.md#compressed-material-images).
- **Skinned meshes and morph targets**: the loader imports skins (four
influences per vertex), morph targets (up to 256 a mesh), the node
hierarchy and animation clips as plain data (`deformation`, `Asset::rig`);
the game samples and blends clips and gives each instance its joint
matrices and morph weights every frame
(`Scene::set_instance_deformation`, `Rig::joint_matrices`). SGL3D morphs
and skins each changed instance once per frame in compute, and every pass
draws the result: motion from the last submitted frame's pose,
culling by skinned bounds, shadows in the cascades and the local-light
atlas. A deforming instance moves and keeps its model; rays see it only
with hardware ray tracing.
Each `set_instance_deformation` call deforms it again and redraws its
shadow faces, so skip it for unchanged poses. Rigid meshes stay baked at
their nodes' rest transforms; clips move them only as named rigid parts.
[Skinned meshes and morph targets](../README.md#skinned-meshes-and-morph-targets).
- **Scene**: starts empty; the game adds, replaces and removes materials,
models, instances, lights, decals and environments between frames (`add_…`,
`set_…`, `remove_…`), each named by the identity its addition returned.
A model arrives as a `PreparedModel`, built from its meshes with
`PreparedModel::new` on any thread, so geometry made at run time is
prepared on the game's workers and the scene only places and copies it.
Each vertex packs into 32 bytes: exact positions, normals and tangents
within 0.01°, 16-bit UVs across each mesh's UV rectangle, vertex colours
as 8-bit sRGB clamped to 0..1
([limits](../README.md#asset-and-environment-limits)).
Buffers grow as content is added; content in use cannot be removed.
[Lifecycle](../README.md#retained-scene-and-frame-lifecycle).
- **Instances**: model placements (`InstanceState`; `InstanceState::new(model)`
is at the origin and shown in every view), static or moving. Static
instances are what bakes and probe captures contain and write no motion;
moving ones are posed each frame with `Scene::set_instance` (and
`set_instance_deformation` when their model deforms) and write motion from
the last submitted frame.
- **Render origin**: positions are `f32` in the scene's render frame, which
`Scene::move_origin` moves by an exact delta, so a large or streamed world
renders near the origin. Motion, shadow caches and histories carry across
the move; nothing redraws and no history restarts.
[Lifecycle](../README.md#retained-scene-and-frame-lifecycle).
- **Alpha modes** (`AlphaMode`, glTF `alphaMode`): masked materials are cut
out below their cutoff in every view, shadow and ray; blended ones are lit,
fogged and drawn back to front over the frame, writing no depth or motion
unless marked to receive screen-space reflections, and casting no shadow.
[Alpha-masked and blended
materials](../README.md#alpha-masked-and-blended-materials).
- **Blended receivers** (`AlphaMode::Blend { receives_screen_space_reflections:
true }`): water or glass, with the normals the game animates, that
receives the frame's screen-space reflections where it is the nearest
receiver, and that TAA, FSR2 and motion blur reproject by its own motion.
No refraction; one reflecting layer per pixel. Animate water with scrolling
normal layers; a mesh replaced every frame with `Scene::set_model` is
prepared again, ray BVH included, every frame. [Blended receivers](../README.md#blended-receivers).
- **Scrolling normal layers** (`asset::Material::normal_layers`,
`SurfaceMaterial::normal_layers`, `NormalLayer`): a material's repeating
normal map drawn as two layers, each with its velocity, scale and
strength, moving with `FrameInput::elapsed_seconds` (an `f64`) in every
view and ray: water's waves with no per-frame upload, on static instances
too. Precise however long a session runs. FSR2 is told where they move,
opaque surfaces included, as AMD asks for animated textures.
[Scrolling normal layers](../README.md#scrolling-normal-layers).
- **Decals**: boxes that project the game's images onto the lit surfaces
inside them, changing base colour and, with their maps, normal, roughness
and metallic before lighting, so reflections and SSR see them
(`Scene::add_decal_image`, `add_decal`, `Decal`). Godot's clustered decals:
clustered with the lights, sampled from one atlas SGL3D packs; probe
captures and world-space ray hits take them too. Unlit materials take
none. Keep boxes shallow: everything inside one takes the decal.
`Decal::new(image)` has Godot's decal defaults. The lit pipelines apply
decals only while the scene holds one, so the first decal added compiles
them anew.
[Decals](../README.md#decals).
- **Material edits** at runtime: `Scene::set_material` (`SurfaceMaterial`,
whose default is glTF's default material).
- **Visibility groups**: `FrameInput::visibility_mask` switches material
groups on and off per frame, including in probe captures.
- **Culling and LOD**: automatic. The GPU builds the camera's opaque and
masked draws and each directional cascade's every frame: frustum culling
of each instance, then of its mesh's 128-triangle sections, one indirect
draw per material, pose kind and positions slab whatever the instance
count, on native and in the browser alike; a cascade draws an opaque
material's sections whose triangles pair as quads a second, indexed
way. A mesh holds at most 65,536 sections.
`Scene::set_mesh_lods` registers up to 8 authored coarser chunks a mesh
([spatial mesh LOD](../README.md#spatial-mesh-lod)). Coplanar surfaces of
different draws have no defined winner at equal depth: give an overlay a
depth offset or make it a decal. Two-phase occlusion culling of the
camera's opaque and masked geometry is opt-in
(`Settings::occlusion_culling`, [settings](settings.md)).
- **Instanced draws**: automatic. In the CPU-built lists (blended surfaces,
local-light shadows, probe captures), instances that draw the same mesh
with the same material, face culling and mobility share one draw, each
keeping its own pose, motion and identity; deforming instances draw alone.
[Visible work](../README.md#visible-work-and-pass-selection).
## Lighting and shadows
- **Directional lights**: up to two (`FrameInput::directional_lights`,
`DirectionalLight`). The first that is on and has a `shadow`
(`DirectionalShadow`: distance and cascade count;
`DirectionalShadow::DEFAULT` for a `const`) casts cascaded shadows that
SGL3D splits and fits from the camera: up to four 2048-texel cascades
(1024 at the Low `Settings::shadow_quality`, which also halves the
local-light atlas and takes one hard filter tap), stable
while the camera moves, blended across their
overlaps, filtered and biased as Bevy does, and cast by everything between
the light and the view. A single-sided material casts from its front faces, a
double-sided one from both. `fog_energy` scales its light in the
volumetric fog and `shadow_opacity` how dark its shadow is. A hemisphere
fill
(`FrameInput::hemisphere_light`, `HemisphereLight`).
[Frame lights and look](../README.md#frame-lights-and-look).
- **Point, spot and rectangle lights**: scene content (`Scene::add_light`,
`Light`, `LightShape`), clustered on the CPU each frame so each pixel
pays only for the lights that reach it, up to 8,192 lights and decals a
cluster (a probe capture's cluster is the whole scene, a ray hit's the
view, a dynamic GI probe ray's the volume). A `baked` light lights only
receivers without baked lighting (moving instances, and static ones with
no lightmap or assigned atlas chart), leaving the rest to the game's bake,
and casts ray-traced shadow rays only at those receivers; `specular` scales its
highlights (0 for a fixture already reflected as an emitter), and
`fog_energy` its light in the volumetric fog (at most 0.001 leaves it out
of the fog, which then skips its attenuation and shadow lookup), and
`shadow_opacity` how dark its shadow is on surfaces and in the fog
(Godot's; 1 by default). `Light::default()` and
`DirectionalLight::default()` are Godot's light defaults, with Wicked
Engine's 2.5 cm light radius and the sun's angular diameter, so a game
sets only what differs (`..Default::default()`).
`LightShape::Rect` is a one-sided panel or strip whose face is integrated
by linearly transformed cosines: soft light and stretched highlights
nearby, a spot of the same intensity far away. It costs more per pixel
than a spot (one integral for diffuse, one more per specular lobe); the
lit pipelines shade rectangles only while the scene holds one.
[Point, spot and rectangle lights](../README.md#point-spot-and-rectangle-lights).
- **Local-light shadows**: lights with `casts_shadow` share one shadow atlas,
sized and chosen by screen coverage; lights beyond its room are lit without
a shadow (`Renderer::local_shadow_stats` counts them). Static casters are
cached per face, so a frame redraws a light's shadow only where something
moved in its range. [Local-light shadows](../README.md#local-light-shadows).
- **Image-based lighting**: environment panoramas with prefiltered atlases
(`environment::EnvironmentMap`, `Scene::add_environment`);
`FrameInput::environment` picks the frame's, `diffuse_environment` and
`reflection_environment` (`EnvironmentLight`, unturned at intensity 1 by
default) turn and scale its diffuse and specular light,
and `backdrop` (`Backdrop`) shows its panorama or a colour behind
everything.
- **Baked diffuse**, authored and baked by the game: a lightmap for chosen
materials of static instances (`Scene::set_lightmap`) and a static
irradiance atlas, BC6H/BC7-compressed for shipping
(`set_compressed_static_irradiance_atlas`), both textures with optional
directionality that the hardware filters, and ambient cubes for moving
instances (`set_instance_baked_irradiance`). A fixture in the bake can also
be a baked scene light, which lights moving instances live; its light then
stays out of their ambient cubes.
- **Irradiance volume**: diffuse light the game computes over a lattice of
cells (`Scene::set_irradiance_volume`, `IrradianceVolume`; a port of
Bevy's irradiance volume), such as a voxel world's propagated sky and
block light at a metre, each cell an ambient cube of its own light and the
sky's visibility from each face (`IrradianceCell`), written by region from a box prepared on any thread
(`PreparedIrradianceRegion`, `Scene::write_irradiance_cells`) with no
geometry or bake replaced, and scrolled with the camera by installing it
at a new origin. Static and moving surfaces without a chart take it in
place of the dynamic GI volume, ambient cubes and the frame's ambient,
which its sky visibility lets through; the visibility darkens the sky's
share of their environment specular too.
[Irradiance volume](../README.md#irradiance-volume).
- **Dynamic diffuse GI**: a volume of probes the game places
(`Scene::set_dynamic_gi_volume`, `DynamicGiVolume`), kept up by rays
through the scene (Wicked Engine's DDGI), near probes every frame and far
ones in turn, within a per-frame budget of rays: coloured bounce light
from the frame's and the scene's lights, emitters and the sky, shadowed
by rays where the lights cast shadows, on static surfaces without a bake
and on moving instances in place of their ambient cubes and the frame's
ambient, fading out over one spacing past the volume. A new placement
starts its probes over a few frames, nearest the camera first; one moved
by whole spacings scrolls, keeping the probes that stay. Probes inside
geometry or behind walls light nothing and cost little; those with no
surface near them light moving instances alone. A converged volume pauses
until something it sees changes. A glowing fixture that a scene light
stands for keeps its own light out of the probes
(`asset::Material::emits_into_gi`, `SurfaceMaterial::emits_into_gi`
false), so it lights surfaces once, through the light; it still blocks
the probes' rays and shows in reflections.
`Settings::dynamic_gi` sets its rays and budget.
[Dynamic GI](../README.md#dynamic-diffuse-gi).
- **Baked specular probes**: parallax-corrected reflection cubes with blended
influence boxes (`Scene::set_baked_specular_probes`), captured offline with
`Renderer::capture_specular_probe`.
[Probes](../README.md#baked-specular-probes).
## Reflections
Environment and probe specular always apply. On top of them:
- **Screen-space reflections** with two methods, Crystal and Velvet, which
combine passes from DiligentFX, AMD FidelityFX, Godot, Wicked Engine and
Bevy, over opaque surfaces and blended receivers. Crystal runs in SGL's
`sgl-post-fx` effects library.
[Reflections](../README.md#reflections) credits each source.
- **World-space reflections**: rays up to 1000 m from the reflecting
surface where screen-space reflections miss, through a software BVH or,
with hardware ray tracing, the scene's acceleration structures. They
reach moving objects (`Moving`), or everything (`All`), which shows
static surfaces as they stand rather than as their probes recorded them
and is meant for hardware ray tracing.
- **Hardware ray tracing** (opt-in): on a device with ray queries and with
`Settings::hardware_ray_tracing` on, world-space reflections' rays, the
dynamic GI volume's and ray-traced shadows' trace the scene's
acceleration structures, built
on the frames that trace rays, masked models among them on Metal; masked
models on Vulkan and DX12 and what the device cannot hold stay on the
software BVHs. Skinned and morphed instances are seen by
those rays only on this path, and not at all where the device cannot
hold them. `Renderer::ray_tracing_in_effect` and
`ray_tracing_error` report it.
[Hardware ray tracing](../README.md#hardware-ray-tracing).
- **Ray-traced shadows** (opt-in, `Settings::ray_traced_shadows`, which
needs hardware ray tracing): the camera's opaque surfaces take the
shadows of the directional light and of up to fifteen casting local
lights from rays instead of the maps, soft by the light's size (a point
or spot light's `radius`, the directional light's `angular_diameter`),
denoised by AMD's FidelityFX shadow denoiser for the first four (the
directional light's alone at `Settings::ray_traced_shadow_quality` Low)
and temporally blended for the rest, reaching beyond the directional
shadow's distance; the fog, blended surfaces and reflections keep the
maps, and without hardware ray tracing the maps shadow everything.
`Renderer::ray_traced_shadows_in_effect` reports it.
[Hardware ray tracing](../README.md#hardware-ray-tracing).
## Image quality and post-processing
- **Ambient occlusion**: XeGTAO after opaque shading, which occludes ambient
diffuse and environment and probe reflections; turning it on draws no
geometry again. [Ambient occlusion](../README.md#ambient-occlusion).
- **Antialiasing**: SGL's DiligentFX-derived TAA in `sgl-post-fx`, SMAA at
SMAA 2.8's Low, Medium, High or Ultra preset, or AMD FSR2, which also
upscales, with RCAS sharpening the game can turn off or set.
[Temporal anti-aliasing](../README.md#temporal-anti-aliasing).
- **Anisotropic texture filtering** of materials, Off to 16×.
- **Scene resolution** scaling below the output size; the game's UI stays at
full size.
- **Exposure** (`FrameInput::exposure`): fixed stops, or automatic exposure
from a log-luminance histogram with a metering mask, a compensation curve,
separate brightening and darkening speeds and limits. FSR2 and the tone map
take the same exposure.
[Exposure, bloom and colour grading](../README.md#exposure-bloom-and-colour-grading).
- **Bloom** (`FrameInput::bloom`): energy-conserving, through a mip chain;
bright light scatters, with no threshold.
- **Motion blur** (`Settings::motion_blur`, `FrameInput::motion_blur`): the
camera's and moving instances' motion, over a shutter angle, after
antialiasing. Wicked Engine's tile-max reconstruction filter: moving edges
blur over what is behind them, and slower surfaces in front, such as what
the camera follows, stay sharp. [Motion blur](../README.md#motion-blur).
- **Colour grading** (`FrameInput::color_grading`): white balance, hue, and
saturation, contrast, gamma, gain and lift for shadows, midtones and
highlights, then AgX tone mapping with Filament's look (`AgxLook`: none,
punchy or golden) and a post-saturation. The output is always dithered
against 8-bit banding.
- **Volumetric fog** (`FrameInput::fog`, `Fog`): Godot's froxel fog, while
`FrameInput::atmosphere` is on (off by default, as Godot's fog). The
frame's medium (density with height falloff, albedo, anisotropy, the
share of ambient light it scatters, none by default as Godot's) and
denser boxes of it (`Scene::update_fog_volumes`, `FogVolume`, by default
Godot's; the first 1,024 that reach the frame), lit by the
directional lights through their cascades, the clustered point, spot and
rectangle lights through their shadows, each scaled by its `fog_energy`,
and that share of the ambient light, so light shafts form where openings
let a shadowed light through. Opaque surfaces, the sky, blended surfaces,
glow and mist all fog from one volume, the sky by `Fog::sky_affect`
(all of it by default, as Godot's). `Fog::length` sets its reach,
`Settings::fog_quality` its resolution and `Settings::fog_filter` its
blur; SGL3D spaces its slices and weights its history.
[Volumetric fog](../README.md#volumetric-fog).
- **Mist**: positioned billboards (`Scene::update_mist`, their look and
drift `FrameInput::mist`, which `Mist::default()` hides), while
`FrameInput::atmosphere` is on.
- **Additive effects**: game-generated glow triangles with soft depth fades
(`Scene::update_effects`, `effects::Glow`): uniform, tapered by a
`GlowProfile`, or one-pixel lines (`GlowKind`).
[Soft additive effects](../README.md#soft-additive-effects).
- **Heat shimmer**: screen distortion over game-supplied triangles
(`Scene::update_heat_distortion`).
[Heat shimmer](../README.md#bounded-heat-shimmer).
## Tools
- **GPU timing** per pass: `timing::GpuTiming`.
[Pass timing](../README.md#gpu-pass-timing).
- **Geometry counts**: `Renderer::geometry_stats`, the camera's draws and
triangles in the most recent completed frame, read back without blocking
(`None` until one completes), and, with diagnostics,
`geometry_stats_for_model`.
- **CPU rays** against scene triangles: `geometry::triangles` and
`obstructed_distance`.
- **Diagnostics** feature: `Settings::diagnostics` turns layers off (culling
among them), runs the frame probe and captures the tone-mapped target;
`Renderer::diagnostic_target`, `take_frame_probe_reports`,
`diagnostic_draws`, `diagnostic_view_times` and
`take_dynamic_gi_reports` (`Diagnostics::dynamic_gi`: the dynamic GI
volume's probes, rays, BVH visits and budget stride, by frame) return what
they observed. Configuration only:
no environment variables or files. Shipping builds leave it off.
## Not provided
Animation playback (sampling and blending clips is the game's).
DLSS/MetalFX are [planned](../../../specs/sgl3d.md#planned). The
directional cascades cull by frustum alone. Compressed images
are BC7 only: transcoding Basis Universal (UASTC) for a device without BC is
not provided.
Also not provided: occlusion textures, tangent generation, runtime probe
capture, order-independent transparency and refraction.