
# The debug tab

The starter adds a tab, "Scenes", to [the debug panel](../spring-boot-starter-flutter/debug-panel.md) 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:

```yaml
# 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**: its state, the time of its start, the mode the scenes draw in and the conditions of `spring.flutter.scene.when` with what each sees, whether the web page is cross-origin isolated, the steps of the start in words.
- **Every scene on the screen by its name**: frames a second against those it may draw, why it stands still, the surface, the engine's numbers of its last frame (draw calls, vertices, programs bound and built in the frame), each pass with its time on the page's thread.
- **Every model by its name**: its file, size, time to read and to import, what it is made of, and a switch that hides it everywhere: the frame's numbers with and without it are what it costs.
- **Every material by its name**: its file, how it is lit and whether it is blended, its parameters, how long its first load took and whether with the splash or while the app ran, its precision, its uses on the screen by scene, and the same switch. Each scene's own rows say which materials it draws with.
- **Memory**: what the engine's caches hold.

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](speed.md#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](engine-notes.md#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](materials.md#precision-what-a-phone-draws-differently)) |
| | 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](../spring-boot-starter-flutter/debug-panel.md#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

- [The debug panel](../spring-boot-starter-flutter/debug-panel.md)
- [The engine's log](engine-log.md)
- [What a scene costs](cost.md)
- [Speed on phones](speed.md)
- [The frame meter](../spring-boot-starter-flutter/frame-meter.md)
- [Modules left out of the build](../spring-core-dart-generator/optimizations/build-conditions.md)
