API Reference · Diagnostics

Diagnostics.FrameTrace

Namespace: Ava3D.Diagnostics

public sealed class Diagnostics.FrameTrace

A bounded record of recent frames, for the questions RenderInfo's averages cannot answer.

RenderInfo says what a frame costs on average. This says what each one cost, on which thread, and what happened to make it cost that — so a stutter every four seconds can be found rather than inferred, and a scene's load can be read as uploads per frame instead of as a feeling. Set Ava3DView.Trace to one, or run with AVA3D_TRACE=frames.json and it is written on exit. FrameTrace.Export writes a file Perfetto opens; FrameTrace.Frames is the same data for code.

What it costs. A record is a struct written into a preallocated ring under a lock, so a frame pays a few hundred nanoseconds and allocates nothing; the ring keeps the last FrameTrace.Capacity frames and forgets the rest. The reason strings are made once per combination.

Which thread writes what. The render thread records the frame when it publishes its report. The UI thread reports each snapshot's preparation as it builds it, keyed by snapshot, and the first frame to draw that snapshot takes the figure. GPU times are read a frame or two after the render and back-filled onto the frame they belong to. FrameTrace.Mark can be called from anywhere.

Constructors

MemberDescription
Diagnostics.FrameTrace(int capacity = 2000)

A trace holding the last capacity frames and as many markers.

Properties

MemberDescription
int Capacity { get; }

How many frames are kept before the oldest is forgotten.

IReadOnlyList<Diagnostics.FrameRecord> Frames { get; }

The frames recorded so far, oldest first, as a copy taken under the lock. Reading it allocates — a record per frame and a small array per record — so it is for after the run, not during it.

Fields

MemberDescription
static string CsvHeader

The CSV columns, in order: FrameRecord's fields with the passes and size unpacked.

static int DefaultCapacity

Frames kept when the constructor is not told otherwise — about a minute at sixty.

Methods

MemberDescription
void Export(IO.Stream stream, Diagnostics.TraceFormat format)

Writes every frame and marker held right now. See TraceFormat.

IDisposable Mark(string name)

A span of the caller's own — "deck build", "level load" — recorded on the calling thread when it is disposed, against whichever frame the render thread had most recently recorded. Thread-safe.

See also