Agfx Porting From D3d12

Recommended Porting Order

Porting shader-and-binding code before device/resource plumbing compiles but can't be tested; the reverse order lets you validate incrementally against a triangle/simple scene before tackling the whole renderer.

1. Device, queue, swap chain. Get agfxDeviceCreate/agfxCommandQueueCreate/agfxSwapChainCreate wired up and clearing the back buffer to a solid color and presenting. This validates the build/link setup (see the repo's top-level README.md for libraries to link on each platform) before any rendering logic is ported.
2. Frame pacing and fences. Port the D3D12 fence/frame-in-flight loop to agfxFence + per-slot command buffers (agfx-synchronization). Do this before resource porting — later steps assume a working drain/wait mechanism, since resource creation/destruction during porting will otherwise race in-flight GPU work.
3. Resources. Port texture/buffer creation calls (CreateCommittedResource → agfxTextureCreate/agfxBufferCreate). Drop descriptor-heap-slot management entirely; keep the returned view handles instead.
4. One render pass end-to-end, e.g. a single G-buffer or forward pass: render target creation, barriers into the right states, agfxRenderPassBegin/draw/End (agfx-render-targets-and-passes). Get one pass rendering a real mesh with the actual shaders before porting the rest of the pipeline — this is where root-signature-to-bindless mistakes surface fastest.
5. Shaders. Rewrite each HLSL shader's binding section: remove register(t/b/u/s, spaceN) declarations tied to the old root signature, replace with AGFX_PUSH_CONSTANTS + ResourceHandle fields, replace register(t0)-style texture/buffer/sampler declarations with AGFXTexture2D/AGFXStructuredBuffer/AGFXSampler ::Create(handle) calls, replace input-assembler vertex fetch with vertex pulling from SV_VertexID (agfx-writing-bindless-shaders). Do this pass-by-pass alongside step 4, not as one giant shader-only pass — a shader rewritten without its host-side push-constant struct updated to match won't compile.
6. Remaining passes. Repeat steps 4–5 for every other render/compute pass in the engine.
7. Cross-cutting: HDR toggle, resize handling, mip generation, then mesh shaders / ray tracing / ExecuteIndirect — all supported as of v1.2.0; see "Advanced features" below for what maps and what doesn't.

Advanced features: mesh shaders, ray tracing, GPU-driven draws

All three are supported as of AGFX v1.2.0 (ray tracing landed in v1.1.0, multi-draw indirect in v1.2.0). Each is capability-gated — query once and keep the fallback path alive, since none are universal (in practice: Apple M3+, NVIDIA RTX 20+, AMD RX 6000+, or Intel Arc):

agfxDeviceInfo info = {};
agfxDeviceGetInfo(device, &info);
// info.supportsRayTracing / info.supportsMeshShaders / info.supportsMultiDrawIndirect

The one structural mismatch to flag early: AGFX supports inline ray tracing only — RayQuery/TraceRayInline from a compute shader. There is no ray-generation/any-hit/closest-hit pipeline, no hit groups, and no shader binding table. A source engine built around a ray-tracing pipeline needs those passes restructured into compute dispatches that trace inline and shade at the hit point themselves; that is a redesign, not a translation, and is worth surfacing to the user before starting.

Delegate the actual work: agfx-raytracing (acceleration structures, inline tracing), agfx-mdi (indirect bundles, GPU culling), agfx-writing-bindless-shaders (main_ms/main_as entry points, reflected group sizes) with agfx-render-targets-and-passes for agfxRenderPassDrawMesh.

Common Porting Pitfalls

• Trying to preserve the descriptor-heap-slot-management code. There's nothing to preserve — delete it. AGFX hands back a ResourceHandle at view-creation time; there's no caller-managed heap index arithmetic.
• Leaving a second root CBV in the shader. AGFX shaders only have register(b0) (push constants). Any additional per-frame/per-scene constant buffer must go through the "handle nested in push constants, loaded as a one-element AGFXStructuredBuffer" pattern in agfx-writing-bindless-shaders, not a second binding slot.
• Getting agglomerate backwards. It's silently correct on the D3D12 and Vulkan sides of a port (the flag is ignored there) and only breaks once the same code path is exercised on Metal — see agfx-synchronization before assuming a barrier port is done just because it builds and runs on Windows or Linux.
• Assuming DXR ports across as-is. Acceleration structures and ExecuteIndirect do map (see "Advanced features"), but AGFX has no ray-tracing pipeline — no DispatchRays, no shader binding table, no hit groups. An engine whose RT is built on an RTPSO needs those passes restructured into inline-RayQuery compute dispatches. Surface this early rather than discovering it mid-port.