Byte Engine Docs
BESL

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

  1. parse tokenizes the source and builds a syntax tree.
  2. stack_layers places the declarations of the shader's layout layers under that tree, lowest layer first. A shader without layers skips this step.
  3. An optional ProgramTransform adapts that tree to the renderer, such as by adding the helpers its shaders share. Material programs start here instead: a renderer's ProgramGenerator builds their whole tree, bindings and entry point included, from the material's BEMX graph.
  4. lex resolves names, types, members, calls, overloads, and references into a semantic graph. It normalizes StageInput, interface, output, and record returns into the stage input and output nodes that the VM and generators use. compile_to_besl combines parsing and linking and can link the source to a supplied parent scope.
  5. The optimizer removes semantically dead portable code.
  6. 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 featureRust entry pointUse
Backend-specific codeParserNode::glsl, ParserNode::hlsl, ParserNode::msl, or ParserNode::raw_codeBridge a feature that portable BESL can't express. Declare every graph input and output.
Specialization valueParserNode::specializationAdd 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 intrinsicParserNode::intrinsic or ParserNode::intrinsic_with_parametersRegister a generated callable operation and its typed body.
Generated structParserNode::r#struct with ParserNode::member fieldsExpose a Rust record shape to the BESL parent scope.
Parent scopecompile_to_besl(source, Some(parent))Let authored source resolve generated types, values, bindings, and helpers.
Layout layersstack_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, or break in 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.

On this page