Kapi Engine · Architecture Infographic

Engine Overview

System Layers

Application App Host & Editor

▶

App Host

Entry point, tick loop, module loading. Supports editor, game, and headless modes for automation and servers.

app_host.hmain.cpp

⚙

Editor Shell

ImGui-driven editor with viewport, asset browser, object details, performance panels, and gizmo overlays.

editor_main.cppImGui

☰

Project & Modules

Dynamic module loading, project settings, editor workflows, and game project configuration.

game_project.hmodule_host.h

scene data & render commands

World & Scene ECS, Scene Graph & Asset Pipeline

◉

World Runtime

Archetype-based ECS with SoA layout in 16KB cache-friendly chunks. Component registry, dirty-state tracking, and fragment-based world parsing.

world_runtime.hSoA 16KB

⋯

Scene Graph

Hierarchical scene structure with GPU BVH acceleration. BVH nodes with AABB bounds and proxy indices for GPU-driven culling.

world_scene_graph.hGpuSceneBvhNode

⚙

Asset Pipeline

Deterministic content-addressed cooking with DDC. Cooked mesh, material, and texture assets. Budget validation at cook time.

asset_cooker.hDDC

★

Bindless Resources

BindlessResourceTable manifest driving mesh/material/texture slots. Scene submission with resolved bindings and generation tracking.

SceneBindlessSubmission

renderable instances & bindless tables

Renderer Render Graph & GPU Pipeline

◆

Render Graph

DAG-based frame scheduling with automatic barrier coalescing, memory aliasing (30-50% VRAM savings), and async compute split execution.

RenderGraphBuilderCompiledRenderGraph

◆

Transient Resources

Alias-group-based memory sharing for frame-local resources. Textures and buffers allocated into shared heaps with lifetime tracking.

RenderGraphTransientAllocationDesc

▣

Visibility Buffer

8 bytes/pixel vs 64-128 for G-buffer. 32-bit packed payload: DrawCall(12) + Triangle(8) + Meshlet(12). Compute shader material evaluation.

VisBufferPayload32-bit

☀

Post-Processing

GTAO ambient occlusion, CMAA2 anti-aliasing, temporal resolve, and HDR tonemapping with per-backend compute implementations.

d3d12_gtao.hd3d12_cmaa2.h

compiled passes & execution segments

Core Runtime & Job System

⇄

Job System

Work-stealing scheduler with 5 priority lanes (Critical/High/Normal/Low/Idle). Lock-free atomics, one worker per hardware core, main-thread assist fallback.

JobCounterJobPriority

⚙

Engine Config

Runtime configuration, input contexts, key bindings, and editor runtime settings. Crash diagnostics with debug trigger support.

engine_config.hinput_contexts.h

▤

Resource Registry

Centralized GPU resource tracking. Runtime asset catalog with content-addressed lookups and streaming-friendly format consumption.

resource_registry.hruntime_asset_catalog.h

⚠

Diagnostics

Debug logging, crash diagnostics, screenshot capture, and performance tracking. Validation runner for headless CI/automation.

debug_log.hcrash_diagnostics.h

API abstraction

Platform & Backends Graphics APIs & OS Layer

■

D3D12 Backend

Native DirectX 12 renderer with GPU-driven submission, bindless descriptors, vertex pulling, and async compute execution.

d3d12_renderer.cppHLSL

■

Vulkan Backend

Vulkan renderer with KHR ray tracing, compute dispatch, and present pipeline. SPIR-V shader compilation. Live on Windows and Linux.

vulkan_renderer.cppGLSL/SPIR-V

■

Metal 4 Backend

Apple Silicon renderer on the Metal 4 API. MetalFX upscaling, hardware ray tracing, residency sets, and TBDR-aware pass ordering.

metal_renderer.cppMSL / Metal 4

■

GDK / D3D12X Backend

Xbox Series X|S renderer on the Microsoft GDK with D3D12X. Lifecycle, suspend/resume, user services, and console-tuned submission paths share the render graph with PC D3D12.

d3d12x_renderer.cppGDKHLSL SM6.6

■

Platform Layer

OS abstraction for window management, input, file I/O, and native dialogs. Windows, macOS, Xbox Series (GDK), and Linux implementations live; remaining consoles on the roadmap.

platform.hWin32CocoaGDKX11/Wayland

■

Future: NVN / AGC

Planned backends for Nintendo NVN (Switch 2) and Sony AGC (PS5). Same render graph, different execution path.

NVNAGC

Renderer Deep-Dive

Render Graph Pipeline

The main scene render graph compiles a DAG of passes into execution segments across Graphics, Compute, and PostGraphics lanes.

Stage 0

GPU Culling

Frustum + Hi-Z occlusion + backface meshlet culling on the compute queue. Builds indirect draw arguments.

→

Stage 1

Visibility Pass

GPU-driven draw of all visible meshlets via mesh shader. Writes 32-bit VisBuffer payload + depth per pixel.

→

Stage 2

Process VisBuffer

Compute pass decoding VisBuffer. Generates per-tile material classification lists and reconstructs barycentrics.

→

Stage 3

Shadow Generation

Raster cascaded shadow maps + hardware RT shadow rays. Both feed the same denoise/apply path.

→

Stage 4

GI Evaluation

TLRC screen probes, DDGI probe grid sampling, or RTXDI ReSTIR. Mode selected per frame from feature capabilities.

→

Stage 5

Deferred Texturing & Lighting

Bindless material evaluation per tile, then compute lighting (up to 256 punctual + IBL). Scene-color HDR write.

→

Stage 6

RT Reflections + SSR

Hardware RT reflections with temporal stabilization; raster SSR fallback honouring the same feature contract.

→

Stage 7

Denoise (NRD / Custom)

REBLUR/RELAX or custom temporal denoiser. Bypassed when DLSS Ray Reconstruction is selected as the denoise path.

→

Stage 8

GTAO + CMAA2

Ground-truth AO and morphological AA. Async-compute candidates that overlap with the graphics queue.

→

Stage 9

Temporal Resolve

TAA · DLSS-SR · DLSS-RR. Halton(2,3) jitter, neighborhood clamp, motion-vector reprojection.

→

Stage 10

Frame Generation

DLSS-FG or FSR3-FG (optional). Optical flow + motion vectors interpolate intermediate frames.

→

Stage 11

Tonemap + HDR Output

ACES Narkowicz / Hill / Khronos PBR Neutral / Reinhard. PQ encoding for HDR10 displays.

→

Stage 12

Editor & Present

Editor overlay composite, ImGui, dual-viewport comparison if active, swapchain present.

Visibility Buffer

32-Bit Payload Layout

Every pixel stores a single uint32 encoding the draw call, triangle, and meshlet that produced it.

Meshlet IDbits 20–31 (12 bits)

Triangle IDbits 12–19 (8 bits)

DrawCall IDbits 0–11 (12 bits)

8 B

Per Pixel (VisBuffer + Depth)

4,095

Max Draw Calls

255

Max Triangles / Meshlet

4,095

Max Meshlets

Data Flow

Scene Submission Pipeline

World

WorldRuntime → SceneGraph → GpuSceneBvh

Scene

SceneRenderableInstance → BindlessResourceTable → SceneBindlessSubmission

Render

RenderGraphBuilder → CompiledRenderGraph → ExecutionSegments

GPU

Graphics Queue Async Compute Copy Queue

Reference

Render Graph Pass Types

Pass	Kind	Queue	Description
`MeshletCull`	Compute	Async	Frustum + Hi-Z occlusion + backface culling, builds indirect args
`VisibilityPass`	Graphics	Main	GPU-driven meshlet draw, writes VisBuffer + depth
`ProcessVisibility`	Compute	Async	Decode VisBuffer, material tile classification
`AttributeInterpolation`	Compute	Async	Barycentric reconstruction, vertex attribute fetch
`DeferredTexturing`	Compute	Async	Bindless material/texture evaluation per tile
`RasterShadowMap`	Graphics	Main	Cascaded directional + per-light raster shadow maps
`RtShadows`	Compute	Main	Hardware ray-traced shadow rays, fed into denoise
`Tlrc`	Compute	Main	Temporal Light Radiance Cache: screen probes + reprojection
`Ddgi`	Compute	Main	Dynamic Diffuse Global Illumination probe-grid update + sample
`RtxdiResTIR`	Compute	Main	RTXDI ReSTIR direct illumination + path-tracing modes
`DeferredLighting`	Compute	Main	PBR lighting from material outputs → scene color (HDR)
`RtReflections`	Compute	Main	Hardware RT reflections with temporal stabilization
`RasterSsr`	Compute	Async	Screen-space reflections fallback path
`NrdDenoise`	Compute	Main	REBLUR/RELAX denoising of RT shadows + reflections + GI
`Gtao`	Compute	Async	Ground-truth ambient occlusion
`Cmaa2`	Compute	Async	Conservative morphological anti-aliasing
`TemporalAa`	Compute	Main	Halton-jittered TAA with neighborhood clamp
`DlssSr`	Compute	Main	NVIDIA DLSS Super Resolution / DLAA
`DlssRr`	Compute	Main	NVIDIA DLSS Ray Reconstruction (denoise + upscale)
`DlssFg`	Compute	Main	NVIDIA DLSS Frame Generation
`Fsr3Fg`	Compute	Main	AMD FidelityFX FSR3 Frame Generation
`Tonemap`	Compute	Main	ACES / Reinhard / Khronos PBR Neutral; PQ for HDR10
`EditorOverlay`	Graphics	Main	Gizmos, selection outlines, grid
`ImGuiComposite`	Graphics	Main	Editor UI composite
`PresentCopy`	Copy	Main	Final resolve to swapchain

Material System

GPU Material Flags