transmission
日本語 | English
Overview
transmission is a test application for transparent PBR surfaces and screen-space refraction. A sphere, a thick slab, and a torus keep independent material values so that normal gradients, silhouettes, Transmission, and IOR can be compared against brick joints and Oak grain while the ray enters and exits each object.
The complete 16-by-9 back wall uses the brick.running.red brick texture, while the floor uses the wood.oak.mixed-sawn Oak texture, mixing quarter-sawn and flat-sawn grain per board with the board length directed into the scene. Both are created through the core ProceduralMaterials.createPreset() API and attached to Shapes with applyTo(). UV repeat counts come from each preset's physical tile dimensions, so the brickwork and boards retain a consistent scale instead of stretching one copy across an entire surface.
The regular brick joints provide clear reference lines for the direction and magnitude of refractive displacement. The Oak floor exposes refraction and absorption on an oblique surface, while both Normal textures show how the opaque surroundings respond to PBR lighting. Texture-generation and shader-validation errors appear as startup errors with their cause, so you can inspect the failing input or shader.
The pass order is opaque G-buffer, deferred PBR lighting, an entry target containing an octahedral normal, Transmission, and linear view depth, a front-material attenuation target, an exit target containing depth, an octahedral normal, and IOR, air-to-medium refraction, front/back boundary marching with binary-search refinement, at most one total-internal-reflection bounce, medium-to-air refraction, opaque-depth background ray marching, an explicit clear-color, constant-color, or HDR-environment result for an unresolved background ray, Beer-Lambert absorption over the complete internal optical path, roughness Frost, transparent PBR forward composition, and Tone Mapping.
Open the CommandPalette with / or a double-click. Select Sphere, Slab, or Torus, then adjust that material's Transmission, IOR, Roughness, Surface Alpha, Absorption RGB, and Absorption Distance. Transmission controls the fraction of light assigned to refraction; the PBR surface shows the remaining contribution. Surface Alpha sets the surface contribution at Transmission 1.0, and lowering Transmission makes the surface contribution more opaque. Absorption RGB is the linear color remaining after the configured distance; a shorter distance produces stronger absorption. T toggles transmission, Space pauses motion, and R restores defaults.
The sample sets transmissionRayMissFallback: "clear", so unresolved rays use the application's clear color. Enable Ray Debug in the CommandPalette to see why a ray used a fallback: red marks an invalid same-pixel volume, orange an entry-refraction failure, magenta a missing boundary on the initial or reflected internal segment, yellow total internal reflection after one bounce, cyan a missing outside distance, and green a missing background hit.
The Help panel reports FPS averaged over 0.2 seconds. It also reports ComputeEffectPipeline time, G-buffer render time, combined GPU time, and JavaScript processing time as percentages of the average frame interval. The GPU total covers ComputeEffectPipeline and G-buffer rendering; the final copy to the presentation target is reported separately. GPU timestamps are shown when available, and otherwise the panel displays unavailable.
The core defaults are a maximum view-space distance of 42, a hit tolerance of 0.10, and 48 base steps. The internal and background ray traversals increase their step counts toward an interval of about 8 pixels along the ray's screen-space major axis, giving a default range of 48–96 steps. Five binary-search iterations narrow a detected crossing interval to 1/32. Hit tolerance sets the depth range used to identify a ray intersection.
To diagnose periodic stalls, the sample records only frames that take at least 20 ms, cross 16 fragmented transparent batches, increase the batch count by at least 16, cross 4 ms of queue CPU time, or change the global-sort state. Up to 64 records are retained in a ring buffer, Detailed objects and JSON are assembled only for frames that meet one of these conditions. Run getTransmissionAnomalyLog() in the browser console to retrieve the records in chronological order. Each record includes local and world angles in degrees (yaw, pitch, and roll) and positions for transparent Nodes, projected bounds, interfering pairs, triangle counts, per-instance batch runs, queue CPU timings, and the latest CPU and GPU pass timings. GPU timestamps are the latest asynchronously read-back values and may not belong to exactly the same frame as the stall.
Transparent-instance interference first uses the eight corners of each local AABB as an inexpensive coarse test. Only candidate instances receive a tight projected-bounds calculation from the vertices of their actual transparent triangles. Using the projected vertices of the actual surface filters out excess overlap from AABB corners outside a sphere or torus. If the short side of the overlap rectangle that remains between tight bounds is at most 8 pixels in the render target, the instances remain independent, preferring stable frame time over exact ordering in that narrow boundary strip. Diagnostics and anomaly records report the number of ignored pairs and the largest ignored overlap.
The entry target stores a complete view-space normal through octahedral encoding, Transmission, and entry depth. The exit target stores exit depth, an octahedral exit normal, and IOR. The compute shader reconstructs the entry position, applies Snell refraction from air to the medium, and marches both the front entry target and back exit target to find the first boundary. Five binary-search steps refine the crossing. If medium-to-air refraction produces total internal reflection, the shader reflects the ray inside the medium, searches both boundary targets again, and attempts medium-to-air refraction at the second boundary. It then marches the outgoing ray against opaque G-buffer depth. Beer-Lambert transmittance is attenuationColor ^ (opticalDistance / attenuationDistance), where opticalDistance includes both internal segments when reflection occurs. A valid hit stores the absorbed refraction directly and does not mix the unrefracted color from the same pixel. The forward PBR pass uses surfaceAlpha = 1 - effectiveTransmission * (1 - materialSurfaceAlpha) so that the non-transmitted fraction belongs to the material surface instead of creating a background ghost.
transmissionRayMissFallback controls rays whose background cannot be resolved from screen-space data. "auto" samples the HDR environment radiance in the outgoing direction when environment.radiance exists and otherwise uses the clear color passed to renderScene(). "environment" requires HDR radiance and reports a configuration error with the required input when radiance is unavailable. "clear" always uses the clear color. "constant" requires transmissionRayMissColor, specified in display sRGB like WebgApp.clearColor; TransparencyPass converts it once for the linear HDR pass. The selected mode is validated during initialization: "constant" requires a color, and other modes accept their own fallback settings.
pipeline.encode(gpu.commandEncoder, {
// ...other effect settings
transparency: {
transmissionEnabled: true,
transmissionRayMissFallback: "constant",
transmissionRayMissColor: [0.04, 0.06, 0.10, 1.0]
}
});
When no exit boundary is found, or a second boundary still causes total internal reflection, the outgoing direction is unresolved and the environment fallback uses clear color. The constant fallback uses its configured color. White attenuation at an infinite distance gives the no-absorption default. Setting Transmission to zero bypasses refraction and leaves the regular alpha-surface behavior. The renderer uses a screen-space, single-layer approximation based on the boundaries recorded in its targets. Exact volume tracking, multiple glass layers, and color dispersion call for additional geometry and optical models. This sample sets transmission, IOR, and volume absorption through webg material parameters. glTF KHR_materials_transmission, KHR_materials_ior, and KHR_materials_volume import, and physically based transmission with alpha set to 1.0, are separate integration paths.
Ray Debug is a classification view separate from the fallback selected for normal rendering. Its diagnostic color takes precedence over the fallback while debugging is enabled. Front/back boundary searches and one internal reflection run whether the view is enabled or disabled. Magenta identifies a missing boundary on either the initial or reflected internal segment, while yellow identifies a ray that is still totally internally reflected at the second boundary and would require another bounce.