Abstract GPU device: resource creation, queue writes, and submission with shared fail-closed validation. More...

#include "donner/gpu/Device.h"

Inheritance diagram for donner::gpu::Device:

Classes
struct	MapWaitTestHooks
	Waits for a pending mapping in slices, until it completes, the caller stops it, the budget runs out, or the device is lost. More...

Public Member Functions
virtual	~Device ()
	Destructor; expires the device-alive token (so handles that outlive the device release nothing) and frees all remaining resources. Backends that submit asynchronously must wait for in-flight submissions in their own destructor before backend state is torn down.
	Device (const Device &)=delete
Device &	operator= (const Device &)=delete
	Device (Device &&)=delete
Device &	operator= (Device &&)=delete
uint64_t	deviceId () const
	Process-unique identity of this device (starts at 1, never reused). Baked into every handle for cross-device validation.
Result< Buffer >	createBuffer (const BufferDescriptor &descriptor)
	Creates a buffer.
Result< Texture >	createTexture (const TextureDescriptor &descriptor)
	Creates a 2D texture.
Result< TextureView >	createTextureView (const Texture &texture, const TextureViewDescriptor &descriptor)
	Creates a view of `texture` covering the whole texture.
Result< Sampler >	createSampler (const SamplerDescriptor &descriptor)
	Creates a sampler.
Result< BindGroupLayout >	createBindGroupLayout (const BindGroupLayoutDescriptor &descriptor)
	Creates a bind group layout.
Result< BindGroup >	createBindGroup (const BindGroupDescriptor &descriptor)
	Creates a bind group.
Result< PipelineLayout >	createPipelineLayout (const PipelineLayoutDescriptor &descriptor)
	Creates a pipeline layout.
Result< ShaderModule >	createShaderModule (const ShaderModuleDescriptor &descriptor)
	Creates a shader module from trusted generated source.
Result< RenderPipeline >	createRenderPipeline (const RenderPipelineDescriptor &descriptor)
	Creates a render pipeline.
Result< ComputePipeline >	createComputePipeline (const ComputePipelineDescriptor &descriptor)
	Creates a compute pipeline.
Status	destroyBuffer (Buffer &&buffer)
	Destroys a buffer (see the destroy contract above).
Status	destroyTexture (Texture &&texture)
	Destroys a texture (see the destroy contract above).
Status	destroyTextureView (TextureView &&textureView)
	Destroys a texture view (see the destroy contract above).
Status	destroySampler (Sampler &&sampler)
	Destroys a sampler (see the destroy contract above).
Status	destroyBindGroupLayout (BindGroupLayout &&bindGroupLayout)
	Destroys a bind group layout (see the destroy contract above).
Status	destroyBindGroup (BindGroup &&bindGroup)
	Destroys a bind group (see the destroy contract above).
Status	destroyPipelineLayout (PipelineLayout &&pipelineLayout)
	Destroys a pipeline layout (see the destroy contract above).
Status	destroyShaderModule (ShaderModule &&shaderModule)
	Destroys a shader module (see the destroy contract above).
Status	destroyRenderPipeline (RenderPipeline &&renderPipeline)
	Destroys a render pipeline (see the destroy contract above).
Status	destroyComputePipeline (ComputePipeline &&computePipeline)
	Destroys a compute pipeline (see the destroy contract above).
Result< std::unique_ptr< CommandEncoder > >	createCommandEncoder ()
	Creates a command encoder recording against this device. The encoder must not outlive the device.
Result< Surface >	createSurface (const SurfaceDescriptor &descriptor)
	Creates a surface presenting to a platform object.
Result< SurfaceCapabilities >	surfaceCapabilities (const Surface &surface) const
	What `surface` supports, for choosing a configuration.
Status	configureSurface (const Surface &surface, const SurfaceConfiguration &configuration)
	Configures how `surface` presents, replacing any previous configuration.
Result< SurfaceTexture >	acquireCurrentTexture (const Surface &surface)
	Acquires the texture for the next frame of `surface`.
Result< SurfaceStatus >	presentSurface (const Surface &surface)
	Presents the texture acquired from `surface` and invalidates it.
Status	abandonCurrentTexture (const Surface &surface)
	Releases the acquired texture of `surface` without presenting it, for a frame the caller decided not to show.
Status	destroySurface (Surface &&surface)
	Destroys a surface (see the destroy contract above).
Result< BufferMapping >	mapBufferAsync (const Buffer &buffer, MapMode mode, uint64_t offsetBytes, uint64_t byteCount)
	Begins mapping a range of `buffer` for host access, and returns the handle that names the mapping.
Result< MapWaitOutcome >	waitForMapping (const BufferMapping &mapping, const MapWaitParams &params, const std::function< bool()> &shouldCancel, const MapWaitTestHooks &testHooks={})
Result< std::span< const uint8_t > >	mappedBytes (const BufferMapping &mapping) const
	Returns the mapped bytes of a completed mapping.
Status	unmapBuffer (BufferMapping &&mapping)
	Releases a mapping, invalidating the handle and every copy of it.
Status	writeBuffer (const Buffer &buffer, uint64_t offsetBytes, std::span< const uint8_t > data)
	Writes `data` into `buffer` at `offsetBytes`.
Status	writeTexture (const Texture &texture, std::span< const uint8_t > data, const TexelCopyBufferLayout &dataLayout, const Extent2d &writeSize)
	Writes texel rows from `data` into `texture` starting at texel (0, 0).
Result< uint64_t >	submit (CommandBuffer commandBuffer)
	Submits a finished command buffer, consuming it, and returns the assigned submission serial.
void	poll ()
	Processes deferred destructions: releases the backend object of every destroyed resource whose last referencing submission has completed (completedSerial), and recycles its slot.
uint64_t	lastSubmittedSerial () const
	Serial assigned to the most recent submission (0 if none yet).
virtual uint64_t	completedSerial () const =0
	Serial of the most recent submission the backend has finished executing (0 if none). The recording backend completes instantly, so this equals lastSubmittedSerial there.

Protected Member Functions
	Device ()
	Constructor for backends; assigns the process-unique device identity.
virtual Status	onCreateBuffer (uint32_t slotIndex, const BufferDescriptor &descriptor)=0
	Backend hook: a buffer passed validation and occupies `slotIndex`.
virtual Status	onCreateTexture (uint32_t slotIndex, const TextureDescriptor &descriptor)=0
	Backend hook: a texture passed validation and occupies `slotIndex`.
virtual Status	onCreateTextureView (uint32_t slotIndex, uint32_t textureSlotIndex, const TextureViewDescriptor &descriptor)=0
	Backend hook: a texture view passed validation and occupies `slotIndex`.
virtual Status	onCreateSampler (uint32_t slotIndex, const SamplerDescriptor &descriptor)=0
	Backend hook: a sampler passed validation and occupies `slotIndex`.
virtual Status	onCreateBindGroupLayout (uint32_t slotIndex, const BindGroupLayoutDescriptor &descriptor)=0
	Backend hook: a bind group layout passed validation and occupies `slotIndex`.
virtual Status	onCreateBindGroup (uint32_t slotIndex, const BindGroupDescriptor &descriptor)=0
	Backend hook: a bind group passed validation and occupies `slotIndex`.
virtual Status	onCreatePipelineLayout (uint32_t slotIndex, const PipelineLayoutDescriptor &descriptor)=0
	Backend hook: a pipeline layout passed validation and occupies `slotIndex`.
virtual Status	onCreateShaderModule (uint32_t slotIndex, const ShaderModuleDescriptor &descriptor)=0
	Backend hook: a shader module passed validation and occupies `slotIndex`.
virtual Status	onCreateRenderPipeline (uint32_t slotIndex, const RenderPipelineDescriptor &descriptor)=0
	Backend hook: a render pipeline passed validation and occupies `slotIndex`.
virtual Status	onCreateComputePipeline (uint32_t slotIndex, const ComputePipelineDescriptor &descriptor)=0
	Backend hook: a compute pipeline passed validation and occupies `slotIndex`.
virtual void	onDestroyResource (std::string_view resourceName, uint32_t slotIndex)=0
	Backend hook: a validated resource was destroyed.
virtual Status	onWriteBuffer (uint32_t slotIndex, uint64_t offsetBytes, std::span< const uint8_t > data)=0
	Backend hook: a validated buffer write.
virtual Status	onWriteTexture (uint32_t slotIndex, std::span< const uint8_t > data, const TexelCopyBufferLayout &dataLayout, const Extent2d &writeSize)=0
	Backend hook: a validated texture write.
Status	validateBufferHandleForBackend (const Buffer &buffer) const
	Validates a buffer handle for backend-provided auxiliary entry points (test readback helpers and similar), running the same null/device-identity/generation checks the template-method public API performs before its hooks.
Status	validateTextureHandleForBackend (const Texture &texture) const
	Validates a texture handle for backend-provided auxiliary entry points, running the same null/device-identity/generation checks the template-method public API performs.
Status	validateTextureViewHandleForBackend (const TextureView &textureView) const
	Validates a texture view handle for backend-provided auxiliary entry points: the view itself plus a re-resolution of its viewed texture, so a view of a destroyed (or slot-recycled) texture fails closed exactly like it does on the normal Device paths.
Status	validateBufferMappingHandleForBackend (const BufferMapping &mapping) const
	Validates a buffer-mapping handle for backend-provided auxiliary entry points, running the same null/device-identity/generation checks the template-method public API performs, so a stale handle cannot read state belonging to the slot's new occupant.
virtual Status	onMapBufferAsync (uint32_t mappingSlotIndex, uint32_t bufferSlotIndex, MapMode mode, uint64_t offsetBytes, uint64_t byteCount)
	Backend hook: begin mapping a buffer range.
virtual MapSliceState	onWaitMappingSlice (uint32_t mappingSlotIndex, double sliceSeconds)
	Backend hook: wait up to `sliceSeconds` for a pending mapping and report what it found.
virtual Result< std::span< const uint8_t > >	onMappedBytes (uint32_t mappingSlotIndex) const
	Backend hook: bytes of a completed mapping.
virtual void	onUnmapBuffer (uint32_t mappingSlotIndex)
	Backend hook: release a mapping.
virtual Status	onCreateSurface (uint32_t slotIndex, const SurfaceDescriptor &descriptor)
	Backend hook: create a surface for a platform object.
virtual Result< SurfaceCapabilities >	onSurfaceCapabilities (uint32_t slotIndex) const
	Backend hook: what a surface supports.
virtual Status	onConfigureSurface (uint32_t slotIndex, const SurfaceConfiguration &configuration)
	Backend hook: apply a configuration.
virtual Result< SurfaceStatus >	onAcquireCurrentTexture (uint32_t slotIndex, uint32_t textureSlotIndex)
	Backend hook: acquire the next frame's texture and report the surface's state.
virtual Result< SurfaceStatus >	onPresentSurface (uint32_t slotIndex)
	Backend hook: present the acquired texture.
virtual void	onAbandonCurrentTexture (uint32_t slotIndex)
	Backend hook: drop the acquired texture without presenting.
virtual Status	onSubmit (uint64_t submissionSerial, uint32_t commandBufferSlotIndex, std::span< const Command > commands)=0
	Backend hook: a validated command buffer was submitted.

Friends
class	CommandEncoder

Detailed Description

Abstract GPU device: resource creation, queue writes, and submission with shared fail-closed validation.

The public API is non-virtual and validates every descriptor, handle, and byte range before delegating to protected on* virtuals (template-method pattern), so every backend - the deterministic RecordingDevice and the platform backends - inherits identical fail-closed behavior. Validation runs in release builds too: invalid input returns a GpuError, never asserts.

Enforced limits are documented in GpuLimits.h. Handle validation checks device identity (GpuErrorType::DeviceMismatch) and slot generation (GpuErrorType::InvalidHandle), so destroyed or foreign handles fail before reaching a backend.

Lifetime: handles are move-only RAII - dropping a live handle releases the resource, an explicit destroy*(std::move(handle)) call releases it early and reports errors, and device teardown frees everything that remains. A handle that outlives its device releases nothing (its device-alive token has expired). Destruction is deferred by submission serial: destroying a resource makes its handles and references stale immediately, but the backend object is kept alive - and its slot is not reused - until every submission referencing it has completed (completedSerial). Deferred backend releases are processed by poll and opportunistically by destroy* and submit.

Two resource kinds are intentionally exempt from submission pinning because commands never reference them: PipelineLayout and ShaderModule are consumed at pipeline creation only, so destroying one releases its backend object immediately. Backends must snapshot or retain whatever they need from them when the pipeline is created (Metal's compiled pipeline state retains its functions; the Vulkan backend must do the equivalent when it lands).

Thread affinity: a Device and everything created from it must be used from one thread at a time, matching the async-renderer worker ownership model.

Class Documentation

◆ donner::gpu::Device::MapWaitTestHooks

struct donner::gpu::Device::MapWaitTestHooks

Waits for a pending mapping in slices, until it completes, the caller stops it, the budget runs out, or the device is lost.

shouldCancel is consulted before each slice, so a caller that changes its mind stops within one slice rather than at the end of the budget. Device loss ends the wait immediately: the mapping can never complete afterwards, and reporting it as a timeout would describe a permanent failure as a slow one.

Parameters

mapping	Live mapping of this device.
params	Slice length and total budget; both must be greater than zero.
shouldCancel	Consulted before each slice; may be empty for an uncancellable wait. Test seam for waitForMapping. Production callers pass none; a test injects a clock and a rest so a budget is verified deterministically and without spending it.

Class Members
function< time_point()>	now	Clock the budget is measured against. Defaults to std::chrono::steady_clock::now.
function< void(microseconds)>	rest	Rests for the given duration. Defaults to std::this_thread::sleep_for.

Member Function Documentation

◆ abandonCurrentTexture()

Status donner::gpu::Device::abandonCurrentTexture ( const Surface & surface )

Releases the acquired texture of surface without presenting it, for a frame the caller decided not to show.

Parameters

surface Live surface with an acquired texture.

◆ acquireCurrentTexture()

Result< SurfaceTexture > donner::gpu::Device::acquireCurrentTexture ( const Surface & surface )

Acquires the texture for the next frame of surface.

The texture is valid until the matching presentSurface, abandonCurrentTexture, or a reconfiguration - each of those invalidates it, so drawing into a presented texture is a reported validation failure rather than a write to a texture the platform now owns.

A non-success status can still come with a usable texture: a surface that has drifted out of date usually still presents, so the caller decides between drawing this frame and reconfiguring first.

Parameters

surface Live, configured surface.

◆ completedSerial()

virtual uint64_t donner::gpu::Device::completedSerial ( ) const

pure virtual

Serial of the most recent submission the backend has finished executing (0 if none). The recording backend completes instantly, so this equals lastSubmittedSerial there.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ configureSurface()

Status donner::gpu::Device::configureSurface	(	const Surface &	surface,
		const SurfaceConfiguration &	configuration )

Configures how surface presents, replacing any previous configuration.

This is how a surface follows its window: a resize reconfigures with the new extent rather than creating a new surface, and it is the recovery from SurfaceStatus::Outdated. Reconfiguring abandons any texture currently acquired from the surface.

Parameters

surface	Live surface.
configuration	Format, usage, extent, pacing and alpha compositing.

◆ createBindGroup()

Result< BindGroup > donner::gpu::Device::createBindGroup ( const BindGroupDescriptor & descriptor )

Creates a bind group.

Fails closed unless every layout binding is matched by exactly one entry whose resource is live, belongs to this device, matches the layout's BindingType, and carries the usage that binding type requires.

Parameters

descriptor Validated bind group descriptor.

◆ createBindGroupLayout()

Result< BindGroupLayout > donner::gpu::Device::createBindGroupLayout ( const BindGroupLayoutDescriptor & descriptor )

Creates a bind group layout.

Fails closed on duplicate binding indices, out-of-limit binding counts or indices, or empty per-entry visibility.

Parameters

descriptor Validated layout descriptor.

◆ createBuffer()

Result< Buffer > donner::gpu::Device::createBuffer ( const BufferDescriptor & descriptor )

Creates a buffer.

Fails closed on zero or oversized byteSize or empty usage.

Parameters

descriptor Validated buffer descriptor.

◆ createComputePipeline()

Result< ComputePipeline > donner::gpu::Device::createComputePipeline ( const ComputePipelineDescriptor & descriptor )

Creates a compute pipeline.

Fails closed on invalid layout/module references, an empty entry point, or a workgroup size that is zero in any dimension, exceeds a per-axis cap, or declares more than kMaxComputeInvocationsPerWorkgroup invocations.

Parameters

descriptor Validated pipeline descriptor.

◆ createPipelineLayout()

Result< PipelineLayout > donner::gpu::Device::createPipelineLayout ( const PipelineLayoutDescriptor & descriptor )

Creates a pipeline layout.

Fails closed on out-of-limit group counts or invalid layout references.

Parameters

descriptor Validated pipeline layout descriptor.

◆ createRenderPipeline()

Result< RenderPipeline > donner::gpu::Device::createRenderPipeline ( const RenderPipelineDescriptor & descriptor )

Creates a render pipeline.

Fails closed on invalid layout/module references, empty entry points, vertex attributes that overflow their stride, duplicate shader locations, empty or out-of-limit target lists, or multisampleCount != 1.

Parameters

descriptor Validated pipeline descriptor.

◆ createSampler()

Result< Sampler > donner::gpu::Device::createSampler ( const SamplerDescriptor & descriptor )

Creates a sampler.

Parameters

descriptor Validated sampler descriptor.

◆ createShaderModule()

Result< ShaderModule > donner::gpu::Device::createShaderModule ( const ShaderModuleDescriptor & descriptor )

Creates a shader module from trusted generated source.

Fails closed on empty source text.

Parameters

descriptor Validated shader module descriptor.

◆ createSurface()

Result< Surface > donner::gpu::Device::createSurface ( const SurfaceDescriptor & descriptor )

Creates a surface presenting to a platform object.

The surface is not usable until configureSurface succeeds: a surface knows what it presents to, and a configuration knows how.

Parameters

descriptor Label and platform object to present to.

◆ createTexture()

Result< Texture > donner::gpu::Device::createTexture ( const TextureDescriptor & descriptor )

Creates a 2D texture.

Fails closed on zero or oversized extents, empty usage, or sampleCount != 1.

Parameters

descriptor Validated texture descriptor.

◆ createTextureView()

Result< TextureView > donner::gpu::Device::createTextureView	(	const Texture &	texture,
		const TextureViewDescriptor &	descriptor )

Creates a view of texture covering the whole texture.

Parameters

texture	Texture to view; must be a live handle of this device.
descriptor	Validated view descriptor.

◆ destroyBindGroup()

Status donner::gpu::Device::destroyBindGroup ( BindGroup && bindGroup )

Destroys a bind group (see the destroy contract above).

Parameters

bindGroup Handle to destroy.

◆ destroyBindGroupLayout()

Status donner::gpu::Device::destroyBindGroupLayout ( BindGroupLayout && bindGroupLayout )

Destroys a bind group layout (see the destroy contract above).

Parameters

bindGroupLayout Handle to destroy.

◆ destroyBuffer()

Status donner::gpu::Device::destroyBuffer ( Buffer && buffer )

Destroys a buffer (see the destroy contract above).

Parameters

buffer Handle to destroy.

◆ destroyComputePipeline()

Status donner::gpu::Device::destroyComputePipeline ( ComputePipeline && computePipeline )

Destroys a compute pipeline (see the destroy contract above).

Parameters

computePipeline Handle to destroy.

◆ destroyPipelineLayout()

Status donner::gpu::Device::destroyPipelineLayout ( PipelineLayout && pipelineLayout )

Destroys a pipeline layout (see the destroy contract above).

Parameters

pipelineLayout Handle to destroy.

◆ destroyRenderPipeline()

Status donner::gpu::Device::destroyRenderPipeline ( RenderPipeline && renderPipeline )

Destroys a render pipeline (see the destroy contract above).

Parameters

renderPipeline Handle to destroy.

◆ destroySampler()

Status donner::gpu::Device::destroySampler ( Sampler && sampler )

Destroys a sampler (see the destroy contract above).

Parameters

sampler Handle to destroy.

◆ destroyShaderModule()

Status donner::gpu::Device::destroyShaderModule ( ShaderModule && shaderModule )

Destroys a shader module (see the destroy contract above).

Parameters

shaderModule Handle to destroy.

◆ destroySurface()

Status donner::gpu::Device::destroySurface ( Surface && surface )

Destroys a surface (see the destroy contract above).

Parameters

surface Handle to destroy.

◆ destroyTexture()

Status donner::gpu::Device::destroyTexture ( Texture && texture )

Destroys a texture (see the destroy contract above).

Parameters

texture Handle to destroy.

◆ destroyTextureView()

Status donner::gpu::Device::destroyTextureView ( TextureView && textureView )

Destroys a texture view (see the destroy contract above).

Parameters

textureView Handle to destroy.

◆ mapBufferAsync()

Result< BufferMapping > donner::gpu::Device::mapBufferAsync	(	const Buffer &	buffer,
		MapMode	mode,
		uint64_t	offsetBytes,
		uint64_t	byteCount )

Begins mapping a range of buffer for host access, and returns the handle that names the mapping.

The mapping is not readable yet: waitForMapping decides when it is. The returned handle is what keeps the mapped range reachable - unmapBuffer consumes it and every copy of it goes stale at that moment, so a read through a handle whose mapping has been released is a reported validation failure rather than a read of memory that is no longer there.

Parameters

buffer	Buffer to map; needs BufferUsage::MapRead.
mode	How the host will access the range.
offsetBytes	Byte offset of the mapped range.
byteCount	Length of the mapped range; must be nonzero and fit the buffer.

◆ mappedBytes()

Result< std::span< const uint8_t > > donner::gpu::Device::mappedBytes ( const BufferMapping & mapping ) const

Returns the mapped bytes of a completed mapping.

Fails closed when the mapping is stale, belongs to another device, or has not completed: the span is only valid while the handle names a live, ready mapping.

Parameters

mapping Live, completed mapping of this device.

◆ onAbandonCurrentTexture()

virtual void donner::gpu::Device::onAbandonCurrentTexture ( uint32_t slotIndex )

protectedvirtual

Backend hook: drop the acquired texture without presenting.

Parameters

slotIndex Slot of the surface.

Reimplemented in donner::geode::GeodeWgpuAdapterDevice.

◆ onAcquireCurrentTexture()

virtual Result< SurfaceStatus > donner::gpu::Device::onAcquireCurrentTexture	(	uint32_t	slotIndex,
		uint32_t	textureSlotIndex )

protectedvirtual

Backend hook: acquire the next frame's texture and report the surface's state.

Parameters

slotIndex	Slot of the surface.
textureSlotIndex	Slot the runtime allocated for the acquired texture.

Reimplemented in donner::geode::GeodeWgpuAdapterDevice.

◆ onConfigureSurface()

virtual Status donner::gpu::Device::onConfigureSurface	(	uint32_t	slotIndex,
		const SurfaceConfiguration &	configuration )

protectedvirtual

Backend hook: apply a configuration.

Parameters

slotIndex	Slot of the surface.
configuration	Configuration to apply.

Reimplemented in donner::geode::GeodeWgpuAdapterDevice.

◆ onCreateBindGroup()

virtual Status donner::gpu::Device::onCreateBindGroup	(	uint32_t	slotIndex,
		const BindGroupDescriptor &	descriptor )

protectedpure virtual

Backend hook: a bind group passed validation and occupies slotIndex.

Parameters

slotIndex	Slot index of the new resource.
descriptor	Validated descriptor.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ onCreateBindGroupLayout()

virtual Status donner::gpu::Device::onCreateBindGroupLayout	(	uint32_t	slotIndex,
		const BindGroupLayoutDescriptor &	descriptor )

protectedpure virtual

Backend hook: a bind group layout passed validation and occupies slotIndex.

Parameters

slotIndex	Slot index of the new resource.
descriptor	Validated descriptor.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ onCreateBuffer()

virtual Status donner::gpu::Device::onCreateBuffer	(	uint32_t	slotIndex,
		const BufferDescriptor &	descriptor )

protectedpure virtual

Backend hook: a buffer passed validation and occupies slotIndex.

Parameters

slotIndex	Slot index of the new resource.
descriptor	Validated descriptor.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ onCreateComputePipeline()

virtual Status donner::gpu::Device::onCreateComputePipeline	(	uint32_t	slotIndex,
		const ComputePipelineDescriptor &	descriptor )

protectedpure virtual

Backend hook: a compute pipeline passed validation and occupies slotIndex.

Parameters

slotIndex	Slot index of the new resource.
descriptor	Validated descriptor.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ onCreatePipelineLayout()

virtual Status donner::gpu::Device::onCreatePipelineLayout	(	uint32_t	slotIndex,
		const PipelineLayoutDescriptor &	descriptor )

protectedpure virtual

Backend hook: a pipeline layout passed validation and occupies slotIndex.

Parameters

slotIndex	Slot index of the new resource.
descriptor	Validated descriptor.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ onCreateRenderPipeline()

virtual Status donner::gpu::Device::onCreateRenderPipeline	(	uint32_t	slotIndex,
		const RenderPipelineDescriptor &	descriptor )

protectedpure virtual

Backend hook: a render pipeline passed validation and occupies slotIndex.

Parameters

slotIndex	Slot index of the new resource.
descriptor	Validated descriptor.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ onCreateSampler()

virtual Status donner::gpu::Device::onCreateSampler	(	uint32_t	slotIndex,
		const SamplerDescriptor &	descriptor )

protectedpure virtual

Backend hook: a sampler passed validation and occupies slotIndex.

Parameters

slotIndex	Slot index of the new resource.
descriptor	Validated descriptor.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ onCreateShaderModule()

virtual Status donner::gpu::Device::onCreateShaderModule	(	uint32_t	slotIndex,
		const ShaderModuleDescriptor &	descriptor )

protectedpure virtual

Backend hook: a shader module passed validation and occupies slotIndex.

Parameters

slotIndex	Slot index of the new resource.
descriptor	Validated descriptor.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ onCreateSurface()

virtual Status donner::gpu::Device::onCreateSurface	(	uint32_t	slotIndex,
		const SurfaceDescriptor &	descriptor )

protectedvirtual

Backend hook: create a surface for a platform object.

Defaults to reporting presentation as unsupported, so a backend that cannot present needs no implementation.

Parameters

slotIndex	Slot the surface occupies.
descriptor	Label and platform object.

Reimplemented in donner::geode::GeodeWgpuAdapterDevice.

◆ onCreateTexture()

virtual Status donner::gpu::Device::onCreateTexture	(	uint32_t	slotIndex,
		const TextureDescriptor &	descriptor )

protectedpure virtual

Backend hook: a texture passed validation and occupies slotIndex.

Parameters

slotIndex	Slot index of the new resource.
descriptor	Validated descriptor.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ onCreateTextureView()

virtual Status donner::gpu::Device::onCreateTextureView	(	uint32_t	slotIndex,
		uint32_t	textureSlotIndex,
		const TextureViewDescriptor &	descriptor )

protectedpure virtual

Backend hook: a texture view passed validation and occupies slotIndex.

Parameters

slotIndex	Slot index of the new resource.
textureSlotIndex	Slot index of the viewed texture.
descriptor	Validated descriptor.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ onDestroyResource()

virtual void donner::gpu::Device::onDestroyResource	(	std::string_view	resourceName,
		uint32_t	slotIndex )

protectedpure virtual

Backend hook: a validated resource was destroyed.

Parameters

resourceName	Resource type name, e.g. "buffer".
slotIndex	Slot index of the destroyed resource.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ onMapBufferAsync()

virtual Status donner::gpu::Device::onMapBufferAsync	(	uint32_t	mappingSlotIndex,
		uint32_t	bufferSlotIndex,
		MapMode	mode,
		uint64_t	offsetBytes,
		uint64_t	byteCount )

protectedvirtual

Backend hook: begin mapping a buffer range.

Defaults to reporting the capability as unsupported, so a backend without host mapping needs no implementation and callers get a clean unsupported result rather than a missing symbol.

Parameters

mappingSlotIndex	Slot the mapping occupies.
bufferSlotIndex	Slot of the buffer being mapped.
mode	How the host will access the range.
offsetBytes	Byte offset of the mapped range.
byteCount	Length of the mapped range.

Reimplemented in donner::geode::GeodeWgpuAdapterDevice.

◆ onMappedBytes()

virtual Result< std::span< const uint8_t > > donner::gpu::Device::onMappedBytes ( uint32_t mappingSlotIndex ) const

protectedvirtual

Backend hook: bytes of a completed mapping.

Parameters

mappingSlotIndex Slot of the mapping.

Reimplemented in donner::geode::GeodeWgpuAdapterDevice.

◆ onPresentSurface()

virtual Result< SurfaceStatus > donner::gpu::Device::onPresentSurface ( uint32_t slotIndex )

protectedvirtual

Backend hook: present the acquired texture.

Parameters

slotIndex Slot of the surface.

Reimplemented in donner::geode::GeodeWgpuAdapterDevice.

◆ onSubmit()

virtual Status donner::gpu::Device::onSubmit	(	uint64_t	submissionSerial,
		uint32_t	commandBufferSlotIndex,
		std::span< const Command >	commands )

protectedpure virtual

Backend hook: a validated command buffer was submitted.

Parameters

submissionSerial	Serial assigned to this submission.
commandBufferSlotIndex	Slot the command buffer occupied before being consumed.
commands	Validated commands, in recording order.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ onSurfaceCapabilities()

virtual Result< SurfaceCapabilities > donner::gpu::Device::onSurfaceCapabilities ( uint32_t slotIndex ) const

protectedvirtual

Backend hook: what a surface supports.

Parameters

slotIndex Slot of the surface.

Reimplemented in donner::geode::GeodeWgpuAdapterDevice.

◆ onUnmapBuffer()

virtual void donner::gpu::Device::onUnmapBuffer ( uint32_t mappingSlotIndex )

protectedvirtual

Backend hook: release a mapping.

Parameters

mappingSlotIndex Slot of the mapping.

Reimplemented in donner::geode::GeodeWgpuAdapterDevice.

◆ onWaitMappingSlice()

virtual MapSliceState donner::gpu::Device::onWaitMappingSlice	(	uint32_t	mappingSlotIndex,
		double	sliceSeconds )

protectedvirtual

Backend hook: wait up to sliceSeconds for a pending mapping and report what it found.

The runtime owns the deadline and the caller's cancellation; this reports only the mapping.

Parameters

mappingSlotIndex	Slot of the pending mapping.
sliceSeconds	Longest this call may block.

Reimplemented in donner::geode::GeodeWgpuAdapterDevice.

◆ onWriteBuffer()

virtual Status donner::gpu::Device::onWriteBuffer	(	uint32_t	slotIndex,
		uint64_t	offsetBytes,
		std::span< const uint8_t >	data )

protectedpure virtual

Backend hook: a validated buffer write.

Parameters

slotIndex	Destination buffer slot.
offsetBytes	Destination byte offset.
data	Payload bytes.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ onWriteTexture()

virtual Status donner::gpu::Device::onWriteTexture	(	uint32_t	slotIndex,
		std::span< const uint8_t >	data,
		const TexelCopyBufferLayout &	dataLayout,
		const Extent2d &	writeSize )

protectedpure virtual

Backend hook: a validated texture write.

Parameters

slotIndex	Destination texture slot.
data	Payload bytes.
dataLayout	Row layout of `data`.
writeSize	Extent written in texels.

Implemented in donner::geode::GeodeWgpuAdapterDevice, donner::gpu::metal::MetalDevice, donner::gpu::RecordingDevice, and donner::gpu::vulkan::VulkanDevice.

◆ poll()

void donner::gpu::Device::poll ( )

Processes deferred destructions: releases the backend object of every destroyed resource whose last referencing submission has completed (completedSerial), and recycles its slot.

Called opportunistically by destroy* and submit; call it directly after waiting for completion to reclaim resources promptly.

◆ presentSurface()

Result< SurfaceStatus > donner::gpu::Device::presentSurface ( const Surface & surface )

Presents the texture acquired from surface and invalidates it.

Not every platform lets a caller present: where the host drives its own frame loop, the frame appears when the host shows it, and asking to present is rejected rather than performed. Such a surface still acquires and still invalidates its texture at the end of the frame through abandonCurrentTexture.

Parameters

surface Live surface with an acquired texture.

◆ submit()

Result< uint64_t > donner::gpu::Device::submit ( CommandBuffer commandBuffer )

Submits a finished command buffer, consuming it, and returns the assigned submission serial.

Serials start at 1 and increase by 1 per submission; a submission rejected here or by the backend does not consume a serial.

Every resource a recorded command references - including bind-group entry resources and the textures behind attachment and entry views - is re-validated against its recorded (slot, generation) identity, so a resource destroyed between recording and submission fails closed with GpuErrorType::InvalidHandle instead of reaching a backend. On success those resources are marked in-use by the new serial, which defers their backend destruction until the submission completes.

Parameters

commandBuffer Command buffer to submit; consumed even on failure.

◆ surfaceCapabilities()

Result< SurfaceCapabilities > donner::gpu::Device::surfaceCapabilities ( const Surface & surface ) const

What surface supports, for choosing a configuration.

Parameters

surface Live surface.

◆ unmapBuffer()

Status donner::gpu::Device::unmapBuffer ( BufferMapping && mapping )

Releases a mapping, invalidating the handle and every copy of it.

Parameters

mapping Mapping to release; consumed either way (see the destroy contract above).

◆ validateBufferHandleForBackend()

Status donner::gpu::Device::validateBufferHandleForBackend ( const Buffer & buffer ) const

protected

Validates a buffer handle for backend-provided auxiliary entry points (test readback helpers and similar), running the same null/device-identity/generation checks the template-method public API performs before its hooks.

Parameters

buffer Handle to validate.

◆ validateBufferMappingHandleForBackend()

Status donner::gpu::Device::validateBufferMappingHandleForBackend ( const BufferMapping & mapping ) const

protected

Validates a buffer-mapping handle for backend-provided auxiliary entry points, running the same null/device-identity/generation checks the template-method public API performs, so a stale handle cannot read state belonging to the slot's new occupant.

Parameters

mapping Handle to validate.

◆ validateTextureHandleForBackend()

Status donner::gpu::Device::validateTextureHandleForBackend ( const Texture & texture ) const

protected

Validates a texture handle for backend-provided auxiliary entry points, running the same null/device-identity/generation checks the template-method public API performs.

Parameters

texture Handle to validate.

◆ validateTextureViewHandleForBackend()

Status donner::gpu::Device::validateTextureViewHandleForBackend ( const TextureView & textureView ) const

protected

Validates a texture view handle for backend-provided auxiliary entry points: the view itself plus a re-resolution of its viewed texture, so a view of a destroyed (or slot-recycled) texture fails closed exactly like it does on the normal Device paths.

Parameters

textureView Handle to validate.

◆ writeBuffer()

Status donner::gpu::Device::writeBuffer	(	const Buffer &	buffer,
		uint64_t	offsetBytes,
		std::span< const uint8_t >	data )

Writes data into buffer at offsetBytes.

Fails closed if the range does not fit (checked arithmetic) or the buffer lacks BufferUsage::CopyDst.

Parameters

buffer	Destination buffer.
offsetBytes	Destination byte offset.
data	Payload bytes.

◆ writeTexture()

Status donner::gpu::Device::writeTexture	(	const Texture &	texture,
		std::span< const uint8_t >	data,
		const TexelCopyBufferLayout &	dataLayout,
		const Extent2d &	writeSize )

Writes texel rows from data into texture starting at texel (0, 0).

Fails closed unless the texture has TextureUsage::CopyDst, dataLayout is 256-aligned and covers writeSize, writeSize fits in the texture, and the described rows fit inside data (checked arithmetic).

Parameters

texture	Destination texture.
data	Payload bytes laid out per `dataLayout`.
dataLayout	Row layout of `data`.
writeSize	Extent to write in texels.

The documentation for this class was generated from the following file:

donner/gpu/Device.h

Classes

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Class Documentation

◆ donner::gpu::Device::MapWaitTestHooks

Member Function Documentation

◆ abandonCurrentTexture()

◆ acquireCurrentTexture()

◆ completedSerial()

◆ configureSurface()

◆ createBindGroup()

◆ createBindGroupLayout()

◆ createBuffer()

◆ createComputePipeline()

◆ createPipelineLayout()

◆ createRenderPipeline()

◆ createSampler()

◆ createShaderModule()

◆ createSurface()

◆ createTexture()

◆ createTextureView()

◆ destroyBindGroup()

◆ destroyBindGroupLayout()

◆ destroyBuffer()

◆ destroyComputePipeline()

◆ destroyPipelineLayout()

◆ destroyRenderPipeline()

◆ destroySampler()

◆ destroyShaderModule()

◆ destroySurface()

◆ destroyTexture()

◆ destroyTextureView()

◆ mapBufferAsync()

◆ mappedBytes()

◆ onAbandonCurrentTexture()

◆ onAcquireCurrentTexture()

◆ onConfigureSurface()

◆ onCreateBindGroup()

◆ onCreateBindGroupLayout()

◆ onCreateBuffer()

◆ onCreateComputePipeline()

◆ onCreatePipelineLayout()

◆ onCreateRenderPipeline()

◆ onCreateSampler()

◆ onCreateShaderModule()

◆ onCreateSurface()

◆ onCreateTexture()

◆ onCreateTextureView()

◆ onDestroyResource()

◆ onMapBufferAsync()

◆ onMappedBytes()

◆ onPresentSurface()

◆ onSubmit()

◆ onSurfaceCapabilities()

◆ onUnmapBuffer()

◆ onWaitMappingSlice()

◆ onWriteBuffer()

◆ onWriteTexture()

◆ poll()

◆ presentSurface()

◆ submit()

◆ surfaceCapabilities()

◆ unmapBuffer()

◆ validateBufferHandleForBackend()

◆ validateBufferMappingHandleForBackend()

◆ validateTextureHandleForBackend()

◆ validateTextureViewHandleForBackend()

◆ writeBuffer()

◆ writeTexture()