spirv-cross(1)

📦 version 2021.01.15+1.4.341.0, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 spirv-cross(1) 💖

User Commands • the manual page, part 1 of 4 • bestie edition, no cap

✨ NAME ✨

spirv-cross — a tool designed for parsing and converting SPIR-V to other shader languages. periodt.

🦋 SYNOPSIS 🦋

spirv-cross <...>

💅 DESCRIPTION 💅

🍓 Basic 🍓

[SPIR-V file] (- is stdin) and [--output <output path>] — if the output path isn't provided, it prints output to stdout. slay.
[--dump-resources] — prints a basic reflection of the SPIR-V module along with other output. ✨
[--help] — prints this help message.

🌈 Select backend 🌈

By default, OpenGL-style GLSL is the target, with #version and GLSL/ESSL information inherited from the SPIR-V module if present.

--vulkan-semantics or -V — emit Vulkan GLSL instead of plain GLSL. Makes use of Vulkan-only features to match SPIR-V.
--msl — emit Metal Shading Language (MSL).
--hlsl — emit HLSL.
--reflect — emit JSON reflection.
--cpp — DEPRECATED. Emits C++ code.

💖 Common options 💖

--entry name — use a specific entry point. By default, the first entry point in the module is used.
--stage <stage (vert, frag, geom, tesc, tese comp)> — forces use of a certain shader stage. Can disambiguate the entry point if more than one entry point exists with same name, but different stage.
--emit-line-directives — if SPIR-V has OpLine directives, aim to emit those accurately in output code as well.
--rename-entry-point <old> <new> <stage> — renames an entry point from what is declared in SPIR-V to code output. Mostly relevant for HLSL or MSL.
--rename-interface-variable <in|out> <location> <new_variable_name> — rename an interface variable based on location decoration.
--force-zero-initialized-variables — forces temporary variables to be initialized to zero. Can be useful in environments where compilers do not allow potentially uninitialized variables. This usually comes up with Phi temporaries.
--fixup-clipspace — fixup Z clip-space at the end of a vertex shader. The behavior is backend-dependent. GLSL: Rewrites [0, w] Z range (D3D/Metal/Vulkan) to GL-style [-w, w]. HLSL/MSL: Rewrites [-w, w] Z range (GL) to D3D/Metal/Vulkan-style [0, w].
--flip-vert-y — inverts gl_Position.y (or equivalent) at the end of a vertex shader. This is equivalent to using negative viewport height.

🎀 GLSL options 🎀

--es — force ESSL.
--no-es — force desktop GLSL.
--version <GLSL version> — e.g. --version 450 will emit '#version 450' in shader. Code generation will depend on the version used.
--flatten-ubo — emit UBOs as plain uniform arrays which are suitable for use with glUniform4*v(). This can be an optimization on GL implementations where this is faster or works around buggy driver implementations. E.g.: uniform MyUBO { vec4 a; float b, c, d, e; }; will be emitted as uniform vec4 MyUBO[2]; Caveat: You cannot mix and match floating-point and integer in the same UBO with this option. Legacy GLSL/ESSL (where this flattening makes sense) does not support bit-casting, which would have been the obvious workaround.
--extension ext — add #extension string of your choosing to GLSL output. Useful if you use variable name remapping to something that requires an extension unknown to SPIRV-Cross.
--remove-unused-variables — do not emit interface variables which are not statically accessed by the shader.
--separate-shader-objects — redeclare gl_PerVertex blocks to be suitable for desktop GL separate shader objects.
--glsl-emit-push-constant-as-ubo — instead of a plain uniform of struct for push constants, emit a UBO block instead.
--glsl-emit-ubo-as-plain-uniforms — instead of emitting UBOs, emit them as plain uniform structs.
--glsl-remap-ext-framebuffer-fetch input-attachment color-location — remaps an input attachment to use GL_EXT_shader_framebuffer_fetch. gl_LastFragData[location] is read from. The attachment to read from must be declared as an output in the shader.
--vulkan-glsl-disable-ext-samplerless-texture-functions — do not allow use of GL_EXT_samperless_texture_functions, even in Vulkan GLSL. Use of texelFetch and similar might have to create dummy samplers to work around it.
--combined-samplers-inherit-bindings — inherit binding information from the textures when building combined image samplers from separate textures and samplers.
--no-support-nonzero-baseinstance — when using gl_InstanceIndex with desktop GL, assume that base instance is always 0, and do not attempt to fix up gl_InstanceID to match Vulkan semantics.
--pls-in format input-name — remaps a subpass input with name into a GL_EXT_pixel_local_storage input. Entry in PLS block is ordered where first --pls-in marks the first entry. Can be called multiple times. Formats allowed: r11f_g11f_b10f, r32f, rg16f, rg16, rgb10_a2, rgba8, rgba8i, rgba8ui, rg16i, rgb10_a2ui, rg16ui, r32ui. Requires ESSL.
--pls-out format output-name — remaps a color output with name into a GL_EXT_pixel_local_storage output. Entry in PLS block is ordered where first --pls-output marks the first entry. Can be called multiple times. Formats allowed: r11f_g11f_b10f, r32f, rg16f, rg16, rgb10_a2, rgba8, rgba8i, rgba8ui, rg16i, rgb10_a2ui, rg16ui, r32ui. Requires ESSL.
--remap source_name target_name components — remaps a variable to a different name with N components. Main use case is to remap a subpass input to gl_LastFragDepthARM. E.g.: uniform subpassInput uDepth; --remap uDepth gl_LastFragDepthARM 1 --extension GL_ARM_shader_framebuffer_fetch_depth_stencil
--no-420pack-extension — do not make use of GL_ARB_shading_language_420pack in older GL targets to support layout(binding).
--remap-variable-type <variable_name> <new_variable_type> — remaps a variable type based on name. Primary use case is supporting external samplers in ESSL for video rendering on Android where you could remap a texture to a YUV one.
--glsl-force-flattened-io-blocks — always flatten I/O blocks and structs.

🦋 MSL options 🦋

--msl-version <MMmmpp> — uses a specific MSL version, e.g. --msl-version 20100 for MSL 2.1.
--msl-capture-output — writes geometry varyings to a buffer instead of as stage-outputs.
--msl-swizzle-texture-samples — works around lack of support for VkImageView component swizzles. This has a massive impact on performance and bloat. Do not use this unless you are absolutely forced to. To use this feature, the API side must pass down swizzle buffers. Should only be used by translation layers as a last resort. Recent Metal versions do not require this workaround.
--msl-ios — target iOS Metal instead of macOS Metal.
--msl-pad-fragment-output — always emit color outputs as 4-component variables. In Metal, the fragment shader must emit at least as many components as the render target format.
--msl-domain-lower-left — use a lower-left tessellation domain.
--msl-argument-buffers — emit Indirect Argument buffers instead of plain bindings. Requires MSL 2.0 to be enabled.
--msl-texture-buffer-native — enable native support for texel buffers. Otherwise, it is emulated as a normal texture.
--msl-framebuffer-fetch — implement subpass inputs with frame buffer fetch. Emits [[color(N)]] inputs in fragment stage. Requires an Apple GPU.
--msl-emulate-cube-array — emulate cube arrays with 2D array and manual math.
--msl-discrete-descriptor-set <index> — when using argument buffers, forces a specific descriptor set to be implemented without argument buffers. Useful for implementing push descriptors in emulation layers. Can be used multiple times for each descriptor set in question.
--msl-device-argument-buffer <descriptor set index> — use device address space to hold indirect argument buffers instead of constant. Comes up when trying to support argument buffers which are larger than 64 KiB.
--msl-multiview — enable SPV_KHR_multiview emulation.
--msl-multiview-no-layered-rendering — don't set [[render_target_array_index]] in multiview shaders. Useful for devices which don't support layered rendering. Only effective when --msl-multiview is enabled.
--msl-view-index-from-device-index — treat the view index as the device index instead. For multi-GPU rendering.
--msl-dispatch-base — add support for vkCmdDispatchBase() or similar APIs. Offsets the workgroup ID based on a buffer.
--msl-dynamic-buffer <set index> <binding> — marks a buffer as having dynamic offset. The offset is applied in the shader with pointer arithmetic. Useful for argument buffers where it is non-trivial to apply dynamic offset otherwise.
--msl-inline-uniform-block <set index> <binding> — in argument buffers, mark an UBO as being an inline uniform block which is embedded into the argument buffer itself.
--msl-decoration-binding — use SPIR-V bindings directly as MSL bindings. This does not work in the general case as there is no descriptor set support, and combined image samplers are split up. However, if the shader author knows of binding limitations, this option will avoid the need for reflection on Metal side.
--msl-force-active-argument-buffer-resources — (bestie, the description for this one is in the next part, hold on to your seat ✨)

Always emit resources which are part of argument buffers. This makes sure that similar shaders with same resource declarations can share the argument buffer as declaring an argument buffer implies an ABI. 🫶

--msl-force-native-arrays — instead of implementing array types as a templated value type ala std::array<T>, use plain, native arrays. It's giving worse code-gen ngl, but it can work around driver bugs on certain driver revisions of certain Intel-based Macbooks where template arrays break. 😭
--msl-disable-frag-depth-builtin — disables FragDepth output. Useful if your pipeline does not enable depth, since pipeline creation might otherwise fail. 💀
--msl-disable-frag-stencil-ref-builtin — disable FragStencilRef output. Useful if your pipeline does not enable stencil output, because pipeline creation might otherwise fail. 💀
--msl-enable-frag-output-mask <mask> — only selectively enable fragment outputs. Useful if your pipeline does not enable fragment output for certain locations, as pipeline creation might otherwise fail. 🙈
--msl-no-clip-distance-user-varying — do not emit user varyings to emulate gl_ClipDistance in fragment shaders. ✨
--msl-shader-input <index> <format> <size> — specify the format of the shader input at <index>. <format> can be any32, any16, u16, u8, or other, to indicate a 32-bit opaque value, 16-bit opaque value, 16-bit unsigned integer, 8-bit unsigned integer, or other-typed variable. <size> is the vector length of the variable, which must be greater than or equal to that declared in the shader. Useful if shader stage interfaces don't match up, as pipeline creation might otherwise fail. 🔥
--msl-multi-patch-workgroup — use the new style of tessellation control processing, where multiple patches are processed per workgroup. This should increase throughput by ensuring all the GPU's SIMD lanes are occupied, but heads up, it is not compatible with the old style. In addition, this style also passes input variables in buffers directly instead of using vertex attribute processing. In a future version of SPIRV-Cross, this will become the default. 👑
--msl-vertex-for-tessellation — when handling a vertex shader, marks it as one that will be used with a new-style tessellation control shader. The vertex shader is output to MSL as a compute kernel which outputs vertices to the buffer in the order they are received, rather than in index order as with --msl-capture-output normally. 🦋
--msl-additional-fixed-sample-mask <mask> — set an additional fixed sample mask. If the shader outputs a sample mask, then the final sample mask will be a bitwise AND of the two. 💅
--msl-arrayed-subpass-input — assume that images of dimension SubpassData have multiple layers. Layered input attachments are accessed relative to BuiltInLayer. This option has no effect if multiview is also enabled. 🌸
--msl-r32ui-linear-texture-align <alignment> — the required alignment of linear textures of format MTLPixelFormatR32Uint. This is used to align the row stride for atomic accesses to such images. ⭐
--msl-r32ui-linear-texture-align-constant-id <id> — the function constant ID to use for the linear texture alignment. On MSL 1.2 or later, you can override the alignment by setting this function constant. 🎀
--msl-texture-1d-as-2d — emit Image variables of dimension Dim1D as texture2d. In Metal, 1D textures do not support all features that 2D textures do. Use this option if your code relies on these features. 💜
--msl-ios-use-simdgroup-functions — use simd_*() functions for subgroup ops instead of quad_*(). Recent Apple GPUs support SIMD-groups larger than a quad. Use this option to take advantage of this support. 🔥
--msl-emulate-subgroups — assume subgroups of size 1. Intended for Vulkan Portability implementations where Metal support for SIMD-groups is insufficient for true subgroups. 😭
--msl-fixed-subgroup-size <size> — assign a constant <size> to the SubgroupSize builtin. Intended for Vulkan Portability implementations where VK_EXT_subgroup_size_control is not supported or disabled. If 0, assume variable subgroup size as actually exposed by Metal. 🌈
--msl-force-sample-rate-shading — force fragment shaders to run per sample. This adds a [[sample_id]] parameter if none is already present. 💖

🔥 HLSL OPTIONS 🔥

--shader-model — enables a specific shader model, e.g. --shader-model 50 for SM 5.0. 👑
--hlsl-enable-compat — allow point size and point coord to be used, even if they won't work as expected. PointSize is ignored, and PointCoord returns (0.5, 0.5). 💀
--hlsl-support-nonzero-basevertex-baseinstance — support base vertex and base instance by emitting a special cbuffer declared as:

cbuffer SPIRV_Cross_VertexInfo
{
    int SPIRV_Cross_BaseVertex;
    int SPIRV_Cross_BaseInstance;
};

--hlsl-auto-binding (push, cbv, srv, uav, sampler, all) — do not emit any : register(#) bindings for specific resource types, and rely on the HLSL compiler to assign something. 🎀
--hlsl-force-storage-buffer-as-uav — always emit SSBOs as UAVs, even when marked as read-only. Normally, SSBOs marked with NonWritable will be emitted as SRVs. 💅
--hlsl-nonwritable-uav-texture-as-srv — emit NonWritable storage images as SRV textures instead of UAV. Using this option messes with the type system. SPIRV-Cross cannot guarantee that this will work. One major problem area with this feature is function arguments, where we won't know if we're seeing a UAV or SRV. Shader must ensure that read/write state is consistent at all call sites. 😭
--set-hlsl-vertex-input-semantic <location> <semantic> — emits a specific vertex input semantic for a given location. Otherwise, TEXCOORD# is used as semantics, where # is location. ✨
--hlsl-enable-16bit-types — enables native use of half/int16_t/uint16_t and ByteAddressBuffer interaction with these types. Requires SM 6.2. 🦋
--hlsl-flatten-matrix-vertex-input-semantics — emits matrix vertex inputs with input semantics as if they were independent vectors, e.g. TEXCOORD{2,3,4} rather than matrix form TEXCOORD2_{0,1,2}. 🌸

💀 OBSCURE OPTIONS 💀

These options are not meant to be used on a regular basis. They have some occasional uses in the test suite. 🙈

--force-temporary — aggressively emit temporary expressions instead of forwarding expressions. Very rarely used and under-tested. 💀
--revision — prints build timestamp and Git commit information (updated when cmake is configured). ⭐
--iterations iter — recompiles the same shader over and over, benchmarking related. 🔁
--disable-storage-image-qualifier-deduction — if storage images are received without any nonwritable or nonreadable information, do not attempt to analyze usage, and always emit read/write state. 👑
--flatten-multidimensional-arrays — do not support multi-dimensional arrays and flatten them to one dimension. 🧚
--cpp-interface-name <name> — emit a specific class name in C++ codegen. 💜

🫶 USAGE 🫶

Usage: spirv-cross <...>

🌸 Basic 🌸

[SPIR-V file] (- is stdin) [--output <output path>] — if not provided, prints output to stdout. 💖
[--dump-resources] — prints a basic reflection of the SPIR-V module along with other output. ✨
[--help] — prints this help message. 🎀

👑 Select backend 👑

By default, OpenGL-style GLSL is the target, with #version and GLSL/ESSL information inherited from the SPIR-V module if present. 🌈

--vulkan-semantics, -V — emit Vulkan GLSL instead of plain GLSL. Makes use of Vulkan-only features to match SPIR-V. 🔥
--msl — emit Metal Shading Language (MSL). 💅
--hlsl — emit HLSL. ⭐
--reflect — emit JSON reflection. 🦋
--cpp — DEPRECATED. Emits C++ code. 💀

💖 Common options 💖

--entry name — use a specific entry point. By default, the first entry point in the module is used. 👑
--stage <stage (vert, frag, geom, tesc, tese comp)> — forces use of a certain shader stage. Can disambiguate the entry point if more than one entry point exists with same name, but different stage. 🌸
--emit-line-directives — if SPIR-V has OpLine directives, aim to emit those accurately in output code as well. ✨
--rename-entry-point <old> <new> <stage> — renames an entry point from what is declared in SPIR-V to code output. Mostly relevant for HLSL or MSL. 🎀
--rename-interface-variable <in|out> <location> <new_variable_name> — rename an interface variable based on location decoration. 💜
--force-zero-initialized-variables — forces temporary variables to be initialized to zero. Can be useful in environments where compilers do not allow potentially uninitialized variables. This usually comes up with Phi temporaries. 🔥
--fixup-clipspace — fixup Z clip-space at the end of a vertex shader. The behavior is backend-dependent. GLSL: rewrites [0, w] Z range (D3D/Metal/Vulkan) to GL-style [-w, w]. HLSL/MSL: rewrites [-w, w] Z range (GL) to D3D/Metal/Vulkan-style [0, w]. 🦋
--flip-vert-y — inverts gl_Position.y (or equivalent) at the end of a vertex shader. This is equivalent to using negative viewport height. ⭐

🎀 GLSL options 🎀

--es — force ESSL. 💖
--no-es — force desktop GLSL. 💅
--version <GLSL version> — e.g. --version 450 will emit '#version 450' in shader. Code generation will depend on the version used. 👑
--flatten-ubo —

okay so this one's the tail end of the flatten-the-UBOs situation 💅 — it spits your UBOs out as plain uniform arrays, the kind that play nice with glUniform4*v(). It can be a real optimization on GL implementations where that path is faster, and it also dodges some genuinely cursed buggy driver behaviour. Like, look at this glow-up:

uniform MyUBO { vec4 a; float b, c, d, e; };

gets emitted as

uniform vec4 MyUBO[2];

⚠️ Caveat bestie, no cap: you literally cannot mix floating-point and integer in the same UBO with this on. Legacy GLSL/ESSL (the only place this flattening even makes sense) doesn't support bit-casting, which would've been the obvious workaround. So it's giving "pick a lane." 😭

--extension ext — drops an #extension string of your choosing straight into the GLSL output. Super useful when you're using variable name remapping to something that needs an extension SPIRV-Cross has never heard of. ✨
--remove-unused-variables — don't emit interface variables that the shader never statically accesses. If nobody's reading it, it's not invited to the party. 🙈
--separate-shader-objects — redeclares gl_PerVertex blocks so they're suitable for desktop GL separate shader objects. Desktop GL girlies, this one's for you. 🫶
--glsl-emit-push-constant-as-ubo — instead of a plain uniform of struct for push constants, emit a UBO block instead. Switching up the fit. 👑
--glsl-emit-ubo-as-plain-uniforms — instead of emitting UBOs, emit them as plain uniform structs. The reverse slay. 💅
--glsl-remap-ext-framebuffer-fetch input-attachment color-location — remaps an input attachment to use GL_EXT_shader_framebuffer_fetch. gl_LastFragData[location] is what gets read from. Heads up: the attachment you're reading from must be declared as an output in the shader, periodt.
--vulkan-glsl-disable-ext-samplerless-texture-functions — don't allow use of GL_EXT_samperless_texture_functions, even in Vulkan GLSL. Using texelFetch and friends might force you to create dummy samplers to work around it. 😭
--combined-samplers-inherit-bindings — inherit binding info from the textures when building combined image samplers out of separate textures and samplers. Sharing is caring. 💖
--no-support-nonzero-baseinstance — when using gl_InstanceIndex with desktop GL, assume the base instance is always 0, and don't bother trying to fix up gl_InstanceID to match Vulkan semantics. No extra work, no extra stress. 🌸
--pls-in format input-name — remaps a subpass input with name into a GL_EXT_pixel_local_storage input. The entry's position in the PLS block is ordered so that the first --pls-in marks the first entry. Can be called multiple times. Formats allowed: r11f_g11f_b10f, r32f, rg16f, rg16, rgb10_a2, rgba8, rgba8i, rgba8ui, rg16i, rgb10_a2ui, rg16ui, r32ui. Requires ESSL. 🎀
--pls-out format output-name — remaps a color output with name into a GL_EXT_pixel_local_storage output. Same ordering rules: the first --pls-output marks the first entry. Can be called multiple times. Formats allowed: r11f_g11f_b10f, r32f, rg16f, rg16, rgb10_a2, rgba8, rgba8i, rgba8ui, rg16i, rgb10_a2ui, rg16ui, r32ui. Requires ESSL. 🎀
--remap source_name target_name components — remaps a variable to a different name with N components. The main character use case here is remapping a subpass input to gl_LastFragDepthARM. E.g.:

uniform subpassInput uDepth; --remap uDepth gl_LastFragDepthARM 1 --extension GL_ARM_shader_framebuffer_fetch_depth_stencil

--no-420pack-extension — do not make use of GL_ARB_shading_language_420pack in older GL targets just to support layout(binding). Living without it, we can do it. 💪
--remap-variable-type <variable_name> <new_variable_type> — remaps a variable type based on its name. Primary use case: supporting external samplers in ESSL for video rendering on Android, where you could remap a texture to a YUV one. Android girlies rise. 🌈
--glsl-force-flattened-io-blocks — always flatten I/O blocks and structs. Flatten everything, bestie. 🦋

🍎 MSL options 🍎

--msl-version <MMmmpp> — uses a specific MSL version, e.g. --msl-version 20100 for MSL 2.1. Set the vibe, choose your version. ⭐
--msl-capture-output — writes geometry varyings to a buffer instead of as stage-outputs. Rerouting the mail. 📦
--msl-swizzle-texture-samples — works around the lack of support for VkImageView component swizzles.

🚨 Bestie this one has a massive impact on performance and bloat. Do not use this unless you are absolutely, genuinely forced to. To use it, the API side must pass down swizzle buffers. It should only ever be used by translation layers as a last resort. Recent Metal versions do not require this workaround, so like… check first. 💀

--msl-ios — target iOS Metal instead of macOS Metal. 📱
--msl-pad-fragment-output — always emit color outputs as 4-component variables. In Metal, the fragment shader must emit at least as many components as the render target format. Pad it out. ✨
--msl-domain-lower-left — use a lower-left tessellation domain. 🦋
--msl-argument-buffers — emit Indirect Argument buffers instead of plain bindings. Requires MSL 2.0 to be enabled. 👑
--msl-texture-buffer-native — enable native support for texel buffers. Otherwise, it gets emulated as a normal texture. Fake it till you make it. 🎀
--msl-framebuffer-fetch — implement subpass inputs with frame buffer fetch. Emits [[color(N)]] inputs in the fragment stage. Requires an Apple GPU. 🍎
--msl-emulate-cube-array — emulate cube arrays with a 2D array and manual math. Doing the math ourselves because we're capable like that. 🧮
--msl-discrete-descriptor-set <index> — when using argument buffers, forces a specific descriptor set to be implemented without argument buffers. Super useful for implementing push descriptors in emulation layers. Can be used multiple times, once for each descriptor set in question. 🔁
--msl-device-argument-buffer <descriptor set index> — use the device address space to hold indirect argument buffers instead of constant. Comes up when you're trying to support argument buffers larger than 64 KiB. Big buffer energy. 🔥
--msl-multiview — enable SPV_KHR_multiview emulation. 👀
--msl-multiview-no-layered-rendering — don't set [[render_target_array_index]] in multiview shaders. Useful for devices that don't support layered rendering. Only effective when --msl-multiview is enabled. ⚠️
--msl-view-index-from-device-index — treat the view index as the device index instead. For multi-GPU rendering. Teamwork. 🫶
--msl-dispatch-base — add support for vkCmdDispatchBase() or similar APIs. Offsets the workgroup ID based on a buffer. 📍
--msl-dynamic-buffer <set index> <binding> — marks a buffer as having a dynamic offset. The offset gets applied in the shader with pointer arithmetic. Useful for argument buffers where applying a dynamic offset is otherwise non-trivial. 🧠
--msl-inline-uniform-block <set index> <binding> — in argument buffers, mark a UBO as being an inline uniform block which is embedded into the argument buffer itself. Nesting era. 🪆
--msl-decoration-binding — use SPIR-V bindings directly as MSL bindings. This does not work in the general case, because there's no descriptor set support and combined image samplers get split up. However, if the shader author knows about the binding limitations, this option will avoid the need for reflection on the Metal side. YMMV, iykyk. 💅
--msl-force-active-argument-buffer-resources — always emit resources which are part of argument buffers. This makes sure similar shaders with the same resource declarations can share the argument buffer, since declaring an argument buffer implies an ABI. 🤝
--msl-force-native-arrays — rather than implementing array types as a templated value type ala std::array<T>, use plain, native arrays. This leads to worse code-gen, but it can work around driver bugs on certain driver revisions of certain Intel-based Macbooks where template arrays break. Fixing the laptop, not the code. 💻
--msl-disable-frag-depth-builtin — disables FragDepth output. Useful if the pipeline does not enable depth, since pipeline creation might otherwise fail. 🙅
--msl-disable-frag-stencil-ref-builtin — disable FragStencilRef output. Useful if the pipeline does not enable stencil output, since pipeline creation might otherwise fail. 🙅
--msl-enable-frag-output-mask <mask> — only selectively enable fragment outputs. Useful if the pipeline does not enable fragment output for certain locations, since pipeline creation might otherwise fail. 🎯
--msl-no-clip-distance-user-varying — do not emit user varyings to emulate gl_ClipDistance in fragment shaders. ✂️
--msl-shader-input <index> <format> <size> — specify the format of the shader input at <index>. <format> can be 'any32', 'any16', 'u16', 'u8', or 'other', to indicate a 32-bit opaque value, 16-bit opaque value, 16-bit unsigned integer, 8-bit unsigned integer, or other-typed variable. <size> is the vector length of the variable, which must be greater than or equal to that declared in the shader. Useful if shader stage interfaces don't match up, since pipeline creation might otherwise fail. 🧩
--msl-multi-patch-workgroup — use the new style of tessellation control processing, where multiple patches are processed per workgroup. This should increase throughput by ensuring all the GPU's SIMD lanes are occupied, but it is not compatible with the old style. In addition, this style also passes input variables in buffers directly instead of using vertex attribute processing. In a future version of SPIRV-Cross, this will become the default. Future is now-ish. 🔮
--msl-vertex-for-tessellation — when handling a vertex shader, marks it as one that will be used with a new-style tessellation control shader. The vertex shader is output to MSL as a compute kernel which outputs vertices to the buffer in the order they are received, rather than in index order as with --msl-capture-output normally. Order matters, bestie. 📋
--msl-additional-fixed-sample-mask <mask> — set an additional fixed sample mask. If the shader outputs a sample mask, then the final sample mask will be a bitwise AND of the two. 🔗
--msl-arrayed-subpass-input

Also, quick note on the option from literally one second ago (the layered-attachment one, you know the one 💅): Assume that images of dimension SubpassData have multiple layers. Layered input attachments are accessed relative to BuiltInLayer. And heads up bestie — this option has no effect if multiview is also enabled. It's giving "mutually exclusive," fr fr.

--msl-r32ui-linear-texture-align <alignment> — the required alignment of linear textures of format MTLPixelFormatR32Uint. It's used to align the row stride for atomic accesses to those images. Alignment matters, no cap 🎀
--msl-r32ui-linear-texture-align-constant-id <id> — the function constant ID you use for that linear texture alignment. On MSL 1.2 or later, you can override the alignment by setting this function constant. Override era ✨
--msl-texture-1d-as-2d — emit Image variables of dimension Dim1D as texture2d. In Metal, 1D textures do not support all features that 2D textures do. Use this option if your code relies on those features. Fake it till you make it 💅
--msl-ios-use-simdgroup-functions — use simd_*() functions for subgroup ops instead of quad_*(). Recent Apple GPUs support SIMD-groups larger than a quad, so flip this on to actually take advantage of that. Bigger groups, bigger slay 🔥
--msl-emulate-subgroups — assume subgroups of size 1. Intended for Vulkan Portability implementations where Metal's support for SIMD-groups is just not enough for true subgroups. Pretend era, but on purpose 🙈
--msl-fixed-subgroup-size <size> — assign a constant <size> to the SubgroupSize builtin. Intended for Vulkan Portability implementations where VK_EXT_subgroup_size_control is not supported or disabled. If 0, assume variable subgroup size as actually exposed by Metal. Pick your fighter 🌸
--msl-force-sample-rate-shading — force fragment shaders to run per sample. This adds a [[sample_id]] parameter if none is already present. Per sample, per moment, main character energy 👑

🔥 HLSL options 🔥

--shader-model — enables a specific shader model, e.g. --shader-model 50 for SM 5.0.
--hlsl-enable-compat — allow point size and point coord to be used, even if they won't work as expected. PointSize is ignored, and PointCoord returns (0.5, 0.5). So like… it compiles. That's the vibe 😭
--hlsl-support-nonzero-basevertex-baseinstance — support base vertex and base instance by emitting a special cbuffer declared as:

cbuffer SPIRV_Cross_VertexInfo
{
    int SPIRV_Cross_BaseVertex;
    int SPIRV_Cross_BaseInstance;
};

--hlsl-auto-binding (push, cbv, srv, uav, sampler, all) — do not emit any : register(#) bindings for specific resource types, and rely on the HLSL compiler to assign something. Delegate era, we love a handoff 🫶
--hlsl-force-storage-buffer-as-uav — always emit SSBOs as UAVs, even when they're marked as read-only. Normally, SSBOs marked with NonWritable get emitted as SRVs. No read-only privilege here, they're all UAVs now 💅
--hlsl-nonwritable-uav-texture-as-srv — emit NonWritable storage images as SRV textures instead of UAV.

⚠️ Using this option messes with the type system. SPIRV-Cross cannot guarantee that this will work. One major problem area with this feature is function arguments, where we won't know if we're seeing a UAV or SRV. Shader must ensure that read/write state is consistent at all call sites. Bestie. Be careful. This one is genuinely unhinged 💀

--set-hlsl-vertex-input-semantic <location> <semantic> — emits a specific vertex input semantic for a given location. Otherwise, TEXCOORD# is used as semantics, where # is location. Custom naming rights, iconic 🎀
--hlsl-enable-16bit-types — enables native use of half/int16_t/uint16_t and ByteAddressBuffer interaction with these types. Requires SM 6.2. Gatekeeping, but respectfully ✨
--hlsl-flatten-matrix-vertex-input-semantics — emits matrix vertex inputs with input semantics as if they were independent vectors, e.g. TEXCOORD{2,3,4} rather than matrix form TEXCOORD2_{0,1,2}. Un-matrix-ify the whole situation 🌈

🫣 Obscure options 🫣

These options are not meant to be used on a regular basis. They have some occasional uses in the test suite. So like, not your everyday thing. You've been warned, bestie 🙈

--force-temporary — aggressively emit temporary expressions instead of forwarding expressions. Very rarely used and under-tested. Under-tested fr fr, tread lightly 💀
--revision — prints build timestamp and Git commit information (updated when cmake is configured). Receipts, literally 🧾
--iterations iter — recompiles the same shader over and over, benchmarking related. Over and over and over, it's giving treadmill energy 🏃‍♀️
--disable-storage-image-qualifier-deduction — if storage images are received without any nonwritable or nonreadable information, do not attempt to analyze usage, and always emit read/write state. No detective work today, we assume the most permissive ✨
--flatten-multidimensional-arrays — do not support multi-dimensional arrays and flatten them to one dimension. One dimension only, we keep it simple 🎀
--cpp-interface-name <name> — emit a specific class name in C++ codegen. Name it, own it 💅

and that's the whole page, bestie, we made it to the end 🥹

This gorgeous little manual is for spirv-cross, and it was dated June 2021 — the page identifies itself as spirv-cross(1), so that's the source/version-and-date energy right there. Go forth and cross some SPIR-V, you absolute icon 👑💖

📦 where this page comes from

debian bookworm: spirv-cross 2021.01.15+1.3.239.0-1 · Apache-2.0
debian trixie: spirv-cross 2021.01.15+1.4.304.1-2 · Apache-2.0
ubuntu jammy: spirv-cross 2021.01.15-5 · Apache-2.0
ubuntu noble: spirv-cross 2021.01.15+1.3.239.0-1build1 · Apache-2.0
ubuntu questing: spirv-cross 2021.01.15+1.4.321.0-1
ubuntu resolute: spirv-cross 2021.01.15+1.4.335.0-1 · Apache-2.0
ubuntu stonking: spirv-cross 2021.01.15+1.4.341.0-1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms