The debug tab

The starter adds a tab, "Scenes", to the debug panel of the Flutter starter: the engine, every scene on the screen and every model by its name, with what each costs.

Why

"Is the scene slow, or the page?" and "what does this model cost?" are questions for a running app, on the device. The tab answers them by name: the names are the name of each SpringSceneView and the names of spring.flutter.scene.models and spring.flutter.scene.materials.

Example

Nothing to write in a debug build: the tab is there, and ⌘⇧D (Ctrl+Shift+D elsewhere) opens the panel. To have it in every build:

# lib/resources/application.yml
spring:
  flutter:
    debug:
      enabled: true          # the debug panel in every build
    scene:
      debug:
        enabled: true        # the scenes' tab; not set: debug and profile builds

What it shows

The engine gives no time on the GPU, and nothing per model: a model's cost is seen by hiding it.

The rows

Part Row What it says
Engine Backend The engine's name: flutter_scene
State idle, starting, ready or failed
Start How long the start took
Failure What the start threw, when it failed
Render The mode the scenes draw in now, with the conditions that changed it (still (touch), a warning), and the ceiling on frames
When <name> One row per condition (touch, slow, the app's own): what it sees, and what it does. a touch screen: still (it holds, a warning), a mouse or none (still when it holds), a touch screen: not followed (when does not name it). For slow: measuring the first scenes (12 of 24 frames), then the middle beat against half of slow.frame-time (3.1 ms a beat of the scenes, of 8.0 ms), with holds when no scene moves once slow beats marked it. See Drawing less where it costs too much
Page isolated On the web: whether Flutter draws in a worker or on the page's thread
Frames On the web: how the engine's frames reach Flutter: premultiplied, or without premultiplied alpha where the browser (WebKit) divides a frame of WebGL by its alpha (Safari: a frame of WebGL and its alpha)
The steps Every step of the start so far, in words
Scenes on the screen Frames The frames drawn in the last second against those the view may draw, or "a still frame" with the reason
Surface The size of the surface in pixels, and the view's own pixel ratio
Frame The time on the page's thread, the draw calls and the vertices of the last frame
Programs Programs bound, and programs built in the frame
Items Items considered, culled, and instances
Materials The materials the scene draws with, and how many times
The passes Each pass with its time and its draw calls
Models Source Where the file is, as the properties say
State idle, loading, ready or failed, and eager or lazy
File The size of the file
Load The time to read and to import
Made of Nodes, meshes, draw calls a use, materials
Materials Source The .fmat file, as the properties say
State idle, loading, ready or failed, and eager or lazy
Shading How it is lit (unlit, lit, ...), and opaque or blended
Precision highp (float32 everywhere) or mediump with the places written highp: half precision on phones, float32 on a desktop; mediump with none is a warning (Precision)
Load How long the first load took, with the splash or while the app ran; longer than a frame while the app ran (its scene waited for it) is a warning to preload it
Used Its uses on the screen, by scene: match-header x2
Parameters The names of its parameters
Memory What each of the engine's caches holds, and the total

A view stands still for one of three reasons: still (the properties, or a condition of spring.flutter.scene.when), motion (the system asks for less) or off-screen.

The numbers are read twice a second, so the panel does not redraw the page for every frame of a scene.

When the tab is in the app

spring.flutter.scene.debug.enabled is read by the generator when it writes main.spring.dart, as the debug panel's own property is:

Value The tab
not set (the default) In debug and profile builds only; a release build compiles it away
true In every build, release included
false In no build: the app has none of its code

The tab shows where the debug panel is in the build (spring.flutter.debug.enabled). Set to false in a profile file, the property also turns the tab off in a running app whose build has it. See When a module is in the app.

The beans

Bean Type What it is
sceneDebugSection SceneDebugSection, a DebugPanelSection The tab
sceneDebug SceneDebug, a SceneViewObserver The views on the screen: views, each with its name, state, framesPerSecond, frameCount, lastFrame and stats

Without these beans (a release build) nothing is measured.

See also