pbr.shader
- .metadata17 B
- README.md14.7 KB
- preview.png28.6 KB
- properties.yaml11.5 KB
- shader.wgsl10.2 KB
This package holds more than this page lists. See all of its files in its world.
README.md
pbr
The engine's standard physically-based material — the full glTF metallic-roughness
workflow lit by the shared @builtin::shaderModules.pbr_shading model. This is the default surface shader a
model uses when its material doesn't specify another, and it is also registered
under the legacy alias standard (the name many materials reference).
It is a surface() shader: it fills a PbrSurface and the engine generates every
pipeline entry point and lights it. Every parameter defaults to a neutral value, so
a material that sets nothing renders as a clean dielectric; the advanced lobes only
cost anything when a material opts into them.
Properties
| Property | Type | Default | Meaning |
|---|---|---|---|
base_color | color | [1,1,1,1] | Albedo tint, multiplied by base_color_texture and vertex colour. |
emissive | color | [0,0,0,1] | Emissive tint, multiplied by emissive_texture and emissive_intensity. |
emissive_intensity | float | 1.0 | HDR multiplier on the emissive output. |
roughness | range | 0.5 | Perceptual roughness, multiplied by the green channel of roughness_metallic_texture. |
metallic | range | 0.0 | Metalness, multiplied by the blue channel of roughness_metallic_texture. |
reflectance | range | 0.5 | Dielectric reflectance knob (neutral 0.5 → 4% F0). |
ior | float | 1.5 | Index of refraction → dielectric F0 and the refraction direction. |
normal_scale | float | 1.0 | Strength of the tangent-space normal_texture. |
occlusion_strength | range | 1.0 | Blend of the occlusion_texture (R) into the ambient term. |
clearcoat | range | 0.0 | Strength of a second dielectric clearcoat specular lobe. |
clearcoat_roughness | range | 0.0 | Roughness of the clearcoat lobe. |
anisotropy | float | 0.0 | Anisotropic highlight stretch along the tangent ([-1,1]). |
sheen_color | color | [0,0,0,1] | Tint of the sheen lobe — the retroreflective rim of velvet, satin and brushed fabric. Black leaves the base untouched. |
sheen_roughness | range | 0.3 | Width of the sheen lobe. |
iridescence | range | 0.0 | Blend toward the thin-film response, the hue that shifts with view angle. |
iridescence_thickness | float | 400.0 | Film thickness in nanometres — which wavelengths cancel and which reinforce. |
iridescence_ior | float | 1.3 | Index of refraction of the film. |
subsurface_color | color | [0,0,0,1] | Tint of the light that entered the surface, scattered beneath it and left again. Black leaves the base untouched. |
subsurface_radius | float | 0.5 | How far the diffuse falloff wraps past the terminator, taken per channel against subsurface_color. |
fibre_color | color | [0,0,0,1] | Tint of the second of the two highlights a hair or fur strand gives. Black leaves the base untouched. |
fibre_specular | range | 0.35 | Strength of the first strand highlight, in the light's own colour. |
fibre_shift | float | 0.06 | How far apart the two strand highlights sit along the fibre. |
fibre_roughness | range | 0.1 | Width of the first strand highlight. |
transmission | range | 0.0 | Specular transmission — refracts the environment through the surface. |
thickness | float | 0.0 | Volume thickness for Beer–Lambert transmission absorption. |
attenuation_color | color | [1,1,1,1] | Transmission absorption tint. |
attenuation_distance | float | large | Beer–Lambert absorption distance. |
uv_scale | float2 | [1,1] | UV tiling applied before every texture sample. |
uv_offset | float2 | [0,0] | UV offset applied before every texture sample. |
alpha_cutoff | range | 0.0 | Mask threshold — fragments with alpha < this are discarded (0 = no cutoff). |
double_sided | bool | false | Flip the shading normal on back faces. |
receives_fog | bool | true | Whether the screen-space fog passes (height fog, aerial perspective) reach this surface. false leaves an opaque deferred draw at the colour it shaded to, however deep in the medium it stands — see below. |
instance_color_lane | float | -1 | Which of the instance's four shader-data lanes colours it (rgb colour, a coverage). -1 reads none. See below. |
instance_emission | float | 0 | How brightly the lane colour glows where it covers. |
parallax_depth_scale | float | 0.0 | Depth of the relief height_texture describes, in UV units: the furthest the parallax march moves a UV. 0 draws the flat face. See below. |
max_parallax_layer_count | float | 32 | The parallax march's steps at a grazing view; straight down takes 40% of them, the self-shadow half. |
parallax_fade_start | float | 20 | World distance from the camera at which the relief starts to flatten. |
parallax_fade_end | float | 40 | World distance past which the relief is flat and no march runs. |
height_map_is_depth | bool | false | Which way height_texture runs: false reads R as height, white highest; true reads it as depth, white deepest. |
Emissive authoring
The glow output is emissive × emissive_intensity (× the emissive_texture). The glow
colour is emissive, a vec; the intensity over it is emissive_intensity, a
scalar. So { emissive = {0.1, 0.9, 1, 1}, emissive_intensity = 5 } is a cyan glow at 5×,
and it is these two names that getProperties() lists and setProperty writes.
A spelling another engine's convention uses for the same role — emissive_color,
emission, emissive_tint — is resolved onto emissive when the material is authored,
so content carried in from glTF, Unity or Godot reaches the property under the name this
shader declares. Where two such spellings meet on one of the two names, the shape of each
value says which of them it is: a vec is the colour and a number is the intensity, so
{ emissive_color = {0.2, 0.8, 1, 1}, emissive = 5 } is the same cyan glow at 5x. Two
values of one shape are one property's, and the one written under the name the shader
declares applies while the other is named in a warning.
A bare positive scalar emissive with no colour beside it is the "turn emission on"
shorthand and means a white glow at that intensity, so emissive = 20 on a white material
lights up.
Parallax occlusion
A material that binds a height_texture (the relief's height map, R channel)
and sets parallax_depth_scale above 0 draws the relief that height map
describes on the flat face. The map is read as height, white highest (the
stones white, the mortar black); a map authored as depth, white deepest
is read by setting height_map_is_depth = true, with no need to invert the
image. A relief that reads inside out (cobbles sunk below their gaps, carving
standing proud) is a map read the wrong way round: flip height_map_is_depth.
The module and pbr_parallax_occlusion state the same switch under the same
name. The view
is marched into it, every map is read where the view met the relief (through
the derivatives of the face's own UV, so the relief's edges pick no coarser
mip and the picture holds still under temporal anti-aliasing), and the relief
takes its own share of the sun, marched only on the fragments the sun lights.
The relief flattens with distance between parallax_fade_start and
parallax_fade_end, and toward a grazing view, so the silhouette of a curved
mesh keeps its shape. A UV that tiles (uv_scale) keeps every tile. The depth
the surface writes and the shadow it casts are those of the flat face.
The code is the PBR_PARALLAX feature, in a material's program only where
parallax_depth_scale stands above 0. A shader of your own gets the same
relief from @builtin::shaderModules.parallax, which this feature calls.
guides { path = "topics/rendering-geometry" } has the rendering guide's
section on relief.
asset.create("material", "cobbles", {
shader = "@builtin::shaders.pbr",
base_color_texture = { __ref = colour.guid, type = "texture" },
height_texture = { __ref = height.guid, type = "texture" }, -- white highest
parallax_depth_scale = 0.05,
uv_scale = { 6, 6 },
})
The lobes over the base layer
Beyond metallic-roughness, the shading model carries six layers this material declares. Each is gated on its own neutral value, so a material that sets none of them shades as a plain dielectric and each one costs only where it is asked for.
| Layer | Turned on by | What it looks like |
|---|---|---|
| Clearcoat | clearcoat > 0 | A second dielectric specular lobe on top — car paint, lacquer, a varnished surface. |
| Anisotropy | anisotropy ~= 0 | The highlight stretches along the tangent — brushed metal, a vinyl record. |
| Sheen | sheen_color above black | A retroreflective rim that brightens toward grazing angles — velvet, satin, dusty cloth. |
| Iridescence | iridescence > 0 | The specular hue shifts with view angle — an oil slick, a soap film, anodised metal, a beetle shell. Thickness picks the colours. |
| Subsurface | subsurface_color above black | Light wraps past the terminator and glows through thin geometry lit from behind — skin, wax, marble, a leaf. thickness gates how much reaches the far side. |
| Fibre | fibre_color above black | The two offset highlights a strand gives instead of the one a surface gives — hair, fur. Taken around the world tangent as the fibre axis. |
All six are evaluated inside the engine's own light loop, once for every light that reaches the surface, so each one is shadowed, attenuated and cone-masked with the base layer it sits over.
Each layer, and specular transmission beside them, is a shader feature its
gating property switches on (features: in properties.yaml: PBR_CLEARCOAT,
PBR_ANISOTROPY, PBR_SHEEN, PBR_IRIDESCENCE, PBR_SUBSURFACE, PBR_FIBRE,
PBR_TRANSMISSION; the per-instance colour below is PBR_INSTANCE_COLOR). A material that sets the property away from its neutral
value draws a program holding that layer; one that leaves every layer at rest
draws a program holding none of them, so the default material pays only for the
metallic-roughness model it shades as. Setting a property with
renderer.material.setProperty moves the material between the two programs, and
renderer.shaderVariants() lists the ones a scene has asked for.
An oil-slicked wet surface is iridescence = 1, an iridescence_thickness
around 300-500 nm and a low roughness over a dark base_color. Skin is a warm
subsurface_color with a subsurface_radius near 0.5. Velvet is a sheen_color
at the fabric's own hue over a dark base.
Standing outside the fog
receives_fog = 0 declares that the screen-space fog passes — heightFog and
aerialPerspective in @builtin::systems.atmosphere — leave this surface at the
colour it shaded to.
The declaration travels to those passes as a per-pixel surface flag written into
the alpha of the G-buffer normal (@builtin::shaderModules.surface_flags). Only
the deferred G-buffer fragment entry writes that channel, so the declaration
reaches the fog from an opaque draw on the deferred path. A draw the
renderer sends through the forward fragment entry — every draw on the forward
path, and the transparent phase on either path — writes no G-buffer channel to
carry it, and its pixels take the fog like any other.
Per-instance colour
instance_color_lane names one of the four shader-data lanes every drawn
instance carries (renderer.instanceData.set for an entity, the
instanceDataBuffer of renderer.mesh.drawInstanced for a population). The
lane's rgb is this instance's colour and its a is how much of it covers the
material's own base colour and emission, 0 none through 1 all, so one material
draws every member of a structure, a crowd or a population in a colour of its
own: a stress map, a heat map, damage tints, team colours, a selection
highlight. A lane never written reads zero and leaves the material's own look.
local mat = renderer.material.create({ shader = "@builtin::shaders.pbr",
properties = { instance_color_lane = 2, roughness = 0.6 } }, "beams")
beam.component.add("Model", { model = "cube", material = mat }) -- the handle
renderer.instanceData.set(beam, 2, 1, 0.2, 0, 1) -- this beam orange-red
The colour replaces the base colour before lighting, so the surface still shades
and the albedo capture pass reads the lane colour. instance_emission adds
the lane colour as emission where it covers. Lanes 0 and 1 carry a baked
lightmap's rect and layer, so a lit material takes lane 2 or 3. The read is the
PBR_INSTANCE_COLOR feature, so a material that leaves instance_color_lane at
-1 draws a program without it. @builtin::materials.instance_color is this
material ready made, reading lane 2.
A write is local to the engine that makes it and replicates nothing, which is
what makes it cheap enough to recolour hundreds of members every frame;
Model.tint is the synced tint every participant sees.
Textures (glTF metallic-roughness set)
| Slot | Default | Channels |
|---|---|---|
base_color_texture | white | RGBA albedo (sRGB). |
roughness_metallic_texture | white | G = roughness, B = metallic (glTF packing). |
emissive_texture | white | RGB emissive (sRGB). |
normal_texture | flat-normal | Tangent-space normal map. |
occlusion_texture | white | R = ambient occlusion. |
height_texture | white | R = height of the relief, white highest (white deepest under height_map_is_depth). Read by parallax occlusion (PBR_PARALLAX, where parallax_depth_scale > 0). |
A program samples the maps its material binds and no other. Each slot is a
shader feature switched on by the material binding a texture there
(PBR_BASE_COLOR_MAP, PBR_ROUGHNESS_METALLIC_MAP, PBR_NORMAL_MAP,
PBR_EMISSIVE_MAP, PBR_OCCLUSION_MAP): a slot left unbound, or bound to its own
default (default:white, default:normal), reads as the value that default
stands for, times the slot's factor, with no texture sample, and an unbound
normal map leaves the geometric normal exactly as it is. A solid-colour material
takes no texture sample at all. A material binding one image as both
roughness_metallic_texture and occlusion_texture (glTF's packed
occlusion-roughness-metallic image) draws PBR_OCCLUSION_IN_ROUGHNESS_METALLIC,
which reads occlusion from the R of the metallic-roughness texel and samples the
image once.
Because the engine holds the full PbrSurface, the capture tool's debug passes
(albedo / roughness / metallic / AO / emissive / world-normal / shadow / depth /
motion) all read real material data.