Vulkan¶
The render-vulkan target (src/rtype/render/vulkan/, namespace rtype::render::vulkan) is the Vulkan renderer:
VulkanRenderer: implementsIRenderer. Skeleton for now:init()creates the instance, the debug messenger and the window surface; drawing throwsUnsupportedFeatureExceptionuntil it is implemented. Registered as"vulkan"byregisterRenderer().core::Loader: opens the system's Vulkan loader at run time and gives itsvkGetInstanceProcAddrto 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: theVkInstance, with its extensions and layers.core::DebugMessenger: prints the validation layer messages to stderr.core::Device::setName()andcommand::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-loaderis required: on macOS therender-vulkantarget 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.glslangis required: itsglslangValidatorcompiles 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-validationlayersis only needed to enableVK_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):
setup(), before the window exists:initLoader(), so GLFW uses the renderer's Vulkan loader (one loader per process). A platform withoutIVulkanSurfaceSourcethrowsUnsupportedFeatureExceptionhere.init(), once the window exists: the instance withgetRequiredExtensions()(plus the layers and the messenger), then the window surface withcreateSurface().
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:
- A
memory::Image: aVkImagefrom VMA (device local, one mip level),R8G8B8A8_SRGB, usageSAMPLED | TRANSFER_DST, and itsVkImageView. Uploader::upload()copies the pixels into a staging buffer and records, with Synchronization2 barriers:UNDEFINED→TRANSFER_DST_OPTIMAL,vkCmdCopyBufferToImage, thenTRANSFER_DST_OPTIMAL→SHADER_READ_ONLY_OPTIMALfor the fragment and compute shaders.Uploader::flush()submits and waits: the texture is ready whencreateTexture()returns.- The image goes into a
core::SlotMap, which gives theTextureId(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(settingvulkan.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 inFrameUniforms::viewProjection, written byendFrame(). - Conversions:
screenToWorld()andworldToScreen(), 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. TheIRenderercontract still takes straight alpha. Filtering then mixes a sprite's edge with its transparent surroundings without a dark fringe.- The
graphics::BlendModeof aSpriteor aShapetravels per instance (SpriteInstance::blend, the second byte ofShapeInstance::kind), and the shaders ABI'sfragment_common.glsl(mirrored byrendering/Blend.hpp) finishes the premultiplied colour for it:kAlphaas is,kAdditivewith an alpha of 0 (nothing is taken from what is under it),kCutoutopaque or fully transparent around half opacity (nodiscard: 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):kCutoutis drawn askAlpha. - 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, withrendering::MeshPass: one pipeline (shaders/mesh.vertandmesh.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 perMeshCommand. Its set 0 is its ownFrameGlobals(_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 nextbeginFrame(). The texture is in the swapchain's format, an entry of the texture table whoseTextureIdstays the same when the size changes, and therecordScene()that draws into it is the one that draws into the swapchain image without it. Its barriers arekSceneToColorAttachment(it waits for the previous frame's fragment shaders that sampled it) andkSceneToShaderRead. -
setScenePreview(preview)draws the world a second time, frompreview.view, into a texture ofpreview.size(_previewTexture, made like the scene's byadoptTarget()). The world is uploaded once (uploadWorld()) and recorded twice (recordWorld()), first into the preview, with its ownFrameGlobals(_previewGlobals, one unit per pixel at zoom 1), then into the scene; neither the overlay nor the meshes are in the preview, andclearWorld()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 : requirethen#include "Name.glsl". - A shader error fails the build with
file:line. Editing a shader recompiles only that shader; editing a header inshaders/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