flutter3d_hardware library
The graphics vocabulary flutter3d is written against.
Nothing here names a graphics API. That is the entire content of this
package: it is what a backend implements and what the engine talks to, so
that neither has to know about the other. Three implement it —
flutter3d_impeller over flutter_gpu, flutter3d_webgl over WebGL2, and
flutter3d_cpu, a software rasteriser with no driver under it at all — and
the engine did not change for any of them.
Two rules hold it in shape, and both are checked rather than intended by
tool/structure.dart's "the hardware layer names no graphics API" rule,
which reads every file in this package's lib/:
- no
flutter_gpuimport anywhere in this package, ever, and no dependency on a backend in its pubspec either — the second because importing nothing and depending on everything would pass a scan of the imports alone. Held bytool/structure.dart's "the hardware layer names no graphics API" rule. It was ano_backend_test.dartin this package until the arrangement rules moved into that scanner, and the citation outlived the file by long enough to be quoted in three places; - no
dart:uiand nopackage:flutter/either, apart from the fileshardwareMayUseFlutternames. The reason is written where each exception is.
That citation used to be flutter3d_hardware/test/no_backend_test.dart,
which has not existed since the boundary tests became one scanner — so the
evidence offered for the load-bearing half of the claim led nowhere, in the
file a fourth-backend author reads first.
When a fourth backend arrives, this package does not change. A translation file appears in the new backend, and that is all.
Classes
- BackendRegistration
- What registerBackendOpener hands back, so a registration can be taken off again.
- BlendState
- How a draw is combined with what the attachment already holds.
- BufferLayout
- One buffer's worth of attributes, and how far apart its elements are.
- ColorTarget
- One colour attachment of a pass.
- CommandEncoder
- A pass somebody opened, and must therefore close.
- ComputeEncoder
- Records one compute pass: bindings, then dispatches, then submit.
- ComputePipelineHandle
- A compiled compute stage, ready to dispatch.
- DepthTarget
- The depth and stencil attachment of a pass.
- GeometryBuffer
- A range of device memory holding vertices or indices.
- GpuFrameTimings
- Every labelled pass of one frame, in the order they were submitted.
- GpuPassTiming
- One labelled pass and how long the GPU spent in it.
- GraphicsDevice
- Everything the engine needs a graphics backend for.
- InputAttribute
- One input of a vertex stage, and where in its buffer it starts.
- LayeredShaderLibrary
- Two libraries consulted in order, the first winning.
- LoadedShaderLibrary
- A library a device built from bytes it was handed, and can rebuild.
- MipChain
- Builds the levels below the base, from half size down to one by one.
- PassEncoder
- A pass that is open, into which draws are recorded.
- PassState
- A pass's rasteriser state. Unset fields are not emitted.
- PipelineHandle
- A vertex and a fragment stage, linked into something that can be bound.
- PresenterRegistration
- What registerDevicePresenter hands back, so a registration can be taken off again. See BackendRegistration for why a registry needs this.
- RenderPassDescriptor
- Everything a pass draws into.
- RenderTargetPool
- Reuses textures across frames, keyed by what makes them interchangeable.
- RenderTargetSpec
- What makes two render targets interchangeable.
- SamplerOptions
- How a texture is sampled.
- ScreenRect
- A rectangle of a render target, in pixels.
- ShaderBundle
- A loadable shader bundle: a name, the SDK it was compiled on, the stages it claims, and a compiled section per backend that needs one.
- ShaderBundleStage
- One entry point a bundle claims to hold.
- ShaderHandle
- ShaderLibrary
- The stages a compiled bundle holds, addressed by name.
- StencilState
- How the stencil test treats the draws that follow, for one face.
- StorageBuffer
- A buffer a compute stage reads and writes.
- TextureAllocator
- Makes a texture. The one thing a pool cannot do on its own.
- TextureBlockLayout
- The block footprint and byte cost of a compressed TextureFormat — blockWidth by blockHeight pixels, bytesPerBlock bytes, however many channels or bits per channel the format packs into that block.
- TextureHandle
- A texture some backend owns, described in the engine's own vocabulary.
- UniformBlock
- A block's members, by name, under the block's own name.
- VertexLayoutSpec
- Every buffer a pipeline reads vertices from, in slot order.
Enums
- BlendFactor
- One term of a blend equation.
- BlendOperation
- How the two blend terms are combined.
- CompareFunction
- The test a depth or stencil comparison performs.
- CullMode
- Which faces the rasteriser discards.
- DepthRange
- What a backend's clip space maps depth onto.
- FramebufferOrigin
- Where a render target's first row of pixels is.
- GeometryUsage
- What a buffer will be bound as.
- IndexType
- The width of one index.
- LoadAction
- What happens to an attachment's existing contents when a pass begins.
- MinMagFilter
- Filtering between texels.
- MipFilter
- Filtering between mip levels.
- PolygonMode
- Whether primitives are filled or drawn as edges.
- PrimitiveType
- How vertices are assembled into primitives.
- SamplerAddressMode
- What sampling outside the 0..1 range does.
- StencilFace
- Which side of a triangle a stencil configuration applies to.
- StencilOperation
- What happens to a stencil value once the stencil and depth tests have decided a fragment's fate.
- StorageMode
- Where an allocation lives and how it may be used.
- StoreAction
- What happens to an attachment's contents when a pass ends.
- TextureFormat
- The layout of one texel.
- TextureType
- What shape a texture is.
- VertexFormat
- The type of one vertex attribute, and how much room it takes.
- VertexStepMode
- Whether a buffer advances once per vertex or once per instance.
- WindingOrder
- Which winding counts as front-facing, wound in clip space: a transform that mirrors reverses the facing without touching the order the vertices arrived in, and every backend decides after the vertex stage rather than before it.
Extensions
- BindUniformBlockObject on PassEncoder
- PassStateApply on PassEncoder
- Applies a PassState to an encoder.
- TextureFormatCompression on TextureFormat
- Whether a TextureFormat is stored in fixed-size blocks rather than one value per texel, and — for the formats where it is — how big those blocks are.
- TextureFormatStencil on TextureFormat
- Whether a TextureFormat carries an eight-bit stencil beside its depth.
Constants
-
readbackFormats
→ const Set<
TextureFormat> -
The formats a readback hands back as they are: four bytes per pixel, one
per channel, which is what
GraphicsDevice.readbackpromises.
Functions
-
lookUpDevicePresenter(
GraphicsDevice device) → Object? -
The presenter registerDevicePresenter stored for
device's own runtime type, or null if nothing ever registered one. -
openRegisteredDevice(
{required int width, required int height, void onFallback(String message)?}) → Future< GraphicsDevice> -
Opens the first registered backend that starts, preferred backends
before the fallback, calling
onFallbackwith a message once for every refusal along the way. -
readbackRegionOf(
TextureHandle texture, ScreenRect? region) → ScreenRect -
The region a readback of
texturewill copy, or an ArgumentError saying why there is none. -
registerBackendOpener(
String name, BackendOpener open, {bool asFallback = false}) → BackendRegistration -
Registers
openas a backend a caller of openRegisteredDevice may try, namednamefor the console line printed if it refuses to start. -
registerDevicePresenter<
T extends GraphicsDevice> (Object presenter) → PresenterRegistration -
Registers
presenter— a value only the caller knows the shape of — as what shows a frame from a device of exactly typeT.
Typedefs
-
BackendOpener
= Future<
GraphicsDevice> Function({required int height, required int width}) -
Opens a GraphicsDevice at
widthbyheight, or throws. -
StageBindings
= ({Set<
String> blocks, Set<String> samplers}) - One compiled stage of a pipeline — a vertex or a fragment program.
- UniformMemberLayout = ({int byteLength, int elements, int offset, String type})
-
One member of a uniform block as the compiler lays it out —
H1.
Exceptions / Errors
- ShaderBundleRefused
- Raised when a device will not load a bundle, and says which and why.