pixi-silk 0.1.0 → 1.0.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 (214) hide show
  1. package/CHANGELOG.md +114 -0
  2. package/README.md +48 -68
  3. package/dist/SilkGraphics.d.ts +270 -55
  4. package/dist/SilkGraphics.js +909 -147
  5. package/dist/app.d.ts +32 -16
  6. package/dist/app.js +44 -10
  7. package/dist/atlas.d.ts +13 -6
  8. package/dist/atlas.js +13 -6
  9. package/dist/batch.d.ts +63 -0
  10. package/dist/batch.js +327 -0
  11. package/dist/color.d.ts +4 -1
  12. package/dist/color.js +9 -4
  13. package/dist/constants.js +31 -5
  14. package/dist/curves.d.ts +9 -3
  15. package/dist/curves.js +11 -5
  16. package/dist/glass/Glass.d.ts +62 -0
  17. package/dist/glass/Glass.js +135 -0
  18. package/dist/glass/GlassFilter.d.ts +33 -0
  19. package/dist/glass/GlassFilter.js +264 -0
  20. package/dist/glass/glass-wgsl.js +129 -0
  21. package/dist/glass/options.d.ts +63 -0
  22. package/dist/glass/options.js +55 -0
  23. package/dist/glass.d.ts +4 -0
  24. package/dist/glass.js +4 -0
  25. package/dist/glow/Glow.d.ts +60 -0
  26. package/dist/glow/Glow.js +65 -0
  27. package/dist/glow/aurora.d.ts +66 -0
  28. package/dist/glow/aurora.js +133 -0
  29. package/dist/glow/light.d.ts +38 -0
  30. package/dist/glow/light.js +83 -0
  31. package/dist/glow/recipes.d.ts +37 -0
  32. package/dist/glow/recipes.js +154 -0
  33. package/dist/glow/shapes.d.ts +13 -0
  34. package/dist/glow/shapes.js +34 -0
  35. package/dist/glow.d.ts +6 -0
  36. package/dist/glow.js +6 -0
  37. package/dist/gradient.d.ts +57 -4
  38. package/dist/gradient.js +142 -4
  39. package/dist/history.d.ts +194 -0
  40. package/dist/history.js +350 -0
  41. package/dist/hit.js +160 -26
  42. package/dist/index.d.ts +6 -5
  43. package/dist/index.js +4 -3
  44. package/dist/layout/flex.js +409 -0
  45. package/dist/layout/node.d.ts +53 -0
  46. package/dist/layout/node.js +117 -0
  47. package/dist/layout/style.d.ts +115 -0
  48. package/dist/layout.d.ts +3 -0
  49. package/dist/layout.js +2 -0
  50. package/dist/motion.d.ts +14 -10
  51. package/dist/motion.js +14 -10
  52. package/dist/path.d.ts +150 -0
  53. package/dist/path.js +761 -0
  54. package/dist/selection.d.ts +133 -0
  55. package/dist/selection.js +194 -0
  56. package/dist/shader-slot.js +9 -0
  57. package/dist/shader-wgsl.js +946 -0
  58. package/dist/shader.js +480 -55
  59. package/dist/signal.d.ts +49 -0
  60. package/dist/signal.js +79 -0
  61. package/dist/stroke.js +271 -0
  62. package/dist/text/SilkText.d.ts +249 -0
  63. package/dist/text/SilkText.js +568 -0
  64. package/dist/text/atlas.d.ts +153 -0
  65. package/dist/text/atlas.js +316 -0
  66. package/dist/text/edt.d.ts +14 -0
  67. package/dist/text/edt.js +97 -0
  68. package/dist/text/label.d.ts +19 -0
  69. package/dist/text/label.js +38 -0
  70. package/dist/text/layout.d.ts +150 -0
  71. package/dist/text/layout.js +270 -0
  72. package/dist/text/segment.d.ts +34 -0
  73. package/dist/text/segment.js +98 -0
  74. package/dist/text/shader.js +355 -0
  75. package/dist/text.d.ts +7 -0
  76. package/dist/text.js +7 -0
  77. package/dist/ui/ButtonDock.d.ts +47 -0
  78. package/dist/ui/ButtonDock.js +110 -0
  79. package/dist/ui/RadialMenu.d.ts +222 -0
  80. package/dist/ui/RadialMenu.js +680 -0
  81. package/dist/ui/SilkButton.d.ts +149 -0
  82. package/dist/ui/SilkButton.js +323 -0
  83. package/dist/ui/ValuePill.d.ts +48 -0
  84. package/dist/ui/ValuePill.js +77 -0
  85. package/dist/ui/arc.d.ts +32 -0
  86. package/dist/ui/arc.js +58 -0
  87. package/dist/ui/brush.d.ts +117 -0
  88. package/dist/ui/brush.js +280 -0
  89. package/dist/ui/camera.d.ts +250 -0
  90. package/dist/ui/camera.js +634 -0
  91. package/dist/ui/color/ColorPicker.d.ts +72 -0
  92. package/dist/ui/color/ColorPicker.js +125 -0
  93. package/dist/ui/color/ColorSlider.d.ts +81 -0
  94. package/dist/ui/color/ColorSlider.js +227 -0
  95. package/dist/ui/color/ColorWheel.d.ts +34 -0
  96. package/dist/ui/color/ColorWheel.js +117 -0
  97. package/dist/ui/color/Eyedropper.d.ts +57 -0
  98. package/dist/ui/color/Eyedropper.js +159 -0
  99. package/dist/ui/color/OklchPicker.d.ts +45 -0
  100. package/dist/ui/color/OklchPicker.js +137 -0
  101. package/dist/ui/color/SwatchPalette.d.ts +60 -0
  102. package/dist/ui/color/SwatchPalette.js +160 -0
  103. package/dist/ui/color/SwatchPopup.d.ts +68 -0
  104. package/dist/ui/color/SwatchPopup.js +237 -0
  105. package/dist/ui/color/draw.d.ts +22 -0
  106. package/dist/ui/color/draw.js +128 -0
  107. package/dist/ui/color/model.d.ts +94 -0
  108. package/dist/ui/color/model.js +193 -0
  109. package/dist/ui/color/rings.d.ts +75 -0
  110. package/dist/ui/color/rings.js +247 -0
  111. package/dist/ui/color.d.ts +11 -0
  112. package/dist/ui/color.js +11 -0
  113. package/dist/ui/dial.d.ts +229 -0
  114. package/dist/ui/dial.js +553 -0
  115. package/dist/ui/driver.d.ts +24 -0
  116. package/dist/ui/driver.js +46 -0
  117. package/dist/ui/gesture.d.ts +66 -0
  118. package/dist/ui/gesture.js +116 -0
  119. package/dist/ui/gizmo.d.ts +199 -0
  120. package/dist/ui/gizmo.js +957 -0
  121. package/dist/ui/grid.d.ts +106 -0
  122. package/dist/ui/grid.js +228 -0
  123. package/dist/ui/group.d.ts +81 -0
  124. package/dist/ui/group.js +144 -0
  125. package/dist/ui/guides.d.ts +142 -0
  126. package/dist/ui/guides.js +379 -0
  127. package/dist/ui/halo.d.ts +164 -0
  128. package/dist/ui/halo.js +438 -0
  129. package/dist/ui/icon.d.ts +14 -0
  130. package/dist/ui/icon.js +40 -0
  131. package/dist/ui/index.d.ts +62 -0
  132. package/dist/ui/index.js +56 -0
  133. package/dist/ui/input.d.ts +28 -0
  134. package/dist/ui/input.js +49 -0
  135. package/dist/ui/inspector.d.ts +4 -0
  136. package/dist/ui/inspector.js +4 -0
  137. package/dist/ui/keys.d.ts +20 -0
  138. package/dist/ui/keys.js +65 -0
  139. package/dist/ui/label.d.ts +18 -0
  140. package/dist/ui/layers.d.ts +5 -0
  141. package/dist/ui/layers.js +5 -0
  142. package/dist/ui/layout/debug.d.ts +38 -0
  143. package/dist/ui/layout/debug.js +299 -0
  144. package/dist/ui/layout/flex-container.d.ts +150 -0
  145. package/dist/ui/layout/flex-container.js +441 -0
  146. package/dist/ui/layout/simulate.d.ts +49 -0
  147. package/dist/ui/layout/simulate.js +92 -0
  148. package/dist/ui/layout/smart-container.d.ts +180 -0
  149. package/dist/ui/layout/smart-container.js +302 -0
  150. package/dist/ui/layout.d.ts +5 -0
  151. package/dist/ui/layout.js +5 -0
  152. package/dist/ui/marquee.d.ts +124 -0
  153. package/dist/ui/marquee.js +321 -0
  154. package/dist/ui/measure.d.ts +138 -0
  155. package/dist/ui/measure.js +351 -0
  156. package/dist/ui/minimap.d.ts +2 -0
  157. package/dist/ui/minimap.js +2 -0
  158. package/dist/ui/modes.d.ts +186 -0
  159. package/dist/ui/modes.js +380 -0
  160. package/dist/ui/odometer.d.ts +104 -0
  161. package/dist/ui/odometer.js +244 -0
  162. package/dist/ui/outline.d.ts +104 -0
  163. package/dist/ui/outline.js +310 -0
  164. package/dist/ui/paint.js +22 -0
  165. package/dist/ui/panel.d.ts +4 -0
  166. package/dist/ui/panel.js +4 -0
  167. package/dist/ui/panels/Inspector.d.ts +228 -0
  168. package/dist/ui/panels/Inspector.js +516 -0
  169. package/dist/ui/panels/LayerTree.d.ts +193 -0
  170. package/dist/ui/panels/LayerTree.js +878 -0
  171. package/dist/ui/panels/Minimap.d.ts +140 -0
  172. package/dist/ui/panels/Minimap.js +412 -0
  173. package/dist/ui/panels/Panel.d.ts +273 -0
  174. package/dist/ui/panels/Panel.js +767 -0
  175. package/dist/ui/panels/ScrollView.d.ts +126 -0
  176. package/dist/ui/panels/ScrollView.js +358 -0
  177. package/dist/ui/panels/binding.d.ts +59 -0
  178. package/dist/ui/panels/binding.js +84 -0
  179. package/dist/ui/panels/fields.d.ts +265 -0
  180. package/dist/ui/panels/fields.js +760 -0
  181. package/dist/ui/panels/icons.d.ts +7 -0
  182. package/dist/ui/panels/icons.js +136 -0
  183. package/dist/ui/panels/pixi-tree.d.ts +35 -0
  184. package/dist/ui/panels/pixi-tree.js +82 -0
  185. package/dist/ui/panels/theme.d.ts +79 -0
  186. package/dist/ui/panels/theme.js +91 -0
  187. package/dist/ui/panels/tree.d.ts +130 -0
  188. package/dist/ui/panels/tree.js +199 -0
  189. package/dist/ui/pathgizmo.d.ts +253 -0
  190. package/dist/ui/pathgizmo.js +932 -0
  191. package/dist/ui/pill.d.ts +3 -0
  192. package/dist/ui/pill.js +2 -0
  193. package/dist/ui/ruler.d.ts +113 -0
  194. package/dist/ui/ruler.js +371 -0
  195. package/dist/ui/snap.d.ts +151 -0
  196. package/dist/ui/snap.js +380 -0
  197. package/dist/ui/spacing.d.ts +122 -0
  198. package/dist/ui/spacing.js +346 -0
  199. package/dist/ui/textedit.d.ts +304 -0
  200. package/dist/ui/textedit.js +1085 -0
  201. package/dist/ui/timeline.d.ts +175 -0
  202. package/dist/ui/timeline.js +488 -0
  203. package/dist/webgpu.d.ts +25 -0
  204. package/dist/webgpu.js +32 -0
  205. package/package.json +172 -1
  206. package/skills/pixi-silk/SKILL.md +138 -0
  207. package/skills/pixi-silk-app-rendering/SKILL.md +114 -0
  208. package/skills/pixi-silk-drawing/SKILL.md +154 -0
  209. package/skills/pixi-silk-editor/SKILL.md +200 -0
  210. package/skills/pixi-silk-layout/SKILL.md +150 -0
  211. package/skills/pixi-silk-migrate-from-graphics/SKILL.md +115 -0
  212. package/skills/pixi-silk-paint/SKILL.md +132 -0
  213. package/skills/pixi-silk-text/SKILL.md +127 -0
  214. package/skills/pixi-silk-widgets/SKILL.md +139 -0
package/dist/app.d.ts CHANGED
@@ -2,17 +2,18 @@ import { Application, ApplicationOptions } from "pixi.js";
2
2
  //#region src/app.d.ts
3
3
  /** Options of {@link createSilkApp}: Pixi application options plus the element to fill, DPR limits and touch behaviour. */
4
4
  export interface SilkAppOptions extends Partial<ApplicationOptions> {
5
- /** Element the canvas fills (it must have a size). */
5
+ /** Element the canvas is appended to and fills. Give it a size in CSS, or the canvas is 1x1. */
6
6
  parent: HTMLElement;
7
- /** Upper bound for the resolution (DPR). Default 3. */
7
+ /** Upper bound for the resolution when it follows devicePixelRatio. Default 3. */
8
8
  maxResolution?: number;
9
- /** Force a resolution instead of following devicePixelRatio. */
9
+ /** Fixed resolution instead of devicePixelRatio, capped at 16. `maxResolution` does not apply. */
10
10
  fixedResolution?: number;
11
- /** Called after every size / resolution change with the size in CSS pixels. */
11
+ /** Called after every size or resolution change, with the size in CSS pixels and the resolution. */
12
12
  onResize?: (width: number, height: number, resolution: number) => void;
13
13
  /**
14
- * Pixi filters render at resolution 1 by default, which blurs everything behind a filter
15
- * on retina screens. When true (default) new filters inherit the renderer resolution.
14
+ * Pixi filters render at resolution 1 by default, which blurs everything behind a filter on
15
+ * high-DPR screens. When true (default), new filters inherit the renderer resolution. It sets
16
+ * the global `Filter.defaultOptions.resolution`, so it affects every Pixi app on the page.
16
17
  */
17
18
  inheritFilterResolution?: boolean;
18
19
  /**
@@ -21,6 +22,13 @@ export interface SilkAppOptions extends Partial<ApplicationOptions> {
21
22
  * Pixi. Use `none` for canvases that handle drags themselves.
22
23
  */
23
24
  touchAction?: string;
25
+ /**
26
+ * Which renderer Pixi tries first. Default `'webgl'` (WebGL2). Pass `'webgpu'` to use WebGPU
27
+ * where the browser has it. Pixi falls back to WebGL2 when it does not, and the app retries on
28
+ * WebGL2 when WebGPU is offered but fails to start (it logs a warning). On WebGPU the app loads
29
+ * the WGSL shader from `pixi-silk/webgpu` before it resolves, so SilkGraphics render on either.
30
+ */
31
+ preference?: ApplicationOptions["preference"];
24
32
  }
25
33
  /** What {@link createSilkApp} returns: the Pixi application, its CSS size and resolution, and helpers to change or destroy it. */
26
34
  export interface SilkApp {
@@ -30,22 +38,30 @@ export interface SilkApp {
30
38
  readonly width: number;
31
39
  /** Current height in CSS pixels. */
32
40
  readonly height: number;
33
- /** Current renderer resolution (device pixels per CSS pixel). */
41
+ /** Current renderer resolution, in device pixels per CSS pixel. */
34
42
  readonly resolution: number;
35
- /** Forces a resolution, for example to compare 1x and 2x. `null` returns to devicePixelRatio. */
43
+ /** Forces a resolution, for example to compare 1x and 2x, and resizes at once. `null` returns to devicePixelRatio. */
36
44
  setResolution(resolution: number | null): void;
37
- /** Stops observers, destroys the stage and renderer and removes the canvas. Safe with several apps on a page. */
45
+ /** Stops observers and listeners, destroys the stage and renderer and removes the canvas. Safe with several apps on a page. */
38
46
  destroy(): void;
39
47
  }
40
48
  /**
41
- * Creates a Pixi application tuned for smooth vector output:
49
+ * Creates a Pixi application, appends its canvas to `parent` and keeps it sized to it.
50
+ *
51
+ * It starts WebGL2 by default and WebGPU with `preference: 'webgpu'`. MSAA is off, since SilkGraphics
52
+ * anti-alias their own edges. The backing store is sized from `devicePixelContentBoxSize`, so each
53
+ * canvas pixel is one device pixel even at fractional DPRs such as 1.25 or 2.625. It follows DPR
54
+ * changes from browser zoom or a move to another display. Coordinates are not rounded, so motion
55
+ * stays sub-pixel smooth. Any other Pixi option you pass overrides these defaults.
56
+ *
57
+ * It also listens for `pointercancel` on `window`. Pixi ignores that event, so a touch the page
58
+ * takes over for a scroll would leave a drag running. The app ends it with `pointerupoutside`.
42
59
  *
43
- * - WebGL2 and no MSAA (analytic AA does the job, MSAA would only cost bandwidth),
44
- * - backing store sized from `devicePixelContentBoxSize`, so every canvas pixel maps to
45
- * exactly one device pixel even at fractional DPRs (1.25, 1.5, 2.625 ...) - no resampling blur,
46
- * - follows DPR changes (moving the window between displays, browser zoom),
47
- * - unrounded coordinates for sub-pixel smooth motion,
48
- * - filters that render at the screen resolution instead of 1x.
60
+ * @example
61
+ * ```ts
62
+ * const silk = await createSilkApp({ parent: document.getElementById('stage')!, background: 0x0b0b0d });
63
+ * silk.app.stage.addChild(new SilkGraphics().circle(100, 100, 40).fill(0x30d158));
64
+ * ```
49
65
  */
50
66
  export declare function createSilkApp(options: SilkAppOptions): Promise<SilkApp>;
51
67
  //#endregion
package/dist/app.js CHANGED
@@ -1,22 +1,29 @@
1
1
  import { Application, Filter } from "pixi.js";
2
2
  //#region src/app.ts
3
3
  /**
4
- * Creates a Pixi application tuned for smooth vector output:
4
+ * Creates a Pixi application, appends its canvas to `parent` and keeps it sized to it.
5
5
  *
6
- * - WebGL2 and no MSAA (analytic AA does the job, MSAA would only cost bandwidth),
7
- * - backing store sized from `devicePixelContentBoxSize`, so every canvas pixel maps to
8
- * exactly one device pixel even at fractional DPRs (1.25, 1.5, 2.625 ...) - no resampling blur,
9
- * - follows DPR changes (moving the window between displays, browser zoom),
10
- * - unrounded coordinates for sub-pixel smooth motion,
11
- * - filters that render at the screen resolution instead of 1x.
6
+ * It starts WebGL2 by default and WebGPU with `preference: 'webgpu'`. MSAA is off, since SilkGraphics
7
+ * anti-alias their own edges. The backing store is sized from `devicePixelContentBoxSize`, so each
8
+ * canvas pixel is one device pixel even at fractional DPRs such as 1.25 or 2.625. It follows DPR
9
+ * changes from browser zoom or a move to another display. Coordinates are not rounded, so motion
10
+ * stays sub-pixel smooth. Any other Pixi option you pass overrides these defaults.
11
+ *
12
+ * It also listens for `pointercancel` on `window`. Pixi ignores that event, so a touch the page
13
+ * takes over for a scroll would leave a drag running. The app ends it with `pointerupoutside`.
14
+ *
15
+ * @example
16
+ * ```ts
17
+ * const silk = await createSilkApp({ parent: document.getElementById('stage')!, background: 0x0b0b0d });
18
+ * silk.app.stage.addChild(new SilkGraphics().circle(100, 100, 40).fill(0x30d158));
19
+ * ```
12
20
  */
13
21
  async function createSilkApp(options) {
14
22
  const { parent, maxResolution = 3, fixedResolution, onResize, inheritFilterResolution = true, touchAction = "pan-y pinch-zoom", ...rest } = options;
15
23
  if (inheritFilterResolution) Filter.defaultOptions.resolution = "inherit";
16
- const app = new Application();
17
24
  let forced = fixedResolution ?? null;
18
25
  const dpr = () => Math.min(forced ?? window.devicePixelRatio ?? 1, forced ? 16 : maxResolution);
19
- await app.init({
26
+ const init = {
20
27
  preference: "webgl",
21
28
  antialias: false,
22
29
  autoDensity: false,
@@ -26,7 +33,23 @@ async function createSilkApp(options) {
26
33
  height: Math.max(1, parent.clientHeight),
27
34
  powerPreference: "high-performance",
28
35
  ...rest
29
- });
36
+ };
37
+ let app = new Application();
38
+ try {
39
+ await app.init(init);
40
+ } catch (error) {
41
+ if (init.preference === "webgl" || Array.isArray(init.preference) && init.preference[0] === "webgl") throw error;
42
+ console.warn("pixi-silk: WebGPU failed to start, falling back to WebGL2.", error);
43
+ try {
44
+ app.destroy({ removeView: true });
45
+ } catch {}
46
+ app = new Application();
47
+ await app.init({
48
+ ...init,
49
+ preference: "webgl"
50
+ });
51
+ }
52
+ if (app.renderer.name === "webgpu") (await import("./webgpu.js")).enableWebGPU();
30
53
  const canvas = app.canvas;
31
54
  canvas.style.touchAction = touchAction;
32
55
  canvas.style.display = "block";
@@ -76,6 +99,16 @@ async function createSilkApp(options) {
76
99
  apply();
77
100
  };
78
101
  watchDpr();
102
+ const events = app.renderer.events;
103
+ const onCancel = ({ pointerId, pointerType, isPrimary, clientX, clientY }) => events._onPointerUp?.(new PointerEvent("pointerup", {
104
+ pointerId,
105
+ pointerType,
106
+ isPrimary,
107
+ clientX,
108
+ clientY,
109
+ button: 0
110
+ }));
111
+ globalThis.addEventListener("pointercancel", onCancel, true);
79
112
  return {
80
113
  app,
81
114
  get width() {
@@ -94,6 +127,7 @@ async function createSilkApp(options) {
94
127
  destroy() {
95
128
  ro.disconnect();
96
129
  mq?.removeEventListener("change", onDprChange);
130
+ globalThis.removeEventListener("pointercancel", onCancel, true);
97
131
  app.destroy({ removeView: true }, { children: true });
98
132
  }
99
133
  };
package/dist/atlas.d.ts CHANGED
@@ -2,13 +2,13 @@ import { Gradient } from "./gradient.js";
2
2
  import { BufferImageSource } from "pixi.js";
3
3
  //#region src/atlas.d.ts
4
4
  /**
5
- * All gradient ramps live in one RGBA16F texture (one ramp per row), shared by every
6
- * SilkGraphics. Half floats keep ~11 bits per channel so dark and low-alpha ramps
7
- * don't get quantised before the shader dithers them to the 8-bit framebuffer.
5
+ * All gradient ramps live in one RGBA16F texture, 256 samples by 256 rows, shared by every
6
+ * SilkGraphics. Half floats keep about 11 bits per channel, so dark and low-alpha ramps are not
7
+ * quantised before the shader dithers them to the 8-bit framebuffer. You rarely need it directly.
8
8
  */
9
9
  export declare class GradientAtlas {
10
10
  private static _shared;
11
- /** The atlas every SilkGraphics uses. */
11
+ /** The atlas every SilkGraphics uses, created on first access. */
12
12
  static get shared(): GradientAtlas;
13
13
  /** The half-float texture that holds the ramps. */
14
14
  readonly source: BufferImageSource;
@@ -17,9 +17,16 @@ export declare class GradientAtlas {
17
17
  private _nextRow;
18
18
  private readonly _scratch;
19
19
  constructor();
20
- /** Returns the atlas row for a gradient ramp, baking it on first use. */
20
+ /**
21
+ * Returns the atlas row for a gradient and adds a reference to it. Gradients with the same
22
+ * `key` share a row, baked and uploaded on first use. Pair every call with {@link GradientAtlas.release}.
23
+ */
21
24
  acquire(gradient: Gradient): number;
22
- /** Drops one reference to a ramp. When the atlas is full, rows nobody uses are reused. */
25
+ /**
26
+ * Drops one reference to a ramp by its gradient key. The row stays baked, so it is free to
27
+ * reuse only once all 256 rows have been handed out. With every row in use, row 0 is shared
28
+ * and a warning is logged.
29
+ */
23
30
  release(key: string): void;
24
31
  private _allocate;
25
32
  private _write;
package/dist/atlas.js CHANGED
@@ -2,13 +2,13 @@ import { toHalf } from "./color.js";
2
2
  import { BufferImageSource } from "pixi.js";
3
3
  //#region src/atlas.ts
4
4
  /**
5
- * All gradient ramps live in one RGBA16F texture (one ramp per row), shared by every
6
- * SilkGraphics. Half floats keep ~11 bits per channel so dark and low-alpha ramps
7
- * don't get quantised before the shader dithers them to the 8-bit framebuffer.
5
+ * All gradient ramps live in one RGBA16F texture, 256 samples by 256 rows, shared by every
6
+ * SilkGraphics. Half floats keep about 11 bits per channel, so dark and low-alpha ramps are not
7
+ * quantised before the shader dithers them to the 8-bit framebuffer. You rarely need it directly.
8
8
  */
9
9
  var GradientAtlas = class GradientAtlas {
10
10
  static _shared = null;
11
- /** The atlas every SilkGraphics uses. */
11
+ /** The atlas every SilkGraphics uses, created on first access. */
12
12
  static get shared() {
13
13
  GradientAtlas._shared ??= new GradientAtlas();
14
14
  return GradientAtlas._shared;
@@ -33,7 +33,10 @@ var GradientAtlas = class GradientAtlas {
33
33
  label: "silk-gradient-atlas"
34
34
  });
35
35
  }
36
- /** Returns the atlas row for a gradient ramp, baking it on first use. */
36
+ /**
37
+ * Returns the atlas row for a gradient and adds a reference to it. Gradients with the same
38
+ * `key` share a row, baked and uploaded on first use. Pair every call with {@link GradientAtlas.release}.
39
+ */
37
40
  acquire(gradient) {
38
41
  let entry = this._rows.get(gradient.key);
39
42
  if (!entry) {
@@ -47,7 +50,11 @@ var GradientAtlas = class GradientAtlas {
47
50
  entry.refs++;
48
51
  return entry.row;
49
52
  }
50
- /** Drops one reference to a ramp. When the atlas is full, rows nobody uses are reused. */
53
+ /**
54
+ * Drops one reference to a ramp by its gradient key. The row stays baked, so it is free to
55
+ * reuse only once all 256 rows have been handed out. With every row in use, row 0 is shared
56
+ * and a warning is logged.
57
+ */
51
58
  release(key) {
52
59
  const entry = this._rows.get(key);
53
60
  if (entry && entry.refs > 0) entry.refs--;
@@ -0,0 +1,63 @@
1
+ import { SilkGraphics } from "./SilkGraphics.js";
2
+ import { ExtensionType, Instruction, InstructionSet, RenderPipe, Renderer } from "pixi.js";
3
+ //#region src/batch.d.ts
4
+ /**
5
+ * Render pipe that draws runs of consecutive SilkGraphics in one instanced draw call, under WebGL2
6
+ * and WebGPU. {@link enableSilkBatching} installs it.
7
+ */
8
+ export declare class SilkPipe implements RenderPipe<SilkGraphics> {
9
+ /** Pixi extension metadata, for `extensions.add(SilkPipe)` if you register it yourself. */
10
+ static extension: {
11
+ /** Renderer pipe lists the pipe joins. */
12
+ type: ExtensionType[];
13
+ /** Key in `renderer.renderPipes`, and the `renderPipeId` of batched objects. */
14
+ name: string;
15
+ };
16
+ private _renderer;
17
+ private _sets;
18
+ private readonly _local;
19
+ private readonly _localGroup;
20
+ /** Created once per renderer, by the pipe that `enableSilkBatching()` installs or by Pixi's extensions. */
21
+ constructor(renderer: Renderer);
22
+ /**
23
+ * Whether this renderer batches. WebGPU needs the WGSL program (`enableWebGPU()`), or the batch
24
+ * would have no program to draw with: without it, objects go to the mesh pipe as before.
25
+ */
26
+ private get _batching();
27
+ /** Adds `g` to the current run when it can share its draw, or starts a new run. */
28
+ addRenderable(g: SilkGraphics, set: InstructionSet): void;
29
+ /** Nothing to do: a batch reads every object again when it draws. */
30
+ updateRenderable(g: SilkGraphics): void;
31
+ /** A batch never needs a rebuild for changes inside its objects. */
32
+ validateRenderable(g: SilkGraphics): boolean;
33
+ /** Draws a batch, or hands a single object to the mesh pipe. */
34
+ execute(instruction: Instruction): void;
35
+ /** Frees the batches of an instruction set that Pixi no longer uses. */
36
+ destroyInstructionSet(set: InstructionSet): void;
37
+ /** @ignore */
38
+ destroy(): void;
39
+ /** The next batch of a set's pool. A set that is being rebuilt starts its pool over. */
40
+ private _next;
41
+ private _draw;
42
+ }
43
+ /**
44
+ * Turns on batching across objects, which is off by default. Runs of consecutive SilkGraphics with
45
+ * the same blend mode and settings then render in one draw call. Only objects created after the
46
+ * call take part, and an object with `batch: false` never does. There is no call to turn it off. Each renderer gets
47
+ * the pipe the first time it draws one of them, so you can call it before or after creating the
48
+ * Application. It is safe to call again.
49
+ *
50
+ * It works with WebGL2 and with WebGPU. On WebGPU, call `enableWebGPU()` too ({@link createSilkApp}
51
+ * does it for you), or objects draw one call each, as without batching.
52
+ *
53
+ * @example
54
+ * ```ts
55
+ * import { enableSilkBatching, SilkGraphics } from 'pixi-silk';
56
+ *
57
+ * enableSilkBatching();
58
+ * const app = new Application();
59
+ * await app.init();
60
+ * ```
61
+ */
62
+ export declare function enableSilkBatching(): void;
63
+ //#endregion
package/dist/batch.js ADDED
@@ -0,0 +1,327 @@
1
+ import { silkGpu } from "./shader-slot.js";
2
+ import { createSilkShader } from "./shader.js";
3
+ import { SilkGeometry, SilkGraphics } from "./SilkGraphics.js";
4
+ import { BindGroup, BufferImageSource, ExtensionType, Matrix, RendererType, State, UniformGroup } from "pixi.js";
5
+ /** Width of the object table texture. */
6
+ const TABLE_WIDTH = 1024;
7
+ /** Returns `a` when it holds `n` floats, or a copy grown to at least `n` (doubling). */
8
+ function grow(a, n) {
9
+ if (a.length >= n) return a;
10
+ const bigger = new Float32Array(Math.max(n, a.length * 2));
11
+ bigger.set(a);
12
+ return bigger;
13
+ }
14
+ /**
15
+ * Counts the instances and path texels of `sources`. Path texels round up to whole rows of the
16
+ * path texture, so every object's texels start on a row of their own.
17
+ */
18
+ function measureBatch(sources) {
19
+ let instances = 0;
20
+ let texels = 0;
21
+ for (const s of sources) {
22
+ instances += s.count;
23
+ texels += Math.ceil(s.polyCount / 256) * 256;
24
+ }
25
+ return {
26
+ instances,
27
+ texels
28
+ };
29
+ }
30
+ /**
31
+ * Copies the instances of every source into `out`, tagging each with its object index + 1 in
32
+ * `aFx.w`, and the path texels into `poly`. Writes each object's path base into `bases`.
33
+ * The arrays must be large enough ({@link measureBatch}).
34
+ */
35
+ function packBatch(sources, out, poly, bases) {
36
+ let o = 0;
37
+ let t = 0;
38
+ sources.forEach((s, i) => {
39
+ const n = s.count * 44;
40
+ out.set(s.f.subarray(0, n), o);
41
+ for (let k = o + 44 - 1; k < o + n; k += 44) out[k] = i + 1;
42
+ o += n;
43
+ bases[i] = t;
44
+ if (s.polyCount > 0) {
45
+ poly.set(s.poly.subarray(0, s.polyCount * 4), t * 4);
46
+ t += Math.ceil(s.polyCount / 256) * 256;
47
+ }
48
+ });
49
+ return {
50
+ instances: o / 44,
51
+ texels: t
52
+ };
53
+ }
54
+ /** Writes one object's row of the object table: its 2x3 matrix, path base and premultiplied tint. */
55
+ function writeObject(table, i, m, base, abgr) {
56
+ const o = i * 3 * 4;
57
+ const alpha = (abgr >>> 24 & 255) / 255;
58
+ table[o] = m.a;
59
+ table[o + 1] = m.b;
60
+ table[o + 2] = m.c;
61
+ table[o + 3] = m.d;
62
+ table[o + 4] = m.tx;
63
+ table[o + 5] = m.ty;
64
+ table[o + 6] = base;
65
+ table[o + 7] = 0;
66
+ table[o + 8] = (abgr & 255) / 255 * alpha;
67
+ table[o + 9] = (abgr >>> 8 & 255) / 255 * alpha;
68
+ table[o + 10] = (abgr >>> 16 & 255) / 255 * alpha;
69
+ table[o + 11] = alpha;
70
+ }
71
+ /** Whether two settings arrays (dither, aaWidth, minStrokePx) match, so their objects can share a draw. */
72
+ function sameSettings(a, b) {
73
+ return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
74
+ }
75
+ function dataTexture(label, width) {
76
+ return new BufferImageSource({
77
+ resource: new Float32Array(width * 4),
78
+ width,
79
+ height: 1,
80
+ format: "rgba32float",
81
+ alphaMode: "premultiplied-alpha",
82
+ scaleMode: "nearest",
83
+ autoGenerateMipmaps: false,
84
+ label
85
+ });
86
+ }
87
+ /** Uploads `data` into `src`, `width` texels per row, resizing it when the row count changes. */
88
+ function upload(src, data, texels, width) {
89
+ const rows = Math.max(1, Math.ceil(texels / width));
90
+ const view = data.subarray(0, rows * width * 4);
91
+ if (src.height !== rows || src.resource.length !== view.length) {
92
+ src.resource = view;
93
+ src.resize(width, rows);
94
+ } else src.resource = view;
95
+ src.update();
96
+ }
97
+ /** @internal One draw: a run of consecutive SilkGraphics. */
98
+ var SilkBatch = class {
99
+ renderPipeId = "silk";
100
+ canBundle = false;
101
+ /** Position in its instruction set, to tell a rebuild of the set from more of the same build. */
102
+ index = -1;
103
+ items = [];
104
+ blendMode = "normal";
105
+ settings = /* @__PURE__ */ new Float32Array(3);
106
+ geometry = new SilkGeometry();
107
+ polys = dataTexture("silk-batch-paths", 256);
108
+ table = dataTexture("silk-batch-objects", TABLE_WIDTH);
109
+ state = State.for2d();
110
+ shader = null;
111
+ data = /* @__PURE__ */ new Float32Array(2816);
112
+ polyData = /* @__PURE__ */ new Float32Array(1024);
113
+ tableData = new Float32Array(TABLE_WIDTH * 4);
114
+ /** What was packed last time: the items and their versions. */
115
+ packed = [];
116
+ versions = [];
117
+ bases = [];
118
+ instances = 0;
119
+ destroy() {
120
+ this.geometry.destroy(true);
121
+ this.shader?.destroy();
122
+ this.polys.destroy();
123
+ this.table.destroy();
124
+ this.items = [];
125
+ this.packed = [];
126
+ }
127
+ };
128
+ /** Pixi's mesh pipe takes any Mesh: SilkGraphics is one, with its own geometry type. */
129
+ const asMesh = (g) => g;
130
+ /**
131
+ * Render pipe that draws runs of consecutive SilkGraphics in one instanced draw call, under WebGL2
132
+ * and WebGPU. {@link enableSilkBatching} installs it.
133
+ */
134
+ var SilkPipe = class {
135
+ /** Pixi extension metadata, for `extensions.add(SilkPipe)` if you register it yourself. */
136
+ static extension = {
137
+ type: [ExtensionType.WebGLPipes, ExtensionType.WebGPUPipes],
138
+ name: "silk"
139
+ };
140
+ _renderer;
141
+ _sets = /* @__PURE__ */ new Map();
142
+ _local = new UniformGroup({
143
+ uTransformMatrix: {
144
+ value: new Matrix(),
145
+ type: "mat3x3<f32>"
146
+ },
147
+ uColor: {
148
+ value: new Float32Array([
149
+ 1,
150
+ 1,
151
+ 1,
152
+ 1
153
+ ]),
154
+ type: "vec4<f32>"
155
+ },
156
+ uRound: {
157
+ value: 0,
158
+ type: "f32"
159
+ }
160
+ });
161
+ _localGroup = new BindGroup({ 0: this._local });
162
+ /** Created once per renderer, by the pipe that `enableSilkBatching()` installs or by Pixi's extensions. */
163
+ constructor(renderer) {
164
+ this._renderer = renderer;
165
+ }
166
+ /**
167
+ * Whether this renderer batches. WebGPU needs the WGSL program (`enableWebGPU()`), or the batch
168
+ * would have no program to draw with: without it, objects go to the mesh pipe as before.
169
+ */
170
+ get _batching() {
171
+ return this._renderer.type === RendererType.WEBGL || silkGpu.program !== null;
172
+ }
173
+ /** Adds `g` to the current run when it can share its draw, or starts a new run. */
174
+ addRenderable(g, set) {
175
+ const pipes = this._renderer.renderPipes;
176
+ if (!this._batching) {
177
+ pipes.mesh.addRenderable(asMesh(g), set);
178
+ return;
179
+ }
180
+ pipes.batch.break(set);
181
+ const last = set.instructions[set.instructionSize - 1];
182
+ const settings = g._settings;
183
+ if (last instanceof SilkBatch && last.index === set.instructionSize - 1 && last.blendMode === g.groupBlendMode && sameSettings(last.settings, settings)) {
184
+ last.items.push(g);
185
+ return;
186
+ }
187
+ const batch = this._next(set);
188
+ batch.items.length = 0;
189
+ batch.items.push(g);
190
+ batch.blendMode = g.groupBlendMode;
191
+ batch.settings.set(settings.subarray(0, 3));
192
+ batch.index = set.instructionSize;
193
+ set.add(batch);
194
+ }
195
+ /** Nothing to do: a batch reads every object again when it draws. */
196
+ updateRenderable(g) {
197
+ if (!this._batching) this._renderer.renderPipes.mesh.updateRenderable(asMesh(g));
198
+ }
199
+ /** A batch never needs a rebuild for changes inside its objects. */
200
+ validateRenderable(g) {
201
+ return this._batching ? false : this._renderer.renderPipes.mesh.validateRenderable(asMesh(g));
202
+ }
203
+ /** Draws a batch, or hands a single object to the mesh pipe. */
204
+ execute(instruction) {
205
+ if (instruction instanceof SilkBatch) this._draw(instruction);
206
+ else this._renderer.renderPipes.mesh.execute(asMesh(instruction));
207
+ }
208
+ /** Frees the batches of an instruction set that Pixi no longer uses. */
209
+ destroyInstructionSet(set) {
210
+ const rec = this._sets.get(set.uid);
211
+ if (!rec) return;
212
+ for (const b of rec.batches) b.destroy();
213
+ this._sets.delete(set.uid);
214
+ }
215
+ /** @ignore */
216
+ destroy() {
217
+ for (const rec of this._sets.values()) for (const b of rec.batches) b.destroy();
218
+ this._sets.clear();
219
+ this._renderer = null;
220
+ }
221
+ /** The next batch of a set's pool. A set that is being rebuilt starts its pool over. */
222
+ _next(set) {
223
+ let rec = this._sets.get(set.uid);
224
+ if (!rec) {
225
+ rec = {
226
+ batches: [],
227
+ used: 0
228
+ };
229
+ this._sets.set(set.uid, rec);
230
+ }
231
+ const prev = rec.used > 0 ? rec.batches[rec.used - 1] : null;
232
+ if (prev && !(prev.index < set.instructionSize && set.instructions[prev.index] === prev)) rec.used = 0;
233
+ let batch = rec.batches[rec.used];
234
+ if (!batch) {
235
+ batch = new SilkBatch();
236
+ rec.batches.push(batch);
237
+ }
238
+ rec.used++;
239
+ return batch;
240
+ }
241
+ _draw(b) {
242
+ const items = b.items.filter((g) => !g.destroyed && g.isRenderable && g.primitiveCount > 0);
243
+ if (!items.length) return;
244
+ let dirty = items.length !== b.packed.length;
245
+ for (let i = 0; !dirty && i < items.length; i++) dirty = items[i] !== b.packed[i] || items[i]._version !== b.versions[i];
246
+ if (dirty) {
247
+ const sources = items.map((g) => g._batchSource);
248
+ const size = measureBatch(sources);
249
+ b.data = grow(b.data, Math.max(size.instances, 1) * 44);
250
+ b.polyData = grow(b.polyData, Math.max(size.texels, 256) * 4);
251
+ const packed = packBatch(sources, b.data, b.polyData, b.bases);
252
+ b.instances = packed.instances;
253
+ b.geometry.instanceBuffer.data = b.data;
254
+ b.geometry.instanceBuffer.update(packed.instances * 44 * 4);
255
+ b.geometry.instanceCount = packed.instances;
256
+ upload(b.polys, b.polyData, packed.texels, 256);
257
+ b.packed = items;
258
+ b.versions = items.map((g) => g._version);
259
+ }
260
+ b.tableData = grow(b.tableData, Math.ceil(items.length * 3 / TABLE_WIDTH) * TABLE_WIDTH * 4);
261
+ items.forEach((g, i) => {
262
+ writeObject(b.tableData, i, g.groupTransform, b.bases[i], g.groupColorAlpha);
263
+ });
264
+ upload(b.table, b.tableData, items.length * 3, TABLE_WIDTH);
265
+ if (!b.shader) {
266
+ const [dither, aaWidth, minStrokePx] = b.settings;
267
+ b.shader = createSilkShader({
268
+ dither,
269
+ aaWidth,
270
+ minStrokePx
271
+ }, b.polys, b.table);
272
+ }
273
+ const shader = b.shader;
274
+ const silk = shader.resources.silkUniforms.uniforms.uSilk;
275
+ if (!sameSettings(silk, b.settings)) {
276
+ silk.set(b.settings);
277
+ shader.resources.silkUniforms.update();
278
+ }
279
+ b.state.blendMode = b.blendMode;
280
+ if (this._renderer.type === RendererType.WEBGPU) {
281
+ const renderer = this._renderer;
282
+ shader.groups[0] = renderer.globalUniforms.bindGroup;
283
+ shader.groups[1] = renderer.renderPipes.uniformBatch.getUniformBindGroup(this._local, true);
284
+ renderer.encoder.draw({
285
+ geometry: b.geometry,
286
+ shader,
287
+ state: b.state
288
+ });
289
+ } else {
290
+ const renderer = this._renderer;
291
+ shader.groups[100] = renderer.globalUniforms.bindGroup;
292
+ shader.groups[101] = this._localGroup;
293
+ renderer.encoder.draw({
294
+ geometry: b.geometry,
295
+ shader,
296
+ state: b.state
297
+ });
298
+ }
299
+ }
300
+ };
301
+ /**
302
+ * Turns on batching across objects, which is off by default. Runs of consecutive SilkGraphics with
303
+ * the same blend mode and settings then render in one draw call. Only objects created after the
304
+ * call take part, and an object with `batch: false` never does. There is no call to turn it off. Each renderer gets
305
+ * the pipe the first time it draws one of them, so you can call it before or after creating the
306
+ * Application. It is safe to call again.
307
+ *
308
+ * It works with WebGL2 and with WebGPU. On WebGPU, call `enableWebGPU()` too ({@link createSilkApp}
309
+ * does it for you), or objects draw one call each, as without batching.
310
+ *
311
+ * @example
312
+ * ```ts
313
+ * import { enableSilkBatching, SilkGraphics } from 'pixi-silk';
314
+ *
315
+ * enableSilkBatching();
316
+ * const app = new Application();
317
+ * await app.init();
318
+ * ```
319
+ */
320
+ function enableSilkBatching() {
321
+ SilkGraphics._pipeId = "silk";
322
+ SilkGraphics._installPipe ??= (renderer) => {
323
+ renderer.renderPipes.silk = new SilkPipe(renderer);
324
+ };
325
+ }
326
+ //#endregion
327
+ export { SilkPipe, enableSilkBatching, grow, measureBatch, packBatch, sameSettings, writeObject };
package/dist/color.d.ts CHANGED
@@ -2,7 +2,10 @@ import { ColorSource } from "pixi.js";
2
2
  //#region src/color.d.ts
3
3
  /** Straight (non-premultiplied) sRGB colour with alpha, all channels 0..1, as returned by {@link parseColor}. */
4
4
  export type RGBA = [number, number, number, number];
5
- /** Any Pixi `ColorSource` as straight sRGB `[r, g, b, a]` (0..1), with `alpha` multiplied in. Memoised. */
5
+ /**
6
+ * Converts any Pixi `ColorSource` to straight sRGB `[r, g, b, a]`, channels 0..1, with `alpha`
7
+ * multiplied in. Returns a new array. Numbers and strings are cached, up to 1024 of them.
8
+ */
6
9
  export declare function parseColor(value: ColorSource, alpha?: number): RGBA;
7
10
  /** Converts linear-light sRGB to OKLab (Björn Ottosson's perceptual colour space), used to interpolate gradients evenly. */
8
11
  export declare function linearToOklab(r: number, g: number, b: number): [number, number, number];