Byte Engine Docs

Inspector and metrics

Look up what the engine's metrics measure and how they're named and serialized, the messages the inspector accepts, how a screenshot is selected and encoded, and the inspector's limits.

Every headed application serves an HTTP inspector on loopback while it runs. Its routes, parameters, and status codes are specified by the HTTP API in the API section; this page specifies what the data means. To read metrics while measuring a change, follow Measure performance.

Metrics

RuleValue
Retained ticksThe latest 1,024.
Distinct metrics128. Further metrics warn once and go unreported.
TickZero-based, counted after each tick.
FrameZero-based, counted when a frame starts; a tick that didn't render has none. The same number names the frame in a screenshot's response.
PresentedWhether any window held an acquired swapchain image in that frame.
Time and deltaWall-clock milliseconds since the application started, at the tick's end, and the frame delta the clock advanced by.
Time to first frameThe time of the first presented tick.
CPU metricThe sum of every span with that name, on every thread, during the tick.
GPU metricA GPU counter's duration in the frame the tick submitted, filled in once the frame completes and dropped if its tick has left the ring.
UnitMilliseconds.
NameMeasures
frameEvery command of a frame on the GPU.
scene.<pipeline>One scene pipeline's commands on one sink.
pass.<name>One post-scene pass's own commands, without bypass copies, clears, or discards.
stage.<name>A GPU counter a pass declares, nested in its node, such as the visibility pipeline's stages.
@<sink> suffixThe sink index when it isn't the first, as in pass.bloom@2.
CPU spansThe application's tick and its phases, the renderer's preparation and recording phases, and audio rendering.

A tick's row lists only what that tick measured: the tick, the frame or null, the time, the delta, the presented flag, and a CPU and a GPU map from name to milliseconds. A summary over a range of ticks holds the tick count, the first and last tick, the presented tick count, the time to first frame, delta statistics, and, per metric, its kind, count, mean, minimum, maximum, and the 50th, 95th, and 99th percentiles by nearest rank. The metrics-out parameter writes the summary as JSON, or every retained row as NDJSON when the path ends in .ndjson.

Entities and messages

The entity query lists every factory-created handle with its types and the name and position the inspector has observed since it started. It filters by exact type or name.

MessagePayloadEffect
TransformationUpdateA complete transform: position and scale as three numbers, orientation as four.Moves the entity.
Delete, DestroyNull.Deletes and retires the entity.
TriggerActionAn input value tagged by its kind, such as a float.Publishes an action event as if from a device. The target is the action's handle, found by name in the entity query.

The message type catalog describes each payload's shape with a small vocabulary: null, boolean, string, integer, number, array, tuple, object, optional, map, result, enum, any, recursive, and unknown.

Configuration

The configuration route lists every runtime setting update with its parameter, the requested value, and its state: pending until the pass it targets is installed, set with the value in effect, or not set with the reason.

Screenshots

SelectionCaptures
A sink aloneThe swapchain after every pass.
A targetThat target after every scene pipeline and before the post-scene passes. The name must be one a scene node writes or a history target.
A target from the previous frameThe previous frame's copy of a history target.
A pass and a targetThe target right after that pass; the name must be one the pass wrote.
RuleValue
FormatsPNG with HDR clamped, from 8-bit, 16-bit, half-float, and the packed scene formats; EXR, lossless; raw bytes with their row pitch.
Captures per request1 to 16.
Queue8 pending requests; further ones are refused.
Timeout5 s.
Rendering on demandA request wakes the loop so a frame renders.
Response headersThe frame, sink, format, width, height, and, for raw captures, the bytes per row.

Rust API

On this page