Agfx Porting From Opengl

Recommended Porting Order

1. Decide raw AGFX vs. agfx::ez. GL's implicit global-state model is the closest thing AGFX has an equivalent for in agfx::ez (using-agfx-ez): immediate SetRenderTargets/SetPipeline/Draw calls, automatic-for-the-common-case barrier tracking, one-call texture/buffer creation. Recommend it unless the engine needs multithreaded command recording or resource types the ez layer doesn't cover.
2. Device, queue, swap chain. Wire up agfxDeviceCreate/agfxCommandQueueCreate/agfxSwapChainCreate (or agfx::ez::Context) and get a cleared back buffer presenting before porting any rendering logic — this also validates the build/link setup replacing GL context creation (GLFW/SDL/EGL/WGL) and function-pointer loading (GLAD/GLEW), which AGFX doesn't need.
3. NDC/depth-range and texture-origin fixes. Before porting shaders or texture uploads, decide how the engine's projection matrices and UV/texture-load code will be adjusted for AGFX's [0,1] depth range and top-left texture origin (both differ from GL's [-1,1]/bottom-left convention) — get this right once, early, rather than debugging it per-shader later.
4. Frame pacing and fences (raw AGFX only — agfx::ez::Context handles this internally). Most GL engines have nothing to port here since the driver paced frames implicitly; this is new code. See agfx-synchronization.
5. Resources. Port glGenTextures/glTexImage2D and glGenBuffers/glBufferData calls to agfxTextureCreate/agfxBufferCreate (or the agfx::ez::Context one-call equivalents). Delete VAO setup entirely — there's nothing to port it to.
6. One render pass end-to-end. Convert one FBO-bind-and-draw sequence to agfxRenderPassBegin/draw/End (agfx-render-targets-and-passes), adding the barriers GL never required by hand (agfx-synchronization, or agfx::ez::Context::SetRenderTargets/TransitionTexture for ez-tracked resources).
7. Shaders. Rewrite GLSL to HLSL per shader (not a source-level auto-translation — different language, different binding model): remove uniform/layout(binding=...) declarations, replace with AGFX_PUSH_CONSTANTS + ResourceHandle fields and AGFXTexture2D/AGFXStructuredBuffer/AGFXSampler::Create(handle) calls, replace VAO-driven vertex fetch with vertex pulling from SV_VertexID (agfx-writing-bindless-shaders). Port a shader and update its host-side push-constant struct together, not as separate passes.
8. Remaining passes, then cross-cutting: stencil-dependent logic (unsupported, flag it), MSAA (verify current AGFX support before assuming it maps), HDR/resize (agfx-presentation-and-swapchain).

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 inserts barriers. GL engines frequently have zero or near-zero glMemoryBarrier calls because drivers are lenient; porting that silence to AGFX produces missing barriers, not a compile error — every write-then-read across passes needs one explicitly (agfx-synchronization).
• Leaving the GL depth-range/texture-origin convention baked into shader math. Projection matrices tuned for [-1,1] NDC depth and UV math assuming a bottom-left texture origin will render with inverted or squashed depth and flipped textures on AGFX until adjusted for [0,1]/top-left.
• Trying to preserve bind-to-target calls (glBindTexture, glBindBuffer, glBindFramebuffer) as dead code alongside VAOs — delete them along with vertex attribute setup; there is nothing on the AGFX side to bind to.
• Porting GLSL source mechanically instead of rewriting to HLSL. Uniform/sampler declarations, matrix multiply order (GLSL is column-major by convention, HLSL row-major by default), and the binding model are different enough that a shader needs to be rewritten against agfx-writing-bindless-shaders, not transliterated keyword-by-keyword.
• Porting stencil-dependent logic. AGFX's pipeline depth state has no stencil fields — flag stencil-dependent GL code to the user rather than silently dropping it.