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 is why flutter3d_core.dart exports this library with this one's Ktx2Texture hidden. 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.
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.
GltfLoader: Decodes glTF 2.0 and GLB into engine geometry.
GltfWriter: Serializes any ModelDocument into glTF's binary container.
Ktx2ColorModel: The data format descriptor's colorModel, for the values that matter when vkFormat is undefined — gfx-78n.
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
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.
Ktx2Texture: 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.
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.
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.
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.
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.
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.
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
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.
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
ktx2HeaderOffset → const int
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
ktx2IndexOffset → const int
ktx2LevelIndexEntryBytes → const int
ktx2LevelIndexOffset → const int
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 versions 1 and 2 have: 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.
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.
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<(int, int, int, int)>: 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.
emitMaterialFragment(MaterialProgram program) → 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<(int, int, int, int)> 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<(int, int, int, int)> 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<(int, int, int, int)> 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.
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) → ({int height, int width})?: 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.
materialExtensionsFromJson(Map<String, Object?> extensions, {required TextureBinding? texture(Object? info), List<String>? warnings, 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.
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 half, 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 half-size half 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, {List<String>? warnings}) → 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.
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, List<String>? warnings, 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) → (Float64List, Float64List): The eigenvalues and unit eigenvectors of the symmetric 3×3 m (row major), by cyclic Jacobi rotations.
toGltfFilters(TextureSampling sampling) → (int, int): The (magFilter, 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.
HdrImage = ({int height, Float32List rgb, int width}): A decoded Radiance image: three floats a pixel, row 0 at the top.
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