Graphics drivers

Purpose

Godot's graphics drivers fall into two camps:

• RD-based drivers (drivers/vulkan, drivers/d3d12, drivers/metal) implement RenderingDeviceDriver (servers/rendering/rendering_device_driver.h). They back the modern "Forward+" and "Mobile" rendering methods that target Vulkan-style APIs.
• Compatibility driver (drivers/gles3) implements RendererCompositor/RendererCanvasRender/RendererSceneRender directly against OpenGL ES 3. It predates RenderingDevice, supports a wider range of older hardware (and the web), and is selected by the "Compatibility" rendering method.

Vulkan

Layout

drivers/vulkan/
├── rendering_context_driver_vulkan.{cpp,h}        Surface + queue + swapchain
├── rendering_device_driver_vulkan.{cpp,h}         The bulk of the driver
├── godot_vulkan.h                                 Common includes / helpers
├── (per-platform context subclasses live in platform/<os>/)
└── ...

The Vulkan driver targets Vulkan 1.0+ with optional 1.1/1.2/1.3 features. It uses VMA (Vulkan Memory Allocator) (vendored under thirdparty/vma) for memory management. The loader is from thirdparty/vulkan-loader so the engine is independent of any system Vulkan installation; it picks up the runtime via the standard ICD search.

Per-platform surface creation:

• Linux: VK_KHR_xcb_surface (X11) or VK_KHR_wayland_surface (Wayland).
• Windows: VK_KHR_win32_surface.
• macOS / iOS / visionOS: through MoltenVK (thirdparty/volk_loader.cpp + MoltenVK's metal-surface extension).
• Android: VK_KHR_android_surface.

Features the driver targets aggressively: dynamic rendering (Vulkan 1.3 or VK_KHR_dynamic_rendering), descriptor indexing, push descriptors, separate depth/stencil layouts, sub-passes for tile-based optimization (Mobile renderer).

What the driver provides

RenderingDeviceDriverVulkan implements:

• Buffer / texture / sampler / framebuffer / render pass / pipeline creation.
• Synchronization primitives (semaphores, fences, events).
• Command buffer allocation + secondary buffers.
• Memory upload (transfer queue + staging buffers).
• Multi-frame in-flight fencing for the swapchain.
• VRS attachments (VK_KHR_fragment_shading_rate).

The driver is multi-threaded internally — command buffer recording can happen on the rendering thread while transfers happen on a dedicated transfer queue.

Direct3D 12

Layout

drivers/d3d12/
├── rendering_context_driver_d3d12.{cpp,h}     IDXGIFactory + swapchain
├── rendering_device_driver_d3d12.{cpp,h}      Bulk of the driver
└── ...

Direct3D 12 is the recommended modern Windows backend. The driver targets D3D12 with feature level 11_0 minimum and uses D3D12 Memory Allocator (vendored).

Key choices:

• Bindless via descriptor heaps + dynamic descriptor copying.
• DXC for SPIR-V→DXIL cross-compilation when shaders arrive in SPIR-V (built-in shaders are pre-translated via the build).
• DirectStorage and Variable Rate Shading via D3D12 extensions where the runtime supports them.
• ID3D12CommandQueue + ID3D12CommandAllocator pools per thread.

D3D12 is Windows-only; Xbox / GDK builds use the same driver with a few #ifdef _GAMING_XBOX paths.

Metal

Layout

drivers/metal/
├── rendering_context_driver_metal.{mm,h}      MTLDevice + CAMetalLayer drawable
├── rendering_device_driver_metal.{mm,h}       Bulk of the driver
├── metal_objects.{mm,h}, metal_utils.{mm,h}, metal_pixel_formats.{mm,h}
└── ...

Metal is Apple's native API on macOS, iOS, and visionOS. The driver:

• Targets Metal 2.0+ and uses MetalFX upscaling where available.
• Uses argument buffers for bindless-style resource binding.
• Cross-compiles shaders from SPIR-V to MSL via SPIRV-Cross (vendored under thirdparty/spirv-cross), with a per-pipeline cache.
• Integrates with CAMetalLayer for window presentation.
• Supports MetalFX temporal AA + scaling.
• Tile-based GPU optimizations via MTLRenderCommandEncoder::useResource hints.

Metal is shared by macOS, iOS, and visionOS — the per-platform code is mostly the surface creation (NSView vs UIView vs CALayer hosting).

OpenGL ES 3 (Compatibility renderer)

Layout

drivers/gles3/
├── rasterizer_gles3.{cpp,h}                  RendererCompositor implementation
├── rasterizer_canvas_gles3.{cpp,h}           2D draw path
├── rasterizer_scene_gles3.{cpp,h}            3D scene draw path
├── effects/                                   2D + 3D effect passes
├── environment/                               Sky + GI (limited compared to RD)
├── shaders/                                   GLES3-specific shaders
├── shader_gles3.{cpp,h}                       Shader compilation/linking + uniform handling
├── shader_glsl_gles3.{cpp,h}                  Godot shader → GLSL ES 300
├── storage/                                   GL-side texture/mesh/material storage
└── (per-platform GL context lives in drivers/gl_context/, drivers/egl/ or platforms)

GLES3 is the Compatibility renderer. It predates the RD architecture and implements the same Renderer* interfaces but uses GL state directly. Notable characteristics:

• Targets GL ES 3.0 (with optional 3.1/3.2 features via extensions).
• Runs on Android, iOS (deprecated by Apple, still works), Linux, macOS (legacy), Windows (via ANGLE), and the Web (WebGL2).
• Lacks some advanced features the RD path supports (no compute particles on most GL ES 3.0 devices, fewer post-process effects, no SDFGI/VoxelGI).
• Strong choice when targeting low-end or legacy hardware, mobile devices without Vulkan, and the web.

Selecting a backend

At runtime the user picks a "rendering method":

• Forward+ — RD path with the clustered forward renderer; maps to Vulkan / D3D12 / Metal.
• Mobile — RD path with the simplified mobile renderer.
• Compatibility — GLES3.

And a "rendering driver":

• vulkan, d3d12, metal, opengl3, opengl3_es.

The combinations available depend on the platform. The CLI flags are --rendering-method and --rendering-driver, mirrored in project settings under rendering/renderer/.

Key abstractions

Abstraction	File	Role
RenderingDeviceDriver	servers/rendering/rendering_device_driver.h	Vendor-neutral GPU API
RenderingContextDriver	servers/rendering/rendering_context_driver.h	Per-driver context + swapchain
RenderingDeviceDriverVulkan	drivers/vulkan/rendering_device_driver_vulkan.cpp	Vulkan implementation
RenderingDeviceDriverD3D12	drivers/d3d12/rendering_device_driver_d3d12.cpp	D3D12 implementation
RenderingDeviceDriverMetal	drivers/metal/rendering_device_driver_metal.mm	Metal implementation
RasterizerGLES3	drivers/gles3/rasterizer_gles3.cpp	Compatibility renderer top-level

Entry points for modification

• Adding GPU features → RenderingDeviceDriver interface plus per-driver implementation.
• New backend (e.g., WebGPU) → implement RenderingDeviceDriver + RenderingContextDriver. The Vulkan / D3D12 / Metal trio are templates.
• GLES3 tweaks → drivers/gles3/; remember the same files compile for desktop GL3.3 + GL ES 3 + WebGL2 with #ifdefs.