Engine

Early path tracing oriented engine prototype built on NRI.

Overview

• Supported graphics APIs: D3D12 and Vulkan
• Show runtime usage:
  • engine.exe --help
• Current runtime backend selection:
  • engine.exe --api d3d12
  • engine.exe --api vk
• Optional reconstruction backend selection:
  • engine.exe --reconstruction auto
  • engine.exe --reconstruction fsr
  • engine.exe --reconstruction dlss-rr
  • engine.exe --reconstruction nis
• Optional scene selection:
  • engine.exe --scene path/to/scene.gltf
  • engine.exe --scene path/to/scene.glb
• Current runtime state: the app can load a glTF scene into engine-owned CPU scene data, track glTF feature support stages in logs and UI, decode glTF images into GPU textures, upload scene buffers and textures to device memory, build scene BLAS / TLAS resources, publish scene resources plus the TLAS descriptor through the bindless heaps, run a compute-driven scene path tracing pass with progressive accumulation, compact half-float / scalar frame textures, stable current / previous camera state plus motion vectors, backend-aware guide writes, then drive an engine-owned ReconstructionRenderer over NRIUpscaler with guide preparation only for DLSS-RR / FSR before presenting through the fullscreen path
• Development notes, technical constraints, and the renderer roadmap live in AGENTS.md
• The glTF support roadmap lives in GLTF_SUPPORT_ROADMAP.md

Runtime Layout

• App owns SDL startup, startup scene resolution / loading, window creation, platform window handle extraction, the event loop, and resize / exposed-frame orchestration
• RendererDevice owns NRI device creation, interface loading, the graphics queue, the per-frame fence, and bindless heap setup
• Scene owns engine-side glTF ingestion with fastgltf, plus the current CPU scene, mesh, material, texture, and instance representation
• SceneResources owns GPU scene buffers, decoded scene textures, scene sampler descriptors, and bindless publication of engine scene data
• SceneAccelerationStructures owns engine-side BLAS / TLAS creation, the TLAS instance buffer, scratch resources, and bindless publication of the TLAS descriptor
• PathTracingRenderer owns the current compute path tracing pass, the broader frame-resource texture set, and dispatch recording
• ReconstructionRenderer owns capability-based primary reconstruction over NRIUpscaler, output texture management, backend selection / override, and upscaler dispatch recording
• SwapchainRenderer owns the swap chain, queued frame resources, the fullscreen presentation path, Dear ImGui integration, and render / present submission
• Main.cpp is intentionally kept thin and only handles command-line parsing plus app startup
• Tests/ owns lightweight regression coverage for engine-side invariants that should not regress between milestones

The engine now defaults to the in-repo sample scene at Scenes/MinimalTriangle.gltf when no --scene path is provided, and the repo also carries focused regression scenes for metallic response, layered alpha blend, texture transforms, normal maps, occlusion import, transmission and volume, and vertex colors. Geometry, mesh, material, and instance data are uploaded to GPU buffers, glTF textures are decoded into scene textures, static mesh BLAS objects are built, and an instance-buffer driven TLAS is created and published through the bindless heap during startup. Scene material parameters and material bindings now live in separate GPU buffers so the path tracer is not dependent on the older monolithic material layout. That scene data now drives the compute path tracing skeleton, including unfilteredRadiance, accumulationHistory, finalOutput, viewZ, normal+roughness, baseColor+metalness, motionVectors, diffuseAlbedo, specularAlbedo, specularHitDistance, and reconstructionNormal+roughness, with the extended DLSS-RR guides written only when the active backend actually consumes them. Primary reconstruction is capability-based: DLSS-RR is preferred when available, FSR is the cross-vendor baseline upscaler path, and NIS remains the simplest fallback. ReconstructionRenderer now owns a dedicated guide-preparation compute pass only for FSR / DLSS-RR, uses measured frame time for FSR, feeds linear infinite-depth guides to FSR / DLSS-RR, and consumes non-jittered motion vectors plus current / previous camera state from the path tracer. The frame-resource budget is now packed around R32_SFLOAT, R16_SFLOAT, and RGBA16_SFLOAT surfaces instead of using RGBA32_SFLOAT everywhere. The current milestone focus is still step 7: stabilizing that reconstruction path and its guide contracts before moving on to final composition.

glTF Support Snapshot

• Rendered end to end today: core metallic-roughness materials, emissive inputs, alpha mask, layered alphaMode: "BLEND", double-sided materials, TEXCOORD_1, KHR_texture_transform, normal maps, vertex colors, KHR_materials_specular, and baseline KHR_materials_transmission / KHR_materials_volume / KHR_materials_ior
• Imported and uploaded but not currently shaded: occlusionTexture is preserved and reported in the support matrix, but it is intentionally not multiplied into traced transport
• Explicitly unsupported or incomplete: EXT_mesh_gpu_instancing, glTF cameras, advanced material extensions such as clearcoat / sheen / iridescence / anisotropy / diffuse transmission, animation and deformation features, and compressed mesh / texture paths such as Draco, meshopt, and KTX2
• Visibility: the engine reports used glTF features as rendered, uploaded, imported, or unsupported in loader logs and the debug UI instead of silently degrading them

Startup Upload Path

• Scene ingestion uses fastgltf to build the engine-owned CPU scene model and glTF support summary
• PNG textures are decoded through libspng; other formats currently fall back to stb_image
• The startup path decodes only the base mip on CPU, streams base mips to the GPU, and generates higher mips on GPU through SceneGenerateMips.cs.hlsl
• SceneResources logs upload timing breakdowns so large-scene startup cost can be separated into parse, decode, upload, and mip-generation work

Frame Passes

• Scene upload and BLAS / TLAS build: startup-only engine passes owned by SceneResources and SceneAccelerationStructures, including streamed base-mip upload and GPU mip generation
• Path tracing: one compute dispatch in PathTracingRenderer that writes unfilteredRadiance, accumulationHistory, finalOutput, and the current guide set
• Reconstruction guide preparation: one compute dispatch in ReconstructionRenderer that sanitizes viewZ, albedo, hit-distance, and reconstruction-normal guides for FSR / DLSS-RR
• Primary reconstruction: one CmdDispatchUpscale call in ReconstructionRenderer
• Fullscreen present: one graphics pass in SwapchainRenderer using ProceduralFullscreen.* to tone-map and present the selected output texture
• ImGui: optional debug UI draw at the end of the fullscreen pass

Mode Routing

• --reconstruction auto: path tracing -> DLSS-RR if available, otherwise FSR, otherwise NIS, then fullscreen present
• --reconstruction dlss-rr: path tracing -> guide preparation -> DLSS-RR -> fullscreen present
• --reconstruction fsr: path tracing -> guide preparation -> FSR -> fullscreen present
• --reconstruction nis: path tracing -> NIS -> fullscreen present
• reconstruction unavailable or inactive: path tracing finalOutput -> fullscreen present
• path tracing unavailable: procedural fullscreen fallback in ProceduralFullscreen.fs.hlsl

On D3D12, native upscaler dispatch can temporarily bind a different descriptor heap / pool. ReconstructionRenderer now restores the engine bindless pool immediately after CmdDispatchUpscale, which prevents the live fullscreen present path from sampling the wrong heap state.

Regression Coverage

• SceneLoadTests verifies glTF support-stage reporting plus importer fidelity for BlendTransformTriangle, BlendLayeredTriangle, NormalOcclusionTriangle, TransmissionVolumeTriangle, and VertexColorTriangle
• engine_gpu_smoke verifies Vulkan DLSS-RR output for the blend, normal-map, transmission-volume, and vertex-color regression scenes, in addition to the older metallic and reconstruction coverage
• Capability-gated smoke tests use SKIP_RETURN_CODE 125, so unsupported D3D12 or FSR paths are reported as skipped instead of poisoning the whole suite

Build

• Use clang and clang++
• Build with Ninja Multi Config
• Install Windows Graphics Tools if you want D3D12 validation
• Set VULKAN_SDK so the build can find DXC
• Run ctest --test-dir Build -C Debug --output-on-failure after a Debug build to execute the current regression checks, including forced FSR / DLSS-RR GPU smokes on both D3D12 and Vulkan, glTF material regression scenes, raw reconstruction readback, and the fullscreen present path over the bindless output SRV

Goal

The target is a real-time path tracing engine with engine-owned scene and renderer systems, using NRISamples as low-level NRI reference material and NRD-Sample as the higher-level renderer architecture reference. The primary reconstruction target is DLSS-RR, with the renderer structured around a capability-based NRIUpscaler abstraction so simpler super-resolution backends and future reconstruction-class backends can be added later with minimal changes to the core path tracing pipeline.