SynchronousBufferReadback mixin base

A device that reads a buffer back in the calling turn — DeviceFeature.synchronousReadback.

A capability a device opts into, not a member every device carries, since 1.0: WebGPU has no such call by design, and a member every device had to answer was a member three of four answered with a refusal. Asked with device is SynchronousBufferReadback; a device that is one lists DeviceFeature.synchronousReadback in its features. The software rasteriser and WebGL2 are.

Out of the main library, since 1.0, because a stall is a test's or a tool's tradeoff and never a frame's: a caller that asks for it imports it from package:flutter3d_hardware/testing.dart, and a backend mixes it in from backend.dart.

Superclass constraints
Mixin applications

Properties

backendId → BackendId
The backend's id: the one name a material compiler, a plugin manifest and RuntimeShaders know this backend by, compared exactly.
no setterinherited
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 setterinherited
defaultColorFormat → TextureFormat
The colour format this device prefers.
no setterinherited
defaultDepthStencilFormat → TextureFormat
The depth/stencil format this device prefers. Legitimately TextureFormat.unknown on a context that has none.
no setterinherited
depthRange → DepthRange
What this backend's clip space maps depth onto.
no setterinherited
errors → Stream<DeviceError>
What the device refused after the call that asked, and survived — since 1.0.0-rc.1.
no setterinherited
features → DeviceFeatures
What this device can do — every optional capability, as one set.
no setterinherited
framebufferOrigin → FramebufferOrigin
Where row zero of a render target is.
no setterinherited
gpuTimings → Stream<GpuFrameTimings>
Each frame's GPU timings, a frame or two after it was encoded — since 1.0.0-rc.2, when it replaced onGpuTimings(listener), whose one slot a second caller took from the renderer. A broadcast stream: the renderer, a profiler and a test each listen without taking the others' timings, and a backend measures only while something listens.
no setterinherited
hashCode → int
The hash code for this object.
no setterinherited
hdrColorFormat → TextureFormat
The format to render high dynamic range colour into.
no setterinherited
hdrOutputFormats → List<TextureFormat>
The formats this device can present an extended-range frame in, empty when it can only present standard range.
no setterinherited
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 setterinherited
isSoftware → bool
Whether this device does its work on the CPU, as the software rasteriser does, rather than on a GPU — since 1.0.0-rc.1.
no setterinherited
limits → DeviceLimits
How much of everything this device has. See DeviceLimits.
no setterinherited
lost → Stream<DeviceLoss>
Each time the device stops working: a WebGPU device lost, a WebGL context lost or restored. An external source, so a Stream.
no setterinherited
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
Samples to use for multisampled targets, or 1 for none.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
shaders → ShaderLibrary
The compiled bundle this device was built with.
no setterinherited
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

Methods

beginComputePass({String? label, PassTimestampWrites? timestampWrites}) → ComputeEncoder
Opens a compute pass; label names it to a debugger and to gpuTimings. timestampWrites (since 1.0) names where the pass writes its start and end GPU times — DeviceFeature.timestampQuery.
inherited
beginFrame() → void
Tells the backend a new frame is starting.
inherited
beginRenderPass(RenderPassDescriptor descriptor) → CommandEncoder
Opens a pass and returns the encoder that records into it.
inherited
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.
inherited
createBuffer(BufferDescriptor descriptor, {ByteData? contents}) → StorageBuffer
A buffer of BufferDescriptor.lengthInBytes bytes, for the usages it names, holding contents (zeros by default).
inherited
createComputePipeline(ShaderHandle shader) → ComputePipelineHandle
A pipeline from a compute stage of this device's shader library.
inherited
createComputePipelineAsync(ShaderHandle shader) → Future<ComputePipelineHandle>
createComputePipeline, asynchronously; see createPipelineAsync. For a caller warming a compute pass up behind a loading screen.
inherited
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
Allocates a cube texture a pass can draw into, face by face and level by level, with nothing in it yet.
inherited
createCubeTextureFromPixels({required int size, required TextureFormat format, required List<ByteData> faces, List<List<ByteData>>? mipLevels}) → TextureHandle
Uploads six square images as one cube texture.
inherited
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
Links two stages into something that can be bound.
inherited
createPipelineAsync(ShaderHandle vertex, ShaderHandle fragment, {VertexLayoutDescriptor? layout}) → Future<PipelineHandle>
createPipeline without holding up the caller: the future completes when the pipeline is linked.
inherited
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.
inherited
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. An override calls RenderBundleDescriptor.checkFeatures once it has the feature.
inherited
createTexture(TextureDescriptor descriptor) → TextureHandle
A brand-new texture matching descriptor, with the single TextureHandle that will ever stand for it, contents undefined until written.
inherited
createTextureFromPixels({required int width, required int height, required TextureFormat format, required ByteData pixels, List<ByteData>? mipLevels}) → TextureHandle
Creates a texture already holding pixels.
inherited
dispose() → void
Releases every persistent resource this device holds — the textures and geometry buffers handed out by createTexture, createTextureFromPixels, createCubeTextureFromPixels, createCubeRenderTarget and uploadGeometry.
inherited
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>
Builds a library from a bundle that arrived as bytes.
inherited
mapBuffer(StorageBuffer buffer, MapMode mode, {int offsetInBytes = 0, int? sizeInBytes}) → Future<MappedBuffer>
Maps sizeInBytes bytes (to the end by default) of buffer from offsetInBytes into host memory, once every pass submitted before this call is done with it — DeviceFeature.mappedBuffers.
inherited
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.
inherited
overwriteGeometry(GeometryBuffer target, int offsetInBytes, ByteData bytes) → void
Writes bytes into target starting offsetInBytes into it, in place.
inherited
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.
inherited
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.
inherited
readBuffer(StorageBuffer buffer) → Future<ByteData>
The contents of buffer, once every pass submitted before this call has finished writing it. buffer must be hostReadable.
inherited
readBufferSync(StorageBuffer buffer, {int offsetInBytes = 0, int? sizeInBytes}) → ByteData
The bytes of buffer (a range of them), read back in the calling turn.
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.
inherited
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.
inherited
releasePipeline(PipelineHandle pipeline) → void
Releases a pipeline createPipeline made. Does nothing by default: a backend whose pipelines are reclaimed with their last reference is right to.
inherited
releaseQuerySet(QuerySet querySet) → void
Releases one query set, as releaseStorageBuffer releases a buffer.
inherited
releaseRenderBundle(RenderBundle bundle) → void
Releases a bundle createRenderBundleEncoder recorded.
inherited
releaseSampler(SamplerDescriptor sampler) → void
Gives back what this device made to sample with sampler, if it made anything.
inherited
releaseStorageBuffer(StorageBuffer buffer) → void
Releases one storage buffer, as releaseGeometry releases geometry.
inherited
releaseTexture(TextureHandle texture) → void
Gives one back, rather than waiting for the whole device to go.
inherited
setLabel(Object resource, String label) → void
Names resource — a TextureHandle, GeometryBuffer, StorageBuffer, PipelineHandle, QuerySet or RenderBundle this device made — for a GPU debugger, a frame capture and the memory report.
inherited
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 here: sampled, filtered, rendered, blended, multisampled, resolved, used as depth, bound as storage.
inherited
toString() → String
A string representation of this object.
inherited
uploadGeometry(ByteData bytes, GeometryUsage usage) → GeometryBuffer
Uploads geometry that will outlive the frame.
inherited
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
Writes bytes into target at offsetInBytes, in place. Visible starting the next pass, as overwriteGeometry; an offset and length that do not fit throw an ArgumentError before anything is written.
inherited
writeTexture(TextureHandle target, ByteData data, {TextureRegion? region, int mipLevel = 0, int? bytesPerRow}) → void
Writes data into region (the whole level by default) of level mipLevel of target, in target's own format, rows bytesPerRow apart (tightly packed by default; a compressed format counts rows of blocks). Visible starting the next pass, as overwriteGeometry.
inherited

Operators

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