GPU Rendering Architecture

Engine-agnostic reference for the modern GPU programming model: how data reaches shaders, how resources are bound, how state is managed, and how synchronization works. Grounded in Vulkan 1.3+, DX12 SM6.6, and Metal 3+. Synthesized from Sebastian Aaltonen's No Graphics API blog series and the leotmp/no_gfx_api Odin implementation.

Relationship to other skills: This skill covers how the GPU is driven — the data model, binding model, state management, and synchronization. For software-rasterizer math (coordinate spaces, barycentric coordinates, projection), see game-rendering. For engine/GDSL shader authoring in Godot 4.x, see godot-shader. For diagnosing GPU bottlenecks and frame-rate problems, see game-performance.

Architecture Overview

The modern GPU programming model replaces per-draw API calls with a single root-pointer per dispatch/draw. The CPU writes structs into persistently-mapped GPU memory; the GPU reads them directly.

CPU (host)                              GPU (device)
─────────────────────────────────────────────────────────────────────
Frame arena (MEMORY_DEFAULT)
  ┌──────────────────────────────┐
  │ SceneData {                  │──── root pointer ────►  Vertex shader
  │   float4x4  viewProj         │                          reads via
  │   const Vertex*  verts       │──── GPU pointer ──────►  data->verts[id]
  │   const uint32*  indices     │──── GPU pointer ──────►  data->indices[id]
  │   uint32    textureBase      │──── heap index ───────►  textureHeap[base+0]
  │   uint32    drawCount        │
  │ }                            │
  └──────────────────────────────┘

Descriptor heap (MEMORY_DEFAULT)
  ┌────────────────────────────────────────────────────────────────┐
  │ slot 0 │ slot 1 │ slot 2 │ ... │ slot N │  (each = 256 bits)  │
  └────────────────────────────────────────────────────────────────┘
         ▲                                    ▲
    textureBase                          textureBase+N
    (color tex)                          (PBR tex)

GPU-private memory (MEMORY_GPU)
  ┌──────────────────────────────┐
  │ Vertex buffer (Morton-swizzled, DCC-compressed)               │
  │ Textures (Morton-swizzled, DCC-compressed)                    │
  └──────────────────────────────┘
         ▲
    Upload path: staging (MEMORY_DEFAULT) → copy cmd → GPU-private

The data model in one sentence: one const Data* root pointer per dispatch/draw; the struct may contain GPU pointers to other data — no vertex buffer objects, no uniform buffer objects, no descriptor sets.

Decision Tables

Memory Type Selection

Rule: MEMORY_DEFAULT is almost always correct for per-frame data. Only use MEMORY_GPU when you need the GPU's compression hardware (textures, large persistent buffers).

Descriptor / Binding Approach

Barrier Selection

Rule: start with no hazard flags. Add HAZARD_DRAW_ARGUMENTS when writing indirect args, HAZARD_DESCRIPTORS when updating bindless tables, HAZARD_DEPTH_STENCIL when reusing a depth attachment (depth read → depth write — flushes HiZ cache).

PSO State: Bake vs. Dynamic

CPU-Driven vs. GPU-Driven Rendering

Symptoms → Cause

API Feature Matrix

Min-Spec Hardware

TBDR note: Apple Silicon Macs (M1/M2/M3), ARM Mali, and Qualcomm Adreno are Tile-Based Deferred Renderers even on desktop/laptop. Blend state must be baked into the PSO or use framebuffer fetch on these architectures.

Key Invariants

1. Bindless is the baseline. A descriptor heap gives every shader access to every texture via a 32-bit index. No per-draw texture binding API. The heap is bound once per command buffer.

2. GPU pointer + struct = the data model. One const Data* root pointer per dispatch/draw. The struct may contain GPU pointers to other data — no vertex buffers, no uniform buffer objects, no descriptor sets. Safety: GPU virtual addresses carry no hardware bounds enforcement on most architectures — an out-of-bounds dereference reads or writes arbitrary GPU memory. Validate all offsets CPU-side before writing into root structs. Add explicit bounds checks in shaders when offsets are derived from GPU-written data.

3. Three memory types. CPU-mapped (default, persistently mapped), GPU-private (textures, large persistent data), Readback (for CPU reads of GPU output). Match to purpose.

4. Stage mask + hazard flags = the barrier model. No per-resource lists. Most barriers need no hazard flags. HAZARD_DRAW_ARGUMENTS after GPU writes indirect args; HAZARD_DESCRIPTORS after GPU writes descriptors.

5. PSO permutation kills perf. Minimize baked state; use dynamic state, shader objects, and static constants for permutation reduction.

6. Transient command buffers. Create, record, submit, done. No reuse. The driver uses a bump allocator; memory is reclaimed after GPU signals completion.

7. Timeline semaphores. One counter, monotonically increasing. wait(N - FRAMES_IN_FLIGHT) before touching frame N's resources. arena_free_all only after the semaphore wait.

8. Write through .cpu; pass .gpu to GPU commands. A MEMORY_DEFAULT allocation has two addresses. Never pass a .cpu pointer to a shader — it will fault or silently read garbage.

9. Staging lifetime = GPU copy completion. Keep staging allocations alive until the upload fence signals. Freeing the staging buffer before the copy engine finishes causes silent corruption.

10. NonUniformResourceIndex on non-uniform heap indices. Required in HLSL/GLSL when different lanes may sample different textures (deferred shading, ray tracing). Not needed for buffer pointer arithmetic.

Worked Examples

Example 1: Passing per-draw material data to shaders

Query: "How should I pass per-draw material data to shaders — push constants, uniform buffers, or something else?"

Skill-guided response:

Use the root-pointer model. Allocate a Material struct in the per-frame arena (CPU-mapped memory), store GPU pointers to textures and other arrays in it, pass its GPU address as the single root pointer.

// Shared CPU/GPU header:
struct alignas(16) MaterialData {
    float4   baseColor;        // 16 bytes — preloaded into scalar regs
    float    roughness;        // 4 bytes
    float    metallic;         // 4 bytes
    uint32   textureBase;      // 4 bytes — heap index; color=base+0, normal=base+1, pbr=base+2
    uint32   _pad;             // 4 bytes — padding; struct is 40 bytes raw, rounds to 48 with alignas(16)
    const float4x4* transform; // 8 bytes — GPU pointer to transform buffer
    // SECURITY: const is not just a performance hint (scalar register path).
    // A writable GPU pointer in a root struct is an arbitrary GPU memory write primitive
    // if its value is ever derived from GPU-written data. Keep output pointers CPU-controlled.
};

// CPU side (per draw):
auto mat = frameArena.allocate<MaterialData>();
mat.cpu->baseColor    = {1.0f, 0.5f, 0.2f, 1.0f};
mat.cpu->roughness    = 0.4f;
mat.cpu->metallic     = 0.0f;
mat.cpu->textureBase  = material.heapBaseIndex;
mat.cpu->transform    = transformBuffer.gpu;

gpuDrawIndexed(cmd,
    mat.gpu,   // vertex shader root pointer
    mat.gpu,   // pixel shader root pointer (same struct here; pass separate ptr when stages differ)
    indices, count);

Why not push constants: push constants are for tiny hot data (< 32 bytes, e.g., a frame counter or matrix index). They don't scale to arbitrary-size per-draw data.

Why not uniform buffers: uniform buffers add descriptor overhead — a descriptor set entry per buffer, alignment requirements, and binding API calls. The root-pointer model eliminates all of this.

Root pointer is the sweet spot: one 8-byte GPU VA in the command stream; the driver preloads the struct's leading fields into scalar registers before the wave launches; pointer arithmetic handles any size.

Example 2: GPU-driven culling writes garbage draw arguments

Query: "My GPU-driven culling compute shader writes draw arguments, then the indirect draw reads garbage. What's wrong?"

Skill-guided response:

Missing HAZARD_DRAW_ARGUMENTS barrier. The command processor prefetches indirect arguments before the compute shader's writes are visible. The barrier must target STAGE_DRAW_INDIRECT (not STAGE_COMPUTE) as the destination stage.

// 1. Culling compute — writes argumentBuffer and drawCount
//    max(1u, ...) avoids zero-count dispatch (DX12 UB on zero thread groups)
gpuDispatch(cmd, cullingData.gpu, {max(1u, (numObjects + 63) / 64), 1, 1});

// 2. REQUIRED: stall command processor prefetch
//    dstStage must be DRAW_INDIRECT, not COMPUTE
gpuBarrier(cmd, STAGE_COMPUTE, STAGE_DRAW_INDIRECT, HAZARD_DRAW_ARGUMENTS);

// 3. Indirect multidraw — now reads the GPU-written arguments
gpuDrawIndexedIndirectMulti(cmd,
    perDrawData.gpu, sizeof(PerDrawData),
    perDrawData.gpu, sizeof(PerDrawData),
    argumentBuffer.gpu,
    drawCount.gpu,
    maxObjects);  // always set to buffer capacity — never UINT32_MAX

Also check:

• drawCount buffer zeroed before culling dispatch each frame (otherwise count accumulates); add barrier(TRANSFER, COMPUTE) between the clear and the culling dispatch
• maxObjects set to the actual buffer capacity (not UINT32_MAX) to prevent the command processor reading past the buffer end
• Culling shader guards if (slot >= data->maxObjects) return; after InterlockedAdd — this is a security boundary: without it, a GPU-written slot value can write draw arguments to arbitrary GPU memory addresses

Relationship to Other Skills

game-rendering — Software-rasterizer math: coordinate spaces, perspective projection, barycentric coordinates, Z-buffer, backface culling. This skill covers how the GPU is driven; game-rendering covers what the GPU computes. When game-rendering mentions "GPU pipeline stages (vertex shaders, fragment shaders, rasterizer hardware)", it defers to Khronos — this skill fills that gap.

godot-shader — Engine/GDSL shader authoring in Godot 4.x: .gdshader files, GDSL syntax, visual effects, lighting models, post-processing. This skill covers the API-level programming model; godot-shader covers the shader language and engine integration. The concepts overlap (bindless textures, barriers) but the implementation is Godot-specific in godot-shader.

game-performance — Diagnosing and fixing GPU bottlenecks: profiling, fill-rate, bandwidth, CPU submission overhead. This skill explains how the pipeline is structured; game-performance explains how to measure and fix it when it's too slow. PSO permutation stutter is a design problem (this skill); measuring shader occupancy is a profiling problem (game-performance).

odin-gamedev — Odin/raylib glue patterns and the leotmp/no_gfx_api implementation. The reference files in this skill use Odin API examples from no_gfx_api. For Odin-specific patterns (type system, allocators, rawptr interop), see odin-gamedev.

References

Further Reading

• Sebastian Aaltonen, No Graphics API blog series: https://iolite-engine.com/blog_posts/no_graphics_api — the primary source for this skill; covers the full "no graphics API" programming model
• leotmp/no_gfx_api — Odin implementation of the concepts in this skill
• Vulkan 1.3 spec — authoritative reference for VK_KHR_synchronization2, VK_EXT_descriptor_buffer, VK_EXT_shader_object
• DX12 Agility SDK docs — Enhanced Barriers, ExecuteIndirect tier 1.1, SM6.6 bindless
• Metal Shading Language Specification — gpuAddress, gpuResourceID, argument buffers (Metal 3+)