Lumina

GPU rendering engine — 21 sub-crates for math, shaders, pipelines, render graphs, and UI.

Documentation

Architecture Overview

Lumina is Helix's GPU graphics pipeline — a complete rendering framework built from scratch across 18 sub-crates and 200+ source files. It spans the full stack from SPIR-V shader compilation to PBR rendering, ray tracing, and UI composition.

Sub-Crate Stack

Lumina — Sub-Crate Stack5N · 4E
▶Application LayerHigh-level 3D + UI1Rendering LayerFrame management + p…2Shader LayerCompilation + IR2Core LayerGPU primitives + mat…2■Backend LayerHardware interface1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

Sub-Crate Inventory

CrateFilesDescription
lumina-core~100GPU resources: buffers, commands, descriptors, devices, pipelines, textures, sync
lumina-math~10Vector/matrix math (vec2/3/4, mat3/4), quaternions, transforms
lumina-shader~15Shader compilation: compiler, module, reflection, variants
lumina-ir~20Intermediate representation: instructions, blocks, functions, SSA, CFG, optimizer
lumina-spirv~15SPIR-V binary: builder, disassembler, instruction encoding, optimizer, validator
lumina-derive~10Proc macros: shader codegen, SPIR-V generation, vertex layout derivation
lumina-render~20Rendering: frame management, render graph, passes, culling, GI, hybrid rendering
lumina-pipeline~10Pipeline state: cache, descriptor layout, reflection, specialization constants
lumina-material~10Material system: PBR, procedural, shader graphs, texture sampling, layers
lumina-mesh~15Geometry: meshlets, cluster LOD, BLAS acceleration, virtual geometry, streaming
lumina-backend~15Vulkan backend: bindless resources, ray tracing pipelines, mesh shaders
lumina-sync~8GPU sync: fences, semaphores, barriers, timeline semaphores, workload tracking
lumina-memory~10GPU memory: allocator, pool, staging buffers, streaming, virtual allocation
lumina-debug~10Debug tools: frame capture, logger, GPU markers, perf counters, validation layers
lumina-scene~15Scene graph: ECS integration, transforms, frustum culling, instancing, LOD, streaming
lumina-3d~103D rendering: atmosphere, camera, GI, lighting, PBR shading, post-processing, shadows
lumina-ui~15UI framework: animation, immediate mode, input, layout, retained mode, widgets, themes
lumina-tools~10Dev tools: AI optimizer, hot reload, live metrics, predictive analysis, time travel debug
lumina-inspector~10Inspector: frame capture, memory analysis, pipeline state, shader debug, timeline

Handle System

Lumina uses a type-safe handle system for GPU resources to prevent use-after-free and dangling references:

graphics/lumina-core/src/types.rs
rust
pub struct Handle<T> {
2
id: u32,
3
generation: u32,
4
_marker: PhantomData<T>,
5
}
Index

Each handle contains a generation counter that is incremented when a resource is freed. Accessing a handle with a stale generation returns an error instead of undefined behavior.

Resource Types

Handle TypeGPU Resource
Handle<Buffer>GPU buffer (vertex, index, uniform, storage)
Handle<Texture>GPU texture (1D, 2D, 3D, cube, array)
Handle<Sampler>Texture sampler state
Handle<Pipeline>Graphics/compute pipeline state object
Handle<RenderPass>Render pass with subpasses and attachments
Handle<Framebuffer>Framebuffer with color/depth attachments
Handle<Shader>Compiled shader module
Handle<DescriptorSet>Descriptor set binding resources to shaders

Math Library

lumina-math provides GPU-optimized math types:

Types

TypeSizeComponents
Vec28Bx, y
Vec312Bx, y, z
Vec416Bx, y, z, w
Mat336B3x3 matrix
Mat464B4x4 matrix
Quat16BQuaternion rotation
Transform80BPosition + Rotation + Scale
AABB24BAxis-aligned bounding box
Frustum96B6 planes for culling

All types implement Copy, Clone, PartialEq, and SIMD-accelerated operations where available.

Render Pipeline

The rendering pipeline processes frames through a configurable graph:

Frame Lifecycle

Render Pipeline — Frame Lifecycle9N · 8E
▶Begin FrameAcquire swapchain im…1Scene CullingFrustum (AABB), Occl…2Render Graph ExecutionTopo-sort passes, al…2Pass: Shadow MapCascade shadow maps,…2Pass: G-BufferNormals, albedo, met…2Pass: LightingDeferred PBR BRDF + …2Pass: Post-ProcessingBloom, tone mapping,…2Pass: UI OverlayImmediate-mode UI re…2■End FrameSubmit command buffe…1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

Render Graph

The render graph is a directed acyclic graph of render passes with automatic resource management:

graphics/lumina-render/src/graph.rs
rust
2 refs
pub struct RenderGraph {
2
nodes: Vec<GraphNode>,
3
edges: Vec<GraphEdge>,
4
textures: Vec<VirtualTexture>,
5
buffers: Vec<VirtualBuffer>,
6
}
7
2 refs
impl RenderGraph {
pub fn new() -> Self;
pub fn add_pass<F>(&mut self, name: impl Into<String>, builder_fn: F) -> NodeId
11
where F: FnOnce(&mut PassBuilderImpl);
pub fn create_texture(&mut self, desc: TextureDesc) -> VirtualTextureHandle;
pub fn compile(&self) -> Result<CompiledGraph>;
pub fn execute(&self, compiled: &CompiledGraph, ctx: &mut RenderContext);
15
}
Index

Features

  • Automatic barrier insertion — resource transitions (read → write) are handled automatically
  • Transient resource allocation — textures used only within the frame are allocated from a pool and recycled
  • Pass culling — passes whose outputs are unused are removed
  • Parallel command recording — independent passes record commands in parallel

Shader Compilation

The shader pipeline compiles high-level shader code to GPU-executable SPIR-V:

Shader Compilation Pipeline6N · 6E
optional▶Shader SourceGLSL-like or Helix S…1lumina-shaderParse + compile2lumina-irIntermediate Represe…2lumina-spirvSPIR-V Code Generati…3lumina-deriveProc Macro Generatio…2■GPU DriverHardware compilation2
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

SPIR-V Module

graphics/lumina-spirv/src/module.rs
rust
2 refs
pub struct SpirVModule {
2
pub header: Header,
3
pub capabilities: Vec<Capability>,
4
pub entry_points: Vec<EntryPoint>,
5
pub types: BTreeMap<Id, TypeDecl>,
6
pub functions: Vec<Function>,
7
}
8
2 refs
impl SpirVModule {
pub fn from_binary(words: &[u32]) -> SpirVResult<Self>;
pub fn validate(&self) -> SpirVResult<()>;
pub fn to_binary(&self) -> Vec<u32>;
13
}
Index

IR Optimization Passes

PassDescription
Dead Code EliminationRemove unreachable instructions
Constant FoldingEvaluate constant expressions at compile time
Function InliningInline small functions
Loop UnrollingUnroll small constant-count loops
Common Subexpression EliminationRemove redundant computations

Magma GPU Driver

The Magma driver (drivers/gpu/magma/, 52+ sub-crates, 61 source files in the main tree) provides the hardware interface between Lumina and the GPU.

Sub-Crate Architecture

Magma GPU Driver — Sub-Crate Architecture8N · 7E
▶magma/GPU driver stack7magma-coreGPU, Engine, Command…1magma-halPCI, BAR, MMIO, IRQ,…1magma-memAddress space, buddy…1magma-cmdCommand buffer, chan…1magma-rpcGSP firmware RPC (NV…1magma-glOpenGL 4.6 implement…1magma-vulkanVulkan 1.3 implement…1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

Hardware Abstraction

drivers/gpu/magma/crates/magma-hal/src/pci.rs
rust
1
// PCI device discovery
pub struct PciDeviceInfo {
3
pub vendor_id: u16,
4
pub device_id: u16,
5
pub bars: [Option<Bar>; 6], // Base Address Registers
6
}
7
8
// MMIO access
pub struct MmioRegion {
pub fn read32(&self, offset: u64) -> u32;
pub fn write32(&self, offset: u64, value: u32);
pub fn read64(&self, offset: u64) -> u64;
pub fn write64(&self, offset: u64, value: u64);
14
}
Index

GPU Memory Management

Magma manages VRAM using a buddy allocator:

RegionTypePurpose
VRAMDevice-localTextures, render targets, vertex buffers
System RAMHost-visibleStaging buffers, uniform buffers
BARCPU-visible VRAMDirect CPU access to VRAM (NVIDIA ReBAR)

API Support

APIVersionFeatures
Vulkan1.3Ray tracing, mesh shaders, bindless, dynamic rendering
OpenGL4.6Compatibility — context, buffer, shader, pipeline, framebuffer

GPU Synchronization

Lumina provides multiple synchronization primitives for GPU-CPU and GPU-GPU coordination:

Primitives

PrimitiveScopeDescription
FenceCPU ↔ GPUCPU waits for GPU work to complete
SemaphoreGPU ↔ GPUQueue-to-queue synchronization
BarrierWithin passMemory/execution dependency within a command buffer
TimelineSemaphoreGPU ↔ GPUMonotonic counter-based sync (Vulkan 1.2+)

Workload Tracking

graphics/lumina-sync/src/workload.rs
rust
pub struct WorkloadTracker {
pub fn submit(&mut self, commands: CommandBuffer, fence: Fence);
pub fn wait_idle(&self);
pub fn is_complete(&self, fence: &Fence) -> bool;
pub fn gpu_timestamp(&self) -> u64;
6
}
Index

Codebase Scale

MetricValue
Lumina sub-crates18
Magma sub-crates52+
Total source files270+
Estimated total lines50,000+
Shader pipeline stages5 (source → parse → IR → optimize → SPIR-V)
Render pass typesShadow, G-buffer, Lighting, Post-process, UI
GPU sync primitives4 (Fence, Semaphore, Barrier, Timeline)
Supported GPU APIs2 (Vulkan 1.3, OpenGL 4.6)