Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Architecture notes

The rest of this book is for people using Unipute. This page is for people working on it, and goes into more detail than a user needs.

It is the same file as docs/ARCHITECTURE.md in the repository.

Architecture

This describes how Unipute is put together and where the pieces that are not built yet will attach. It is written for anyone working on Unipute itself.

The shape of it

front end            IR                 back end           output
---------            --                 --------           ------
#[kernel] macro  ->  unipute-ir     ->  unipute-naga   ->  WGSL, SPIR-V,
(unipute-macros)     Kernel             lower + write      MSL, HLSL, GLSL

Three properties follow from that shape, and every change should preserve them.

The IR has no dependencies. unipute-ir is plain data: structs, enums, String and Vec. It pulls in nothing, not a shader compiler and not a graphics library. That is what lets a new front end or back end be added without dragging the rest of the project along.

Neither end knows about the other. The macro never mentions naga. The naga back end never mentions Rust syntax. They meet at Kernel and nowhere else.

Nothing touches a device. No crate here creates an instance, a queue or a buffer. Output is text or a word buffer, and the caller decides what to do with it. This is what “graphics API agnostic” means in practice, and it is why the layout information in BindingInfo names groups and bindings rather than any particular API’s descriptor types.

Crates

CrateDepends onPurpose
unipute-irnothingKernel, Function, Type, Expr, Stmt, the Backend trait, Target
unipute-macrossyn, quote, unipute-ir, unipute-nagathe #[kernel] attribute
unipute-naganaga, unipute-irlowering to naga IR and writing shaders
uniputethe three abovethe crate users depend on

unipute-macros depends on unipute-naga because the whole point is that the back end runs during compilation. Cargo builds a proc macro for the host, so the two copies of unipute-naga in a build (host and target) have their features resolved separately. That is why the facade’s target features name both, as in spv = ["unipute-macros/spv", "unipute-naga?/spv"].

How a kernel becomes a shader

  1. unipute_macros::kernel parses the attribute and the function with syn.
  2. parse::kernel walks the signature into Resources and the body into Stmts, resolving names against a scope stack. Untyped integer literals take their type from the other side of the operator they appear in. Nested fn items are read first, since a call has to resolve against a signature whichever order the two were written in. A #[workgroup] let becomes a Shared entry on the kernel rather than a local, and produces no statement.
  3. unipute_naga::lower builds a naga::Module. Two naga rules shape it: expressions must appear before their users, and most expressions have to sit inside a Statement::Emit range while a specific few must not. The ones that must not, which are literals, globals, locals and function arguments, are all created before the first emit range opens and looked up from a cache afterwards. A call’s result is in that group too, but it cannot be made up front, so a call closes the open range and opens a new one instead. Helpers are lowered before the entry point. Workgroup memory is a global variable in naga’s workgroup address space, declared next to the resources and looked up the same way, with no binding.
  4. unipute_naga::validate runs naga’s validator. A failure here means a bug in Unipute, not in the user’s kernel, so the message is passed through as it is.
  5. Each enabled target’s writer runs, and generate::kernel_type pastes the result into the caller’s crate as a constant.

The function is replaced by a type of the same name implementing Kernel, plus one trait per enabled target. Keeping the shader on a trait rather than an inherent constant means a caller can be generic over kernels.

Extension points

Four things are designed for and not implemented. Each one already has a place to attach.

Other back ends, such as CUDA and PTX

Attaches to: unipute_ir::Backend and unipute_ir::Target.

Backend is deliberately vague about output. It has an associated Output type, so a back end can produce a String of PTX, a word buffer, or machine code, and callers written against the trait do not care which.

Target::Ptx is already in the enum and Target::is_implemented already returns false for it, so the rest of the project can talk about a target before the generator for it exists.

What a PTX back end needs:

  • A new crate, unipute-ptx, depending on unipute-ir and nothing from naga.
  • impl Backend for PtxBackend, mirroring NagaBackend.
  • A feature on the facade and on unipute-macros, plus a #[cfg] block in generate::compile_targets and a PtxKernel trait.

What it does not need: any change to unipute-ir or unipute-macros beyond that feature. If a PTX back end turns out to need an IR change, that is a signal the IR has grown a naga assumption, and the fix belongs in the IR rather than in the new back end.

The one real gap is that CUDA’s memory model does not line up with bind groups. Resource names a group and a binding, which a PTX back end would have to flatten into kernel parameters. That mapping belongs in the back end, not in the IR.

Graphics stages

Attaches to: unipute_ir::Stage.

Stage already has Vertex and Fragment alongside Compute, and it is #[non_exhaustive] so more can be added. Stage::is_implemented returns false for both, and lower checks it first, so a graphics kernel fails with a clear message today rather than a confusing one.

What graphics support needs:

  • Binding::Location in the IR, since a vertex shader passes values to a fragment shader by location rather than by built-in. This is the one change that does touch the IR.
  • A return type on Kernel, since a vertex shader produces a position and a fragment shader produces a colour. Today check_signature rejects any return type outright.
  • The graphics built-ins: Position, VertexIndex, InstanceIndex, FragDepth and so on. ir::BuiltIn is a flat enum, so these are additions rather than restructuring.
  • Matrix types in ir::Type, which is the other likely IR change.
  • #[kernel(vertex)] and #[kernel(fragment)] in the attribute parser, in place of the workgroup_size that compute requires.

Naga handles all of this already, so unipute-naga is mostly a matter of mapping the new variants across.

Bindings for C, C++ and other languages

Attaches to: unipute-ir, from the other side.

There are two different things people mean by bindings, and they need different work.

Calling Unipute from C. A host program written in C or Zig wants to hand Unipute a kernel and get a shader back. That needs an unipute-ffi crate with extern "C" functions over Kernel, built as a cdylib and staticlib, plus a generated header. The natural surface is narrow: build a kernel, add resources and statements, compile to a target, free the result. Because the IR is plain data with no borrowed lifetimes inside it, this is an opaque pointer API and not much more.

Writing kernels in another language. A Zig or C++ programmer wants to write the kernel itself in their own language. That is a new front end, not an FFI layer. It produces a Kernel the same way unipute-macros does, and from there the pipeline is identical. Nothing in unipute-ir or unipute-naga needs to change, which is the whole reason the IR has no dependencies.

The likely shape is a serialised form of Kernel, so a front end written in any language can emit it as data and hand it to a small Rust driver. That means adding optional serde support to unipute-ir, which is the one piece of preparation worth doing before anyone starts.

More of the Rust language in kernels

The front end covers a useful subset and rejects the rest with a message. The pieces most likely to be wanted next, in rough order of value:

  • Structs nested in structs, and arrays as struct fields. The IR and the back end take both already; the derive does not, see Structs.
  • Atomics as struct fields, for the same reason.
  • Textures and samplers, which mostly matter once graphics stages land.

Calling other functions is done, as nested fn items inside a kernel body. See Functions below for the shape of it and what is left. User defined structs are done too, and Structs is about how a macro on one item came to know about another. So are atomics, see Atomics.

Atomics

Type::Atomic(Scalar) is a u32 or i32 that invocations update through Expr::Atomic, Expr::AtomicCompareExchange and Stmt::Atomic. Reading one is an ordinary Expr::Index or Expr::Shared of its place and writing one is an ordinary Stmt::Store; naga’s writers see the pointer’s type and spell both as the atomic load and store of each language. The IR keeps atomics as a type rather than a flag on the operation because that is what every target does: the declaration says the memory is atomic, and the operations follow.

In naga an atomic operation is a statement that binds its result to an Expression::AtomicResult, the same arrangement as a call, so the lowering is the same dance: close the emit range, push the statement, open a new one. Stmt::Atomic pushes it with no result, except for an exchange, where naga insists on one. A compare and exchange binds naga’s predeclared two member struct, which Module::generate_predeclared_type makes and the writers know by name, and only the exchanged member is handed on. The old value would not say whether a target that is allowed to fail spuriously actually swapped.

The front end treats an atomic as a place and never a value. Scope::expr refuses an atomic typed result, so a bare read is an error pointing at .load(), and only a method receiver or the left side of an assignment goes through place_or_value, which allows it. Assignment and compound assignment to an atomic are caught there too, each naming the method to use instead. Uniforms, read only buffers, locals and helper parameters refuse the type outright, and the back end checks the buffer case again.

Structs

Type::Struct carries a StructType: a name, members with explicit byte offsets, and a size. The offsets are redundant in the sense that StructType::new computes them from the member types by the rules in Type::alignment, and that redundancy is deliberate. A host reading the IR should not need to know the rules, and a back end should not trust a front end to have followed them, so unipute-naga recomputes the layout and refuses a struct whose offsets differ. Naga’s writers lay a struct out by their own reckoning and only the SPIR-V one reads offsets back, so an unusual layout would come out five different ways rather than one wrong way.

The rules are the ones WGSL, SPIR-V, MSL and HLSL share for a storage buffer: scalars 4 bytes aligned to 4, vec2 8 aligned to 8, vec3 12 aligned to 16, vec4 16 aligned to 16, each member at the next multiple of its alignment, the struct rounded up to its largest. For a uniform the same rules hold as long as no member is itself a struct or an array, which is why the derive stops there for now: a nested struct in a uniform needs 16 byte alignment that a storage buffer does not, and one StructType cannot carry both.

How #[kernel] learns the fields. A proc macro sees the item it is on and nothing else. #[derive(Layout)] therefore leaves a macro_rules! next to the struct, holding its fields, and re-exports it under the struct’s own name with pub(crate) use. A macro and a type live in different namespaces, so the two do not collide, and a use of the struct brings the macro along. When #[kernel] finds a type name it does not know, it expands to a call of that macro, passing the names still unknown, the definitions gathered so far, the attribute and the whole function. The macro adds its struct and calls unipute::__kernel_with_layouts, which repeats until nothing is pending and then expands the kernel for real. crates/unipute-macros/src/chain.rs is the whole of it, and layout.rs is the derive.

Two consequences are worth knowing. A macro_rules! without #[macro_export] cannot be pub used out of its crate, and one with it lands at the crate root where a macro expanded macro cannot be reached by path (the macro_expanded_macro_exports_accessed_by_absolute_paths lint), so a struct and the kernels naming it have to share a crate. And a name that is not a Layout struct fails as “cannot find macro”, which is why the kernel macro also emits a Layout trait bound on every unknown name: the trait’s on_unimplemented message is the one that says what to do.

Host layout. The derive computes the #[repr(C)] layout from the same syntax, compares the two, and reports the first field that differs, with the padding field that would fix it. It emits offset_of! and size_of assertions as well, so a mistake in that computation would fail the build rather than pass silently. Vectors are spelled as arrays on the host, [f32; 3] for Vec3<f32>, because a host type with the GPU’s alignment would need a size Rust cannot give it: a vec3 is 12 bytes aligned to 16, and in Rust size is always a multiple of alignment.

Functions

A kernel body can declare fn items and call them. Three things about the design are worth knowing before changing any of it.

A helper captures nothing. ir::Function has parameters, locals and a body, and no access to resources, workgroup memory or built-ins. That is not a simplification: shader languages hand bindings and built-ins to the entry point, and a function called from it cannot ask for them. It also happens to match what a nested fn means in Rust, so the rule needs no explaining to someone reading a kernel.

Kernel::functions is ordered, callees first. No shader language has forward declarations, so a callee has to be written before its callers. The order is an invariant of the IR rather than something each back end works out, and the front end is what establishes it. parse::function::order reads the call graph off the syntax with a syn::visit::Visit before any body is parsed, which is also where a cycle is caught. Recursion cannot be represented in the IR at all, which is right, since no target supports it.

Naga has no call expression. Statement::Call binds its result to an Expression::CallResult, and that result is one of the expressions naga requires to sit outside an emit range. So lowering a call in the middle of an expression means closing the current range, pushing the call statement, and opening a new one. That is why lower_expr carries a &mut Block and a &mut Emitter rather than just returning a handle.

What is not done: sharing a helper between two kernels. #[kernel] is an attribute on one function and cannot see its siblings, so this needs a different surface, most likely a module level macro wrapping several kernels and their shared helpers together. Nothing in the IR would have to change for it.

Testing

  • crates/unipute-naga/tests/lowering.rs builds IR by hand and checks the generated shaders. This is where lowering bugs surface.
  • tests/kernels.rs goes from Rust source through the macro to shader text for every target, and checks that the compile time and run time paths agree.
  • tests/ui/ pins the error messages, since those are most of what a macro’s users experience. Run with TRYBUILD=overwrite to refresh them after changing a message on purpose.
  • tests/gpu.rs runs kernels on whatever adapter wgpu finds and compares the results with the same computation on the CPU. It is the only place a kernel that is well formed and wrong gets caught. It feeds wgpu the WGSL, SPIR-V and GLSL the crate writes, and the naga module straight out of lower, so each of those paths is exercised on a device rather than only through the validator. A machine with no adapter skips it with a note. CI installs a software Vulkan driver on Linux and sets UNIPUTE_REQUIRE_GPU there, so a missing adapter is a failure rather than a silent skip. The wgpu glue is examples/host/mod.rs, shared with the examples and outside the library.

When adding a back end or a stage, the first test to write is a lowering test, because it fails in a readable way. The macro tests are for the front end.

Toolchain

rust-toolchain.toml pins nightly, and .cargo/config.toml builds the dev profile with the cranelift codegen backend. That backend is the only reason for the pin. It compiles unoptimised binaries faster than LLVM, which is worth having on a workspace that rebuilds naga and a proc macro, and the cargo keys that select it are unstable.

It is a build speed setting and a constraint at the same time, so treat it as a rule rather than a detail:

  • No nightly language or library features anywhere. Not in the public API, not in the macro, not in tests or examples. Someone on stable has to be able to depend on Unipute and to work on it.
  • The cranelift keys stay in .cargo/config.toml. They belonged in Cargo.toml once, which meant the manifest carried cargo-features and stable cargo could not parse it, so every project depending on Unipute broke. A cargo config only applies to commands run inside this repository, so a dependent never sees it.
  • Nightly is not a capability to build on. If something seems to need a nightly feature, that is a design problem to solve rather than a feature to reach for.

rustup installs the cranelift component from the toolchain file, so a fresh checkout builds as is. To turn cranelift off, comment out the [unstable] and [profile.dev] sections of .cargo/config.toml. While they are there a stable cargo cannot read that file, so commenting them out is also what lets you run cargo +stable test locally.

CI runs the pinned nightly for testing and linting, and a separate job builds a crate against Unipute on stable from outside the checkout, where neither the pin nor the cargo config applies. Anything nightly only that reaches the manifest or the code fails there.