Metal: Stable argument buffers; GPU rendering crashes; visionOS exports

[stuartcarnie]

Supersedes #110683

Note

Some of the changes were moving code from Metal 3-specific files into a common file, to allow for reuse when adding Metal 4 support.

Summary

The PR addresses the following bugs and regressions:

• Rendering artefacts and GPU crashes for all Apple Silicon
  • Reproducible on on iOS and visionOS due to lower memory specs
  • Supersedes Metal: fix incorrect usage of useResources: APIs #110683
• Unable to export and bake shaders for visionOS
• Incorrect Metal Shader Language and OS feature targeting in shader baker
• Performance regression using UMA buffers

The PR adds the following improvements and optimisations:

• Reduce memory and CPU usage by generating stable argument buffer bindings for shaders
• Uses lodBias on 26.0+ OSs and removes the warning "Metal does not support LOD bias for samplers."
• Uses GPU encoded MTLEvent rather than callbacks to handle frame synchronisation on supported OSs
• Adds support for debugPrintfEXT in Metal – which is propagated through. See this for more info

Details

FIX: Rendering artefacts and GPU crashes

The correct usage of useResources:count:usage:stages: and useResources:count:usage: was previously misunderstood, assuming that all resources must be made resident before calling endEncoding on the MTLCommandEncoder. The documentation is clear that resources used by subsequent draw calls must be made resident before encoding the draw or dispatch command:

You can make multiple resources resident (available in GPU memory) for the remaining duration of the render pass by calling this method. Call the method before encoding draw calls that may access the elements of resources through an argument buffer. The method ensures each resource is in a format that’s compatible with the shaders that depend on it.

Note

Stable argument buffers reduced the complexity and CPU resources required to manage this data.

---

FIX: Unable to export and bake shaders for visionOS

visionOS was omitted from the shader baking export, so no shaders were baked and Godot would generate errors.

---

FIX: Incorrect Metal Shader Language and OS feature targeting

When Metal shaders are generated from SPIR-V and available features determined, only two variables were considered:

• Minimum GPU, and Metal language version

However, the minimum OS target version must also be considered, as certain APIs and Metal language features may be unavailable. Improved the Metal shader container to capture all three to determine the available features and what shader features should be generated.

The shader features and then passed to the RenderingDeviceDriverMetal to ensure it only uses the features specified in the generated shader.

Note

In a future PR, we will add support for baking multiple shader versions, so that the target system can choose the best available based on the OS and GPU.

FIX: Performance regression using UMA buffers

UMA buffers for Metal does not use argument buffers when using a UMA buffer, which is all canvas 2D rendering. With the previous implementation, all slots were updated every time each time a uniform set changed. For 2D rendering, when a texture changes frequently, this resulted in costly calls to the Metal command encoder to encode all slots, even if it was only the texture, and possibly the sampler, had changed. This update caches the slots that have changed, so only the minimal Metal binding calls are executed. This should improve performance across the board for all devices using direct / slot binding in Metal

---

IMPROVEMENT: Reduce memory and CPU usage

The changes to use stable argument buffer bindings means that Metal shaders generated from SPIR-V now produce consistent argument buffer layouts across shader versions and pipeline stages, by using the information from the RenderingShaderContainer. This class has had some improvements to include additional reflected data that is passed to the device-specific shader containers.

By ensuring argument buffer layout is consistent, we no longer have to generate an argument buffer per shader version and stage, which reduces the calculation and layout of 100s per shader variant, in some cases! This was happening for every material in the Bistro demo, which had 100s of materials. That resulted in unique argument buffers for every shader material.

Important

These changes are also preparation for adding Metal 4 support in the future

These changes had small improvements across the board for the Godot reflection benchmark.

• 45 gm is the current 4.5.1 version
• 46 args disables is when argument buffers are disabled, and slot or direct binding is used
• 46 args enabled is when argument buffers are enabled

FPS

Godot Version	Description	FPS Mean	FPS Median	FPS 5% Low	FPS 99% High
4.5	gm	195	185	128	380
4.6	dev args disabled	197	186	130	383
4.6	dev args enabled	199	189	132	392

GPU times

Godot Version	Description	Frames	GPU Time Mean (ms)	GPU Time Median (ms)	GPU Time 99% (ms)
4.5	gm	4995	1.95	1.89	3.77
4.6	dev args disabled	4995	1.94	1.91	3.20
4.6	dev args enabled	4996	1.87	1.79	3.02

Memory improvements

Savings of about 1MB with fewer argument buffer allocations

Godot Version	Description	GPU Memory Mean (MB)	Process Memory Mean (MB)	Process Memory Max (MB)
4.5	gm	788	1,585	1,590
4.6	dev args disabled	787	1,529	1,536
4.6	dev args enabled	787	1,521	1,526

[stuartcarnie]

Device Profile is now keyed by platform (macOS, iOS, etc), GPU and minimum OS version. This ensures that when generating or baking the shader, it selects the correct features based on the target OS also.

[stuartcarnie]

Fixes GPU corruption / crashes by tracking resource usage and ensuring they are resident prior to each command (draw, dispatch, etc)

[stuartcarnie]

Moved the implementation of these from the RenderingDeviceDriverMetal into MDCommandBuffer, for consistency

[stuartcarnie]

Now we have a single argument buffer per uniform set vs 100s or more

[stuartcarnie]

The following block was moved from the RenderingDeviceDriverMetal into here, to be consistent with the other functions.

[stuartcarnie]

We need to account for visionOS when generating Metal binaries

[stuartcarnie]

We define the reflect objects in the Shader Container, so that data flows outwards from Shader Container. It allows us to evolve what we reflect that is passed to the driver-specific shader containers.

Further, the ReflectShader type is passed to the driver-specific implementations to inspect the reflected SPIR-V.

Previously we were traversing the reflected SPIR-V and constructing RDD::ShaderReflection, which is used by the drivers and RenderingDriver. We were also using ShaderReflection to construct the internal state of the RenderingShaderContainer and also constructing the ShaderReflection from the internal state. We wanted to add more metadata to ShaderReflection, so Metal could build stable bindings, but that would mean changing ShaderReflection.

[stuartcarnie]

Ensure we can bake shaders for visionOS

[stuartcarnie]

❤️ Thanks for the feedback, @AThousandShips – will incorporate all your changes!

[stuartcarnie]

Thanks @AThousandShips – all your feedback has been incorporated

[stuartcarnie]

The BindingCache is used to avoid redundant binding calls to a MTLCommandEncoder

[stuartcarnie]

Removed dead code from #111183

[stuartcarnie]

This allows us to greatly simplify the direct binding code, but unifying MTLRenderCommandEncoder and MTLComputeCommandEncoder binding and caching

[clayjohn]

Let's go ahead with this.

I still have a bit of reservation about the duplication between RDC and ShaderContainer that this introduced. But I understand your rationale for it and can't think of a better option. I don't want to block this work due to my hesitation since it is most likely a result of my lack of familiarity with the ShaderContainer code.

So to move this forward I suggest that we merge this as-is. Then, when Dario is back from vacation, I will ask him to take a look as well and point out if there are any potential issues, or perhaps a better way to avoid the duplication that neither of us are seeing.

[Repiteo]

Thanks!

[stuartcarnie]

I still have a bit of reservation about the duplication between RDC and ShaderContainer that this introduced. But I understand your rationale for it and can't think of a better option. I don't want to block this work due to my hesitation since it is most likely a result of my lack of familiarity with the ShaderContainer code.

Thanks @clayjohn – and I agree.

I will spend some time looking at how this could be improved as a more targeted PR that doesn't have as many broad changes. I realise this turned into a large change, which wasn't my intention or at all ideal, but there were many stones unturned…