Scene class base Scene graph

Represents a 3D scene, which is a collection of nodes that can be rendered onto the screen.

Scene manages the scene graph and handles rendering operations. It contains a root Node that serves as the entry point for all nodes in this Scene, and it provides methods for adding and removing nodes from the scene graph.

Implemented types

Constructors

Scene()

Properties

ambientOcclusion → AmbientOcclusionSettings
Screen-space ambient occlusion settings. Off by default; set AmbientOcclusionSettings.enabled to turn it on. Requires a PerspectiveCamera (the occlusion is reconstructed from the camera's perspective depth); it is skipped for other camera types.
final
antiAliasingMode ↔ AntiAliasingMode
The requested anti-aliasing strategy for this Scene.
getter/setter pair
autoExposure → AutoExposureSettings
Automatic exposure (eye adaptation). Off by default; set AutoExposureSettings.enabled to turn it on. Meters the rendered HDR image on the GPU each frame and eases a correction factor the resolve multiplies with exposure, so exposure stays the artistic base.
final
baseEnvironment ↔ EnvironmentSettings?
The global base look that environmentVolumes blend over.
getter/setter pair
camera ↔ Camera? Rendering
The scene's primary camera.
getter/setter pair
depthOfField → DepthOfField
Depth of field with bokeh. Off by default; set DepthOfField.enabled to turn it on. Requires a PerspectiveCamera (it reconstructs blur from the camera depth prepass, which it forces while enabled); skipped otherwise.
final
directionalLight ↔ DirectionalLight?
A single analytic directional light (e.g. a sun) layered on top of the image-based lighting. Null (the default) means IBL only.
getter/setter pair
effectiveAntiAliasingMode → AntiAliasingMode
The anti-aliasing technique that actually runs when this Scene renders.
no setter
environment ↔ EnvironmentMap?
Transient-uniform allocator, created once and reused every frame. The image-based-lighting environment, or null to use the engine's default (the built-in procedural EnvironmentMap.studio, built lazily on first render).
getter/setter pair
environmentIntensity ↔ double
Scalar multiplier applied to environment's contribution. 1.0 (the default) is neutral.
getter/setter pair
environmentSettings ↔ EnvironmentSettings
The scene's blendable look (image-based lighting, exposure, tone mapping, and post-processing) as a copyable value.
getter/setter pair
environmentTransform ↔ Matrix3
Rotation applied to the image-based-lighting environment when it is sampled. Identity (the default) leaves the environment unrotated.
getter/setter pair
environmentVolumes → List<EnvironmentVolume>
Environment volumes blended over baseEnvironment by camera position, so the look transitions as the camera moves between areas. Ignored when baseEnvironment is null. See EnvironmentVolume.
final
exposure ↔ double
Linear exposure multiplier applied to the HDR scene color before tone mapping. 1.0 (the default) is neutral; see physicalCameraExposure to derive a value from camera settings.
getter/setter pair
filterQuality ↔ FilterQuality
The sampling quality used when compositing screen views onto the canvas. Defaults to ui.FilterQuality.medium.
getter/setter pair
fog → Fog
Distance fog. Off by default; set Fog.enabled and a Fog.mode to turn it on. Applied per-fragment by every material in linear HDR before tone mapping, so it works on any camera type.
final
godRays → GodRaysSettings
Directional volumetric god rays. Off by default; set GodRaysSettings.enabled to turn them on. Requires a shadow-casting DirectionalLight and a PerspectiveCamera (they march the cascaded shadow map against the camera depth); skipped otherwise.
final
hashCode → int
The hash code for this object.
no setterinherited
highlightStyle → HighlightStyle
How the selection outline is drawn around nodes that have a Node.highlightColor. No outline is drawn when no node is highlighted.
final
postProcess → PostProcessSettings
Built-in post-processing settings, such as color grading. Every effect is off by default.
final
renderPasses → List<CustomRenderPass> Rendering
The custom render passes inserted into the pipeline, in the order they were added. Use addRenderPass / removeRenderPass to change the set.
no setter
renderScale ↔ double
Scales the resolution screen views render at, relative to the display's native resolution. Defaults to 1.0.
getter/setter pair
renderScene → RenderScene
The flat list of drawable items the render passes iterate.
final
root → Node
The root Node of the scene graph.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
screenSpaceReflections → ScreenSpaceReflectionsSettings
Screen-space reflection settings. Off by default; set ScreenSpaceReflectionsSettings.enabled to turn it on. Requires a PerspectiveCamera (the reflection trace is reconstructed from the camera's perspective depth); it is skipped for other camera types.
final
skybox ↔ Skybox?
The visible background drawn behind the scene, or null (the default) to clear to transparent.
getter/setter pair
skyEnvironment ↔ SkyEnvironment?
Drives environment from a sky on a refresh policy, or null (the default) to leave environment caller-managed.
getter/setter pair
sunLight ↔ SunLight?
Aims directionalLight at a sky's sun so cast shadows track the sky.
getter/setter pair
surface → Surface
Handles the creation and management of render targets for this Scene.
final
toneMapping ↔ ToneMappingMode
Tone mapping operator used when resolving the HDR scene color to the display image. Defaults to ToneMappingMode.pbrNeutral.
getter/setter pair
views → List<RenderView>
Views this scene owns and renders every frame, in addition to the views passed to each renderViews call.
final

Methods

add(Node child) → void
Add a child node.
override
addAll(Iterable<Node> children) → void
Add a list of child nodes.
override
addMesh(Mesh mesh) → void
Add a mesh as a child node.
override
addRenderPass(CustomRenderPass pass) → void Rendering
Inserts pass into the render pipeline at its CustomRenderPass.stage. Passes at the same stage run in the order they were added. Adding the same pass twice is a no-op.
loadEnvironment(String assetPath, {bool showSkybox = true, double skyBlur = 0.0, double? intensity, double? exposure, double? rotationY, int maxWidth = 4096, AssetBundle? bundle}) → Future<void>
Loads an equirectangular image (EnvironmentMap.fromEquirectImageAsset, so Radiance .hdr, OpenEXR .exr, or a standard sRGB image), lights the scene with it, and (when showSkybox) shows it as the skybox. A one-call setup so environment and skybox cannot drift apart.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
raycast(Ray ray, {double maxDistance = double.infinity, int layerMask = 0xFFFFFFFF, bool where(Node node)?, bool includeInvisible = false}) → SceneRaycastHit?
Casts ray through the scene's render geometry and returns the nearest hit, or null.
raycastAll(Ray ray, {double maxDistance = double.infinity, int layerMask = 0xFFFFFFFF, bool where(Node node)?, bool includeInvisible = false}) → List<SceneRaycastHit>
Casts ray through the scene's render geometry and returns every hit, sorted nearest-first. Parameters as in raycast.
remove(Node child) → void
Remove a child node.
override
removeAll() → void
Remove all children nodes.
override
removeRenderPass(CustomRenderPass pass) → bool Rendering
Removes a previously addRenderPassed pass. Returns whether it was present.
render(Camera camera, Canvas canvas, {Rect? viewport, double? pixelRatio}) → void
Renders camera's view of this scene onto canvas.
renderViews(List<RenderView> views, Canvas canvas, {Rect? region, double? pixelRatio}) → void
Renders a list of views of this scene onto canvas.
toString() → String
A string representation of this object.
inherited
update(double deltaSeconds) → void
Advances the scene by deltaSeconds: ticks every node's components and animation players, and refreshes the flat render layer.
warmUp(List<RenderView> views) → Future<void> Assets and loading
Compiles the render pipelines and uploads the GPU resources this scene needs, by encoding one frame offscreen and discarding it, so the first visible frame does not stall while shaders compile or textures upload.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

isReadyToRender → bool Assets and loading
Whether the engine's shared static resources (the base shader library and the material BRDF lookup table) have finished loading, so any scene can render this frame.
no setter

Static Methods

advancePhysics({required PhysicsWorld world, required void fixedUpdateWalk(double deltaSeconds), required double accumulator, required double frameDt}) → double
Fixed-step substepping driver. Adds frameDt to accumulator, takes up to PhysicsWorld.maxSubsteps fixed steps to consume it (walking fixedUpdateWalk then world.step each step), drops leftover time when the renderer falls far behind, and finishes by calling world.interpolateTransforms with the residual fraction.
initializeStaticResources() → Future<void>
Prepares the rendering resources, such as textures and shaders, that are used to display models in this Scene.
isAntiAliasingModeSupported(AntiAliasingMode mode) → bool
Whether mode is supported by the active Flutter GPU backend.
physicalCameraExposure({required double aperture, required double shutterSpeed, required double iso}) → double
Computes the linear exposure multiplier for a physical pinhole camera, the way photographers reason about it: aperture (f-stops), shutterSpeed (seconds), and sensor iso.