raea/pbr

<StandardMaterial> is Bevy's physically based material, with its fields named as Bevy names them (base_color, perceptual_roughness, metallic, emissive and the rest). An ExtendedMaterial adds a shader extension on top of it; ToonMaterial and the paint and wear extensions give stylised looks; ShaderMesh and SurfaceShader take your own shader. Fog, volumetric fog, decals and fire are here too.

import { Sphere } from "raea/3d";
import { Mesh3d } from "raea/mesh";
import { StandardMaterial } from "raea/pbr";

const Ball = () => (
  <Mesh3d>
    <Sphere radius={0.5} />
    <StandardMaterial base_color="#c03030" perceptual_roughness={0.2} metallic={0.1} clearcoat={1} />
  </Mesh3d>
);

import { AmbientOcclusion, Decal, ExtendedMaterial, Fire } from "raea/pbr"

raea/pbr exports 22 components, 1 function, 1 value, 35 types. Bevy's counterpart: bevy_pbr, bevy_material. Source: sdk/raea/src/pbr.ts.

#Components

#AmbientOcclusion

Screen-space ambient occlusion: creases, corners and the ground under things darken where the sky's and the room's light can't reach. It darkens ambient and environment light (an , an ), not the direct light of a sun or a lamp. Turns multisampling off, so the edges are smoothed by SMAA instead (see ). Put it inside the Canvas3D, once; the first frame's holds for the piece.

Bevy: bevy_pbr::ssao::ScreenSpaceAmbientOcclusion.

Takes AmbientOcclusionProps's props.

#Decal

A picture pressed onto whatever surface it lies across: a label on a jar, a stain on a counter, tiles on a wall, a sticker on a laptop (Bevy's forward decal; the camera gets a depth prepass for it). Placed and keyed like any part, so it moves and fades with a render's clock and a game's play alike.

Bevy: bevy_pbr::mesh_material::MeshMaterial3d<bevy_pbr::extended_material::ExtendedMaterial<bevy_pbr::pbr_material::StandardMaterial, bevy_pbr::decal::forward::ForwardDecalMaterialExt>>.

Takes DecalProps's props.

#ExtendedMaterial

Bevy's ExtendedMaterial: a StandardMaterial with one of raea's extensions (GridExtension, PaintExtension, ToonExtension) drawn on it.

<ExtendedMaterial base={} extension={} />

Bevy: bevy_pbr::ExtendedMaterial.

Used in: shader/extended_material, shader/extended_material_bindless.

#Fire

A fire: a flame drawn as a volume, its tongues rising, curling and tearing off as it burns, with a flickering light on its surroundings. Every pixel of it is a function of the frame (rising 3D noise in a tapering envelope), so a render of any frame equals its play. Stand it on its fuel (a pyre, a brazier); put embers and smoke round it yourself.

Bevy: bevy_pbr::mesh_material::MeshMaterial3d<raea_render::engine::fire::FireMaterial>.

Takes FireProps's props.

#Fog

Distance fog: far things fade into color. Inside the it is Bevy's DistanceFog on that camera, with all of Bevy's fields (an atmospheric falloff, the sun's colour); inside the Canvas3D it fogs the scene's camera by near, far or density.

Bevy: bevy_pbr::fog::DistanceFog.

Takes FogProps's props.

#FogVolume

A box of air that light shows in: dust in a sunbeam, smoke, a haze of blood. Needs a in the Canvas3D; lights marked volumetric throw shafts through it, and every light's glow fills it softly. A part, so it keeps its name across frames: animate its density, colour and placement.

Bevy: bevy_light::volumetric::FogVolume.

Takes FogVolumeProps's props.

Used in: 3d/fog_volumes.

#GridExtension

raea's grid over a StandardMaterial, as an ExtendedMaterial's extension (engine/render grid.rs):

Bevy: bevy_pbr::mesh_material::MeshMaterial3d<bevy_pbr::extended_material::ExtendedMaterial<bevy_pbr::pbr_material::StandardMaterial, raea_render::engine::grid::Grid>>.

#Lightmap

A light bake on the meshes of a its mesh names, lighting them in place of the scene's lights, scaled by their material's lightmap_exposure (a in the same Model, by material). Goes in a .

Bevy: bevy_pbr::lightmap::Lightmap.

Used in: 3d/lightmaps.

#PaintExtension

#ProceduralExtension

raea's procedural surface over a StandardMaterial, as an ExtendedMaterial's extension (systems/procmat):

<ExtendedMaterial base={} extension={} />

Bevy: bevy_pbr::mesh_material::MeshMaterial3d<bevy_pbr::extended_material::ExtendedMaterial<bevy_pbr::pbr_material::StandardMaterial, raea_sys_procmat::Procedural>>.

#Refinish

Every inside re-covered: each of its glTF materials (all, or the one each names by material) given the colour, texture or finish each gives, the rest of it kept (a run of cabinets painted, the doors and drawers with them; map: null takes the wood's picture off). A model's own children go first.

#ShaderExtension

Also takes the props of SurfaceShaderSpec.

Used in: shader/extended_material, shader/extended_material_bindless.

#ShaderMesh

A mesh drawn by a material written here in WESL or WGSL: one generic Bevy material (rdb's ShaderMaterial, an AsBindGroup of 16 uniform slots and 4 textures) whose fragment shader is this source, so a dissolve, a toon ramp, a hologram or a procedural pattern needs no Rust. Uniforms may change from frame to frame (they're set again on any frame where they change); the shader isn't compiled again (#28).

Bevy: bevy_pbr::mesh_material::MeshMaterial3d<raea_sys_material::shader_material::ShaderMaterial>.

Takes ShaderMeshProps's props.

#Splat

A gaussian splat: a reconstructed scene or object, drawn back to front for the frame's camera, behind any mesh in front of it, through the frame's look. Animate it with reveal, assemble, disperse, explode, wave, twist, morph and pulse, all values of the frame.

Bevy: bevy_pbr::mesh_material::MeshMaterial3d<raea_render::engine::splat::SplatMaterial>, bevy_pbr::mesh_material::MeshMaterial3d<raea_render::engine::splat::SplatMask>.

Takes SplatProps's props.

#StandardMaterial

Bevy's StandardMaterial for the Mesh3d it's inside. Unlit draws as MeshBasicMaterial; a clearcoat or transmission as MeshPhysicalMaterial; anything else as MeshStandardMaterial, all on Bevy's StandardMaterial in the engine.

Bevy: bevy_pbr::pbr_material::StandardMaterial.

Also takes the props of StandardMaterialProps.

Used in: ui/render_ui_to_texture, ui/widgets/viewport_node, 3d/fog, 3d/vertex_colors, 3d/rotate_environment_map, 3d/transparency_3d, 3d/spherical_area_lights, 3d/lightmaps, and 41 more.

#SurfaceShader

One shader over every lit standard surface in the scene that has none of its own (meshes, Models' materials, Characters), so the whole scene shares one look. Unlit, toon, paint, flat and looked surfaces and ShaderMesh keep theirs. In the 3D beside the camera; one per scene.

Bevy: bevy_pbr::mesh_material::MeshMaterial3d<bevy_pbr::extended_material::ExtendedMaterial<bevy_pbr::pbr_material::StandardMaterial, raea_sys_shader::ShaderExt>>.

Takes SurfaceShaderSpec's props.

#ThreeShaderMaterial

A three.js shader on the mesh it's in, as it is: a ShaderMaterial's GLSL (or a node material's WGSL) with its uniforms, drawn by raea's engine with three's built-ins. <R3F> makes these from an R3F scene's materials.

Takes ThreeShaderMaterialProps's props.

#ToonExtension

Also takes the props of ToonExtensionProps.

#ToonMaterial

raea's ToonMaterial: a StandardMaterial's colour, texture and emission drawn in bands, as <ExtendedMaterial base={<StandardMaterial />} extension={<ToonExtension />} /> is (the old MeshToonMaterial).

Bevy: bevy_pbr::mesh_material::MeshMaterial3d<bevy_pbr::extended_material::ExtendedMaterial<bevy_pbr::pbr_material::StandardMaterial, raea_render::engine::toon::ToonExt>>, bevy_pbr::mesh_material::MeshMaterial3d<raea_render::engine::toon::OutlineMaterial>.

Also takes the props of StandardMaterialProps (material, base_color, base_color_texture, emissive, alpha_mode); ToonExtensionProps.

#Volume

A simulated volume: density and heat in a box, put in by its sources and puffs, lifted by heat, weighed down, carried by the wind and its own curls, drawn lit and shadowed by itself. Smoke, a cloud or a contrail is a choice of these (examples/volumes). Simulated and raymarched by engine/render volume.rs:

Bevy: bevy_pbr::mesh_material::MeshMaterial3d<raea_render::engine::volume::VolumeMaterial>.

Takes VolumeProps's props.

#VolumetricFog

Volumetric fog on the camera: light in the air, drawn inside every , with shafts from the lights marked volumetric. Put it inside the Canvas3D, once; without it fog volumes draw nothing.

Bevy: bevy_light::volumetric::VolumetricFog, bevy_light::volumetric::VolumetricLight.

Takes VolumetricFogProps's props.

Used in: 3d/fog_volumes.

#WearExtension

raea's chips, grime and rust over a StandardMaterial, as an ExtendedMaterial's extension (systems/wear):

Bevy: bevy_pbr::mesh_material::MeshMaterial3d<bevy_pbr::extended_material::ExtendedMaterial<bevy_pbr::pbr_material::StandardMaterial, raea_sys_wear::Wear>>.

#Functions

#volumeShadow

a volume's shadow as the row's number: 1 by default, 0 for none

function volumeShadow(owner: string, v: unknown): number

#Values

#FogFalloff

FogFalloff's constructors: the visibility distance (5% contrast left at it by default) to a density

Used in: 3d/atmospheric_fog.

#Types

#AlphaMode

Bevy's AlphaMode, as it reflects.

type AlphaMode = "Opaque" | "Blend" | "Premultiplied" | "Add" | "Multiply" | "AlphaToCoverage" | { Mask: number }

#AmbientOcclusionProps

#DecalProps

#ExtendedMaterialProps

The props of ExtendedMaterial, tabled there.

#FireProps

#FogProps

#FogVolumeProps

#GridExtensionProps

raea's extension of StandardMaterial (a Bevy MaterialExtension of raea's): graph paper over the surface for greybox levels, lines every cell world units (fixed in the world, so they run on across shapes), a heavier one every major cells (4), in color, and each face of a Box outlined in edge ("" for no outlines). Its colours are the first frame's. It goes in an ExtendedMaterial's extension.

The props of GridExtension, tabled there.

#LightmapProps

The props of Lightmap, tabled there.

#MetallicRoughnessMaps

Separate greyscale maps packed into Bevy's metallic_roughness_texture when they load: the roughness map's grey as its green, the metalness map's as its blue (white without one, so metallic is its factor exactly). Poly Haven's "_rough" sets come this way; a packed "_arm" map is a plain path.

#PaintExtensionProps

raea's extension of StandardMaterial for a paint look (): the surface broken up by world-space noise of scale metres (1), its tone boundaries wandering by breakup (0.5) and patches of it taking color (amount, 0.6, of the way): a mottled field, rust, a wall's uneven paint. It goes in an ExtendedMaterial's extension.

The props of PaintExtension, tabled there.

#ProceduralExtensionProps

raea's extension of StandardMaterial that draws a pattern on the GPU in place of its flat colour (the engine's Procedural MaterialExtension, systems/procmat): pattern (noise, wood, marble, stone, brick, tiles, fabric, brushed, plaster) in colors with roughness rough_a/rough_b, features scale metres across, a bump; brick and tiles in tile [w, h] metre cells with gap metre joints in gap_color. Over it, each 0-1: dust on what faces up, dirt in joints, hollows, undersides and the floor line, edges worn lighter. The pattern overrides the base's colour and roughness; its lighting stays. It goes in an ExtendedMaterial's extension, alone.

The props of ProceduralExtension, tabled there.

#SampledImage

A picture read with its own sampler: Bevy's load_with_settings, whose ImageLoaderSettings give the Image its ImageSamplerDescriptor ({ path: "checker.png", sampler: { filter: "nearest" } } for hard pixels).

#ShaderExtensionProps

raea's extension of StandardMaterial written in WESL: its fn surface runs before Bevy's lighting and its fn lit after it, on the base's inputs, so the surface stays lit and shadowed. raea/3d's is the same thing; the spec is SurfaceShaderSpec. It goes in an ExtendedMaterial's extension, alone.

Bevy: bevy_pbr::extended_material::ExtendedMaterial<bevy_pbr::pbr_material::StandardMaterial, raea_sys_shader::ShaderExt>.

The props of ShaderExtension, tabled there.

#ShaderMeshProps

#SplatMorph

#SplatProps

#SplatWave

#StandardMaterialAnimate

The StandardMaterial fields animate takes, each a track of its own kind of value. An emissive brighter than white is LinearRgba keys of one colour: track({ 0: E.mul(0), 30: E.mul(2.5) }) with E = LinearRgba.from(Srgba.hex(c)).

#StandardMaterialProps

Bevy's StandardMaterial fields (colours as CSS colours, textures as file paths), with Bevy's defaults.

#SurfaceDrawProps

How a surface's alpha and faces draw (Bevy's StandardMaterial alpha_mode, alpha cutoff, double_sided and cull_mode), from the first frame.

#SurfaceShaderSpec

#ThreeShaderMaterialProps

#ToonBand

#ToonExtensionAnimate

#ToonExtensionProps

raea's extension of StandardMaterial that cel-shades it (the engine's ToonExt; three.js's MeshToonMaterial): the scene's lights in steps hard bands (2; bands for an explicit ramp, darkest first), the bottom one shadow_color (the base colour darker, nudged towards violet), with an optional rim, highlight and ink outline (true for their defaults). Its base gives base_color, base_color_texture, emissive, alpha_mode and material; a toon surface has no roughness or metal. It goes in an ExtendedMaterial's extension, alone.

#ToonHighlight

#ToonMaterialProps

The props of ToonMaterial, tabled there.

#ToonOutline

#ToonRim

#VolumeCommon

#VolumeProps

#VolumeSource

where density and heat come in: a burner, or an engine moving at -> to (a contrail)

#VolumetricFogProps

#WearExtensionProps

raea's extension of StandardMaterial that wears it (the engine's Wear MaterialExtension, systems/wear): its paint mottled, chipped back to chip_color on edges and a few spots, grime gathered low and underneath and rust run down in streaks, fixed in the part's own space as it moves. amount 0-1; chips, grime and rust each 0-1 of it (0.6, 0.5, 0.25); scale a blotch's size in metres (0.08); seed moves the pattern. It goes in an ExtendedMaterial's extension.

The props of WearExtension, tabled there.