[DRAFT] [DX/VK/MTL] SV_StencilRef + configurable stencil format (D24S8 / D32_FLOAT_S8X24) + StencilState plumbing

[alsepkow]

⚠️ DRAFT — not ready for pickup. Title still being refined; do not assign or start work yet.

Background

#1046 added depth (SV_Depth, Depth32 SRV) but no stencil. The body of #1046 mentions stencil and SV_StencilRef, however delivering it cleanly is well beyond the bare AC bullets:

• Format::D32FloatS8Uint already exists in the enum and is mapped to DXGI_FORMAT_D32_FLOAT_S8X24_UINT / VK_FORMAT_D32_SFLOAT_S8_UINT / MTL::PixelFormatDepth32Float_Stencil8, but PipelineDesc.DSFormat = Format::D32FloatS8Uint; is hardcoded in lib/API/{DX,VK,MTL}/Device.cpp — there's no YAML hook to choose stencil vs. depth-only, and D24_UNORM_S8_UINT is missing entirely.
• No StencilState struct exists in shared include/Support/Pipeline.h — stencil func / mask / read-mask / write-mask / front/back op are not plumbed through YAML or PSO desc.
• No call site for OMSetStencilRef (DX) / setStencilReferenceValue (MTL) / vkCmdSetStencilReference (VK).
• Only a depth readback path exists today — stencil readback is missing.
• SV_StencilRef requires the PSSpecifiedStencilRefSupported capability (FL 11_1) — needs a lit feature like SV_StencilRef-tier and a runtime capability check.

Originally added as an AC on #1046 (2026-06-01) and reverted later the same day after scope analysis: the work spans 5+ shared-header + 3-backend touch-points + a new capability gate + a new test (>3 days), large enough to warrant its own tracker so #1046 can close cleanly on the SV_Depth deliverable.

Acceptance criteria

• Add Format::D24UnormS8Uint to include/API/Resources.h (enum + all 5 helper switches: getElementSize, getDataFormat, getNumChannels, isDepthFormat, isStencilFormat).
• Map D24UnormS8Uint → DXGI_FORMAT_D24_UNORM_S8_UINT (and SRV DXGI_FORMAT_R24_UNORM_X8_TYPELESS for depth read, DXGI_FORMAT_X24_TYPELESS_G8_UINT for stencil read) in lib/API/DX/DXResources.h.
• Map D24UnormS8Uint → VK_FORMAT_D24_UNORM_S8_UINT in lib/API/VK/VKResources.h; MTL falls back to Depth32Float_Stencil8 with a TODO.
• Make DSFormat configurable via YAML (extend Pipeline.h::PipelineDesc + the YAML parser).
• Add StencilState struct to shared Pipeline.h (func + mask + read/write mask + front/back op + ref).
• Wire stencil state into the DX D3D12_DEPTH_STENCIL_DESC / VK VkPipelineDepthStencilStateCreateInfo / MTL MTLDepthStencilDescriptor.
• Add OMSetStencilRef / vkCmdSetStencilReference / setStencilReferenceValue call site (using the runtime ref from YAML).
• Add a stencil readback path mirroring DSReadback.
• Capability-gate SV_StencilRef lit feature (D3D12_FEATURE_DATA_D3D12_OPTIONS::PSSpecifiedStencilRefSupported).
• Add a graphics-pipeline test: PS writes SV_StencilRef, framework reads the stencil aspect and verifies.

Notes

• Estimated 3–5 days.

Refs #1046, llvm/wg-hlsl#400.