Import these from @grafloria/renderer.
Functions
formatSnapshot
Format a snapshot for a human.
Deliberately calls out the ratios that reveal a bug rather than just printing numbers: "culled 0/10000" reads as fine until you notice it means nothing was culled. The HUD's job is to make that impossible to miss.
tsfunction formatSnapshot(s: PerfSnapshot): string[]
Classes
PerfHud
A DOM overlay, framework-free.
Absolutely positioned, pointer-events: none — a debug HUD that eats clicks is a
bug generator of its own. It is opt-in and never mounted unless asked for.
tsclass PerfHud
Methods
constructor(private readonly host: HTMLElement)show(): voidupdate(snapshot: PerfSnapshot): voidhide(): void
QualityGovernor
tsclass QualityGovernor
Methods
constructor(options: GovernorOptions = {})record(frameMs: number): QualityBias— Feed the governor one frame time (ms). Returns the bias to render the NEXT frame at.getBias(): QualityBias— The bias to apply right now.getState(): GovernorStateeffectiveTier(zoomTier: string, tiers: readonly string[]): string— Apply the bias to a zoom-derived tier.
tiers must be ordered richest → poorest, which is the order the LOD config
declares them in. The governor can only ever make the picture SIMPLER than the
zoom asked for — never richer. A governor that could upgrade detail beyond what
the zoom wants would draw labels on 4px nodes to fill spare budget, which is
not a feature.
reset(): void— Forget everything — e.g. after a diagram swap, where past frames say nothing.
Constants
EMPTY_SNAPSHOT
tsconst EMPTY_SNAPSHOT: PerfSnapshot
Interfaces
GovernorOptions
tsinterface GovernorOptions
Properties
| Name | Type | Default | Description |
|---|---|---|---|
budgetMs? | number | The frame budget. 16.7ms = 60fps. | |
downFactor? | number | Step DOWN when the median frame exceeds budget × this. Default 1.0 — the budget IS the line; there is no point having a budget you are content to miss. | |
upFactor? | number | Step UP only when the median frame is below budget × this. Default 0.55 — the DEAD BAND. A tier that renders at 0.9× budget is doing its job; restoring detail would put us straight back over it, which is the oscillation this exists to prevent. | |
window? | number | Frames in the rolling window. | |
recoveryWindows? | number | Consecutive fast windows required before restoring a tier. Recovery is patient. | |
maxBias? | QualityBias | Worst tier the governor may impose. | |
panicFactor? | number | ESCALATION. A frame this many times over budget is not a slow frame, it is a structurally wrong one — and waiting a full window to notice means 12 frames of a visibly locked-up canvas. Default 4× (≈67ms: a third of a second of these and the user is already reaching for the tab close button). | |
panicWindow? | number | How many frames the escalation path looks at. THREE, NOT ONE — and that is the whole subtlety. Reacting to a single catastrophic frame would make one GC pause indistinguishable from a scene the machine genuinely cannot draw. A median over three still rejects a lone spike (two of the three must be bad for the median to be bad) while reacting 4× sooner than the main window. |
GovernorState
tsinterface GovernorState
Properties
| Name | Type | Default | Description |
|---|---|---|---|
bias | QualityBias | ||
medianMs | number | Median frame time over the window — what the decision is actually made on. | |
samples | number | Frames recorded so far in the current window. | |
recoveryStreak | number | Consecutive fast windows accumulated toward a step back up. | |
lastDecision | 'steady' | 'stepped-down' | 'stepped-up' | 'escalated' | Why the governor last changed its mind — surfaced in the HUD, because an invisible governor is indistinguishable from a bug. |
PerfSnapshot
tsinterface PerfSnapshot
Properties
| Name | Type | Default | Description |
|---|---|---|---|
fps | number | Rolling FPS. | |
frameMs | number | Last frame, ms. | |
nodes | number | Entities in the model. | |
links | number | ||
visibleNodes | number | Entities that survived viewport culling — i.e. what we actually paid for. | |
visibleLinks | number | ||
mountedViews | number | Entities whose views exist in the DOM right now. | |
dirtyNodes | number | Entities re-rendered this frame. | |
dirtyLinks | number | ||
routedLinks | number | Links whose route was recomputed this frame. Should be ~0 on an idle frame. | |
tier | string | The LOD tier actually rendered, and the governor's reasoning. | |
governor? | GovernorState |
Types
QualityBias
How many tiers below the zoom-derived one we are currently rendering.
tstype QualityBias = 0 | 1 | 2;
Members
toString(radix?: number): string— Returns a string representation of an object.toFixed(fractionDigits?: number): string— Returns a string representing a number in fixed-point notation.toExponential(fractionDigits?: number): string— Returns a string containing a number represented in exponential notation.toPrecision(precision?: number): string— Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.valueOf(): number— Returns the primitive value of the specified object.toLocaleString(locales?: string | string[], options?: Intl.NumberFormatOptions): string— Converts a number to a string by using the current or specified locale.
Was this page helpful?