laymur 0.28.0 → 0.29.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.
Files changed (81) hide show
  1. package/README.md +53 -4
  2. package/dist/core/constraints/UIAspectConstraint/UIAspectConstraint.d.ts +14 -3
  3. package/dist/core/constraints/UIAspectConstraint/UIAspectConstraint.js +38 -5
  4. package/dist/core/constraints/UICustomConstraint.js +1 -1
  5. package/dist/core/constraints/UIHeightConstraint/UIHeightConstraint.js +1 -1
  6. package/dist/core/constraints/UIHorizontalDistanceConstraint/UIHorizontalDistanceConstraint.js +1 -1
  7. package/dist/core/constraints/UIHorizontalInterpolationConstraint/UIHorizontalInterpolationConstraint.js +1 -1
  8. package/dist/core/constraints/UIHorizontalProportionConstraint/UIHorizontalProportionConstraint.js +1 -1
  9. package/dist/core/constraints/UISingleParameterConstraint/UISingleParameterConstraint.d.ts +6 -0
  10. package/dist/core/constraints/UISingleParameterConstraint/UISingleParameterConstraint.js +8 -0
  11. package/dist/core/constraints/UIVerticalDistanceConstraint/UIVerticalDistanceConstraint.js +1 -1
  12. package/dist/core/constraints/UIVerticalInterpolationConstraint/UIVerticalInterpolationConstraint.js +1 -1
  13. package/dist/core/constraints/UIVerticalProportionConstraint/UIVerticalProportionConstraint.js +1 -1
  14. package/dist/core/constraints/UIWidthConstraint/UIWidthConstraint.js +1 -1
  15. package/dist/core/elements/UICanvasElement/UICanvasElement.d.ts +54 -0
  16. package/dist/core/elements/UICanvasElement/UICanvasElement.js +70 -0
  17. package/dist/core/elements/UIDummy/UIDummy.Internal.d.ts +2 -0
  18. package/dist/core/elements/UIDummy/UIDummy.js +3 -1
  19. package/dist/core/elements/UIGraphics/UIGraphics.Internal.d.ts +42 -2
  20. package/dist/core/elements/UIGraphics/UIGraphics.Internal.js +2 -2
  21. package/dist/core/elements/UIGraphics/UIGraphics.d.ts +48 -34
  22. package/dist/core/elements/UIGraphics/UIGraphics.js +196 -93
  23. package/dist/core/elements/UIImage/UIImage.d.ts +11 -1
  24. package/dist/core/elements/UIImage/UIImage.js +14 -0
  25. package/dist/core/elements/UIScene/UIScene.Internal.d.ts +10 -1
  26. package/dist/core/elements/UIScene/UIScene.Internal.js +1 -0
  27. package/dist/core/elements/UIScene/UIScene.d.ts +11 -1
  28. package/dist/core/elements/UIScene/UIScene.js +29 -5
  29. package/dist/core/elements/UIText/UIText.Interfaces.d.ts +2 -2
  30. package/dist/core/elements/UIText/UIText.Internal.d.ts +14 -1
  31. package/dist/core/elements/UIText/UIText.Internal.js +12 -0
  32. package/dist/core/elements/UIText/UIText.Measuring.d.ts +9 -4
  33. package/dist/core/elements/UIText/UIText.Measuring.js +17 -6
  34. package/dist/core/elements/UIText/UIText.Rendering.d.ts +7 -16
  35. package/dist/core/elements/UIText/UIText.Rendering.js +212 -46
  36. package/dist/core/elements/UIText/UIText.d.ts +58 -28
  37. package/dist/core/elements/UIText/UIText.js +113 -138
  38. package/dist/core/index.d.ts +10 -4
  39. package/dist/core/index.js +5 -1
  40. package/dist/core/layers/UILayer/UILayer.d.ts +17 -3
  41. package/dist/core/layers/UILayer/UILayer.js +35 -4
  42. package/dist/core/layers/UIViewportLayer/UIViewportLayer.d.ts +2 -0
  43. package/dist/core/layers/UIViewportLayer/UIViewportLayer.js +3 -0
  44. package/dist/core/miscellaneous/canvas-surface/UICanvasSurface.d.ts +46 -0
  45. package/dist/core/miscellaneous/canvas-surface/UICanvasSurface.js +86 -0
  46. package/dist/core/miscellaneous/color/UIColor.d.ts +17 -0
  47. package/dist/core/miscellaneous/color/UIColor.js +22 -0
  48. package/dist/core/miscellaneous/color/canvasColor.d.ts +9 -0
  49. package/dist/core/miscellaneous/color/canvasColor.js +15 -0
  50. package/dist/core/miscellaneous/insets/UIInsets.d.ts +3 -0
  51. package/dist/core/miscellaneous/insets/UIInsets.js +15 -0
  52. package/dist/core/miscellaneous/paint/UIGradient.Internal.d.ts +37 -0
  53. package/dist/core/miscellaneous/paint/UIGradient.Internal.js +14 -0
  54. package/dist/core/miscellaneous/paint/UIGradient.d.ts +18 -0
  55. package/dist/core/miscellaneous/paint/UIGradient.js +35 -0
  56. package/dist/core/miscellaneous/paint/UILinearGradient.d.ts +14 -0
  57. package/dist/core/miscellaneous/paint/UILinearGradient.js +22 -0
  58. package/dist/core/miscellaneous/paint/UIPaint.Internal.d.ts +21 -0
  59. package/dist/core/miscellaneous/paint/UIPaint.Internal.js +1 -0
  60. package/dist/core/miscellaneous/paint/UIPaint.d.ts +17 -0
  61. package/dist/core/miscellaneous/paint/UIPaint.js +21 -0
  62. package/dist/core/miscellaneous/paint/UIRadialGradient.d.ts +18 -0
  63. package/dist/core/miscellaneous/paint/UIRadialGradient.js +33 -0
  64. package/dist/core/miscellaneous/shared.d.ts +14 -0
  65. package/dist/core/miscellaneous/shared.js +11 -0
  66. package/dist/core/miscellaneous/text-style/UITextStyle.Internal.d.ts +88 -30
  67. package/dist/core/miscellaneous/text-style/UITextStyle.Internal.js +12 -8
  68. package/dist/core/miscellaneous/text-style/UITextStyle.d.ts +41 -66
  69. package/dist/core/miscellaneous/text-style/UITextStyle.js +165 -294
  70. package/dist/core/miscellaneous/texture/UITextureView.Internal.d.ts +2 -1
  71. package/dist/core/miscellaneous/texture/UITextureView.Internal.js +12 -3
  72. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.Internal.d.ts +1 -1
  73. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.d.ts +1 -1
  74. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.js +1 -1
  75. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.Internal.d.ts +6 -2
  76. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.d.ts +41 -9
  77. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.js +97 -35
  78. package/dist/particles/elements/UIEmitter.Internal.d.ts +3 -0
  79. package/dist/particles/elements/UIEmitter.Internal.js +1 -0
  80. package/dist/particles/elements/UIEmitter.js +3 -2
  81. package/package.json +1 -1
package/README.md CHANGED
@@ -19,6 +19,7 @@
19
19
  - **Orientation-aware** - define portrait and landscape rules in one layout, solver toggles automatically
20
20
  - **Micro-transforms** - transforms (scale, rotation, offset) that bypass the solver; input follows them
21
21
  - **Masks** - analytic shader masks (rectangle, rounded rectangle, ellipse) with soft edges and input clipping
22
+ - **Text effects** - gradient fills, stacked outlines, shadows and glows, drawn at screen resolution
22
23
  - **Color adjustment** - per-element hue/saturation/lightness and additive blend mode
23
24
  - **Resize policies** - Cover, Fit, FixedHeight, FixedWidth, Cross strategies
24
25
  - **Modular particles** - separate `laymur/particles` entry point, import only if needed
@@ -184,7 +185,55 @@ element.lightness = 0.1; // offset (0 = unchanged)
184
185
  element.blendMode = UIBlendMode.ADDITIVE;
185
186
  ```
186
187
 
187
- ### 6. Particle System
188
+ ### 6. Text and Graphics
189
+
190
+ `UIText` and `UIGraphics` draw on a canvas. Both redraw it at the size the element takes on the
191
+ screen, so they stay sharp on high-DPI screens and when constraints enlarge them.
192
+
193
+ ```typescript
194
+ import { UIGraphics, UILinearGradient, UIText } from "laymur";
195
+
196
+ const title = new UIText(layer, "WELL DONE!", {
197
+ commonStyle: {
198
+ fontSize: 64,
199
+ fontWeight: "bold",
200
+ color: new UILinearGradient([
201
+ { offset: 0, color: "#fff6b0" },
202
+ { offset: 1, color: "#ff7a00" },
203
+ ]),
204
+ strokes: [
205
+ { paint: "#7a2a00", thickness: 4 },
206
+ { paint: "#ffffff", thickness: 4 },
207
+ ],
208
+ shadows: [
209
+ { color: "rgba(0, 0, 0, 0.6)", offsetY: 6 },
210
+ { color: "rgba(255, 230, 0, 0.9)", blur: 12 },
211
+ ],
212
+ },
213
+ });
214
+
215
+ const panel = new UIGraphics(layer, { width: 300, height: 200 });
216
+ panel.drawRoundedRect(0, 0, 300, 200, 24, {
217
+ fill: "#2060ff",
218
+ stroke: { paint: "#ffffff", width: 4 },
219
+ });
220
+ ```
221
+
222
+ - Text is laid out in pixels of its style. With `UITextResizeMode.SCALE`, scaling the element with
223
+ constraints does not change the line breaks. With `BREAK` the text rewraps to the width.
224
+ - A gradient is laid over the box of what it fills, in fractions of that box from its top left
225
+ corner. For text the box is each line or the whole text (`paintBox`), for a shape its bounds.
226
+ - Strokes stack outward from the glyphs in list order. Shadows are cast by the outlined glyphs,
227
+ the first one on top, and a shadow without an offset is a glow.
228
+ - `UIGraphics` keeps its shapes until `clear()`. They are drawn in a box as large as the width and
229
+ height the element is created with, y pointing down, and the box is stretched over the element.
230
+ - With `lineBox: UITextLineBox.FONT` the height of a line comes from the font metrics, so texts
231
+ of one font aligned by an edge share the baseline.
232
+ - A `UIAspectConstraint` without an aspect follows the aspect of the text as it rewraps, and the
233
+ aspect of the texture of a `UIImage`.
234
+ - Micro transforms do not redraw the canvas.
235
+
236
+ ### 7. Particle System
188
237
 
189
238
  Modular pipeline: Spawn -> Behavior -> Rendering.
190
239
 
@@ -259,7 +308,7 @@ places each particle where it was at the particle's moment within the frame, and
259
308
  positions and the points of behavior modules are layer coordinates. In `LOCAL` space, the default,
260
309
  live particles move with the emitter.
261
310
 
262
- ### 7. Debug Overlay
311
+ ### 8. Debug Overlay
263
312
 
264
313
  `laymur/debug` renders visual overlays for constraints - useful during development to inspect layout relationships.
265
314
 
@@ -293,7 +342,7 @@ Most commonly used exports (not exhaustive):
293
342
 
294
343
  ### Core
295
344
 
296
- UIViewportLayer, UIImage, UIAnimatedImage, UIText, UINineSlice, UIProgress, UIMask
345
+ UIViewportLayer, UIImage, UIAnimatedImage, UIText, UIGraphics, UINineSlice, UIProgress, UIMask, UILinearGradient, UIRadialGradient
297
346
 
298
347
  ### Constraints
299
348
 
@@ -301,7 +350,7 @@ UIAspectConstraint, UIHorizontalDistanceConstraint, UIVerticalDistanceConstraint
301
350
 
302
351
  ### Extension Points
303
352
 
304
- UIElement, UIArea, UIResizePolicy, UIViewport, UIProgressMaskFunction, UIMaskMaterialPatch, UIAffineMatrix3
353
+ UIElement, UIArea, UIGradient, UIResizePolicy, UIViewport, UIProgressMaskFunction, UIMaskMaterialPatch, UIAffineMatrix3
305
354
 
306
355
  UIRenderingModule, UISpawnModule, UIBehaviorModule (laymur/particles)
307
356
 
@@ -1,22 +1,33 @@
1
1
  import type { UILayerElement, UIPlaneElement } from "../../miscellaneous/shared.js";
2
2
  import { UISingleParameterConstraint } from "../UISingleParameterConstraint/UISingleParameterConstraint.js";
3
3
  import type { UIAspectConstraintOptions } from "./UIAspectConstraint.Internal.js";
4
- /** Maintains element aspect ratio (width = height * aspect) */
4
+ /**
5
+ * Maintains element aspect ratio (width = height * aspect). Without an aspect in the options it
6
+ * follows the content of an element that has its own aspect, such as `UIText` or `UIImage`, and
7
+ * keeps the current ratio of any other element.
8
+ */
5
9
  export declare class UIAspectConstraint extends UISingleParameterConstraint {
6
10
  readonly element: UIPlaneElement & UILayerElement;
7
11
  /** Solver constraint descriptor */
8
12
  protected readonly constraint: number;
9
13
  /** Current aspect ratio */
10
14
  private aspectInternal;
15
+ /** Element whose content aspect the constraint follows, null once an aspect is set */
16
+ private followedContent;
11
17
  /**
12
18
  * @param element Element to constrain
13
- * @param options Aspect configuration. Defaults to element's current ratio.
19
+ * @param options Aspect configuration. Without an aspect, the content aspect of the element or
20
+ * its current ratio.
14
21
  */
15
22
  constructor(element: UIPlaneElement & UILayerElement, options?: Partial<UIAspectConstraintOptions>);
16
23
  /** Current aspect ratio (width/height) */
17
24
  get aspect(): number;
18
- /** Updates aspect ratio */
25
+ /** Updates aspect ratio. The constraint stops following the content aspect of the element. */
19
26
  set aspect(value: number);
27
+ protected destroyInternal(): void;
28
+ private applyAspect;
29
+ private stopFollowingContent;
20
30
  /** Builds constraint expression: width - (height * aspect) = 0 */
21
31
  private buildLHS;
32
+ private readonly onContentAspectChanged;
22
33
  }
@@ -1,12 +1,18 @@
1
1
  import { assertValidPositiveNumber } from "../../miscellaneous/asserts.js";
2
+ import { isUIContentAspectElement } from "../../miscellaneous/shared.js";
2
3
  import { UIExpression } from "../../miscellaneous/UIExpression.js";
3
4
  import { assertValidConstraintElement } from "../constraintAsserts.js";
4
5
  import { UISingleParameterConstraint } from "../UISingleParameterConstraint/UISingleParameterConstraint.js";
5
- /** Maintains element aspect ratio (width = height * aspect) */
6
+ /**
7
+ * Maintains element aspect ratio (width = height * aspect). Without an aspect in the options it
8
+ * follows the content of an element that has its own aspect, such as `UIText` or `UIImage`, and
9
+ * keeps the current ratio of any other element.
10
+ */
6
11
  export class UIAspectConstraint extends UISingleParameterConstraint {
7
12
  /**
8
13
  * @param element Element to constrain
9
- * @param options Aspect configuration. Defaults to element's current ratio.
14
+ * @param options Aspect configuration. Without an aspect, the content aspect of the element or
15
+ * its current ratio.
10
16
  */
11
17
  constructor(element, options = {}) {
12
18
  if (options.aspect !== undefined) {
@@ -14,22 +20,49 @@ export class UIAspectConstraint extends UISingleParameterConstraint {
14
20
  }
15
21
  super(assertValidConstraintElement(element, "UIAspectConstraint.constructor"), options);
16
22
  this.element = element;
17
- this.aspectInternal = options.aspect ?? element.width / element.height;
18
- this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled());
23
+ /** Element whose content aspect the constraint follows, null once an aspect is set */
24
+ this.followedContent = null;
25
+ this.onContentAspectChanged = (aspect) => {
26
+ this.applyAspect(aspect);
27
+ };
28
+ if (options.aspect !== undefined) {
29
+ this.aspectInternal = options.aspect;
30
+ }
31
+ else if (isUIContentAspectElement(element)) {
32
+ this.aspectInternal = element.contentAspect;
33
+ this.followedContent = element;
34
+ element.signalContentAspectChanged.on(this.onContentAspectChanged);
35
+ }
36
+ else {
37
+ this.aspectInternal = element.width / element.height;
38
+ }
39
+ this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled(), this);
19
40
  }
20
41
  /** Current aspect ratio (width/height) */
21
42
  get aspect() {
22
43
  return this.aspectInternal;
23
44
  }
24
- /** Updates aspect ratio */
45
+ /** Updates aspect ratio. The constraint stops following the content aspect of the element. */
25
46
  set aspect(value) {
26
47
  this.assertNotDestroyed("UIAspectConstraint.aspect");
27
48
  assertValidPositiveNumber(value, "UIAspectConstraint.aspect");
49
+ this.stopFollowingContent();
50
+ this.applyAspect(value);
51
+ }
52
+ destroyInternal() {
53
+ this.stopFollowingContent();
54
+ super.destroyInternal();
55
+ }
56
+ applyAspect(value) {
28
57
  if (this.aspectInternal !== value) {
29
58
  this.aspectInternal = value;
30
59
  this.solverWrapper.setConstraintLHS(this.constraint, this.buildLHS());
31
60
  }
32
61
  }
62
+ stopFollowingContent() {
63
+ this.followedContent?.signalContentAspectChanged.off(this.onContentAspectChanged);
64
+ this.followedContent = null;
65
+ }
33
66
  /** Builds constraint expression: width - (height * aspect) = 0 */
34
67
  buildLHS() {
35
68
  return new UIExpression(0, [
@@ -12,7 +12,7 @@ export class UICustomConstraint extends UISingleParameterConstraint {
12
12
  super(assertValidConstraintExpressions(layer, [lhs, rhs], "UICustomConstraint.constructor"), options);
13
13
  this.lhsInternal = lhs;
14
14
  this.rhsInternal = rhs;
15
- this.constraint = this.solverWrapper.createConstraint(this.lhsInternal, this.rhsInternal, this.relation, this.priority, this.isConstraintEnabled());
15
+ this.constraint = this.solverWrapper.createConstraint(this.lhsInternal, this.rhsInternal, this.relation, this.priority, this.isConstraintEnabled(), this);
16
16
  }
17
17
  /** Left-hand side expression */
18
18
  get lhs() {
@@ -15,7 +15,7 @@ export class UIHeightConstraint extends UISingleParameterConstraint {
15
15
  super(assertValidConstraintElement(element, "UIHeightConstraint.constructor"), options);
16
16
  this.element = element;
17
17
  this.heightInternal = options.height ?? element.height;
18
- this.constraint = this.solverWrapper.createConstraint(new UIExpression(0, [[this.element.hVariable, 1]]), new UIExpression(this.heightInternal), this.relation, this.priority, this.isConstraintEnabled());
18
+ this.constraint = this.solverWrapper.createConstraint(new UIExpression(0, [[this.element.hVariable, 1]]), new UIExpression(this.heightInternal), this.relation, this.priority, this.isConstraintEnabled(), this);
19
19
  }
20
20
  /** Current height in world units */
21
21
  get height() {
@@ -27,7 +27,7 @@ export class UIHorizontalDistanceConstraint extends UISingleParameterConstraint
27
27
  this.anchorAInternal = options.anchorA ?? DEFAULT_ANCHOR;
28
28
  this.anchorBInternal = options.anchorB ?? DEFAULT_ANCHOR;
29
29
  this.distanceInternal = options.distance ?? 0;
30
- this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(this.distanceInternal), this.relation, this.priority, this.isConstraintEnabled());
30
+ this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(this.distanceInternal), this.relation, this.priority, this.isConstraintEnabled(), this);
31
31
  }
32
32
  /** Current distance in world units */
33
33
  get distance() {
@@ -35,7 +35,7 @@ export class UIHorizontalInterpolationConstraint extends UISingleParameterConstr
35
35
  this.anchorBInternal = anchorB;
36
36
  this.anchorCInternal = options.anchorC ?? DEFAULT_ANCHOR;
37
37
  this.tInternal = options.t ?? DEFAULT_T;
38
- this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled());
38
+ this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled(), this);
39
39
  }
40
40
  /** Interpolation factor (0 = A position, 1 = B position) */
41
41
  get t() {
@@ -17,7 +17,7 @@ export class UIHorizontalProportionConstraint extends UISingleParameterConstrain
17
17
  this.a = a;
18
18
  this.b = b;
19
19
  this.proportionInternal = options.proportion ?? 1;
20
- this.constraint = this.solverWrapper.createConstraint(new UIExpression(0), this.buildRHS(), this.relation, this.priority, this.isConstraintEnabled());
20
+ this.constraint = this.solverWrapper.createConstraint(new UIExpression(0), this.buildRHS(), this.relation, this.priority, this.isConstraintEnabled(), this);
21
21
  }
22
22
  /** Current proportion multiplier */
23
23
  get proportion() {
@@ -25,6 +25,12 @@ export declare abstract class UISingleParameterConstraint extends UIConstraint {
25
25
  get relation(): UIRelation;
26
26
  /** When constraint is active */
27
27
  get orientation(): UIOrientation;
28
+ /**
29
+ * Whether the solver applies the constraint. False while the orientation of the layer disables
30
+ * it, or while it conflicts with other required (P0) constraints, the later created of which is
31
+ * not applied. A conflict throws in development builds and warns in production builds.
32
+ */
33
+ get applied(): boolean;
28
34
  /** Updates constraint priority */
29
35
  set priority(value: UIPriority);
30
36
  /** Updates constraint relation */
@@ -31,6 +31,14 @@ export class UISingleParameterConstraint extends UIConstraint {
31
31
  get orientation() {
32
32
  return this.orientationInternal;
33
33
  }
34
+ /**
35
+ * Whether the solver applies the constraint. False while the orientation of the layer disables
36
+ * it, or while it conflicts with other required (P0) constraints, the later created of which is
37
+ * not applied. A conflict throws in development builds and warns in production builds.
38
+ */
39
+ get applied() {
40
+ return !this.destroyed && this.solverWrapper.isConstraintApplied(this.constraint);
41
+ }
34
42
  /** Updates constraint priority */
35
43
  set priority(value) {
36
44
  this.assertNotDestroyed("UISingleParameterConstraint.priority");
@@ -27,7 +27,7 @@ export class UIVerticalDistanceConstraint extends UISingleParameterConstraint {
27
27
  this.anchorAInternal = options.anchorA ?? DEFAULT_ANCHOR;
28
28
  this.anchorBInternal = options.anchorB ?? DEFAULT_ANCHOR;
29
29
  this.distanceInternal = options.distance ?? 0;
30
- this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(this.distanceInternal), this.relation, this.priority, this.isConstraintEnabled());
30
+ this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(this.distanceInternal), this.relation, this.priority, this.isConstraintEnabled(), this);
31
31
  }
32
32
  /** Current distance in world units */
33
33
  get distance() {
@@ -35,7 +35,7 @@ export class UIVerticalInterpolationConstraint extends UISingleParameterConstrai
35
35
  this.anchorBInternal = anchorB;
36
36
  this.anchorCInternal = options.anchorC ?? DEFAULT_ANCHOR;
37
37
  this.tInternal = options.t ?? DEFAULT_T;
38
- this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled());
38
+ this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled(), this);
39
39
  }
40
40
  /** Interpolation factor (0 = A position, 1 = B position) */
41
41
  get t() {
@@ -17,7 +17,7 @@ export class UIVerticalProportionConstraint extends UISingleParameterConstraint
17
17
  this.a = a;
18
18
  this.b = b;
19
19
  this.proportionInternal = options.proportion ?? 1;
20
- this.constraint = this.solverWrapper.createConstraint(new UIExpression(0), this.buildRHS(), this.relation, this.priority, this.isConstraintEnabled());
20
+ this.constraint = this.solverWrapper.createConstraint(new UIExpression(0), this.buildRHS(), this.relation, this.priority, this.isConstraintEnabled(), this);
21
21
  }
22
22
  /** Current proportion multiplier */
23
23
  get proportion() {
@@ -15,7 +15,7 @@ export class UIWidthConstraint extends UISingleParameterConstraint {
15
15
  super(assertValidConstraintElement(element, "UIWidthConstraint.constructor"), options);
16
16
  this.element = element;
17
17
  this.widthInternal = options.width ?? element.width;
18
- this.constraint = this.solverWrapper.createConstraint(new UIExpression(0, [[this.element.wVariable, 1]]), new UIExpression(this.widthInternal), this.relation, this.priority, this.isConstraintEnabled());
18
+ this.constraint = this.solverWrapper.createConstraint(new UIExpression(0, [[this.element.wVariable, 1]]), new UIExpression(this.widthInternal), this.relation, this.priority, this.isConstraintEnabled(), this);
19
19
  }
20
20
  /** Current width in world units */
21
21
  get width() {
@@ -0,0 +1,54 @@
1
+ import type { WebGLRenderer } from "three";
2
+ import type { UILayer } from "../../layers/UILayer/UILayer.js";
3
+ import type { UICanvasRenderingContext2D } from "../../miscellaneous/canvas.js";
4
+ import { UICanvasSurface } from "../../miscellaneous/canvas-surface/UICanvasSurface.js";
5
+ import type { UIColorConfig } from "../../miscellaneous/color/UIColor.Internal.js";
6
+ import { UIColor } from "../../miscellaneous/color/UIColor.js";
7
+ import type { UIElementOptions } from "../UIElement/UIElement.Internal.js";
8
+ import { UIElement } from "../UIElement/UIElement.js";
9
+ /**
10
+ * Element showing content drawn on a canvas. The content is drawn in content units and
11
+ * rasterized at the size the element takes on the screen, so it stays sharp when constraints
12
+ * enlarge the element and on high-DPI screens. The canvas is drawn again when the content changes
13
+ * or when the needed raster scale crosses a step. Micro transforms and the tint do not redraw it.
14
+ */
15
+ export declare abstract class UICanvasElement extends UIElement {
16
+ /** Canvas the content is drawn on, also usable for measuring between drawings */
17
+ protected readonly surface: UICanvasSurface;
18
+ private readonly colorInternal;
19
+ /** Raster scale the canvas holds, NaN before the first drawing */
20
+ private rasterScale;
21
+ /** Pixel density of the layer the raster scale was calculated for */
22
+ private rasterPixelDensity;
23
+ /** Width of the content in content units */
24
+ protected abstract readonly contentWidth: number;
25
+ /** Height of the content in content units */
26
+ protected abstract readonly contentHeight: number;
27
+ /**
28
+ * @param layer - Layer containing this element
29
+ * @param subject - Name of the subclass constructor, used in errors
30
+ * @param options - Configuration options
31
+ */
32
+ constructor(layer: UILayer, subject: string, options?: Partial<UIElementOptions> & {
33
+ color?: UIColorConfig;
34
+ });
35
+ /** Multiplicative tint. Alpha channel controls opacity. */
36
+ get color(): UIColor;
37
+ /** Multiplicative tint. Alpha channel controls opacity. */
38
+ set color(value: UIColorConfig);
39
+ /** Frees the canvas texture */
40
+ protected destroyInternal(): void;
41
+ protected onWillRender(renderer: WebGLRenderer, deltaTime: number): void;
42
+ /**
43
+ * Brings the content up to date before a frame.
44
+ * @param layoutChanged - Whether the solver changed the layout since the last frame
45
+ * @returns True when the content changed and has to be drawn again
46
+ */
47
+ protected abstract updateContent(layoutChanged: boolean): boolean;
48
+ /**
49
+ * Draws the content on the cleared canvas. The context transform maps content units onto the
50
+ * canvas.
51
+ * @param context - Canvas context
52
+ */
53
+ protected abstract drawContent(context: UICanvasRenderingContext2D): void;
54
+ }
@@ -0,0 +1,70 @@
1
+ import { calculateRasterScale, UICanvasSurface, } from "../../miscellaneous/canvas-surface/UICanvasSurface.js";
2
+ import { UIColor } from "../../miscellaneous/color/UIColor.js";
3
+ import { UIAffineMatrix3 } from "../../miscellaneous/UIAffineMatrix3.js";
4
+ import source from "../../shaders/UIImage.js";
5
+ import { UIElement } from "../UIElement/UIElement.js";
6
+ /**
7
+ * Element showing content drawn on a canvas. The content is drawn in content units and
8
+ * rasterized at the size the element takes on the screen, so it stays sharp when constraints
9
+ * enlarge the element and on high-DPI screens. The canvas is drawn again when the content changes
10
+ * or when the needed raster scale crosses a step. Micro transforms and the tint do not redraw it.
11
+ */
12
+ export class UICanvasElement extends UIElement {
13
+ /**
14
+ * @param layer - Layer containing this element
15
+ * @param subject - Name of the subclass constructor, used in errors
16
+ * @param options - Configuration options
17
+ */
18
+ constructor(layer, subject, options) {
19
+ const surface = new UICanvasSurface(subject);
20
+ const color = new UIColor(options?.color);
21
+ super(layer, source, {
22
+ texture: surface.texture,
23
+ textureTransform: new UIAffineMatrix3(),
24
+ color,
25
+ }, options);
26
+ /** Raster scale the canvas holds, NaN before the first drawing */
27
+ this.rasterScale = Number.NaN;
28
+ /** Pixel density of the layer the raster scale was calculated for */
29
+ this.rasterPixelDensity = Number.NaN;
30
+ this.surface = surface;
31
+ this.colorInternal = color;
32
+ }
33
+ /** Multiplicative tint. Alpha channel controls opacity. */
34
+ get color() {
35
+ return this.colorInternal;
36
+ }
37
+ /** Multiplicative tint. Alpha channel controls opacity. */
38
+ set color(value) {
39
+ this.colorInternal.set(value);
40
+ }
41
+ /** Frees the canvas texture */
42
+ destroyInternal() {
43
+ this.surface.dispose();
44
+ super.destroyInternal();
45
+ }
46
+ onWillRender(renderer, deltaTime) {
47
+ const layoutChanged = this.consumeLayoutChange();
48
+ const contentChanged = this.updateContent(layoutChanged);
49
+ const pixelDensity = this.layer.pixelDensity;
50
+ if (contentChanged || layoutChanged || pixelDensity !== this.rasterPixelDensity) {
51
+ this.rasterPixelDensity = pixelDensity;
52
+ const width = this.contentWidth;
53
+ const height = this.contentHeight;
54
+ const rasterScale = calculateRasterScale(width, height, pixelDensity * Math.max(this.width / width, this.height / height));
55
+ if (contentChanged || rasterScale !== this.rasterScale) {
56
+ this.rasterScale = rasterScale;
57
+ const textureReplaced = this.surface.begin(width, height, rasterScale);
58
+ this.drawContent(this.surface.context);
59
+ if (textureReplaced) {
60
+ this.sceneWrapper.setProperties(this.planeHandler, { texture: this.surface.texture });
61
+ }
62
+ }
63
+ }
64
+ if (this.colorInternal.dirty) {
65
+ this.sceneWrapper.setProperties(this.planeHandler, { color: this.colorInternal });
66
+ this.colorInternal.setDirtyFalse();
67
+ }
68
+ super.onWillRender(renderer, deltaTime);
69
+ }
70
+ }
@@ -34,6 +34,8 @@ export interface UIDummyOptions extends UIAnchorOptions {
34
34
  interactionArea: UIArea;
35
35
  /** Controls visibility and interactivity */
36
36
  mode: UIMode;
37
+ /** Rendering and input priority, see UIDummy.zIndex */
38
+ zIndex: number;
37
39
  /** Mask clipping the element, see UIDummy.mask */
38
40
  mask: UIMask | null;
39
41
  }
@@ -21,6 +21,8 @@ export class UIDummy extends UIAnchor {
21
21
  const h = options?.height ?? DUMMY_DEFAULT_HEIGHT;
22
22
  assertValidPositiveNumber(w, "UIDummy.constructor.width");
23
23
  assertValidPositiveNumber(h, "UIDummy.constructor.height");
24
+ const zIndex = options?.zIndex ?? DUMMY_DEFAULT_Z_INDEX;
25
+ assertValidNumber(zIndex, "UIDummy.constructor.options.zIndex");
24
26
  super(layer, options);
25
27
  this.pointers = new Map();
26
28
  this.maskInternal = null;
@@ -79,7 +81,7 @@ export class UIDummy extends UIAnchor {
79
81
  catchPointerMove: this.catchPointerMove,
80
82
  catchPointerUp: this.catchPointerUp,
81
83
  catchPointerCancel: this.catchPointerCancel,
82
- }, DUMMY_DEFAULT_Z_INDEX);
84
+ }, zIndex);
83
85
  this.inputWrapper.setActive(this.catcherHandler, isUIModeInteractive(this.modeInternal));
84
86
  const mask = options?.mask ?? null;
85
87
  if (mask !== null) {
@@ -1,11 +1,51 @@
1
1
  import type { UIColorConfig } from "../../miscellaneous/color/UIColor.Internal.js";
2
- import { UIColor } from "../../miscellaneous/color/UIColor.js";
2
+ import type { UILineCap, UILineJoin, UIPaint, UIPaintBox, UIPaintConfig } from "../../miscellaneous/paint/UIPaint.Internal.js";
3
3
  import type { UIElementOptions } from "../UIElement/UIElement.Internal.js";
4
4
  /** Configuration options for UIGraphics */
5
5
  export interface UIGraphicsOptions extends UIElementOptions {
6
6
  /** Multiplicative tint */
7
7
  color: UIColorConfig;
8
8
  }
9
+ /** Line along the outline of a shape, centered on it */
10
+ export interface UIGraphicsStrokeConfig {
11
+ /** Color or gradient of the line */
12
+ paint: UIPaintConfig;
13
+ /** Line width in drawing units */
14
+ width: number;
15
+ /** How the corners are joined. Miter by default. */
16
+ join?: UILineJoin;
17
+ /** How the open ends look. Butt by default. */
18
+ cap?: UILineCap;
19
+ }
20
+ /** How a shape is painted. A shape without a fill and a stroke is not drawn. */
21
+ export interface UIGraphicsStyle {
22
+ /** Color or gradient inside the shape */
23
+ fill?: UIPaintConfig;
24
+ /** Line along the outline of the shape */
25
+ stroke?: UIGraphicsStrokeConfig;
26
+ }
27
+ /** Shape as kept until the graphics is cleared */
28
+ export interface UIGraphicsShape {
29
+ /** Builds the path of the shape on a context */
30
+ buildPath: (context: CanvasPath) => void;
31
+ /**
32
+ * Bounds of the path. A fill gradient is laid over them, a stroke gradient over them widened
33
+ * by half the stroke on each side.
34
+ */
35
+ box: UIPaintBox;
36
+ /** Fill, if any */
37
+ fill?: UIPaint;
38
+ /** Stroke, if any */
39
+ stroke?: {
40
+ paint: UIPaint;
41
+ width: number;
42
+ join: UILineJoin;
43
+ cap: UILineCap;
44
+ };
45
+ }
46
+ /** Corner radius of a rounded rectangle, one for all corners or four from the top left clockwise */
47
+ export type UIGraphicsCornerRadius = number | readonly [number, number, number, number];
9
48
  export declare const GRAPHICS_DEFAULT_WIDTH = 2;
10
49
  export declare const GRAPHICS_DEFAULT_HEIGHT = 2;
11
- export declare const GRAPHICS_TEMP_COLOR: UIColor;
50
+ export declare const GRAPHICS_DEFAULT_STROKE_JOIN: "miter";
51
+ export declare const GRAPHICS_DEFAULT_STROKE_CAP: "butt";
@@ -1,4 +1,4 @@
1
- import { UIColor } from "../../miscellaneous/color/UIColor.js";
2
1
  export const GRAPHICS_DEFAULT_WIDTH = 2;
3
2
  export const GRAPHICS_DEFAULT_HEIGHT = 2;
4
- export const GRAPHICS_TEMP_COLOR = new UIColor();
3
+ export const GRAPHICS_DEFAULT_STROKE_JOIN = "miter";
4
+ export const GRAPHICS_DEFAULT_STROKE_CAP = "butt";
@@ -1,51 +1,65 @@
1
- import type { WebGLRenderer } from "three";
2
1
  import type { UILayer } from "../../layers/UILayer/UILayer.js";
3
- import type { UIColorConfig } from "../../miscellaneous/color/UIColor.Internal.js";
4
- import { UIColor } from "../../miscellaneous/color/UIColor.js";
5
- import { UIElement } from "../UIElement/UIElement.js";
6
- import type { UIGraphicsOptions } from "./UIGraphics.Internal.js";
7
- /** Canvas-based 2D drawing element */
8
- export declare class UIGraphics extends UIElement {
9
- private readonly colorInternal;
10
- private readonly canvas;
11
- private readonly context;
12
- private readonly texture;
2
+ import type { UICanvasRenderingContext2D } from "../../miscellaneous/canvas.js";
3
+ import type { Vector2Like } from "../../miscellaneous/math.js";
4
+ import type { UIPaintConfig } from "../../miscellaneous/paint/UIPaint.Internal.js";
5
+ import { UICanvasElement } from "../UICanvasElement/UICanvasElement.js";
6
+ import type { UIGraphicsCornerRadius, UIGraphicsOptions, UIGraphicsStrokeConfig, UIGraphicsStyle } from "./UIGraphics.Internal.js";
7
+ /**
8
+ * 2D vector drawing element. Shapes are drawn in a drawing box as large as the width and height
9
+ * the element is created with, from its top left corner with y pointing down, and the box is
10
+ * stretched over the element. The shapes are kept until `clear`.
11
+ */
12
+ export declare class UIGraphics extends UICanvasElement {
13
+ /** Width of the drawing box */
14
+ protected readonly contentWidth: number;
15
+ /** Height of the drawing box */
16
+ protected readonly contentHeight: number;
17
+ private readonly shapes;
18
+ private shapesDirty;
13
19
  /**
14
20
  * Creates a new UIGraphics instance.
15
21
  *
16
22
  * @param layer - Layer containing this element
17
- * @param options - Configuration options
23
+ * @param options - Configuration options. The width and height also set the drawing box.
18
24
  */
19
25
  constructor(layer: UILayer, options?: Partial<UIGraphicsOptions>);
20
- /** Multiplicative tint. Alpha channel controls opacity. */
21
- get color(): UIColor;
22
- /** Multiplicative tint. Alpha channel controls opacity. */
23
- set color(value: UIColorConfig);
24
26
  /**
25
- * Clears canvas. Optionally fills with color.
27
+ * Removes all shapes. Optionally fills the drawing box.
26
28
  *
27
- * @param color - Fill color after clearing
29
+ * @param fill - Color or gradient filling the box after clearing
28
30
  */
29
- clear(color?: UIColorConfig): this;
30
- /** Draws filled rectangle */
31
- drawRect(x: number, y: number, width: number, height: number, color: UIColorConfig): this;
32
- /** Draws filled circle */
33
- drawCircle(x: number, y: number, radius: number, color: UIColorConfig): this;
31
+ clear(fill?: UIPaintConfig): this;
32
+ /** Draws a rectangle */
33
+ drawRect(x: number, y: number, width: number, height: number, style: UIGraphicsStyle): this;
34
34
  /**
35
- * Draws filled arc.
35
+ * Draws a rectangle with rounded corners. Each radius is clamped to half of the shorter side.
36
36
  *
37
- * @param startAngle - Start angle in radians
38
- * @param endAngle - End angle in radians
37
+ * @param radius - One radius for all corners, or four from the top left clockwise
39
38
  */
40
- drawArc(x: number, y: number, radius: number, startAngle: number, endAngle: number, color: UIColorConfig): this;
39
+ drawRoundedRect(x: number, y: number, width: number, height: number, radius: UIGraphicsCornerRadius, style: UIGraphicsStyle): this;
40
+ /** Draws a circle */
41
+ drawCircle(x: number, y: number, radius: number, style: UIGraphicsStyle): this;
41
42
  /**
42
- * Draws connected line segments.
43
+ * Draws an arc of a circle. A fill covers the part cut off by the chord between its ends.
44
+ * Gradients are laid over the bounds of the whole circle.
43
45
  *
44
- * @param points - Array of [x, y] pairs
45
- * @param lineWidth - Line width in pixels
46
+ * @param startAngle - Start angle in radians, clockwise from the right
47
+ * @param endAngle - End angle in radians, clockwise from the right
46
48
  */
47
- drawPolyline(points: [number, number][], color: UIColorConfig, lineWidth?: number): this;
48
- /** Frees resources of the graphics */
49
- protected destroyInternal(): void;
50
- protected onWillRender(renderer: WebGLRenderer, deltaTime: number): void;
49
+ drawArc(x: number, y: number, radius: number, startAngle: number, endAngle: number, style: UIGraphicsStyle): this;
50
+ /**
51
+ * Draws a closed polygon. Needs at least three points.
52
+ *
53
+ * @param points - Corners in order
54
+ */
55
+ drawPolygon(points: readonly Vector2Like[], style: UIGraphicsStyle): this;
56
+ /**
57
+ * Draws connected line segments. Needs at least two points.
58
+ *
59
+ * @param points - Points in order
60
+ */
61
+ drawPolyline(points: readonly Vector2Like[], stroke: UIGraphicsStrokeConfig): this;
62
+ protected updateContent(): boolean;
63
+ protected drawContent(context: UICanvasRenderingContext2D): void;
64
+ private addShape;
51
65
  }