@beeson-group/tycho 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,19 +6,45 @@ export type Vec3 = [number, number, number];
6
6
  export interface MemberResult {
7
7
  index: number;
8
8
  line: Vec3[];
9
- /** Present only when the layer has `head: true`. Null while the track is hidden. */
9
+ /** Present only when the layer has `head: true`. Null while the trajectory is hidden. */
10
10
  head?: Vec3 | null;
11
11
  }
12
- export interface TrackLayerResult {
13
- kind: 'track';
14
- /** Null when the set query does not match any track set, and `members` is then empty. */
12
+ export interface TrajectoriesLayerResult {
13
+ kind: 'trajectories';
14
+ /** Null when the set query does not match any trajectory set, and `members` is then empty. */
15
15
  set: string | null;
16
16
  members: MemberResult[];
17
17
  }
18
+ export interface ArrowMemberResult {
19
+ index: number;
20
+ /** The point at the reading. Null while the trajectory is hidden. */
21
+ base: Vec3 | null;
22
+ /** The base displaced by `scale` times the vector, blended in the same way. Null while the trajectory is hidden. */
23
+ tip: Vec3 | null;
24
+ }
25
+ export interface ArrowLayerResult {
26
+ kind: 'arrow';
27
+ /** Null when the set query does not match any trajectory set, and `members` is then empty. */
28
+ set: string | null;
29
+ members: ArrowMemberResult[];
30
+ }
31
+ export interface InsetBoxLayerResult {
32
+ kind: 'inset_box';
33
+ /** The declared panel whose window the box outlines. */
34
+ panel: string;
35
+ /** The first shown panel in layout order that names `panel`, or null when the layout does not show it, and the four keys below are then null. */
36
+ shown_panel: string | null;
37
+ /** The display frame of the target panel. */
38
+ frame: string | null;
39
+ /** The image of the origin of the target frame in the display frame, at the reading of the reference trajectory. Null when the reference does not resolve to a trajectory. */
40
+ origin: Vec3 | null;
41
+ /** The images of the three unit points of the target frame minus `origin`, i.e. the columns of the linear part of the map. Null as `origin` is. */
42
+ axes: [Vec3, Vec3, Vec3] | null;
43
+ }
18
44
  export interface BodyLayerResult {
19
45
  kind: 'body';
20
46
  body: string;
21
- /** Null when the view's driver does not resolve to a track. */
47
+ /** Null when the reference does not resolve to a trajectory. */
22
48
  position: Vec3 | null;
23
49
  /** Present only when the layer has a `trail`. */
24
50
  trail?: Vec3[];
@@ -26,10 +52,35 @@ export interface BodyLayerResult {
26
52
  export interface MarkLayerResult {
27
53
  kind: 'axes' | 'grid';
28
54
  }
29
- export type LayerResult = TrackLayerResult | BodyLayerResult | MarkLayerResult;
55
+ export interface LabelLayerResult {
56
+ kind: 'label';
57
+ /** The anchor in the display frame (rule `label`), or null for an anchor on the screen or one that does not resolve. */
58
+ position: Vec3 | null;
59
+ }
60
+ export interface PointsMemberResult {
61
+ index: number;
62
+ /** The drawn samples in storage order (rule `points`). Empty while the member is hidden or before its first sample is reached. */
63
+ points: Vec3[];
64
+ }
65
+ export interface PointsLayerResult {
66
+ kind: 'points';
67
+ /** Null when the set query does not match any trajectory set, and `members` is then empty. */
68
+ set: string | null;
69
+ members: PointsMemberResult[];
70
+ }
71
+ export type LayerResult = TrajectoriesLayerResult | ArrowLayerResult | InsetBoxLayerResult | BodyLayerResult | MarkLayerResult | LabelLayerResult | PointsLayerResult;
72
+ /** The window of a camera with keyframes (rule `camera-keyframes`). */
73
+ export interface CameraResult {
74
+ center: [number, number];
75
+ width: number;
76
+ /** Null unless the keyframes give a height, under a camera of free aspect. */
77
+ height: number | null;
78
+ }
30
79
  export interface PanelResult {
31
80
  frame: string;
32
81
  layers: LayerResult[];
82
+ /** Present only when the camera of the panel has keyframes, and null when the camera does not have a window at the frame (rule `camera-keyframes`). */
83
+ camera?: CameraResult | null;
33
84
  }
34
85
  export interface EvaluateResult {
35
86
  panels: Record<string, PanelResult>;
@@ -4,7 +4,7 @@
4
4
  * It is bundled as an immediately invoked function expression (IIFE) that exposes `tycho`, and as an ES module.
5
5
  */
6
6
  export { Container, DATA_VERSION, decodeEmbedded } from './container.js';
7
- export type { ArrayView, DataHeader, DataStore, Dtype, EncodedViewInfo, RawViewInfo, TypedArray, ViewInfo } from './container.js';
7
+ export type { ArrayInfo, DataArray, DataHeader, DataStore, Dtype, EncodedArrayInfo, RawArrayInfo, TypedArray } from './container.js';
8
8
  export { TychoError } from './errors.js';
9
9
  export { SCENE_MAJOR, SCENE_MINOR } from './scene.js';
10
10
  export type * from './scene.js';
@@ -13,7 +13,7 @@ export { evaluate } from './evaluate/index.js';
13
13
  export type * from './evaluate/types.js';
14
14
  export { TychoViewerElement, define } from './runtime/element.js';
15
15
  export { EXPORT_LIMITS, sizePreset } from './runtime/export.js';
16
- export type { ExportOptions, ExportSize, SizePreset } from './runtime/export.js';
16
+ export type { ExportLimits, ExportOptions, ExportSize, SizePreset } from './runtime/export.js';
17
17
  export { formatNumber } from './runtime/readouts.js';
18
18
  export { colormap, colormapCss } from './runtime/colormaps.js';
19
19
  import { type TychoViewerElement } from './runtime/element.js';
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Colors for drawing (section 2.7): the theme, a layer's color as a constant or a colormap over
2
+ * Colors for drawing: the theme, a layer's color as a constant or a colormap over
3
3
  * a parameter or a channel of its set, and the body colors. Colors are sRGB in [0, 1] and are
4
4
  * written to the canvas as they are, without color management.
5
5
  */
@@ -11,7 +11,27 @@ export interface Theme {
11
11
  background: string;
12
12
  foreground: string;
13
13
  grid: string;
14
+ /** A CSS font family for every text of the page and of a video. */
15
+ font?: string;
16
+ /** The color of the panel area and of the gutters between panels, on the page and in a video, by default a blend of the foreground and the background. */
17
+ gutter?: string;
18
+ /** The foreground and the background of the scene's own theme, which the colors equal to them follow. */
19
+ sceneForeground?: string;
20
+ sceneBackground?: string;
14
21
  }
22
+ /**
23
+ * A color of the scene as the viewer draws it: a color equal to the foreground or the background of the scene's theme is drawn
24
+ * in the viewer's foreground or background, so that black lines and white marker fills of a scene written for a white page follow
25
+ * a palette that replaces its theme, e.g. the dark one of a slide. Any other color is drawn as it is.
26
+ */
27
+ export declare function themed(hex: string, theme: Theme): string;
28
+ /** A layer's color with its fixed colors themed. */
29
+ export declare function themedSpec(spec: ColorSpec | undefined, theme: Theme): ColorSpec | undefined;
30
+ /** A marker with its fill and its edge themed. */
31
+ export declare function themedMarker<M extends {
32
+ color?: string;
33
+ edge?: string;
34
+ }>(m: M, theme: Theme): M;
15
35
  export declare const DEFAULT_THEME: Theme;
16
36
  export declare function sceneTheme(scene: Scene): Theme;
17
37
  /** The palettes of the `theme` attribute of `<tycho-viewer>`, which match the dark and light modes of the Beeson group's slide theme. */
@@ -38,7 +58,7 @@ export declare function cssColorHex(value: string): string | null;
38
58
  * the custom properties `--tycho-background`, `--tycho-foreground`, and `--tycho-grid` takes precedence over both.
39
59
  */
40
60
  export declare function hostTheme(base: Theme, name: string | null, read: (property: string) => string): Theme;
41
- /** The brand colors of the viewer's controls (its chrome). Orange marks what is current, and violet what the pointer or the keyboard touches. */
61
+ /** The brand colors of the viewer's controls. Orange marks what is current, and violet what the pointer or the keyboard touches. */
42
62
  export declare const ACCENT: {
43
63
  readonly accent: '#f0a050';
44
64
  readonly hover: '#ffb366';
@@ -48,38 +68,45 @@ export declare const ACCENT: {
48
68
  readonly error: '#ff7a7a';
49
69
  };
50
70
  /**
51
- * The colors of the chrome as CSS custom properties. The neutrals are
71
+ * The colors of the controls as CSS custom properties. The neutrals are
52
72
  * the theme's foreground mixed toward its background, and the orange and violet accents are
53
73
  * fixed. Every value is a color, hence the result can be put into a style sheet as it is.
54
74
  */
55
- export declare function chromeTokens(theme: Theme): Record<string, string>;
75
+ export declare function controlsTokens(theme: Theme): Record<string, string>;
56
76
  /** Parses `hex`, written as `#rrggbb`, into three numbers in [0, 1], and returns white, [1, 1, 1], for any other string. */
57
77
  export declare function hexRgb(hex: string): Rgb;
58
78
  /** The color `a` blended toward `b` by the fraction `t`, as `#rrggbb`. */
59
79
  export declare function mixHex(a: string, b: string, t: number): string;
60
80
  /**
61
81
  * A value's position on a colormap. The interval `range` maps to [0, 1], a value outside it is
62
- * clamped, and the result maps onto the part of the colormap that `clip` specifies.
82
+ * clamped, and the result maps onto the part of the colormap that `truncate` specifies.
63
83
  */
64
- export declare function colormapPosition(value: number, range: readonly [number, number], clip?: readonly [number, number]): number;
65
- /** A colormapped color's values over a set, one per track or one per sample, with its range and clip. */
84
+ export declare function colormapPosition(value: number, range: readonly [number, number], truncate?: readonly [number, number]): number;
85
+ /** A colormapped color's values over a set, one per trajectory or one per sample, with its range and truncation. */
66
86
  export interface ColorScale {
67
87
  id: ColormapId;
68
88
  name: string;
69
- perTrack: boolean;
89
+ perTrajectory: boolean;
70
90
  values: ArrayLike<number>;
71
91
  range: [number, number];
72
- clip: [number, number];
92
+ truncate: [number, number];
73
93
  }
74
- /** A function from which a color reads a choice. It returns the current value of `variable`, or undefined when `variable` does not have one. */
75
- export type ChoiceValue = (variable: string) => string | undefined;
94
+ /** A function from which a color reads a choice. It returns the current value of `input`, or undefined when `input` does not have one. */
95
+ export type ChoiceValue = (input: string) => string | undefined;
76
96
  /**
77
97
  * The colormap given by `colormap`, or for a map keyed by a choice, its entry for the choice's
78
98
  * current value. The map's first entry is used without a value or for a value that the map lacks.
79
99
  */
80
100
  export declare function colormapName(colormap: ColormapName | ColormapByChoice, value?: ChoiceValue): ColormapId;
81
- export declare function colorScale(spec: Exclude<ColorSpec, string>, set: SetData, value?: ChoiceValue): ColorScale;
82
- /** A layer's color on its set, either one constant or one color per sample (a track's color repeated over its samples). */
101
+ /** A color given by thresholds of a channel (section 2.7), which is not a colormap and does not have a colorbar. */
102
+ export type ThresholdColor = Extract<ColorSpec, {
103
+ thresholds: unknown;
104
+ }>;
105
+ export declare const isThreshold: (spec: ColorSpec | undefined) => spec is ThresholdColor;
106
+ /** The index of the color of a threshold color at value `x`, i.e. the count of thresholds below `x`. */
107
+ export declare function thresholdIndex(thresholds: readonly number[], x: number): number;
108
+ export declare function colorScale(spec: Exclude<ColorSpec, string | ThresholdColor>, set: SetData, value?: ChoiceValue): ColorScale;
109
+ /** A layer's color on its set, either one constant or one color per sample (a trajectory's color repeated over its samples). */
83
110
  export type Coloring = {
84
111
  kind: 'constant';
85
112
  rgb: Rgb;
@@ -23,13 +23,13 @@ export declare function buildChip(text: string, caret: 'menu' | 'select' | 'none
23
23
  button: HTMLButtonElement | null;
24
24
  select: HTMLSelectElement | null;
25
25
  };
26
- /** A readout's elements, as stat tiles when `readoutTiles` splits its parts, in a row under the stage or stacked in a panel. */
26
+ /** A readout's elements, as stat tiles when `readoutTiles` splits its parts, in a row under the panel area or stacked in a panel. */
27
27
  export declare function buildReadout(parts: Readout['parts'], cls: 'wide' | 'stack'): ReadoutDom;
28
28
  /** Writes a readout: its value parts into the tiles, or the whole text, or an error, as a line. */
29
29
  export declare function fillReadout(r: ReadoutDom, pieces: string[] | {
30
30
  error: string;
31
31
  }): void;
32
- /** The words inside a drop overlay. */
32
+ /** The words inside a drop marker. */
33
33
  export declare function dropText(payload: {
34
34
  kind: string;
35
35
  }, zone: DropZone): string;
@@ -49,22 +49,40 @@ export declare class TychoViewerElement extends Base {
49
49
  /** The colors in use, or null before a scene loads. */
50
50
  private theme;
51
51
  private kiosk;
52
+ /**
53
+ * What a twin made by `exportVideo` shows, or null for a viewer on the page. A twin is hidden, is drawn only by the export, and
54
+ * does not save its state. As `kiosk` it is the picture of a kiosk viewer, and as `picture` the panel area over its caption readouts.
55
+ */
56
+ private twin;
57
+ private minimal;
58
+ private keepPanels;
52
59
  private loading;
53
60
  /** Counts the loads begun, so that a load that a later one overtook drops its result. */
54
61
  private loads;
55
- /** The panel-scoped choice that a panel's header chip shows. */
62
+ /** The per-panel choice that a panel's header chip shows. */
56
63
  private choice;
57
64
  private root;
58
65
  private header;
59
66
  private titleEl;
60
67
  private varsEl;
61
68
  private addEl;
62
- private stage;
69
+ private panelArea;
63
70
  private panelsEl;
64
71
  private statusEl;
65
72
  private statsEl;
66
73
  private footer;
67
74
  private canvas;
75
+ /** The 2D canvas over the panel area, on which labels, boxes, and overlays are painted. */
76
+ private paintCanvas;
77
+ /** The held progress, valid while the frame index is the one it was taken at. */
78
+ private get heldProgress();
79
+ private set heldProgress(value);
80
+ /** The progress shown while paused at a time between two frame indices, e.g. after `seek`, or null. */
81
+ private heldValue;
82
+ /** The frame index at which `heldValue` was taken. Any other frame index, e.g. after a scrub, drops it. */
83
+ private heldFrame;
84
+ /** The loop position, unwrapped from the anchor of playback, at which `playTo` pauses, and the step it stops at. */
85
+ private stopAt;
68
86
  private readonly panelDom;
69
87
  private readonly gutterDom;
70
88
  private gutters;
@@ -73,11 +91,13 @@ export declare class TychoViewerElement extends Base {
73
91
  private addChips;
74
92
  private addButton;
75
93
  private addGroup;
76
- private transport;
94
+ private playback;
77
95
  private menu;
78
96
  /** Closes the export row when it is open, and returns whether it was open. */
79
97
  private closeExport;
80
98
  private raf;
99
+ /** The panel under the pointer, on which the keys of a 3d camera act, or null. */
100
+ private hovered;
81
101
  /** Whether the element intersects the viewport. It stays true where IntersectionObserver does not exist. */
82
102
  private intersecting;
83
103
  /** Whether the animation loop may run, i.e. the element intersects the viewport and the page is visible. */
@@ -90,10 +110,12 @@ export declare class TychoViewerElement extends Base {
90
110
  private playProgress;
91
111
  private speed;
92
112
  private readonly meter;
93
- /** The stage's size in CSS pixels, kept by the resize observer so that a draw never forces a layout. */
94
- private stageSize;
113
+ /** The panel area's size in CSS pixels, kept by the resize observer so that a draw never forces a layout. */
114
+ private panelAreaSize;
95
115
  private saveTimer;
96
116
  private resizeObserver;
117
+ /** Watches the header and the colorbars of every panel, whose sizes the labels are kept clear of. */
118
+ private overlayObserver;
97
119
  private readonly onPageHide;
98
120
  private unsubscribe;
99
121
  private lastPanels;
@@ -121,7 +143,7 @@ export declare class TychoViewerElement extends Base {
121
143
  private stop;
122
144
  /** The computed value of a custom property on the host, or an empty string when it is not set. */
123
145
  private hostProperty;
124
- /** Recolors the chrome and a live renderer from the scene's theme, the `theme` attribute, and the custom properties of the host. */
146
+ /** Recolors the controls and a live renderer from the scene's theme, the `theme` attribute, and the custom properties of the host. */
125
147
  private applyTheme;
126
148
  private recall;
127
149
  private save;
@@ -146,12 +168,17 @@ export declare class TychoViewerElement extends Base {
146
168
  /** Feeds the frame rate shown in the Playback group with a draw presented at `now`. */
147
169
  private countDraw;
148
170
  private showRate;
149
- /** Reads the stage's size once per resize, so that the draw loop never forces a layout. */
150
- private measureStage;
171
+ /** Reads the panel area's size once per resize, so that the draw loop never forces a layout. */
172
+ private measurePanelArea;
173
+ /** Draws the panel area and its overlays at the pixel ratio of the screen, at most 2, or at `ratio` when it is given. */
151
174
  private draw;
175
+ /** Whether a split of the layout moves with the timeline, so that the panels' elements follow it at every frame. */
176
+ private get animatedLayout();
177
+ /** Paints the labels, the boxes, the panel fades, and the overlays over the panel area at progress `q`. */
178
+ private paint;
152
179
  private pieces;
153
180
  private firstPanel;
154
- private hasTransport;
181
+ private hasPlayback;
155
182
  /** Whether the clock is set to run. It stays true while the clock waits for the element to be shown. */
156
183
  get playing(): boolean;
157
184
  /** Starts the clock, at once or when the element is next shown. It does not do anything before a scene loads. */
@@ -159,31 +186,63 @@ export declare class TychoViewerElement extends Base {
159
186
  /** Stops the clock. It does not do anything before a scene loads. */
160
187
  pause(): void;
161
188
  private step;
189
+ /** The steps of the scene, in order of time. */
190
+ get steps(): {
191
+ id: string;
192
+ at: number;
193
+ label?: string;
194
+ }[];
195
+ /** The time of the timeline shown, in seconds, or 0 before a scene loads. */
196
+ get time(): number;
197
+ /** The id of the last step at or before the time shown, or null when there is none. */
198
+ get currentStep(): string | null;
199
+ private stepIndex;
200
+ /** Shows time `t` of the timeline, in seconds, paused. A time at the end of the loop holds its last picture. */
201
+ seek(t: number): void;
202
+ /** Shows a step, given by its id or its index, paused. */
203
+ goto(step: string | number): void;
204
+ /** Plays from the time shown, and pauses at the time of a step, given by its id or index. A step behind the time shown is reached on the next loop. */
205
+ playTo(step: string | number): void;
206
+ /** Plays to the next step, and returns its id, or null when the time shown is at or past the last step. */
207
+ next(): string | null;
208
+ /** Shows the step before the time shown, paused, and returns its id, or null when there is none. */
209
+ previous(): string | null;
210
+ private reachStep;
162
211
  /** Goes to a frame, playing on from there when playing. */
163
- private seek;
212
+ private seekFrame;
164
213
  private onKey;
165
214
  /**
166
215
  * Acts on a key that reached the element, and returns whether the viewer used it. A key used by a focused control counts as
167
216
  * used, since a listener on the document, such as reveal.js's, sees the event retargeted to the element and cannot tell.
168
217
  */
169
218
  private useKey;
170
- /** Fits every panel's camera to what it draws. */
219
+ /** Returns every panel with camera keyframes to its keyframes, and fits every other panel's camera to what it draws. */
171
220
  fitAll(): void;
172
221
  private fitPanel;
173
- /** Moves the first scene-scoped slider by `by` stops, and returns false when there is not a slider with stops to move. */
222
+ /** Moves the first shared slider by `by` stops, and returns false when there is not a slider with stops to move. */
174
223
  private stepSlider;
175
224
  private buildFooter;
176
225
  /**
177
- * Exports a video of the current state, at the viewer's playback speed unless `options.speed` is set,
178
- * and resolves to an MP4 blob. It rejects for the reasons that exportVideo in export.ts lists, and when
179
- * the viewer has not loaded a scene.
226
+ * Exports a video of the current state, at the viewer's playback speed unless `options.speed` is set, and resolves to an MP4
227
+ * blob. The frames show what a kiosk viewer of this size shows when `options.kiosk` is true, which is the default for a kiosk
228
+ * viewer, and the panel area over its caption readouts otherwise. It rejects for the reasons that exportVideo in export.ts lists, and
229
+ * when the viewer has not loaded a scene.
180
230
  */
181
231
  exportVideo(options?: ExportOptions): Promise<Blob>;
232
+ /** The size in CSS pixels of what an export shows at the size of this viewer, i.e. the whole viewer for a kiosk, and the panel area over the caption readouts otherwise. */
233
+ private pictureSize;
234
+ /**
235
+ * Lays out a hidden twin of this viewer at w by h CSS pixels, with a frozen copy of the state, for an export to draw. The twin
236
+ * lives in this viewer's shadow root, hence it inherits the font, the custom properties, and the theme of this viewer.
237
+ */
238
+ private openTwin;
239
+ /** Draws a twin at frame index `index` and progress `q`, at `ratio` canvas pixels per CSS pixel. */
240
+ private drawAt;
182
241
  private buildExport;
183
242
  private makeWidget;
184
- /** The panel-scoped choice that a header chip shows and, with one view, the Add panel group offers, i.e. the one a view's frame reads, or else the first. */
243
+ /** The per-panel choice that a panel header chip shows, i.e. the one that the frame of a declared panel reads, or else the first. */
185
244
  private templateChoice;
186
- /** What the Add panel group offers. It offers the views when there are several, and the values of the panel-scoped choice otherwise. */
245
+ /** What the Add panel group offers, i.e. every declared panel by its label or id. */
187
246
  private templates;
188
247
  private buildTopBar;
189
248
  private buildAddGroup;
@@ -193,7 +252,7 @@ export declare class TychoViewerElement extends Base {
193
252
  private chipEntries;
194
253
  private addPanel;
195
254
  private isTall;
196
- /** A panel's name in the menus, which is its view when the scene has several, then what its header chip shows. */
255
+ /** A shown panel's name in the menus, which is its declared panel when the scene declares several, then what its header chip shows. */
197
256
  private panelName;
198
257
  /** Opens a menu under `anchor`, or closes it when it is the one open. */
199
258
  private openMenu;
@@ -202,15 +261,22 @@ export declare class TychoViewerElement extends Base {
202
261
  private panelValue;
203
262
  private syncPanels;
204
263
  private createPanelDom;
264
+ private observeOverlay;
265
+ /**
266
+ * Measures the header of a panel and writes its height as --header-height, which places the colorbars under it, hides the colorbars when
267
+ * they do not have room, and gives the renderer both boxes, which the labels are kept clear of. It reads the layout, hence it
268
+ * runs when the observer reports a change of size, or before a frame of an export, but not in the draw loop.
269
+ */
270
+ private measureOverlay;
205
271
  private removePanelDom;
206
- /** Places panels and gutters where the layout tiles the stage. */
272
+ /** Places panels and gutters where the layout tiles the panel area. */
207
273
  private layoutDom;
208
274
  private startResize;
209
275
  /** Writes a panel's colorbars from the renderer's data, in place, so that a drag on one survives the redraw it causes. */
210
276
  private syncBars;
211
277
  private makeBar;
212
278
  private barStops;
213
- /** Sets the bar's selector to the stop nearest the value at `t` along the bar, as the top bar's slider does. */
279
+ /** Sets the bar's parameter input to the stop nearest the value at `t` along the bar, as the top bar's slider does. */
214
280
  private setFromBar;
215
281
  private stepBar;
216
282
  private startDrag;
@@ -1,12 +1,10 @@
1
- import type { Scene, State } from '../scene.js';
2
- import { type Theme } from './colors.js';
3
- import type { GeometryCache } from './geometry.js';
4
- import type { Colorbar, PanelLabel } from './overlay.js';
5
- /** The longest export allowed, in frames and in seconds. A longer export is refused. */
6
- export declare const EXPORT_LIMITS: {
7
- readonly frames: 2000;
8
- readonly seconds: 90;
9
- };
1
+ import type { Clock } from '../scene.js';
2
+ export interface ExportLimits {
3
+ frames: number;
4
+ seconds: number;
5
+ }
6
+ /** The longest export allowed by default, in frames and in seconds. A longer export is refused unless `limits` of ExportOptions raises them. */
7
+ export declare const EXPORT_LIMITS: Readonly<ExportLimits>;
10
8
  export declare const EXPORT_FPS: readonly [24, 30, 60];
11
9
  export declare const EXPORT_LOOPS: readonly [1, 2, 3, 4];
12
10
  export interface Schedule {
@@ -20,19 +18,19 @@ export interface Schedule {
20
18
  progress(k: number): number;
21
19
  }
22
20
  /**
23
- * Every output frame, as live playback would draw it at the time of the frame. A loop of `steps` lasts
24
- * `seconds / speed`, where `seconds` is LAP_SECONDS for each lap. Output frame `k` is drawn at time
21
+ * Every output frame, as live playback would draw it at the time of the frame. A loop of `frameCount` frames lasts
22
+ * `seconds / speed`, where `seconds` is the clock's loopSeconds. Output frame `k` is drawn at time
25
23
  * `k / fps`, at the progress reached then, with the integer part of the loop position as its index.
26
24
  */
27
- export declare function frameSchedule(steps: number, fps: number, loops: number, speed?: number, start?: number, seconds?: number): Schedule;
28
- /** Why an export of `count` frames at `fps` is refused, or null when it is not. */
29
- export declare function checkExport(count: number, fps: number): string | null;
25
+ export declare function frameSchedule(frameCount: number, fps: number, loops: number, speed?: number, start?: number, seconds?: number): Schedule;
26
+ /** Why an export of `count` frames at `fps` is refused under `limits`, or null when it is not. */
27
+ export declare function checkExport(count: number, fps: number, limits?: ExportLimits): string | null;
30
28
  /**
31
29
  * The frame rate an export row starts at, i.e. the highest of EXPORT_FPS at which one loop at
32
30
  * `speed` stays within EXPORT_LIMITS, or null when every rate in EXPORT_FPS exceeds them.
33
31
  */
34
- export declare function defaultExportFps(steps: number, speed: number, seconds?: number): number | null;
35
- export type SizePreset = '720p' | '1080p' | 'stage';
32
+ export declare function defaultExportFps(frameCount: number, speed: number, seconds?: number): number | null;
33
+ export type SizePreset = '720p' | '1080p' | 'panels';
36
34
  export interface ExportSize {
37
35
  /** The size of the video in pixels, as `width` and `height`. */
38
36
  width: number;
@@ -42,11 +40,11 @@ export interface ExportSize {
42
40
  }
43
41
  /**
44
42
  * A preset's size at `fps`. The presets 720p and 1080p share one layout of 1280 by 720 CSS pixels,
45
- * at pixel ratios of 1 and 1.5. The preset `stage` is the stage's size rounded down to even pixels,
43
+ * at pixel ratios of 1 and 1.5. The preset `panels` is the size of the panel area rounded down to even pixels,
46
44
  * at the whole pixel ratio nearest the screen's, at most 2. Where H.264 cannot hold the size and the
47
45
  * rate there, the ratio is lowered in eighths to the largest at which it can. Both sides are kept even, as required by H.264.
48
46
  */
49
- export declare function sizePreset(preset: SizePreset, stage?: {
47
+ export declare function sizePreset(preset: SizePreset, panelArea?: {
50
48
  w: number;
51
49
  h: number;
52
50
  }, devicePixelRatio?: number, fps?: number): ExportSize;
@@ -77,43 +75,55 @@ export interface ExportOptions {
77
75
  size?: SizePreset | ExportSize;
78
76
  fps?: number;
79
77
  loops?: number;
80
- /** The playback speed, at which a lap of the clock lasts 8 s divided by the speed. Defaults to 1. */
78
+ /** The playback speed, at which a revolution of the clock lasts 8 s divided by the speed. Defaults to 1. */
81
79
  speed?: number;
82
80
  /** The frame index of the first frame. Defaults to 0. */
83
81
  start?: number;
82
+ /**
83
+ * Whether each frame is the picture of a kiosk viewer of the video's size in CSS pixels, i.e. the panel area alone. Otherwise a frame
84
+ * holds the panel area over the caption readouts. Defaults to whether the viewer has the attribute `kiosk`.
85
+ */
86
+ kiosk?: boolean;
87
+ /** The longest export allowed, by default EXPORT_LIMITS. */
88
+ limits?: ExportLimits;
84
89
  bitrate?: number;
90
+ /** The number of frames from one key frame to the next, by default twice the frame rate. Infinity makes the first frame the only key frame. */
91
+ keyFrameInterval?: number;
92
+ /** The hardware acceleration asked of the H.264 encoder, by default `no-preference`. */
93
+ hardwareAcceleration?: HardwareAcceleration;
85
94
  /** Called with the encoder configuration the browser accepted, before the first frame. */
86
95
  onConfig?: (config: VideoEncoderConfig) => void;
96
+ /** Called with each frame, as a canvas of the video's size, after it is drawn and before it is encoded. */
97
+ onFrame?: (frame: HTMLCanvasElement, k: number) => void;
87
98
  onProgress?: (done: number, total: number) => void;
88
99
  signal?: AbortSignal;
89
100
  }
90
- /** What an export draws: a scene, its data, and the snapshot to freeze. */
101
+ /** A picture laid out at a size, which an export draws at each frame. */
102
+ export interface Picture {
103
+ /** Draws frame index `index` at progress `q` onto `g`, whose transform maps the picture's CSS pixels to the canvas. */
104
+ draw(g: CanvasRenderingContext2D, index: number, q: number): void;
105
+ close(): void;
106
+ }
107
+ /** What an export draws, as the viewer gives it. */
91
108
  export interface ExportSource {
92
- scene: Scene;
93
- geometry: GeometryCache;
94
- state: State;
95
- /** The stage's size in CSS pixels, for the `stage` preset. */
96
- stage?: {
109
+ clock: Clock;
110
+ /** The size of the picture on the page in CSS pixels, which the `panels` preset starts from. */
111
+ panelArea: {
97
112
  w: number;
98
113
  h: number;
99
114
  };
100
- /** The theme to draw with, by default the scene's. */
101
- theme?: Theme;
102
- /** The font family of the text on the canvas, by default FONT. */
103
- font?: string;
115
+ /** Lays out the picture at w by h CSS pixels, to be drawn at `ratio` video pixels per CSS pixel, and resolves once it can be drawn. */
116
+ open(w: number, h: number, ratio: number): Promise<Picture>;
104
117
  }
105
118
  export declare function webCodecsMissing(): string | null;
106
119
  /**
107
120
  * The first H.264 configuration this browser's encoder accepts, at the lowest level that holds the
108
121
  * size and rate. The profiles high, main, and baseline are tried in turn, in the avc format used in an MP4.
109
122
  */
110
- export declare function chooseConfig(width: number, height: number, fps: number, bitrate: number): Promise<VideoEncoderConfig>;
111
- /** Draws a panel label as the page places it, centered vertically on (x, y) and turned to read upward when rotated. Exported for the tests. */
112
- export declare function drawLabel(g: CanvasRenderingContext2D, l: PanelLabel, x: number, y: number, fg: string, bg: string, font?: string): void;
113
- export declare function drawColorbars(g: CanvasRenderingContext2D, bars: Colorbar[], right: number, top: number, fg: string, dim: string, line: string, bg: string, font?: string): void;
123
+ export declare function chooseConfig(width: number, height: number, fps: number, bitrate: number, hardwareAcceleration?: HardwareAcceleration): Promise<VideoEncoderConfig>;
114
124
  /**
115
125
  * Exports a video of `source` and resolves to an MP4 blob of H.264. Rejects with an AbortError
116
126
  * when `options.signal` aborts, and with an Error that gives the reason when WebCodecs is missing, when
117
- * the browser does not have an H.264 encoder for the size, or when the export would exceed EXPORT_LIMITS.
127
+ * the browser does not have an H.264 encoder for the size, or when the export would exceed its limits.
118
128
  */
119
129
  export declare function exportVideo(source: ExportSource, options?: ExportOptions): Promise<Blob>;