scene library

3D rendering for Flutter, built on Flutter GPU and Impeller.

The entry points most applications need are:

Flutter Scene needs Flutter 3.47 (stable) or newer. Rendering goes through the Flutter GPU API, which every platform except the web turns on once per project (see the package README).

Classes

AccelerationModule
Adds a constant acceleration (world units per second squared) to every particle's velocity each step. Use it for wind or as an extra gravity on top of the system's own gravity.
AmbientOcclusionSettings
Screen-space ambient occlusion settings for a Scene.
Animation
A reusable description of an animation, parsed from a model.
AnimationClip
An instance of an Animation that has been bound to a specific Node.
AnimationPlayer
Drives playback and blending for the AnimationClips on a single node subtree.
AssetModelSource
Loads a .glb model from the asset bundle.
AutoExposureSettings
Automatic exposure (eye adaptation) settings for a Scene.
BezierPath
A path of joined cubic Bezier segments.
BillboardGeometry
A batch of camera-facing quads ("billboards"), expanded from per-instance data in the vertex shader and drawn in a single instanced call.
BloomSettings
Makes bright areas bleed light into their surroundings. Computed in a chain of HDR passes and added back to the scene before tone mapping.
BoxEmitterShape
Emits particles uniformly inside an axis-aligned box, each headed along a shared direction.
BoxVolumeBounds
An axis-aligned box region.
Camera
A view onto a scene: a world-space eye position and orientation paired with a lens projection, used by Scene.render to map the scene into clip space.
CameraComponent
An engine Component that places a Camera in the scene.
CameraController
Drives a camera node's transform from continuous input.
CameraControls
Feeds pointer, scroll, and keyboard input to a CameraController.
CameraProjection
A lens projection that maps view-space coordinates into clip space.
CapsuleGeometry
A capsule (a cylinder capped by two hemispheres) aligned with the Y axis, centered on the origin.
CapturedPass
One executed pass: identity, CPU time, and the blackboard keys it read and wrote, in observation order.
CapturedResource
One resource observed during the capture frame: a texture written by a pass (under a blackboard key or a transient debug name), or a non-texture blackboard entry (packed uniform data).
CatmullRomPath
A smooth curve passing through every one of a list of points.
ChromaticAberrationSettings
Splits the red and blue channels toward the edges, like a simple lens. Sampled from the scene color before grading and tone mapping.
ColorDistribution
A color value generator sampled per particle, the color analog of FloatDistribution.
ColorGradient
A color curve over normalized time [0, 1], baked into a lookup table.
ColorGradingSettings
Color grading applied to the linear HDR scene color, before exposure and tone mapping.
ColorLut
A 3D color-grading lookup table applied by the resolve pass.
ColorOverLifeModule
Sets each particle's color from a ColorDistribution sampled over its normalized age (color over life).
ColorStop
One color stop of a ColorGradient: a linear RGBA color at normalized time t.
Component
A unit of data or behavior attached to a Node.
ConeEmitterShape
Emits particles from a disc of radius in the local XZ plane, each headed within a cone of half-angle angle about +Y.
ConstantColor
A ColorDistribution that is color for every particle.
ConstantFloat
A FloatDistribution that is value for every particle.
CuboidGeometry
An axis-aligned box geometry spanning -extents/2 to +extents/2 on each axis, with flat per-face normals.
CurveFloat
A FloatDistribution that samples curve over the particle's normalized age and scales it by scale.
CustomRenderPass
A user-supplied render pass inserted into the built-in pipeline at a named stage. Add one with Scene.addRenderPass.
CylinderGeometry
A cylinder aligned with the Y axis, centered on the origin.
DashPattern
A repeating dash-and-gap pattern for a PolylineGeometry, measured in scene units along the line's arc length.
DecodedHdr
A decoded HDR image: linear RGBA float pixels (alpha 1), row-major, row 0 at the top.
DepthOfField
Depth-of-field settings for a Scene (scene.depthOfField), disabled by default.
DirectionalLight
An infinitely-distant light source (e.g. the sun) that illuminates the whole scene from a single direction.
DirectionalLightComponent
An engine Component that places a DirectionalLight in the scene.
DiscGeometry
A flat filled disc in the XZ plane, centered on the origin, facing +Y.
EmitterShape
Decides where a freshly spawned particle starts and which way it initially heads.
EnvironmentMap
A source of image-based lighting: diffuse irradiance plus prefiltered specular radiance, both derived from an equirectangular environment.
EnvironmentSettings
A copyable, interpolatable snapshot of a Scene's scene-wide look.
EnvironmentSkySource
Shows the scene's image-based-lighting environment as the background, optionally blurred.
EnvironmentVolume
A region that overrides the scene look with its settings, contributing by camera position.
EnvironmentVolumeBounds
The shape of an EnvironmentVolume's region.
EnvironmentVolumeComponent
A Component that contributes a spatial environment volume: a region whose look (settings) overrides the scene environment, blended by camera position so the environment transitions as the camera moves between areas.
ExtrudeGeometry
An arbitrary closed 2D profile swept along a ScenePath.
FilmGrainSettings
Adds animated noise over the final image, after tone mapping.
FlipbookModule
Animates each particle's flipbook ParticleStorage.frame through a frameCount-cell atlas.
FloatDistribution
A scalar value generator sampled per particle, the single value type behind every scalar particle parameter.
FlyCameraController
A free-look flying camera: drag to look, WASD to move on the look plane (strafing ignores pitch so looking down does not drift into the floor), Q/E to move down/up, and shift to boost speed.
FmatMaterialRegistry
Resolves and loads the .fmat materials the buildMaterials build hook compiled.
Fog
Distance fog for a Scene: geometry blends toward color the farther it is from the camera, evaluated per-fragment in linear HDR before tone mapping so fog is exposed and tone-mapped along with the scene.
FollowCameraController
A third-person camera that eases toward following followTarget, orbiting it at yaw / pitch / distance and looking at a point lookHeight above its origin. Drag orbits, scroll dollies.
GaussianSplats
A loaded Gaussian splat set, the decoded arrays plus the GPU textures the splat shaders fetch from.
Geometry
Vertex (and optional index) data along with the vertex shader used to transform it.
GeometryBufferArena
Packs immutable mesh uploads into shared GPU buffers.
GeometryBuilder
Assembles a MeshGeometry one vertex and triangle at a time.
GodRaysSettings
Directional volumetric god rays (crepuscular rays / light shafts).
GpuTextureSource
Wraps a raw gpu.Texture as a TextureSource, for advanced or interop cases that already own a GPU texture (widget/particle textures, custom pipelines) and do not need Texture2D's image decode and mip generation.
GradientColor
A ColorDistribution that samples gradient over the particle's normalized age (color over life).
GradientSkySource
A stylized gradient sky: zenith, horizon, and ground colors with an HDR sun disk.
HighlightStyle
How the selection outline (around nodes with a Node.highlightColor) is drawn. Reachable through Scene.highlightStyle.
IcosphereGeometry
A geodesic sphere built by subdividing an icosahedron, centered on the origin.
InstancedMesh
Many copies of one Geometry / Material pair, each placed by its own model transform.
InstancedMeshComponent
An engine Component that draws an InstancedMesh.
Lighting
The lighting state handed to a Material when it binds for a draw.
LinearDragModule
Damps velocity toward zero with a linear drag coefficient (per second): each step scales velocity by max(0, 1 - coefficient * dt).
LineSegmentData
Disconnected line segments (point pairs) derived from a mesh, the output of MeshData.extractEdges.
LineSegmentsGeometry
A batch of thick, disconnected line segments, each expanded into a camera-facing quad of a fixed world-space width in the vertex shader and drawn in a single instanced call.
LodComponent
A MeshComponent that draws one of several level-of-detail variants of an object, chosen each frame from how large the object appears on screen.
LodLevel
One level of detail for an LodComponent: a drawable variant shown while the object's projected on-screen size (see lodScreenSize) is at least screenSize, a fraction of the viewport height.
Material
Base class for shading a MeshPrimitive.
MaterialParameters
Type-checked, name-addressed parameters for a custom material.
MaterialsVariantsComponent
Switches an imported model between its named material variants (KHR_materials_variants).
MemoryCategory
One category of resident GPU memory.
MemoryModelSource
Wraps already-loaded .glb bytes, for models fetched by the app (a network download, a local cache, generated content).
MemoryReport
A snapshot of what flutter_scene is keeping resident.
Mesh
Defines the shape and appearance of a 3D model in the scene.
MeshAttributeData
One named per-vertex attribute stream carried by a MeshData, matching a custom material's attributes entry (see Geometry.setCustomAttribute).
MeshComponent
An engine Component that draws a Mesh.
MeshData
An isolate-transferable snapshot of a mesh's vertex and index data.
MeshGeometry
A triangle mesh built at runtime from vertex attribute arrays.
MeshParticleEmitterComponent
An engine component that simulates a ParticleSystem on the CPU and draws each live particle as an instance of a 3D mesh, one instanced draw per geometry.
MeshPrimitive
Represents a single part of a Mesh, containing both Geometry and Material properties.
MeshTriangle
One triangle of a MeshData, yielded by MeshData.triangles.
Node
A Node represents a single element in a 3D scene graph.
NodeCamera
A Camera whose view comes from a node's world transform: the +Z axis is the look direction, +Y is up, and the translation is the eye. This is the inverse of the eye/target/up convention PerspectiveCamera builds, so a node placed at inverse(camera.getViewMatrix()) yields the same view.
NodeFilter
Selects which scene nodes an object-filtered draw includes.
OrbitCameraController
Orbits the camera around a fixed target point: drag rotates, scroll or pinch dollies in and out, and a two-finger or secondary drag pans the target across the view.
ParticleBurst
A one-off (or repeating) burst of particles scheduled at a point in the emitter's run.
ParticleCurve
A scalar curve over normalized time [0, 1], authored as keyframes and baked once into a lookup table so per-particle, per-frame sample calls are a cheap clamped table lerp rather than a keyframe search.
ParticleEmitterComponent
An engine component that simulates a ParticleSystem on the CPU and draws its live particles as one instanced batch of camera-facing billboards.
ParticleKeyframe
One control point of a ParticleCurve: a value at normalized time t (in [0, 1]).
ParticleModule
A unit of per-particle behaviour layered onto a system's simulation.
ParticleStorage
Structure-of-arrays storage for one emitter's live particles, with an O(1) free pool.
ParticleSystem
A self-contained, CPU-driven particle simulation: storage plus the config, shape, spawner, and module stack that fill and advance it.
PerspectiveCamera
A standard pinhole-style perspective camera.
PerspectiveProjection
A standard pinhole perspective projection.
PhysicallyBasedMaterial
A metallic-roughness physically based material with optional layered and transmissive features.
PhysicalSkySource
A physically based daylight sky: an analytic single-scattering atmosphere (Rayleigh and Mie terms) with an HDR sun disk, producing plausible day, sunset, and twilight skies from a sun direction.
PlaneGeometry
A flat rectangular grid in the XZ plane, centered on the origin, with its surface facing +Y.
PointEmitterShape
Emits every particle from the local origin along a single direction.
PointLight
A light that radiates from a single world-space point equally in every direction, its influence falling off with distance.
PointLightComponent
An engine Component that places a PointLight in the scene.
PolylineGeometry
A thick, camera-facing line through a list of points.
PolylinePath
A path of straight segments connecting a list of points.
PostEffect
A custom, user-authored post-processing effect: a fragment shader that reads the current color and writes a new one.
PostProcessSettings
Built-in post-processing settings for a Scene.
PreprocessedMaterial
A material driven by a .fmat custom-material shader and its sidecar metadata (produced at build time by buildMaterials).
PreprocessedSky
A sky driven by a .fmat sky shader (sky { vec3 Sky(vec3 direction) }) and its sidecar metadata (produced at build time by buildMaterials).
RectAreaLight
A rectangle that emits light from its face, shaded with linearly transformed cosines so the highlight stretches and the falloff follows the panel's true shape and area.
RectAreaLightComponent
An engine Component that places a RectAreaLight in the scene.
RenderGraphCaptureRequest
What a capture collects. Metadata (passes, data flow, timings) is always recorded; images are opt-in and can be restricted to thumbnails or to a set of resource keys, since a full-resolution capture of every target can exceed 150 MB at display sizes.
RenderGraphCaptureResult
The product of one captured frame.
RenderPassContext
The frame context handed to CustomRenderPass.execute.
RenderTexture
An offscreen render target a RenderView can render into.
RenderTextureSampling
Sampling options used when a material samples a RenderTexture.
RenderTextureUpdate
When a RenderTexture re-renders.
RenderTextureView
Displays a live RenderTexture in the widget tree.
RenderView
One view of a Scene: a camera plus where and how its image is drawn.
ResourceGroup
Tracks a set of in-flight resource loads so a scene can wait for all of them before it is shown, and report aggregate progress while they run.
RibbonGeometry
A flat strip of constant width swept along a ScenePath.
RingGeometry
A flat annulus (a disc with a concentric hole) in the XZ plane, centered on the origin, facing +Y.
RotationModule
Integrates each particle's in-plane rotation from its angular velocity (rotation += angularVelocity * dt).
Scene
Represents a 3D scene, which is a collection of nodes that can be rendered onto the screen.
SceneAnimationSpec
Declares the playback state of one of a SceneModel's imported animations.
SceneMesh
A declarative mesh node: SceneNode plus a Geometry and Material.
SceneModel
A declarative imported model: loads a .glb and mounts it as a node.
SceneModelSource
Describes where a SceneModel loads its model bytes from.
SceneNode
A declarative Node: a transform in the scene graph, described in build().
SceneNodeController
The declarative scene layer, widgets that own and reconcile Nodes in a retained Scene. Widgets are immutable descriptions; each widget's state holds the engine object and applies property diffs on rebuild, so an unchanged rebuild writes nothing and structural changes are proportional to what changed.
SceneNodeHost
Mounts an app-owned Node subtree inside a declarative tree.
ScenePath
A curve through 3D space, independent of any geometry or rendering.
ScenePathFrame
An oriented coordinate frame at a point along a ScenePath.
ScenePointer
A programmatic pointer into a scene: a crosshair, a gamepad-driven cursor, a VR laser, or the built-in pointer behind automatic widget input.
SceneRaycastHit
A render-geometry intersection from raycastNode (or Scene.raycast).
SceneRegistry
Resolves generated .fsceneb files by source path, the .fscene counterpart of ModelRegistry.
SceneScope
Exposes the active Scene (and the per-frame elapsed time) to descendants of a SceneView.
SceneSubtree
Mounts declarative scene widgets under an app-owned Node.
SceneView
A widget that renders a Scene and drives its per-frame repaint.
ScreenSpaceReflectionsSettings
Screen-space reflection settings for a Scene.
SemanticsComponent
Exposes the owning Node to assistive technology (screen readers, switch access) as one element of the enclosing SceneView's semantics.
ShaderMaterial
A Material backed by a caller-supplied fragment shader.
ShaderSkySource
Draws a custom sky from a fragment shader.
ShadowCascade
One cascade of a cascaded shadow map, produced by DirectionalLight.computeCascades.
SizeOverLifeModule
Scales each particle's rendered size by a FloatDistribution sampled over its normalized age, relative to the size set at spawn (size = baseSize * scale(age / lifetime)).
Skin
A skeletal binding used by skinned meshes for animation.
SkinnedGeometry
Geometry whose vertices use the skinned 104-byte layout: the unskinned attributes followed by 4 joint indices and 4 joint weights.
Skybox
The visible background drawn behind a Scene.
SkyEnvironment
Drives Scene.environment from a sky on a refresh policy.
SkySource
A source of skybox color as a function of world-space view direction.
Spawner
Decides how many particles to emit on each simulation step from a steady rate plus any bursts.
SphereEmitterShape
Emits particles from a sphere (or its surface, or a hemisphere), each headed radially outward.
SphereGeometry
A UV sphere centered on the origin.
SphereVolumeBounds
A sphere region.
SplatComponent
An engine component that draws a GaussianSplats set.
SplatData
The CPU-side contents of a Gaussian splat set as flat, index-parallel arrays (one entry per splat).
SpotLight
A light that radiates from a world-space point within a cone, combining a PointLight's distance falloff with an angular falloff between an inner and outer cone.
SpotLightComponent
An engine Component that places a SpotLight in the scene.
Sprite
A single camera-facing textured quad, ready to attach to a Node.
SpriteMaterial
A material for camera-facing quads drawn by BillboardGeometry.
SunLight
Aims a scene's directional light at a SunSky's sun, so cast shadows track the sky.
SunSky
A sky that exposes a directional sun, so the engine can drive a matching shadow-casting directional light from it.
Surface
Manages the swapchain color textures a Scene composites onto the Flutter canvas, plus the pools of transient render-graph attachments.
Texture2D
A 2D image texture ready to bind to a material's texture slot.
TextureAtlas
A uniform grid texture atlas: one or more equally sized PBR maps packed as columns x rows square tiles, with an optional gutter of padding texels around each tile so mip sampling does not bleed across tile edges.
TextureSampling
How a texture is sampled. The defaults are trilinear, anisotropic, and mipmapped, the tasteful default for material textures viewed in 3D.
TextureSource
Something a material can sample: it yields the GPU texture to sample for the current frame and the sampler to bind it with. Implemented by Texture2D (a static image) and RenderTexture (a live, rendered-into texture).
TextureTransform
A texture-coordinate transform applied before sampling a material slot.
TorusGeometry
A torus (ring) lying in the XZ plane, centered on the origin.
TrailComponent
An engine component that trails a camera-facing ribbon behind its owning node as the node moves, for missiles, sword slashes, tracers, and debris.
TransientWriter
Destination for per-frame transient GPU data (uniform blocks, instance vertex data). Emplaced data is valid for the current frame only.
TubeGeometry
A round cross-section of constant radius swept along a ScenePath.
TurbulenceModule
Advects particles through a curl-noise field, the divergence-free swirl that gives fire, smoke, and drifting embers their turbulent motion.
UniformColor
A ColorDistribution that picks a color between a and b per particle from its stored random (constant over the particle's life).
UniformCurveFloat
A FloatDistribution whose value follows, per particle, a blend between a min and max curve chosen by the particle's stored random. Each particle keeps its own curve inside the envelope for the whole life.
UniformFloat
A FloatDistribution that picks a value in [min, max] per particle from its stored random (constant over the particle's life).
UnlitMaterial
A material that draws geometry with a flat color or texture, ignoring scene lighting.
UnskinnedGeometry
Geometry whose vertices use the unskinned 72-byte layout.
VertexAttributeDescriptor
A described vertex attribute: the shader input it feeds (by name), its element format, and its byte offsetInBytes within the owning buffer's per-element stride.
VertexBufferDescriptor
One vertex buffer slot: its per-element strideInBytes, how it advances while drawing (stepMode), and the attributes read from it. The buffer's position in VertexLayoutDescriptor.buffers is its binding slot.
VertexLayoutDescriptor
A complete, described vertex input layout: the buffer slots a pipeline reads from and the attributes each one feeds.
VignetteSettings
Darkens the image toward the edges, after tone mapping.
WedgeGeometry
A triangular-prism wedge (a ramp), centered on the origin in X and Z with its base on the y = 0 plane.
WidgetComponent
A live widget subtree on a scene surface.
WidgetTexture
Hosts a live widget subtree and streams its visual output into a WidgetTextureController's texture for sampling inside a scene.
WidgetTextureController
Owns the gpu.Texture a WidgetTexture streams its child into.
WidgetUpdatePolicy
When a WidgetTexture (or a WidgetComponent) re-captures its child.

Enums

AlphaMode
How a PhysicallyBasedMaterial's alpha channel is interpreted, matching glTF's alphaMode.
AmbientOcclusionMethod
Which screen-space occlusion estimator AmbientOcclusionSettings runs.
AntiAliasingMode
Anti-aliasing strategy used when rendering a Scene.
BillboardFacing
How a billboard quad orients itself toward the camera.
DepthOfFieldQuality
Depth-of-field quality tiers, trading gather taps and cleanup passes for frame time. See DepthOfField.quality.
DirectionalShadowFilter
The sampling pattern used for directional shadow filtering.
EnvironmentVolumeShape
The region shape of an EnvironmentVolumeComponent.
EquirectImageFormat
The container of an equirectangular image, detected from its bytes.
FogMode
How fog density grows with distance from the camera.
GeometryStorage
How a MeshGeometry manages its GPU buffers over its lifetime.
MeshParticleFacing
How a mesh particle orients itself.
MeshVariant
The mesh kind a vertex shader runs on.
PolylineCap
How a PolylineGeometry finishes its two end points.
PolylineWidthMode
How a PolylineGeometry's width is measured.
PostInsertion
Where in the post-processing chain a PostEffect runs.
RenderInput
An engine geometry buffer a CustomRenderPass can request through CustomRenderPass.inputs. Declaring one makes the engine produce it this frame and exposes it on the RenderPassContext, so a pass can read the scene's geometry (depth, normals, shadows), not just its color. Together they turn the custom-pass API into a general depth/shadow-aware post-process system (contact shadows, custom occlusion, volumetrics, and so on).
RenderStage
A named anchor point in the built-in render pipeline where a CustomRenderPass runs. Ordering within one stage follows the order the passes were added.
RibbonAlignment
How a RibbonGeometry orients its strip across the path.
ShaderStage
Which shader a material binds a uniform block or texture against.
ShadowCasterFaces
Which faces of a shadow caster are rendered into the shadow map (the others are culled). Trades the two shadow-map failure modes (self-shadow acne vs peter-panning) against each other.
SkyEnvironmentRefresh
When a SkyEnvironment re-bakes the sky into the scene's lighting.
SpecularAmbientOcclusionMode
How AmbientOcclusionSettings occludes indirect specular reflections.
SplatColorSpace
How a splat file's colors relate to the renderer's linear HDR pipeline.
SplatCropMode
How a crop box filters the splats of a SplatComponent.
SplatFormat
The splat file formats the runtime loader understands.
SpriteBlendMode
Selects how a sprite's color is blended into the scene.
SsrDebugView
A diagnostic visualization for ScreenSpaceReflectionsSettings.debugView.
TextureContent
What a texture's pixels represent, which controls how mip levels are downsampled so the result is correct (color must average in linear light, normals must be averaged as vectors and renormalized).
ToneMappingMode
Tone mapping operator applied when resolving the linear HDR scene color to the display-referred image (see Scene.toneMapping).
UnweldAttribute
The canned per-triangle attributes MeshData.unweld can attach to its output, under the names custom materials read them by.
WidgetInput
How a WidgetComponent receives pointer input.

Mixins

SceneGraph
Defines a common interface for managing a scene graph, allowing the addition and removal of Nodes.

Extensions

QuaternionSlerp on Quaternion
Spherical interpolation helpers on Quaternion.
Vector3Lerp on Vector3
Per-component arithmetic helpers on Vector3.

Constants

kDiffuseShCoefficientCount → const int
Number of L2 spherical-harmonic coefficients used for diffuse irradiance (bands 0..2).
kRenderLayerAll → const int
A layer mask that selects every layer (the default render-view mask).
kRenderLayerDefault → const int
The default layer a Node occupies (bit 0).

Properties

baseShaderLibrary → ShaderLibrary
The shader bundle shipped with flutter_scene.
no setter

Functions

blendEnvironmentVolumes(EnvironmentSettings base, List<EnvironmentVolume> volumes, Vector3 cameraPosition) → EnvironmentSettings
Blends volumes over base for a camera at cameraPosition. A thin wrapper over blendEnvironmentContributions for the manual volume API.
clearSceneTemplateCache() → void
Drops every cached scene template, whatever their outstanding claims.
clearTextureCache() → void
Drops every cached texture, whatever their outstanding claims.
decodeEquirectHdrImage(Uint8List bytes, {int? maxWidth}) → DecodedHdr?
Decodes a high-dynamic-range equirectangular image (EquirectImageFormat.radianceHdr or EquirectImageFormat.openExr) from bytes to linear float pixels, or returns null for a low-dynamic-range image (the caller decodes those with the platform image codec as sRGB).
decodeOpenExr(Uint8List bytes, {int? maxWidth}) → DecodedHdr
Decodes an OpenEXR image from bytes to linear RGBA float pixels (alpha 1), row-major, row 0 at the top (the equirect up pole).
decodeRadianceHdr(Uint8List bytes, {int? maxWidth}) → DecodedHdr
Decodes a Radiance .hdr/.pic RGBE image from bytes.
detectEquirectImageFormat(Uint8List bytes) → EquirectImageFormat
Detects the EquirectImageFormat of bytes from its magic number.
environmentAssetPathOf(EnvironmentMap environment) → String?
The radiance asset path environment was loaded from through EnvironmentMap.fromEquirectImageAsset (or the deprecated fromAssets), or null for environments built another way.
generateSolidColorAtlasPixels({required List<Vector4> tileColors, required int columns, required int tileSize, int padding = 0}) → Uint8List
Builds RGBA8888 pixels (row-major, top-left origin) for a placeholder grid atlas laid out to match a TextureAtlas with the same columns, tileSize, and padding. Each tile's whole cell (content plus padding gutter) is filled with its solid color from tileColors ((r, g, b, a) in [0, 1]), so a tile never bleeds into its neighbor. Cells past tileColors.length are left transparent.
gpuTextureFromAsset(String assetPath) → Future<Texture>
Loads an image from the asset bundle at assetPath and uploads it as a Flutter GPU texture.
gpuTextureFromImage(Image image) → Future<Texture>
Uploads a decoded dart:ui ui.Image to a Flutter GPU texture.
imageFromAsset(String assetPath, {AssetBundle? bundle}) → Future<Image>
Loads and decodes an image from the asset bundle at assetPath.
imageFromBytes(Uint8List bytes, {int? maxWidth}) → Future<Image>
Decodes an encoded image (PNG, JPEG, etc.) from raw bytes.
loadBaseShaderLibrary() → Future<void>
Asynchronously loads and caches the base shader bundle. Idempotent. Called by Scene.initializeStaticResources so the synchronous baseShaderLibrary getter has a cached library to return (shader assets can't be read synchronously on any backend).
loadFmatMaterial(String sourcePath, {String? package, String? bundleName, AssetBundle? bundle, FmatMaterialFactory? factory}) → Future<PreprocessedMaterial>
loadFmatSky(String sourcePath, {String? package, String? bundleName, AssetBundle? bundle}) → Future<PreprocessedSky>
Loads a generated .fmat sky by its source path relative to the owning package's root (for example assets/gradient_sky.fmat).
loadScene(String sourcePath, {String? package, AssetBundle? bundle, FsceneComponentRegistry? registry, SceneReloadCallback? onReload, Scene? applyStageTo}) → Future<Node>
Loads a generated .fsceneb scene by its source path relative to the owning package's root (for example assets/levels/forest.glb).
loadSceneSubtree(Node node, {String? package, AssetBundle? bundle, FsceneComponentRegistry? registry}) → Future<void>
Streams a lazy placeholder node's prefab content under it, resolving the referenced prefab by its source path (the registry-aware counterpart of loadSubtree for scenes loaded with loadScene).
loadTexture(String sourcePath, {String? package, AssetBundle? bundle, TextureSampling? sampling}) → Future<TextureSource>
Loads a cooked compressed texture by its source path relative to the owning package's root (for example assets/shadow_plane.png), ready to assign to a material texture slot.
prefilterEquirectRadiance(Texture sourceEquirect, {bool sourceIsLinear = false, bool mipLayout = false}) → Texture
Prefilters an equirectangular radiance texture for image-based specular lighting.
raycastNode(Node root, Ray ray, {double maxDistance = double.infinity, int layerMask = 0xFFFFFFFF, bool where(Node node)?, bool includeInvisible = false}) → SceneRaycastHit?
Casts ray (direction need not be normalized) through root's subtree and returns the nearest hit, or null.
raycastNodeAll(Node root, Ray ray, {double maxDistance = double.infinity, int layerMask = 0xFFFFFFFF, bool where(Node node)?, bool includeInvisible = false}) → List<SceneRaycastHit>
Casts ray through root's subtree and returns every hit, sorted nearest-first. Parameters as in raycastNode.
releaseScene(String sourcePath, {String? package, AssetBundle? bundle}) → Future<bool>
Releases one claim on the template loadScene built for sourcePath, dropping it from the shared cache when no claims remain.
releaseTexture(String sourcePath, {String? package, AssetBundle? bundle}) → Future<bool>
Releases one claim on the texture loadTexture returned for sourcePath, dropping it from the shared cache when no claims remain.
takeMemoryReport() → MemoryReport
Takes a MemoryReport of what the engine's shared caches are holding.

Typedefs

FmatMaterialFactory = PreprocessedMaterial Function({required Shader fragmentShader, required Map<String, Object?> metadata, Map<String, Shader>? vertexShaders})
Constructs a typed material from one generated .fmat entry.
GltfResourceResolver = Future<Uint8List> Function(String uri)
Resolves an external resource referenced by a multi-file glTF document (a .bin buffer or an image file).
SceneCameraBuilder = Camera Function(Duration elapsed)
Builds a Camera for the current frame from the elapsed time since the view started ticking. Use this for time-based cameras (for example an orbiting view); pass a fixed SceneView.camera instead when the camera does not change over time.
SceneLoadingBuilder = Widget Function(BuildContext context, double progress)
Builds the widget shown while a SceneView waits for its resources to load, given the current load progress (0 to 1). See SceneView.loadingBuilder.
SceneReloadCallback = void Function(Node root)
Called after a hot-reloaded scene has been patched in place (see loadScene), so the app can re-apply per-instance customizations the patch may have discarded: re-apply a custom material, or re-grab inner nodes by name. root is the same root instance the app holds.
SceneTickCallback = void Function(Duration elapsed, double deltaSeconds)
Called once per frame with the total elapsed time and the deltaSeconds since the previous tick. Drive per-frame app logic here, or advance the scene with a supplied timestep via Scene.update (after which Scene.render skips its implicit wall-clock tick for that frame).
SceneViewsBuilder = List<RenderView> Function(Duration elapsed)
Builds the list of RenderViews to render for the current frame from the elapsed time since the view started ticking. Use this for multi-view rendering (split-screen, picture-in-picture); pass a single SceneView.camera or SceneView.cameraBuilder for one view.

Exceptions / Errors

ExrFormatException
Thrown when decodeOpenExr cannot parse the bytes as an OpenEXR image.
HdrFormatException
Thrown when decodeRadianceHdr cannot parse bytes as a supported Radiance HDR image.