Log inGet started
World

Builtin Library

Branchmain
Branchesmainpublish
Commit15ce14a4c1

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:

WhereThe switchDefault
this moduleZeroParallax.height_map_is_depthfalse (height, white highest)
pbr materialheight_map_is_depth propertyfalse (height, white highest)
pbr_parallax_occlusion materialheight_map_is_depth propertytrue (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

FieldMeaning
depthHow deep the relief reaches, in UV units: the furthest the march moves a UV. 0 draws the flat face.
max_stepsThe view march's steps at a grazing view; straight down takes 40% of them, the self-shadow half.
fade_start, fade_endWorld distance from the camera over which the relief flattens; past fade_end no march runs.
height_map_is_depthfalse (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_visibility states 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 textureSampleGrad through hit.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.