drawnui-react 0.1.0-preview.9 → 1.0.1

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 (117) hide show
  1. package/README.md +229 -22
  2. package/SKIPPED.md +37 -28
  3. package/dist/controls/AnimatedFramesRenderer.d.ts +9 -0
  4. package/dist/controls/AnimatedFramesRenderer.js +18 -1
  5. package/dist/controls/DrawnGame.d.ts +44 -0
  6. package/dist/controls/DrawnGame.js +82 -0
  7. package/dist/controls/GridStructure.d.ts +25 -3
  8. package/dist/controls/GridStructure.js +81 -5
  9. package/dist/controls/SkiaBackdrop.d.ts +8 -2
  10. package/dist/controls/SkiaBackdrop.js +42 -14
  11. package/dist/controls/SkiaButton.d.ts +17 -3
  12. package/dist/controls/SkiaButton.js +26 -8
  13. package/dist/controls/SkiaCarousel.d.ts +22 -3
  14. package/dist/controls/SkiaCarousel.js +85 -9
  15. package/dist/controls/SkiaCheckbox.d.ts +0 -1
  16. package/dist/controls/SkiaCheckbox.js +2 -7
  17. package/dist/controls/SkiaDrawer.d.ts +15 -0
  18. package/dist/controls/SkiaDrawer.js +42 -7
  19. package/dist/controls/SkiaEditor.d.ts +51 -2
  20. package/dist/controls/SkiaEditor.js +292 -58
  21. package/dist/controls/SkiaGif.d.ts +7 -0
  22. package/dist/controls/SkiaGif.js +25 -4
  23. package/dist/controls/SkiaImage.d.ts +10 -0
  24. package/dist/controls/SkiaImage.js +80 -19
  25. package/dist/controls/SkiaLabel.d.ts +200 -11
  26. package/dist/controls/SkiaLabel.js +925 -93
  27. package/dist/controls/SkiaLabelFps.d.ts +12 -0
  28. package/dist/controls/SkiaLabelFps.js +35 -0
  29. package/dist/controls/SkiaLayout.d.ts +89 -9
  30. package/dist/controls/SkiaLayout.js +397 -23
  31. package/dist/controls/SkiaLottie.js +5 -3
  32. package/dist/controls/SkiaProgress.d.ts +2 -1
  33. package/dist/controls/SkiaProgress.js +8 -5
  34. package/dist/controls/SkiaRadioButton.d.ts +2 -0
  35. package/dist/controls/SkiaRadioButton.js +16 -4
  36. package/dist/controls/SkiaRichLabel.d.ts +1 -1
  37. package/dist/controls/SkiaRichLabel.js +11 -1
  38. package/dist/controls/SkiaScroll.d.ts +86 -7
  39. package/dist/controls/SkiaScroll.js +361 -40
  40. package/dist/controls/SkiaScrollBar.d.ts +27 -0
  41. package/dist/controls/SkiaScrollBar.js +51 -2
  42. package/dist/controls/SkiaShaderCarousel.d.ts +11 -1
  43. package/dist/controls/SkiaShaderCarousel.js +27 -5
  44. package/dist/controls/SkiaShape.d.ts +15 -2
  45. package/dist/controls/SkiaShape.js +57 -10
  46. package/dist/controls/SkiaShell.d.ts +282 -0
  47. package/dist/controls/SkiaShell.js +972 -0
  48. package/dist/controls/SkiaSlider.d.ts +20 -2
  49. package/dist/controls/SkiaSlider.js +61 -7
  50. package/dist/controls/SkiaSprite.d.ts +4 -0
  51. package/dist/controls/SkiaSprite.js +27 -11
  52. package/dist/controls/SkiaSvg.d.ts +4 -0
  53. package/dist/controls/SkiaSvg.js +28 -4
  54. package/dist/controls/SkiaSwitch.d.ts +0 -1
  55. package/dist/controls/SkiaSwitch.js +4 -8
  56. package/dist/controls/SkiaToggle.d.ts +25 -5
  57. package/dist/controls/SkiaToggle.js +58 -5
  58. package/dist/controls/SnappingLayout.d.ts +12 -1
  59. package/dist/controls/SnappingLayout.js +21 -2
  60. package/dist/controls/TooltipStyle.d.ts +52 -0
  61. package/dist/controls/TooltipStyle.js +88 -0
  62. package/dist/core/Accessibility.d.ts +162 -11
  63. package/dist/core/Accessibility.js +882 -22
  64. package/dist/core/Animators.d.ts +37 -1
  65. package/dist/core/Animators.js +102 -9
  66. package/dist/core/Canvas.d.ts +307 -8
  67. package/dist/core/Canvas.js +1202 -66
  68. package/dist/core/ControlStyle.d.ts +2 -0
  69. package/dist/core/ControlStyle.js +2 -0
  70. package/dist/core/DesignerActions.d.ts +32 -0
  71. package/dist/core/DesignerActions.js +68 -0
  72. package/dist/core/Easing.d.ts +12 -1
  73. package/dist/core/Easing.js +25 -1
  74. package/dist/core/Gestures.d.ts +86 -2
  75. package/dist/core/Gestures.js +184 -4
  76. package/dist/core/Hover.d.ts +51 -0
  77. package/dist/core/Hover.js +140 -0
  78. package/dist/core/ImageEffects.d.ts +2 -0
  79. package/dist/core/ImageEffects.js +2 -0
  80. package/dist/core/KeyboardManager.d.ts +40 -0
  81. package/dist/core/KeyboardManager.js +98 -8
  82. package/dist/core/PopupWindows.d.ts +94 -0
  83. package/dist/core/PopupWindows.js +207 -0
  84. package/dist/core/Props.d.ts +11 -0
  85. package/dist/core/Props.js +44 -0
  86. package/dist/core/ScrollAnimators.d.ts +6 -0
  87. package/dist/core/ScrollAnimators.js +16 -1
  88. package/dist/core/Shaping.d.ts +40 -0
  89. package/dist/core/Shaping.js +224 -0
  90. package/dist/core/SkiaControl.d.ts +306 -13
  91. package/dist/core/SkiaControl.js +681 -75
  92. package/dist/core/SkiaEffect.d.ts +29 -1
  93. package/dist/core/SkiaEffect.js +78 -16
  94. package/dist/core/SkiaImageManager.d.ts +101 -18
  95. package/dist/core/SkiaImageManager.js +318 -63
  96. package/dist/core/Styles.js +7 -1
  97. package/dist/core/Super.d.ts +33 -2
  98. package/dist/core/Super.js +58 -12
  99. package/dist/core/TextInputProxy.d.ts +31 -1
  100. package/dist/core/TextInputProxy.js +97 -15
  101. package/dist/core/Tooltips.d.ts +71 -0
  102. package/dist/core/Tooltips.js +205 -0
  103. package/dist/core/Types.d.ts +11 -1
  104. package/dist/core/Types.js +32 -1
  105. package/dist/core/ViewsAdapter.d.ts +7 -2
  106. package/dist/core/ViewsAdapter.js +10 -3
  107. package/dist/index.d.ts +8 -0
  108. package/dist/index.js +8 -0
  109. package/dist/react/SkiaShell.d.ts +8 -74
  110. package/dist/react/SkiaShell.js +163 -475
  111. package/dist/react/index.d.ts +48 -4
  112. package/dist/react/index.js +210 -43
  113. package/dist/react/reconciler.d.ts +32 -0
  114. package/dist/react/reconciler.js +71 -40
  115. package/dist/vite/index.d.ts +9 -0
  116. package/dist/vite/index.js +36 -3
  117. package/package.json +103 -5
@@ -59,6 +59,14 @@ export declare function IsPostRendererEffect(e: SkiaEffect): e is SkiaEffect & I
59
59
  * skipped, declared texture children that are not supplied sample transparent.
60
60
  */
61
61
  export declare class SkiaShaderEffect extends SkiaEffect implements IPostRendererEffect {
62
+ /**
63
+ * The clock origin of every shader's iTime: the page time (ms) of the first shader frame, one for all effects so
64
+ * they stay in step (C# ShaderTimeOriginNanos). iTime is a float32 on the GPU: counted from the page load, a tab open
65
+ * for days would move it in visible steps (0.125 s after 18 days).
66
+ */
67
+ static ShaderTimeOrigin?: number;
68
+ /** Seconds since the first shader frame for a page time in ms, taken in double before the GPU's float (C# GetShaderTime). */
69
+ static GetShaderTime(nowMs: number): number;
62
70
  /** Url of the .sksl file (fetched once, compiled once per text). */
63
71
  get ShaderSource(): string;
64
72
  set ShaderSource(v: string);
@@ -79,7 +87,7 @@ export declare class SkiaShaderEffect extends SkiaEffect implements IPostRendere
79
87
  MipmapMode: SkiaMipmapMode;
80
88
  /** Tile mode of the input textures. */
81
89
  TileMode: ShaderTileMode;
82
- /** Set every Render from the frame time (seconds); can be driven manually. */
90
+ /** Set every Render: seconds since the first shader frame (GetShaderTime); can be driven manually. */
83
91
  TimeSeconds: number;
84
92
  /** Shadertoy iMouse.xy, pixels relative to the control. */
85
93
  MouseCurrent: {
@@ -119,12 +127,29 @@ export declare class SkiaShaderEffect extends SkiaEffect implements IPostRendere
119
127
  get NeedApply(): boolean;
120
128
  /** Loads (async, once) and compiles (sync) when needed; true when a compiled effect exists. */
121
129
  EnsureCompiled(): boolean;
130
+ /**
131
+ * C# ShouldInvalidateParentCache (default false): animation ticks, `SetUniform` and `UpdateUniforms()` only redraw
132
+ * this effect over the parent's cache (ancestor caches still redraw), because the effect paints over the parent's
133
+ * cached content and a uniform change needs no new cache. True: they also invalidate the parent's cache, so the parent
134
+ * re-renders its content on every change; set it when that content refreshes only through the effect's redraws (a
135
+ * custom Paint reading changing data without calling Update()). `Update()` always invalidates the cache.
136
+ */
137
+ ShouldInvalidateParentCache: boolean;
138
+ /** Call after changing a value only the shader reads (a uniform, an animation progress): redraws the effect over the parent's cache, or `Update()` when ShouldInvalidateParentCache is true. */
139
+ UpdateUniforms(): void;
122
140
  SetUniform(name: string, ...values: number[]): this;
123
141
  ReleaseFrozenSnapshot(): void;
124
142
  private DisposeImage;
125
143
  protected ApplyShaderSource(): void;
126
144
  /** Snapshot of what the parent painted (C# CreateSnapshot): the surface the pixels are on, mapped through its origin. */
127
145
  protected CreateSnapshot(ctx: DrawingContext, destination: SKRect): CachedTexture | undefined;
146
+ private frozenEpoch;
147
+ /** Canvas.GpuEpoch: GPU textures made before a WebGL context restore are made again. */
148
+ protected GpuEpoch(): number;
149
+ /** Where the parent was when the texture was frozen (Once): the texture moves with it, as its cache does. */
150
+ private frozenAt?;
151
+ private ParentOrigin;
152
+ private FollowParent;
128
153
  /** C# GetPrimaryTexture: the parent's cache, a frozen snapshot (Once) or nothing (Never). */
129
154
  protected GetPrimaryTexture(_ctx: DrawingContext, _destination: SKRect): CachedTexture | undefined;
130
155
  /** Image → shader with the effect's sampling, translated so texel (0,0) = bounds top-left; cached per image. */
@@ -165,6 +190,9 @@ export declare class ShaderDoubleTexturesEffect extends SkiaShaderEffect {
165
190
  set PrimarySource(v: string);
166
191
  get SecondarySource(): string;
167
192
  set SecondarySource(v: string);
193
+ /** The textures it draws are held while it draws them (SkiaImageManager.Hold / Free). */
194
+ private HoldPrimary;
195
+ private HoldSecondary;
168
196
  private controlFrom?;
169
197
  private controlTo?;
170
198
  private primarySource;
@@ -2,7 +2,7 @@ import { SkiaValueAnimator } from "./Animators";
2
2
  import { Easing } from "./Easing";
3
3
  import { SkiaImageManager } from "./SkiaImageManager";
4
4
  import { Super } from "./Super";
5
- import { Thickness } from "./Types";
5
+ import { SKRect, Thickness } from "./Types";
6
6
  /**
7
7
  * Mirrors DrawnUi SkiaEffect: something attached to a control through `VisualEffects`. `Update()` re-renders the
8
8
  * parent (C# invalidates the parent's cache and redraws), `GetEffectMargin` reports what it paints outside the box.
@@ -45,6 +45,17 @@ const sourceCache = new Map();
45
45
  * skipped, declared texture children that are not supplied sample transparent.
46
46
  */
47
47
  export class SkiaShaderEffect extends SkiaEffect {
48
+ /**
49
+ * The clock origin of every shader's iTime: the page time (ms) of the first shader frame, one for all effects so
50
+ * they stay in step (C# ShaderTimeOriginNanos). iTime is a float32 on the GPU: counted from the page load, a tab open
51
+ * for days would move it in visible steps (0.125 s after 18 days).
52
+ */
53
+ static ShaderTimeOrigin;
54
+ /** Seconds since the first shader frame for a page time in ms, taken in double before the GPU's float (C# GetShaderTime). */
55
+ static GetShaderTime(nowMs) {
56
+ SkiaShaderEffect.ShaderTimeOrigin ??= nowMs;
57
+ return (nowMs - SkiaShaderEffect.ShaderTimeOrigin) / 1000;
58
+ }
48
59
  /** Url of the .sksl file (fetched once, compiled once per text). */
49
60
  get ShaderSource() { return this.shaderSource; }
50
61
  set ShaderSource(v) { if (this.shaderSource !== v) {
@@ -74,7 +85,7 @@ export class SkiaShaderEffect extends SkiaEffect {
74
85
  MipmapMode = "None";
75
86
  /** Tile mode of the input textures. */
76
87
  TileMode = "Clamp";
77
- /** Set every Render from the frame time (seconds); can be driven manually. */
88
+ /** Set every Render: seconds since the first shader frame (GetShaderTime); can be driven manually. */
78
89
  TimeSeconds = 0;
79
90
  /** Shadertoy iMouse.xy, pixels relative to the control. */
80
91
  MouseCurrent = { X: 0, Y: 0 };
@@ -116,11 +127,27 @@ export class SkiaShaderEffect extends SkiaEffect {
116
127
  }
117
128
  return this.compiled !== undefined;
118
129
  }
130
+ /**
131
+ * C# ShouldInvalidateParentCache (default false): animation ticks, `SetUniform` and `UpdateUniforms()` only redraw
132
+ * this effect over the parent's cache (ancestor caches still redraw), because the effect paints over the parent's
133
+ * cached content and a uniform change needs no new cache. True: they also invalidate the parent's cache, so the parent
134
+ * re-renders its content on every change; set it when that content refreshes only through the effect's redraws (a
135
+ * custom Paint reading changing data without calling Update()). `Update()` always invalidates the cache.
136
+ */
137
+ ShouldInvalidateParentCache = false;
138
+ /** Call after changing a value only the shader reads (a uniform, an animation progress): redraws the effect over the parent's cache, or `Update()` when ShouldInvalidateParentCache is true. */
139
+ UpdateUniforms() {
140
+ if (this.ShouldInvalidateParentCache) {
141
+ this.Update();
142
+ return;
143
+ }
144
+ this.Parent?.RepaintComposition();
145
+ }
119
146
  // ---- uniforms API (C# SetUniform overloads) ----
120
147
  SetUniform(name, ...values) {
121
148
  if (name && values.length > 0) {
122
149
  this.Uniforms.set(name, values);
123
- this.Update();
150
+ this.UpdateUniforms();
124
151
  }
125
152
  return this;
126
153
  }
@@ -129,6 +156,7 @@ export class SkiaShaderEffect extends SkiaEffect {
129
156
  this.DisposeImage(this.frozen.Image);
130
157
  this.frozen = undefined;
131
158
  this.frozenOwned = false;
159
+ this.frozenAt = undefined;
132
160
  }
133
161
  DisposeImage(image) {
134
162
  const sv = this.Parent?.Superview;
@@ -158,12 +186,27 @@ export class SkiaShaderEffect extends SkiaEffect {
158
186
  return undefined;
159
187
  return { Image: image, Bounds: destination, Origin: { X: ox, Y: oy } };
160
188
  }
189
+ frozenEpoch = 0;
190
+ /** Canvas.GpuEpoch: GPU textures made before a WebGL context restore are made again. */
191
+ GpuEpoch() { return this.Parent?.Superview?.GpuEpoch ?? 0; }
192
+ /** Where the parent was when the texture was frozen (Once): the texture moves with it, as its cache does. */
193
+ frozenAt;
194
+ ParentOrigin() { const r = this.Parent?.DrawingRect; return { X: r?.Left ?? 0, Y: r?.Top ?? 0 }; }
195
+ FollowParent(texture) {
196
+ if (!texture || !this.frozenAt)
197
+ return texture;
198
+ const now = this.ParentOrigin(), dx = now.X - this.frozenAt.X, dy = now.Y - this.frozenAt.Y;
199
+ if (dx === 0 && dy === 0)
200
+ return texture;
201
+ const b = texture.Bounds;
202
+ return { Image: texture.Image, Bounds: new SKRect(b.Left + dx, b.Top + dy, b.Right + dx, b.Bottom + dy), Origin: texture.Origin && { X: texture.Origin.X + dx, Y: texture.Origin.Y + dy } };
203
+ }
161
204
  /** C# GetPrimaryTexture: the parent's cache, a frozen snapshot (Once) or nothing (Never). */
162
205
  GetPrimaryTexture(_ctx, _destination) {
163
206
  switch (this.UseBackground) {
164
207
  case "Never": return undefined;
165
208
  case "Once":
166
- if (!this.AquiredBackground || !this.frozen) {
209
+ if (!this.AquiredBackground || !this.frozen || this.frozenEpoch !== this.GpuEpoch()) { // a frozen texture of a lost GPU context is taken again
167
210
  this.ReleaseFrozenSnapshot();
168
211
  let snapshot = this.Parent?.CachedImage;
169
212
  let owned = false;
@@ -175,9 +218,11 @@ export class SkiaShaderEffect extends SkiaEffect {
175
218
  this.frozen = snapshot;
176
219
  this.frozenOwned = owned;
177
220
  this.AquiredBackground = true;
221
+ this.frozenAt = this.ParentOrigin();
222
+ this.frozenEpoch = this.GpuEpoch();
178
223
  }
179
224
  }
180
- return this.frozen;
225
+ return this.FollowParent(this.frozen);
181
226
  default:
182
227
  return this.Parent?.CachedImage;
183
228
  }
@@ -228,7 +273,7 @@ export class SkiaShaderEffect extends SkiaEffect {
228
273
  static async FetchText(url) {
229
274
  let p = sourceCache.get(url);
230
275
  if (!p) {
231
- p = fetch(url).then((r) => { if (!r.ok)
276
+ p = fetch(Super.ResolveAssetUrl(url)).then((r) => { if (!r.ok)
232
277
  throw new Error(`${r.status} ${url}`); return r.text(); });
233
278
  sourceCache.set(url, p);
234
279
  }
@@ -346,7 +391,7 @@ export class SkiaShaderEffect extends SkiaEffect {
346
391
  }
347
392
  /** IPostRendererEffect: draws the shader over ctx.Destination (C# Render). */
348
393
  Render(ctx) {
349
- this.TimeSeconds = performance.now() / 1000;
394
+ this.TimeSeconds = SkiaShaderEffect.GetShaderTime(performance.now());
350
395
  const texture = this.GetPrimaryTexture(ctx, ctx.Destination);
351
396
  const built = this.CreateShader(ctx, texture);
352
397
  if (!built)
@@ -389,15 +434,18 @@ export class ShaderDoubleTexturesEffect extends SkiaShaderEffect {
389
434
  get PrimarySource() { return this.primarySource; }
390
435
  set PrimarySource(v) { if (this.primarySource !== v) {
391
436
  this.primarySource = v;
392
- this.primaryImage = undefined;
393
- this.LoadTexture(v, (i) => { this.primaryImage = i; this.Update(); });
437
+ this.HoldPrimary(undefined);
438
+ this.LoadTexture(v, (i) => { this.HoldPrimary(i); this.Update(); });
394
439
  } }
395
440
  get SecondarySource() { return this.secondarySource; }
396
441
  set SecondarySource(v) { if (this.secondarySource !== v) {
397
442
  this.secondarySource = v;
398
- this.secondaryImage = undefined;
399
- this.LoadTexture(v, (i) => { this.secondaryImage = i; this.secondary?.delete(); this.secondary = undefined; this.Update(); });
443
+ this.HoldSecondary(undefined);
444
+ this.LoadTexture(v, (i) => { this.HoldSecondary(i); this.secondary?.delete(); this.secondary = undefined; this.Update(); });
400
445
  } }
446
+ /** The textures it draws are held while it draws them (SkiaImageManager.Hold / Free). */
447
+ HoldPrimary(i) { const old = this.primaryImage; this.primaryImage = i; SkiaImageManager.Instance.Hold(i); SkiaImageManager.Instance.Free(old); }
448
+ HoldSecondary(i) { const old = this.secondaryImage; this.secondaryImage = i; SkiaImageManager.Instance.Hold(i); SkiaImageManager.Instance.Free(old); }
401
449
  controlFrom;
402
450
  controlTo;
403
451
  primarySource = "";
@@ -410,8 +458,18 @@ export class ShaderDoubleTexturesEffect extends SkiaShaderEffect {
410
458
  LoadTexture(url, done) {
411
459
  if (!url)
412
460
  return;
413
- SkiaImageManager.Instance.LoadImageAsync(url).then((i) => { if (url === this.primarySource || url === this.secondarySource)
414
- done(i); }).catch((e) => this.SendError(String(e)));
461
+ SkiaImageManager.Instance.LoadImageManagedAsync(url).then((i) => {
462
+ if (!i) {
463
+ this.SendError(`DrawnUi: cannot load image '${url}'`);
464
+ return;
465
+ }
466
+ if (url !== this.primarySource && url !== this.secondarySource) {
467
+ SkiaImageManager.Instance.Hold(i);
468
+ SkiaImageManager.Instance.Free(i);
469
+ return;
470
+ }
471
+ done(i);
472
+ });
415
473
  }
416
474
  /** C# Resize*LoadedBitmap: the file texture spans the parent box. */
417
475
  Resized(ctx, source, slot) {
@@ -420,7 +478,8 @@ export class ShaderDoubleTexturesEffect extends SkiaShaderEffect {
420
478
  return undefined;
421
479
  const w = Math.round(d.Width), h = Math.round(d.Height);
422
480
  const cur = slot === "p" ? this.resizedPrimary : this.resizedSecondary;
423
- if (cur && cur.source === source && cur.w === w && cur.h === h)
481
+ const epoch = this.GpuEpoch();
482
+ if (cur && cur.source === source && cur.w === w && cur.h === h && cur.epoch === epoch)
424
483
  return cur.image;
425
484
  const main = ctx.Context.Surface;
426
485
  if (!main)
@@ -435,7 +494,7 @@ export class ShaderDoubleTexturesEffect extends SkiaShaderEffect {
435
494
  const image = surface.makeImageSnapshot();
436
495
  surface.delete();
437
496
  cur?.image.delete();
438
- const entry = { source, w, h, image };
497
+ const entry = { source, w, h, epoch, image };
439
498
  if (slot === "p")
440
499
  this.resizedPrimary = entry;
441
500
  else
@@ -485,6 +544,9 @@ export class ShaderDoubleTexturesEffect extends SkiaShaderEffect {
485
544
  this.resizedSecondary = undefined;
486
545
  this.controlFrom = undefined;
487
546
  this.controlTo = undefined;
547
+ this.primarySource = this.secondarySource = "";
548
+ this.HoldPrimary(undefined);
549
+ this.HoldSecondary(undefined);
488
550
  super.OnDisposing();
489
551
  }
490
552
  }
@@ -546,7 +608,7 @@ export class AnimatedShaderEffect extends SkiaShaderEffect {
546
608
  return;
547
609
  if (!this.Animator) {
548
610
  const a = new SkiaValueAnimator(parent);
549
- a.OnUpdated = (v) => { this.Progress = v; this.Update(); };
611
+ a.OnUpdated = (v) => { this.Progress = v; this.UpdateUniforms(); };
550
612
  a.Finished = () => this.Completed?.(this);
551
613
  this.Animator = a;
552
614
  }
@@ -2,42 +2,125 @@ import type { Image } from "canvaskit-wasm";
2
2
  /** C# LoadPriority: order of the managed load queue. */
3
3
  export type LoadPriority = "Low" | "Normal" | "High";
4
4
  /**
5
- * Mirrors DrawnUi SkiaImageManager: loads + decodes image sources once and shares the decoded CanvasKit Image
6
- * between all SkiaImage instances using the same source (`ReuseBitmaps`). `LoadImageManagedAsync` goes through the
7
- * priority queue (High > Normal > Low, at most `MaxParallelLoads` fetches in flight, C# semaphore of 5; the same
8
- * source requested twice is fetched once), `LoadImageAsync` loads directly. `PreloadImages` warms the cache,
9
- * `CancelAll` drops what is still queued. Sources are URLs (absolute, or relative to the page like "images/photo.jpg").
5
+ * Mirrors DrawnUi SkiaImageManager (DrawnUi.Net): loads and decodes image sources, keeps the decoded images in a cache
6
+ * by source for `CacheLongevitySecs`, and shares one decoded image between every control on the same source
7
+ * (`ReuseBitmaps`; off, each caller gets a copy of its own of the one cached copy). `LoadImageManagedAsync` caches and
8
+ * goes through the priority queue (High > Normal > Low, at most `MaxParallelLoads` fetches in flight; the same source
9
+ * requested twice is fetched once); `LoadImageAsync` is a direct load that does not touch the cache. The cache keeps
10
+ * at most `CacheBudgetMb` megabytes of decoded pixels: over it, images no control holds go, the one held longest ago first
11
+ * (as DrawnUI for Rust's image cache); images a control holds never go. Keys are case-insensitive and local paths
12
+ * normalized (backslashes, a leading slash). Sources are URLs (absolute, or relative to the page like
13
+ * "images/photo.jpg").
14
+ *
15
+ * Ownership: CanvasKit images must be deleted by hand. The manager deletes an image it made once no holder draws it
16
+ * and the cache no longer keeps it; a control holds the image it shows (`Hold`) and lets it go (`Free`). Removing an
17
+ * entry from the cache (`RemoveFromCache`, `ClearCache`, expiry, the budget) never deletes an image a control holds.
10
18
  */
11
19
  export declare class SkiaImageManager {
12
20
  static readonly Instance: SkiaImageManager;
13
- /** Keep decoded images for reuse across controls (DrawnUi ReuseBitmaps). */
21
+ /** Share one decoded image between every control on the same source (DrawnUi ReuseBitmaps, on by default). */
14
22
  static ReuseBitmaps: boolean;
23
+ /** Use the cache at all (DrawnUi UseCache): off, every load fetches and decodes again. */
24
+ static UseCache: boolean;
25
+ /** Seconds a cached image is kept before the next load fetches it again (DrawnUi, 30 minutes). */
26
+ static CacheLongevitySecs: number;
27
+ /**
28
+ * Most megabytes of decoded pixels the cache keeps (DrawnUi CacheBudgetMb, 128 as DrawnUI for Rust; 0 or less = no
29
+ * limit). Images a control holds never go for it.
30
+ */
31
+ static CacheBudgetMb: number;
15
32
  /** Fetches in flight at once through the managed queue (C# CreateSemaphoreForLocalFiles: 5). */
16
33
  static MaxParallelLoads: number;
17
- /** C# CanReload: raised when a queued load failed so the caller may retry later. */
18
- CanReload?: (source: string, error: Error) => void;
34
+ /** Retry a failed load (DrawnUi EnableHttpRetry): up to HttpRetryMaxAttempts more times, 100, 200, 400 ms apart. */
35
+ static EnableHttpRetry: boolean;
36
+ static HttpRetryMaxAttempts: number;
37
+ /** Base address of relative sources (DrawnUi HttpBaseAddress); unset, they resolve against the page. */
38
+ static HttpBaseAddress?: string;
39
+ /** C# CanReload: raised when `IsLoadingLocked` is turned off, so what waited or failed meanwhile may load again. */
40
+ CanReload?: () => void;
19
41
  private readonly cache;
20
- private readonly pending;
42
+ /** Every image the manager made and still tracks: cached ones and the copies it handed out. */
43
+ private readonly owned;
44
+ private readonly inflight;
21
45
  private readonly queue;
22
46
  private readonly waiting;
47
+ private readonly registered;
23
48
  private running;
49
+ private used;
50
+ private tick;
51
+ private locked;
52
+ private unlocked;
53
+ private unlock?;
24
54
  /** Queue diagnostics. */
25
55
  get QueuedCount(): number;
26
56
  get RunningCount(): number;
27
- /** Cached decoded image, if loaded already (C# GetFromCache). */
28
- GetFromCache(source: string): Image | undefined;
29
- /** Direct load without the queue (C# LoadImageAsync); cached and de-duplicated. Rejects on network/decode failure. */
30
- LoadImageAsync(source: string, signal?: AbortSignal): Promise<Image>;
57
+ /** Megabytes of decoded pixels the cache holds now (DrawnUi CacheMemoryMb). */
58
+ get CacheMemoryMb(): number;
59
+ /** The browser says it has no network. */
60
+ get IsOffline(): boolean;
61
+ /** While true, managed loads wait (DrawnUi IsLoadingLocked); turning it off lets them go and raises CanReload. */
62
+ get IsLoadingLocked(): boolean;
63
+ set IsLoadingLocked(value: boolean);
64
+ /** Registers a source under a name of its own (DrawnUi RegisterImage): loading `alias` loads `source`. */
65
+ RegisterImage(alias: string, source?: string): void;
66
+ /** Cache key: case-insensitive, a local path with forward slashes and no leading slash (DrawnUi GetCacheKey). */
67
+ static Key(source: string): string;
68
+ /** A holder (a control) draws this image now: it is not deleted until let go. Images the manager did not make are ignored. */
69
+ Hold(image: Image | undefined): void;
70
+ /** The holder no longer draws it: an image no holder draws and the cache does not keep is deleted. */
71
+ Free(image: Image | undefined): void;
72
+ /** Deletes an image nobody keeps any more. */
73
+ private Forget;
74
+ private Track;
75
+ /** A copy of an image of its own (ReuseBitmaps off), tracked so its holder frees it. */
76
+ private Copy;
77
+ /** What a caller gets of a cached image: the shared one, or a copy of its own (ReuseBitmaps off). */
78
+ private HandOut;
79
+ /** Puts an image in the cache for `cacheLongevitySecs` (DrawnUi AddToCache); false when cached already or caching is off. */
80
+ AddToCache(uri: string, image: Image, cacheLongevitySecs?: number): boolean;
81
+ /** Replaces the cached image of a source (DrawnUi UpdateInCache, minutes as .NET). */
82
+ UpdateInCache(uri: string, image: Image, cacheLongevityMinutes: number): void;
83
+ /** Drops the image from the cache, so the next load reads it again (DrawnUi RemoveFromCache); false when it was not cached. */
84
+ RemoveFromCache(uri: string): boolean;
85
+ /** Drops every cached image; images controls still show stay until they let them go. */
86
+ ClearCache(): void;
87
+ /** RemoveFromCache(source) or ClearCache(). */
88
+ Clear(source?: string): void;
89
+ private Drop;
90
+ private CleanupExpired;
91
+ /** Over the budget: the cached images no holder draws go, the one held longest ago first (DrawnUI for Rust trim). */
92
+ Trim(): void;
93
+ /** The cached image of a source, or undefined (DrawnUi GetFromCache): the shared one, or a copy (ReuseBitmaps off). */
94
+ GetFromCache(url: string): Image | undefined;
95
+ /** The cached image itself, whatever ReuseBitmaps says (DrawnUi GetFromCacheInternal). */
96
+ GetFromCacheInternal(url: string): Image | undefined;
97
+ /** The address a source is fetched from: its registered file, against HttpBaseAddress, stamped (Super.ResolveAssetUrl). */
98
+ private Address;
99
+ /** Fetches and decodes a source, retried when it fails (EnableHttpRetry); undefined when it could not be loaded. */
31
100
  private Fetch;
32
- /** Queued load (C# LoadImageManagedAsync): cached images resolve at once, the rest wait their turn by priority. */
33
- LoadImageManagedAsync(source: string, signal?: AbortSignal, priority?: LoadPriority): Promise<Image>;
101
+ /**
102
+ * Direct load without the queue and the cache (C# LoadImageAsync): a new image the caller owns (delete it, or hand it
103
+ * to a control that holds it); undefined when it could not be loaded.
104
+ */
105
+ LoadImageAsync(source: string, signal?: AbortSignal): Promise<Image | undefined>;
106
+ /**
107
+ * Queued, cached load (C# LoadImageManagedAsync): a cached image resolves at once, the rest wait their turn by priority;
108
+ * one fetch serves every request of the same source. Resolves to the shared image (ReuseBitmaps) or a copy of its own,
109
+ * undefined when it could not be loaded. As the DrawnUi.Net Blazor head: when the caller's signal aborts a cached load,
110
+ * or a load waiting for IsLoadingLocked, the promise rejects with the abort (an AbortError, C# OperationCanceledException);
111
+ * with UseCache off a cancelled load resolves to undefined.
112
+ */
113
+ LoadImageManagedAsync(source: string, signal?: AbortSignal, priority?: LoadPriority): Promise<Image | undefined>;
114
+ /** C# Task.WaitAsync(token): rejects with the abort when the signal aborts; the load itself goes on for the others. */
115
+ private static WithCancel;
116
+ private Enqueue;
117
+ /** A fresh image goes into the cache; the cached one (an equal source loaded meanwhile) wins. */
118
+ private Cached;
34
119
  private Pump;
35
120
  /** C# PreloadImage: warms the cache for one source; failures are ignored. */
36
121
  PreloadImage(source: string, priority?: LoadPriority): Promise<void>;
37
122
  /** Warms the cache so first paint of these images is instant (DrawnUi PreloadImages). Failures are ignored. */
38
123
  PreloadImages(sources: string[], priority?: LoadPriority): Promise<void>;
39
- /** Drops everything still waiting in the queue (C# CancelAll); loads already in flight finish. */
124
+ /** Drops everything still waiting in the queue (C# CancelAll): those loads resolve to nothing; loads in flight finish. */
40
125
  CancelAll(): void;
41
- /** Drops a cached image (or everything) — decoded images hold GPU/WASM memory. */
42
- Clear(source?: string): void;
43
126
  }