Agfx Porting From Vulkan

Recommended Porting Order

Because Vulkan and AGFX share the same broad shape (explicit command buffers, explicit barriers, explicit fences), porting shader-and-binding code before device/resource plumbing is somewhat less risky here than for other source APIs — but still validate incrementally rather than attempting the whole renderer at once.

1. Device, queue, swap chain. Replace instance/physical-device/logical-device/queue creation with agfxDeviceCreate/agfxCommandQueueCreate, and VkSwapchainKHR setup with agfxSwapChainCreate. Get a cleared back buffer presenting before porting rendering logic — validates the build/link setup (no more Vulkan loader/extension/validation-layer bootstrapping).
2. Frame pacing and fences. Port the frame-in-flight fence/semaphore rotation to agfxFence + per-slot command buffers (agfx-synchronization) — if the engine already uses timeline semaphores this is close to a rename; if it uses binary semaphores + per-frame fences, consolidate onto AGFX's single monotonic-value fence model.
3. Resources. Port VkImage/VkBuffer (+ VMA/manual allocation) creation to agfxTextureCreate/agfxBufferCreate. Drop descriptor-set/descriptor-pool bookkeeping; keep the returned view/handle objects instead — see agfx-writing-bindless-shaders.
4. One render pass end-to-end. Convert one vkCmdBeginRenderPass/vkCmdBeginRendering sequence (with its layout transitions) to agfxRenderPassBegin/draw/End (agfx-render-targets-and-passes), including barriers into the right states beforehand (agfx-synchronization) — this is where descriptor-set-to-bindless mistakes surface fastest if the source wasn't already bindless.
5. Shaders. Rewrite each shader's binding section: remove layout(set=,binding=) descriptor declarations, replace with AGFX_PUSH_CONSTANTS + ResourceHandle fields and AGFXTexture2D/AGFXStructuredBuffer/AGFXSampler::Create(handle) calls, replace vertex-input-state fetch with vertex pulling from SV_VertexID (agfx-writing-bindless-shaders). Do this pass-by-pass alongside step 4 — a shader rewritten without its host-side push-constant struct updated in the same pass won't compile.
6. Remaining passes. Repeat steps 4–5 for every other render/compute pass.
7. Cross-cutting: any stencil-dependent logic (unsupported in AGFX — flag to the user), then mesh shaders / ray tracing / indirect draws — all supported as of v1.2.0; see "Advanced features" below. HDR/resize handling (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

• Trying to preserve descriptor set/pool/layout management. If the source is classic (non-bindless) Vulkan, there's real deletion work here, not just a rename — agfx-writing-bindless-shaders for the replacement pattern.
• Assuming agglomerate has a Vulkan equivalent. It doesn't — AGFX's own Vulkan backend ignores the flag entirely (barriers are always emitted via vkCmdPipelineBarrier2), so every AGFX barrier from a Vulkan port should generally pass agglomerate = true (ordinary transitions) to get Metal-side hazard tracking; see agfx-synchronization for the one exception (present-adjacent transitions).
• Assuming a Vulkan ray-tracing pipeline ports across. Acceleration structures and VK_KHR_ray_query map cleanly, but vkCmdTraceRaysKHR, RT pipeline stages, and the SBT have no AGFX equivalent — those passes must be restructured into inline-RayQuery compute dispatches. Surface this early. Indirect draws, by contrast, do port (see "Advanced features").
• Porting stencil-dependent logic (VK_FORMAT_D24_UNORM_S8_UINT-based effects, stencil-buffer masking). AGFX's pipeline depth state has no stencil fields — flag it rather than silently dropping it.
• Missing that AGFX's depth range already matches Vulkan's [0,1] and re-applying a GL-style depth-range fix that isn't needed, or missing a genuine Y-flip discrepancy between the source's off-screen-vs-swapchain convention and AGFX's own.