backend library

What a graphics backend needs beyond the contract in flutter3d_hardware.dart: the constructors of the handles it hands out, and the check it makes before it uses one.

For the author of a GraphicsDevice, not for an application. A handle's constructor is private since 1.0, so code that draws cannot make a texture or a pipeline that no device made; a backend wraps its own objects with these, naming itself as the owner so that the handle's dispose gives the object back to it, and calls debugCheckLive before handing a handle it was given to its API. A backend that can read a buffer in the calling turn mixes in SynchronousBufferReadback from here; a caller that asks for it imports it from testing.dart, since the main library does not offer a stall. UniformScratch is the buffer a backend fills a uniform block in, kept per block size instead of made per draw.

As stable as the contract itself. This library is part of the package's snapshot and follows the same strict semver through 1.x: a constructor here gains only optional parameters within a major, and a new kind of handle arrives as a new constructor. A backend written against 1.0.0 keeps compiling against every 1.x.

Classes

UniformScratch

One reusable, zeroed buffer per block size, for a backend's bindUniformBlock.

Mixins

SynchronousBufferReadback

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

Functions

debugCheckLive(Object handle, String operation) → void

Asserts that handle — a TextureHandle, GeometryBuffer, StorageBuffer, PipelineHandle, ComputePipelineHandle, QuerySet or RenderBundle — has not been disposed, naming operation when it has.

forgetShader(Map<String, ShaderHandle?> handles, ShaderHandle handle) → void

Takes handle out of handles if it is still the one kept under its name — the release most libraries hand wrapShader. A library that frees a backend object as well does so beside it.

wrapComputePipeline({required Object backend, required ShaderHandle shader, GraphicsDevice? owner}) → ComputePipelineHandle

A ComputePipelineHandle over a backend's own backend pipeline, for a backend; see wrapStorageBuffer.

wrapFence({required Object backend, GraphicsDevice? owner}) → GpuFence

A GpuFence over a backend's own backend fence, for a backend; see wrapStorageBuffer.

wrapGeometry({required Object backend, required int offsetInBytes, required int lengthInBytes, void release(GeometryBuffer)?}) → GeometryBuffer

A GeometryBuffer over lengthInBytes bytes of a backend's own backend buffer from offsetInBytes — for a backend, from package:flutter3d_hardware/backend.dart. release is what the buffer's GeometryBuffer.dispose calls — the device's releaseGeometry for a buffer uploadGeometry made, and null for a view of something else.

wrapPipeline({required Object backend, required String name, GraphicsDevice? owner}) → PipelineHandle

A PipelineHandle over a backend's own linked backend pipeline, for a backend. owner's releasePipeline is what the handle's dispose calls.

wrapQuerySet({required Object backend, required QueryType type, required int count, GraphicsDevice? owner}) → QuerySet

A QuerySet over a backend's own backend query set, for a backend. owner's releaseQuerySet is what the handle's dispose calls.

wrapRenderBundle({required Object backend, required RenderBundleDescriptor descriptor, String? label, GraphicsDevice? owner}) → RenderBundle

A RenderBundle over a backend's own recorded backend bundle, for a backend's RenderBundleEncoder.finish, from package:flutter3d_hardware/backend.dart. owner's releaseRenderBundle is what the handle's dispose calls.

wrapShader({required Object backend, required String name, StageBindings? kept, Map<String, Map<String, UniformMemberLayout>>? layouts, void release(ShaderHandle handle)?}) → ShaderHandle

A ShaderHandle over a backend's own compiled backend stage — for a backend's ShaderLibrary, from package:flutter3d_hardware/backend.dart.

wrapStorageBuffer({required Object backend, required int lengthInBytes, bool? hostReadable, GeometryBuffer? asIndices, GeometryBuffer? asVertices, BufferUsage? usage, GraphicsDevice? owner}) → StorageBuffer

A StorageBuffer over a backend's own backend buffer — for a backend, from package:flutter3d_hardware/backend.dart. owner's releaseStorageBuffer is what the handle's dispose calls.

wrapTexture({required Object backend, required int width, required int height, required TextureFormat format, int sampleCount = 1, StorageMode storageMode = StorageMode.devicePrivate, TextureType? type, TextureDimension? dimension, int? depthOrArrayLayers, int mipLevelCount = 1, TextureUsage usage = TextureUsage.standard, TextureAllocator? owner}) → TextureHandle

A TextureHandle over a backend's own backend texture — for a backend's implementation of GraphicsDevice, from package:flutter3d_hardware/ backend.dart. Application code never makes a handle; a device hands one out. owner is the device whose releaseTexture the handle's dispose calls.