# Connected DX12 teaching samples

Independent C++20 teaching programs. These files are not verified QubicEngine repository implementation. Native compilation was not performed in the authoring Linux environment; use the Windows steps below to compile and validate them.

## Prerequisites

Windows 10/11, a DX12 device supporting Shader Model 6.0 (or `--warp`), Visual Studio 2022 with Desktop development with C++, a Windows 10/11 SDK, CMake 3.24+, and the Microsoft DirectX Shader Compiler (`dxc.exe`) on PATH. Enable the Windows Graphics Tools optional feature for the DX12 debug layer. Obtain DXC from its official repository: https://github.com/microsoft/DirectXShaderCompiler/releases . The compiler must be runnable, including its supplied DLLs.

## Build and run

Open **x64 Native Tools Command Prompt for VS 2022**, enter this directory, and run:

```text
dxc --version
cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Debug
build\Debug\qubic_triangle.exe
build\Debug\qubic_texture.exe
build\Debug\qubic_texture.exe "C:\images\color.png"
build\Debug\qubic_triangle.exe --warp
```

If `dxc.exe` is not on PATH, configure with `-DDXC_EXECUTABLE="C:\tools\dxc\bin\x64\dxc.exe"`. Keep the `shaders` directory generated next to the executables. Source shaders are compiled by CMake to Shader Model 6.0 DXIL.

`qubic_triangle` shows a color-interpolated triangle. `qubic_texture` shows a rotating indexed cube with a generated checker texture, or the WIC-decoded image you pass. Resize the window, minimize/restore it, and press Escape to exit. The texture has one mip level. Face brightness is a teaching tint, not a lighting model. These samples do not implement model-file import, a material system, or a production render graph.

## What is included

- Win32 class, window creation, message processing, launch, resize, and shutdown.
- Debug-layer enablement before device creation, hardware adapter selection, explicit WARP option, and shader-model check.
- Queue, flip-discard swap chain, RTV/SRV/DSV heaps, two frame allocators, command list, fence, and event.
- Complete root signature and pipeline state, offline DXC shaders, indexed geometry, viewport/scissor, and draw commands.
- Left-handed camera; row-vector, row-major matrices; root constants at b0, texture t0, sampler s0.
- WIC decode to RGBA8, dimensions validation, footprints, padded row copies, upload/default resources, texture copy, state transition, fence-safe staging retention, and SRV publication.
- Depth testing and linear-color shader output through an sRGB RTV; sRGB texture input.

Vertex and index buffers remain in upload heaps to keep the teaching path short. A production renderer copies static geometry into default heaps. Initialization waits once for texture upload; frame rendering uses per-slot fence completion and does not unconditionally flush every frame. Resize flushes because it replaces the swap-chain targets.

## Optional animation reference

`pose-reference.hpp` contains complete DirectXMath helpers for key sampling, quaternion blending, hierarchy evaluation, and row-major skin matrices. It is a reference extension and is not compiled by the two minimal targets. Validate importer contracts before using it. Native compilation of this extension is also unverified.

## Windows validation checklist

Build both targets in Debug and Release. Check Visual Studio Output for DX12 debug messages. Test generated checker, PNG/JPEG input, invalid filename, resizing, minimize/restore, and WARP. Confirm no allocator-reset or live-resource errors. Record adapter/driver and SDK/compiler versions when reporting a result. Native runtime and graphics output remain unverified until these checks run on Windows.

## References

https://learn.microsoft.com/en-us/windows/win32/direct3d12/creating-a-basic-direct3d-12-component
https://learn.microsoft.com/en-us/windows/win32/direct3d12/uploading-resources
https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-id3d12commandallocator-reset