lib/display-refresh
The refresh rate of the display a page is shown on, measured from its animation frames, and the frame rate a stream matching it runs at.
A stream whose rate differs from the display's even slightly drifts against
its refresh: at 60 frames per second on a display refreshing at 59.94, one
frame in a thousand has no refresh of its own and is never shown, a skip
every 17 s, and a stream slower than its display shows a frame twice as
often. Matched, every frame lands on a refresh of its own. No web API names
the refresh rate, so the page measures it: the timestamps
requestAnimationFrame hands a callback fall on the display's refreshes, a
frame the page was too busy for costing a whole refresh, so a straight line
through them against the count of refreshes has the refresh period for its
slope, finer than the timer's resolution. The median of the short intervals
(those near the tenth percentile, which a page busy for most of its frames
still leaves at one refresh) sets the refresh count of each step for a first
fit, whose period sets it for the second; an interval off that cadence or
longer than GAP_MS (a page hidden or throttled meanwhile) starts a new run
of the fit, and frames mostly off any cadence measure nothing. The fit
stands once its standard error is within PRECISION of the period, a tenth
of the step between 60 and 59.94.
A measurement within 0.1% of a whole number or of an NTSC rate (N * 1000 / 1001, 59.94 being 60000/1001) is that rate exactly, since displays run at those and the measurement's own error is smaller; any other is kept to a hundredth of a frame per second. The server carries the rate as the fraction it names down to every encoder.
The display is measured for two seconds, longer where the frames are too
rough for the fit to stand by then (up to MAX_MEASURE_MS), when the page
loads, again whenever the page becomes visible, and whenever the window may
have moved to another display: its device pixel ratio or, where the engine
reports it, its screen changed, or it entered or left full screen.
Variables
FRAMERATE_DISPLAY
const FRAMERATE_DISPLAY: "display" = 'display';Defined in: lib/display-refresh.js:44
The stored frame rate that asks for the display's own.
GAP_MS
const GAP_MS: 250 = 250;Defined in: lib/display-refresh.js:47
An interval at least this long is a gap in the frames, not a refresh, in ms.
MIN_FRAMES
const MIN_FRAMES: 30 = 30;Defined in: lib/display-refresh.js:49
The fewest refreshes a measurement stands on.
SNAP_TOLERANCE
const SNAP_TOLERANCE: 0.001 = 0.001;Defined in: lib/display-refresh.js:51
How far a measurement may lie from a standard rate and be it, as a share of it.
MEASURE_MS
const MEASURE_MS: 2000 = 2000;Defined in: lib/display-refresh.js:53
How long one measurement collects frames for at least, and at most, in ms.
MAX_MEASURE_MS
const MAX_MEASURE_MS: 8000 = 8000;Defined in: lib/display-refresh.js:54
PRECISION
const PRECISION: 0.0001 = 0.0001;Defined in: lib/display-refresh.js:56
The standard error a measurement stands at, as a share of the period.
Functions
estimateRefresh()
function estimateRefresh(stamps): number;Defined in: lib/display-refresh.js:80
The display's refresh rate from the timestamps of consecutive animation
frames, or null where they say too little: fewer than MIN_FRAMES refreshes
on a steady cadence, a cadence no display runs at, or a fit short of
PRECISION.
Parameters
| Parameter | Type | Description |
|---|---|---|
stamps | number[] | Callback timestamps in ms, ascending. |
Returns
number
Refreshes per second.
fitPeriod()
function fitPeriod(
stamps,
coarse,
steady
): number;Defined in: lib/display-refresh.js:110
The refresh period of stamps fitted against their refresh counts, each
step counted in whole periods of coarse, or null where fewer than
ON_CADENCE of the steady intervals or MIN_FRAMES refreshes lie on the
cadence, the frames stray from it by more than MAX_SCATTER, or the fit's
standard error is past PRECISION.
Parameters
| Parameter | Type | Description |
|---|---|---|
stamps | number[] | - |
coarse | number | - |
steady | number | The intervals shorter than GAP_MS. |
Returns
number
snapRefresh()
function snapRefresh(hz): number;Defined in: lib/display-refresh.js:161
The rate a measured refresh names: the whole number or the NTSC rate nearest
it where one lies within SNAP_TOLERANCE, else the measurement to a
hundredth.
Parameters
| Parameter | Type | Description |
|---|---|---|
hz | number | - |
Returns
number
matchDisplay()
function matchDisplay(
hz,
min,
max
): number;Defined in: lib/display-refresh.js:178
The frame rate that matches a display refreshing at hz inside a server's
span: the refresh itself, else its largest whole division the span holds, so
each frame still lasts a whole number of refreshes, else the span's nearer
end.
Parameters
| Parameter | Type | Description |
|---|---|---|
hz | number | - |
min | number | - |
max | number | - |
Returns
number
framerateLabel()
function framerateLabel(rate): number;Defined in: lib/display-refresh.js:191
A frame rate as the dashboards show it: to a hundredth, so 60000/1001 reads 59.94.
Parameters
| Parameter | Type | Description |
|---|---|---|
rate | number | - |
Returns
number
followsDisplay()
function followsDisplay(stored, span): boolean;Defined in: lib/display-refresh.js:205
Whether a page's frame rate follows its display: where the stored choice is
FRAMERATE_DISPLAY and the server does not lock the rate. With nothing
chosen the page asks for nothing, since the server's pacing strays from the
rate asked of it by more than a matched rate would remove.
Parameters
| Parameter | Type | Description |
|---|---|---|
stored | string | The stored value, null where none is. |
span | { min: number; max: number; } | The server's framerate setting, null before it arrives. |
span.min | number | - |
span.max | number | - |
Returns
boolean
requestedFramerate()
function requestedFramerate(
stored,
displayRate,
span
): number;Defined in: lib/display-refresh.js:219
The frame rate a page asks the server for: the one stored, or where the
page follows its display (followsDisplay) the display's own inside the
server's span; null asks for nothing, as does a display not measured yet.
Parameters
| Parameter | Type | Description |
|---|---|---|
stored | string | The stored value, null where none is. |
displayRate | number | The measured refresh, null where unknown. |
span | { min: number; max: number; } | The server's framerate setting, null before it arrives. |
span.min | number | - |
span.max | number | - |
Returns
number
watchDisplayRefresh()
function watchDisplayRefresh(onRate): object;Defined in: lib/display-refresh.js:234
Measures the display while the page runs, calling onRate with the first
rate and each that differs from the last by more than CHANGE.
Parameters
| Parameter | Type | Description |
|---|---|---|
onRate | (arg0) => void | - |
Returns
object
rate
rate: () => number;Returns
number
measure
measure: () => void;Returns
void
stop
stop: () => void;Returns
void