Debug views and render stats
Open the live demo · Read the source · View on GitHub
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.
targetBytesdoes 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 thedebug-view-splitreference images on all four backends.