|
|
| RecordingDevice ()=default |
| | Constructs an empty recording device.
|
|
| ~RecordingDevice () override=default |
| | Destructor.
|
| std::string | serialize () const |
| | Returns the deterministic line-based text capture of every recorded operation, in order.
|
| uint64_t | completedSerial () const override |
| | Serial of the most recent submission; recording completes instantly.
|
|
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.
|
| bool | isLost () const |
| | True once the backend root this device drives has been declared lost, either by the backend's device-lost callback or by a bounded wait giving up on it.
|
|
DeviceLossSnapshot | deviceLossSnapshot () const |
| | First-winner loss attribution, once its diagnostic fields have settled.
|
| virtual RcString | deviceLostReason () const |
| | Backend-provided loss reason, when the backend retains one. Empty otherwise.
|
| void | markLostAfterWaitTimeout (DeviceLostWaitSite site, std::chrono::milliseconds elapsed, const char *reason) const |
| | Declares this device's backend root lost because a bounded wait gave up, recording which wait it was and how long it actually ran.
|
| virtual ShaderSourceKind | shaderSourceKind () const |
| | Shader representation accepted by this device. Recording and WebGPU devices use WGSL; native backends override this so callers select the matching build-time artifact.
|
| virtual bool | supportsFullIndexRange (IndexFormat format) const |
| | Whether indexed draws through this device honor every value of format. Metal and WebGPU always do; a Vulkan device without fullDrawIndexUint32 caps 32-bit indices below the full range, and RenderPassEncoder::setIndexBuffer refuses that format on it rather than let a driver truncate index values.
|
| Result< Buffer > | createBuffer (const BufferDescriptor &descriptor) |
| | Creates a buffer.
|
| Result< Texture > | createTexture (const TextureDescriptor &descriptor) |
| | Creates a 2D texture.
|
| Result< TextureDescriptor > | textureDescriptor (const Texture &texture) const |
| | Returns the descriptor texture was created with, by value.
|
| 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).
|
| Status | destroyBufferBacking (Buffer &&buffer) |
| | Destroys buffer and releases its backend allocation at once, rather than leaving the allocation to the backend's own collector.
|
| Status | destroyTextureBacking (Texture &&texture) |
| | Destroys texture and releases its backend allocation at once, the texture counterpart of destroyBufferBacking; a succession of resized render targets is where the deferred release shows up as retained memory.
|
| bool | ownsTextureBacking (const Texture &texture) const |
| | Whether texture names backing this device allocated, rather than memory some other owner holds and this device only named.
|
| Result< TextureExport > | exportTexture (const Texture &texture) |
| | Exports texture so another runtime device over the same backend device can register it.
|
| Result< Texture > | registerTexture (const TextureExport &source) |
| | Registers a texture another runtime device exported, as a read-only texture of this one.
|
| bool | waitForTextureSource (const Texture ®istration, double timeoutSeconds) |
| | Waits until work naming registration may be submitted, the budget runs out, or either device is lost, and reports whether it may.
|
| SerialWaitResult | waitForTextureSourceUnlessStalled (const Texture ®istration, std::chrono::milliseconds stallBound) |
| | waitForTextureSource for a caller whose bound exists to detect a hung producer: the wait gives up only once the producer has made no progress for stallBound, measured from that progress, rather than giving the producer's whole backlog a fixed budget.
|
| uint64_t | sharedTextureTailBytes () const |
| | Bytes of this device's exported textures that are still held by an export token or a registration after this device released its own handle.
|
|
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< MapSliceReport > | pollMapping (const BufferMapping &mapping) |
| | Polls a mapping once without blocking or yielding; ready mappings become readable.
|
| Result< MapWaitReport > | waitForMapping (const BufferMapping &mapping, const MapWaitParams ¶ms, const std::function< bool()> &shouldCancel, const MapWaitTestHooks &testHooks={}) |
| | Waits for a pending mapping in slices, until it completes, the caller stops it, the budget runs out, or the device is lost.
|
| 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, const Origin2d &destinationOrigin={}) |
| | Writes texel rows from data into the writeSize rectangle of texture whose top-left texel is destinationOrigin, leaving every texel outside that rectangle unchanged.
|
| Result< uint64_t > | submit (CommandBuffer commandBuffer) |
| | Submits a finished command buffer, consuming it, and returns the assigned submission serial.
|
| Result< uint64_t > | submit (std::span< CommandBuffer > commandBuffers) |
| | Submits finished command buffers as one submission, consuming them, and returns the single 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.
|
|
void | pollCompletionOnce () |
| | Drive one nonblocking backend completion iteration even when no resource destroy is pending.
|
|
bool | hasPendingDestroys () const |
| | Whether a completed submission can still release a backend object. Owner-thread only.
|
|
uint64_t | lastSubmittedSerial () const |
| | Serial assigned to the most recent submission (0 if none yet).
|
| bool | waitForSerial (uint64_t serial, double timeoutSeconds) |
| | Blocks until completedSerial reaches serial, timeoutSeconds elapses, or the backend gives up on the work, and reports whether the submission completed.
|
| SerialWaitResult | waitForSerialUnlessStalled (uint64_t serial, std::chrono::milliseconds stallBound) |
| | Blocks until completedSerial reaches serial, giving up only when the work the serial waits behind stops making progress.
|
| std::optional< std::chrono::steady_clock::time_point > | lastProgress () |
| | When the work this device's submissions wait behind last made progress, or nothing when the backend has no notion of progress.
|
| Status | installObserver (DeviceObserver &observer) |
| | Installs observer to be notified of the work this device accepts (see DeviceObserver).
|
| void | removeObserver (const DeviceObserver &observer) |
| | Removes observer when it is the installed one and otherwise changes nothing, so an owner can only ever remove its own.
|
|
const DeviceObserver * | observer () const |
| | The installed observer, or null when there is none.
|
|
| Status | onCreateBuffer (uint32_t slotIndex, const BufferDescriptor &descriptor) override |
| | Backend hook: a buffer passed validation and occupies slotIndex.
|
| Status | onCreateTexture (uint32_t slotIndex, const TextureDescriptor &descriptor) override |
| | Backend hook: a texture passed validation and occupies slotIndex.
|
| Status | onCreateTextureView (uint32_t slotIndex, uint32_t textureSlotIndex, const TextureViewDescriptor &descriptor) override |
| | Backend hook: a texture view passed validation and occupies slotIndex.
|
| Status | onCreateSampler (uint32_t slotIndex, const SamplerDescriptor &descriptor) override |
| | Backend hook: a sampler passed validation and occupies slotIndex.
|
| Status | onCreateBindGroupLayout (uint32_t slotIndex, const BindGroupLayoutDescriptor &descriptor) override |
| | Backend hook: a bind group layout passed validation and occupies slotIndex.
|
| Status | onCreateBindGroup (uint32_t slotIndex, const BindGroupDescriptor &descriptor) override |
| | Backend hook: a bind group passed validation and occupies slotIndex.
|
| Status | onCreatePipelineLayout (uint32_t slotIndex, const PipelineLayoutDescriptor &descriptor) override |
| | Backend hook: a pipeline layout passed validation and occupies slotIndex.
|
| Status | onCreateShaderModule (uint32_t slotIndex, const ShaderModuleDescriptor &descriptor) override |
| | Backend hook: a shader module passed validation and occupies slotIndex.
|
| Status | onCreateRenderPipeline (uint32_t slotIndex, const RenderPipelineDescriptor &descriptor) override |
| | Backend hook: a render pipeline passed validation and occupies slotIndex.
|
| Status | onCreateComputePipeline (uint32_t slotIndex, const ComputePipelineDescriptor &descriptor) override |
| | Backend hook: a compute pipeline passed validation and occupies slotIndex.
|
| void | onDestroyResource (std::string_view resourceName, uint32_t slotIndex) override |
| | Backend hook: a retired resource is no longer used by submitted work and can be released.
|
| Status | onWriteBuffer (uint32_t slotIndex, uint64_t offsetBytes, std::span< const uint8_t > data) override |
| | Backend hook: a validated buffer write.
|
| Status | onWriteTexture (uint32_t slotIndex, std::span< const uint8_t > data, const TexelCopyBufferLayout &dataLayout, const Extent2d &writeSize, const Origin2d &destinationOrigin) override |
| | Backend hook: a validated texture write. The written rectangle is writeSize texels wide and tall with its top-left texel at destinationOrigin; texels outside it keep their contents.
|
| Status | onSubmit (uint64_t submissionSerial, std::span< const SubmittedCommandBuffer > commandBuffers) override |
| | Backend hook: validated command buffers were submitted as one submission.
|
|
| Device () |
| | Constructor for backends; assigns the process-unique device identity.
|
| virtual void | onPollBackend () |
| | One nonblocking backend event iteration before a pending-destroy scan. Native devices report completion directly; callback-driven adapters override this hook.
|
| void | adoptLostState (std::shared_ptr< DeviceLostState > state) |
| | Adopts the sticky loss condition of a backend root this device shares with another device.
|
| uint64_t | bufferLastUseSerial (uint32_t slotIndex) const |
| | Last accepted submission referencing a buffer slot already validated by the caller.
|
| uint64_t | textureLastUseSerial (uint32_t slotIndex) const |
| | Last accepted submission referencing a texture slot already validated by the caller.
|
| virtual void | onRetireBuffer (uint32_t slotIndex) |
| | Backend hook: a buffer handle was retired. Discard unsubmitted work, but keep native resources alive until onDestroyResource.
|
| virtual void | onRetireTexture (uint32_t slotIndex) |
| | Backend hook: a texture handle was retired. Discard unsubmitted work, but keep native resources alive until onDestroyResource.
|
| virtual void | onDestroyBufferBacking (uint32_t slotIndex) |
| | Backend hook: destroyBufferBacking validated slotIndex and is about to destroy its handle; release the allocation now rather than when the slot is recycled.
|
| virtual void | onDestroyTextureBacking (uint32_t slotIndex) |
| | Backend hook: the texture counterpart of onDestroyBufferBacking, with the same default. A slot whose backing this device does not own keeps its allocation.
|
| virtual bool | onOwnsTextureBacking (uint32_t slotIndex) const |
| | Backend hook: whether slotIndex holds backing this device allocated.
|
| virtual BackendDeviceIdentity | backendDeviceIdentity () const |
| | Backend hook: which backend family this device belongs to and which native device it records against, for matching an export against a registering device.
|
| virtual Result< BackendTextureExport > | onExportTexture (uint32_t slotIndex) |
| | Backend hook: export the texture in slotIndex, which the runtime has already validated as a live texture this device allocated and no surface has out.
|
| virtual Status | onRegisterTexture (uint32_t slotIndex, const ExportedTextureBacking &backing) |
| | Backend hook: name another device's exported texture in slotIndex.
|
| virtual bool | onTextureWritePending (uint32_t slotIndex) const |
| | Backend hook: whether the write writeTexture just accepted for slotIndex is waiting for this device's next submission, rather than complete or ordered on the queue already.
|
| virtual bool | onWaitForSerial (uint64_t serial, double timeoutSeconds) |
| | Backend hook: waitForSerial with a budget already clamped to zero or more.
|
| virtual SerialWaitResult | onWaitForSerialUnlessStalled (uint64_t serial, std::chrono::milliseconds stallBound) |
| | Backend hook: waitForSerialUnlessStalled with a bound already clamped.
|
| virtual std::optional< std::chrono::steady_clock::time_point > | onLastProgress () |
| | Backend hook: lastProgress. The default reports no notion of progress.
|
| 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 MapSliceReport | onWaitMappingSlice (uint32_t mappingSlotIndex, double sliceSeconds) |
| | Backend hook: wait up to sliceSeconds for a pending mapping, and report what it found and how it spent the slice.
|
| 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.
|
| uint64_t | lastTextureUseSerial (uint32_t textureSlotIndex) const |
| | Serial of the last submission that referenced the texture at textureSlotIndex, or 0 when nothing has submitted work naming it.
|
| virtual void | onDestroySurface (uint32_t slotIndex) |
| | Backend hook: release the platform state of a surface that is going away.
|
| virtual Status | onSubmitAfterSources (uint64_t submissionSerial, std::span< const SubmittedCommandBuffer > commandBuffers, std::span< const SourceWait > waits) |
| | Backend hook: onSubmit for a submission that must also wait on the device, before any of its work runs, for producer work it names through registrations ordered on the device (SourceOrdering::WaitOnDevice).
|
| virtual uint64_t | onTextureWriteByteCount (std::span< const uint8_t > data) const |
| | Backend hook: the bytes the write onWriteTexture just accepted handed the backend's queue, which DeviceObserver::onTextureWritten reports.
|
|
void | notifyObserverOfBackendSubmission () const |
| | Reports a queue submission the backend made on its own, outside submit, to the installed observer as a submission of no command buffers and no draws.
|
Deterministic recording backend.
Inherits every fail-closed validation check from Device and records each validated operation as a line of text. serialize returns the capture: repeated identical operation streams serialize byte-identically, resources are identified by stable slot-based ids like buffer#0 (never pointers or process state), descriptor fields are dumped in full with fixed formatting, and data payloads appear as byte counts plus a content hash.
Submission completes instantly: completedSerial always equals Device::lastSubmittedSerial.
1.15.0 