|
|
| ~BrowserDevice () override |
| | Destructor; releases every browser object this device still owns.
|
| ShaderSourceKind | shaderSourceKind () const override |
| | Shader representation this device accepts; the browser's own shading language.
|
| uint64_t | completedSerial () const override |
| | Serial of the most recent submission the browser has reported finished (0 if none).
|
|
bool | isDeviceLost () const |
| | Whether the browser has reported the device lost. Once true it never becomes false again.
|
| RcString | deviceLostReason () const override |
| | What the browser said when it reported the device lost. Empty while the device is alive.
|
|
uint32_t | maxTextureDimension2D () const |
| | Largest width or height of a 2D texture this device supports, as the browser reports it. WebGPU guarantees at least 8,192, which stands in when the browser reports no limit.
|
|
size_t | liveObjectCountForTest () const |
| | Number of browser objects this device currently owns. Test accessor, for the teardown and slot-reuse contracts.
|
|
uint64_t | foreignThreadReleasesForTest () const |
| | How many releases this device refused because they came from a thread that does not own the browser device. Test accessor; a nonzero count is a caller error, not a device state.
|
|
uint64_t | nestedWaitRefusalsForTest () const |
| | How many waits this device refused for being entered while it was already yielding. Test accessor; a nonzero count is a caller error, not a device state.
|
|
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.
|
| 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 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.
|
| Status | replayCommandBuffer (uint64_t submissionSerial, uint32_t commandBufferIndex, std::span< const Command > commands, std::string_view operation) |
| | Replays one command buffer of a submission through the bridge, leaving it finished and unsubmitted.
|
| Status | onMapBufferAsync (uint32_t mappingSlotIndex, uint32_t bufferSlotIndex, MapMode mode, uint64_t offsetBytes, uint64_t byteCount) override |
| | Backend hook: begin mapping a buffer range.
|
| MapSliceReport | onWaitMappingSlice (uint32_t mappingSlotIndex, double sliceSeconds) override |
| | Backend hook: wait up to sliceSeconds for a pending mapping, and report what it found and how it spent the slice.
|
| bool | onWaitForSerial (uint64_t serial, double timeoutSeconds) override |
| | Yields the thread to the browser until it reports serial complete, the device is lost, or the budget runs out.
|
| Result< std::span< const uint8_t > > | onMappedBytes (uint32_t mappingSlotIndex) const override |
| | Backend hook: bytes of a completed mapping.
|
| void | onUnmapBuffer (uint32_t mappingSlotIndex) override |
| | Backend hook: release a mapping.
|
| Status | onCreateSurface (uint32_t slotIndex, const SurfaceDescriptor &descriptor) override |
| | Backend hook: create a surface for a platform object.
|
| Result< SurfaceCapabilities > | onSurfaceCapabilities (uint32_t slotIndex) const override |
| | Backend hook: what a surface supports.
|
| Status | onConfigureSurface (uint32_t slotIndex, const SurfaceConfiguration &configuration) override |
| | Backend hook: apply a configuration.
|
| Result< SurfaceStatus > | onAcquireCurrentTexture (uint32_t slotIndex, uint32_t textureSlotIndex) override |
| | Backend hook: acquire the next frame's texture and report the surface's state.
|
| Result< SurfaceStatus > | onPresentSurface (uint32_t slotIndex) override |
| | Backend hook: present the acquired texture.
|
| void | onAbandonCurrentTexture (uint32_t slotIndex) override |
| | Backend hook: drop the acquired texture without presenting.
|
| void | onDestroySurface (uint32_t slotIndex) override |
| | Backend hook: release the platform state of a surface that is going away.
|
| BackendDeviceIdentity | backendDeviceIdentity () const override |
| | Names the browser backend and the browser device this device runs on. Fixed when the device is constructed, so the runtime may ask from any thread without reaching the browser.
|
| Result< BackendTextureExport > | onExportTexture (uint32_t slotIndex) override |
| | 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.
|
| Status | onRegisterTexture (uint32_t slotIndex, const ExportedTextureBacking &backing) override |
| | Backend hook: name another device's exported texture in slotIndex.
|
|
| 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 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 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.
|
| 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 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.
|
Browser backend of the Donner GPU runtime.
Inherits every fail-closed validation check from donner::gpu::Device; the on* hooks receive only validated input and express it to the browser's GPU service through a BrowserBridge. Browser objects are named across that boundary by BrowserObjectId rather than by slot index, so an identifier retained past its object's destruction names nothing instead of naming whatever the runtime put in that slot next.
Three refusals are this backend's own, on top of the base class's:
- An operation naming a resource this device has no browser object for fails with GpuErrorType::InvalidHandle. That is a defense in depth rather than the primary check: the base class resolves the handle first, so reaching here with an unregistered slot means the two records disagree, which is exactly the condition worth failing on.
- An operation issued from a context that does not own the browser device fails with GpuErrorType::InvalidState. A browser device belongs to the worker that obtained it and its objects are unusable elsewhere, so this is a hard boundary, not a convention.
- Every operation that can be refused fails with GpuErrorType::InvalidState once the browser reports the device lost. Loss is permanent: a lost device is never regained, and a pending mapping on one can never complete, so waits end immediately rather than spending their budget. Release and teardown paths deliberately proceed instead, so a lost device still frees the browser objects it holds; refusing those would strand them for the life of the page.
Presentation follows the browser's model rather than the runtime's default one: a browser decides for itself when a canvas is shown, so Device::presentSurface is refused on this backend and a frame ends by abandoning its acquired texture. Acquiring, configuring and reconfiguring behave as the runtime documents.
What a NativeSurfaceKind::CanvasSelector names is narrower here than the descriptor suggests, and narrower in a worker than on the main thread. On the main thread it is a CSS selector, resolved against the document. A worker has no document, and a canvas reaches one by being transferred, so there it names the canvas by its element id and a selector that is not a plain id will not resolve. The editor renders from a worker, so that is the case to write against; passing "#canvas" satisfies both readings, which is why it is the form used throughout. Widening this back out is a change to the descriptor's own documentation and belongs with the unit that owns it.
Several devices can run over one browser device in one worker, each through a bridge of its own with its own identifiers, mappings and submission serials; that is how a snapshot capture context sits beside the renderer it reads back. A texture of one is registered on another as a read-only alias of the same browser texture (Device::exportTexture, Device::registerTexture). They submit to the browser device's one queue, in order, from the thread that owns it, so a registration is ordered after the producer's work by submission order alone and nothing waits. WebGPU cannot share a texture across browser devices, so an export of another browser device is refused with GpuErrorType::DeviceMismatch, and loss of the browser device is loss for every device over it.
The compiled WGSL projection is what this backend accepts, matching the browser's own shading language.
Thread affinity: single-threaded use, matching donner::gpu::Device, and additionally pinned to the context that obtained the browser device.
1.15.0 