nCine::RHI::Metal::MetalDevice class
#include <nCine/Graphics/RHI/Metal/MetalDevice.h>

Pipeline-state and draw-call facade of the Metal backend (aliased as RHI::Device).

Exposes the OpenGL device's surface (blending, depth, cull, scissor, viewport, clear and the draw calls) so the backend-neutral render pipeline drives it unchanged.

The device also owns the real MTL::Device, MTL::CommandQueue and the CAMetalLayer SDL attaches to the window (via CreateSwapchain(), called by the SDL window backend). Every frame is one MTL::CommandBuffer; draws are recorded into a render command encoder per render target, and PresentFrame() acquires a drawable, draws the rendered screen texture into it and commits (the buffer-swap equivalent).

The scene is rendered top-down, which is both the RHI's convention (see RhiFwd.h) and Metal's own: clip-space y = +1 is the top row of every target and the first one in memory, so rendered and CPU-uploaded textures agree with no conversion, viewports and scissors map to Metal's as they are, and the present pass copies the screen texture into the drawable row for row.

Public types

struct ScissorState
struct BlendingState
struct DepthTestState
struct CullFaceState

Public static functions

static void SetBlendingEnabled(bool enabled)
static void SetBlendingFactors(nCine::BlendingFactor srcRgb, nCine::BlendingFactor dstRgb, nCine::BlendingFactor srcAlpha, nCine::BlendingFactor dstAlpha)
static auto GetBlendingState() -> BlendingState
static void SetBlendingState(const BlendingState& state)
static void SetDepthTestEnabled(bool enabled)
static void SetDepthMaskEnabled(bool enabled)
static auto GetDepthTestState() -> DepthTestState
static void SetDepthTestState(const DepthTestState& state)
static void SetCullFaceEnabled(bool enabled)
static auto GetCullFaceState() -> CullFaceState
static void SetCullFaceState(const CullFaceState& state)
static auto GetScissorState() -> ScissorState
static void SetScissorState(const ScissorState& state)
static void SetScissor(const Recti& rect)
static void SetScissorTestEnabled(bool enabled)
static auto GetViewport() -> Recti
static void SetViewport(const Recti& rect)
static void InitViewport(std::int32_t x, std::int32_t y, std::int32_t width, std::int32_t height)
static auto GetClearColor() -> Colorf
static void SetClearColor(const Colorf& color)
static void Clear(ClearFlags flags)
static void DrawArrays(PrimitiveType primitive, std::int32_t firstVertex, std::int32_t numVertices)
static void DrawArraysInstanced(PrimitiveType primitive, std::int32_t firstVertex, std::int32_t numVertices, std::int32_t numInstances)
static void DrawElements(PrimitiveType primitive, std::uint32_t numIndices, IndexFormat indexFormat, std::uintptr_t indexOffset, std::int32_t baseVertex)
static void DrawElements(PrimitiveType primitive, std::uint32_t numIndices, std::uintptr_t indexOffset, std::int32_t baseVertex)
static void DrawElementsInstanced(PrimitiveType primitive, std::uint32_t numIndices, IndexFormat indexFormat, std::uintptr_t indexOffset, std::int32_t numInstances, std::int32_t baseVertex)
static void DrawElementsInstanced(PrimitiveType primitive, std::uint32_t numIndices, std::uintptr_t indexOffset, std::int32_t numInstances, std::int32_t baseVertex)
static auto InsertFence() -> FenceHandle
static void DeleteFence(FenceHandle& fence)
static auto ClientWaitFence(FenceHandle fence, std::uint64_t timeoutNs) -> bool
static void SetupInitialState()
static void BindProgram(MetalShaderProgram* program): Records the currently bound shader program.
static auto CurrentProgram() -> MetalShaderProgram*: Returns the currently bound shader program.
static void BindTexture(std::uint32_t unit, const MetalTexture* texture): Records the texture bound to a texture unit.
static void UnbindTexture(const MetalTexture* texture): Clears a texture from every unit it is bound to (called from ~MetalTexture to avoid a dangling pointer).
static auto GetBoundTexture(std::uint32_t unit) -> const MetalTexture*: Returns the texture bound to a texture unit.
static void BindUniformRange(std::uint32_t index, const std::uint8_t* data, std::uint32_t size): Records the host data range bound to a uniform binding point.
static void UnbindRenderTarget(const MetalRenderTarget* renderTarget): Clears a render target from the device if it is the current one (called from ~MetalRenderTarget).
static void SetRenderTarget(MetalRenderTarget* renderTarget): Records the current draw render target (its color attachments receive the pixels).
static void OnRenderTargetChanged(const MetalRenderTarget* renderTarget): Ends the open render pass if it draws into renderTarget, whose attachments just changed.
static void OnShaderProgramDestroyed(MetalShaderProgram* program): Drops any cached render pipelines keyed on a shader program being destroyed/reset.
static auto currentRenderTargetInternal() -> MetalRenderTarget*: Returns the currently bound draw render target (nullptr = the screen).
static auto MaxUniformBindingsPublic() -> std::uint32_t: Number of uniform binding slots tracked by BindUniformRange().
static void GetUniformRange(std::uint32_t index, const std::uint8_t*& data, std::uint32_t& size): Returns the host data range bound to a uniform binding slot.
static auto CreateSwapchain(void* windowHandle, std::int32_t width, std::int32_t height, bool vsync) -> bool: Creates the Metal device, command queue and the window's layer.
static void DestroySwapchain(): Releases the layer, the screen texture and the device.
static void ResizeSwapchain(std::int32_t width, std::int32_t height): Resizes the layer's drawables and the screen texture to the new drawable size (waits for the GPU to go idle first).
static void PresentFrame(): Acquires a drawable, draws the rendered screen texture into it, presents it and commits the frame (the buffer-swap equivalent).
static void BeginGpuTiming(): No-op (a command buffer records its own GPU times, which PresentFrame() reports once it completes).
static void EndGpuTiming(): No-op.
static auto CreateSecondarySwapchain(void* windowHandle, std::int32_t width, std::int32_t height) -> void*: Creates an additional Metal view and layer for a secondary window.
static void DestroySecondarySwapchain(void* handle): Releases a secondary view and layer created by CreateSecondarySwapchain().
static void ResizeSecondarySwapchain(void* handle, std::int32_t width, std::int32_t height): Resizes a secondary layer's drawables.
static void QueueSecondaryPresent(void* handle, const MetalTexture* source): Hands the texture holding a secondary window's contents over to the next PresentFrame().
static auto GetMaxTextureDimension() -> std::int32_t: Returns the largest 2D texture dimension (16384 on every Mac GPU family).
static auto GetUniformBufferOffsetAlignment() -> std::int32_t: Returns the constant-buffer bind-offset alignment the uniform ring honors (256 bytes on macOS).
static auto GetMaxUniformBufferRange() -> std::int32_t: Returns the uniform range the batch size is derived from (64 KB, the budget the offline MSL baked its BATCH_SIZE from).

Constructors, destructors, conversion operators

MetalDevice() deleted
~MetalDevice() deleted

Function documentation

static bool nCine::RHI::Metal::MetalDevice::CreateSwapchain(void* windowHandle, std::int32_t width, std::int32_t height, bool vsync)

Creates the Metal device, command queue and the window's layer.

Parameters
windowHandle	The `SDL_Window` (created with `SDL_WINDOW_METAL`), passed as a `void` so the window backend does not need the Metal headers. The backend attaches a Metal view to it through the SDL Metal API and configures the view's `CAMetalLayer`.
width	Drawable width in pixels
height	Drawable height in pixels
vsync	Whether PresentFrame() presents with vertical sync (`displaySyncEnabled`)
Returns	`true` if the device and the layer were created

static void* nCine::RHI::Metal::MetalDevice::CreateSecondarySwapchain(void* windowHandle, std::int32_t width, std::int32_t height)

Creates an additional Metal view and layer for a secondary window.

Parameters
windowHandle	`SDL_Window` of the secondary window, passed as a `void`
width	Drawable width in pixels
height	Drawable height in pixels
Returns	An opaque handle to pass to the other `Secondary` functions, or `nullptr` if the view failed

Used by the ImGui multi-viewport support for the windows it spawns when a panel is dragged out of the main one. Only their presentation lives in the backend: the contents are rendered through the ordinary RHI path into an off-screen render target, whose texture is handed over for the frame with QueueSecondaryPresent(). PresentFrame() then draws each queued texture into its window's drawable and presents it with the frame's single commit.