Data and streaming

Partial update at offset

Switch the feed on. Each frame rewrites forty samples where the sweep has reached and leaves the other 1,960 as they were, the way an oscilloscope redraws its trace. The cost is the forty.

101 of 136

The call

plot.writeBuffer(handle: BufferHandle, offset: number, values: Float32Array | Float64Array): void

Overwrite part of a buffer, starting offset scalars in.

The streaming path: a live series appends and only the appended scalars are touched. Writing past the end grows the buffer.

Throws when the precision does not match what the buffer holds. Refused rather than narrowed, because narrowing a caller's f64 silently is the kind of loss that only ever shows up as a plot that looks subtly wrong.

calls/partial-update-at-offset

const count = 2000;
const span = 40;
const x = plot.uploadBuffer(Float64Array.from({ length: count }, (_, i) => i));
const y = plot.uploadBuffer(Float32Array.from({ length: count }, (_, i) => signal(i)));
plot.setCharts({
  charts: [{ series: [{ x, y, label: "trace" }], y: { range: [-2.5, 2.5] }, legend: false }],
});

const patch = new Float32Array(span);
let from = 0;
return {
  stream(at) {
    for (let i = 0; i < span; i++) patch[i] = signal(from + i) * Math.cos(at) + Math.sin(at);
    // The handle, how many scalars in to start, and what to put there.
    plot.writeBuffer(y, from, patch);
    from = (from + span) % count;
  },
};

Also called

2 in the code above, in the order it makes them

plot.uploadBuffer(values: Float32Array | Float64Array): BufferHandle

Upload a block of scalars and return a handle naming it.

A buffer keeps the precision it arrived in. Use Float64Array for time and for anything where f32's twenty-four bits of mantissa would lose something real: a millisecond timestamp narrowed to f32 rounds every sample into a five-minute bucket, and it does that silently.

plot.setCharts(document: ChartDocument): readonly ChartHandle[]

Draw a document of charts, and get a handle for each one.

The handles come back in document order and are what names a chart afterwards: chartView, setChartView, chartPicked, and the chart on a hover, a hit or any other event. A page linking two charts holds two handles rather than allocating ids.

Replaces the charts and the series each one reads.

Throws rather than drawing a partial document, and a throw leaves the previous document in place. What it refuses: a misspelled key, a handle that names something other than a buffer, a range whose ends are the wrong way round, and a column on a chart kind that cannot read it. All four would otherwise be a chart that draws something subtly wrong, or nothing, with nothing said.

Setting a document again is the way to change one: there is no per-chart edit, and the compile is cheap because the data does not move. The buffers are named by handle, so a live chart writes to them with writeBuffer and never sets a document at all.