HLSL To SPIR-V On Metal: Struct Tag Issue

Aug 27, 2025 by Lucas 42 views

HLSL Compiled to SPIR-V on Metal: Must Use 'struct' Tag to Refer to Type 'X' in This Scope

Hey guys! Ever run into those quirky little issues when you're porting your graphics code across different platforms? Today, we're diving deep into a specific head-scratcher: why HLSL compiled to SPIR-V on Metal insists on using the struct tag when referring to types. This can be a real pain, especially if your code works perfectly fine on other platforms like Windows with Vulkan. Let's break down the problem, explore the reasons behind it, and figure out how to tackle it like seasoned developers.

Understanding the Issue

So, you've got this awesome project, right? You've been hammering away at it on Windows, using Vulkan, and everything's smooth sailing. You've got your HLSL fragment shaders compiling to SPIR-V with shaderc, and they're playing nicely in your Vulkan pipeline via SDL3. But then, BAM! You switch over to macOS, and suddenly you're drowning in errors like this:

[mvk-error] VK_ERROR_INITIALIZATION_FAILED: Shader library compile failed (Error code 3):
program_source:67:44: error: must use 'struct' tag to refer to type 'world_info' in this scope
    constant auto& world_info = *(constant world_info* )((constant char* )spvDescriptorSet3.world_info + spvDynamicOffsets[0]);
                                           ^
                                           struct 
program_source:67:20: note: struct 'world_info' is hidden by a non-type declaration of 'world_info' here
    constant auto& world_info = *(constant world_info* )((constant char* )spvDescriptorSet3.world_info + spvDynamicOffsets[0]);
                   ^
program_source:68:44: error: must use 'struct' tag to refer to type 'frame_info' in this scope
    constant auto& frame_info = *(constant frame_info* )((constant char* )spvDescriptorSet3.frame_info + spvDynamicOffsets[1]);
                                           ^
                                           struct 
program_source:68:20: note: struct 'frame_info' is hidden by a non-type declaration of 'frame_info' here
    constant auto& frame_info = *(constant frame_info* )((constant char* )spvDescriptorSet3.frame_info + spvDynamicOffsets[1]);
                   ^
.
[mvk-error] VK_ERROR_INITIALIZATION_FAILED: Fragment shader function could not be compiled into pipeline. See previous logged error.

What's going on here? The error message is screaming about needing the struct tag when referring to types like world_info and frame_info. But why only on macOS? Let's dig into the code snippet that's causing the trouble:

struct WorldInfo {
    float4 ambient_light;
    float2 world_resolution;
    float2 level_size;
};

struct FrameInfo {
    float2 world_offset;
    uint num_lights;
};

ConstantBuffer<WorldInfo> world_info : register(b0, space3);
ConstantBuffer<FrameInfo> frame_info : register(b1, space3);

You've defined your structs, set up your constant buffers, and everything looks Kosher. But when you peek at the compiled shader code (thanks to those handy MVK_CONFIG_LOG_LEVEL=3 MVK_CONFIG_DEBUG=1 options), you see something funky:

struct world_info
{
    float4 ambient_light;
    float2 world_resolution;
    float2 level_size;
};

struct frame_info
{
    float2 world_offset;
    uint num_lights;
};

...

struct spvDescriptorSetBuffer3
{
    constant void* _m0_pad [[id(0)]];
    constant world_info* world_info [[id(1)]];
    constant frame_info* frame_info [[id(2)]];
};

struct main0_out
{
    float4 _entryPointOutput [[color(0)]];
};

struct main0_in
{
    float2 input_uv [[user(locn0)]];
};

fragment main0_out main0(main0_in in [[stage_in]], constant spvDescriptorSetBuffer2& spvDescriptorSet2 [[buffer(2)]], constant spvDescriptorSetBuffer3& spvDescriptorSet3 [[buffer(3)]], constant uint* spvDynamicOffsets [[buffer(30)]])
{
    constant auto& world_info = *(constant world_info* )((constant char* )spvDescriptorSet3.world_info + spvDynamicOffsets[0]);
    constant auto& frame_info = *(constant frame_info* )((constant char* )spvDescriptorSet3.frame_info + spvDynamicOffsets[1]);

Notice how the struct definitions in the compiled code use lowercase names (world_info and frame_info), which clash with the variable names you're using. This naming collision is the heart of the problem. The compiler gets confused and throws a fit, demanding that you explicitly use the struct tag to disambiguate the type.

Why Does This Happen on macOS (Metal)?

This is where things get interesting. The issue seems to be specific to the Metal backend when compiling SPIR-V from HLSL. Different platforms and shader compilers have their own quirks and interpretations of the shading language specifications. In this case, the Metal compiler appears to be more strict about naming conflicts between struct names and variable names. It's likely that the HLSL-to-SPIR-V compilation process, when targeting Metal, generates code that exposes this behavior. Other platforms, like Windows with Vulkan, might be more lenient or handle the naming collision differently, which is why your code works fine there.

Solutions and Workarounds

Alright, so we know what's going wrong. Now, how do we fix it? Here are a few strategies you can use to tackle this issue:

1. Explicitly Use the `struct` Tag

The most straightforward solution is to simply add the struct tag wherever you refer to your struct types. This tells the compiler exactly what you mean and resolves the naming ambiguity. For example, you would change the offending lines in your shader code like this:

constant auto& world_info = *(constant struct world_info* )((constant char* )spvDescriptorSet3.world_info + spvDynamicOffsets[0]);
constant auto& frame_info = *(constant struct frame_info* )((constant char* )spvDescriptorSet3.frame_info + spvDynamicOffsets[1]);

This might seem a bit verbose, but it's a clear and effective way to resolve the error. However, it does mean you'll need to modify your shader code, which might not be ideal if you're aiming for maximum portability.

2. Rename Your Variables or Structs

Another approach is to avoid the naming collision altogether. You could rename either your variables or your structs so that they don't share the same name (case-insensitively). For instance, you could rename your variables to worldInfoData and frameInfoData, or you could rename your structs to WorldInfoType and FrameInfoType. This way, the compiler won't get confused about which world_info or frame_info you're referring to.

This solution can be cleaner in some ways, as it avoids the verbosity of the struct tag. However, it might require more extensive code changes, especially if you're using the conflicting names in many places.

3. Adjust Your HLSL-to-SPIR-V Compilation

It's also worth exploring whether there are options in your HLSL-to-SPIR-V compilation process that might affect this behavior. Some compilers have flags that control how names are mangled or how naming conflicts are handled. Digging into the documentation for your compiler (in this case, shaderc) might reveal a setting that can mitigate this issue. This approach could be the most elegant, as it avoids code changes, but it might require some experimentation and a deeper understanding of your toolchain.

4. MoltenVK Configuration (if applicable)

Since you're using MoltenVK, there might be specific configuration options or workarounds within MoltenVK itself that can address this issue. Checking the MoltenVK documentation or community forums for similar problems could turn up a MoltenVK-specific solution. This is particularly relevant because the error messages you're seeing are coming from MoltenVK.

Best Practices for Cross-Platform Shaders

This whole situation highlights the challenges of writing shaders that work seamlessly across different platforms. Here are a few best practices to keep in mind to minimize these kinds of headaches:

Be Explicit: When in doubt, be explicit in your shader code. Using the struct tag, fully qualifying names, and avoiding naming collisions can all help prevent unexpected behavior.
Test on Multiple Platforms: Don't just assume your shaders will work everywhere. Regularly test your code on all the platforms you're targeting to catch issues early.
Understand Your Toolchain: Get familiar with the nuances of your shader compilers and runtime environments. Knowing how they handle names, types, and other language features can help you write more portable code.
Use a Consistent Shading Language: If possible, stick to a single shading language (like GLSL or HLSL) and compile it to SPIR-V for use with Vulkan and other APIs. This can reduce the risk of platform-specific quirks.
Consider a Shader Transpiler: Tools like glslang can help you translate between different shading languages, which can be useful for targeting platforms with specific shader language requirements.

Conclusion

The