graphics_3d library

Classes

Aabb3: A mutable axis-aligned box [min, max].
AnimationChannelData: One animated property of one node.
AnimationClip: A glTF animation, ready to sample: sample writes the nodes it moves at any time into a Pose.
AnimationData: A glTF animation (a clip).
AnimationPlayerComponent: Plays the animations (glTF clips) of the entity's ModelComponent.
AnimationSamplerData: Keyframes: times and values.
AnimationSystem3D: Moves animation time on and places sockets: for every entity with an AnimationPlayerComponent and a ModelComponent, advances its clip (looping or holding at the end) and its crossfade; then moves each SocketComponent entity to its node in its parent's posed model.
Arch3D: A curved band standing up in its entity's XY plane: angle of a ring of radius (outside) and thickness, depth deep. Half a turn, the default, is an arch with its feet on the ground.
BloomSettings: The glow around bright things (HDR only).
Capsule3D: An upright capsule: a cylinder with a half ball on each end, height tall overall (never less than its width) and of radius.
ClipFixup: The one place the engine's clip space meets Flutter GPU's.
Cone3D: A cone of radius at its base and height, its tip up.
CookedModel: The cooked model format (.jmodel): a ModelData ready to upload — vertices and indices as the renderer takes them, textures decoded with their mip levels — so loading it parses no glTF and decodes no image.
CookedResult: What cookModel made.
Cube3D: A box width × height × depth: a cube when they are equal.
Cylinder3D: An upright cylinder of radius and height, segments round.
DefaultTextures: 1×1 textures standing in for a material's missing maps: white (base colour, metal-rough, occlusion, emissive — so factors apply alone) and a flat normal.
DirectionalLight: The sun: light travelling along direction.
DynamicResolution: Renders fewer pixels while frames run slow, and more again when there is time to spare: a scale between minScale and maxScale on top of the renderer's own, stepped by what the last second of frames took.
Environment: The sky and the light that doesn't come from lights.
EnvironmentComponent: The sky and the ambient light of a 3-D scene. The first enabled one in a scene is used.
EnvironmentMapData: What lights a scene from all round, ready for the GPU: a small cube map of what surrounds it — level 0 the sky itself, each smaller level blurred for a rougher surface (GGX, prefiltered here on the CPU) — and its diffuse light as nine spherical-harmonic coefficients.
Frustum: The six planes bounding what a camera sees, each facing inwards.
GpuBuffer: GPU memory holding vertices, indices or uniforms.
GpuBufferView: A range of a buffer, as bound to a draw.
GpuCaps: What a GpuDevice can do. Read once when the device is created; the renderer chooses its paths (HDR, MSAA, skinning, compression) from it.
GpuColorTarget: One colour attachment.
GpuCommands: Commands recorded for one submission.
GpuDepthTarget: The depth (and stencil) attachment.
GpuDevice: A GPU the renderer draws with.
GpuEnvironmentMap: An EnvironmentMapData on the GPU: its levels in one half-float cube texture, its spherical harmonics beside it. Give it to Environment.map and lit surfaces take their ambient light and reflections from it; with Environment.skybox the sky shows it.
GpuMaterial: A material's textures and settings, ready to bind.
GpuModel: A model uploaded to the GPU: its primitives' buffers, its materials' textures, and the data it came from.
GpuPass: Records draws into one set of targets.
GpuPipeline: A vertex and fragment shader with a vertex layout, ready to draw.
GpuPrimitive: One primitive's vertex and index buffers.
GpuRenderTargets: What a pass draws into.
GpuSampler: How a texture is sampled.
GpuShader: One compiled shader stage.
GpuShaderLibrary: Compiled shader stages, by name.
GpuSurface: A pool of presentable textures Flutter draws as an image.
GpuSurfaceFrame: A texture leased from a GpuSurface for one frame.
GpuTexture: An image on the GPU.
GpuTextureDesc: A texture's size, format and uses.
GpuUniformBlock: A uniform block's layout, from shader reflection.
GpuVertexAttribute: One attribute read from a vertex buffer.
GpuVertexBufferLayout: One vertex buffer slot.
GpuVertexLayout: All of a pipeline's vertex buffer slots, slot 0 first.
Graphics3D: 3-D graphics for an engine. Give one to the engine and its 3-D components — ModelComponent, LightComponent, EnvironmentComponent, AnimationPlayerComponent, SocketComponent and the shapes from Cube3D to Polygon3D — are saved, loaded, offered in the editor's 3-D scenes and drawn:
GraphicsModelAsset: The engine's view of a model loaded by just_graphics_engine: its bounds and triangles in engine axes (+Y down), for picking and mesh colliders.
GraphicsModelLoader: Creates GraphicsModelAssets for the engine's asset manager.
GraphicsModels: The models a game's scenes use, each loaded once per asset path: read from bundle, parsed, uploaded with uploader.
GraphicsSceneRenderer: Draws a world's 3-D components (Model, the shapes, Light, Environment) from the engine's camera — the SceneRenderer a Graphics3D adds.
GraphicsSchemas: How the 3-D components are saved and shown in an editor. Every one is a 3-D component (Dimensions.threeD).
GraphicsShapes: The GPU side of the shapes (Primitive3D): meshes made from their sizes and materials from their looks, uploaded once and shared by every shape alike — twenty equal crates are one mesh and one material, drawn in one instanced draw.
HdrImage: An image of linear RGB floats: a Radiance .hdr decoded.
ImageData: An image as stored in the file (PNG, JPEG, …).
InstanceBatch: Many copies of one primitive in one material, drawn in one call: grass, rocks, tiles, a fence's posts. Unlike MeshInstances, which the renderer culls and packs one by one each frame, a batch is culled as a whole by its bounds and keeps its instances on the GPU between frames, uploaded again only when they change (setInstances).
LightComponent: A light at its entity's transform. Directional and spot lights shine along the entity's forward (+Z) axis.
LightData: KHR_lights_punctual: a light pointing down its node's -Z.
MaterialChain: Walks a variant's parents and lays each file over the one before.
MaterialData: A glTF metallic-roughness material, with the extensions this renderer reads (KHR_materials_unlit, KHR_materials_emissive_strength, KHR_texture_transform).
MaterialFile: A material saved in its own file (*.material.json), which 3-D shapes and models refer to by path: change it once and everything drawn with it changes.
MaterialLibrary: The material files (*.material.json) the scene's shapes and models draw with, read once each and made into GPU materials.
MaterialOverride: Changes to one material; a null field keeps the file's value.
MaterialOverrides3D: An entity's own values for the material files it is drawn with — its shape's (Primitive3D.material) or its model's (ModelComponent.materials): a glow pulsing, a colour fading, a texture sliding. By key from MaterialFile.animatableKeys, shaped as a material file saves them (color an ARGB number, tiling [x, y]).
MaterialSlots: Where an entity's material file goes: its shape's Primitive3D.material, or — for a model — the file drawn for every one of its materials (* in ModelComponent.materials). What painting a material on, and picking one up, work through.
Matrix4: 4D Matrix. Values are stored in column major order.
MeshBuilder: Builds a ShapeMesh a vertex and a triangle at a time. Each triangle is wound to face the way its vertices' normals point, whichever order it was given in.
MeshData: One glTF mesh.
MeshInstance: One primitive drawn somewhere in the world.
ModelComponent: Draws a 3-D model (glTF 2.0, .glb or .gltf) at its entity's transform. The model's own +Y-up axes are turned into the engine's.
ModelData: A model, ready for the GPU: meshes as interleaved vertices and indices, materials, encoded images, the node tree and its lights. In the file's own axes (glTF: +Y up); the renderer corrects axes once, at the root.
ModelImportSettings: How a model file is imported: what an editor saves beside it as <model>.import.json (see ModelImportSettings.sidecarOf) and what cooking it (cookModel) applies.
ModelUploader: Uploads ModelData to a GpuDevice.
NodeData: A node of the model's tree.
NullGpuDevice: A GpuDevice that draws nothing and records what it was asked to do.
NullUniformBlock: A uniform block a NullGpuDevice shader declares.
OverlayDraw: Lines drawn over the scene: a primitive's edges where world puts it, in color — a selection's highlight, a wireframe.
PipelineSet: Every pipeline a renderer draws with, created up front.
PipelineSpec: A pipeline the renderer needs, named by its shaders in a bundle.
Plane: The plane of points p with normal · p + constant = 0.
Plane3D: A flat rectangle width × depth lying on its entity's ground plane, seen from both sides. Its collider is a slab 0.1 m thick just under it.
Polygon3D: An outline drawn on the ground, raised height: a floor, a wall or a platform of any shape. Each of its points is (x, z) in its entity's space — Offset.dx is x, Offset.dy is z.
Pose: Every node's translation, rotation and scale: what an animation moves.
PosedModel: One placed copy of a model in a pose of its own: what an animated character is to the renderer.
Primitive3D: A 3-D shape made from its own sizes rather than a model file — the base of Cube3D, Sphere3D, Plane3D, Cylinder3D, Capsule3D, Cone3D, Torus3D, Ramp3D, Stairs3D, Arch3D and Polygon3D.
PrimitiveData: Triangles with one material.
PunctualLight: A point or spot light.
Quaternion: A mutable rotation quaternion (x, y, z, w), Hamilton convention.
Ramp3D: A wedge rising towards +Z: flat underneath, height tall at its back, nothing at its front — something to walk up.
Ray3: A half-line from origin along direction.
Renderer3D: Forward renderer for RenderScenes: physically based lighting from a sun (with two cascades of shadow maps), up to 8 point/spot lights and a hemisphere ambient; skinned meshes; a gradient sky; HDR with 4x MSAA and ACES tonemapping where the device can.
RendererPipelines: The pipelines the renderer draws with.
RenderProvider<C extends Component>: Turns a component the renderer does not know — a terrain, a scatter of grass, a swept road — into meshes and batches it draws.
RenderProviderContext: What a RenderProvider builds with: the uploader that makes GPU meshes, the models and the shapes' materials it may share, and the stand-in textures.
RenderProviderOutput: What a RenderProvider hands the renderer for one entity: meshes and batches placed in the entity's own space — the renderer moves them with the entity.
RenderProviders: The RenderProviders of one engine: what its 3-D renderer draws beyond models and shapes.
RenderScene: Everything the renderer draws in one view.
RenderStats: What the last frame did.
RenderTargetPool: Reuses intermediate render targets (depth, MSAA colour, shadow maps, post-processing buffers) from frame to frame instead of allocating new ones.
RenderView: The camera a frame is drawn from, in the renderer's conventions: +Y down, clip y down, depth 0..1 (JustMatrix4.setPerspectiveYDown).
RgbaImage: An image as RGBA8 pixels.
SamplerData: glTF sampler state (GL enum values).
Scene3DView: Draws scene seen from camera with renderer, every frame.
SceneEditorAids: What an editor shows in its views of the scene beyond what the game draws: what it hides, the selection's outline, a view mode and a slice. Set by the editor (GraphicsSceneRenderer.aids), never by a game, and left out of the plainViews — the game's own camera seen in the editor.
ShadowFit: A sun shadow map's placement for one frame.
ShadowSettings: How the sun's shadows are drawn.
ShapeMesh: A 3-D shape's triangles on the CPU, in its own space: the renderer's axes (+Y down), metres. Front faces wind counter-clockwise seen from outside, as glTF's do once turned into engine axes.
ShapeSchemas: How the 3-D shapes are saved and shown in an editor. Each is a 3-D component (Dimensions.threeD) in the 3D Shapes group: its sizes, its detail, then its material.
ShapeUv: How a shape lays its texture out.
ShapeValues: What a shape's mesh or look was last made from, kept to tell cheaply whether it has changed: a renderer keeps one per shape and each frame gives it the shape's values (Primitive3D.writeShapeValues, Primitive3D.writeMaterialValues) between begin and end. Numbers are compared in place, so nothing is made while nothing changes.
SkeletalAnimationTarget: Plays an animator graph's states on a 3-D model's skeleton: an entity with an AnimatorComponent, a ModelComponent and an AnimationPlayerComponent (which it drives). A transition's duration crossfades; a blend tree blends its motions, weighted by the graph's parameters every update. It sets what the player plays at run time (playingClip, playingSpeed, playingLoop), never what it saves.
SkeletalClipTrack: A timeline track playing clips on the bound entity's 3-D model (its AnimationPlayerComponent): each block names a clip, plays at the block's speed, and loops as the block says. Entering a block crossfades over the player's crossfade; between blocks the model goes back to the clip it was playing before — what was authored, unless something (an animator) had taken it over. Scrubbing puts the clip exactly where the block says it should be. It sets what the player plays at run time, never what it saves.
Skeleton: A model's node tree flattened parents first, for turning a Pose into node matrices and those into the joint palettes of its skins.
SkinData: A glTF skin: the nodes that are its joints and how the mesh sat on them.
SkinPalette: One posed skin, ready to draw: rows holds its joint palette (kPaletteFloats floats per joint), refreshed by its owner each frame.
SocketComponent: Pins its entity to a node of its parent's model — a joint, for a sword in a hand or a hat on a head. The entity must be a child (it has a ParentComponent) of an entity with a ModelComponent; each update it is moved to that node, keeping its own scale.
SortKey: Draw sort keys: one integer per draw, sorted ascending.
Sphere3D: A ball of radius, segments round and rings from pole to pole.
Stairs3D: A flight of steps solid steps rising towards +Z, width wide, height tall and depth long overall.
TextureData: A texture: an image and how to sample it.
TextureRef: A material's use of a texture.
Torus3D: A ring lying flat: a tube of tubeRadius bent round a circle of radius (to the middle of the tube).
UniformWriter: Fills one uniform block's bytes: 32-bit floats and ints in host byte order, at member offsets taken from shader reflection.
Vector2: A mutable 2-D vector.
Vector3: A mutable 3-D vector.
VertexOffsets: Byte offsets of each attribute inside one vertex.

Enums

AlphaMode: How a material treats alpha.
AnimationInterpolation: How values between keys are found.
AnimationPath: What an animation channel moves.
GpuAddress: What sampling does outside 0..1.
GpuBlend: Colour blending presets.
GpuCompare: Depth comparison.
GpuCompression: A family of block-compressed texture formats a device may support.
GpuCull: Which faces to skip.
GpuFilter: Texture filtering.
GpuFormat: A texture's pixel format.
GpuIndexType: Size of each index.
GpuLoad: How an attachment starts a pass.
GpuStorage: Where a texture lives and who can write it.
GpuStore: What happens to an attachment when its pass ends.
GpuTopology: What a draw's vertices form.
GpuVertexFormat: One vertex attribute's type.
LightKind: The kind of a LightComponent.
LightType: A punctual light.
MaterialAlpha: How a MaterialFile treats what is behind it.
MaterialKind: What a MaterialFile is.
MaterialUv: How a MaterialFile's maps are laid over a surface.
RenderViewMode: How the renderer draws the scene: as it looks, flat-lit to read shapes by, or as lines only.
SkinningMode: How joint matrices reach the vertex shader.
TextureCompression: How cooked textures are stored.
UvMode: Where a material's textures are read.

Extensions

JustMatrix4 on Matrix4: Engine-side operations on Matrix4.
ShapeMeshGeometry on ShapeMesh: A ShapeMesh as the engine's ModelGeometry, for picking and colliders.

Constants

kBatchInstanceFloats → const int: Floats per instance in a batch's buffer: a model matrix, then a normal matrix (three columns of four) — what every lit and shadow draw reads.
kMaxUniformJoints → const int: The most joints the uniform-array fallback holds per draw.
kPaletteFloats → const int: Floats per joint in a palette: the top three rows of its 4x4 matrix.
kSkinFloats → const int: Floats per vertex in PrimitiveData.skin: four joint indices (as floats) and their four weights, which sum to 1.
kVertexFloats → const int: Floats per vertex in PrimitiveData.vertices: position (3), normal (3), tangent (4, w = handedness; all zero when the file had none), uv (2), colour (4).
litLayout → const GpuVertexLayout: The vertex layout of every lit mesh: one vertex buffer (VertexOffsets) and one per-instance buffer of a model matrix and a normal matrix.
litSkinnedLayout → const GpuVertexLayout: Skinned lit meshes: vertices, joints and weights, then per instance the matrices and the palette's first texel.
supportedGltfExtensions → const Set<String>: Extensions this loader reads. A file that requires any other is refused, since it can't be shown correctly without it.

Properties

gltfToEngine → Matrix4: glTF is +Y up; the engine is +Y down with +Z into the screen. A 180° turn about X takes one to the other. It is a rotation, not a mirror, so triangle winding is kept.
final
rendererNullShaders → Map<String, Map<String, NullUniformBlock>>: The renderer's shaders' uniform blocks as reflection reports them, for a NullGpuDevice standing in for a GPU: NullGpuDevice(shaders: rendererNullShaders) can create a Renderer3D, which then runs its whole CPU side (culling, sorting, batching, uniform packing) and draws nothing. A GPU test checks these against the real reflection.
final

Functions

buildMips(RgbaImage image, {required bool srgb, int? maxLevels}) → Future<List<RgbaImage>>: Builds the mip chain of image in a background isolate, at most maxLevels levels (all the way to 1×1 by default): level 0 is the image itself. srgb averages in linear light, so colour textures do not darken as they shrink.
cookModel(Uint8List source, {required String name, ModelFetch? fetch, ModelImportSettings settings = const ModelImportSettings()}) → Future<CookedResult>: Cooks the model file source (.glb or .gltf, named name; fetch reads files a .gltf refers to) with settings: lengths scaled, materials changed, every texture decoded, shrunk to ModelImportSettings.maxTextureSize and given its mip levels (sRGB averaged for colour maps, linear for data maps). The result loads with no glTF parsing and no image decoding.
cookStamp(Uint8List source, ModelImportSettings settings) → String: A short fingerprint of source and settings: a cooked model made from both carries it (CookedModel.stampOf), so a tool can tell when it needs cooking again.
createGpuDevice({void onUnsupported(String reason)?}) → GpuDevice?: On the web there is no Flutter GPU: always null, with the reason given to onUnsupported.
decodeImage(Uint8List encoded) → Future<RgbaImage>: Decodes a PNG or JPEG (anything Flutter decodes) into RGBA8. Must run on the root isolate; Flutter decodes off the UI thread itself.
decodeRadianceHdr(Uint8List bytes) → HdrImage: Decodes a Radiance .hdr (RGBE, flat or run-length encoded, -Y w +X h orientation) into linear RGB floats.
fitSunShadow(RenderView view, Vector3 direction, ShadowSettings settings, ShadowFit out, {double from = 0, double? to}) → bool: Places a shadow map for a sun shining along direction around what view sees up to settings' distance, into out. The box is the bounding sphere of that slice of the view (so it keeps its size as the camera turns) and moves in whole texels (so shadow edges don't crawl as the camera moves). False when there is nothing to fit.
halve(RgbaImage image, {required bool srgb}) → RgbaImage: image at half size (each side halved, at least 1), every pixel the average of up to four source pixels. Alpha is always averaged linearly.
loadModelData(Uint8List bytes, {required String name, ModelFetch? fetch}) → Future<ModelData>: Reads a glTF model — .glb or .gltf — into ModelData.

Typedefs

ModelFetch = Future<Uint8List> Function(String uri): Fetches a file a glTF refers to, by the URI the file used (relative to the model).
Scene3DFrameCallback = void Function(Duration elapsed, Size size): Called before Scene3DView draws a frame: move the camera, animate the scene. elapsed is the time since the view started ticking; size is its size in logical pixels.

graphics_3d library

Classes

Enums

Extensions

Constants

Properties

Functions

Typedefs

just_game_engine package

graphics_3d library