Compilation and reflection
Understand how BESL is linked, extended from Rust, optimized, reflected, and executed before you change the compiler.
Read this page before you change the BESL parser, linker, optimizer, reflection, a backend generator, or the VM. Byte Engine turns authored BESL into a linked semantic graph before it generates platform shader source or executes the program in the VM. The language itself is specified in the BESL reference.
Follow the compilation path
parsetokenizes the source and builds a syntax tree.stack_layersplaces the declarations of the shader's layout layers under that tree, lowest layer first. A shader without layers skips this step.- An optional
ProgramTransformadapts that tree to the renderer, such as by adding the helpers its shaders share. Material programs start here instead: a renderer'sProgramGeneratorbuilds their whole tree, bindings and entry point included, from the material's BEMX graph. lexresolves names, types, members, calls, overloads, and references into a semantic graph. It normalizesStageInput,interface,output, and record returns into the stage input and output nodes that the VM and generators use.compile_to_beslcombines parsing and linking and can link the source to a supplied parent scope.- The optimizer removes semantically dead portable code.
- Reflection evaluates the reachable graph, and the active generator emits GLSL, HLSL, or MSL. Tests can compile the same graph for VM execution.
Standalone .besl assets use this path during baking and take their stage
settings and layout layers from the adjacent
.besl.bead file.
On macOS, baking keeps a precompiled header of the Metal standard-library
texture types in the system temporary directory, named
byte-engine-msl-prelude-<hash>.pch. Every shader compile reuses it, which
roughly halves the time a bake takes. Byte Engine builds one header for each
Metal toolchain and deployment target, and compiles without it if the compiler
rejects it, so you can delete these files at any time.
Extend a program from Rust
Some graph features are intentionally available only to engine and render-model
code. They aren't syntax you can write in a .besl file.
| Generated feature | Rust entry point | Use |
|---|---|---|
| Backend-specific code | ParserNode::glsl, ParserNode::hlsl, ParserNode::msl, or ParserNode::raw_code | Bridge a feature that portable BESL can't express. Declare every graph input and output. |
| Specialization value | ParserNode::specialization | Add a host-selected typed value at a pipeline constant id. Vector components take consecutive ids, so give each specialization its own range. Pipelines receive values through SpecializationMapEntry at the same ids, and the VM receives them by name through SpecializationValues. See Shader variants for when to use one. |
| Custom intrinsic | ParserNode::intrinsic or ParserNode::intrinsic_with_parameters | Register a generated callable operation and its typed body. |
| Generated struct | ParserNode::r#struct with ParserNode::member fields | Expose a Rust record shape to the BESL parent scope. |
| Parent scope | compile_to_besl(source, Some(parent)) | Let authored source resolve generated types, values, bindings, and helpers. |
| Layout layers | stack_layers(module, layers) | Link a parsed module against shared BESL declarations, such as a descriptor set that several shaders bind. Baking does this for the layers a .besl.bead file lists. |
Raw nodes declare their dependencies explicitly. For example, renderer code can add one GLSL-only expression with named graph inputs and outputs:
let node = besl::ParserNode::glsl("native_expression", &["input"], &["output"]);Keep raw nodes small. Reflection can follow their declared dependencies but
can't inspect the backend source itself. The VM rejects reachable raw nodes with
UnsupportedRawCode.
Understand optimization
optimization::optimize operates on functions reachable from main. It:
- removes unread local declarations when their initializer has no observable effect;
- removes statements after a
return,continue, orbreakin the same block; and - repeats until removing one local doesn't expose another dead local.
Calls, atomics, image writes, barriers, raw nodes, and assignments outside a local value remain intact. The pass is idempotent and reports how many dead locals and unreachable statements it removed.
Understand reflection
The resource-management shader layer reflects descriptors into stable metadata:
- authored name and flat slot;
- buffer, sampled-texture, or storage-image kind;
- texture view shape and resource count;
- storage-buffer stride for the active layout target; and
- read and write usage.
Reflection groups the descriptors into descriptor sets: one for each
layout layer that declares
descriptors, in the order the shader lists them, and one for the descriptors the
shader declares itself. Each set holds its layer's whole layout and marks the
descriptors that code reachable from main uses. Two sets with the same
descriptors have the same identity, whichever shader they were reflected from.
It rejects distinct bindings that alias one flat slot. Reflection also classifies
the reachable output as Opaque, NonOpaque, or Unknown for material
decisions. Raw backend code can make that classification unknown because its
effects aren't visible to the semantic evaluator.
Express resources and outputs in BESL whenever possible. Reachable declarations let Byte Engine validate, reflect, optimize, and test the program consistently.
Execute BESL in the VM
The VM runs portable BESL semantics on the host. Use it for behavior tests that shouldn't depend on one generated shading language.
The VM supports:
- scalar, vector, matrix, struct, array, function, expression, and control-flow semantics;
- descriptor buffers, sampled textures and samplers, storage images, push constants, and stage input and output layouts;
- texture mips, explicit level of detail, texel fetches, array layers, image operations, and atomics;
- invocation coordinates, configurable subgroup collectives, workgroup shared storage, and barriers through the workgroup scheduler; and
- task payloads and output counts plus captured mesh counts, positions, triangles, and render-target array indices.
Compile a linked graph with ExecutableProgram, bind its resources through
DescriptorBindings, and call run_main, run_main_with_config, or
run_workgroup. ExecutionConfig sets instruction and call-depth limits,
invocation coordinates, subgroup size, and task or mesh output limits.
Rust API
The BESL reference specifies the language that this path compiles.