Skip to content

Vulkan

The render-vulkan target (src/rtype/render/vulkan/, namespace rtype::render::vulkan) is the Vulkan renderer:

  • VulkanRenderer: implements IRenderer. Skeleton for now: init() creates the instance, the debug messenger and the window surface; drawing throws UnsupportedFeatureException until it is implemented. Registered as "vulkan" by registerRenderer().
  • core::Loader: opens the system's Vulkan loader at run time and gives its vkGetInstanceProcAddr to the instance and the window library, so the process has one loader and a release does not need one linked (see Self-contained releases). On macOS it still links Homebrew's.
  • core::Instance: the VkInstance, with its extensions and layers.
  • core::DebugMessenger: prints the validation layer messages to stderr.
  • core::Device::setName() and command::CommandLabel: name objects and label passes, for validation messages and GPU captures. See GPU debugging.

A runnable example lives in examples/graphic/render/vulkan/VulkanInstance. examples/graphic/platform/sdl/SdlVulkanWindow runs the same renderer on a platform written with SDL3 inside the example: a model for plugging another windowing library into the engine.

Setup

macOS

macOS has no native Vulkan driver: Vulkan runs on top of Metal through MoltenVK. Install it with Homebrew, along with the loader, the shader compiler and the validation layers:

brew install molten-vk vulkan-loader glslang vulkan-validationlayers
  • vulkan-loader is required: on macOS the render-vulkan target links Homebrew's loader, the only one that finds Homebrew's MoltenVK and layers. The build stops with an explicit message if it is missing.
  • glslang is required: its glslangValidator compiles the shaders. On the other platforms it comes from xmake, but building it there needs xmake's own Python, which no longer builds on macOS.
  • vulkan-validationlayers is only needed to enable VK_LAYER_KHRONOS_validation (debug builds).

Linux / Windows

Both come from your GPU vendor: the driver installs the Vulkan loader (libvulkan.so.1, vulkan-1.dll), which core::Loader opens when the renderer starts, so a build links no loader and a machine without one gets an error naming what to install. For the validation layers, install vulkan-validationlayers (Linux package manager) or the Vulkan SDK (Windows).

Usage

The engine does not create VulkanRenderer itself: the render-vulkan target registers it under the name "vulkan", and the configuration picks it (see Backend.md):

rtype::plugins::graphics::BackendRegistry registry;
rtype::platform::glfw::registerPlatform(registry.platforms);   // "glfw"
rtype::render::vulkan::registerRenderer(registry.renderers);  // "vulkan"

rtype::core::config::Settings config;
config.set("platform", "glfw");
config.set("renderer", "vulkan");
config.set("vulkan.layers", std::vector<std::string>{"VK_LAYER_KHRONOS_validation"});  // debug builds
config.set("vulkan.debugging", true);

const rtype::plugins::graphics::Backend backend = registry.createBackend(config);

The vulkan settings fill a VulkanRenderer::Config: engineName, layers, extraExtensions, debugging (the DebugMessenger), minSeverity, preferredDeviceType (the type of GPU favored when several are suitable, "discrete_gpu" by default), synchronizationValidation, bestPractices, virtualResolution ({ width, height }, the resolution the game is designed for, see Camera and sprites) and presentMode (the swapchain's present mode: "fifo" by default, synchronized to the vertical blank and always supported; "mailbox", also synchronized to the vertical blank, but a newer image replaces the pending one instead of waiting for it; "immediate", not synchronized and may tear, for benchmarks; FIFO when the surface does not support the requested one). No layer is enabled by default.

When layers contains VK_LAYER_KHRONOS_validation, synchronizationValidation (on by default) and bestPractices (off by default) configure it through VK_EXT_layer_settings, chained into the instance's pNext: the layer's validate_sync and validate_best_practices settings. Synchronization validation reports missing barriers and hazards between commands, and is slow. The engine only loads the layer in debug builds (NDEBUG not defined).

VulkanRenderer needs a platform that implements IVulkanSurfaceSource (GlfwPlatform does):

  1. setup(), before the window exists: initLoader(), so GLFW uses the renderer's Vulkan loader (one loader per process). A platform without IVulkanSurfaceSource throws UnsupportedFeatureException here.
  2. init(), once the window exists: the instance with getRequiredExtensions() (plus the layers and the messenger), then the window surface with createSurface().

On macOS, Instance also enables VK_KHR_portability_enumeration, which MoltenVK requires.

Textures

createTexture() takes RGBA8 pixels (decoded by the TextureAssets resource) and returns a TextureId:

  1. A memory::Image: a VkImage from VMA (device local, one mip level), R8G8B8A8_SRGB, usage SAMPLED | TRANSFER_DST, and its VkImageView.
  2. Uploader::upload() copies the pixels into a staging buffer and records, with Synchronization2 barriers: UNDEFINED → TRANSFER_DST_OPTIMAL, vkCmdCopyBufferToImage, then TRANSFER_DST_OPTIMAL → SHADER_READ_ONLY_OPTIMAL for the fragment and compute shaders.
  3. Uploader::flush() submits and waits: the texture is ready when createTexture() returns.
  4. The image goes into a core::SlotMap, which gives the TextureId (slot index and generation). Destroying a texture bumps its slot's generation, so an id kept from before reaches nothing instead of the slot's next texture.

destroy() forgets the id at once, and defers the image to the DeletionQueue bucket of the last recorded frame: it is freed once that frame's fence has signaled, so destroying a texture drawn this frame is safe. The textures left are destroyed with the renderer, before the allocator.

Samplers and descriptor sets

A sampler says how a shader reads an image: filtering and what happens past its edges. texture::SamplerCache creates the four the textures need at init(), one per TextureDesc filter and repeat mode, shared by every texture:

Clamp to edge Repeat
kNearest (sharp pixels: pixel art) nearest-clamp nearest-repeat
kLinear (smooth; anisotropic up to 16x when the device supports it) linear-clamp linear-repeat

Each texture also gets its descriptor set, written once by createTexture(): its image view and its sampler, as a combined image sampler at VulkanRenderer::kTextureSet (1), binding kTextureBinding (0). A fragment shader reads it as layout(set = 1, binding = 0) uniform sampler2D, next to the frame's uniforms at set 0, so drawing a texture only binds its set. The sets come from a descriptor::DescriptorAllocator, which adds a pool of 64 sets whenever the current one is full, so the number of textures has no fixed limit; a destroyed texture gives its set back to its pool.

Shader layout

Every pipeline the renderer builds shares one layout (VulkanRenderer's pipeline layout), with the data grouped by how often it changes, so binding from the least to the most frequent keeps the lower sets bound:

What Where Changes GLSL C++
FrameUniforms: time, delta time, framebuffer size, the camera's viewProjection set 0, binding 0 once per frame frame rendering::FrameUniforms
The texture and its sampler set 1, binding 0 per texture (batch) uTexture the texture's set
DrawConstants: model (unit quad to world), color, uvRect push constants, 96 bytes per draw draw rendering::DrawConstants

Per-object data fits in the push constants (at most 128 bytes, the minimum every device supports), so there is no set 2. The set and binding numbers are in rendering/ShaderLayout.hpp. A shader gets all of it with #include "ShaderLayout.glsl" (from shaders/include/, which includes FrameUniforms.glsl, TextureSet.glsl and DrawConstants.glsl). Each GLSL block mirrors its C++ struct field by field: static_asserts check the C++ offsets, and vulkan-tests embeds a shader that includes ShaderLayout.glsl (through set_values("glsl.includedirs", ...)), so a header that stops compiling fails the build.

Camera and sprites

setView() sets the frame's view (a graphics::View: position, rotation, projection); the last one set before endFrame() applies to the whole frame, and without one the frame shows the view from the world's origin at its top-left corner. graphics::CameraView (in contract/renderer/, so games use the same math to convert the mouse to world coordinates) turns it into what the frame shows:

  • Virtual resolution: Config::virtualResolution (setting vulkan.virtualResolution = { 1920, 1080 }) is the resolution the game is designed for. The camera shows that many world units divided by its zoom, centred on its position, whatever the window size; the viewport is the largest rectangle of that aspect ratio in the window, centred, and the rest is left to the clear colour (letterboxing), so resizing never stretches anything. Unset (0x0), the view is the framebuffer: one world unit per framebuffer pixel, which on a HiDPI screen (Retina: 1600x1200 for an 800x600 window) is not a window pixel. The engine sets it to the window's size, so world units do not depend on the screen.
  • Projection: glm::orthoRH_ZO, X right, Y down, depth 0 to 1, after the camera's rotation (clockwise on screen) around its position. The matrix goes in FrameUniforms::viewProjection, written by endFrame().
  • Conversions: screenToWorld() and worldToScreen(), in framebuffer pixels from the top-left corner.

draw(Sprite) does not record anything: it turns the sprite into a 64-byte rendering::SpriteInstance (position, size and origin scaled, rotation, UV rect from the source and the texture size, colour) and adds it to the frame's rendering::SpriteBatch, where consecutive sprites of the same texture form one batch. endFrame() then hands the batch to rendering::SpritePass, which copies the instances into the frame's instance buffer (one per frame in flight, doubled when too small) and records, for each batch, the texture's set and one instanced draw of a 6-vertex quad (shaders/sprite.vert builds it from gl_VertexIndex; sprite.frag multiplies the texture by the colour). Both are the default shader: they include the shaders ABI of the renderer contract (src/rtype/contract/renderer/shaders/) with no game code, so built-in and game sprites are drawn by the same code, and the renderer depends on no plugin for it. Only consecutive sprites merge, so the draw order is kept: sort by layer, then by texture within a layer, for fewer draw calls. A debug build with the validation layer draws 10,000 sprites in about 8 ms a frame on an Apple M-series GPU.

Blending. Every sprite and shape is blended with premultiplied alpha (src + dst * (1 - src.a), GraphicsPipeline::BlendMode::kPremultipliedAlpha):

  • createTexture() multiplies each pixel's colour by its alpha before uploading it (texture::premultiplySrgb()), in linear space since the textures are sRGB, through a 64 KiB table computed once. The IRenderer contract still takes straight alpha. Filtering then mixes a sprite's edge with its transparent surroundings without a dark fringe.
  • The graphics::BlendMode of a Sprite or a Shape travels per instance (SpriteInstance::blend, the second byte of ShapeInstance::kind), and the shaders ABI's fragment_common.glsl (mirrored by rendering/Blend.hpp) finishes the premultiplied colour for it: kAlpha as is, kAdditive with an alpha of 0 (nothing is taken from what is under it), kCutout opaque or fully transparent around half opacity (no discard: without a depth buffer a transparent fragment changes nothing). One pipeline draws every mode, so a mode never splits a batch, and no sort by pipeline is needed. Shapes have no cutout (it would lose their antialiased edge): kCutout is drawn as kAlpha.
  • The passes are rebuilt when a recreated swapchain changes its image format, since a pipeline is built for one.

examples/graphic/render/vulkan/VulkanBlendModes shows the three modes side by side.

Meshes and the scene texture

A tool built on the renderer (the editor, Editor.md) uses two optional calls of IRenderer:

  • drawMesh(mesh) adds indexed triangles, in framebuffer pixels, to the frame's meshes. endFrame() draws them last, in the window, with rendering::MeshPass: one pipeline (shaders/mesh.vert and mesh.frag, on the shared layout, so a mesh texture is a set 1 like any other), a vertex and an index buffer per frame in flight, and one scissored indexed draw per MeshCommand. Its set 0 is its own FrameGlobals (_meshGlobals), with one unit per pixel, origin at the top-left corner: updating the overlay's would change what the overlay already recorded.
  • setSceneSize(size) draws the scene (sprites, particles, shapes, overlay) into a texture instead of the window. The change is made by the next beginFrame(). The texture is in the swapchain's format, an entry of the texture table whose TextureId stays the same when the size changes, and the recordScene() that draws into it is the one that draws into the swapchain image without it. Its barriers are kSceneToColorAttachment (it waits for the previous frame's fragment shaders that sampled it) and kSceneToShaderRead.

  • setScenePreview(preview) draws the world a second time, from preview.view, into a texture of preview.size (_previewTexture, made like the scene's by adoptTarget()). The world is uploaded once (uploadWorld()) and recorded twice (recordWorld()), first into the preview, with its own FrameGlobals (_previewGlobals, one unit per pixel at zoom 1), then into the scene; neither the overlay nor the meshes are in the preview, and clearWorld() forgets the world once both are recorded.

getFrameStats() gives the sprites, shapes, overlay items, mesh triangles and textures of the last frame.

Shaders

Shaders are written in GLSL and compiled to SPIR-V, then turned into vk::raii::ShaderModules by pipeline::ShaderCache, which keeps each module so asking twice gives the same one. They come from two places.

Built-in shaders (engine)

Shaders the engine itself uses (rectangles, sprites, post-processing) live in src/rtype/render/vulkan/shaders/ and are embedded in the renderer at build time: nothing to find on disk at runtime, and they cannot get out of sync with the code. The glsl.spirv rule of render/vulkan/xmake.lua compiles shaders/<name>.<stage> (vert, frag, comp, geom, tesc, tese) with glslangValidator from the glslang package (a system one, such as Homebrew's, is used when found) and generates <name>.<stage>.h, which defines const uint32_t rtype_shader_<name>_<stage>[]:

#include "sprite.vert.h"
const vk::raii::ShaderModule& vertex = shaders.get("sprite.vert", rtype_shader_sprite_vert);
  • Target environment vulkan1.3; debug info (-g) in debug builds, for validation messages and RenderDoc; size-optimized SPIR-V (-Os) in release builds.
  • Common headers go in shaders/include/ and are included with #extension GL_GOOGLE_include_directive : require then #include "Name.glsl".
  • A shader error fails the build with file:line. Editing a shader recompiles only that shader; editing a header in shaders/include/ recompiles every shader.

Built-in shaders at runtime

The built-in shaders are SPIR-V files loaded at runtime with shaders.load("sprite.frag.spv"). A relative path is resolved against the vulkan.shaderDirectory setting ("shaders" by default), itself relative to the executable's directory, never to the working directory: the files are found the same way through xmake run, a terminal or a file manager. An absolute shaderDirectory is used as is. A missing file or a file that is not SPIR-V throws a ShaderException naming the full path.

The game's own shaders do not go through this folder: the shader plugin compiles them from the game directory, and reloads them when they are saved (Shaders.md).

Specialization constants

pipeline::SpecializationBuilder builds the vk::SpecializationInfo of a stage, for compile-time variants of one shader (e.g. layout(constant_id = 0) const bool USE_TEXTURE = false;) without extra shader files: builder.add(0, true).add(1, 4U), then builder.build(). The result points into the builder: keep both alive until the pipeline is created.

Pipeline cache

Every pipeline is created through one VkPipelineCache, saved to disk when the renderer is destroyed and read back by init() at the next launch, so the driver does not compile the same pipelines again. The file is the vulkan.pipelineCache setting ("pipeline_cache.bin" by default), relative to the user's cache directory's rtype folder: ~/Library/Caches/rtype on macOS, $XDG_CACHE_HOME/rtype or ~/.cache/rtype on Linux, %LOCALAPPDATA%\rtype on Windows. It stays writable even when the game is installed in a read-only directory. An absolute path is used as is, and an empty one keeps nothing.

The file is written to a temporary file then renamed over the old one, so a crash while saving never leaves a truncated cache. At launch, its header is checked against the GPU (vendor, device and the driver's pipeline cache UUID): a cache from another GPU or driver, or a corrupted one, is ignored with a message and rebuilt, since some drivers crash on such data instead of ignoring it. Measured on the particle example (Apple M-series, MoltenVK): the pipelines are created in about 27 ms on the first launch, and about 1.5 to 2 ms with the cache.

Run the example

xmake f -m debug --VulkanInstance=y   # debug: validation enabled (release: -m release, no validation)
xmake build VulkanInstance
xmake run VulkanInstance              # "Vulkan instance and window surface created."

The validation layer stays silent while there is nothing to report. To check that it is loaded:

VK_LOADER_DEBUG=layer xmake run VulkanInstance   # look for: Insert instance layer "VK_LAYER_KHRONOS_validation"

Roadmap

What a complete Vulkan renderer needs, from the instance (done) to the per-frame loop.

%%{init: {'flowchart': {'nodeSpacing': 45, 'rankSpacing': 70, 'curve': 'basis', 'wrappingWidth': 220}}}%%
flowchart TB
  classDef must fill:#1f6feb,stroke:#0b3d91,color:#fff,stroke-width:2px
  classDef opt fill:#6e7681,stroke:#30363d,color:#fff
  classDef d2 fill:#2da44e,stroke:#116329,color:#fff
  classDef d3 fill:#d97706,stroke:#7c2d12,color:#fff
  classDef adv fill:#8250df,stroke:#4c2889,color:#fff
  classDef dbg fill:#cf222e,stroke:#82071e,color:#fff
  classDef dec fill:#facc15,stroke:#854d0e,color:#000,stroke-width:2px

  %% =========================================================
  %% LEGEND
  %% =========================================================
  subgraph LEGEND["LEGEND"]
    direction LR
    LG1["Required"]:::must
    LG2["Optional"]:::opt
    LG3["2D specific"]:::d2
    LG4["3D specific"]:::d3
    LG5["Advanced"]:::adv
    LG6["Debug / validation"]:::dbg
    LG7{"Decision"}:::dec
  end

  %% =========================================================
  %% ROW 1 - FOUNDATION
  %% =========================================================
  subgraph ROW1["ROW 1 - FOUNDATION"]
    direction LR

    subgraph PH0["0. Project setup"]
      direction TB
      A1["Windowing<br/>GLFW / SDL3 / native"]:::must
      A2["Vulkan SDK + loader<br/>volk optional"]:::must
      A3["Helper libs<br/>VMA, glm, stb_image,<br/>cgltf / assimp, ImGui"]:::opt
      A4["Shader compiler<br/>glslang / shaderc /<br/>DXC / slangc"]:::must
      A5["CMake<br/>+ shader build step"]:::must
      A1 --> A2 --> A3 --> A4 --> A5
    end

    subgraph PH1["1. Instance"]
      direction TB
      B1["VkApplicationInfo<br/>apiVersion 1.3+"]:::must
      B2["Instance extensions<br/>surface, platform surface,<br/>debug_utils"]:::must
      B3["MoltenVK / macOS<br/>portability_enumeration"]:::opt
      B4["Validation layer"]:::dbg
      B5["vkCreateInstance"]:::must
      B6["Debug messenger"]:::dbg
      B1 --> B2 --> B3 --> B4 --> B5 --> B6
    end

    subgraph PH2["2. Surface"]
      direction TB
      C1["VkSurfaceKHR<br/>from window"]:::must
      C2["Headless alternative<br/>render to image<br/>+ readback"]:::opt
      C1 -.- C2
    end

    subgraph PH3["3. Physical device"]
      direction TB
      D1["vkEnumerate<br/>PhysicalDevices"]:::must
      D2["Queue families<br/>graphics, present,<br/>compute, transfer"]:::must
      D3["Device extensions<br/>swapchain,<br/>portability_subset"]:::must
      D4["Features<br/>dynamicRendering, sync2,<br/>timeline, anisotropy,<br/>BDA, descriptorIndexing"]:::must
      D5["Limits<br/>sizes, alignments,<br/>MSAA counts"]:::must
      D6["Score + pick GPU"]:::opt
      D1 --> D2 --> D3 --> D4 --> D5 --> D6
    end

    subgraph PH4["4. Logical device"]
      direction TB
      E1["Queue create infos<br/>one per unique family"]:::must
      E2["Feature pNext chain<br/>1.1 / 1.2 / 1.3"]:::must
      E3["vkCreateDevice"]:::must
      E4["vkGetDeviceQueue"]:::must
      E1 --> E2 --> E3 --> E4
    end

    subgraph PH5["5. Memory"]
      direction TB
      F1["VMA allocator<br/>or manual sub-alloc"]:::must
      F2["Memory types<br/>DEVICE_LOCAL,<br/>HOST_VISIBLE,<br/>HOST_COHERENT"]:::must
      F3["Unified memory<br/>Apple Silicon / ReBAR"]:::opt
      F1 --> F2 --> F3
    end

    PH0 --> PH1 --> PH2 --> PH3 --> PH4 --> PH5
  end

  %% =========================================================
  %% ROW 2 - PRESENTATION AND SYNC
  %% =========================================================
  subgraph ROW2["ROW 2 - PRESENTATION AND SYNCHRONIZATION"]
    direction LR

    subgraph PH6["6. Swapchain"]
      direction TB
      G1["Query capabilities,<br/>formats, present modes"]:::must
      G2["Format SRGB<br/>+ color space"]:::must
      G3["Present mode<br/>FIFO / MAILBOX /<br/>IMMEDIATE"]:::must
      G4["Extent, image count,<br/>usage, transform"]:::must
      G5["vkCreateSwapchainKHR"]:::must
      G6["Images + image views"]:::must
      G7["Recreate on resize /<br/>OUT_OF_DATE /<br/>minimized"]:::must
      G1 --> G2 --> G3 --> G4 --> G5 --> G6 --> G7
    end

    subgraph PH7["7. Render targets"]
      direction TB
      H1["Depth<br/>D32 / D24S8"]:::d3
      H2["2D: depth optional<br/>z-order via layers"]:::d2
      H3["MSAA color<br/>+ resolve"]:::opt
      H4["HDR RGBA16F"]:::adv
      H5["G-Buffer"]:::adv
      H1 --> H2 --> H3 --> H4 --> H5
    end

    subgraph PH8["8. Rendering model"]
      direction TB
      I0{"Which model?"}:::dec
      I1["Dynamic rendering<br/>vkCmdBeginRendering"]:::must
      I2["Classic render pass<br/>+ subpasses<br/>+ framebuffer"]:::opt
      I3["Attachments<br/>load / store ops,<br/>clear, resolve"]:::must
      I0 --> I1 --> I3
      I0 --> I2 --> I3
    end

    subgraph PH9["9. Commands and sync"]
      direction TB
      J1["Command pools<br/>per thread / frame"]:::must
      J2["Command buffers<br/>primary + secondary"]:::must
      J3["Frames in flight<br/>2 or 3"]:::must
      J4["Semaphores<br/>imageAvailable,<br/>renderFinished"]:::must
      J5["Fences"]:::must
      J6["Timeline semaphores<br/>+ Synchronization2"]:::adv
      J1 --> J2 --> J3 --> J4 --> J5 --> J6
    end

    PH6 --> PH7 --> PH8 --> PH9
  end

  %% =========================================================
  %% ROW 3 - RESOURCES AND PIPELINES
  %% =========================================================
  subgraph ROW3["ROW 3 - GPU RESOURCES AND PIPELINES"]
    direction LR

    subgraph PH10["10. Shaders"]
      direction TB
      K1["Write GLSL /<br/>HLSL / Slang"]:::must
      K2["Compile to SPIR-V"]:::must
      K3["VkShaderModule"]:::must
      K4["Specialization<br/>constants"]:::opt
      K5["Reflection<br/>SPIRV-Reflect"]:::opt
      K6["Hot reload"]:::opt
      K1 --> K2 --> K3 --> K4 --> K5 --> K6
    end

    subgraph PH11A["11a. Buffers"]
      direction TB
      L1["Staging buffer"]:::must
      L2["Copy to DEVICE_LOCAL"]:::must
      L3["Vertex + index"]:::must
      L4["Uniform per frame<br/>std140"]:::must
      L5["SSBO std430<br/>device address"]:::adv
      L6["Indirect buffers<br/>query pools"]:::adv
      L1 --> L2 --> L3 --> L4 --> L5 --> L6
    end

    subgraph PH11B["11b. Images"]
      direction TB
      M1["VkImage + memory<br/>+ view"]:::must
      M2["Layout transitions<br/>barriers"]:::must
      M3["Mipmaps"]:::d3
      M4["Samplers"]:::must
      M5["Arrays, cubemaps, 3D,<br/>BCn / ASTC / ETC2"]:::adv
      M1 --> M2 --> M3 --> M4 --> M5
    end

    subgraph PH12["12. Descriptors"]
      direction TB
      N1["Set layouts"]:::must
      N2["Descriptor pool"]:::must
      N3["Allocate + update"]:::must
      N4["Push constants"]:::must
      N5["Sets per frequency<br/>global / material / object"]:::opt
      N6["Bindless"]:::adv
      N1 --> N2 --> N3 --> N4 --> N5 --> N6
    end

    subgraph PH13["13. Graphics pipeline"]
      direction TB
      O1["Pipeline layout"]:::must
      O2["Shader stages<br/>+ vertex input<br/>2D: pos uv color<br/>3D: pos normal tangent uv"]:::must
      O3["Input assembly<br/>+ dynamic viewport /<br/>scissor"]:::must
      O4["Rasterization<br/>+ multisample"]:::must
      O5["Depth / stencil<br/>+ color blend"]:::must
      O6["Create + pipeline cache"]:::must
      O7["Variants: opaque,<br/>transparent, shadow,<br/>skybox, sprite, UI"]:::must
      O1 --> O2 --> O3 --> O4 --> O5 --> O6 --> O7
    end

    subgraph PH14["14. Other pipelines"]
      direction TB
      P1["Compute<br/>culling, particles,<br/>skinning, post"]:::adv
      P2["Mesh + task shaders"]:::adv
      P3["Ray tracing<br/>BLAS, TLAS, SBT"]:::adv
      P1 --> P2 --> P3
    end

    PH10 --> PH11A --> PH11B --> PH12 --> PH13 --> PH14
  end

  %% =========================================================
  %% ROW 4 - CONTENT AND PASSES
  %% =========================================================
  subgraph ROW4["ROW 4 - CONTENT AND MULTI-PASS"]
    direction LR

    subgraph PH15A["15a. 2D content"]
      direction TB
      Q1["Ortho camera"]:::d2
      Q2["Sprite batching<br/>instancing + atlas"]:::d2
      Q3["Tilemap"]:::d2
      Q4["Text<br/>SDF / MSDF"]:::d2
      Q5["UI<br/>ImGui or custom"]:::d2
      Q6["Layer sort<br/>+ alpha blend"]:::d2
      Q7["Particles, 2D lights,<br/>post effects"]:::d2
      Q1 --> Q2 --> Q3 --> Q4 --> Q5 --> Q6 --> Q7
    end

    subgraph PH15B["15b. 3D content"]
      direction TB
      R1["Model loading<br/>glTF / OBJ / FBX"]:::d3
      R2["Perspective camera<br/>flip Y, depth 0..1"]:::d3
      R3["Transforms<br/>+ PBR materials"]:::d3
      R4["Lights<br/>dir, point, spot, IBL"]:::d3
      R5["Shadows CSM + PCF<br/>+ skybox"]:::d3
      R6["Instancing, culling,<br/>LOD, animation"]:::d3
      R7["Transparency<br/>sort or OIT"]:::d3
      R1 --> R2 --> R3 --> R4 --> R5 --> R6 --> R7
    end

    subgraph PH16["16. Multi-pass architecture (render graph)"]
      direction LR
      S1["Render graph<br/>passes + deps"]:::adv
      S2["Shadow"]:::d3
      S3["Geometry /<br/>G-Buffer"]:::must
      S4["Lighting<br/>deferred / Forward+"]:::d3
      S5["Transparent"]:::must
      S6["Post-process<br/>tonemap, bloom,<br/>SSAO, TAA"]:::adv
      S7["UI overlay"]:::must
      S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7
    end

    PH15A --> PH16
    PH15B --> PH16
  end

  %% =========================================================
  %% ROW 5 - PER-FRAME LOOP
  %% =========================================================
  subgraph ROW5["ROW 5 - PER-FRAME RENDER LOOP"]
    direction LR
    T1["Poll events<br/>delta time"]:::must
    T2["Wait fence"]:::must
    T3["Acquire<br/>next image"]:::must
    T4{"Acquire<br/>result?"}:::dec
    TR["Recreate swapchain<br/>+ render targets<br/>see phase 6"]:::dbg
    T5["Reset fence<br/>+ cmd buffer"]:::must
    T6["Update<br/>UBO / SSBO"]:::must
    T7["Begin cmd<br/>buffer"]:::must
    T8["Barrier to<br/>COLOR_ATTACHMENT"]:::must
    T9["Begin<br/>rendering"]:::must
    T10["Bind pipeline,<br/>descriptors,<br/>buffers"]:::must
    T11["Draw /<br/>DrawIndexed /<br/>Indirect /<br/>Dispatch"]:::must
    T12["End<br/>rendering"]:::must
    T13["Barrier to<br/>PRESENT_SRC"]:::must
    T14["End cmd<br/>buffer"]:::must
    T15["Queue submit<br/>wait / signal<br/>+ fence"]:::must
    T16["Queue<br/>present"]:::must
    T17{"Present<br/>result?"}:::dec
    T18["Next frame<br/>index"]:::must
    T19{"Window<br/>closed?"}:::dec
    TQ["Exit loop<br/>go to cleanup"]:::dbg

    T1 --> T2 --> T3 --> T4
    T4 -- "SUCCESS" --> T5
    T4 -- "OUT_OF_DATE" --> TR
    T5 --> T6 --> T7 --> T8 --> T9 --> T10 --> T11 --> T12 --> T13 --> T14 --> T15 --> T16 --> T17
    T17 -- "OUT_OF_DATE /<br/>SUBOPTIMAL" --> TR
    T17 -- "SUCCESS" --> T18 --> T19
    T19 -- "yes" --> TQ
    T19 -- "no" --> T1
    TR --> T1
  end

  %% =========================================================
  %% ROW 6 - QUALITY AND LIFECYCLE
  %% =========================================================
  subgraph ROW6["ROW 6 - PERFORMANCE, DEBUG AND CLEANUP"]
    direction LR

    subgraph PH18["18. Performance"]
      direction TB
      U1["Per-thread<br/>command pools"]:::adv
      U2["Async transfer<br/>queue"]:::adv
      U3["Async compute<br/>queue"]:::adv
      U4["Pipeline cache<br/>on disk"]:::adv
      U5["Ring buffers<br/>persistent mapping"]:::adv
      U1 --> U2 --> U3 --> U4 --> U5
    end

    subgraph PH19["19. Debug and profiling"]
      direction TB
      V1["Validation<br/>+ sync validation"]:::dbg
      V2["Object names<br/>+ labels"]:::dbg
      V3["RenderDoc / Nsight /<br/>Xcode GPU capture"]:::dbg
      V4["Timestamp queries"]:::dbg
      V5["Device lost<br/>handling"]:::dbg
      V1 --> V2 --> V3 --> V4 --> V5
    end

    subgraph PH20["20. Cleanup (reverse order)"]
      direction TB
      W1["vkDeviceWaitIdle"]:::must
      W2["Pipelines, layouts,<br/>descriptors, shaders"]:::must
      W3["Buffers, images,<br/>samplers, allocator"]:::must
      W4["Sync objects,<br/>command pools"]:::must
      W5["Swapchain + views"]:::must
      W6["Device, surface,<br/>messenger, instance"]:::must
      W7["Window"]:::must
      W1 --> W2 --> W3 --> W4 --> W5 --> W6 --> W7
    end

    PH18 --> PH19 --> PH20
  end

  %% =========================================================
  %% GLOBAL FLOW (row to row only, keeps rows horizontal)
  %% =========================================================
  LEGEND ~~~ ROW1
  ROW1 --> ROW2 --> ROW3 --> ROW4 --> ROW5 --> ROW6