formats library

The formats a model arrives in and leaves in: the document every decoder produces, the materials it names, the readers and writers for glTF/GLB, OBJ, STL, USDZ and the engine's own .f3d and .fmat, the FBX decoder that recognises a file and refuses it with a reason, the image codecs, and the KTX2 container a compressed texture sits in.

A library of flutter3d_core, importable on its own. A modeller's document layer, the server an agent starts with dart run, a service that checks an uploaded asset and a plain dart test all read a .glb or a .ktx2; none of them resolves a Flutter SDK, and none of them has to import the renderer to do it. This was flutter3d_formats (and flutter3d_fbx) until the package boundary turned out to protect nothing a library does not.

The line is drawn at bytes. This library turns bytes into a document. The KTX2 reader stops at vkFormat, a Khronos number; mapping it to the hardware's own TextureFormat is the engine's Ktx2Texture, which wraps this library's Ktx2Container. What fetches the bytes — the asset bundle, the isolate — and what uploads the result is the renderer's.

Classes

AnimationClip: A named set of tracks that play together.
AnimationInterpolation: How a track's values are blended between keyframes.
AnimationMarker: A named moment in an animation: at seconds into a clip, or a share of a state's cycle — see where it is held.
AnimationMask: The joints one animation layer writes, by node index.
AnimationPath: Which node property a track drives.
AnimationPointer: One resolved pointer: property of the indexth object of its kind.
AnimationPointerProperty: The property a pointer drives, with the number of floats in one value.
AnimationPointerSink: Where a pointer track's sampled value goes.
AnimationPointerTarget: The kind of object a pointer lands on.
AnimationTrack: One animated property of one node.
AssetByteRange: The bytes from start up to end of a file, end not included; to the end of the file when end is null.
AssetCancel: A read called off: the signal a reader keeps and a source watches.
AssetProgress: How far a read has come: received bytes of total.
AssetRead: What a reader asks of one AssetSource.read: progress, a way to stop, and the bytes it wants.
AssetRequest: What a resolver is being asked for.
AssetSource: Where a model and its sibling files live.
AssetSources: Which AssetSource a path names, by its scheme.
BundledMaterials: The lighting models of the materials a bundle was built from, read off the sources the bundle carries — P8.
CheckedModelWriter: A writer whose files this package can also read, so a write can be checked by reading it back — what exportChecked does.
ColorConfusion: Two named colours that someone missing a cone runs together: one pair ColorVision.confusions answers.
ColorHint: A colour of channels components — three for a tint, four when the fourth is opacity.
ColorVision: A colour transform for colour vision: how the picture looks to someone with a deficiency, or the picture moved so that they tell apart what it would otherwise run together.
ColorVisionDeficiency: A kind of colour blindness: which cone is missing.
CubeLut: A parsed .cube file.
DecodedImage: A PNG decoded down to plain RGBA8 — top row first, four bytes a pixel, width * height * 4 bytes long.
DecoderRegistry: Model and material decoders, and the schemes a path names a source by: the slot a plugin that reads a format fills.
DocumentAsset: What the source file said about itself, as opposed to what it contains: the tool that wrote it, and who made it and on what terms.
DocumentDifference: One thing a round trip did not preserve.
DracoAttribute: One decoded attribute.
DracoAttributeType: Draco's GeometryAttribute::Type.
DracoMesh: What a decoded primitive carries.
EncodedImage: An image still in its source encoding (PNG, JPEG, …).
EnumHint: One of values, and nothing else.
EnumHintValue: One choice in an EnumHint: what is written into the file, and what a person reads in the list.
ExportReport: One write, read back and checked against what went in.
F3dAttributeFlags: Bit positions inside a surfaceAttributes record — one per name VertexLayout's own attributes use.
F3dDecoder: .f3d through the same ModelDecoder boundary an application's own formats come through, so every built-in reader is one: see builtInModelDecoder.
F3dDocument: A .f3d file, read as a ModelDocument.
F3dExtraSection: A section of a .f3d as its directory describes it: what F3dDocument.section reads back, and what F3dWriter writes beside the engine's own.
F3dExtrasOwner: Whose an F3dSection.extras record is.
F3dModelWriter: .f3d, the engine's own container.
F3dMorphFlags: Which optional streams a morph target record carries.
F3dRecord: Fixed record sizes, in bytes. All multiples of four.
F3dSamplingFlags: Bit positions inside a texture binding's samplingFlags.
F3dSection: Section kinds.
F3dSectionFlags: The bits of a directory entry's flags word (version 2 and up).
F3dWriter: Serializes any ModelDocument into the .f3d container.
FbxDecoder: A ModelDecoder for Autodesk's FBX — the skeleton this package's own pubspec.yaml describes: recognises the format, and says plainly that reading one is not built here yet.
GlbContainer: A parsed glTF container: the JSON document plus the optional binary chunk.
GlbModelWriter: A self-contained glTF binary.
GltfAccessorReader: Reads accessors out of the resolved glTF buffers.
GltfAsset: The decoded result of a glTF or GLB file.
GltfFilters: A glTF sampler's two filter constants, as GL numbers them: what toGltfFilters answers.
GltfLoader: Decodes glTF 2.0 and GLB into engine geometry.
GltfWriter: Serializes any ModelDocument into glTF's binary container.
HdrImage: A decoded Radiance image: three floats a pixel, row 0 at the top.
Ktx2ColorModel: The data format descriptor's colorModel, for the values that matter when vkFormat is undefined — gfx-78n.
Ktx2Container: A KTX2 file, read down to what a texture upload needs: dimensions, the raw vkFormat its mip bytes are in, and each level's bytes.
Ktx2GlobalDataField: The Basis Universal "supercompression global data" a supercompressionScheme == basisLZ file carries: the endpoint and selector codebooks, the per-block bitstream's Huffman tables, and one ImageDesc per image telling where in the level's own bytes the RGB (and optionally alpha) slice lives.
Ktx2HeaderField: Byte offsets of the header fields, relative to ktx2HeaderOffset.
Ktx2ImageDescField: Byte offsets of an ImageDesc's fields, relative to its own start; see Ktx2GlobalDataField for the layout.
Ktx2IndexField: Byte offsets of the Index section's fields, relative to ktx2IndexOffset — the pointers to the data format descriptor, the key/value data, and (for a Basis Universal file) the supercompression global data this stage now reads.
Ktx2SupercompressionScheme: supercompressionScheme values this format defines.
LightingModel: A lighting model: one pre-built fragment shader and what the engine may bind to it.
LightingModels: The lighting models a document may name in one engine: the engine's LightingModel.builtIn and every model a plugin registered — the open registry, one per engine (D23, D43).
MaterialBindings: What describeMaterial found, in the shape LightingModel takes.
MaterialBlend: How a surface is combined with what is behind it — a state block's blend — version 2.
MaterialBlockMember: One member of a uniform block of a material's own, where std140 puts it.
MaterialBlockSlot: One uniform block a material binds: MaterialParams, or a block of its own (uniform(Hair) …), with its members in declaration order.
MaterialComputeKernel: A material compute stage, lowered: the kernel and what binds it.
MaterialComputePlacement: Where MaterialComputeKernel.place put a material's kernel: the site the hardware layer chose and the kernel's stage there — since 1.0.0-rc.1.
MaterialDocument: A material as a file of its own, rather than as part of a model.
MaterialExpressionVisitor<R>: The expression language's ExpressionVisitor, with a method for each kind a material adds: its inputs, parameters and lets, and sample.
MaterialExtensions: What a surface has beyond metal-rough: the KHR_materials_* layers glTF adds on top of the core model — M1.
MaterialFileState: What a material's state block says — version 2: how it is drawn, and which light its stage leaves out.
MaterialHint: A kind with the words that go around it.
MaterialHintKind: What a control for one value should look like.
MaterialInput: One value the fragment body can read.
MaterialInputRef: One of materialInputs.
MaterialLet: let name = expr; — single assignment, so nothing here is a variable.
MaterialLocalRef: A let bound earlier in the body.
MaterialMap: The maps of a metal-rough material, in the order the layered stage keeps their transforms — C8, LayerInfo.uv_transform and kMapBaseColor and the rest in lib/surface.glsl.
MaterialOutput: out name = expr; — one of materialVertexOutputs, written by a vertex block — version 2. Each at most once, and the block's only way to say anything: it has no return.
MaterialParameter: One declared parameter: a name, a type and the value a variant that says nothing about it gets.
MaterialParamRef: A declared parameter, before a variant has said what it is.
MaterialProgram: A material read from source: its name, what it declares, and its body.
MaterialRemoveUpdate: 4: remove sheen; — name has no meaning from version on, and an instance's value for it is dropped rather than kept for a parameter that a later version may declare again with another meaning.
MaterialRenameUpdate: 2: rename ink -> inkColor; — the value of from is to's from version on.
MaterialReturn: return expr; — a vec4, rgb being the light the surface emits and a its opacity, which is what WriteSurface takes.
MaterialSample: sample(slot, uv).
MaterialScaleUpdate: 3: scale roughness 0.5; — every component of name's value is multiplied by factor from version on: a parameter whose meaning changed scale (a roughness that became perceptual, a size in another unit).
MaterialSlotTable: What a material binds beyond the engine's own: its uniform blocks and its own textures, in a fixed order (D21).
MaterialStageKind: What a source is — version 2 adds the two kinds after material.
MaterialStatement: One statement of a block: a let, a return, an out.
MaterialStatementVisitor<R>: Something that reads every kind of MaterialStatement. One abstract method per kind 1.0 knows; a kind added later defaults to visitUnknown, as MaterialExpressionVisitor explains.
MaterialSurfaceValues: What a fragment of the surface being shaded is, for evaluateMaterial.
MaterialTextureSlot: One texture slot the material samples, by the name the engine binds it under.
MaterialTextureSlotEntry: One texture of a material's own, by what the source calls it and what it is bound under. A material that names none for it is drawn with a white texel in its place, as an engine texture slot nobody filled is.
MaterialUpdate: One step of a material's updates block — language version 3: how a parameter value written for a version before version changes on the way to it.
MaterialVariant: One compiled entry point: a program with its parameters pinned.
ModelCamera: A camera decoded from glTF's own cameras, or held for a writer to encode into it — fmt-28's own row, the other half beside ModelLight.
ModelCameraProjection: How a decoded camera projects — glTF's own two, perspective and orthographic, and no others: the core specification defines exactly these two camera.type values.
ModelDecodeContext: What ModelDecoder.decode is handed.
ModelDecoder: A decoder for a format the engine does not ship.
ModelDecoders: The DecoderRegistry the formats fill: the model decoders and the asset sources plugins bring.
ModelDocument: A decoded model, whatever format it came from.
ModelFormat: Which decoder to use.
ModelImpostor: A node baked into two octahedral atlases — C4.
ModelLight: A punctual light, decoded from KHR_lights_punctual or held for a writer to encode into it — fmt-28's own row.
ModelLoadRequest: Everything a decode needs, in one sendable object.
ModelLod: One level of detail a node offers in place of its own full surface list — pro-eng-06's own row.
ModelNode: A node in a decoded model's hierarchy.
ModelOrthographicCamera: camera.orthographic — a view volume's own half-extents, both planes required.
ModelPerspectiveCamera: camera.perspective — a field of view and a near plane, an aspect ratio and a far plane that both may be absent.
ModelProbe: What ModelDecoder.handles is asked about: a file, by name and bytes.
ModelSkin: A skeleton: which nodes are joints, and how each undoes the bind pose.
ModelSplat: A cloud of Gaussian splats a node of a decoded model carries — C1.
ModelSurface: One drawable piece of a decoded model.
ModelWrite: What one write produced.
ModelWriteContext: What ModelWriter.write is handed.
ModelWriter: A format a ModelDocument can be written as.
MtlMaterial: A material exactly as written in a .mtl file.
ObjDocument: The decoded contents of an OBJ file.
ObjLoader: Decodes Wavefront OBJ, optionally with its .mtl material libraries.
ObjModelWriter: Wavefront OBJ, with its .mtl beside it when the document names a material.
ObjNormals: How to fill in normals that the file does not provide.
ObjWriter: Encodes any ModelDocument as Wavefront OBJ, with its .mtl beside it.
OcclusionAffects: Which light a material's occlusion map darkens under the engine's own lighting models: both by default, or the direct or the indirect half alone.
PackedMapSource: One lane of a packed map: the texture it is read from and the channel of that texture's own image it takes. See MaterialExtensions.coatMapSources.
PagedSplatOctree: A splat tree whose pages arrive on request.
PipelineAnchor: An anchor a pipeline adds: a plugin's own, standing right after another.
PipelineDocument: A frame's pipeline, written down (D44): what a renderer describes of its own frame (Renderer.describePipeline), what an editor edits, what a .f3dplugin's pipeline: section brings, and what RendererSteps.fromDocument applies.
PipelineNode: One node of a pipeline: where it stands, what it touches, and — for a node of a plugin's own — which kind makes it.
PixelExtent: A width and a height in whole pixels: what a ResourceSize resolves to, and the size of an image read from its header.
PlainModelDocument: A ModelDocument assembled by hand, from plain lists.
RangeHint: A number with two ends and, when it is not continuous, an increment.
Rgba8Image: A decoded source image: tightly packed RGBA8, row-major, top row first — exactly what ui.Image.toByteData(format: rawStraightRgba) hands the engine's own texture upload path, and what every encoder in encode/ takes in.
Rgba8Texel: One pixel of eight bits a channel: what a 4x4 block encoder takes sixteen of, and what decodeUniversalBlock answers sixteen of.
RgbTriple: Three channels of a colour, red, green and blue, as a colour table or a colour transform reads and answers them. Whether they are linear or sRGB encoded is the answering member's to say.
SplatAxes: Which axes a cloud read by parseSplatSpz comes back in.
SplatCloud: A fitted cloud, in the units the file stored.
SplatColorSpace: The colour space a splat's colours were fitted in, as KHR_gaussian_splatting's colorSpace names it.
SplatOctree: A cloud as a tree of levels of detail. Node 0 is the root.
SplatOctreeNode: One box of the tree.
StlLoader: Decodes STL, binary or ASCII.
StlModelWriter: STL, binary or ASCII.
StlNormals: How a facet's normal is chosen.
StlWriter: Encodes any ModelDocument as STL, binary or ASCII — fmt-20's own row.
SurfaceAlphaMode: How a surface treats the alpha channel.
SurfaceMaterial: Format-neutral description of how a surface looks.
SymmetricEigen: The eigenvalues and eigenvectors of a symmetric 3×3 matrix: what symmetricEigen3 answers.
TextureBinding: A reference from a material to one of the document's images.
TextureCodec: An image format of a plugin's own — DDS, TGA, a game's packed format — read into RGBA8 pixels the engine uploads like a PNG's (D22b).
TextureCodecs: The image formats plugins brought, asked in the order they were registered — the application's first, then each plugin's.
TextureDecodeContext: What a TextureCodec is handed for one encoded image: one object that can gain members, rather than a list of parameters that grows.
TextureHint: A path to an image, and what a file picker should offer.
TextureSampling: Filtering and wrapping requested for a texture.
TextureTransform: KHR_texture_transform's three fields — see TextureBinding.transform.
UniversalBlockFormat: What universalBlockFormat says of a universal-block file: whether it hasAlpha. An open class rather than a bool, so it can say more later.
UniversalTarget: What a universal level can be turned into at load.
UsdzModelWriter: .usdz — geometry only, the spike UsdzWriter describes. Not a CheckedModelWriter: nothing here reads a .usdz.
UsdzWriter: Encodes a ModelDocument as .usdz — fmt-27's own row, and a spike rather than the feature-complete writer every other format here has: geometry only, no materials, no hierarchy past one Mesh prim per surface. What decides whether it grows past that is stated in the plan as a question — is there demand — and a spike is exactly the size of thing that can answer it without committing to the rest up front.
UsdzZip: A ZIP archive holding entries uncompressed, each one's data padded to start at a 64-byte offset — the one structural rule .usdz adds on top of an ordinary ZIP.
VertexStageVariant: A variant of a material's own vertex stage, for geometry that reads more than the standard vertex (D22b).
VkFormat: The subset of Vulkan's VkFormat this loader maps to a TextureFormat.
WrittenFile: One file a write produced.

Enums

GltfAccessorType: glTF accessor type values.
GltfComponentType: glTF componentType values.
GltfPrimitiveMode: glTF primitive topology.

Constants

builtInModelExtensions → const Map<String, ModelFormat>: Every file suffix a built-in reader answers to, and which reader.
builtInModelWriters → const List<ModelWriter>: Every writer this package ships, in the order a menu would offer them.
f3dFormat → const FormatSpec: .f3d in the format registry: its id, suffix, magic, the version this build reads up to, and the fixture minted at each version.
f3dHeaderBytes → const int: The header's size in bytes: magic, version, section count and entry size, a u32 each. The directory starts right after it.
f3dMagic → const int: F3D\n, chosen so a file opened in a text editor announces itself on line one and the trailing newline stops the magic from running into what follows.
f3dmatFormat → const FormatSpec: .f3dmat in the format registry: text, versioned by an optional f3dmat <N> line, so it has no JSON envelope and no fixed magic.
f3dMaxSectionEntryBytes → const int: The largest directory entry a reader accepts, in bytes. An entry grows at its tail as a record does, and 256 bytes is twelve times today's: a header claiming more is a broken or hostile file, refused before the directory's size is multiplied out.
f3dSectionEntryBytes → const int: A version-1 directory entry: kind, offset, length, count.
f3dSectionEntryBytesV2 → const int: A version-2 directory entry: a version-1 entry and its flags word. The header's fourth word says the size a file uses, so a later version may grow the entry the same way a record grows.
f3dsplatFormat → const FormatSpec: .f3dsplat in the format registry.
f3dVendorKindStart → const int: The first section kind that is never the engine's. Kinds from here up are free for tools and plugins; the engine skips them unless asked to read one.
f3dVersion → const int: The newest version this build reads: bumped when an existing record changes meaning. Adding a section does not need it — an old reader skips what it does not recognise.
f3dWideMagic → const int: The magic of the wide variant, F3DW: u64 offsets for files past 4 GiB. Reserved; see "How the format grows" in this library's documentation.
firstMaterialVersion → const int: The version of a material that says none (material Hatch { … } rather than material Hatch version 3 { … }), and of an instance that predates material versions. A material's versions count from it.
fmatFormat → const FormatSpec: .fmat in the format registry.
fmatVersion → const int: The version this reader writes, and the newest it reads.
ktx2HeaderBytes → const int: The header's size in bytes: nine u32 fields, see Ktx2HeaderField.
ktx2HeaderOffset → const int: Where the header starts, in bytes from the start of the file: right after the twelve-byte identifier.
ktx2Identifier → const List<int>: AB 4B 54 58 20 32 30 BB 0D 0A 1A 0A — the twelve-byte identifier every KTX2 file starts with.
ktx2IndexBytes → const int: The index's size in bytes: see Ktx2IndexField.
ktx2IndexOffset → const int: Where the index starts, in bytes from the start of the file: 48.
ktx2LevelIndexEntryBytes → const int: The size of one level index entry in bytes: u64 byte offset, u64 byte length and u64 uncompressed byte length.
ktx2LevelIndexOffset → const int: Where the level index starts, in bytes from the start of the file: 80.
materialAmbientInputs → const List<MaterialInput>: What an ambient block reads on top of materialInputs — version 2: the level's baked light at this fragment, which the engine's own ambient adds to the hemisphere.
materialBuiltins → const List<ExpressionBuiltin>: The builtins a material may call, the sixteen every version so far has: dot, length, normalize, mix, clamp, smoothstep, step, pow, min, max, abs, sqrt, floor, fract, sin and cos.
materialBuiltinVersions → const Map<String, int>: The language version each of materialBuiltins arrived in, by name: all sixteen are version 1's. A builtin a later version adds is written here with that version, and a source of an older one neither calls it nor has the name taken from a let or a parameter of its own.
materialCompositeInputs → const List<MaterialInput>: What a composite block reads on top of materialInputs — version 2: the lights gathered through the light block, and the light the ambient block (or the engine's own ambient) gave, neither yet under the occlusion.
materialComputeInputs → const List<MaterialInput>: What a compute stage's kernel reads — version 2: the texel of its target this invocation writes, the target's size in texels, and the texel's centre as nought to one.
materialComputeParameters → const String: The f32 buffer a lowered kernel reads its uniforms from.
materialComputeTarget → const String: The binding a lowered kernel writes its texels to.
materialDepthCompares → const List<String>: The words of materialDepthCompareWire, in its order.
materialDepthCompareWire → const Map<String, CompareFunction>: The depth tests a state block's depthCompare names, and the CompareFunction each becomes.
materialDepthLayerLimit → const int: The furthest a state block's depthLayer reaches either way.
materialFullscreenInputs → const List<MaterialInput>: What a fullscreen stage's fragment body reads — version 2: where on the screen it is, nought to one from the top left, and the depth the scene left there along the view axis, in metres, a million where nothing was drawn. The picture itself is the texture scene, read with sample(scene, uv).
materialInputs → const List<MaterialInput>: Every input, and the single list of them.
materialLanguageFirstVersion → const int: The material language version of a file with no f3dmat line: every file written before the line existed.
materialLanguageStagesVersion → const int: The material language version that adds the state, vertex, ambient and composite blocks, the fullscreen and compute kinds, the scene inputs, and a material's own blocks and textures.
materialLanguageStandardVersion → const int: The material language version that opens the engine's standard model: lighting standard;, the surface block and the standard input.
materialLanguageUpdatesVersion → const int: The material language version that gives a material a version of its own and an updates block.
materialLanguageVariantsVersion → const int: The version from which a vertex block is drawn on instanced and lightmapped draws too, as <name>VertexInstanced and <name>VertexLightmapped, and reads instance. An older source keeps the engine's stages for those draws, as it always had.
materialLanguageVersion → const int: The newest material language version this build reads. A file with no f3dmat line is version 1.
materialLightInputs → const List<MaterialInput>: What the light block reads about the one light it is shading for, on top of materialInputs — P8, the lighting hook.
materialLitInput → const MaterialInput: The surface lit as the engine lights it, through the material's own light block — P8. Read in the fragment body of a material that has one.
materialNothingBehind → const String: What sceneDepth reads where nothing was drawn behind — the sky — in metres: far enough that every soft edge and every fog reads it as nothing there, and well inside a half float.
materialOwnTexturePrefix → const String: What the binding of a texture of a material's own starts with: texture fur; is bound as material_fur.
materialParametersBlock → const String: The block every uniform is a member of unless it names another, and the one RenderMaterial.parameterBlock names by default.
materialReservedBlockNames → const Set<String>: Every uniform block one of the engine's own shaders declared at 1.0.0, which a material's block cannot be named: frozen, not read off the live table, so a block the engine adds in a minor takes no name from a material that built before. A block the engine adds after 1.0.0 is named in isEngineBlockName's reserved shape instead, which a material's block was never allowed (material_language_versions_test.dart holds the engine to that).
materialSceneInputs → const List<MaterialInput>: What a fragment body of version 2 reads of the scene behind it — item 9 of tasks/1.0-scope-additions.md, for soft edges, fog and water.
materialStandardLighting → const String: The lighting a material can name with lighting <name>; — version 4: standard, the engine's metal-rough model, into which the material's surface, light and lighttype declarations inject. A material that names none lights itself, as every material before version 4 did.
materialStandardLightInput → const MaterialInput: What a light block reads beside materialInputs and materialLightInputs in a material lit by the engine's standard model (lighting standard;) — version 4: standard, the standard model's own answer to this light, which the block returns as it is or changes. The engine multiplies what it returns by the light's radiance, n·l and shadow, as it does the standard model's.
materialSurfaceOutputs → const List<MaterialInput>: What a surface block may write in a material lit by the standard model — version 4, with out name = value;: the surface the model lights, after the engine has read it and applied its maps, before any light. A field the block does not write keeps the engine's value; a written normal is made unit length and the view's cosine taken again.
materialSyntax → const ExpressionSyntax: The tokens the material language reads: the expression language's arithmetic, its own { } = ;, and no units, exponents or comparisons, which no version of it has had.
materialTextureBindings → const List<String>: What the engine binds, and therefore the only names a texture declaration with = may point at.
materialVertexInputs → const List<MaterialInput>: What a vertex block reads — version 2.
materialVertexOutputs → const List<MaterialInput>: What a vertex block may write, with out name = value; — version 2.
modelFormats → const List<FormatSpec>: The engine's own model and material formats, for a FormatRegistry: .f3d, .fmat, .f3dmat and .f3dsplat.
pipelineFormat → const FormatSpec: f3d.pipeline in the format registry.
pipelineVersion → const int: The f3d.pipeline version this build writes and the newest it reads.
splatOctreeExtension → const String: The file suffix flutter3d_build convert writes a splat tree to.
splatOctreeHeaderBytes → const int: Bytes before the node table.
splatOctreeNodeBytes → const int: Bytes a node takes in the table.
splatOctreeVersion → const int: The tree file's format version.
splatPageBytesPerSplat → const int: Bytes a splat takes in a page: centre, colour, scale, rotation as float32.
splatShC0 → const double: The spherical-harmonic normalisation the 3D Gaussian Splatting papers and every exporter after them use for the zeroth band.
spzLatestVersion → const int: The highest format version this reads: version 4, zstd streams.
universalBlockKey → const String: The KTX2 key/value key that says a file's blocks are these.
universalBlockRgb → const String: The key's value for a texture whose alpha is opaque throughout.
universalBlockRgba → const String: The key's value for a texture that carries alpha.

Properties

builtInMaterialHints → Map<String, MaterialHint>: Hints for the fields every material has, held here rather than written into every file.
final

Functions

applyBinary(String op, List<double> a, List<double> b) → List<double>: + - * / on two values, with GLSL's broadcasting: the expression language's applyExpressionOperator.
broadcastArguments(List<List<double>> arguments, ExpressionBuiltin builtin) → List<List<double>>: Spreads a one-component argument across the widest one, for the builtins that take a float beside a vector: the expression language's broadcastExpressionArguments.
buildMipChain(Rgba8Image base, {bool srgb = false, bool isNormalMap = false, double? alphaTestThreshold}) → List<Rgba8Image>: Builds a full mip chain from base down to a 1×1 level, each level a proper Kaiser-windowed resample of the one above rather than a box average — ap-08 in doc/asset-pipeline-plan.md.
buildSplatOctree(SplatCloud cloud, {int leafCapacity = 512, int grid = 8}) → SplatOctree: Builds the tree over cloud.
builtInModelDecoder(ModelFormat format, ModelLoadRequest request) → ModelDecoder: The decoder this package ships for format, configured from request.
canDecodeFileName(String fileName, {List<ModelDecoder> decoders = const <ModelDecoder>[]}) → bool: Whether a file called fileName is one decodeModelBytes would read on its name alone — a built-in suffix, or one of decoders claiming it.
checkMaterialSurface(Map<String, List<double>> inputs) → void: Throws ArgumentError unless inputs answers every name in materialInputs, with the right number of components.
compareModelDocuments(ModelDocument source, ModelDocument readBack, {double tolerance = 0.0, bool allowVertexReorder = false}) → List<DocumentDifference>: What readBack lost or changed against source. Empty means the round trip held.
composeMaterialLit(MaterialProgram program, MaterialSurfaceValues surface, {required List<double> direct, required List<double> lightmap}) → List<double>: lit for one fragment of a lit program, as the emitted main adds it up — version 2's hooks and switches included, so a backend that evaluates has one answer to call rather than a second transcription.
decodeDataUri(String uri) → Uint8List: Decodes a data: URI payload.
decodeDraco(Uint8List bytes) → DracoMesh: Decodes bytes, the contents of the buffer view a primitive's KHR_draco_mesh_compression extension points at.
decodeImagePure(Uint8List encoded) → Future<Rgba8Image>: Decodes encoded into straight RGBA8 pixels with no Flutter SDK and no dart:ui behind it — mcp-04n: the headless half of flutter3d_core's own ImageDecoder typedef, which this function's signature already matches structurally without needing to import it (flutter3d_formats sits below flutter3d_core in the dependency order, so the import would run backwards).
decodeJpeg(Uint8List bytes) → DecodedImage: bytes decoded.
decodeModel(ModelLoadRequest request, {AssetRead read = AssetRead.whole}) → Future<ModelDocument>: Decodes a model on the calling isolate.
decodeModelBytes(ModelLoadRequest request, Uint8List bytes, AssetUriResolver resolveUri) → Future<ModelDocument>: Decodes already-read bytes with an explicit resolver.
decodePng(Uint8List bytes) → DecodedImage: bytes decoded.
decodeSplatPage(Uint8List bytes, int count) → SplatCloud: One node's page, count splats, as a cloud.
decodeUniversalBlock(Uint8List blocks, int index) → List<Rgba8Texel>: The sixteen texels of block index, row-major — what the legs with no structural shortcut start from, and what a test compares against.
describeMaterial(MaterialProgram program) → MaterialBindings: What the engine may bind to program's compiled shader.
emitMaterialDebugStages(MaterialProgram program) → Map<String, String>: The debug twin of program's fragment stage, by the name the renderer looks it up under — <name>Debug — with its GLSL: the stage with the debug views compiled in, drawn in place of the plain one only while a view is on. Empty for a program that shows no views, which is every one not lit by the standard model. program is specialised already, as the build hands it over.
emitMaterialFragment(MaterialProgram program, {bool debugViews = false}) → String: The .frag source for program, which should already be specialised.
emitMaterialVertex(MaterialProgram program, {bool skinned = false, bool instanced = false, bool lightmapped = false}) → String: The vertex stage of program's vertex block — version 2 — or, with skinned, its skinned half: mesh.vert and mesh_skinned.vert with the block between the engine's answer and the varyings.
emitMaterialVertexStages(MaterialProgram program) → Map<String, String>: Every vertex stage program's vertex block becomes, by the name each is built and looked up under, with its GLSL: <name>Vertex, its skinned half and, from version 3, its instanced and lightmapped halves (materialVertexVariantStages). Empty for a program without the block. program is specialised already, as the build hands it over.
encodeAstc4x4(Rgba8Image image) → Uint8List: Encodes image as ASTC 4×4 LDR (vkFormat.astc4x4UNormBlock): one 16-byte block per 4×4 tile — mat-30's own gap on top of fmt-22's BC1/BC3/ETC2 trio, doc/asset-pipeline-plan.md's ap-07.
encodeAstc4x4Block(List<Rgba8Texel> pixels) → Uint8List: Encodes one 4×4 block (row-major, alpha ignored) as sixteen bytes: the 11-bit _kBlockMode, a 2-bit partition count of zero (one partition), a 4-bit CEM of _kCemLdrRgbDirect, six _kColorBits-wide endpoint channel values, then sixteen _kWeightBits-wide per-texel weights packed downward from bit 127 — 17 + 48 from the bottom and 48 from the top, leaving the fifteen bits between them zero.
encodeBc1(Rgba8Image image) → Uint8List: Encodes image as BC1 (vkFormat.bc1RgbaUNormBlock): one 8-byte block per 4×4 tile, two RGB565 endpoints and sixteen 2-bit palette picks.
encodeBc3(Rgba8Image image) → Uint8List: Encodes image as BC3 (vkFormat.bc3UNormBlock): sixteen bytes per 4×4 tile — an eight-byte alpha block, then the same eight-byte colour block encodeBc1Block writes, in that order.
encodeCompressedPng(int width, int height, Uint8List rgba) → Uint8List: rgba (width × height, four bytes a pixel, top row first — the same shape DecodedImage.rgba reads back) written as an 8-bit RGBA PNG.
encodeEtc2Rgb8(Rgba8Image image) → Uint8List: Encodes image as ETC2 RGB8 (vkFormat.etc2R8g8b8UNormBlock): one 8-byte block per 4×4 tile.
encodeEtc2Rgb8Block(List<Rgba8Texel> pixels) → Uint8List: Encodes one 4×4 block (row-major, alpha ignored) as the eight bytes of an ETC1-compatible ETC2 RGB8 block — flip = 0, top and bottom 4×2 halves each with their own base colour and modifier table.
encodeSplatOctree(SplatOctree tree) → Uint8List: tree as a file: header, node table, then every page breadth first. Every node must be loaded.
encodeUniversalBlock(List<Rgba8Texel> pixels) → Uint8List: Encodes one 4×4 block (sixteen (r, g, b, a) tuples, row-major).
encodeUniversalBlocks(Rgba8Image image) → Uint8List: Encodes image as universal blocks, one per 4×4 tile.
evaluateMaterial(MaterialProgram program, MaterialSurfaceValues surface) → List<double>: The colour program returns for one fragment: rgb the light the surface emits, a its opacity.
evaluateMaterialAmbient(MaterialProgram program, MaterialSurfaceValues surface) → List<double>: What program's ambient block gives — version 2: three numbers, the light the surface takes from its surroundings, which the caller treats as ShadeAmbient is treated. surface's inputs carry materialAmbientInputs as well. Throws a StateError for a program with no block.
evaluateMaterialComposite(MaterialProgram program, MaterialSurfaceValues surface) → List<double>: What program's composite block gives — version 2: lit. surface's inputs carry materialCompositeInputs as well. Throws a StateError for a program with no block.
evaluateMaterialLight(MaterialProgram program, MaterialSurfaceValues surface) → List<double>: How the surface answers one light, from program's light block — P8: three numbers, which the caller multiplies by the light's radiance, n·l and shadow, as AccumulateLights does with ShadeLight.
evaluateMaterialSurface(MaterialProgram program, MaterialSurfaceValues surface) → Map<String, List<double>>: What program's surface block writes for one fragment — version 4, a material lit by the standard model: each output it names, by name, computed against the surface as read. An output the block does not write is absent, and the caller keeps the surface's own; a written normal is the caller's to make unit length, as the emitted stage does. Throws a StateError for a program with no block.
evaluateMaterialVertex(MaterialProgram program, MaterialSurfaceValues vertex) → Map<String, List<double>>: What program's vertex block writes for one vertex — version 2: each output it names, by name. vertex carries materialVertexInputs; an output the block does not write is absent, and the caller keeps its own. Throws a StateError for a program with no block.
exportChecked(ModelDocument document, CheckedModelWriter writer, {String name = 'model'}) → Future<ExportReport>: Writes document through writer, reads the files back through the same writer and compares at CheckedModelWriter.tolerance.
exportToF3d(ModelDocument document, {String name = 'model'}) → ExportReport: Writes document to this engine's own .f3d container, reads the result back and compares. Synchronous, unlike the other three: .f3d is read as a view over its own bytes rather than decoded, and nothing in that path is asynchronous either.
exportToGlb(ModelDocument document, {String name = 'model'}) → Future<ExportReport>: Writes document as glTF, reads the result back and compares — a binary format, so the round trip is held to a tolerance of 0.0.
exportToObj(ModelDocument document, {String name = 'model'}) → Future<ExportReport>: Writes document as OBJ (with its .mtl beside it, when the document names a material), reads the result back and compares — held to ObjWriter.decimals' own precision rather than 0.0, since a decimal text format rounds on the way out by design.
exportToStl(ModelDocument document, {String name = 'model'}) → Future<ExportReport>: Writes document as binary STL, reads the result back and compares.
hasConflictingTextureTransforms(SurfaceMaterial material) → bool: Whether the textures of material name transforms that cannot all be honoured by one set of coordinates — the case a caller warns about.
hdrSizeOf(Uint8List bytes) → PixelExtent?: How big bytes says it is, without decoding a pixel of it — ux-49.
inflate(Uint8List data) → Uint8List?: A raw DEFLATE stream, with no zlib wrapper around it — zlibInflate's own worker, public because a caller that already has the wrapper stripped (or none at all, as in a raw .deflate stream) should not have to fake one back on to call this.
isBasisUniversalKtx2(Uint8List bytes) → bool: True when bytes is a KTX2 file whose vkFormat is undefined — a Basis Universal file, whose pixels are a transcode rather than a copy.
isBinaryStl(Uint8List bytes) → bool: True when bytes is a binary STL file.
isEngineBlockName(String name) → bool: Whether name is one of the engine's block names, or in the shape the engine keeps for the blocks it adds later: F3d… or …Info.
isF3dFile(Uint8List bytes) → bool: True when bytes begins with the .f3d magic.
isFmat(Uint8List bytes) → bool: Whether bytes look like a .fmat.
isKtx2BasisUniversal(Uint8List bytes) → bool: Whether bytes is a KTX2 file Basis Universal produced — fmt-21's own row, the check that decides whether a texture can travel as KHR_texture_basisu or has to be embedded the ordinary way instead.
isKtx2File(Uint8List bytes) → bool: True when bytes begins with the KTX2 identifier.
isPng(Uint8List bytes) → bool: Whether bytes start with the PNG signature.
linearToSrgb(double c) → double: One channel, linear to sRGB-encoded — IEC 61966-2-1's piecewise curve.
looksLikeAsciiStl(Uint8List bytes) → bool: True when bytes looks like the text dialect: solid (any case), once leading whitespace is skipped.
looksLikeSpz(Uint8List bytes) → bool: Whether bytes starts the way an SPZ does: the version 4 magic in the clear, or a gzip stream, which is what versions 1 to 3 are.
lowerMaterialCompute(MaterialProgram program) → MaterialComputeKernel: program, a MaterialStageKind.compute stage, written in the kernel language: see the library's documentation for what that decides.
materialDebugStageName(MaterialProgram program) → String?: The name of program's debug twin, <name>Debug — see emitMaterialDebugStages — or null for a program that has none.
materialExtensionsFromJson(Map<String, Object?> extensions, {required TextureBinding? texture(Object? info), IssueSink? onIssue, String where = 'a material'}) → MaterialExtensions?: The layers extensions names — a glTF material's own extensions object, or the same shape in a .fmat or a .f3d — or null when it names none of MaterialExtensions.gltfNames.
materialExtensionsToJson(MaterialExtensions e, {required Object? texture(TextureBinding binding)}) → Map<String, Object?>: The inverse of materialExtensionsFromJson: each extension whose values differ from its defaults, or that carries a texture, keyed by its glTF name. texture writes one binding in the caller's format.
materialLightTypeInput(String name) → MaterialInput: What a light block's lighttype tube = acme.tube; declaration reads as tube: one while the block shades a light of that type, nought otherwise — version 3. The code is the renderer's, handed out in registration order, so the material binds it by the type's name (materialLightTypeMember) and the renderer fills the member.
materialLightTypeMember(String name) → String: The MaterialParams member a lighttype declaration named name holds its type's code in: what LightingModel.lightTypeMembers maps to the type's name, and the renderer fills from LightTypes.codeNamed.
materialStageIn(String namespace, String material) → String?: The stage a material called material compiles to when a plugin of namespace ships it: <namespace>__<material> for the bare name a .f3dmat writes (material Hair in acme_hair is acme_hair__Hair), and material as it is when it already names that namespace. Null for a name in another namespace (other__Ink), which no plugin compiles.
materialVertexVariants(MaterialProgram program) → Set<VertexStageVariant>: materialVertexVariantStages's variants.
materialVertexVariantStages(MaterialProgram program) → Map<VertexStageVariant, String>: The halves of program's own vertex stage besides the plain and the skinned one: the instanced and the lightmapped, for a version 3 source with a vertex block, by the name each is built under.
mergeSplats(List<SplatCloud> parts, {required Vector3 center, required double halfExtent, required int grid}) → SplatCloud: The splats of parts merged into at most grid³, one per occupied cell of a grid³ lattice over the cube of halfExtent-size halfExtent about center.
modelWriterNamed(String asked, {List<ModelWriter> writers = builtInModelWriters}) → ModelWriter?: The writer in writers that asked names — by ModelWriter.name first, then by ModelWriter.suffix, with or without its dot, ignoring case — or null when none does.
parseMaterial(String source) → MaterialProgram: Reads source as one material.
parseMtl(String text, {IssueSink? onIssue}) → Map<String, MtlMaterial>: Parses a .mtl library.
parseSplatOctree(Uint8List bytes) → SplatOctree: A whole tree file read at once, every page attached.
parseSplatOctreeIndex(Uint8List bytes) → SplatOctree: The tree's nodes out of the header and table, every page still to load.
parseSplatPly(Uint8List bytes, {bool keepHigherBands = false, SplatColorSpace colorSpace = SplatColorSpace.srgb}) → SplatCloud: The cloud in bytes, or a thrown SplatPlyException saying why not.
parseSplatSpz(Uint8List bytes, {SplatAxes axes = SplatAxes.rightUpBack, bool keepHigherBands = true, SplatColorSpace colorSpace = SplatColorSpace.srgb}) → SplatCloud: The cloud in bytes, or a thrown SplatSpzException saying why not.
readFmat(Uint8List bytes, {String name = '', LightingModels? lightingModels}) → MaterialDocument: Reads a .fmat material.
readHdr(Uint8List bytes) → HdrImage: bytes as an HDR image.
recognizedModelFormat(String fileName) → ModelFormat?: The format fileName's own extension names, or null when it names none of the four this package reads.
renameMaterialSource(String source, String name) → String: source, a .f3dmat, with its first block — the material, the full-screen stage or the compute kernel the file is — named name, and every other byte as it was written: what a build or a run time compiles, and carries in the bundle's material section, once the stage is in its plugin's namespace (materialStageIn), so whatever reads the source back reads the stage's own name.
safeRelativeAssetPath(String uri) → String: A reference inside a model is always relative to the model. An absolute path or a .. segment means the file is reaching outside its directory, which is worth refusing rather than resolving.
sharedTextureTransform(SurfaceMaterial material) → TextureTransform?: The one transform every texture of material asks for, or null.
sniffImageMimeType(Uint8List bytes) → String?: Guesses an image's MIME type from its leading bytes.
sniffModelFormat(Uint8List bytes) → ModelFormat: Guesses a format from the leading bytes.
specializeMaterial(MaterialProgram program, MaterialVariant variant) → MaterialProgram: program with variant's parameter values folded in, ready to emit or to evaluate.
splatBytesReader(Uint8List bytes) → SplatRangeReader: A SplatRangeReader over a file already in memory — for tests, and for a caller that has the whole file but wants the paged path anyway.
splatChannel(double coefficient) → double: A zeroth-band spherical-harmonic coefficient as a colour channel, in the space it was fitted in and unclamped — the raw sum the file's numbers make.
splatColor(double coefficient, SplatColorSpace space) → double: A zeroth-band coefficient as the linear channel the engine blends, for a cloud fitted in space.
splatOctreeIndexBytes(Uint8List header) → int: How many bytes of the file parseSplatOctreeIndex needs, given its first splatOctreeHeaderBytes.
splatOpacity(double logit) → double: logit through the logistic function, which is how a file stores opacity.
srgbToLinear(double c) → double: One channel, sRGB-encoded to linear.
surfaceMaterialFromJson(Map<String, Object?> json, {LightingModels? lightingModels, String? name, IssueSink? onIssue, TextureBinding? baseColorTexture, TextureBinding? normalTexture, TextureBinding? metallicRoughnessTexture, TextureBinding? occlusionTexture, TextureBinding? emissiveTexture, MaterialExtensions? extensions}) → SurfaceMaterial: The inverse of surfaceMaterialToJson: a SurfaceMaterial built from json's own scalar and colour fields, with name as the fallback for a document that names itself no other way and the five texture bindings supplied by the caller — already resolved against whatever document json came from, the same division surfaceMaterialToJson draws.
surfaceMaterialToJson(SurfaceMaterial surface, {LightingModels? lightingModels}) → Map<String, Object?>: surface's own scalar and colour fields, keyed the way writeFmat nests them into a .fmat — everything but its texture slots, which surfaceMaterialFromJson takes as separate, already-resolved arguments rather than reading here.
symmetricEigen3(Float64List m) → SymmetricEigen: The eigenvalues and unit eigenvectors of the symmetric 3×3 m (row major), by cyclic Jacobi rotations.
toGltfFilters(TextureSampling sampling) → GltfFilters: The magFilter and minFilter GL constant pair a glTF writer should emit for sampling — the exact inverse of _decodeSampler's filter half, so a document decoded from glTF and written back out names the same constant it arrived with, mipmap variant included.
transcodeUniversal(Uint8List blocks, UniversalTarget target, {required int width, required int height}) → Uint8List: blocks as target, ready to upload.
universalBlockFormat(Uint8List bytes) → UniversalBlockFormat?: Whether bytes is a universal-block file and whether it carries alpha, or null when it is an ordinary KTX2.
validateGltfExport(Uint8List bytes, {AssetUriResolver? resolveUri, double tolerance = 1e-5}) → Future<List<String>>: Reads bytes as glTF/GLB and checks every accessor's declared min/max against the values it actually holds.
withTextureTransform(MeshData mesh, TextureTransform transform) → MeshData: mesh with transform applied to its texture coordinates.
writeFmat(MaterialDocument document, {LightingModels? lightingModels}) → String: Writes document back out, so a tool that edits a material can save it.
writeKtx2({required int vkFormat, required int pixelWidth, required int pixelHeight, required List<Uint8List> levels, Map<String, String> keyValues = const <String, String>{}}) → Uint8List: Assembles a KTX2 file from already-encoded mip levels — the writer half of ktx2_loader.dart, and the reason ap-07 in doc/asset-pipeline-plan.md lives beside it rather than in flutter3d_build: both read and write the same container, in the same package, with no Flutter SDK behind either.
writeKtx2WithMips(Rgba8Image base, {bool srgb = false, bool isNormalMap = false, double? alphaTestThreshold}) → Uint8List: ap-08's own glue: builds the mip chain over base and writes every level through writeKtx2 in one call, so a caller that wants a ready-to-load file does not have to know that a chain and a writer are two different pieces.
zlibCompress(Uint8List data) → Uint8List: data compressed as a complete zlib (RFC 1950) stream — the two-byte header, one final DEFLATE block, and the trailing Adler-32 _adler32 computes over the uncompressed bytes, which every real decoder checks even though this package's own zlibInflate does not.
zlibInflate(Uint8List zlib) → Uint8List?: zlib decompressed — the zlib header (RFC 1950) stripped and read, and the raw DEFLATE stream behind it inflated. Returns null rather than throwing on anything short, malformed, or naming a compression method or a block type this does not decode — the same "no size to answer with" convention imageDimensions already uses for a truncated header, so a caller has one shape to check either way.

Typedefs

AssetSourceFactory = AssetSource Function(String path): Makes the AssetSource for path — the path with its scheme taken off.
AssetUriResolver = Future<Uint8List> Function(AssetRequest request): Resolves a URI referenced from inside an asset to its bytes.
SplatRangeReader = Future<Uint8List> Function(int offset, int length): Reads length bytes of the tree file starting at offset.

Exceptions / Errors

AnimationGraphFormatException: An animation graph's JSON (a model's extras) in a shape the reader does not know, naming where in the document it went wrong.
AnimationPointerFormatException: An animation pointer (KHR_animation_pointer) whose path this build does not know how to resolve.
CubeLutFormatException: A .cube colour lookup table the reader cannot read, naming the line.
DracoException: Thrown when a stream is not one this decodes, with the reason in it.
F3dFormatException: Raised when a file is not a .f3d, is truncated, or claims a version this build does not understand.
FbxFormatException: An FBX file, which this build recognises and does not read yet.
FmatFormatException: A .fmat material file that is not one: not a JSON object, no version key, or a version newer than this build reads.
FrameCaptureFormatException: A frame capture (FrameCapture.fromJson) that is not one, or is from a newer build: the message says which, and what to do about it.
GltfFormatException: A glTF or GLB file the reader cannot read: a container that is not GLB, an accessor that runs past its buffer, a component type or mode the specification does not define.
HdrFormatException: What a file that is not a readable .hdr is answered with.
ImageFormatException: An image the pure decoders (PNG, JPEG) cannot read: a signature that is not the format's, a chunk that runs past the end, a feature the decoder does not implement.
Ktx2FormatException: Raised when bytes are not a KTX2 file, are truncated, or use a feature this stage of the loader does not read yet — see the library doc comment for exactly which those are.
MaterialBundleException: A .f3dmat bundle that holds no material, or one that cannot be told apart from another. Syntax errors inside a material are MaterialSyntaxException.
MaterialSyntaxException: A material source that could not be read, with where it went wrong.
MaterialVersionException: An instance written for a version of a material this build does not have: a newer one, or none at all.
MeshoptFormatException: A meshopt-compressed buffer (EXT_meshopt_compression) that does not decode: truncated, an unknown header, or a count that does not match.
ResourceLoadCanceledException: A read or a request for a cached resource that was called off before it was handed over: what AssetCancel throws and what ResourceRequest.handle completes with after ResourceRequest.cancel.
SplatOctreeException: Thrown when bytes are not a splat tree this can read.
SplatPlyException: Thrown when a file is not a PLY this can read, with the reason in it.
SplatSpzException: Thrown when a file is not an SPZ this can read, with the reason in it.

formats library

Classes

Enums

Constants

Properties

Functions

Typedefs

Exceptions / Errors

flutter3d_core package

formats library