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 → String
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
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
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
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 onGpuTimings. 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.
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
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).
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