Agfx Writing Bindless Shaders

AGFX Bindless HLSL Shaders

Overview

AGFX shaders are HLSL (SM 6.6), compiled with DXC to a per-platform target: DXIL on Windows (agfx_shader_compiler_windows.cpp); DXIL then translated to Metal IR via the Metal shader converter on macOS (agfx_shader_compiler_mac.mm, using IRRootSignatureFlagSamplerHeapDirectlyIndexed | IRRootSignatureFlagCBVSRVUAVHeapDirectlyIndexed); SPIR-V on Linux (agfx_shader_compiler_linux.cpp, DXC's -spirv target via a dlopen'd libdxcompiler.so — path settable through agfxShaderCompilerOptions::dxCompilerPath, defaulting to data/dlls/libdxcompiler.so). Every target is fully bindless, direct-indexed heaps. The compiler defines AGFX_METAL on macOS and AGFX_VULKAN on Linux automatically; data/shaders/agfx.h uses these to hide the per-backend differences (e.g. [[vk::push_constant]]), so shader authors never branch on them for ordinary resource access. There is no per-draw descriptor table, no register(t0, space0) binding model, and no Bind* API on the C side beyond push constants. Every resource a shader touches — textures, buffers, samplers — is accessed by a ResourceHandle (a plain uint index) pulled out of ResourceDescriptorHeap/SamplerDescriptorHeap and wrapped in one of the AGFX* helper classes declared in data/shaders/agfx.h.

The host side hands shaders these handles two ways: almost always via push constants (agfxRenderPassPushConstants/agfxComputePassPushConstants, bound at register(b0)), or, for structured scene/per-draw constant data, by putting the handle to a constant buffer inside the push constants and loading it as an AGFXStructuredBuffer in the shader (see sceneCB pattern below) rather than a second root CBV.

Ownership

Owns:

• The bindless resource-access pattern: ResourceHandle, AGFXTexture1D/2D/2DArray/3D/Cube<T>, AGFXRWTexture1D/2D/3D<T>, AGFXStructuredBuffer<T>/AGFXRWStructuredBuffer<T>, AGFXByteAddressBuffer/AGFXRWByteAddressBuffer, AGFXSampler/AGFXComparisonSampler, AGFXRaytracingAccelerationStructure
• Push constants: AGFX_PUSH_CONSTANTS(type, name) at register(b0) (a [[vk::push_constant]] block on Vulkan — the macro hides it), and the optional per-draw ID (AGFX_DECLARE_DRAW_ID()/AGFX_DRAW_ID(): register(b1) on D3D12/Metal, the SPIR-V DrawIndex builtin on Vulkan), which is how a shader replayed from an indirect bundle recovers which draw it is — but note the value's meaning diverges on Vulkan, see agfx-mdi
• Entry point / stage conventions (main_vs, main_ps, main_cs, main_ms, main_as) and matching agfxShaderModuleType
• agfxShaderCompilerOptions/agfxShaderCompilerResult and agfxCompileShader — the HLSL → DXIL (Windows) / Metal IR (macOS) / SPIR-V (Linux) pipeline
• Wiring compiled agfxShaderModules into agfxRenderPipelineCreateInfo/agfxComputePipelineCreateInfo

Doesn't own:

• Render pass/attachment setup the pipeline is later bound and drawn within → agfx-render-targets-and-passes
• Barriers needed before a shader can safely read/write a resource (state transitions, UAV hazard barriers) → agfx-synchronization
• The AGFXIndirectDraw*Bundle append helpers declared in the same header (Create/Draw/DrawIndexed/DrawMesh/Dispatch) and the GPU-driven submission model around them → agfx-mdi
• Swap chain / back buffer acquisition → agfx-presentation-and-swapchain

References

The bindless helper header is a single shared file at data/shaders/agfx.h, included by every shader in the repo as #include "data/shaders/agfx.h" (a repo-root-relative path, not relative to the including shader) — always #include it first in a new shader and read it before inventing a new resource-access pattern; it is the complete list of what's available. Real shader examples: data/shaders/demo/gbuffer.hlsl (vertex+fragment, structured vertex pulling, textures+sampler), data/shaders/demo/gbuffer_indirect.hlsl (the GPU-driven variant, split into its own file for the Vulkan push-constant rule below), data/shaders/demo/ssao.hlsl (compute, RW texture output, scene CB), data/shaders/demo/mipgen.hlsl (minimal compute), data/shaders/demo/deferred_lighting.hlsl, data/shaders/demo/shadow_depth.hlsl, data/shaders/demo/tonemap.hlsl, data/shaders/demo/imgui.hlsl. Host-side compile+load pattern: agfx_demo/deferred_renderer.cpp's CompileShader helper, agfx_demo/ssao.cpp, agfx_demo/agfx_mipgen.cpp. Compiler internals: agfx_shader/agfx_shader_compiler.h and the per-platform agfx_shader_compiler_windows.cpp/_mac.mm/_linux.cpp.

Design Patterns

Minimal shader skeleton

#include "data/shaders/agfx.h"   // one shared header for all shaders; path is repo-root-relative

struct MyPushConstants {
    ResourceHandle someTex;
    ResourceHandle someSampler;
    ResourceHandle sceneCB;
    float someScalar;
};

AGFX_PUSH_CONSTANTS(MyPushConstants, g_Constants);

AGFX_PUSH_CONSTANTS expands to ConstantBuffer<type> name : register(b0) — this is the only resource binding declaration a shader normally needs. Everything else is created inline from a ResourceHandle field on that struct.

Reading resources: create-from-handle, then use

AGFXTexture2D<float4> albedoTex = AGFXTexture2D<float4>::Create(g_Constants.albedoTex);
AGFXSampler samp = AGFXSampler::Create(g_Constants.textureSampler);
float4 c = albedoTex.Sample(samp, uv);

AGFXRWTexture2D<float4> aoOut = AGFXRWTexture2D<float4>::Create(g_Constants.aoTex);
aoOut.Store(int2(id.xy), float4(ao, ao, ao, 1.0f));

AGFXStructuredBuffer<SceneVertex> vertices = AGFXStructuredBuffer<SceneVertex>::Create(g_Constants.vertexBuffer);
SceneVertex v = vertices.Load(vertexID);

Pick the wrapper by both dimensionality and read/write need: AGFXTexture2D<T> (read-only, sampled) vs AGFXRWTexture2D<T> (read/write, Load/Store only, no filtering) — matching AGFX_TEXTURE_USAGE_SAMPLED vs AGFX_TEXTURE_USAGE_STORAGE on the host-side agfxTextureCreateInfo. Use AGFXStructuredBuffer<T> for typed per-element buffer reads (scene constants, vertex pulling) and AGFXByteAddressBuffer/AGFXRWByteAddressBuffer for raw/untyped access — matching AGFX_BUFFER_VIEW_TYPE_STRUCTURED vs AGFX_BUFFER_VIEW_TYPE_RAW host-side.

Scene/per-frame constants: no second CBV — nest a handle in push constants

There is no root-level CBV beyond b0's push constants. To pass a larger, per-frame constant buffer, put its ResourceHandle as a field in the push-constant struct and load it as a one-element AGFXStructuredBuffer inside the shader:

struct GBufferSceneConstants { float4x4 viewProj; };
struct GBufferPushConstants {
    float4x4 worldMatrix;
    ResourceHandle sceneCB;
    // ...
};
AGFX_PUSH_CONSTANTS(GBufferPushConstants, g_Constants);

vs_out main_vs(uint vertexID : SV_VertexID) {
    AGFXStructuredBuffer<GBufferSceneConstants> sceneCB = AGFXStructuredBuffer<GBufferSceneConstants>::Create(g_Constants.sceneCB);
    GBufferSceneConstants scene = sceneCB.Load(0);
    // ...
}

Host side, this sceneCB handle comes from agfxBufferViewGetHandle on an agfxBufferView created with AGFX_BUFFER_VIEW_TYPE_CONSTANT (or STRUCTURED, since the shader reads it as a structured buffer either way) over an upload-heap agfxBuffer.