Agfx Porting From D3d11

Recommended Porting Order

1. Decide raw AGFX vs. agfx::ez. If the D3D11 code is architecturally simple (single render loop, no deferred contexts, resources created ad hoc rather than pooled/tracked), porting to agfx::ez (using-agfx-ez) preserves the D3D11-like "immediate calls, no manual barrier bookkeeping for the common case" feel and is significantly less work. Reserve raw AGFX for engines that need explicit control the ez layer doesn't expose (custom barrier scheduling, more than one command buffer per frame, non-2D texture types).
2. Device, queue, swap chain. Wire up agfxDeviceCreate/agfxCommandQueueCreate/agfxSwapChainCreate (or agfx::ez::Context if using ez) and get a cleared back buffer presenting — validates build/link before any rendering logic moves over.
3. Frame pacing and fences (raw AGFX only — agfx::ez::Context does this internally). D3D11 had no fence concept to port; this is new code, not translated code. See agfx-synchronization.
4. Resources. Port ID3D11Buffer/ID3D11Texture2D creation to agfxBufferCreate/agfxTextureCreate (or agfx::ez::Context::CreateVertexBuffer/CreateTexture2D etc.). Drop Map/Unmap-per-frame dynamic-buffer patterns in favor of AGFX's ring-buffered constants if using ez, or a hand-rolled equivalent if using raw AGFX.
5. One render pass end-to-end. Convert one OMSetRenderTargets + draw sequence to an agfxRenderPassBegin/draw/End (agfx-render-targets-and-passes), including the barriers D3D11 never required (agfx-synchronization, or agfx::ez::Context::TransitionTexture/SetRenderTargets, which tracks this automatically for ez-created resources).
6. Shaders. Rewrite each HLSL shader's binding section: remove register(tN/bN/sN) slot declarations, replace with AGFX_PUSH_CONSTANTS + ResourceHandle fields and AGFXTexture2D/AGFXStructuredBuffer/AGFXSampler::Create(handle) calls, replace input-layout vertex fetch with vertex pulling from SV_VertexID (agfx-writing-bindless-shaders). A shader rewritten without its host-side push-constant struct updated in the same pass won't compile — do these together.
7. Remaining passes, then cross-cutting concerns: any stencil-dependent logic (unsupported — flag to the user), MSAA (check current AGFX support before assuming it maps), HDR/resize (agfx-presentation-and-swapchain). AGFX also offers mesh shaders, inline ray tracing, and multi-draw indirect, none of which D3D11 has — see "Advanced features" below if the port is also a modernization.

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

• Assuming the driver still tracks hazards. The single most common bug: D3D11 code has zero barrier calls because the driver inserted them implicitly. Every render-target-write → shader-read, and every UAV write ordered against another dispatch, needs an explicit barrier now (agfx-synchronization) — missing one doesn't fail to compile, it produces silently wrong or flickering output.
• Trying to preserve Map-every-frame dynamic buffer patterns 1:1. It still works (agfxBufferMap on a CPU_TO_GPU buffer), but without frame-in-flight fencing around it, per-frame constant writes race the GPU reading the previous frame's data — either drive it through agfx::ez's ring buffer or replicate that pattern by hand in raw AGFX.
• Leaving slot-based binding calls (PSSetShaderResources etc.) as dead code instead of deleting them along with the input layout and state objects — there's nothing on the AGFX side to bind to; delete outright rather than translate.
• Porting stencil logic. AGFX's pipeline depth state has no stencil fields. Flag any stencil-dependent D3D11 code to the user rather than silently dropping it.