donner::gpu::Device Class Reference

Abstract GPU device: resource creation, queue writes, and submission with shared fail-closed validation (design 0053 "Proposed Architecture", "Validation layer"). More...

#include "donner/gpu/Device.h"

Inheritance diagram for donner::gpu::Device:

Public Member Functions
virtual	~Device ()
	Destructor; frees all remaining resources.
	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.
Status	destroyBuffer (const Buffer &buffer)
	Destroys a buffer; the handle and all references to it become stale.
Status	destroyTexture (const Texture &texture)
	Destroys a texture; the handle and all references to it become stale.
Status	destroyTextureView (const TextureView &textureView)
	Destroys a texture view; the handle and all references to it become stale.
Status	destroySampler (const Sampler &sampler)
	Destroys a sampler; the handle and all references to it become stale.
Status	destroyBindGroupLayout (const BindGroupLayout &bindGroupLayout)
	Destroys a bind group layout; the handle and all references to it become stale.
Status	destroyBindGroup (const BindGroup &bindGroup)
	Destroys a bind group; the handle and all references to it become stale.
Status	destroyPipelineLayout (const PipelineLayout &pipelineLayout)
	Destroys a pipeline layout; the handle and all references to it become stale.
Status	destroyShaderModule (const ShaderModule &shaderModule)
	Destroys a shader module; the handle and all references to it become stale.
Status	destroyRenderPipeline (const RenderPipeline &renderPipeline)
	Destroys a render pipeline; the handle and all references to it become stale.
Result< std::unique_ptr< CommandEncoder > >	createCommandEncoder ()
	Creates a command encoder recording against this device. The encoder must not outlive the device.
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.
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 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.
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 (design 0053 "Proposed Architecture", "Validation layer").

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 today, platform backends in later packets - 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: resources are freed by explicit destroy* calls; device teardown frees everything that remains (handles are not RAII in this packet, see Handles.h). Handles must not be used after their device is destroyed.

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.

Member Function Documentation

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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.

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.

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

(

const BindGroup &

bindGroup

)

Destroys a bind group; the handle and all references to it become stale.

Parameters

bindGroup

Handle to destroy.

destroyBindGroupLayout()

Status donner::gpu::Device::destroyBindGroupLayout

(

const BindGroupLayout &

bindGroupLayout

)

Destroys a bind group layout; the handle and all references to it become stale.

Parameters

bindGroupLayout

Handle to destroy.

destroyBuffer()

Status donner::gpu::Device::destroyBuffer

(

const Buffer &

buffer

)

Destroys a buffer; the handle and all references to it become stale.

Parameters

buffer

Handle to destroy.

destroyPipelineLayout()

Status donner::gpu::Device::destroyPipelineLayout

(

const PipelineLayout &

pipelineLayout

)

Destroys a pipeline layout; the handle and all references to it become stale.

Parameters

pipelineLayout

Handle to destroy.

destroyRenderPipeline()

Status donner::gpu::Device::destroyRenderPipeline

(

const RenderPipeline &

renderPipeline

)

Destroys a render pipeline; the handle and all references to it become stale.

Parameters

renderPipeline

Handle to destroy.

destroySampler()

Status donner::gpu::Device::destroySampler

(

const Sampler &

sampler

)

Destroys a sampler; the handle and all references to it become stale.

Parameters

sampler

Handle to destroy.

destroyShaderModule()

Status donner::gpu::Device::destroyShaderModule

(

const ShaderModule &

shaderModule

)

Destroys a shader module; the handle and all references to it become stale.

Parameters

shaderModule

Handle to destroy.

destroyTexture()

Status donner::gpu::Device::destroyTexture

(

const Texture &

texture

)

Destroys a texture; the handle and all references to it become stale.

Parameters

texture

Handle to destroy.

destroyTextureView()

Status donner::gpu::Device::destroyTextureView

(

const TextureView &

textureView

)

Destroys a texture view; the handle and all references to it become stale.

Parameters

textureView

Handle to destroy.

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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::gpu::metal::MetalDevice, and donner::gpu::RecordingDevice.

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 by the backend does not consume a serial.

Known gap: commands are validated at recording time, so destroying a resource between recording and submit is not yet detected here. Deferred-destruction validation arrives with the resource-lifetime and submission packet (design 0053 change sequence step 3).

Parameters

commandBuffer

Command buffer to submit; consumed even on failure.

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.

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