tecs.gpu.materials

Material identity, numbering, and the component that selects one.

A material decides a fragment's color, coverage, surface normal, and lighting response. It is authored as a WGSL file under a material root, and every material found is folded into one generated fragment shader that dispatches on the id an instance carries. This module owns the names and the numbering; the backend owns the compiled dispatch.

world:spawn(
    tecs.ecs.Transform2D(120, 80, 1, 0, 0, 64, 64),
    tecs.gfx.Material(tecs.gpu.materials.id("rounded"), 0.25),
    tecs.gfx.Tint(0.2, 0.6, 1.0, 1.0),
    tecs.gfx.Renderable2D
)

An entity carrying no Material draws through textured, which holds id zero for exactly that reason. Every other name takes an id from sorted order, so adding or removing a material renumbers the ones after it. Persisted state therefore stores the name and resolves it again, which is what the component's own snapshot does.

Material.param supplies one scalar from zero to one. The built-ins read it as follows:

• ellipse uses the height fraction.
• ring uses the inner-radius fraction.
• rounded uses the corner-radius fraction.
• frame and line use a thickness fraction.
• capsule uses a height fraction.
• pie uses a full-turn sweep fraction.
• star uses valley depth.
• emissive uses how much of its own color the surface gives off.
• glyph uses the distance-field range.
• textured, circle, glyphalpha, and triangle ignore it.

Authoring a material#

A .wgsl file under a material root defines one material function:

fn material(frag: MaterialInput) -> MaterialOutput {
    var result = materialDefaults();
    let radius = mix(0.02, 0.20, frag.param);
    result.albedo = textureSample(image, imageSampler, frag.uv) * frag.color;
    result.coverage = -sdRoundedBox(frag.local, vec2(0.5), radius);
    result.lit = 1.0;
    return result;
}

frag.local runs from -0.5 to 0.5 inside the quad. frag.uv, frag.color, and frag.param carry the image coordinates, tint, and instance parameter. frag.blended says whether the fragment reaches a pass that blends it. Start from materialDefaults, then set albedo, normal, orm, lit, emission, and coverage.

Coverage above zero keeps a fragment; zero or below discards it. The deferred lane does not blend partial coverage: a tint alpha below one routes the instance to the blended lane instead. A material that resolves an edge by discarding puts the edge in alpha where frag.blended is set, which is what textured does.

Adding materials to a build#

addRoot names a directory this module globs for *.wgsl. The same directory is read by the build step that produces the shader pack, so the ids this module assigns and the ids the compiled dispatch answers to come from one rule applied to one set of files. A root added after the pack was built renumbers the set and the backend rejects an id its dispatch does not carry, rather than drawing the wrong material.

Runtime assembly and reload are deliberately absent. A release links no shader assembler and loads a prebuilt pack, so a changed material body is a rebuild.

struct Material
    id: integer
    param: number
end

id: integer

param: number

function addRoot(path: string): nil

function count(): integer

function define(name: string): nil

function find(name: string): integer?

function id(name: string): integer

function install(): nil

function name(value: integer): string?

function names(): {string}

function reset(): nil

function revision(): integer

const DEFAULT: string

const MaterialComponent: components.FFIComponent<Material>