pixi-silk 1.0.2 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -90,9 +90,12 @@ const premultiply = (out, color, alpha) => {
90
90
  * `measureText`, so line breaks and widths match PixiJS `Text`. Style changes relayout once, on the
91
91
  * next render or the next read of {@link SilkText.layout}.
92
92
  *
93
- * It has no rich text, per-character styles or right-to-left shaping. Glyphs combine code points
94
- * one by one, so complex scripts and emoji sequences do not shape. Works with Pixi's WebGL2 and
95
- * WebGPU renderers.
93
+ * Any common script works. Arabic and Hebrew paragraphs are reordered with the Unicode bidi
94
+ * algorithm, and numbers and Latin words inside them keep reading left to right. Words of scripts
95
+ * that need shaping (Arabic, Burmese, Thai, the Indic scripts) are baked whole, so Canvas shapes
96
+ * them, and lines grow to fit stacked marks. `{name}` tokens make room for inline objects, see
97
+ * {@link SilkRichText}. Emoji keep their colours. It has no per-character styles. Works with Pixi's
98
+ * WebGL2 and WebGPU renderers.
96
99
  *
97
100
  * @example
98
101
  * ```ts
@@ -111,7 +114,8 @@ var SilkText = class SilkText extends Mesh {
111
114
  fill: 16777215,
112
115
  letterSpacing: 0,
113
116
  lineHeight: 0,
114
- align: "left",
117
+ align: "start",
118
+ direction: "auto",
115
119
  wordWrap: false,
116
120
  wordWrapWidth: 100,
117
121
  breakWords: false,
@@ -120,7 +124,16 @@ var SilkText = class SilkText extends Mesh {
120
124
  outline: null,
121
125
  shadow: null,
122
126
  dilate: 0,
123
- aaWidth: 1
127
+ aaWidth: 1,
128
+ wordBreak: "normal",
129
+ inlines: {},
130
+ maxLines: 0,
131
+ maxWidth: 0,
132
+ maxHeight: 0,
133
+ ellipsis: "…",
134
+ shrinkToFit: false,
135
+ minFontSize: 0,
136
+ tabSize: 8
124
137
  };
125
138
  /** Point of the text box placed at the position: (0, 0) top left, (0.5, 0.5) centre, (1, 1) bottom right. Changing it relayouts. */
126
139
  anchor;
@@ -133,6 +146,9 @@ var SilkText = class SilkText extends Mesh {
133
146
  _version = -1;
134
147
  _f;
135
148
  _count = 0;
149
+ _passes = 1;
150
+ _size = 0;
151
+ _inlineBoxes = {};
136
152
  _uniforms;
137
153
  _gradKey = null;
138
154
  _scratch = /* @__PURE__ */ new Float32Array(4);
@@ -142,7 +158,7 @@ var SilkText = class SilkText extends Mesh {
142
158
  const opts = typeof options === "string" ? { text: options } : options;
143
159
  const atlas = opts.atlas ?? SdfAtlas.shared;
144
160
  const geometry = new SilkTextGeometry();
145
- const shader = createTextShader(atlas.source);
161
+ const shader = createTextShader(atlas.source, atlas.colorSource);
146
162
  super({
147
163
  geometry,
148
164
  shader,
@@ -252,6 +268,14 @@ var SilkText = class SilkText extends Mesh {
252
268
  set align(v) {
253
269
  this._set("align", v);
254
270
  }
271
+ /** Base direction of each paragraph: `ltr`, `rtl` or `auto` (from the first strong character). */
272
+ get direction() {
273
+ return this._style.direction;
274
+ }
275
+ /** Sets {@link SilkText.direction}. */
276
+ set direction(v) {
277
+ this._set("direction", v);
278
+ }
255
279
  /** Breaks lines at spaces to fit {@link SilkText.wordWrapWidth}. */
256
280
  get wordWrap() {
257
281
  return this._style.wordWrap;
@@ -348,9 +372,12 @@ var SilkText = class SilkText extends Mesh {
348
372
  const layout = this.layout;
349
373
  return caretAtPoint(layout, point.x - this._ox, point.y - this._oy, isStop);
350
374
  }
351
- /** Where a caret at `index` sits, in local units. `upstream` picks the end of a wrapped line. */
352
- caretRect(index, upstream = false) {
353
- const r = caretRect(this.layout, index, upstream);
375
+ /**
376
+ * Where a caret at `index` sits, in local units. `upstream` picks the end of a wrapped line,
377
+ * `leading` the place before the next character where the direction changes.
378
+ */
379
+ caretRect(index, upstream = false, leading = false) {
380
+ const r = caretRect(this.layout, index, upstream, leading);
354
381
  return {
355
382
  x: r.x + this._ox,
356
383
  top: r.top + this._oy,
@@ -375,7 +402,110 @@ var SilkText = class SilkText extends Mesh {
375
402
  /** Glyph instances drawn: characters with ink. Spaces, shadows and outlines are not counted. */
376
403
  get glyphCount() {
377
404
  this.updateText();
378
- return this._style.shadow ? this._count / 2 : this._count;
405
+ return this._count / this._passes;
406
+ }
407
+ /**
408
+ * Where the inline objects of the text go, one rectangle per `{name}` token, in local units.
409
+ * Bidi and wrapping move them with the text. See {@link SilkTextStyle.inlines}.
410
+ */
411
+ inlineRects() {
412
+ const layout = this.layout;
413
+ const out = [];
414
+ for (const g of layout.glyphs) {
415
+ const box = g.inline ? this._inlineBoxes[g.inline] : void 0;
416
+ if (!g.inline || !box) continue;
417
+ out.push({
418
+ name: g.inline,
419
+ x: this._ox + g.x + box.margin,
420
+ y: this._oy + g.y - box.top,
421
+ width: box.width,
422
+ height: box.height,
423
+ line: g.line,
424
+ index: g.index
425
+ });
426
+ }
427
+ return out;
428
+ }
429
+ /** Room for inline objects, by name. Set a new object to change it, mutating this one does nothing. */
430
+ get inlines() {
431
+ return this._style.inlines;
432
+ }
433
+ /** Sets {@link SilkText.inlines}. */
434
+ set inlines(v) {
435
+ this._set("inlines", v);
436
+ }
437
+ /** Most lines to show, 0 for no limit. See {@link SilkTextStyle.maxLines}. */
438
+ get maxLines() {
439
+ return this._style.maxLines;
440
+ }
441
+ /** Sets {@link SilkText.maxLines}. */
442
+ set maxLines(v) {
443
+ this._set("maxLines", v);
444
+ }
445
+ /** Widest the text may be when it does not wrap, 0 for no limit. See {@link SilkTextStyle.maxWidth}. */
446
+ get maxWidth() {
447
+ return this._style.maxWidth;
448
+ }
449
+ /** Sets {@link SilkText.maxWidth}. */
450
+ set maxWidth(v) {
451
+ this._set("maxWidth", v);
452
+ }
453
+ /** Tallest the text box may be, 0 for no limit. See {@link SilkTextStyle.maxHeight}. */
454
+ get maxHeight() {
455
+ return this._style.maxHeight;
456
+ }
457
+ /** Sets {@link SilkText.maxHeight}. */
458
+ set maxHeight(v) {
459
+ this._set("maxHeight", v);
460
+ }
461
+ /** What a cut line ends with, or `null` for no mark. */
462
+ get ellipsis() {
463
+ return this._style.ellipsis;
464
+ }
465
+ /** Sets {@link SilkText.ellipsis}. */
466
+ set ellipsis(v) {
467
+ this._set("ellipsis", v);
468
+ }
469
+ /** Shrinks the font to fit `maxWidth`, `maxHeight` and `maxLines`. See {@link SilkTextStyle.shrinkToFit}. */
470
+ get shrinkToFit() {
471
+ return this._style.shrinkToFit;
472
+ }
473
+ /** Sets {@link SilkText.shrinkToFit}. */
474
+ set shrinkToFit(v) {
475
+ this._set("shrinkToFit", v);
476
+ }
477
+ /** Smallest size `shrinkToFit` goes to, 0 for half the font size. */
478
+ get minFontSize() {
479
+ return this._style.minFontSize;
480
+ }
481
+ /** Sets {@link SilkText.minFontSize}. */
482
+ set minFontSize(v) {
483
+ this._set("minFontSize", v);
484
+ }
485
+ /** Tab stops every this many space widths. */
486
+ get tabSize() {
487
+ return this._style.tabSize;
488
+ }
489
+ /** Sets {@link SilkText.tabSize}. */
490
+ set tabSize(v) {
491
+ this._set("tabSize", v);
492
+ }
493
+ /** The font size the text is drawn at: `fontSize`, or smaller when `shrinkToFit` had to shrink it. */
494
+ get renderedFontSize() {
495
+ this.updateText();
496
+ return this._size;
497
+ }
498
+ /** True when the text did not fit its limits and was cut. */
499
+ get truncated() {
500
+ return this.layout.truncated;
501
+ }
502
+ /** Where lines may break without spaces: `normal` or `keep-all`. */
503
+ get wordBreak() {
504
+ return this._style.wordBreak;
505
+ }
506
+ /** Sets {@link SilkText.wordBreak}. */
507
+ set wordBreak(v) {
508
+ this._set("wordBreak", v);
379
509
  }
380
510
  get bounds() {
381
511
  this.updateText();
@@ -417,6 +547,53 @@ var SilkText = class SilkText extends Mesh {
417
547
  if (shader) this.atlas.untrack(shader);
418
548
  shader?.destroy();
419
549
  }
550
+ /** The inline boxes in layout terms: advance with margins, and the height above and below the baseline. */
551
+ _resolveInlines(font, k, ascent, descent) {
552
+ const out = {};
553
+ const names = Object.keys(this._style.inlines);
554
+ this._inlineBoxes = {};
555
+ if (!names.length) return out;
556
+ const plain = this._text.replace(/\{[\w-]+\}/g, "").replace(/\s+/g, "");
557
+ let middle = (this.atlas.ink(font, "H").ascent * k || ascent * .7) / 2;
558
+ if (plain && !/[\p{Lu}\p{Nd}]/u.test(plain)) {
559
+ const m = this.atlas.measure(font, plain);
560
+ if (m.ascent + m.descent > 0) middle = (m.ascent - m.descent) / 2 * k;
561
+ }
562
+ for (const name of names) {
563
+ const d = this._style.inlines[name];
564
+ const h = Math.max(0, d.height);
565
+ const margin = d.margin ?? 0;
566
+ let top;
567
+ switch (d.align ?? "middle") {
568
+ case "baseline":
569
+ top = h;
570
+ break;
571
+ case "center":
572
+ top = (ascent - descent) / 2 + h / 2;
573
+ break;
574
+ case "top":
575
+ top = ascent;
576
+ break;
577
+ case "bottom":
578
+ top = h - descent;
579
+ break;
580
+ default: top = middle + h / 2;
581
+ }
582
+ top -= d.offsetY ?? 0;
583
+ this._inlineBoxes[name] = {
584
+ width: Math.max(0, d.width),
585
+ height: h,
586
+ margin,
587
+ top
588
+ };
589
+ out[name] = {
590
+ width: Math.max(0, d.width) + 2 * margin,
591
+ ascent: top,
592
+ descent: h - top
593
+ };
594
+ }
595
+ return out;
596
+ }
420
597
  _set(key, value) {
421
598
  if (this._style[key] === value) return;
422
599
  this._style[key] = value;
@@ -435,43 +612,97 @@ var SilkText = class SilkText extends Mesh {
435
612
  weight: s.fontWeight,
436
613
  style: s.fontStyle
437
614
  };
438
- const k = s.fontSize / atlas.size;
439
615
  const fm = atlas.metrics(font);
440
- const layout = layoutText(this._text, {
441
- ascent: fm.ascent * k,
442
- descent: fm.descent * k,
443
- letterSpacing: s.letterSpacing,
444
- lineHeight: s.lineHeight > 0 ? s.lineHeight : void 0,
445
- align: s.align,
446
- wordWrap: s.wordWrap,
447
- wordWrapWidth: s.wordWrapWidth,
448
- breakWords: s.breakWords,
449
- tabularNumbers: s.tabularNumbers,
450
- kerning: s.kerning
451
- }, {
452
- advance: (c) => atlas.advance(font, c) * k,
453
- kerning: (a, b) => atlas.kerning(font, a, b) * k
454
- });
616
+ const reach = Math.max(0, s.dilate) + (s.outline && (s.outline.alpha ?? 1) > 0 ? Math.max(0, s.outline.width) : 0);
617
+ const lay = (size, maxLines, cut) => {
618
+ const k = size / atlas.size;
619
+ const f = size / s.fontSize;
620
+ return layoutText(this._text, {
621
+ ascent: fm.ascent * k,
622
+ descent: fm.descent * k,
623
+ letterSpacing: s.letterSpacing * f,
624
+ lineHeight: s.lineHeight > 0 ? s.lineHeight * f : void 0,
625
+ align: s.align,
626
+ direction: s.direction,
627
+ wordWrap: s.wordWrap,
628
+ wordWrapWidth: s.wordWrapWidth,
629
+ breakWords: s.breakWords,
630
+ tabularNumbers: s.tabularNumbers,
631
+ kerning: s.kerning,
632
+ wordBreak: s.wordBreak,
633
+ tabSize: s.tabSize,
634
+ inlines: this._resolveInlines(font, k, fm.ascent * k, fm.descent * k),
635
+ maxLines: cut ? maxLines : 0,
636
+ maxWidth: cut && s.maxWidth > 0 ? s.maxWidth : void 0,
637
+ ellipsis: s.ellipsis
638
+ }, {
639
+ advance: (c) => atlas.advance(font, c) * k,
640
+ kerning: (a, b) => atlas.kerning(font, a, b) * k,
641
+ ink: (c) => {
642
+ const i = atlas.ink(font, c);
643
+ return {
644
+ ascent: i.ascent * k + reach,
645
+ descent: i.descent * k + reach
646
+ };
647
+ }
648
+ });
649
+ };
650
+ const fits = (l) => (s.maxWidth <= 0 || s.wordWrap || l.width <= s.maxWidth + 1e-6) && (s.maxHeight <= 0 || l.height <= s.maxHeight + 1e-6) && (s.maxLines <= 0 || l.lines.length <= s.maxLines);
651
+ let size = s.fontSize;
652
+ let layout = lay(size, 0, false);
653
+ if (s.shrinkToFit && !fits(layout)) {
654
+ let lo = Math.min(s.fontSize, s.minFontSize > 0 ? s.minFontSize : s.fontSize / 2);
655
+ let hi = s.fontSize;
656
+ if (fits(lay(lo, 0, false))) for (let i = 0; i < 8 && hi - lo > .05; i++) {
657
+ const mid = (lo + hi) / 2;
658
+ if (fits(lay(mid, 0, false))) lo = mid;
659
+ else hi = mid;
660
+ }
661
+ size = lo;
662
+ layout = lay(size, 0, false);
663
+ }
664
+ if (!fits(layout)) {
665
+ let lines = s.maxLines > 0 ? s.maxLines : Number.POSITIVE_INFINITY;
666
+ if (s.maxHeight > 0 && layout.height > s.maxHeight) {
667
+ const font = layout.ascent + layout.descent;
668
+ lines = Math.min(lines, Math.max(1, Math.floor((s.maxHeight - font) / layout.lineHeight + 1e-6) + 1));
669
+ }
670
+ layout = lay(size, Number.isFinite(lines) ? lines : 0, true);
671
+ }
672
+ const k = size / atlas.size;
673
+ this._size = size;
455
674
  const ox = -this.anchor.x * layout.width;
456
675
  const oy = -this.anchor.y * layout.height;
457
676
  const shadow = s.shadow && (s.shadow.alpha ?? 1) > 0 ? s.shadow : null;
677
+ const outline = s.outline && s.outline.width > 0 && (s.outline.alpha ?? 1) > 0 ? s.outline : null;
458
678
  const glyphs = layout.glyphs;
459
- const layers = shadow ? 2 : 1;
679
+ const passes = [];
680
+ if (shadow) passes.push([1, 0]);
681
+ if (outline) passes.push([0, 1], [0, 2]);
682
+ else passes.push([0, 0]);
460
683
  this._layout = layout;
461
684
  this._ox = ox;
462
685
  this._oy = oy;
463
- this._ensure(glyphs.length * layers);
686
+ this._passes = passes.length;
687
+ this._ensure(glyphs.length * passes.length);
464
688
  const f = this._f;
689
+ const bounds = this.geometry.localBounds;
690
+ const pad = atlas.pad * k;
465
691
  let n = 0;
466
- for (let layer = layers - 1; layer >= 0; layer--) {
692
+ bounds.clear();
693
+ bounds.addFrame(ox, oy, ox + layout.width, oy + layout.height);
694
+ for (const [layer, mode] of passes) {
467
695
  const dx = layer ? shadow?.offsetX ?? 0 : 0;
468
696
  const dy = layer ? shadow?.offsetY ?? 0 : 0;
697
+ const reach = Math.max(0, s.dilate) + (outline ? outline.width : 0) + (layer ? shadow?.blur ?? 4 : 0);
469
698
  for (const pg of glyphs) {
699
+ if (pg.inline) continue;
470
700
  const g = atlas.glyph(font, pg.char);
471
701
  if (g.w === 0) continue;
472
702
  const o = n * STRIDE;
473
703
  const x0 = ox + pg.x + g.left * k + dx;
474
704
  const y0 = oy + pg.y + g.top * k + dy;
705
+ bounds.addFrame(x0 + pad - reach, y0 + pad - reach, x0 + g.w * k - pad + reach, y0 + g.h * k - pad + reach);
475
706
  f[o] = x0;
476
707
  f[o + 1] = y0;
477
708
  f[o + 2] = x0 + g.w * k;
@@ -481,16 +712,14 @@ var SilkText = class SilkText extends Mesh {
481
712
  f[o + 6] = g.x + g.w;
482
713
  f[o + 7] = g.y + g.h;
483
714
  f[o + 8] = layer;
484
- f[o + 9] = 0;
485
- f[o + 10] = 0;
486
- f[o + 11] = 0;
715
+ f[o + 9] = mode;
716
+ f[o + 10] = g.color ? g.color.x : -1;
717
+ f[o + 11] = g.color ? g.color.y : -1;
487
718
  n++;
488
719
  }
489
720
  }
490
721
  this._count = n;
491
722
  const geometry = this.geometry;
492
- geometry.localBounds.clear();
493
- geometry.localBounds.addFrame(ox, oy, ox + layout.width, oy + layout.height);
494
723
  geometry.instanceCount = n;
495
724
  geometry.instanceBuffer.update(Math.max(n, 1) * STRIDE * 4);
496
725
  this._paint(s, k, ox, oy, layout);
@@ -546,7 +775,7 @@ var SilkText = class SilkText extends Mesh {
546
775
  atlas.radius,
547
776
  atlas.cutoff,
548
777
  k,
549
- s.fontSize
778
+ this._size
550
779
  ]);
551
780
  u.uFx.set([
552
781
  s.dilate,
@@ -23,6 +23,14 @@ export interface Glyph {
23
23
  left: number;
24
24
  /** Top edge of the cell relative to the baseline (negative is above it). */
25
25
  top: number;
26
+ /**
27
+ * Where a colour glyph (an emoji) keeps its colours: the top left of a cell of the same size in
28
+ * {@link SdfAtlas.colorSource}. Absent for one-colour glyphs.
29
+ */
30
+ color?: {
31
+ x: number;
32
+ y: number;
33
+ };
26
34
  }
27
35
  /** Vertical metrics of a font at the atlas size, measured the way PixiJS `Text` measures them. */
28
36
  export interface FontMetrics {
@@ -44,6 +52,11 @@ export interface GlyphContext {
44
52
  textBaseline: string;
45
53
  /** Horizontal anchor of `fillText`. The atlas sets `left`. */
46
54
  textAlign: string;
55
+ /**
56
+ * Base direction of `fillText` and `measureText`. The atlas sets `ltr` where the context has it,
57
+ * so a run of Arabic letters starts at the pen like any other glyph.
58
+ */
59
+ direction?: string;
47
60
  /** The canvas behind the context. The atlas grows it when a glyph does not fit. */
48
61
  readonly canvas: {
49
62
  /** Width in pixels. */
@@ -109,6 +122,12 @@ export declare class SdfAtlas {
109
122
  version: number;
110
123
  private _data;
111
124
  private _source;
125
+ private _cData;
126
+ private _cSource;
127
+ private _cHeight;
128
+ private _cShelves;
129
+ private _cNextY;
130
+ private _cDirty;
112
131
  private readonly _shaders;
113
132
  private _height;
114
133
  private readonly _width;
@@ -120,6 +139,13 @@ export declare class SdfAtlas {
120
139
  private _ctx;
121
140
  private _listening;
122
141
  constructor(options?: SdfAtlasOptions);
142
+ /**
143
+ * The RGBA texture with the colours of colour glyphs (emoji), premultiplied. It starts small and
144
+ * grows like {@link SdfAtlas.source}. Read it again after {@link SdfAtlas.flush}.
145
+ */
146
+ get colorSource(): BufferImageSource;
147
+ /** How full the atlas is, 0 to 1: the share of its largest texture that holds glyphs. Near 1 it will start over soon. */
148
+ get usage(): number;
123
149
  /**
124
150
  * The R8 texture with every glyph. When the atlas grows it moves to a new, taller texture, and
125
151
  * the shaders it tracks follow. Read it again after {@link SdfAtlas.flush} rather than keeping it.
@@ -129,12 +155,33 @@ export declare class SdfAtlas {
129
155
  get dimensions(): [width: number, height: number];
130
156
  /** Vertical metrics of a font at {@link SdfAtlas.size}. */
131
157
  metrics(font: FontSpec): FontMetrics;
132
- /** Advance width of one character at {@link SdfAtlas.size}, from `measureText`. */
158
+ /** Advance width of one character, or of a run of joined letters, at {@link SdfAtlas.size}, from `measureText`. */
133
159
  advance(font: FontSpec, char: string): number;
134
160
  /** Kerning between two characters at {@link SdfAtlas.size}: how much closer (negative) Canvas puts them. */
135
161
  kerning(font: FontSpec, a: string, b: string): number;
136
- /** The baked glyph of a character, baking it now if needed. Call {@link SdfAtlas.flush} to upload. */
162
+ /**
163
+ * The baked glyph of a character, or of a cluster (a base with its marks, a run of joined Arabic
164
+ * letters), baking it now if needed. Call {@link SdfAtlas.flush} to upload.
165
+ */
137
166
  glyph(font: FontSpec, char: string): Glyph;
167
+ /**
168
+ * The box `measureText` reports for a string at {@link SdfAtlas.size}: its ink above and below
169
+ * the baseline, and its advance. Nothing is baked. Stacked marks may reach past it, see
170
+ * {@link SdfAtlas.ink} for the exact ink of one glyph.
171
+ */
172
+ measure(font: FontSpec, text: string): {
173
+ ascent: number;
174
+ descent: number;
175
+ width: number;
176
+ };
177
+ /**
178
+ * Where a glyph's ink reaches, from its baked pixels, at {@link SdfAtlas.size}: up from the
179
+ * baseline (`ascent`) and down from it (`descent`). Zero for glyphs with no ink. Bakes the glyph.
180
+ */
181
+ ink(font: FontSpec, char: string): {
182
+ ascent: number;
183
+ descent: number;
184
+ };
138
185
  /** Uploads the texture if glyphs were baked since the last call. */
139
186
  flush(): void;
140
187
  /** Forgets every glyph and starts over. Texts rebake what they need on their next frame. */
@@ -142,6 +189,9 @@ export declare class SdfAtlas {
142
189
  /** Frees the texture. */
143
190
  destroy(): void;
144
191
  private _createSource;
192
+ private _createColorSource;
193
+ /** Shelf packing in the colour texture, which grows to {@link SdfAtlas} `maxHeight` like the other. */
194
+ private _placeColor;
145
195
  private _context;
146
196
  private _font;
147
197
  private _bake;