WebGpuDevice class final

WebGPU as a GraphicsDevice, and as the compiler its shader libraries reach a browser through.

Mixed-in types

Properties

backendId → String
The backend's id: the one name a material compiler, a plugin manifest and RuntimeShaders know this backend by, compared exactly.
no setter
backendName → String
The name a refusal from this device gives as its backend. The runtime type by default; a backend overrides it with the name a person knows it by ("WebGPU", "Impeller").
no setter
debugBindGroupCount → int
How many distinct bind groups this device has assembled. Diagnostic, for the reason debugSamplerCount is: the dynamic offset on a uniform block exists to keep this number small, and nothing else would notice if it stopped working.
no setter
debugDeferredBuilds → int
no setter
debugDeferredDraws → int
How many draws were skipped while their pipeline was built off the frame, and how many of those builds arrived before the fallback, for a test.
no setter
debugSamplerCount → int
Every GPU object this device owns and would have to release: the textures and geometry it handed out, the frame arenas and fallbacks it made for itself, and the modules, layouts, samplers, bind groups and _pipelines it cached.
no setter
debugTrackedResourceCount → int
no setter
debugWarmedPipelines → int
How many pipelines createPipelineAsync built ahead of a draw, and how many states it tried that the browser refused, for a test.
no setter
debugWarmRefused → int
no setter
defaultColorFormat → TextureFormat
The colour format this device prefers.
no setter
defaultDepthStencilFormat → TextureFormat
depth32float-stencil8 where the adapter granted it, and depth24plus-stencil8 where it did not — A2.8. A float is what lets RenderSettings.reversedDepth keep its precision to the horizon, which is why features reports DeviceFeature.reversedDepth exactly where this answers the first; depth24plus may be stored either way, and the browser does not say which.
no setter
deferPipelineBuilds ↔ bool?
Whether a draw that meets a state no pipeline was built in yet builds it off the frame, through createRenderPipelineAsync, and is skipped until it arrives — for one frame at most, after which it is built in place (WebGpuPipelineCache.forDraw).
getter/setter pair
defersPipelineBuilds → bool
What deferPipelineBuilds decides for the frame being drawn.
no setter
depthRange → DepthRange
Near at zero, far at one. The engine builds its projections for this and corrects at the boundary for a backend that says otherwise, so this is the case that needs no correction.
no setter
features → DeviceFeatures
Every capability, decided once from what the device was granted — see webgpuDeviceFeatures, which is where each answer and each absence is explained, and which runs on the VM.
latefinal
framebufferOrigin → FramebufferOrigin
Top left, like Metal and Impeller and unlike OpenGL. WebGPU's framebuffer coordinates start at the top left corner and its attachments are written from there, so nothing has to be turned over anywhere: an uploaded image and a rendered one are the same way up, which is the pair the WebGL2 backend has to keep apart with a flag on every texture.
no setter
hashCode → int
The hash code for this object.
no setterinherited
hdrColorFormat → TextureFormat
The format to render high dynamic range colour into.
no setter
hdrOutputFormats → List<TextureFormat>
rgba16float on a display the browser says has a high dynamic range — R9 — asked once, when the device is made. A frame in it is presented through a canvas configured for extended tone mapping; see copyToCanvas.
no setter
isLost → bool
Whether the device is lost now, and not restored — the state lost reports the changes of, so a caller that subscribed late can ask. Every backend that reports on lost answers here too.
no setter
limits → DeviceLimits
The device's own limits, as granted — open asks for no raised ones, so these are what the adapter gives every device by default — with three answers of this backend's own:
latefinal
lost → Stream<DeviceLoss>
The device's lost promise, as GraphicsDevice.lost: one event, never recoverable — a WebGPU device that is lost stays lost, and the application opens another. dispose is reported here too, as DeviceLossReason.destroyed, before the stream closes.
no setter
pipelineRefusals → PipelineRefusals
The pipelines this device could not build or link, and what to do with a draw that needs one.
no setterinherited
preferredSampleCount → int
Four, which is the only multisample count above one WebGPU guarantees.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
shaders → ShaderLibrary
The compiled bundle this device was built with.
no setter
shareableKinds → Set<NativeHandleKind>
The NativeHandleKinds this device can both export and import. Empty on a device without DeviceFeature.sharedTextures, sharedBuffers or sharedFences, which is every backend in this repository today.
no setterinherited
viewType → String
The platform view type this device's canvas is registered under.
latefinal

Methods

applyCanvasStyle({BoxFit fit = BoxFit.fill, FilterQuality quality = FilterQuality.none}) → void
Styles the canvas through CSS, honouring fit and quality the way Flutter would if it composited these pixels itself.
beginComputePass({String? label, PassTimestampWrites? timestampWrites}) → ComputeEncoder
Opens a compute pass; label names it to a debugger and to onGpuTimings. timestampWrites (since 1.0) names where the pass writes its start and end GPU times — DeviceFeature.timestampQuery.
beginFrame() → void
Rewinds the three frame arenas, then hands over what the browser said since the last frame.
beginRenderPass(RenderPassDescriptor descriptor) → CommandEncoder
Opens a pass and returns the encoder that records into it.
beginTransferPass({String? label}) → TransferEncoder
Opens a pass of copies between buffers and textures. Never refused — each copy is gated by its own feature. See TransferEncoder. By default a pass whose every copy refuses by its feature, and whose submit has nothing to send.
compileModule(String name, String wgsl) → Object
Turns wgsl into a GPUShaderModule, and asks the browser what it thought of it.
override
copyToCanvas(TextureHandle frame) → void
Copies frame into the canvas the browser composites.
createBuffer(BufferDescriptor descriptor, {ByteData? contents}) → StorageBuffer
A general buffer. Its host usages are realised as gpuBufferUsageOf says — a real mapping where WebGPU allows one beside the rest, a staging copy or a queue write where it does not.
createComputePipeline(ShaderHandle shader) → ComputePipelineHandle
A pipeline from a compute stage of this device's shader library.
createComputePipelineAsync(ShaderHandle shader) → Future<ComputePipelineHandle>
createComputePipeline through createComputePipelineAsync: a compute pipeline has no draw state, so the whole of it is realised here, off the calling turn, and a pipeline the browser refuses completes the future with the error rather than surfacing later at debugDrainErrors.
createComputePipelineFrom(ComputePipelineDescriptor descriptor) → ComputePipelineHandle
The compute pipeline descriptor describes, for createPipelineFrom's reason. By default it builds through createComputePipeline (so a device without DeviceFeature.compute refuses it as compute) and gives it ComputePipelineDescriptor.label.
inherited
createComputePipelineFromAsync(ComputePipelineDescriptor descriptor) → Future<ComputePipelineHandle>
createComputePipelineFrom, asynchronously, through createComputePipelineAsync by default.
inherited
createCubeRenderTarget({required int size, required TextureFormat format, int mipLevels = 1}) → TextureHandle
A cube a pass may aim at one face and one level of.
createCubeTextureFromPixels({required int size, required TextureFormat format, required List<ByteData> faces, List<List<ByteData>>? mipLevels}) → TextureHandle
Uploads six square images as one cube texture.
createFence() → GpuFence
A timeline fence at value zero, which signalFence raises and waitFence waits for — DeviceFeature.sharedFences.
inherited
createPipeline(ShaderHandle vertex, ShaderHandle fragment, {VertexLayoutDescriptor? layout}) → PipelineHandle
Records the stage pair, its layout and the reflection a bind group will need. Nothing is built: see WebGpuPipeline, and webgpu_encoder.dart for what a draw does with it.
createPipelineAsync(ShaderHandle vertex, ShaderHandle fragment, {VertexLayoutDescriptor? layout}) → Future<PipelineHandle>
createPipeline, and the real pipelines it will need built off the calling turn, through createRenderPipelineAsync.
createPipelineFrom(PipelineDescriptor descriptor) → PipelineHandle
The pipeline descriptor describes: the entry point every pipeline input after 1.0 arrives through.
inherited
createPipelineFromAsync(PipelineDescriptor descriptor) → Future<PipelineHandle>
createPipelineFrom without holding up the caller, as createPipelineAsync is to createPipeline. By default it goes through createPipelineAsync, so a backend that compiles off the thread there does so here too.
inherited
createQuerySet(QueryType type, int count) → QuerySet
A set of count queries of type — DeviceFeature.occlusionQuery, DeviceFeature.timestampQuery or DeviceFeature.pipelineStatisticsQuery, the feature QueryType.feature names.
createRenderBundleEncoder(RenderBundleDescriptor descriptor) → RenderBundleEncoder
Opens an encoder whose draws are kept as a RenderBundle, to be replayed into any pass whose attachments match descriptor — DeviceFeature.renderBundles. See RenderBundleEncoder for what a bundle cannot record.
createTexture(TextureDescriptor descriptor) → TextureHandle
Any shape — webgpuCreateTextureWithDescriptor checks what the browser would otherwise refuse asynchronously; the features each shape needs are refused here first.
createTextureFromPixels({required int width, required int height, required TextureFormat format, required ByteData pixels, List<ByteData>? mipLevels}) → TextureHandle
Creates a texture already holding pixels.
debugDrainErrors({String where = ''}) → Future<String?>
Everything the browser complained about since the last drain, or null when it complained about nothing.
decodeTexture(Uint8List encoded, {bool mipmaps = false, int? maxDimension}) → Future<TextureHandle>
Decoded by the browser, copied in with copyExternalImageToTexture, and given a chain drawn level by level on the GPU — A4.16. See webgpu_image_decode.dart.
dispose() → void
Releases everything: the textures and buffers handed out, the arenas, the caches, the canvas's configuration and the device itself.
exportBuffer(StorageBuffer buffer, {NativeHandleKind? kind}) → NativeHandle
exportTexture for a buffer — DeviceFeature.sharedBuffers.
inherited
exportFence(GpuFence fence, {NativeHandleKind? kind}) → NativeHandle
fence as a NativeHandle of kind, for another device to import.
inherited
exportTexture(TextureHandle texture, {NativeHandleKind? kind}) → NativeHandle
texture's memory as a NativeHandle of kind (the first of shareableKinds by default), for another device or API to import — DeviceFeature.sharedTextures. The handle is valid while texture is.
inherited
importBuffer(NativeHandle handle, BufferDescriptor descriptor) → StorageBuffer
importTexture for a buffer — DeviceFeature.sharedBuffers.
inherited
importFence(NativeHandle handle) → GpuFence
A fence over the one handle names, which another device made.
inherited
importTexture(NativeHandle handle, TextureDescriptor descriptor) → TextureHandle
A texture shaped like descriptor over the memory handle names, which another device or API made and keeps — DeviceFeature.sharedTextures. Released like any texture; the memory stays its maker's.
inherited
labelOf(Object resource) → String?
The label setLabel gave resource, or null when it has none.
inherited
loadShaders(ByteData bytes) → Future<LoadedShaderLibrary>
The bundle's own WGSL, compiled by this device, as a library that can be reloaded.
mapBuffer(StorageBuffer buffer, MapMode mode, {int offsetInBytes = 0, int? sizeInBytes}) → Future<MappedBuffer>
mapAsync, on the buffer itself where it was made mappable and through a staging copy or a queue write where its other usages rule that out — see gpuBufferUsageOf.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onFrameComplete(void whenDone()) → void
Runs whenDone once the GPU has finished with the frame being encoded now.
onGpuTimings(void listener(GpuFrameTimings timings)?) → void
Sets where each frame's GPU timings go, a frame or two after it was encoded; null stops them. The engine does not call it on a device whose features lack DeviceFeature.gpuTimestamps; a backend without the feature may still answer a caller that asks, with what it can measure and its doc saying what that is (Impeller times each labelled pass from submission to completion, and puts it on the Dart timeline).
overwriteGeometry(GeometryBuffer target, int offsetInBytes, ByteData bytes) → void
Writes bytes into target starting offsetInBytes into it, in place.
overwriteTexture(TextureHandle target, ByteData rgba, {ScreenRect? region, int mipLevel = 0}) → Future<void>
Overwrites region (the whole texture by default) of target's base level with rgba — raw RGBA8 bytes, region.width * region.height * 4 of them, row-major from the top the same way readback answers them.
readback(TextureHandle texture, {ScreenRect? region}) → Future<ByteData>
The pixels of region — the whole texture by default — as they stand at this point in the queue: premultiplied RGBA8, row-major from the top-left, the region's own width times four per row.
readBuffer(StorageBuffer buffer) → Future<ByteData>
The contents of buffer, once every pass submitted before this call has finished writing it. buffer must be hostReadable.
readQueryResults(QuerySet querySet, {int first = 0, int? count}) → Future<List<int>>
The results of count queries of querySet from first, once every pass submitted before this call has finished: sample counts for occlusion, nanoseconds for timestamps, and for pipeline statistics one value per PipelineStatistic per query, in its order. A query no pass wrote reads zero. By default refused by the feature of the set's own type.
refuse(DeviceFeature feature, {String? reason}) → UnsupportedCapabilityException
The refusal for feature on this device, for a default body or a backend's own gate to throw: throw refuse(DeviceFeature.compute).
inherited
refuseResource(String operation, String reason, {Object? cause}) → DeviceResourceException
The refusal for a request this device has the feature for and still cannot honour, for a backend to throw from operation: throw refuseResource('createTextureFromPixels', 'the pixels are …').
inherited
releaseComputePipeline(ComputePipelineHandle pipeline) → void
Releases a pipeline createComputePipeline made, as releasePipeline.
inherited
releaseFence(GpuFence fence) → void
Releases a fence createFence or importFence made.
inherited
releaseGeometry(GeometryBuffer geometry) → void
Releases one geometry buffer, rather than waiting for the whole device to go.
releasePipeline(PipelineHandle pipeline) → void
Forgets what was built for pipeline's pair and layout once no other handle stands for them: every GPURenderPipeline the draws built in whatever state, and — when the pair has no handle left under any layout — its bind group layouts and the bind groups made from them.
releaseQuerySet(QuerySet querySet) → void
Releases one query set, as releaseStorageBuffer releases a buffer.
releaseRenderBundle(RenderBundle bundle) → void
Releases a bundle createRenderBundleEncoder recorded.
inherited
releaseSampler(SamplerDescriptor sampler) → void
Drops the GPUSampler made for sampler, and every cached bind group that holds it, so the object can be collected: WebGPU has no destroy for a sampler. The next bind of an equal description makes a new one.
releaseStorageBuffer(StorageBuffer buffer) → void
Releases one storage buffer, as releaseGeometry releases geometry.
releaseTexture(TextureHandle texture) → void
Gives one back, rather than waiting for the whole device to go.
setLabel(Object resource, String label) → void
Passes the label to the browser, which names the object in its own validation errors and in a frame capture, and keeps it for labelOf.
signalFence(GpuFence fence, int value) → void
Raises fence to value on this device's queue once the work submitted before this call is done. value only grows.
inherited
textureFormatSupport(TextureFormat format) → TextureFormatSupport
What format can be used for on what this device was granted — see webgpuTextureFormatSupport. Its sampled is what supportsTextureFormat answers.
toString() → String
A string representation of this object.
inherited
uploadGeometry(ByteData bytes, GeometryUsage usage) → GeometryBuffer
Uploads geometry that will outlive the frame.
waitFence(GpuFence fence, int value) → void
Holds the work this device submits after this call until fence reaches value. The CPU does not wait.
inherited
writeBuffer(StorageBuffer target, int offsetInBytes, ByteData bytes) → void
queue.writeBuffer, from an offset that is a multiple of four. A length that is not one is allowed only where it runs to the end of the buffer, whose allocation was rounded up to four: anywhere else the padding writeBuffer needs would land on bytes the caller did not name.
writeTexture(TextureHandle target, ByteData data, {TextureRegion? region, int mipLevel = 0, int? bytesPerRow}) → void
queue.writeTexture, which takes any row stride.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

open({required int width, required int height, WebGpuSectionStages? stages, Future<ByteData?> loadAsset(String key)?}) → Future<WebGpuDevice>
Opens a device over a canvas of width by height, with the engine's own stages unless others are given — WGSL translated from flutter3d_shaders, beside the reflection a GPUShaderModule cannot be asked for.

Constants

warmStateLimit → const int
How many draw states createPipelineAsync warms a new pair in, at most: the most recently built distinct ones.