Help us improve
Share bugs, ideas, or general feedback.
From game-porting-skills
Compiles DXIL/HLSL to metallib using Metal shader converter CLI or libmetalirconverter at runtime. Covers offline and runtime compilation, root signatures, reflection, ray tracing, and emulation.
npx claudepluginhub apple/game-porting-toolkit --plugin game-porting-skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/game-porting-skills:compiling-with-metal-shaderconverterThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Two modes: **CLI** (`metal-shaderconverter`) for offline/build-time compilation, **library** (`libmetalirconverter` C API) for runtime compilation. Both produce metallibs consumed by the Metal framework. Use the CLI for build pipelines and asset cooking; use the library when DXIL must be compiled at runtime (e.g., an engine that ships DXIL and compiles to metallib on first load).
Integrates Metal shader converter (MSC) shaders at runtime: binding model, TLAB layout, root signatures, descriptor/sampler heaps, static samplers, bindless resources, vertex fetch, geometry/tessellation emulation, compute dispatch, unbounded arrays, and append/consume buffers.
Creates p5.js generative art with seeded randomness, noise fields, and interactive parameter exploration. Use for algorithmic art, flow fields, or particle systems.
Share bugs, ideas, or general feedback.
Two modes: CLI (metal-shaderconverter) for offline/build-time compilation, library (libmetalirconverter C API) for runtime compilation. Both produce metallibs consumed by the Metal framework. Use the CLI for build pipelines and asset cooking; use the library when DXIL must be compiled at runtime (e.g., an engine that ships DXIL and compiles to metallib on first load).
For binding compiled shaders to Metal encoders at draw/dispatch time, see integrating-metal-shaderconverter-shaders.
| Scenario | Use |
|---|---|
| Build pipeline, asset cooking, offline shader cache | CLI |
| Compile DXIL to metallib at runtime | Library |
| Dynamic root signatures not known until runtime | Library |
| Generate reflection JSON for binding code | CLI (--output-reflection-file) |
| Runtime reflection after compilation | Library (IRShaderReflection) |
metal-shaderconverter --version
If not found, download from https://developer.apple.com/download/all/?q=Metal%20Shader%20Converter
man metal-shaderconverter | col -b
Authoritative flag reference. If unavailable, use metal-shaderconverter --help.
metal-shaderconverter only accepts DXIL — compile HLSL with DXC first:
dxc -T vs_6_0 -E main shader.hlsl -Fo shader.dxil
metal-shaderconverter shader.dxil -o shader.metallib
Generate reflection alongside the metallib when binding code is needed:
metal-shaderconverter shader.dxil -o shader.metallib --output-reflection-file shader.json
Read references/cli.md for multi-shader workflows and debug/dsym handling.
man libmetalirconverter | col -b
If the man page is unavailable, read the header at metal_irconverter/metal_irconverter.h (macOS default: /usr/local/include/metal_irconverter/).
Link against metalirconverter (-lmetalirconverter). The library is at /usr/local/lib/libmetalirconverter.dylib on macOS by default.
#include <metal_irconverter/metal_irconverter.h>
The notes below cover what's easy to miss when reading the API reference. See references/library.md for a complete compile-loop example.
Lifetime. rootSig must outlive the IRCompiler that references it — destroy the compiler first. Don't share an IRCompiler across threads concurrently; compilation is expensive, prefer worker threads or pre-compile offline.
Bytecode extraction. On Apple, IRMetalLibGetBytecodeData(lib) returns a zero-copy dispatch_data_t that [MTLDevice newLibraryWithData:error:] consumes directly. Non-Apple: use IRMetalLibGetBytecodeSize + IRMetalLibGetBytecode to copy into a caller-owned buffer.
Reflection. Each IRShaderReflectionCopy*Info allocates; always pair with the matching Release*Info. Same rule for IRShaderReflectionCopyFunctionConstants.
Root signature struct initialization. The header documents the struct fields but not how to populate them — see references/library.md.
Read references/library.md for the complete compile loop, root signature struct initialization, per-compilation-reset options, and ray tracing compilation.
Metal shader converter 3.0+ exposes Metal features to HLSL via Metal_HLSL.inc: function constants for shader specialization, and framebuffer fetch for programmable blending.
See references/hlsl-metal-extensions.md for declaration syntax, compile flags (CLI and library), and the root signature caveat.
IRBytecodeOwnershipNone — the IRObject holds a raw pointer; keep the buffer alive until after compile returns.CopyXxxInfo without the matching ReleaseXxxInfo — each Copy allocates; the Release frees it.IRCompilerSetGlobalRootSignature must be called before IRCompilerAllocCompileAndLink.