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
- 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.
- DepthTarget
- The depth and stencil attachment of a pass.
- GeometryBuffer
- A range of device memory holding vertices or indices.
- 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.
- 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
- One compiled stage of a pipeline — a vertex or a fragment program.
- ShaderLibrary
- The stages a compiled bundle holds, addressed by name.
- StencilState
- How the stencil test treats the draws that follow, for one face.
- 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.
- 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
- 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
-
readbackRegionOf(
TextureHandle texture, ScreenRect? region) → ScreenRect -
The region a readback of
texturewill copy, or an ArgumentError saying why there is none.
Exceptions / Errors
- ShaderBundleRefused
- Raised when a device will not load a bundle, and says which and why.