Fix: macOS Metal Shader Converter SPV-Cross Warning

A cross-platform engine compiles HLSL → SPIR-V → MSL via spirv-cross for macOS. Warnings about “decorationOffset on sampler unaligned” appear; Metal renders subtly wrong on M-series GPUs.

Inspect Generated MSL

spirv-cross --msl shader.spv > shader.metal

Read the MSL. Check sampler bindings match what your engine expects to bind.

Explicit Sampler Bindings

// HLSL
Texture2D myTexture : register(t0);
SamplerState mySampler : register(s0);

float4 PSMain(...) : SV_TARGET {
    return myTexture.Sample(mySampler, uv);
}

Explicit register slots translate cleanly. Without them, spirv-cross assigns slots heuristically; mismatches with engine bindings cause subtle bugs.

Combined Samplers

For simpler cross-platform behavior, prefer combined image-samplers (GLSL sampler2D):

// GLSL
uniform sampler2D myTexture;

// Auto-translates to combined in MSL

Less precise than separate, but more portable. For most use cases (game shaders), the difference doesn’t matter.

Argument Buffer Hints

Metal can group resources in argument buffers. spirv-cross may emit either pattern. If your engine binds individual resources, use spirv-cross flags to force per-resource binding:

spirv-cross --msl --msl-no-resource-binding

Per-Texture Sampler Override

Some shader graphs need filtering that differs per texture. In MSL, define samplers per-call:

constexpr sampler linearSampler(mag_filter::linear, min_filter::linear);
float4 col = myTexture.sample(linearSampler, uv);

Faster and explicit; bypasses runtime sampler binding.

Verifying

Re-compile shaders. No warnings. Rendered scene matches reference on Vulkan/D3D12. Validation on Metal frame debugger shows correct sampler usage per texture.

“Cross-compile is lossy. Inspect output, lock down bindings explicitly, and verify on target hardware.”

For Apple Silicon especially, validate on M1 and M2 separately — minor MSL quirks differ across architectures.