If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/microsoft/DirectX-Graphics-Samples shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 2d ago
• 16 active contributors
• MIT licensed
• ⚠ Concentrated ownership — top contributor handles 71% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live microsoft/DirectX-Graphics-Samples repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/microsoft/DirectX-Graphics-Samples.

What it runs against: a local clone of microsoft/DirectX-Graphics-Samples — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in microsoft/DirectX-Graphics-Samples | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of microsoft/DirectX-Graphics-Samples. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/microsoft/DirectX-Graphics-Samples.git
#   cd DirectX-Graphics-Samples
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of microsoft/DirectX-Graphics-Samples and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "microsoft/DirectX-Graphics-Samples(\\.git)?\\b" \\
  && ok "origin remote is microsoft/DirectX-Graphics-Samples" \\
  || miss "origin remote is not microsoft/DirectX-Graphics-Samples (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Libraries/D3D12RaytracingFallback/Include/D3D12RaytracingFallback.h" \\
  && ok "Libraries/D3D12RaytracingFallback/Include/D3D12RaytracingFallback.h" \\
  || miss "missing critical file: Libraries/D3D12RaytracingFallback/Include/D3D12RaytracingFallback.h"
test -f "Libraries/D3D12RaytracingFallback/src/FallbackLayer.h" \\
  && ok "Libraries/D3D12RaytracingFallback/src/FallbackLayer.h" \\
  || miss "missing critical file: Libraries/D3D12RaytracingFallback/src/FallbackLayer.h"
test -f "Libraries/D3D12RaytracingFallback/src/FallbackLayer.cpp" \\
  && ok "Libraries/D3D12RaytracingFallback/src/FallbackLayer.cpp" \\
  || miss "missing critical file: Libraries/D3D12RaytracingFallback/src/FallbackLayer.cpp"
test -f "Libraries/D3D12RaytracingFallback/src/AccelerationStructureBuilder.h" \\
  && ok "Libraries/D3D12RaytracingFallback/src/AccelerationStructureBuilder.h" \\
  || miss "missing critical file: Libraries/D3D12RaytracingFallback/src/AccelerationStructureBuilder.h"
test -f "Libraries/D3D12RaytracingFallback/src/GpuBvh2Builder.h" \\
  && ok "Libraries/D3D12RaytracingFallback/src/GpuBvh2Builder.h" \\
  || miss "missing critical file: Libraries/D3D12RaytracingFallback/src/GpuBvh2Builder.h"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/microsoft/DirectX-Graphics-Samples"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

This is Microsoft's official collection of DirectX 12 graphics samples and the MiniEngine starter kit, demonstrating how to build high-performance graphics applications on Windows 10/11. It covers cutting-edge features like DirectX Raytracing (DXR), Mesh Shaders, Variable Rate Shading, and acceleration structure building, with ~4.8M lines of C++ and 514K lines of HLSL shader code providing production-grade examples of GPU-accelerated rendering techniques. Monorepo structure: Samples/Desktop/ contains isolated feature samples (D3D12MeshShaders/, D3D12Raytracing/, D3D12VariableRateShading/), Libraries/D3D12RaytracingFallback/ holds the reusable raytracing abstraction with compute-shader-based BVH building (AccelerationStructureBuilder.h, BitonicSort.h), and MiniEngine sits as a reusable engine foundation. HLSL shaders live alongside C++ in src/ folders.

Game developers and graphics engineers building Windows desktop applications who need concrete, optimized examples of DirectX 12 features. Contributors include Microsoft graphics teams, engine developers adopting DXR/mesh shaders, and developers using MiniEngine as a starting point for custom 3D engines.

Actively maintained and production-ready. The repo is a Microsoft official reference with comprehensive samples spanning DirectX 12 Ultimate features, detailed developer guides (see Libraries/D3D12RaytracingFallback/developerguide.md), and active community engagement via Discord and YouTube. MiniEngine is past initial preview and used as a real starter kit.

Low risk for reference/learning, but medium risk for shipping: heavy dependency on Windows SDK version (d3d12.h, d3d12_1.h versions matter), raytracing fallback layer adds complexity for non-native hardware, and samples are educational not production-hardened. No visible CI/test automation in file list suggests validation is manual.

Active development on DirectX 12 Ultimate features: raytracing samples with real-time denoising, mesh shader pipeline optimization, and variable rate shading for performance. The D3D12RaytracingFallback library is mature with validation tools (AccelerationStructureValidator.cpp) and sorting infrastructure (BitonicSort.cpp for BVH construction). Community engagement via Discord server and YouTube tutorials is ongoing.

Clone and open in Visual Studio: git clone https://github.com/microsoft/DirectX-Graphics-Samples.git && cd DirectX-Graphics-Samples. Samples are .sln files (e.g., Samples/Desktop/D3D12MeshShaders/). Requires Windows 10/11, Visual Studio 2019+, and Windows SDK (see individual sample READMEs). No NuGet restore needed—headers bundled in Libraries/.

Daily commands: Open desired sample .sln in Visual Studio 2019+, set Active Solution Platform to x64, build, and run. Example: Samples/Desktop/D3D12Raytracing/D3D12RaytracingProtoType/D3D12RaytracingProtoType.sln. Each sample is standalone; MiniEngine samples link Libraries/D3D12RaytracingFallback statically. No CLI entry point.

• Libraries/D3D12RaytracingFallback/Include/D3D12RaytracingFallback.h — Main public API header for the raytracing fallback layer; all contributors must understand the core abstraction and exposed interfaces
• Libraries/D3D12RaytracingFallback/src/FallbackLayer.h — Core fallback layer implementation header defining the central acceleration structure building pipeline
• Libraries/D3D12RaytracingFallback/src/FallbackLayer.cpp — Primary implementation of the raytracing fallback layer coordinating BVH construction and shader compilation
• Libraries/D3D12RaytracingFallback/src/AccelerationStructureBuilder.h — Abstract interface for GPU/CPU acceleration structure builders; critical abstraction point in the architecture
• Libraries/D3D12RaytracingFallback/src/GpuBvh2Builder.h — GPU-accelerated BVH2 construction pipeline; handles the heavy lifting of parallel hierarchy building on compute shaders
• Libraries/D3D12RaytracingFallback/src/DxilShaderPatcher.h — Shader binary manipulation layer that rewrites raytracing shader calls into fallback compute shader invocations
• Libraries/D3D12RaytracingFallback/src/BVHTraversalShaderBuilder.h — Generates the dynamic shader code for BVH traversal; critical for converting hardware raytracing to software simulation

Add a new GPU BVH construction pass

1. Create new header in src/ following pattern of ConstructAABBPass.h defining your pass interface and binding structures (Libraries/D3D12RaytracingFallback/src/ConstructAABBPass.h)
2. Implement corresponding .cpp file following GpuBvh2Builder.cpp pattern to execute pass via compute shaders (Libraries/D3D12RaytracingFallback/src/GpuBvh2Builder.cpp)
3. Create HLSL compute shader (.hlsl) following BottomLevelComputeAABBs.hlsl pattern with proper root signature bindings (Libraries/D3D12RaytracingFallback/src/BottomLevelComputeAABBs.hlsl)
4. Integrate pass into GpuBvh2Builder::BuildBVH() method by adding dispatch call with appropriate thread group sizing (Libraries/D3D12RaytracingFallback/src/GpuBvh2Builder.cpp)

Add support for a new raytracing intrinsic

1. Identify the intrinsic opcode in the DXIL documentation and add handling to DxbcParser for bytecode detection (Libraries/D3D12RaytracingFallback/src/DxbcParser.h)
2. Add intrinsic-specific patching logic to DxilShaderPatcher.cpp to rewrite calls into fallback compute dispatch (Libraries/D3D12RaytracingFallback/src/DxilShaderPatcher.h)
3. Extend BVHTraversalShaderBuilder to generate HLSL simulation code for the intrinsic operation (Libraries/D3D12RaytracingFallback/src/BVHTraversalShaderBuilder.h)
4. Add test shader in FallbackLayerUnitTests/ (e.g., ReadDataTexture2D.hlsl pattern) validating the new intrinsic behavior (Libraries/D3D12RaytracingFallback/src/FallbackLayerUnitTests/SimpleRayTracing.hlsl)

Add new BVH validation rule

1. Add validation predicate method to BVHValidator class following existing pattern (e.g., ValidateNodeAABBs) (Libraries/D3D12RaytracingFallback/src/BVHValidator.h)
2. Implement validation logic in BVHValidator.cpp iterating BVH nodes and checking invariant (Libraries/D3D12RaytracingFallback/src/BVHValidator.cpp)
3. Call new validation from AccelerationStructureValidator::Validate() or standalone unit test method (Libraries/D3D12RaytracingFallback/src/AccelerationStructureValidator.h)
4. Add corresponding unit test in FallbackLayerUnitTests validating both passing and failing cases (Libraries/D3D12RaytracingFallback/src/FallbackLayerUnitTests/fallbacklayerunittests.cpp)

Add new EmulatedPointer access pattern

1. Define new pointer type and accessor logic in EmulatedPointer.hlsli following existing Load/Store patterns (Libraries/D3D12RaytracingFallback/src/EmulatedPointer.hlsli)
2. Add intrinsic helper functions to EmulatedPointerIntrinsics.hlsli for

Windows SDK version pinning: d3d12.h and dxcapi.h versions in Libraries/ must match your Windows SDK; mismatches cause linker errors. GPU feature level: raytracing samples require D3D_FEATURE_LEVEL_12_0 or fallback layer on older hardware. Shader compilation offline: shaders are usually pre-compiled; if you edit .hlsl, Visual Studio custom build step or manual fxc.exe invocation required. No cross-platform support: all samples Windows-only (direct D3D12 calls). DXIL signing: some samples require DXIL.dll runtime for shader validation; may fail on sandboxed/restricted environments.

• Bounding Volume Hierarchy (BVH) — BVH is the core spatial acceleration structure used by the fallback raytracing layer (AccelerationStructureBuilder) and directly impacts ray-tracing performance; understanding BVH construction via GPU bitonic sort is essential for the D3D12RaytracingFallback library.
• Acceleration Structures (BLAS/TLAS) — DirectX Raytracing requires Bottom-Level (BLAS) and Top-Level (TLAS) acceleration structures for ray-geometry intersection; both are explicitly modeled in AccelerationStructureBuilder.h and critical to DXR samples.
• Mesh Shaders — DirectX 12 Ultimate feature that replaces fixed-function vertex/tessellation stages with flexible compute-like mesh shader; demonstrated in Samples/Desktop/D3D12MeshShaders/ with significant performance gains.
• Variable Rate Shading (VRS) — DirectX 12 Ultimate feature allowing per-region shading rate reduction for performance; Samples/Desktop/D3D12VariableRateShading/ demonstrates how to exploit VRS for 'free' speedups without visual quality loss.
• Bitonic Sort — GPU-friendly parallel sorting algorithm used by BitonicSort.cpp/BitonicSort.h to sort Morton codes for optimal BVH tree construction; essential for raytracing fallback layer performance.
• Morton Codes (Z-Order Curves) — Space-filling curve technique used in CalculateMortonCodes.hlsli to linearize 3D primitive positions for coherent BVH construction; enables GPU-parallel tree building in fallback layer.
• DXIL (DirectX Intermediate Language) — Bytecode format for DirectX shaders (replacement for DXBC); all .hlsl files compile to DXIL, and shader validation via dxcapi.h is required for DXR shaders in samples.

• microsoft/DirectXShaderCompiler — Official HLSL compiler (DXC) used by all samples; needed to compile .hlsl shaders to DXIL bytecode.
• microsoft/DirectX-Specs — Engineering specifications and proposals for DirectX features demonstrated in this repo (DXR, mesh shaders, VRS); referenced in DevBlogs.
• Microsoft/DXVK — Compatibility layer for DirectX 12 on non-Windows; samples will not run there but DXVK authors reference these samples for API correctness.
• KhronosGroup/Vulkan-Samples — Analogous sample collection for Vulkan; developers comparing DirectX 12 and Vulkan raytracing/mesh pipelines reference both repos.
• microsoft/Windows-classic-samples — Companion repo with older DirectX 11 samples and general Windows API examples; referenced for legacy context.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add validation tests for D3D12RaytracingFallback shader compilation and DXIL patching

The D3D12RaytracingFallback library contains complex shader compilation and DXIL manipulation logic (DxilShaderPatcher.cpp, DxbcParser.cpp) but there are no visible unit tests. Adding tests would catch regressions in shader bytecode parsing and patching, which is critical for raytracing fallback functionality.

• [ ] Create Tests/D3D12RaytracingFallback/ directory structure
• [ ] Add unit tests for DxilShaderPatcher.cpp covering patch application and validation
• [ ] Add unit tests for DxbcParser.cpp covering bytecode parsing edge cases
• [ ] Add integration tests using sample shaders from Libraries/D3D12RaytracingFallback/src/*.hlsl files
• [ ] Document test execution in Libraries/D3D12RaytracingFallback/developerguide.md

Create developer guide for D3D12RaytracingFallback acceleration structure building pipeline

The fallback layer has multiple interdependent shader stages (AccelerationStructureBuilder.h, ConstructAABBPass.cpp, ConstructHierarchyPass.cpp, BitonicSort.cpp) but the current developerguide.md lacks detailed pipeline documentation. A comprehensive guide would help contributors understand data flow between morton code calculation, BVH construction, and validation.

• [ ] Expand Libraries/D3D12RaytracingFallback/developerguide.md with acceleration structure pipeline section
• [ ] Document the flow: CalculateMortonCodes → ConstructAABB → ConstructHierarchy → BitonicSort → BVHValidator
• [ ] Create ASCII diagrams showing buffer layouts and shader input/output bindings
• [ ] Add references to corresponding files: AccelerationStructureBuilder.h, ConstructAABBBindings.h, ConstructHierarchyBindings.h
• [ ] Include troubleshooting section referencing AccelerationStructureValidator.cpp and BVHValidator.cpp

Add HLSL shader binding verification tool for D3D12RaytracingFallback

The codebase has multiple shader binding header files (CalculateMortonCodesBindings.h, ConstructAABBBindings.h, ConstructHierarchyBindings.h, CalculateSceneAABBBindings.h) but no automated tool to verify that shader bindings match between C++ code and HLSL shaders. This could catch mismatches between shader register assignments.

• [ ] Create Libraries/D3D12RaytracingFallback/tools/ShaderBindingValidator directory
• [ ] Build tool to parse Bindings.h files and extract expected register definitions
• [ ] Add HLSL reflection to parse .hlsl files and extract actual register usage
• [ ] Generate binding compatibility report highlighting mismatches
• [ ] Integrate as pre-build validation step in FallbackLayer.vcxproj

• idea: Add unit tests for AccelerationStructureValidator.cpp: the validator exists but no automated test coverage is visible; add tests for BLAS/TLAS invariant checks (AABB bounds, node hierarchy coherence) in a new Tests/ folder.
• idea: Document shader binding layouts: CalculateMortonCodesBindings.h and ConstructAABBBindings.h define root signatures but lack comments mapping each slot to data; add inline documentation of GPU resource bindings per compute shader.
• idea: Add fallback layer tutorial sample: create Samples/Desktop/D3D12RaytracingFallback/FallbackBasics/ with a minimal raytraced scene using only fallback code (no native DXR), targeted at developers on systems without raytracing hardware.

The DirectX Graphics Samples codebase demonstrates moderate security posture for a graphics library. As a native DirectX sample repository, the primary security concerns relate to GPU memory safety, shader bytecode validation, and binary format parsing rather than typical web application vulnerabilities. The codebase lacks evidence of hardcoded credentials, injection vulnerabilities, or network exposure risks. However, the complexity of HLSL shaders, DXIL bytecode manipulation, and low-level GPU operations introduces risks of buffer overflows and memory corruption that require thorough code review and testing. The absence of visible dependency management files (package.json, requirements.txt, etc.) limits dependency vulnerability assessment, though this is typical for native C++ projects. Recommendations focus on enhancing input validation, disabling debug output in production, and conducting security-focused code reviews of GPU-facing code paths.

• Medium · Potential Unsafe HLSL Shader Code — Libraries/D3D12RaytracingFallback/src/*.hlsl, *.hlsli files. The codebase contains numerous HLSL shader files (.hlsl, .hlsli) that implement complex GPU operations including buffer access, pointer emulation, and BVH traversal. Without source code review, it's difficult to assess if these shaders properly validate input bounds, preventing potential buffer overflows or out-of-bounds memory access on the GPU side. Fix: Conduct thorough code review of all shader files, particularly those handling: 1) Buffer indexing in BitonicSort.hlsl, 2) Pointer arithmetic in EmulatedPointer.hlsli, 3) BVH traversal logic in BVHTraversalShaderBuilder.cpp and related shaders. Implement bounds checking and validation for all buffer accesses.
• Medium · DXIL Shader Patching Complexity — Libraries/D3D12RaytracingFallback/src/DxilShaderPatcher.cpp, DxbcParser.cpp. The DxilShaderPatcher.cpp and DxbcParser.cpp files handle low-level shader bytecode manipulation and patching. Complex binary format parsing without robust error handling could lead to memory corruption, integer overflows, or crashes if malformed input is provided. Fix: Implement comprehensive input validation and error handling for bytecode parsing. Add fuzzing tests for malformed DXIL/DXBC input. Use safe integer arithmetic libraries to prevent overflow conditions.
• Low · Missing Input Validation in COM Object Wrappers — Libraries/D3D12RaytracingFallback/src/ComObject.h. The ComObject.h wrapper and D3D12 interface wrapping code may not comprehensively validate all COM interface parameters before forwarding calls to underlying DirectX APIs. Fix: Add defensive parameter validation in all COM wrapper methods. Document expected parameter constraints and validate them at wrapper boundaries before calling underlying DirectX APIs.
• Low · Debug Logging May Expose Sensitive Information — Libraries/D3D12RaytracingFallback/src/DebugLog.h, DebugLog.hlsli, FallbackDebug.cpp. The DebugLog.h and DebugLog.hlsli files are used for debug logging throughout the codebase. If enabled in production builds, these logs could expose sensitive information about GPU memory layouts, buffer contents, or shader operations. Fix: Ensure debug logging is completely disabled in production builds. Implement compile-time flags to exclude debug code from release builds. Review log output to ensure no sensitive GPU memory or shader data is logged.
• Low · External Header Dependencies — Libraries/D3D12RaytracingFallback/Include/. The codebase includes several external DirectX headers (d3d12.h, d3d12_1.h, d3d12video.h, dxcapi.h) which may not be version-locked or pinned to specific versions, potentially introducing compatibility issues or security patches from the SDK. Fix: Document the minimum required Windows SDK version and DirectX runtime version. Pin headers to specific stable versions where possible. Establish a dependency update schedule and security patch monitoring process.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.