textmode.js 0.4.1-beta.1 → 0.6.0-beta.2

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.
Files changed (106) hide show
  1. package/dist/textmode.esm.js +2578 -1861
  2. package/dist/textmode.esm.min.js +2578 -1861
  3. package/dist/textmode.umd.js +11 -8
  4. package/dist/textmode.umd.min.js +11 -8
  5. package/dist/types/Textmode.d.ts +13 -22
  6. package/dist/types/errors/ErrorHandler.d.ts +6 -1
  7. package/dist/types/index.d.ts +8 -6
  8. package/dist/types/rendering/index.d.ts +3 -3
  9. package/dist/types/rendering/webgl/batching/DrawQueue.d.ts +89 -0
  10. package/dist/types/rendering/webgl/{VAOManager.d.ts → batching/GeometryAttributeCache.d.ts} +4 -4
  11. package/dist/types/rendering/webgl/batching/InstanceAttributeBinder.d.ts +87 -0
  12. package/dist/types/rendering/webgl/{InstanceBatch.d.ts → batching/InstanceBatch.d.ts} +28 -37
  13. package/dist/types/rendering/webgl/batching/InstanceBuffer.d.ts +78 -0
  14. package/dist/types/rendering/webgl/{InstanceData.d.ts → batching/InstanceData.d.ts} +11 -18
  15. package/dist/types/rendering/webgl/batching/InstanceWriter.d.ts +70 -0
  16. package/dist/types/rendering/webgl/{Framebuffer.d.ts → core/Framebuffer.d.ts} +37 -39
  17. package/dist/types/rendering/webgl/core/Renderer.d.ts +64 -0
  18. package/dist/types/rendering/webgl/{Shader.d.ts → core/Shader.d.ts} +2 -23
  19. package/dist/types/rendering/webgl/core/interfaces/IFramebuffer.d.ts +103 -0
  20. package/dist/types/rendering/webgl/core/interfaces/IRenderer.d.ts +210 -0
  21. package/dist/types/rendering/webgl/geometries/{Arc.d.ts → 2d/Arc.d.ts} +5 -4
  22. package/dist/types/rendering/webgl/geometries/{BezierCurve.d.ts → 2d/BezierCurve.d.ts} +5 -4
  23. package/dist/types/rendering/webgl/geometries/{Ellipse.d.ts → 2d/Ellipse.d.ts} +6 -5
  24. package/dist/types/rendering/webgl/geometries/{Line.d.ts → 2d/Line.d.ts} +5 -4
  25. package/dist/types/rendering/webgl/geometries/{Rectangle.d.ts → 2d/Rectangle.d.ts} +5 -4
  26. package/dist/types/rendering/webgl/geometries/{Triangle.d.ts → 2d/Triangle.d.ts} +5 -4
  27. package/dist/types/rendering/webgl/geometries/BaseGeometry.d.ts +30 -26
  28. package/dist/types/rendering/webgl/geometries/immediate/ImmediateQuad.d.ts +33 -0
  29. package/dist/types/rendering/webgl/geometries/index.d.ts +6 -6
  30. package/dist/types/rendering/webgl/geometries/utils/GeometryDescriptors.d.ts +31 -0
  31. package/dist/types/rendering/webgl/geometries/utils/GeometryGenerator.d.ts +16 -0
  32. package/dist/types/rendering/webgl/index.d.ts +15 -14
  33. package/dist/types/rendering/webgl/materials/Material.d.ts +26 -0
  34. package/dist/types/rendering/webgl/materials/MaterialManager.d.ts +63 -0
  35. package/dist/types/rendering/webgl/materials/index.d.ts +2 -0
  36. package/dist/types/rendering/webgl/pipeline/MaterialBatchPipeline.d.ts +63 -0
  37. package/dist/types/rendering/webgl/pipeline/index.d.ts +7 -0
  38. package/dist/types/rendering/webgl/state/RenderState.d.ts +143 -0
  39. package/dist/types/rendering/webgl/types/DrawCommand.d.ts +5 -3
  40. package/dist/types/rendering/webgl/types/GeometryTypes.d.ts +10 -10
  41. package/dist/types/rendering/webgl/types/RenderTypes.d.ts +1 -1
  42. package/dist/types/rendering/webgl/utils/GLUtils.d.ts +45 -0
  43. package/dist/types/rendering/webgl/utils/hash.d.ts +118 -0
  44. package/dist/types/textmode/AnimationController.d.ts +11 -21
  45. package/dist/types/textmode/Canvas.d.ts +10 -2
  46. package/dist/types/textmode/Grid.d.ts +2 -0
  47. package/dist/types/textmode/TextmodeColor.d.ts +57 -0
  48. package/dist/types/textmode/Textmodifier.d.ts +32 -213
  49. package/dist/types/textmode/interfaces/ITextmodifier.d.ts +275 -0
  50. package/dist/types/textmode/interfaces/index.d.ts +1 -0
  51. package/dist/types/textmode/loadables/TextmodeImage.d.ts +47 -0
  52. package/dist/types/textmode/loadables/TextmodeSource.d.ts +130 -0
  53. package/dist/types/textmode/loadables/TextmodeVideo.d.ts +265 -0
  54. package/dist/types/textmode/{font → loadables/font}/CharacterColorMapper.d.ts +1 -1
  55. package/dist/types/textmode/{font → loadables/font}/CharacterExtractor.d.ts +0 -10
  56. package/dist/types/textmode/{font → loadables/font}/TextmodeFont.d.ts +9 -3
  57. package/dist/types/textmode/{font → loadables/font}/TextureAtlas.d.ts +4 -11
  58. package/dist/types/textmode/{font → loadables/font}/typr/types.d.ts +0 -6
  59. package/dist/types/textmode/loadables/index.d.ts +5 -0
  60. package/dist/types/textmode/loading/LoadingPhaseTracker.d.ts +20 -0
  61. package/dist/types/textmode/loading/LoadingScreenManager.d.ts +211 -0
  62. package/dist/types/textmode/loading/LoadingScreenState.d.ts +22 -0
  63. package/dist/types/textmode/loading/LoadingScreenTheme.d.ts +26 -0
  64. package/dist/types/textmode/loading/LoadingScreenTransition.d.ts +17 -0
  65. package/dist/types/textmode/loading/index.d.ts +6 -0
  66. package/dist/types/textmode/loading/templates/SpinnerTemplate.d.ts +2 -0
  67. package/dist/types/textmode/loading/templates/index.d.ts +1 -0
  68. package/dist/types/textmode/loading/types.d.ts +251 -0
  69. package/dist/types/textmode/managers/KeyboardManager.d.ts +2 -3
  70. package/dist/types/textmode/managers/MouseManager.d.ts +1 -1
  71. package/dist/types/textmode/{plugins → managers}/PluginManager.d.ts +18 -16
  72. package/dist/types/textmode/managers/TouchManager.d.ts +0 -2
  73. package/dist/types/textmode/mixins/AnimationMixin.d.ts +2 -122
  74. package/dist/types/textmode/mixins/FontMixin.d.ts +2 -77
  75. package/dist/types/textmode/mixins/KeyboardMixin.d.ts +3 -85
  76. package/dist/types/textmode/mixins/MouseMixin.d.ts +3 -130
  77. package/dist/types/textmode/mixins/RenderingMixin.d.ts +2 -749
  78. package/dist/types/textmode/mixins/TextmodifierMixin.d.ts +2 -44
  79. package/dist/types/textmode/mixins/TouchMixin.d.ts +2 -187
  80. package/dist/types/textmode/mixins/index.d.ts +8 -8
  81. package/dist/types/textmode/mixins/interfaces/IAnimationMixin.d.ts +167 -0
  82. package/dist/types/textmode/mixins/interfaces/IFontMixin.d.ts +46 -0
  83. package/dist/types/textmode/mixins/interfaces/IKeyboardMixin.d.ts +235 -0
  84. package/dist/types/textmode/mixins/interfaces/IMouseMixin.d.ts +457 -0
  85. package/dist/types/textmode/mixins/interfaces/IRenderingMixin.d.ts +1124 -0
  86. package/dist/types/textmode/mixins/interfaces/ITouchMixin.d.ts +186 -0
  87. package/dist/types/textmode/types.d.ts +49 -0
  88. package/dist/types/textmode/utils/cssColor.d.ts +8 -0
  89. package/dist/types/utils/array.d.ts +34 -0
  90. package/dist/types/utils/math.d.ts +69 -0
  91. package/package.json +1 -1
  92. package/dist/types/rendering/webgl/DrawQueue.d.ts +0 -30
  93. package/dist/types/rendering/webgl/RenderPipeline.d.ts +0 -30
  94. package/dist/types/rendering/webgl/RenderState.d.ts +0 -73
  95. package/dist/types/rendering/webgl/Renderer.d.ts +0 -158
  96. package/dist/types/rendering/webgl/ShaderManager.d.ts +0 -66
  97. package/dist/types/rendering/webgl/geometries/NoiseGrid.d.ts +0 -1
  98. package/dist/types/textmode/TextmodeImage.d.ts +0 -161
  99. package/dist/types/textmode/mixins/ShaderMixin.d.ts +0 -1
  100. /package/dist/types/rendering/webgl/{StateCache.d.ts → utils/ViewportCache.d.ts} +0 -0
  101. /package/dist/types/textmode/{font → loadables/font}/MetricsCalculator.d.ts +0 -0
  102. /package/dist/types/textmode/{font → loadables/font}/index.d.ts +0 -0
  103. /package/dist/types/textmode/{font → loadables/font}/types.d.ts +0 -0
  104. /package/dist/types/textmode/{font → loadables/font}/typr/Typr.d.ts +0 -0
  105. /package/dist/types/textmode/{font → loadables/font}/utils/FontTableReader.d.ts +0 -0
  106. /package/dist/types/textmode/{font → loadables/font}/utils/index.d.ts +0 -0
@@ -0,0 +1,265 @@
1
+ import type { GLRenderer } from '../../rendering/webgl/core/Renderer';
2
+ import type { Material } from '../../rendering/webgl/materials/Material';
3
+ import { TextmodeSource } from './TextmodeSource';
4
+ type TextmodeVideoPreloadStrategy = 'captureStream' | 'seeking';
5
+ export interface TextmodeVideoPreloadProgress {
6
+ percent: number;
7
+ loadedFrames: number;
8
+ totalFrames: number;
9
+ strategy: TextmodeVideoPreloadStrategy;
10
+ }
11
+ export interface TextmodeVideoPreloadComplete {
12
+ totalFrames: number;
13
+ strategy: TextmodeVideoPreloadStrategy;
14
+ }
15
+ /**
16
+ * Options for preloading video frames in {@link TextmodeVideo}.
17
+ *
18
+ * When providing this options object as a second argument to {@link Textmodifier.loadVideo},
19
+ * you can choose to preload all video frames at a specified frame rate before using the video.
20
+ *
21
+ * When preloading, the video will not play live asynchronously. Instead, all frames will be captured
22
+ * upfront, allowing for frame-accurate seeking and rendering.
23
+ *
24
+ * This is especially useful for scenarios where precise frame control is needed,
25
+ * like capturing GIFs/videos from textmode.js canvas using the `textmode.export.js` add-on library without
26
+ * missing frames due to asynchronous video playback.
27
+ *
28
+ * Preloading takes time proportional to the video length and frame rate, which introduces significant delays
29
+ * before the sketch can start rendering. Therefore, it is recommended to use this feature only when intending
30
+ * to capture or export frames, rather than for real-time playback.
31
+ */
32
+ export interface TextmodeVideoOptions {
33
+ /** Frame rate to use when preloading video frames. If not specified, video will not be preloaded. */
34
+ frameRate?: number;
35
+ /** Callback invoked periodically during preloading to report progress. */
36
+ onProgress?: (progress: TextmodeVideoPreloadProgress) => void;
37
+ /** Callback invoked once preloading is complete. */
38
+ onComplete?: (summary: TextmodeVideoPreloadComplete) => void;
39
+ /** Callback invoked if an error occurs during preloading. */
40
+ onError?: (error: Error) => void;
41
+ }
42
+ /**
43
+ * Represents a video element for textmode rendering via {@link Textmodifier.loadVideo}.
44
+ *
45
+ * It can be drawn to the canvas via {@link Textmodifier.image}.
46
+ *
47
+ * A video uploaded currently runs through an adjustable brightness-converter that converts
48
+ * the video frames into a textmode representation using characters.
49
+ * Those adjustable options are available via chainable methods on this class.
50
+ * ```javascript
51
+ * const t = textmode.create({
52
+ * width: 800,
53
+ * height: 600,
54
+ * });
55
+ *
56
+ * let video;
57
+ *
58
+ * t.setup(async () => {
59
+ * video = await t.loadVideo('https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4');
60
+ * // Start playback and enable looping so the video keeps playing
61
+ * video.play();
62
+ * video.loop();
63
+ *
64
+ * video.characters(" .:-=+*#%@");
65
+ * // ... other adjustments like video.flipX(boolean), video.cellColorMode('sampled' | 'fixed'), etc.
66
+ * // (can also be chained or updated during runtime)
67
+ * });
68
+ *
69
+ * t.draw(() => {
70
+ * t.background(0);
71
+ *
72
+ * if (video) {
73
+ * // Draw the loaded video
74
+ * t.image(video);
75
+ * }
76
+ * });
77
+ * ```
78
+ */
79
+ export declare class TextmodeVideo extends TextmodeSource {
80
+ private _videoElement;
81
+ private _isPreloaded;
82
+ private _preloadedFrames;
83
+ private _frameRate;
84
+ private _totalFrames;
85
+ private _currentFrameIndex;
86
+ private _lastProgressBucket;
87
+ /**
88
+ * Create a new TextmodeVideo instance.
89
+ * @param gl WebGL2 rendering context
90
+ * @param renderer GLRenderer instance
91
+ * @param texture WebGL texture for video frames
92
+ * @param videoElement The HTML video element
93
+ * @param originalWidth Original video width in pixels
94
+ * @param originalHeight Original video height in pixels
95
+ * @param gridCols Number of columns in the grid (for auto-sizing)
96
+ * @param gridRows Number of rows in the grid (for auto-sizing)
97
+ *
98
+ * @ignore
99
+ */
100
+ constructor(gl: WebGL2RenderingContext, renderer: GLRenderer, texture: WebGLTexture, videoElement: HTMLVideoElement, originalWidth: number, originalHeight: number, gridCols: number, gridRows: number);
101
+ /**
102
+ * Dispose of GPU resources and cleanup video element.
103
+ * @ignore
104
+ */
105
+ $dispose(): void;
106
+ /**
107
+ * Update the texture with the current video frame if needed.
108
+ * For preloaded videos, this returns the appropriate frame texture.
109
+ * For live videos, this updates the texture with current video data.
110
+ * @ignore
111
+ */
112
+ $updateTexture(): void;
113
+ /**
114
+ * Get the active texture for the current frame.
115
+ * For preloaded videos, returns the texture at the current frame index.
116
+ * For live videos, returns the live texture.
117
+ * @ignore
118
+ */
119
+ protected $getActiveTexture(): WebGLTexture;
120
+ /**
121
+ * Get or create the material for rendering this video.
122
+ * Always updates the material to ensure the latest video frame is used.
123
+ * @ignore
124
+ */
125
+ $getMaterial(): Material;
126
+ protected $beforeMaterialUpdate(): void;
127
+ /**
128
+ * Preload all frames of the video at the specified frame rate.
129
+ * Chooses the most optimal strategy based on browser capabilities.
130
+ * @param frameRate Frame rate to use for capturing frames
131
+ * @ignore
132
+ */
133
+ private _preloadFrames;
134
+ private _initializePreloadState;
135
+ private _finalizePreloadSuccess;
136
+ private _captureSourceToTexture;
137
+ private _reportPreloadProgress;
138
+ private _tryPreloadWithTrackProcessor;
139
+ private _preloadWithLegacySeeking;
140
+ private _waitForSeek;
141
+ /**
142
+ * For preloaded videos, set or get the current frame index.
143
+ * When called without arguments, returns this video instance for use with t.image().
144
+ * When called with an index, sets the frame and returns this instance.
145
+ *
146
+ * The frame index automatically wraps using modulo, so you can pass t.frameCount directly
147
+ * and it will loop through the video frames seamlessly.
148
+ *
149
+ * For non-preloaded videos, this method does nothing and returns the instance.
150
+ *
151
+ * @param index Optional frame index to set (0-based, automatically wraps)
152
+ * @returns This instance for chaining.
153
+ *
154
+ * @example
155
+ * ```javascript
156
+ * // Draw specific frame
157
+ * t.image(video.frame(0), x, y);
158
+ *
159
+ * // Draw frame based on frameCount (automatically wraps)
160
+ * t.image(video.frame(t.frameCount), x, y);
161
+ *
162
+ * video.frame(t.frameCount);
163
+ * t.image(video, x, y);
164
+ * ```
165
+ */
166
+ frame(index?: number): this;
167
+ /**
168
+ * Create a TextmodeVideo instance from a video source (URL or HTMLVideoElement).
169
+ * @param renderer GLRenderer instance
170
+ * @param source Video URL string or HTMLVideoElement
171
+ * @param gridCols Number of columns in the grid
172
+ * @param gridRows Number of rows in the grid
173
+ * @param glyphResolver Function to resolve character strings to glyph colors
174
+ * @param options Optional preload configuration (frameRate, onProgress, onComplete, onError).
175
+ * @returns Promise resolving to TextmodeVideo instance
176
+ * @ignore
177
+ */
178
+ static $fromSource(renderer: GLRenderer, source: string | HTMLVideoElement, gridCols: number, gridRows: number, glyphResolver: (s: string) => ([number, number, number])[], options?: TextmodeVideoOptions): Promise<TextmodeVideo>;
179
+ /**
180
+ * Play the video.
181
+ * @returns Promise that resolves when playback starts
182
+ */
183
+ play(): Promise<void>;
184
+ /**
185
+ * Pause the video.
186
+ */
187
+ pause(): void;
188
+ /**
189
+ * Stop the video and reset to beginning.
190
+ */
191
+ stop(): void;
192
+ /**
193
+ * Set the playback speed.
194
+ * @param rate Playback rate (1.0 = normal speed)
195
+ */
196
+ speed(rate: number): this;
197
+ /**
198
+ * Set whether the video should loop.
199
+ * @param shouldLoop Whether to loop (defaults to true)
200
+ */
201
+ loop(shouldLoop?: boolean): this;
202
+ /**
203
+ * Set the current time position in the video.
204
+ * @param seconds Time in seconds
205
+ */
206
+ time(seconds: number): this;
207
+ /**
208
+ * Set the volume.
209
+ * @param level Volume level (0.0-1.0)
210
+ */
211
+ volume(level: number): this;
212
+ /**
213
+ * WebGL texture handle containing the current video frame.
214
+ */
215
+ get texture(): WebGLTexture;
216
+ /**
217
+ * Ideal width to draw the video at (in grid cells), calculated to fit the grid while preserving aspect ratio.
218
+ */
219
+ get width(): number;
220
+ /**
221
+ * Ideal height to draw the video at (in grid cells), calculated to fit the grid while preserving aspect ratio.
222
+ */
223
+ get height(): number;
224
+ /**
225
+ * Original pixel width of the video.
226
+ */
227
+ get originalWidth(): number;
228
+ /**
229
+ * Original pixel height of the video.
230
+ */
231
+ get originalHeight(): number;
232
+ /**
233
+ * The underlying HTML video element.
234
+ */
235
+ get videoElement(): HTMLVideoElement;
236
+ /**
237
+ * Current playback time in seconds.
238
+ */
239
+ get currentTime(): number;
240
+ /**
241
+ * Total duration of the video in seconds.
242
+ */
243
+ get duration(): number;
244
+ /**
245
+ * Whether the video is currently playing.
246
+ */
247
+ get isPlaying(): boolean;
248
+ /**
249
+ * Whether this video has been preloaded with frames.
250
+ */
251
+ get isPreloaded(): boolean;
252
+ /**
253
+ * Total number of preloaded frames. Returns 0 for non-preloaded videos.
254
+ */
255
+ get totalFrames(): number;
256
+ /**
257
+ * The frame rate used for preloading. Returns null for non-preloaded videos.
258
+ */
259
+ get preloadFrameRate(): number | null;
260
+ /**
261
+ * Current frame index for preloaded videos. Returns 0 for non-preloaded videos.
262
+ */
263
+ get currentFrameIndex(): number;
264
+ }
265
+ export {};
@@ -17,7 +17,7 @@ export declare class CharacterColorMapper {
17
17
  /**
18
18
  * Generates a unique RGB color for a character based on its index.
19
19
  * @param index The index of the character
20
- * @returns RGB color as a tuple [r, g, b] with values from 0-1 for shader use
20
+ * @returns RGB color as a tuple [r, g, 0] with values from 0-1 for shader use
21
21
  */
22
22
  private _generateCharacterColor;
23
23
  /**
@@ -10,12 +10,6 @@ export declare class CharacterExtraction {
10
10
  * @returns Array of unique character strings
11
11
  */
12
12
  $extractCharacters(font: TyprFont): string[];
13
- /**
14
- * Filters out problematic characters that might cause rendering issues.
15
- * @param characters Array of character strings to filter
16
- * @returns Filtered array of character strings
17
- */
18
- $filterProblematicCharacters(characters: string[]): string[];
19
13
  /**
20
14
  * Extracts characters from a Format 4 cmap table (Basic Multilingual Plane).
21
15
  */
@@ -28,8 +22,4 @@ export declare class CharacterExtraction {
28
22
  * Calculates the glyph index for a character in a Format 4 cmap table.
29
23
  */
30
24
  private _calculateGlyphIndexFormat4;
31
- /**
32
- * Checks if a character is valid for rendering.
33
- */
34
- private _isValidCharacter;
35
25
  }
@@ -1,12 +1,15 @@
1
- import type { GLRenderer } from '../../rendering/webgl/Renderer.ts';
2
- import type { GLFramebuffer } from '../../rendering/webgl/Framebuffer.ts';
1
+ import type { GLRenderer } from '../../../rendering/webgl/core/Renderer.ts';
2
+ import type { GLFramebuffer } from '../../../rendering/webgl/core/Framebuffer.ts';
3
3
  import type { TextmodeCharacter } from './types.ts';
4
4
  import type { TyprFont, GlyphData } from './typr/types.ts';
5
5
  /**
6
- * Manages the font used for rendering characters.
6
+ * Manages the font used for rendering characters via {@link Textmodifier.loadFont}.
7
7
  *
8
8
  * This class coordinates font loading, character extraction, texture atlas creation,
9
9
  * and provides character information.
10
+ *
11
+ * The font used by your {@link Textmodifier} instance is accessible via
12
+ * the {@link Textmodifier.font} property.
10
13
  */
11
14
  export declare class TextmodeFont {
12
15
  private _font;
@@ -75,9 +78,12 @@ export declare class TextmodeFont {
75
78
  $getCharacterColors(characters: string): [number, number, number][];
76
79
  /**
77
80
  * Lazily retrieves glyph data for the given Unicode code point.
81
+ *
78
82
  * Glyph data is cached after the first access to avoid repeated Typr parsing.
83
+ *
79
84
  * @param codePoint Unicode code point
80
85
  * @returns Parsed glyph data or null if unavailable
86
+ * @ignore
81
87
  */
82
88
  getGlyphData(codePoint: number): GlyphData | null;
83
89
  private _getGlyphIndex;
@@ -1,6 +1,6 @@
1
1
  import type { TextmodeCharacter, GlyphDimensions } from './types.ts';
2
- import type { GLRenderer } from '../../rendering/webgl/Renderer.ts';
3
- import type { GLFramebuffer } from '../../rendering/webgl/Framebuffer.ts';
2
+ import type { GLRenderer } from '../../../rendering/webgl/core/Renderer.ts';
3
+ import type { GLFramebuffer } from '../../../rendering/webgl/core/Framebuffer.ts';
4
4
  import type { TyprFont } from './typr/types.ts';
5
5
  /**
6
6
  * Handles creation of texture atlases for font rendering.
@@ -23,10 +23,10 @@ export declare class TextureAtlasCreation {
23
23
  * @param characters Array of TextmodeCharacter objects
24
24
  * @param maxGlyphDimensions Maximum dimensions of glyphs
25
25
  * @param fontSize Font size for rendering
26
- * @param fontDataOrFamilyName Either Typr.js font data object for path rendering, or font family name string for fillText rendering
26
+ * @param font Either Typr.js font data object for path rendering, or font family name string for fillText rendering
27
27
  * @returns Object containing framebuffer, columns, and rows
28
28
  */
29
- createTextureAtlas(characters: TextmodeCharacter[], maxGlyphDimensions: GlyphDimensions, fontSize: number, fontDataOrFamilyName: TyprFont | string): {
29
+ $createTextureAtlas(characters: TextmodeCharacter[], maxGlyphDimensions: GlyphDimensions, fontSize: number, font: TyprFont): {
30
30
  framebuffer: GLFramebuffer;
31
31
  columns: number;
32
32
  rows: number;
@@ -53,13 +53,6 @@ export declare class TextureAtlasCreation {
53
53
  * @returns Parsed glyph data or null if not found
54
54
  */
55
55
  private _getGlyphData;
56
- /**
57
- * Gets the advance width for a glyph
58
- * @param fontData The Typr.js font data
59
- * @param glyphIndex The glyph index
60
- * @returns The advance width in font units
61
- */
62
- private _getGlyphAdvanceWidth;
63
56
  /**
64
57
  * Renders a glyph to the canvas using direct path rendering from glyph outline data.
65
58
  * @param glyphData Glyph data from Typr.js
@@ -18,12 +18,6 @@ export interface TyprBinary {
18
18
  readUint: (buff: Uint8Array, p: number) => number;
19
19
  /** Read ASCII string */
20
20
  readASCII: (buff: Uint8Array, p: number, l: number) => string;
21
- /** Write unsigned 16-bit integer (big-endian) */
22
- writeUshort: (buff: Uint8Array, p: number, n: number) => void;
23
- /** Write unsigned 32-bit integer (big-endian) */
24
- writeUint: (buff: Uint8Array, p: number, n: number) => void;
25
- /** Write ASCII string */
26
- writeASCII: (buff: Uint8Array, p: number, s: string) => void;
27
21
  /** Shared typed array buffers for efficient reading */
28
22
  t: {
29
23
  uint8: Uint8Array;
@@ -0,0 +1,5 @@
1
+ export { TextmodeImage } from './TextmodeImage';
2
+ export { TextmodeVideo } from './TextmodeVideo';
3
+ export { TextmodeFont } from './font/TextmodeFont';
4
+ export type { TextmodeCharacter } from './font/types';
5
+ export type { TextmodeVideoOptions } from './TextmodeVideo';
@@ -0,0 +1,20 @@
1
+ import type { LoadingPhaseSnapshot } from './types';
2
+ /**
3
+ * Tracks loading phases and their progress.
4
+ * @ignore
5
+ */
6
+ export declare class LoadingPhaseTracker {
7
+ private _phases;
8
+ private _phaseOrder;
9
+ private _totalWeight;
10
+ private _lastReportedProgress;
11
+ private _onProgressChange?;
12
+ get $totalWeight(): number;
13
+ get $progress(): number;
14
+ $setProgressChangeCallback(callback: (progress: number) => void): void;
15
+ $createPhase(label: string, weight?: number): string;
16
+ $updatePhaseProgress(id: string, progress: number): void;
17
+ $completePhase(id: string): void;
18
+ $failPhase(id: string): void;
19
+ $snapshotPhases(): LoadingPhaseSnapshot[];
20
+ }
@@ -0,0 +1,211 @@
1
+ import type { Textmodifier } from '../Textmodifier';
2
+ import type { RGBA } from '../utils/cssColor';
3
+ import type { LoadingPhaseHandle, LoadingScreenOptions } from './types';
4
+ /**
5
+ * Manages the loading screen display and state. Can be accessed via {@link Textmodifier.loading}.
6
+ */
7
+ export declare class LoadingScreenManager {
8
+ private readonly _textmodifier;
9
+ private readonly _options;
10
+ private readonly _stateMachine;
11
+ private readonly _phaseTracker;
12
+ private readonly _transition;
13
+ private readonly _loadingAnimationController;
14
+ private _loadingFont;
15
+ private _loadingGrid;
16
+ private _loadingDrawFramebuffer;
17
+ private _loadingFramebuffer;
18
+ private _renderer;
19
+ private _palette;
20
+ private _theme;
21
+ private _startTime;
22
+ private _loadingFrameCount;
23
+ private _isRendering;
24
+ private _isInitialized;
25
+ /**
26
+ * Initializes a new LoadingScreenManager.
27
+ * @param textmodifier Textmodifier instance to render on.
28
+ * @param opts Loading screen options.
29
+ * @param canvasBackground Background color of the canvas.
30
+ * @ignore
31
+ */
32
+ constructor(textmodifier: Textmodifier, opts: LoadingScreenOptions | undefined, canvasBackground: RGBA | null);
33
+ /**
34
+ * Initialize loading screen resources (font, grid, framebuffers).
35
+ * Must be called after the renderer is ready.
36
+ * @param fontSource Optional font source for the loading screen
37
+ * @ignore
38
+ */
39
+ $initialize(fontSource?: string): Promise<void>;
40
+ /**
41
+ * Indicates whether the loading screen should render this frame.
42
+ * @ignore
43
+ */
44
+ get $shouldRender(): boolean;
45
+ /**
46
+ * Start the independent loading screen animation loop.
47
+ * This runs independently of the user's animation loop.
48
+ * @ignore
49
+ */
50
+ $start(): void;
51
+ /**
52
+ * Stop the independent loading screen animation loop.
53
+ * @ignore
54
+ */
55
+ $stop(): void;
56
+ /**
57
+ * Handle canvas resize during loading.
58
+ * Updates grid and framebuffers to match new canvas dimensions.
59
+ * @ignore
60
+ */
61
+ $resize(): void;
62
+ /**
63
+ * Dispose of the loading screen manager and clean up resources.
64
+ * @ignore
65
+ */
66
+ $dispose(): void;
67
+ /**
68
+ * Get the current overall loading progress (0-1).
69
+ *
70
+ * @example
71
+ * ```ts
72
+ * const t = textmode.create({
73
+ * width: 800,
74
+ * height: 600,
75
+ * loadingScreen: { message: 'starting...' }
76
+ * });
77
+ *
78
+ * // In setup we can start a phase and read the overall progress
79
+ * t.setup(async () => {
80
+ * const phase = t.loading.beginPhase('assets', 1);
81
+ * phase.report(0.5); // half complete for the phase
82
+ *
83
+ * // The `progress` accessor reports the global progress across all phases
84
+ * console.log(`Loading: ${Math.round(t.loading.progress * 100)}%`);
85
+ * });
86
+ * ```
87
+ */
88
+ get progress(): number;
89
+ /**
90
+ * Get or set the loading screen message.
91
+ * @param next Optional new message to set.
92
+ * @returns The current loading screen message.
93
+ *
94
+ * @example
95
+ * ```ts
96
+ * const t = textmode.create({
97
+ * width: 800,
98
+ * height: 600,
99
+ * loadingScreen: { message: 'loading...' }
100
+ * });
101
+ *
102
+ * t.setup(() => {
103
+ * // Update the message visible on the loading screen
104
+ * t.loading.message('preloading video...');
105
+ *
106
+ * // Read the current message (useful in custom renderers)
107
+ * const msg = t.loading.message();
108
+ * console.log(msg);
109
+ * });
110
+ * ```
111
+ */
112
+ message(next?: string): string | undefined;
113
+ /**
114
+ * Begin a new loading phase.
115
+ *
116
+ * With the returned {@link LoadingPhaseHandle} you can report progress,
117
+ * track asynchronous work, and manage the phase lifecycle.
118
+ *
119
+ * @param label Label for the loading phase.
120
+ * @param weight Weight of the loading phase (default is 1).
121
+ * @returns A handle to the created loading phase.
122
+ *
123
+ * @example
124
+ * ```ts
125
+ * const t = textmode.create({
126
+ * width: 800,
127
+ * height: 600,
128
+ * loadingScreen: { message: 'preparing...' }
129
+ * });
130
+ *
131
+ * // In setup we start a phase and then track work in that phase
132
+ * t.setup(async () => {
133
+ * const phase = t.loading.beginPhase('video preload', 2);
134
+ *
135
+ * // Example: report progress from a loader callback
136
+ * await phase.track(async () => {
137
+ * // Simulated work
138
+ * for (let i = 0; i <= 10; i++) {
139
+ * phase.report(i / 10);
140
+ * await new Promise((r) => setTimeout(r, 30));
141
+ * }
142
+ * });
143
+ * });
144
+ * ```
145
+ */
146
+ addPhase(label: string, weight?: number): LoadingPhaseHandle;
147
+ /**
148
+ * Finish the loading process.
149
+ * @ignore
150
+ */
151
+ $finish(): void;
152
+ private _notifyComplete;
153
+ private _onCompleteCallback?;
154
+ /**
155
+ * Set a callback to be invoked when loading is complete.
156
+ * @param callback The callback function to invoke.
157
+ * @ignore
158
+ */
159
+ $setOnComplete(callback: () => void): void;
160
+ /**
161
+ * Report an error that occurred during loading.
162
+ * @param error The error message or `Error` object.
163
+ *
164
+ * @example
165
+ * ```ts
166
+ * const t = textmode.create({
167
+ * width: 800,
168
+ * height: 600,
169
+ * loadingScreen: { message: 'starting...' }
170
+ * });
171
+ *
172
+ * t.setup(async () => {
173
+ * const phase = t.loading.beginPhase('remote fetch', 1);
174
+ * try {
175
+ * await phase.track(async () => {
176
+ * // Failing call
177
+ * throw new Error('server down');
178
+ * });
179
+ * } catch (err) {
180
+ * // This will put the loading manager into an error state
181
+ * t.loading.error(err instanceof Error ? err : String(err));
182
+ * }
183
+ * });
184
+ * ```
185
+ */
186
+ error(error: Error | string): void;
187
+ /**
188
+ * Independent render loop for the loading screen.
189
+ * This runs on its own animation controller, separate from user animation.
190
+ * @ignore
191
+ */
192
+ private _renderLoadingFrame;
193
+ /**
194
+ * Performs the actual rendering of the loading screen.
195
+ * @ignore
196
+ */
197
+ private _performRender;
198
+ /**
199
+ * Update the background color used in the loading screen theme.
200
+ * @param color The new background color.
201
+ * @ignore
202
+ */
203
+ $updateBackgroundColor(color: RGBA | null): void;
204
+ private _resolveRenderer;
205
+ /**
206
+ * Renders the library branding tag at the bottom left of the loading screen.
207
+ * Uses obfuscation techniques to make removal more difficult.
208
+ * @ignore
209
+ */
210
+ private _renderBrandingTag;
211
+ }
@@ -0,0 +1,22 @@
1
+ import type { LoadingScreenState } from './types';
2
+ /**
3
+ * Manages the state of the loading screen.
4
+ * @ignore
5
+ */
6
+ export declare class LoadingScreenStateMachine {
7
+ private _state;
8
+ private _errorMessage;
9
+ private _errorDetails;
10
+ constructor(initialState?: LoadingScreenState);
11
+ get $state(): LoadingScreenState;
12
+ get $isEnabled(): boolean;
13
+ get $shouldRender(): boolean;
14
+ get $errorMessage(): string;
15
+ get $errorDetails(): string;
16
+ $activate(): void;
17
+ $finish(): void;
18
+ $startTransition(): void;
19
+ $completeTransition(): void;
20
+ $setError(error: Error | string): void;
21
+ $disable(): void;
22
+ }
@@ -0,0 +1,26 @@
1
+ import type { LoadingScreenTheme, LoadingScreenOptions } from './types';
2
+ import type { Textmodifier } from '../Textmodifier';
3
+ import type { TextmodeColor } from '../TextmodeColor';
4
+ /**
5
+ * Resolves the loading screen theme based on options and background color.
6
+ * @param options Loading screen options.
7
+ * @param background Background color as RGBA or null.
8
+ * @returns The resolved loading screen theme.
9
+ * @ignore
10
+ */
11
+ export declare function $resolveTheme(options: LoadingScreenOptions, background: [number, number, number, number] | null): LoadingScreenTheme;
12
+ /**
13
+ * Resolves the default color palette based on the theme mode.
14
+ * @param theme The loading screen theme.
15
+ * @returns An array of color strings representing the default palette.
16
+ * @ignore
17
+ */
18
+ export declare function $resolveDefaultPalette(theme: LoadingScreenTheme): string[];
19
+ /**
20
+ * Resolves an array of color inputs into TextmodeColor instances.
21
+ * @param inputs Input colors as numbers, strings, or TextmodeColor instances.
22
+ * @param textmodifier The Textmodifier instance used to create TextmodeColor objects.
23
+ * @returns An array of TextmodeColor instances.
24
+ * @ignore
25
+ */
26
+ export declare function $resolveColorInputs(inputs: (number | string | TextmodeColor)[], textmodifier: Textmodifier): TextmodeColor[];
@@ -0,0 +1,17 @@
1
+ export type TransitionType = 'none' | 'fade';
2
+ /**
3
+ * Handles loading screen transitions.
4
+ * @ignore
5
+ */
6
+ export declare class LoadingScreenTransition {
7
+ private _transitionStartTime;
8
+ private _transitionOpacity;
9
+ private _transitionType;
10
+ private _transitionDuration;
11
+ constructor(transitionType: TransitionType, transitionDuration: number);
12
+ get $opacity(): number;
13
+ get $isTransitioning(): boolean;
14
+ $start(): void;
15
+ $update(): boolean;
16
+ $reset(): void;
17
+ }