flutter3d
Showcase Changelog 62 packages API reference

Debug views and render stats

since 1.0.0-rc.1 Post-processing

When a surface looks wrong, the lit picture rarely says why. The albedo may be too bright, a metalness map may have been read as sRGB, or a seam may run through the UVs. RenderSettings.debugView shows one material channel in place of the light, over all of the frame or the right part of it, so the lit picture and the channel can be compared in a single frame. The frame then says what it cost: draws, triangles, the bytes its targets hold, and the same numbers pass by pass.

Step 1: The channels #

There are eight channels besides DebugView.off. Albedo is the base colour after its texture and tint. Normal is the shading normal after the normal map, as n · 0.5 + 0.5 in world space. Roughness, metalness and occlusion are greys. Emission is its own colour, clipped at one. UV is the base map's coordinate in red and green, so a seam shows as a step in colour. nonFinite is magenta wherever the light came out NaN or infinite, and a dark grey of the light's brightness everywhere else.

/// Every channel there is, in the order the page steps through them.
static const List<DebugView> _channels = <DebugView>[
  DebugView.albedo,
  DebugView.normal,
  DebugView.roughness,
  DebugView.metallic,
  DebugView.occlusion,
  DebugView.emissive,
  DebugView.uv,
  DebugView.nonFinite,
];

The stage has one thing that gives off light, so the emission channel has something to show.

// Something that gives off light, so the emission channel has more to
// show than black.
final MeshNode lantern = MeshNode(
  DeviceMesh.upload(
    context.device,
    CuboidShape(size: Vector3.all(0.4)).build(),
  ),
  RenderMaterial(
    name: 'lantern',
    baseColor: LinearColor.fromSrgb(0.2, 0.2, 0.2, 1.0),
    emissive: LinearColor(0.3, 0.9, 0.5),
    emissiveStrength: 2.0 * RenderMaterial.defaultEmissiveStrength,
  ),
  name: 'lantern',
)..setPosition(0.0, 0.2, 1.6);

Step 2: Wipe between the light and a channel #

DebugViewSettings takes the channel and a split, the share of the width left lit. Nought shows the channel over the whole frame; a half keeps the left half lit. The materials write the channel themselves, before they write their light, so it shows what the maps did rather than what a buffer kept. The composite leaves the debug side out of the exposure, the tone curve, the bloom and the grade.

_debug = DebugViewSettings(view: _channels[channel], split: split);

Drag Split to move the wipe, or leave Step through the channels on and the page moves to the next channel every two seconds.

Step 3: What the frame cost #

FrameResult has the totals: drawCalls, triangles, instances and pipelineSwitches. FrameResult.passes has the same numbers for each pass of the frame graph, plus its CPU time and its GPU time where the device measures it. targetBytes counts every texture the frame drew into or read from, each once: its base level, every slice and every sample. textureBytes is how a single texture is counted, so a caller can count its own.

The page checks that the pass costs add up to the frame's totals, that the composite is a single draw, and that the targets hold at least as many bytes as the picture handed back. The scene's own colour target is that large on its own.

final FramePass scenePass = frame.passes.firstWhere(
  (FramePass p) => p.name == 'scene',
);
final FramePass composite = frame.passes.firstWhere(
  (FramePass p) => p.name == 'composite',
);
final int passDraws = frame.passes.fold<int>(
  0,
  (int total, FramePass p) => total + p.drawCalls,
);
// The scene pass drew the five meshes' triangles, and the composite,
// which passes the debug side through untoned, is one triangle's draw.
if (scenePass.drawCalls < 5 ||
    scenePass.triangles <= 0 ||
    composite.drawCalls != 1 ||
    passDraws != frame.drawCalls ||
    frame.triangles < scenePass.triangles) {
  throw StateError('the pass costs do not add up to the frame');
}
// The scene's own colour target alone is at least as large as the
// eight-bit picture handed back, so the targets cannot hold less.
if (frame.targetBytes < textureBytes(frame.frame)) {
  throw StateError(
    'the targets hold ${frame.targetBytes} bytes, less than the picture',
  );
}

Note. Only lit materials write a channel. The sky, particles, splats and glass's own pass draw as they always do, and on the debug side they reach the screen without the tone curve, so they look brighter there. Reflections, depth of field, motion blur and a temporal resolve still run over the channel, so turn them off for a clean reading. targetBytes does not count mip chains. Whether Metal, compiled with fast math, keeps the NaN comparison has not been checked. The page's own check reads the counters, not the pixels: the split picture is held by the debug-view-split reference images on all four backends.