RecordingDevice class final

A GraphicsDevice that passes every call to inner and keeps it as a TraceEvent in events; see the library comment.

A call the trace format has no event for is passed through and named in unrecorded, so a trace that would not replay faithfully says so.

Inheritance

• Object
• GraphicsDevice
• RecordingDevice

Mixed-in types

• SynchronousBufferReadback

Constructors

RecordingDevice(GraphicsDevice inner)

Creates a recorder over inner, with nothing recorded yet.

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 setter, override

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, override

defaultColorFormat → TextureFormat

The colour format this device prefers.

no setter, override

defaultDepthStencilFormat → TextureFormat

The depth/stencil format this device prefers. Legitimately TextureFormat.unknown on a context that has none.

no setter, override

depthRange → DepthRange

What this backend's clip space maps depth onto.

no setter, override

errors → Stream<DeviceError>

What the device refused after the call that asked, and survived — since 1.0.0-rc.1.

no setter, override

events → List<TraceEvent>

What was asked, in order.

final

features → DeviceFeatures

What this device can do — every optional capability, as one set.

no setter, override

framebufferOrigin → FramebufferOrigin

Where row zero of a render target is.

no setter, override

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 setter, override

hashCode → int

The hash code for this object.

no setter, inherited

hdrColorFormat → TextureFormat

The format to render high dynamic range colour into.

no setter, override

hdrOutputFormats → List<TextureFormat>

The formats this device can present an extended-range frame in, empty when it can only present standard range.

no setter, override

inner → GraphicsDevice

The device every call goes through to.

final

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, override

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 setter, override

limits → DeviceLimits

How much of everything this device has. See DeviceLimits.

no setter, override

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 setter, override

pipelineRefusals → PipelineRefusals

The inner device's: its encoders are the ones that report, and a renderer drawing through this recorder takes the reports from here.

no setter, override

preferredSampleCount → int

Samples to use for multisampled targets, or 1 for none.

no setter, override

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

shaders → ShaderLibrary

The compiled bundle this device was built with.

no setter, override

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 setter, override

unrecorded → List<String>

The 1.0-surface calls this recording forwarded without tracing, in order. Empty for every frame the engine draws today.

final

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.

override

beginFrame() → void

Tells the backend a new frame is starting.

override

beginRenderPass(RenderPassDescriptor descriptor) → CommandEncoder

Opens a pass and returns the encoder that records into it.

override

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.

override

createBuffer(BufferDescriptor descriptor, {ByteData? contents}) → StorageBuffer

A storage buffer — the usages createStorageBuffer made before 1.0 folded it in here, with its whole contents given or none — is recorded as createStorageBuffer, the event a trace has always carried for one; any other buffer is passed on and noted as unrecorded.

override

createComputePipeline(ShaderHandle shader) → ComputePipelineHandle

A pipeline from a compute stage of this device's shader library.

override

createComputePipelineAsync(ShaderHandle shader) → Future<ComputePipelineHandle>

The inner device's own, recorded when it completes; see createPipelineAsync.

override

createComputePipelineFrom(ComputePipelineDescriptor descriptor) → ComputePipelineHandle

The inner device's own, recorded as createComputePipeline is. A trace names no compute pipeline's label, so a label is passed on and listed in unrecorded.

override

createComputePipelineFromAsync(ComputePipelineDescriptor descriptor) → Future<ComputePipelineHandle>

createComputePipelineFrom, recorded when it completes.

override

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.

override

createCubeTextureFromPixels({required int size, required TextureFormat format, required List<ByteData> faces, List<List<ByteData>>? mipLevels}) → TextureHandle

Uploads six square images as one cube texture.

override

createFence() → GpuFence

A timeline fence at value zero, which signalFence raises and waitFence waits for — DeviceFeature.sharedFences.

override

createPipeline(ShaderHandle vertex, ShaderHandle fragment, {VertexLayoutDescriptor? layout}) → PipelineHandle

Links two stages into something that can be bound.

override

createPipelineAsync(ShaderHandle vertex, ShaderHandle fragment, {VertexLayoutDescriptor? layout}) → Future<PipelineHandle>

The inner device's own asynchronous link, so a device that compiles off the thread still does under the recorder; the pipeline is written into the trace when the link completes, as createPipeline writes it. A refused link is not recorded: there is no pipeline to name.

override

createPipelineFrom(PipelineDescriptor descriptor) → PipelineHandle

The inner device's own, so a backend that reads a descriptor field createPipeline has no room for still sees it under the recorder; written into the trace as createPipeline writes it, with the label as a TraceSetLabel after it.

override

createPipelineFromAsync(PipelineDescriptor descriptor) → Future<PipelineHandle>

createPipelineFrom, recorded when the inner device's link completes.

override

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.

override

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.

override

createTexture(TextureDescriptor descriptor) → TextureHandle

Recorded with its whole descriptor, whatever its shape: a pool's target, an array, a volume, a chain or a storage texture.

override

createTextureFromPixels({required int width, required int height, required TextureFormat format, required ByteData pixels, List<ByteData>? mipLevels}) → TextureHandle

Creates a texture already holding pixels.

override

dispose() → void

Releases every persistent resource this device holds — the textures and geometry buffers handed out by createTexture, createTextureFromPixels, createCubeTextureFromPixels, createCubeRenderTarget and uploadGeometry.

override

exportBuffer(StorageBuffer buffer, {NativeHandleKind? kind}) → NativeHandle

exportTexture for a buffer — DeviceFeature.sharedBuffers.

override

exportFence(GpuFence fence, {NativeHandleKind? kind}) → NativeHandle

fence as a NativeHandle of kind, for another device to import.

override

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.

override

importBuffer(NativeHandle handle, BufferDescriptor descriptor) → StorageBuffer

importTexture for a buffer — DeviceFeature.sharedBuffers.

override

importFence(NativeHandle handle) → GpuFence

A fence over the one handle names, which another device made.

override

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.

override

labelOf(Object resource) → String?

The label setLabel gave resource, or null when it has none.

override

loadShaders(ByteData bytes) → Future<LoadedShaderLibrary>

Builds a library from a bundle that arrived as bytes.

override

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.

override

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.

override

overwriteGeometry(GeometryBuffer target, int offsetInBytes, ByteData bytes) → void

Writes bytes into target starting offsetInBytes into it, in place.

override

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.

override

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.

override

readBuffer(StorageBuffer buffer) → Future<ByteData>

The contents of buffer, once every pass submitted before this call has finished writing it. buffer must be hostReadable.

override

readBufferSync(StorageBuffer buffer, {int offsetInBytes = 0, int? sizeInBytes}) → ByteData

The bytes of buffer (a range of them), read back in the calling turn.

override

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.

override

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.

override

releaseFence(GpuFence fence) → void

Releases a fence createFence or importFence made.

override

releaseGeometry(GeometryBuffer geometry) → void

Releases one geometry buffer, rather than waiting for the whole device to go.

override

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.

override

releaseQuerySet(QuerySet querySet) → void

Releases one query set, as releaseStorageBuffer releases a buffer.

override

releaseRenderBundle(RenderBundle bundle) → void

Releases a bundle createRenderBundleEncoder recorded.

override

releaseSampler(SamplerDescriptor sampler) → void

Gives back what this device made to sample with sampler, if it made anything.

override

releaseStorageBuffer(StorageBuffer buffer) → void

Releases one storage buffer, as releaseGeometry releases geometry.

override

releaseTexture(TextureHandle texture) → void

Gives one back, rather than waiting for the whole device to go.

override

setLabel(Object resource, String label) → void

Passed through, and written into the trace for a texture, a geometry buffer, a pipeline or a storage buffer the trace made, so a replay gives it the same label. Any other resource is passed through and listed in unrecorded.

override

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.

override

textureFormatSupport(TextureFormat format) → TextureFormatSupport

What format can be used for here: sampled, filtered, rendered, blended, multisampled, resolved, used as depth, bound as storage.

override

toString() → String

A string representation of this object.

inherited

uploadGeometry(ByteData bytes, GeometryUsage usage) → GeometryBuffer

Uploads geometry that will outlive the frame.

override

waitFence(GpuFence fence, int value) → void

Holds the work this device submits after this call until fence reaches value. The CPU does not wait.

override

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.

override

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.

override

Operators

operator ==(Object other) → bool

The equality operator.

inherited