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

adaptiveRenderScale → double Rendering
The multiplier the adaptive controller currently applies on top of renderScale; 1.0 unless RenderQualitySettings.adaptive has stepped it down.
no setter
agxContrast ↔ double
AgX curve contrast. Only used by ToneMappingMode.agx.
getter/setter pair
agxWhite ↔ double
AgX reference white. Only used by ToneMappingMode.agx.
getter/setter pair
ambientOcclusion → AmbientOcclusionSettings
Screen-space ambient occlusion settings. Off by default; set AmbientOcclusionSettings.enabled to turn it on. Works with perspective and orthographic cameras.
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
coplanarTieBreak ↔ bool
Whether exactly coplanar surfaces of different materials resolve to a stable winner instead of flickering (z-fighting).
getter/setter pair
debug → SceneDebugSettings Rendering
Surface debug views: show a resolved material channel, a geometry attribute, an identity color, or a validation flag in place of the lit result, optionally split against it, plus overlays such as wireframe.
final
debugCheckCoplanarOverlaps ↔ bool
Whether a debug build checks the scene for surfaces that overlap in one plane once it has held still for a moment, and prints what it finds (see findCoplanarOverlaps). The check runs a couple of milliseconds per frame until it is through the scene, and again whenever nodes are added or removed. Debug builds only; defaults to true.
getter/setter pair
debugLastPlanarCapturePasses ↔ List<PlanarReflectionCapturePass>
The planar reflection capture passes built for the most recent capturing view, for tests that assert graph composition. Empty when no reflector captured.
getter/setter pair
debugViewId ↔ String Rendering
The id of the active surface debug view in DebugViewRegistry, or none. Setting an unknown id throws an ArgumentError.
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 camera depth); 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
effectiveRenderQualityTier → RenderQualityTier Rendering
The quality tier in effect: RenderQualitySettings.tier (or the platform default), lowered by any steps the adaptive controller took.
no setter
effectiveSceneColorCaptureBatches → int Rendering
The capture budget in effect, sceneColorCaptureBatches clamped, or the tier's default when it is null.
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
fitNearPlane ↔ bool
Whether perspective views rasterize with a near plane fitted to the content they draw, each frame.
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
globalIllumination → GlobalIlluminationSettings
World-space global illumination settings. Off by default; set GlobalIlluminationSettings.enabled to turn the irradiance field on. Works with perspective and orthographic cameras, and forces the depth prepass with normals on.
final
globalIlluminationProbeGrid → IrradianceProbeGrid? Lighting and environment
The probe lattice the global-illumination field is filling this frame, or null when the field is off or has not run a frame yet.
no setter
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
maxGpuFramesInFlight ↔ int Rendering
How many frames of GPU work may be outstanding before a screen view presents its previous image again instead of encoding a new frame.
getter/setter pair
pacedFrameCount → int Rendering
Frames a screen view has presented from its previous image because the GPU was maxGpuFramesInFlight frames behind. A diagnostic counter.
no setter
postProcess → PostProcessSettings
Built-in post-processing settings, such as color grading. Every effect is off by default.
final
punctualLightClustering ↔ bool Lighting and environment
Whether punctual lights shade through per-view froxel clustering (the view frustum subdivided into screen tiles and depth slices, each shading only the lights that reach it) instead of per-object light lists. On by default for perspective and orthographic views; frames using light channel masks fall back to the per-object path. Clustering removes the per-object light cap, so a large mesh reached by many lights shades them all. Disable to compare, or to force the per-object path.
getter/setter pair
punctualLightOverflowCount → int Lighting and environment
How many drawable items (or, under clustered lighting, screen froxels) dropped punctual lights last frame because more lights reached them than the per-slice budget can shade. Zero when everything fit. A persistent nonzero value means light ranges need authoring (an unranged light reaches everything) or large meshes need splitting.
no setter
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
renderQuality → RenderQualitySettings Rendering
Where this scene's automatic settings sit on the quality ladder, and whether the renderer may lower them itself when frames overrun a target. See RenderQualitySettings; effectiveRenderQualityTier and adaptiveRenderScale report what is in effect.
final
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
renderStats → RenderStats Debugging and profiling
Steady-state rendering statistics: the last frame's draw, culling, batching, and pipeline counters broken down by view and by pass, with CPU times, plus a bounded history. Always collected.
final
repaintRequested → Listenable Rendering
Notifies when the scene wants painting again outside any repaint the app drives: a screen view held its previous image because the GPU was maxGpuFramesInFlight frames behind, and that work has now finished. SceneView listens. A custom painter that repaints only on demand should pass this as its repaint, or the held frame never shows.
no setter
reversedDepth ↔ bool
Whether camera passes store depth reversed, 1 at the near plane and 0 at the far plane.
getter/setter pair
root → Node
The root Node of the scene graph.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
sceneColorCaptureBatches ↔ int? Rendering
How many overlap-safe scene color captures a frame may open for materials that read the opaque scene behind them (transmission), from 1 to maxSceneColorCaptureBatches. Readers whose screen bounds overlap each get a fresh capture of everything drawn before them, and each capture is a full-resolution copy plus a new render pass. Once the cap is reached the remaining readers share the last snapshot, so they stop seeing each other through glass. Null (the default) follows effectiveRenderQualityTier: the full budget on high, two on medium, one on low (every reader shares one capture, the cost of a single reader). See effectiveSceneColorCaptureBatches.
getter/setter pair
screenDistortion → ScreenDistortionSettings
Parametric radial screen distortion pulses. Off by default; set ScreenDistortionSettings.enabled and add a DistortionPulse to turn it on. Runs on the display-referred image after tone mapping.
final
screenSpaceReflections → ScreenSpaceReflectionsSettings
Screen-space reflection settings. Off by default; set ScreenSpaceReflectionsSettings.enabled to turn it on. Works with perspective and orthographic cameras.
final
shadowCasterOverflowCount → int Lighting and environment
How many lights asked to cast a shadow last frame but got no slot in the shared shadow atlas, which caps shadow-casting spots and point lights separately (see kMaxSpotShadows and kMaxPointShadows).
no setter
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
smaa → SmaaSettings
SMAA quality settings. Active when antiAliasingMode is AntiAliasingMode.smaa.
final
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
temporalAntiAliasing → TemporalAntiAliasingSettings
Temporal anti-aliasing settings. Active when antiAliasingMode is AntiAliasingMode.taa.
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.
addTickListener(SceneTickListener listener) → void
Registers listener to run at the start of every tick and before every fixed step, ahead of all components. Listeners run in the order added.
bakeIrradianceField({int faceResolution = 16, int probesPerStep = 8, int layerMask = 0xFFFFFFFF}) → IrradianceFieldBakeStepper Lighting and environment
Bakes the irradiance field by rendering the scene from every probe in the active volume.
captureEnvironment({required Vector3 position, int faceResolution = 128, int equirectWidth = 512, int layerMask = 0xFFFFFFFF}) → EnvironmentMap Lighting and environment
Captures the scene's linear HDR lighting at position into a new EnvironmentMap: renders the scene into six cube faces (with shadows and analytic lights, without screen-space effects or post-processing), then prefilters the result like any other environment.
captureRenderGraph({int viewIndex = 0, RenderGraphCaptureRequest request = const RenderGraphCaptureRequest(), Duration timeout = const Duration(seconds: 5)}) → Future<RenderGraphCaptureResult> Rendering
Captures the next rendered frame of screen view viewIndex: the pass list with CPU timings, the blackboard data flow, and (per request) GPU copies of the textures each pass wrote. Resolves after that frame's graph executes; the caller must ensure a frame renders (schedule one).
debugFittedNearPlane([int viewIndex = 0]) → double?
The near plane screen view viewIndex last rasterized with under fitNearPlane, or null before its first frame.
findCoplanarOverlaps({Camera? camera}) → List<CoplanarOverlap>
Finds surfaces that overlap in one plane and so flicker against each other (z-fighting), from the scene's geometry, without rendering.
invalidateGlobalIllumination() → void
Discards the accumulated irradiance field so it refills from scratch, for a hard camera cut or a wholesale lighting change that should not converge in over the hysteresis tail.
isShadowCasterGranted(Object lightComponent) → bool Lighting and environment
Whether lightComponent (a SpotLightComponent or PointLightComponent) held a shadow slot last frame.
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
probeDepthConflicts({Camera? camera, int width = 960, int height = 540, int layerMask = kRenderLayerAll, int minPixels = 4}) → Future<DepthConflictReport>
Finds the surfaces that flicker against each other (z-fighting) in camera's view, and reports them by node.
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.
removeTickListener(SceneTickListener listener) → bool
Unregisters listener. Returns whether it was registered.
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, {bool includeOffscreen = false, Duration? sliceBudget}) → 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

debugAllowRenderGraphCapture ↔ bool Rendering
Opt-in for captureRenderGraph and the render-graph debug hooks. False (the shipping default) keeps the capture branch tree-shakeable; an editor or debugging host sets it at startup.
getter/setter pair
isReadyToRender → bool Assets and loading
Whether the engine's shared shader libraries and material lookup resources 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.
debugEmptyFrameDiagnosis({required bool warned, required bool drewSomething, required bool regionEmpty, required bool noViews, required bool noScreenViews, required int meshCount, required int visibleMeshCount, required bool anyLayerMaskZero, required List<int> screenViewMasks, required int visibleLayersUnion}) → ({String? message, bool warned})
Diagnoses a frame that issued zero draw calls, for renderViews.
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.
preload({bool physicalMaterials = true, bool smaa = false}) → Future<void> Assets and loading
Loads engine resources that otherwise load the first time something needs them, along with initializeStaticResources, so a loading screen absorbs the cost.