compiling-with-metal-shaderconverter

name

compiling-with-metal-shaderconverter

description

ALWAYS use when compiling DXIL/HLSL to metallib with Metal shader converter (commonly referred to as MSC) via the metal-shaderconverter CLI or libmetalirconverter (IRCompiler, IRObject, IRShaderReflection) at runtime. Covers offline/runtime DXIL compilation, root signatures, reflection output, ray tracing shaders, geometry/tessellation emulation compilation, framebuffer fetch in HLSL, programmable blending in HLSL, Metal_HLSL.inc, and compatibility flags. Do NOT trigger for binding compiled shaders to encoders — use integrating-metal-shaderconverter-shaders for that.

Metal shader converter — CLI & Library

Overview

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.

Decision Guide

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)

---

CLI

Step 1: Check availability