From 299dae4a1c0e7db8afae92acf9000ca3dad79cb1 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Thu, 16 May 2024 12:34:03 +0200 Subject: [PATCH] Document Metal support in Internal rendering architecture --- about/list_of_features.rst | 16 +++--- .../internal_rendering_architecture.rst | 52 +++++++++++-------- 2 files changed, 39 insertions(+), 29 deletions(-) diff --git a/about/list_of_features.rst b/about/list_of_features.rst index 42453162858..bf83a6014fc 100644 --- a/about/list_of_features.rst +++ b/about/list_of_features.rst @@ -95,14 +95,14 @@ Editor Rendering --------- -3 rendering *methods* (running over 2 rendering *drivers*) are available: - -- **Forward+**, running over Vulkan 1.0 (with optional Vulkan 1.1 and 1.2 - features). The most advanced graphics backend, suited for desktop platforms - only. Used by default on desktop platforms. -- **Forward Mobile**, running over Vulkan 1.0 (with optional Vulkan 1.1 and 1.2 - features). Less features, but renders simple scenes faster. Suited for mobile - and desktop platforms. Used by default on mobile platforms. +3 rendering *methods* (running over 4 rendering *drivers*) are available: + +- **Forward+**, running over Vulkan / Direct3D 12 / Metal. The most advanced + graphics backend, suited for desktop platforms only. Used by default on + desktop platforms. +- **Forward Mobile**, running over Vulkan / Direct3D 12 / Metal. Less features, + but renders simple scenes faster. Suited for mobile and desktop platforms. + Used by default on mobile platforms. - **Compatibility**, running over OpenGL 3.3 / OpenGL ES 3.0 / WebGL 2.0. The least advanced graphics backend, suited for low-end desktop and mobile platforms. Used by default on the web platform. diff --git a/contributing/development/core_and_modules/internal_rendering_architecture.rst b/contributing/development/core_and_modules/internal_rendering_architecture.rst index 8cd9905335a..6b4ba4e4e69 100644 --- a/contributing/development/core_and_modules/internal_rendering_architecture.rst +++ b/contributing/development/core_and_modules/internal_rendering_architecture.rst @@ -20,11 +20,11 @@ ask in the ``#rendering`` channel of the recommended to go through an OpenGL tutorial such as `LearnOpenGL `__. - Modern low-level APIs (Vulkan/Direct3D 12) require intermediate + Modern low-level APIs (Vulkan/Direct3D 12/Metal) require intermediate knowledge of higher-level APIs (OpenGL/Direct3D 11) to be used effectively. Thankfully, contributors rarely need to work directly with low-level APIs. Godot's renderers are built entirely on OpenGL and - RenderingDevice, which is our abstraction over Vulkan/Direct3D 12. + RenderingDevice, which is our abstraction over Vulkan/Direct3D 12/Metal. .. _doc_internal_rendering_architecture_methods: @@ -108,7 +108,7 @@ Compatibility .. note:: This is the only rendering method available when using the OpenGL driver. - This rendering method is not available when using Vulkan or Direct3D 12. + This rendering method is not available when using Vulkan, Direct3D 12 or Metal. This is a traditional (non-clustered) forward renderer. It's intended for old GPUs that don't have Vulkan support, but still works very efficiently on newer @@ -207,18 +207,23 @@ for more information. Metal ^^^^^ -Godot supports Metal rendering via `MoltenVK `__, -as macOS and iOS do not support Vulkan natively. -This is done automatically when specifying the Vulkan driver in the Project Settings. +Godot provides a native Metal driver that works on all Apple Silicon hardware +(macOS ARM). Compared to using the MoltenVK translation layer, this is +significantly faster, particularly in CPU-bound scenarios. -MoltenVK makes driver maintenance easy at the cost of some performance overhead. -Also, MoltenVK has several limitations that a native Metal driver implementation -wouldn't have. Both the clustered and mobile -:ref:`doc_internal_rendering_architecture_methods` can be used with a Metal -backend via MoltenVK. +Both the Forward+ and Mobile :ref:`doc_internal_rendering_architecture_methods` can be +used with Metal. + +:ref:`doc_internal_rendering_architecture_core_shaders` are shared with the +Vulkan renderer. Shaders are transpiled from GLSL to :abbr:`MSL (Metal Shading Language)` +using SPIRV-Cross. -A native Metal driver is planned in the future for better performance and -compatibility. +Godot also supports Metal rendering via `MoltenVK `__, +which is used as a fallback when native Metal support is not available (e.g. on x86 macOS). + +**This driver is still experimental and only available in Godot 4.x (TODO) and later.** +See the `pull request that introduced Metal support `__ +for more information. OpenGL ^^^^^^ @@ -247,13 +252,13 @@ Summary of rendering drivers/methods The following rendering API + rendering method combinations are currently possible: -- Vulkan + Forward+ -- Vulkan + Forward Mobile +- Vulkan + Forward+ (optionally through MoltenVK on macOS and iOS) +- Vulkan + Forward Mobile (optionally through MoltenVK on macOS and iOS) - Direct3D 12 + Forward+ - Direct3D 12 + Forward Mobile -- Metal + Forward+ (via MoltenVK) -- Metal + Forward Mobile (via MoltenVK) -- OpenGL + Compatibility +- Metal + Forward+ +- Metal + Forward Mobile +- OpenGL + Compatibility (optionally through ANGLE on Windows and macOS) Each combination has its own limitations and performance characteristics. Make sure to test your changes on all rendering methods if possible before opening a @@ -270,10 +275,10 @@ To make the complexity of modern low-level graphics APIs more manageable, Godot uses its own abstraction called RenderingDevice. This means that when writing code for modern rendering methods, you don't -actually use the Vulkan or Direct3D 12 APIs directly. While this is still +actually use the Vulkan, Direct3D 12 or Metal APIs directly. While this is still lower-level than an API like OpenGL, this makes working on the renderer easier, as RenderingDevice will abstract many API-specific quirks for you. The -RenderingDevice presents a similar level of abstraction as Metal or WebGPU. +RenderingDevice presents a similar level of abstraction as WebGPU. **Vulkan RenderingDevice implementation:** @@ -283,6 +288,10 @@ RenderingDevice presents a similar level of abstraction as Metal or WebGPU. - `drivers/d3d12/rendering_device_driver_d3d12.cpp `__ +**Metal RenderingDevice implementation:** + +- `drivers/metal/rendering_device_driver_metal.mm `__ + Core rendering classes architecture ----------------------------------- @@ -736,7 +745,8 @@ Occlusion culling ^^^^^^^^^^^^^^^^^ While modern GPUs can handle drawing a lot of triangles, the number of draw -calls in complex scenes can still be a bottleneck (even with Vulkan and Direct3D 12). +calls in complex scenes can still be a bottleneck (even with Vulkan, Direct3D 12 +and Metal). Godot 4 supports occlusion culling to reduce overdraw (when the depth prepass is disabled) and reduce vertex throughput.