Builtin Library
- ..
- README.md4.3 KB
- module.wgsl9.7 KB
README.md
parallax
Parallax occlusion for any lit surface shader: relief from a height map, drawn on a flat face. The view ray is marched into the height field in tangent space and every map the surface samples is read where the ray met the relief, so raised parts stand in front of low ones as the view moves. A shorter march toward the sun gives the relief its own shadow.
Which way the height map runs
One convention for the module and both built-in shaders that carry it: the
map's R channel is height, white highest (raised parts white, gaps and
grooves black). A map authored the other way, depth, white deepest, is read
by switching height_map_is_depth on, with no need to invert the image:
| Where | The switch | Default |
|---|---|---|
| this module | ZeroParallax.height_map_is_depth | false (height, white highest) |
pbr material | height_map_is_depth property | false (height, white highest) |
pbr_parallax_occlusion material | height_map_is_depth property | true (depth, white deepest: the maps made for it, parallax_bricks among them, are depth maps) |
A relief that reads inside out (stones sunk into the mortar, carving standing
proud) is a map read the wrong way: flip height_map_is_depth.
#include "@builtin::shaderModules.parallax"
fn surface(input: FragmentData) -> PbrSurface {
let relief = zero_parallax(0.06, 32.0); // depth in UV units, most steps
let hit = zero_parallax_march(input, height_texture, height_texture_sampler, input.uv, relief);
var s = zero_pbr_default_surface(input);
s.albedo = textureSampleGrad(base_color_texture, base_color_texture_sampler, hit.uv, hit.ddx, hit.ddy).rgb;
// ... every other map at hit.uv the same way ...
// The relief's self-shadow, folded into the sun the shading lights with.
s.sun_visibility = zero_parallax_sun_visibility(input, s, height_texture, height_texture_sampler, hit, relief);
return s;
}
A fragment() shader that lights itself does the same and returns
zero_pbr_shade(input, s).
ZeroParallax
| Field | Meaning |
|---|---|
depth | How deep the relief reaches, in UV units: the furthest the march moves a UV. 0 draws the flat face. |
max_steps | The view march's steps at a grazing view; straight down takes 40% of them, the self-shadow half. |
fade_start, fade_end | World distance from the camera over which the relief flattens; past fade_end no march runs. |
height_map_is_depth | false (the default): R is height, white highest. true: R is depth below the top, white deepest. |
zero_parallax(depth, max_steps) fills the rest: fading over 20 to 40 world
units, reading a height map.
What it costs and where
- The view march runs only where the relief is nearer than
fade_end, and its step count falls as the view turns toward the face. - The relief flattens toward a grazing view, so the silhouette of a curved surface (a trunk, a column) keeps its shape.
- The self-shadow march runs only on a fragment the sun lights:
zero_pbr_sun_visibilitystates the sun's share first, and a fragment the sun does not reach, that faces away from it, or that its shadow maps hold in full shadow takes no self-shadow sample. - Maps are read with
textureSampleGradthroughhit.ddx/hit.ddy, the derivatives of the face's own UV with the frame's texture bias, so the jumps the march makes at the relief's edges choose no coarser mip and the picture holds still under temporal anti-aliasing.
What the relief is
The fragment stage draws it: the depth the surface writes and the shadow it casts are those of the flat face, and the relief offsets the UV inside the face rather than past its edges. A UV that tiles keeps every tile: the march reads the height map with the sampler's own wrap.
zero_parallax_march takes the derivatives of the UV it is given, so it is
called from uniform control flow, where an implicit-derivative textureSample
may be.
The built-in pbr shader carries it as a feature (parallax_depth_scale > 0
with height_texture), and pbr_parallax_occlusion is built on it; each
states the map's direction with its height_map_is_depth property. The
rendering guide's relief section (guides { path = "topics/rendering-geometry" })
places it among the engine's other geometry techniques.