Typed immutable descriptors for donner::gpu resource creation. More...

#include <array>
#include <chrono>
#include <cstdint>
#include <optional>
#include <ostream>
#include <type_traits>
#include <variant>
#include <vector>
#include "donner/base/RcString.h"
#include "donner/gpu/Handles.h"

Include dependency graph for Descriptors.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	donner::gpu::IsBitmaskEnum< T >
	Marks an enum as a bitmask, enabling operator\|, operator&, operator\|=, and HasAllFlags. More...
struct	donner::gpu::NativeSurfaceHandle
	The platform object a surface presents to. More...
struct	donner::gpu::SurfaceDescriptor
	Descriptor for Device::createSurface. More...
struct	donner::gpu::MapSliceReport
	What one backend wait slice found, and how it spent the slice. More...
struct	donner::gpu::MapWaitReport
	How a bounded wait for a mapping ended, and how its slices were spent. More...
struct	donner::gpu::MapWaitParams
	Bounds of a wait for a pending buffer mapping. More...
struct	donner::gpu::SerialWaitResult
	How a wait for a submission serial ended, and how long it ran. More...
struct	donner::gpu::Extent2d
	A 2D extent in texels. More...
struct	donner::gpu::Origin2d
	A 2D texel coordinate, used as the corner a copy region starts at. The default (0, 0) is the whole-rect-from-the-origin convention every copy used before sub-rectangle copies existed. More...
struct	donner::gpu::BufferDescriptor
	Descriptor for Device::createBuffer. More...
struct	donner::gpu::TextureDescriptor
	Descriptor for Device::createTexture. All Donner textures are 2D, single-mip. More...
struct	donner::gpu::TextureViewDescriptor
	Descriptor for Device::createTextureView. Views cover the whole texture. More...
struct	donner::gpu::SurfaceConfiguration
	Configuration a surface presents under. More...
struct	donner::gpu::SurfaceCapabilities
	What a surface supports, for choosing a SurfaceConfiguration. More...
struct	donner::gpu::SamplerDescriptor
	Descriptor for Device::createSampler. More...
struct	donner::gpu::BindGroupLayoutEntry
	One entry of a BindGroupLayoutDescriptor. More...
struct	donner::gpu::BindGroupLayoutDescriptor
	Descriptor for Device::createBindGroupLayout. More...
struct	donner::gpu::PipelineLayoutDescriptor
	Descriptor for Device::createPipelineLayout. More...
struct	donner::gpu::WorkgroupSize
	Workgroup size a compute entry point declares. More...
struct	donner::gpu::ComputeEntryPointInfo
	One compute entry point a shader module contains, with the workgroup size compiled into it. More...
struct	donner::gpu::ShaderBufferBindingInfo
	One buffer statically used by an entry point, including uses through helper functions. Generated from the same IR as shader source; the runtime never parses shader source. More...
struct	donner::gpu::ShaderModuleDescriptor
	Descriptor for Device::createShaderModule. Source is trusted generated build output, never runtime input from documents. Exactly one source representation must be populated: text kinds (ShaderSourceKind::Wgsl, ShaderSourceKind::Msl) require nonempty sourceText and empty spirvWords; ShaderSourceKind::Spirv requires nonempty spirvWords and empty sourceText. Device::createShaderModule fails closed on any other combination. More...
struct	donner::gpu::VertexAttribute
	One vertex attribute within a VertexBufferLayout. More...
struct	donner::gpu::VertexBufferLayout
	Layout of one vertex buffer slot of a render pipeline. More...
struct	donner::gpu::BlendComponent
	One blend term (color or alpha) of a BlendState. More...
struct	donner::gpu::BlendState
	Blend state for one color target. More...
struct	donner::gpu::ColorTargetState
	One color target of a render pipeline's fragment stage. More...
struct	donner::gpu::VertexState
	Vertex stage of a RenderPipelineDescriptor. More...
struct	donner::gpu::FragmentState
	Fragment stage of a RenderPipelineDescriptor. More...
struct	donner::gpu::ComputeState
	Compute stage of a ComputePipelineDescriptor. More...
struct	donner::gpu::ComputePipelineDescriptor
	Descriptor for Device::createComputePipeline. More...
struct	donner::gpu::ComputePassDescriptor
	Descriptor for CommandEncoder::beginComputePass. More...
struct	donner::gpu::RenderPipelineDescriptor
	Descriptor for Device::createRenderPipeline. More...
struct	donner::gpu::RenderPassColorAttachment
	One color attachment of a RenderPassDescriptor. More...
struct	donner::gpu::RenderPassDescriptor
	Descriptor for CommandEncoder::beginRenderPass. More...
struct	donner::gpu::TexelCopyTextureInfo
	Source texture of a texture-to-buffer copy. Copies start at texel (0, 0). More...
struct	donner::gpu::TexelCopyBufferLayout
	Byte layout of texel rows in buffer or host memory for copy operations. More...
struct	donner::gpu::BufferBinding
	A buffer range bound through a bind group. More...
struct	donner::gpu::TextureViewBinding
	A texture view bound through a bind group. More...
struct	donner::gpu::SamplerBinding
	A sampler bound through a bind group. More...
struct	donner::gpu::BindGroupEntry
	One entry of a BindGroupDescriptor. The resource alternative must match the BindingType of the layout entry with the same binding index. More...
struct	donner::gpu::BindGroupDescriptor
	Descriptor for Device::createBindGroup. More...

Namespaces
namespace	donner
	Top-level Donner namespace, which is split into different sub-namespaces such as donner::svg and donner::css.

Concepts
concept	donner::gpu::BitmaskEnum
	Concept satisfied by enums marked with donner::gpu::IsBitmaskEnum.

Enumerations
enum class	donner::gpu::TextureFormat : uint8_t { RGBA8Unorm , BGRA8Unorm , R8Unorm , RGBA32Float }
	Texture formats used by Donner render targets, masks, and image uploads. More...
enum class	donner::gpu::TextureUsage : uint32_t { None = 0 , RenderAttachment = 1 << 0 , Sampled = 1 << 1 , CopySrc = 1 << 2 , CopyDst = 1 << 3 , StorageBinding = 1 << 4 }
	Texture usage flags. Combinable with \|. More...
enum class	donner::gpu::BufferUsage : uint32_t { None = 0 , Vertex = 1 << 0 , Index = 1 << 1 , Uniform = 1 << 2 , Storage = 1 << 3 , CopySrc = 1 << 4 , CopyDst = 1 << 5 , MapRead = 1 << 6 }
	Buffer usage flags. Combinable with \|. More...
enum class	donner::gpu::NativeSurfaceKind : uint8_t { MetalLayer , XlibWindow , WaylandSurface , CanvasSelector , EmbedderSurface , Headless }
	Platform object kind a donner::gpu::NativeSurfaceHandle names. More...
enum class	donner::gpu::PresentMode : uint8_t { Fifo , Immediate , Mailbox }
	How presented frames are paced. More...
enum class	donner::gpu::SurfaceAlphaMode : uint8_t { Opaque , Premultiplied , Inherit }
	How a surface composites its alpha channel with what is behind it. More...
enum class	donner::gpu::MapMode : uint8_t { Read }
	How a mapped buffer range is accessed from the host. More...
enum class	donner::gpu::MapSliceState : uint8_t { Pending , Ready , DeviceLost , Failed }
	State of a pending buffer mapping after one backend wait slice. More...
enum class	donner::gpu::MapWaitOutcome : uint8_t { Ready , TimedOut , Cancelled , DeviceLost , Failed }
	Outcome of a bounded wait for a pending buffer mapping. More...
enum class	donner::gpu::MapWaitKind : uint8_t { Polled , CompletionEvent }
	How a backend spent a wait for a pending buffer mapping. More...
enum class	donner::gpu::SerialWaitEnd : uint8_t { Completed , Stalled , Failed }
	How a wait for a submission serial that gives up only on a stall ended; see donner::gpu::Device::waitForSerialUnlessStalled. More...
enum class	donner::gpu::ShaderStage : uint32_t { None = 0 , Vertex = 1 << 0 , Fragment = 1 << 1 , Compute = 1 << 2 }
	Shader stage visibility flags for bindings. Combinable with \|. More...
enum class	donner::gpu::ColorWriteMask : uint32_t { None = 0 , Red = 1 << 0 , Green = 1 << 1 , Blue = 1 << 2 , Alpha = 1 << 3 , All = Red \| Green \| Blue \| Alpha }
	Per-channel color write mask for a color target. Combinable with \|. More...
enum class	donner::gpu::FilterMode : uint8_t { Nearest , Linear }
	Sampler minification/magnification filter. More...
enum class	donner::gpu::AddressMode : uint8_t { ClampToEdge , Repeat }
	Sampler texture addressing mode. More...
enum class	donner::gpu::VertexFormat : uint8_t { Float32x2 , Float32x4 , Uint32 }
	Vertex attribute formats used by Donner pipelines. More...
enum class	donner::gpu::VertexStepMode : uint8_t { Vertex , Instance }
	Rate at which a vertex buffer is stepped through during a draw. More...
enum class	donner::gpu::IndexFormat : uint8_t { Uint16 , Uint32 }
	Element width of an index buffer bound with RenderPassEncoder::setIndexBuffer. Every backend honors the full unsigned range of the width; a device that cannot is reported through Device::supportsFullIndexRange and refuses the binding. More...
enum class	donner::gpu::PrimitiveTopology : uint8_t { TriangleList , TriangleStrip }
	Primitive topology for render pipelines. More...
enum class	donner::gpu::CullMode : uint8_t { None , Back }
	Face culling mode for render pipelines. More...
enum class	donner::gpu::BlendFactor : uint8_t { Zero , One , SrcAlpha , OneMinusSrcAlpha , OneMinusDstAlpha }
	Blend factors used by Donner pipelines (premultiplied-alpha compositing). More...
enum class	donner::gpu::BlendOperation : uint8_t { Add , Max }
	Blend operations used by Donner pipelines. More...
enum class	donner::gpu::BindingType : uint8_t { UniformBuffer , ReadOnlyStorageBuffer , SampledTexture2dFloat , FilteringSampler , WriteOnlyStorageTexture2d , SampledTexture2dUnfilterableFloat }
	Type of resource a bind group layout entry expects. More...
enum class	donner::gpu::LoadOp : uint8_t { Clear , Load }
	Load operation for a render pass color attachment. More...
enum class	donner::gpu::StoreOp : uint8_t { Store , Discard }
	Store operation for a render pass color attachment. More...
enum class	donner::gpu::ShaderSourceKind : uint8_t { Wgsl , Msl , Spirv }
	Shader source language of a donner::gpu::ShaderModuleDescriptor. More...
enum class	donner::gpu::SurfaceStatus : uint8_t { Success , Outdated , Lost , DeviceLost , Timeout }
	Outcome of acquiring from or presenting to a surface. More...

Functions
template<BitmaskEnum T>
constexpr T	donner::gpu::operator\| (T lhs, T rhs)
	Bitwise-or for bitmask enums.
template<BitmaskEnum T>
constexpr T	donner::gpu::operator& (T lhs, T rhs)
	Bitwise-and for bitmask enums.
template<BitmaskEnum T>
constexpr T &	donner::gpu::operator\|= (T &lhs, T rhs)
	Bitwise-or-assign for bitmask enums.
template<BitmaskEnum T>
constexpr bool	donner::gpu::HasAllFlags (T value, T flags)
	Returns true if `value` contains every flag in `flags`.
constexpr uint32_t	donner::gpu::IndexFormatByteSize (IndexFormat format)
	Bytes occupied by one index of `format`, or 0 for an unknown enumerator so callers fail closed instead of dividing by a guess.
std::ostream &	donner::gpu::operator<< (std::ostream &os, TextureFormat value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, TextureUsage value)
	Ostream output operator, e.g. RenderAttachment\|CopySrc, or None when no flags are set.
std::ostream &	donner::gpu::operator<< (std::ostream &os, BufferUsage value)
	Ostream output operator, e.g. Vertex\|CopyDst, or None when no flags are set.
std::ostream &	donner::gpu::operator<< (std::ostream &os, ShaderStage value)
	Ostream output operator, e.g. Vertex\|Fragment, or None when no flags are set.
std::ostream &	donner::gpu::operator<< (std::ostream &os, ColorWriteMask value)
	Ostream output operator, e.g. Red\|Green\|Blue\|Alpha, or None when no flags are set.
std::ostream &	donner::gpu::operator<< (std::ostream &os, FilterMode value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, AddressMode value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, VertexFormat value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, VertexStepMode value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, IndexFormat value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, PrimitiveTopology value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, CullMode value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, BlendFactor value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, BlendOperation value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, BindingType value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, LoadOp value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, StoreOp value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, ShaderSourceKind value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, NativeSurfaceKind value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, PresentMode value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, SurfaceAlphaMode value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, MapSliceState value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, MapWaitOutcome value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, MapWaitKind value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, SerialWaitEnd value)
	Ostream output operator.
std::ostream &	donner::gpu::operator<< (std::ostream &os, const SerialWaitResult &value)
	Ostream output operator, e.g. {Stalled, 5003 ms}.
std::ostream &	donner::gpu::operator<< (std::ostream &os, const MapSliceReport &value)
	Ostream output operator, e.g. {Pending, Polled}.
std::ostream &	donner::gpu::operator<< (std::ostream &os, const MapWaitReport &value)
	Ostream output operator, e.g. {Ready, CompletionEvent}.
bool	donner::gpu::IsKnownEnumValue (TextureFormat value)
	Returns true if `value` is a known enumerator. Every enum arriving through a descriptor is checked with these overloads so out-of-range casts fail closed with donner::gpu::GpuErrorType::InvalidDescriptor instead of flowing into layout or copy math.
bool	donner::gpu::IsKnownEnumValue (FilterMode value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (AddressMode value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (VertexFormat value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (VertexStepMode value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (IndexFormat value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (PrimitiveTopology value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (CullMode value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (BlendFactor value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (BlendOperation value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (BindingType value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (LoadOp value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (StoreOp value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (ShaderSourceKind value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (NativeSurfaceKind value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (PresentMode value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsKnownEnumValue (SurfaceAlphaMode value)
	Returns true if `value` is a known enumerator.
bool	donner::gpu::IsValidBitmask (TextureUsage value)
	Returns true if `value` contains only known flag bits (an empty mask is bit-valid; emptiness is validated separately where required).
bool	donner::gpu::IsValidBitmask (BufferUsage value)
	Returns true if `value` contains only known flag bits.
bool	donner::gpu::IsValidBitmask (ShaderStage value)
	Returns true if `value` contains only known flag bits.
bool	donner::gpu::IsValidBitmask (ColorWriteMask value)
	Returns true if `value` contains only known flag bits.
uint32_t	donner::gpu::TextureFormatBytesPerTexel (TextureFormat format)
	Bytes per texel for a donner::gpu::TextureFormat.
uint32_t	donner::gpu::VertexFormatByteSize (VertexFormat format)
	Byte size of a donner::gpu::VertexFormat.
std::ostream &	donner::gpu::operator<< (std::ostream &os, SurfaceStatus value)
	Ostream output operator.

Detailed Description

Typed immutable descriptors for donner::gpu resource creation.

The enum and descriptor surface is intentionally narrow: it covers the operations Geode's rendering, filtering, and the editor actually use, not a general GPU API. Descriptors are plain value types, immutable by convention; all validation happens in donner::gpu::Device operations, which fail closed on malformed input.

Enumeration Type Documentation

◆ AddressMode

enum class donner::gpu::AddressMode : uint8_t

strong

Sampler texture addressing mode.

Enumerator
ClampToEdge	Clamp coordinates to the edge texel.
Repeat	Wrap coordinates (pattern tiling).

◆ BindingType

enum class donner::gpu::BindingType : uint8_t

strong

Type of resource a bind group layout entry expects.

Enumerator
UniformBuffer	Uniform buffer binding.
ReadOnlyStorageBuffer	Read-only storage buffer binding.
SampledTexture2dFloat	Sampled 2D float texture binding.
FilteringSampler	Filtering sampler binding.
WriteOnlyStorageTexture2d	Write-only 2D storage texture binding (compute stage only).
SampledTexture2dUnfilterableFloat	Float texture read with texel loads, without filtering.

◆ BlendFactor

enum class donner::gpu::BlendFactor : uint8_t

strong

Blend factors used by Donner pipelines (premultiplied-alpha compositing).

Enumerator
Zero	Factor 0.
One	Factor 1.
SrcAlpha	Factor (source alpha).
OneMinusSrcAlpha	Factor (1 - source alpha).
OneMinusDstAlpha	Factor (1 - destination alpha); destination-over compositing.

◆ BlendOperation

enum class donner::gpu::BlendOperation : uint8_t

strong

Blend operations used by Donner pipelines.

Enumerator
Add	Component-wise addition (premultiplied source-over).
Max	Component-wise maximum (coverage / clip-mask union).

◆ BufferUsage

enum class donner::gpu::BufferUsage : uint32_t

strong

Buffer usage flags. Combinable with |.

Enumerator
None	No usage; invalid for creation.
Vertex	Bound as a vertex buffer.
Index	Bound as an index buffer.
Uniform	Bound as a uniform buffer.
Storage	Bound as a read-only storage buffer.
CopySrc	Source of copy operations.
CopyDst	Destination of copies and queue writes.
MapRead	Host-readable after readback.

◆ ColorWriteMask

enum class donner::gpu::ColorWriteMask : uint32_t

strong

Per-channel color write mask for a color target. Combinable with |.

Enumerator
None	Write no channels.
Red	Write the red channel.
Green	Write the green channel.
Blue	Write the blue channel.
Alpha	Write the alpha channel.
All	Write all channels.

◆ CullMode

enum class donner::gpu::CullMode : uint8_t

strong

Face culling mode for render pipelines.

Enumerator
None	No culling; Donner geometry has no guaranteed winding.
Back	Cull back faces.

◆ FilterMode

enum class donner::gpu::FilterMode : uint8_t

strong

Sampler minification/magnification filter.

Enumerator
Nearest	Nearest-texel sampling.
Linear	Bilinear sampling.

◆ IndexFormat

enum class donner::gpu::IndexFormat : uint8_t

strong

Element width of an index buffer bound with RenderPassEncoder::setIndexBuffer. Every backend honors the full unsigned range of the width; a device that cannot is reported through Device::supportsFullIndexRange and refuses the binding.

Enumerator
Uint16	16-bit unsigned indices, two bytes each.
Uint32	32-bit unsigned indices, four bytes each.

◆ LoadOp

enum class donner::gpu::LoadOp : uint8_t

strong

Load operation for a render pass color attachment.

Enumerator
Clear	Clear to the attachment's clear color.
Load	Preserve existing contents.

◆ MapMode

enum class donner::gpu::MapMode : uint8_t

strong

How a mapped buffer range is accessed from the host.

Enumerator
Read	Host reads the range; the buffer needs BufferUsage::MapRead.

◆ MapSliceState

enum class donner::gpu::MapSliceState : uint8_t

strong

State of a pending buffer mapping after one backend wait slice.

This is what a backend reports; donner::gpu::MapWaitOutcome is what the caller of a bounded wait sees, and the two differ because the deadline and the caller's cancellation are decisions the runtime makes, not the backend.

Enumerator
Pending	The mapping has not completed yet.
Ready	The mapping completed; its bytes are readable.
DeviceLost	The device was lost, so the mapping can never complete.
Failed	The backend reported the mapping itself failed.

◆ MapWaitKind

enum class donner::gpu::MapWaitKind : uint8_t

strong

How a backend spent a wait for a pending buffer mapping.

A completion-event wait is woken by the backend the moment the map settles. A polled wait rechecks readiness itself and rests or yields in between, which costs orders of magnitude more wall time to observe the same completion, so a caller reporting readback timings needs the two apart rather than averaged together.

Enumerator
Polled	The wait rechecked readiness itself between rests or yields.
CompletionEvent	The wait blocked on a signal raised when the map settles.

◆ MapWaitOutcome

enum class donner::gpu::MapWaitOutcome : uint8_t

strong

Outcome of a bounded wait for a pending buffer mapping.

Every way a wait can end is its own value. A caller that stopped the wait itself, one whose budget ran out, and one whose device died have different recoveries, so folding them into a single failure would throw away the only information that distinguishes them.

Enumerator
Ready	The mapping completed; its bytes are readable.
TimedOut	The wait budget elapsed with the mapping still pending.
Cancelled	The caller's predicate asked to stop waiting.
DeviceLost	The device was lost, so the mapping can never complete.
Failed	The backend reported the mapping itself failed.

◆ NativeSurfaceKind

enum class donner::gpu::NativeSurfaceKind : uint8_t

strong

Platform object kind a donner::gpu::NativeSurfaceHandle names.

One kind per platform object a surface can name; each backend accepts only the kinds it presents to. A browser canvas is named by a CSS selector rather than by a pointer, which is why the handle below carries a string field alongside its pointer fields.

Enumerator
MetalLayer	Core Animation Metal layer.
XlibWindow	X11 display plus window id. Refused by every backend; use EmbedderSurface.
WaylandSurface	Wayland display plus surface. Refused by every backend; use EmbedderSurface.
CanvasSelector	CSS selector naming a browser canvas element. A browser drives presentation from its own frame loop, so a surface of this kind presents when the host says so rather than when the caller asks: an explicit present only hands the acquired frame back for that implicit presentation. Everything else about the surface behaves the same. In a worker, which has no document, the selector is read as the id of a transferred canvas, so only a plain id such as "#canvas" resolves there.
EmbedderSurface	A surface object the embedder created itself, named by its 64-bit handle. The production path on a platform whose windowing library already knows how to make one. A window-system surface is scoped to the graphics instance it was created against, so the embedder creates it against the instance the runtime exposes for exactly this purpose, and keeps ownership: the runtime builds its swapchain on the surface and retires that swapchain with the surface handle, but destroying the handle never destroys the surface itself. On Vulkan, the only backend that accepts this kind, the embedder registers the surface with VulkanSharedRoot::registerExternalSurface() before creating the runtime surface and destroys it with VulkanSharedRoot::destroyExternalSurface(), which refuses until the swapchain is proven retired. Destroy order is the runtime's surface first, then the embedder's, then the instance it was created against. This is what keeps the runtime free of window-system headers: the embedder links the one it already uses and hands over the result.
Headless	A surface with no window behind it at all. Presentation is the one part of this runtime that a machine without a display cannot exercise, which is exactly where its synchronization has to be checked. A headless surface names no platform object and presents to nothing; every other part of the contract - the configuration it accepts, the frames it hands out, the order its submissions and presents must take - behaves as it does for a window.

◆ PresentMode

enum class donner::gpu::PresentMode : uint8_t

strong

How presented frames are paced.

Enumerator
Fifo	Queue frames and present on refresh. Always available.
Immediate	Present without waiting for refresh; may tear.
Mailbox	Replace the queued frame; no tearing, no blocking.

◆ PrimitiveTopology

enum class donner::gpu::PrimitiveTopology : uint8_t

strong

Primitive topology for render pipelines.

Enumerator
TriangleList	Separate triangles.
TriangleStrip	Triangle strip.

◆ SerialWaitEnd

enum class donner::gpu::SerialWaitEnd : uint8_t

strong

How a wait for a submission serial that gives up only on a stall ended; see donner::gpu::Device::waitForSerialUnlessStalled.

Enumerator
Completed	The device completed the serial.
Stalled	The work the serial waits behind made no progress for the stall bound.
Failed	The root is lost, or the backend failed so the serial can never complete.

◆ ShaderSourceKind

enum class donner::gpu::ShaderSourceKind : uint8_t

strong

Shader source language of a donner::gpu::ShaderModuleDescriptor.

Enumerator
Wgsl	WGSL text.
Msl	Metal Shading Language text.
Spirv	SPIR-V binary words (spirvWords; sourceText must be empty).

◆ ShaderStage

enum class donner::gpu::ShaderStage : uint32_t

strong

Shader stage visibility flags for bindings. Combinable with |.

Enumerator
None	No stage; invalid for bind group layout entries.
Vertex	Visible to the vertex stage.
Fragment	Visible to the fragment stage.
Compute	Visible to the compute stage.

◆ StoreOp

enum class donner::gpu::StoreOp : uint8_t

strong

Store operation for a render pass color attachment.

Enumerator
Store	Write results back to the texture.
Discard	Discard results (transient attachments).

◆ SurfaceAlphaMode

enum class donner::gpu::SurfaceAlphaMode : uint8_t

strong

How a surface composites its alpha channel with what is behind it.

Enumerator
Opaque	Alpha is ignored.
Premultiplied	Color channels are already multiplied by alpha.
Inherit	Whatever the platform's default is.

◆ SurfaceStatus

enum class donner::gpu::SurfaceStatus : uint8_t

strong

Outcome of acquiring from or presenting to a surface.

The three failures are different problems with different recoveries, so each is its own value. A surface whose configuration no longer matches its window is donner::gpu::SurfaceStatus::Outdated and recovers by reconfiguring; a surface whose platform object is gone is donner::gpu::SurfaceStatus::Lost and recovers only by creating a new surface from a fresh native handle; a lost device recovers by neither.

Enumerator
Success	The operation succeeded.
Outdated	The configuration no longer matches the window. Reconfigure and retry.
Lost	The platform object is gone. A new surface is needed.
DeviceLost	The device was lost.
Timeout	No texture became available in time. Retry.

◆ TextureFormat

enum class donner::gpu::TextureFormat : uint8_t

strong

Texture formats used by Donner render targets, masks, and image uploads.

Enumerator
RGBA8Unorm	8-bit RGBA, unsigned normalized. Default render target format.
BGRA8Unorm	8-bit BGRA, unsigned normalized. Editor surface format.
R8Unorm	8-bit single channel. Coverage / clip-mask textures.
RGBA32Float	32-bit float RGBA. Filter intermediates.

Examples: geode_embed.cc.

◆ TextureUsage

enum class donner::gpu::TextureUsage : uint32_t

strong

Texture usage flags. Combinable with |.

Enumerator
None	No usage; invalid for creation.
RenderAttachment	Color attachment of a render pass.
Sampled	Sampled in a shader.
CopySrc	Source of copy operations (readback).
CopyDst	Destination of copies and queue writes.
StorageBinding	Written through a storage-texture binding in a compute shader.

◆ VertexFormat

enum class donner::gpu::VertexFormat : uint8_t

strong

Vertex attribute formats used by Donner pipelines.

Enumerator
Float32x2	Two 32-bit floats (8 bytes).
Float32x4	Four 32-bit floats (16 bytes).
Uint32	One 32-bit unsigned integer (4 bytes).

◆ VertexStepMode

enum class donner::gpu::VertexStepMode : uint8_t

strong

Rate at which a vertex buffer is stepped through during a draw.

Enumerator
Vertex	Advance per vertex.
Instance	Advance per instance.

Function Documentation

◆ HasAllFlags()

template<BitmaskEnum T>

bool donner::gpu::HasAllFlags	(	T	value,
		T	flags )

constexpr

Returns true if value contains every flag in flags.

Parameters

value	Flags to test.
flags	Required flags.

◆ IndexFormatByteSize()

uint32_t donner::gpu::IndexFormatByteSize ( IndexFormat format )

constexpr

Bytes occupied by one index of format, or 0 for an unknown enumerator so callers fail closed instead of dividing by a guess.

Parameters

format Index format.

◆ IsKnownEnumValue() [1/17]

bool donner::gpu::IsKnownEnumValue ( AddressMode value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [2/17]

bool donner::gpu::IsKnownEnumValue ( BindingType value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [3/17]

bool donner::gpu::IsKnownEnumValue ( BlendFactor value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [4/17]

bool donner::gpu::IsKnownEnumValue ( BlendOperation value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [5/17]

bool donner::gpu::IsKnownEnumValue ( CullMode value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [6/17]

bool donner::gpu::IsKnownEnumValue ( FilterMode value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [7/17]

bool donner::gpu::IsKnownEnumValue ( IndexFormat value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [8/17]

bool donner::gpu::IsKnownEnumValue ( LoadOp value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [9/17]

bool donner::gpu::IsKnownEnumValue ( NativeSurfaceKind value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [10/17]

bool donner::gpu::IsKnownEnumValue ( PresentMode value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [11/17]

bool donner::gpu::IsKnownEnumValue ( PrimitiveTopology value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [12/17]

bool donner::gpu::IsKnownEnumValue ( ShaderSourceKind value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [13/17]

bool donner::gpu::IsKnownEnumValue ( StoreOp value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [14/17]

bool donner::gpu::IsKnownEnumValue ( SurfaceAlphaMode value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [15/17]

bool donner::gpu::IsKnownEnumValue ( TextureFormat value )

Returns true if value is a known enumerator. Every enum arriving through a descriptor is checked with these overloads so out-of-range casts fail closed with donner::gpu::GpuErrorType::InvalidDescriptor instead of flowing into layout or copy math.

Parameters

value Value to check.

◆ IsKnownEnumValue() [16/17]

bool donner::gpu::IsKnownEnumValue ( VertexFormat value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsKnownEnumValue() [17/17]

bool donner::gpu::IsKnownEnumValue ( VertexStepMode value )

Returns true if value is a known enumerator.

Parameters

value Value to check.

◆ IsValidBitmask() [1/4]

bool donner::gpu::IsValidBitmask ( BufferUsage value )

Returns true if value contains only known flag bits.

Parameters

value Bitmask to check.

◆ IsValidBitmask() [2/4]

bool donner::gpu::IsValidBitmask ( ColorWriteMask value )

Returns true if value contains only known flag bits.

Parameters

value Bitmask to check.

◆ IsValidBitmask() [3/4]

bool donner::gpu::IsValidBitmask ( ShaderStage value )

Returns true if value contains only known flag bits.

Parameters

value Bitmask to check.

◆ IsValidBitmask() [4/4]

bool donner::gpu::IsValidBitmask ( TextureUsage value )

Returns true if value contains only known flag bits (an empty mask is bit-valid; emptiness is validated separately where required).

Parameters

value Bitmask to check.

◆ operator&()

template<BitmaskEnum T>

T donner::gpu::operator&	(	T	lhs,
		T	rhs )

constexpr

Bitwise-and for bitmask enums.

Parameters

lhs	First operand.
rhs	Second operand.

◆ operator<<() [1/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		AddressMode	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [2/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		BindingType	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [3/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		BlendFactor	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [4/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		BlendOperation	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [5/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		BufferUsage	value )

Ostream output operator, e.g. Vertex|CopyDst, or None when no flags are set.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [6/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		ColorWriteMask	value )

Ostream output operator, e.g. Red|Green|Blue|Alpha, or None when no flags are set.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [7/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		const MapSliceReport &	value )

Ostream output operator, e.g. {Pending, Polled}.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [8/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		const MapWaitReport &	value )

Ostream output operator, e.g. {Ready, CompletionEvent}.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [9/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		const SerialWaitResult &	value )

Ostream output operator, e.g. {Stalled, 5003 ms}.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [10/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		CullMode	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [11/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		FilterMode	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [12/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		IndexFormat	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [13/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		LoadOp	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [14/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		MapSliceState	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [15/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		MapWaitKind	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [16/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		MapWaitOutcome	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [17/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		NativeSurfaceKind	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [18/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		PresentMode	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [19/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		PrimitiveTopology	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [20/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		SerialWaitEnd	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [21/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		ShaderSourceKind	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [22/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		ShaderStage	value )

Ostream output operator, e.g. Vertex|Fragment, or None when no flags are set.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [23/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		StoreOp	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [24/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		SurfaceAlphaMode	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [25/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		SurfaceStatus	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [26/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		TextureFormat	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [27/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		TextureUsage	value )

Ostream output operator, e.g. RenderAttachment|CopySrc, or None when no flags are set.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [28/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		VertexFormat	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator<<() [29/29]

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		VertexStepMode	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

◆ operator|()

template<BitmaskEnum T>

T donner::gpu::operator\|	(	T	lhs,
		T	rhs )

constexpr

Bitwise-or for bitmask enums.

Parameters

lhs	First operand.
rhs	Second operand.

◆ operator|=()

template<BitmaskEnum T>

T & donner::gpu::operator\|=	(	T &	lhs,
		T	rhs )

constexpr

Bitwise-or-assign for bitmask enums.

Parameters

lhs	Value to update.
rhs	Flags to add.

◆ TextureFormatBytesPerTexel()

uint32_t donner::gpu::TextureFormatBytesPerTexel ( TextureFormat format )

Bytes per texel for a donner::gpu::TextureFormat.

Parameters

format Texture format.

◆ VertexFormatByteSize()

uint32_t donner::gpu::VertexFormatByteSize ( VertexFormat format )

Byte size of a donner::gpu::VertexFormat.

Parameters

format Vertex attribute format.

Classes

Namespaces

Concepts

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ AddressMode

◆ BindingType

◆ BlendFactor

◆ BlendOperation

◆ BufferUsage

◆ ColorWriteMask

◆ CullMode

◆ FilterMode

◆ IndexFormat

◆ LoadOp

◆ MapMode

◆ MapSliceState

◆ MapWaitKind

◆ MapWaitOutcome

◆ NativeSurfaceKind

◆ PresentMode

◆ PrimitiveTopology

◆ SerialWaitEnd

◆ ShaderSourceKind

◆ ShaderStage

◆ StoreOp

◆ SurfaceAlphaMode

◆ SurfaceStatus

◆ TextureFormat

◆ TextureUsage

◆ VertexFormat

◆ VertexStepMode

Function Documentation

◆ HasAllFlags()

◆ IndexFormatByteSize()

◆ IsKnownEnumValue() [1/17]

◆ IsKnownEnumValue() [2/17]

◆ IsKnownEnumValue() [3/17]

◆ IsKnownEnumValue() [4/17]

◆ IsKnownEnumValue() [5/17]

◆ IsKnownEnumValue() [6/17]

◆ IsKnownEnumValue() [7/17]

◆ IsKnownEnumValue() [8/17]

◆ IsKnownEnumValue() [9/17]

◆ IsKnownEnumValue() [10/17]

◆ IsKnownEnumValue() [11/17]

◆ IsKnownEnumValue() [12/17]

◆ IsKnownEnumValue() [13/17]

◆ IsKnownEnumValue() [14/17]

◆ IsKnownEnumValue() [15/17]

◆ IsKnownEnumValue() [16/17]

◆ IsKnownEnumValue() [17/17]

◆ IsValidBitmask() [1/4]

◆ IsValidBitmask() [2/4]

◆ IsValidBitmask() [3/4]

◆ IsValidBitmask() [4/4]

◆ operator&()

◆ operator<<() [1/29]

◆ operator<<() [2/29]

◆ operator<<() [3/29]

◆ operator<<() [4/29]

◆ operator<<() [5/29]

◆ operator<<() [6/29]

◆ operator<<() [7/29]

◆ operator<<() [8/29]

◆ operator<<() [9/29]

◆ operator<<() [10/29]

◆ operator<<() [11/29]

◆ operator<<() [12/29]

◆ operator<<() [13/29]

◆ operator<<() [14/29]

◆ operator<<() [15/29]

◆ operator<<() [16/29]

◆ operator<<() [17/29]

◆ operator<<() [18/29]

◆ operator<<() [19/29]

◆ operator<<() [20/29]

◆ operator<<() [21/29]