laymur 0.25.2 → 0.26.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 (118) hide show
  1. package/README.md +41 -5
  2. package/dist/core/elements/UIAnchor/UIAnchor.d.ts +2 -2
  3. package/dist/core/elements/UIAnchor/UIAnchor.js +3 -2
  4. package/dist/core/elements/UIDummy/UIDummy.Internal.d.ts +3 -0
  5. package/dist/core/elements/UIDummy/UIDummy.d.ts +32 -0
  6. package/dist/core/elements/UIDummy/UIDummy.js +101 -2
  7. package/dist/core/elements/UIElement/UIElement.d.ts +23 -1
  8. package/dist/core/elements/UIElement/UIElement.js +50 -3
  9. package/dist/core/elements/UIGraphics/UIGraphics.js +2 -2
  10. package/dist/core/elements/UIProgress/UIProgress.js +2 -5
  11. package/dist/core/elements/UIScene/UIScene.js +3 -2
  12. package/dist/core/elements/UIText/UIText.js +2 -2
  13. package/dist/core/index.d.ts +48 -2
  14. package/dist/core/index.js +13 -1
  15. package/dist/core/layers/UILayer/UILayer.d.ts +5 -1
  16. package/dist/core/layers/UILayer/UILayer.js +33 -1
  17. package/dist/core/miscellaneous/UIAffineMatrix3.d.ts +13 -0
  18. package/dist/core/miscellaneous/UIAffineMatrix3.js +13 -0
  19. package/dist/core/miscellaneous/area/UIArea.d.ts +10 -1
  20. package/dist/core/miscellaneous/area/UIArea.js +4 -1
  21. package/dist/core/miscellaneous/area/UIAreaCircle.d.ts +1 -0
  22. package/dist/core/miscellaneous/area/UIAreaCircle.js +0 -1
  23. package/dist/core/miscellaneous/area/UIAreaPolygon.d.ts +1 -0
  24. package/dist/core/miscellaneous/area/UIAreaPolygon.js +0 -1
  25. package/dist/core/miscellaneous/area/UIAreaRectangle.d.ts +1 -0
  26. package/dist/core/miscellaneous/area/UIAreaRectangle.js +0 -1
  27. package/dist/core/miscellaneous/area/UIAreaRoundedRectangle.d.ts +1 -0
  28. package/dist/core/miscellaneous/area/UIAreaRoundedRectangle.js +0 -1
  29. package/dist/core/miscellaneous/asserts.d.ts +9 -0
  30. package/dist/core/miscellaneous/asserts.js +16 -0
  31. package/dist/core/miscellaneous/color/UIColor.js +1 -0
  32. package/dist/core/miscellaneous/generic-plane/UIGenericInstancedPlane/UIGenericInstancedPlane.Internal.d.ts +17 -3
  33. package/dist/core/miscellaneous/generic-plane/UIGenericInstancedPlane/UIGenericInstancedPlane.Internal.js +88 -26
  34. package/dist/core/miscellaneous/generic-plane/UIGenericInstancedPlane/UIGenericInstancedPlane.Layout.d.ts +9 -0
  35. package/dist/core/miscellaneous/generic-plane/UIGenericInstancedPlane/UIGenericInstancedPlane.Layout.js +29 -6
  36. package/dist/core/miscellaneous/generic-plane/UIGenericInstancedPlane/UIGenericInstancedPlane.js +51 -11
  37. package/dist/core/miscellaneous/generic-plane/UIGenericPlaneRegistry/UIGenericPlaneRegistry.Internal.d.ts +2 -0
  38. package/dist/core/miscellaneous/generic-plane/UIGenericPlaneRegistry/UIGenericPlaneRegistry.js +47 -6
  39. package/dist/core/miscellaneous/generic-plane/shared.d.ts +15 -3
  40. package/dist/core/miscellaneous/generic-plane/shared.js +38 -7
  41. package/dist/core/miscellaneous/generic-plane/varyingPacking.d.ts +46 -0
  42. package/dist/core/miscellaneous/generic-plane/varyingPacking.js +170 -0
  43. package/dist/core/miscellaneous/mask/UIMask.Internal.d.ts +61 -0
  44. package/dist/core/miscellaneous/mask/UIMask.Internal.js +56 -0
  45. package/dist/core/miscellaneous/mask/UIMask.d.ts +84 -0
  46. package/dist/core/miscellaneous/mask/UIMask.js +265 -0
  47. package/dist/core/miscellaneous/mask/UIMaskMaterialPatch.d.ts +50 -0
  48. package/dist/core/miscellaneous/mask/UIMaskMaterialPatch.js +233 -0
  49. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunction.d.ts +10 -1
  50. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunction.js +7 -1
  51. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.d.ts +2 -0
  52. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.js +0 -1
  53. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionDirectional.d.ts +2 -0
  54. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionDirectional.js +0 -1
  55. package/dist/core/miscellaneous/micro/UIMicro.Internal.d.ts +3 -0
  56. package/dist/core/miscellaneous/micro/UIMicro.Internal.js +1 -0
  57. package/dist/core/miscellaneous/micro/UIMicro.d.ts +18 -1
  58. package/dist/core/miscellaneous/micro/UIMicro.js +23 -2
  59. package/dist/core/miscellaneous/resize-policy/UIResizePolicy.d.ts +16 -1
  60. package/dist/core/miscellaneous/resize-policy/UIResizePolicy.js +8 -2
  61. package/dist/core/miscellaneous/texture/UITextureView.d.ts +2 -1
  62. package/dist/core/miscellaneous/texture/UITextureView.js +3 -2
  63. package/dist/core/shaders/UIMask.d.ts +15 -0
  64. package/dist/core/shaders/UIMask.js +45 -0
  65. package/dist/core/wrappers/UISceneWrapper/UISceneWrapper.Internal.d.ts +2 -0
  66. package/dist/core/wrappers/UISceneWrapper/UISceneWrapper.d.ts +1 -0
  67. package/dist/core/wrappers/UISceneWrapper/UISceneWrapper.js +3 -0
  68. package/dist/debug/index.d.ts +2 -0
  69. package/dist/particles/behaviorModules/UIBehaviorDirectionalGravity.d.ts +7 -0
  70. package/dist/particles/behaviorModules/UIBehaviorDirectionalGravity.js +0 -2
  71. package/dist/particles/behaviorModules/UIBehaviorModule.d.ts +7 -1
  72. package/dist/particles/behaviorModules/UIBehaviorModule.js +2 -1
  73. package/dist/particles/behaviorModules/UIBehaviorPointGravity.d.ts +7 -0
  74. package/dist/particles/behaviorModules/UIBehaviorPointGravity.js +0 -2
  75. package/dist/particles/behaviorModules/UIBehaviorScaleOscillation.d.ts +7 -0
  76. package/dist/particles/behaviorModules/UIBehaviorScaleOscillation.js +0 -2
  77. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.d.ts +7 -0
  78. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.js +0 -2
  79. package/dist/particles/behaviorModules/UIBehaviorTorqueDamping.d.ts +7 -0
  80. package/dist/particles/behaviorModules/UIBehaviorTorqueDamping.js +0 -2
  81. package/dist/particles/behaviorModules/UIBehaviorTorqueNoise.d.ts +7 -0
  82. package/dist/particles/behaviorModules/UIBehaviorTorqueNoise.js +0 -2
  83. package/dist/particles/behaviorModules/UIBehaviorVelocityDamping.d.ts +7 -0
  84. package/dist/particles/behaviorModules/UIBehaviorVelocityDamping.js +0 -2
  85. package/dist/particles/behaviorModules/UIBehaviorVelocityNoise.d.ts +7 -0
  86. package/dist/particles/behaviorModules/UIBehaviorVelocityNoise.js +0 -2
  87. package/dist/particles/elements/UIEmitter.Internal.d.ts +7 -0
  88. package/dist/particles/elements/UIEmitter.d.ts +1 -8
  89. package/dist/particles/index.d.ts +5 -0
  90. package/dist/particles/index.js +3 -0
  91. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.d.ts +11 -2
  92. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.js +101 -72
  93. package/dist/particles/instancedParticle/UIInstancedParticle.d.ts +1 -0
  94. package/dist/particles/instancedParticle/UIInstancedParticle.js +4 -2
  95. package/dist/particles/renderingModules/UIRenderingColorOverLife.d.ts +4 -0
  96. package/dist/particles/renderingModules/UIRenderingColorOverLife.js +0 -2
  97. package/dist/particles/renderingModules/UIRenderingColorOverVelocity.d.ts +4 -0
  98. package/dist/particles/renderingModules/UIRenderingColorOverVelocity.js +0 -2
  99. package/dist/particles/renderingModules/UIRenderingModule.d.ts +10 -1
  100. package/dist/particles/renderingModules/UIRenderingModule.js +3 -1
  101. package/dist/particles/renderingModules/UIRenderingTexture.d.ts +4 -0
  102. package/dist/particles/spawnModules/UISpawnModule.d.ts +13 -1
  103. package/dist/particles/spawnModules/UISpawnModule.js +3 -1
  104. package/dist/particles/spawnModules/UISpawnOffset.d.ts +7 -0
  105. package/dist/particles/spawnModules/UISpawnOffset.js +0 -2
  106. package/dist/particles/spawnModules/UISpawnRandomLifetime.d.ts +7 -0
  107. package/dist/particles/spawnModules/UISpawnRandomLifetime.js +0 -2
  108. package/dist/particles/spawnModules/UISpawnRandomRotation.d.ts +7 -0
  109. package/dist/particles/spawnModules/UISpawnRandomRotation.js +0 -2
  110. package/dist/particles/spawnModules/UISpawnRandomScale.d.ts +7 -0
  111. package/dist/particles/spawnModules/UISpawnRandomScale.js +0 -2
  112. package/dist/particles/spawnModules/UISpawnRandomTorque.d.ts +7 -0
  113. package/dist/particles/spawnModules/UISpawnRandomTorque.js +0 -2
  114. package/dist/particles/spawnModules/UISpawnRandomVelocity.d.ts +7 -0
  115. package/dist/particles/spawnModules/UISpawnRandomVelocity.js +0 -2
  116. package/dist/particles/spawnModules/UISpawnRectangle.d.ts +7 -0
  117. package/dist/particles/spawnModules/UISpawnRectangle.js +0 -2
  118. package/package.json +1 -1
package/README.md CHANGED
@@ -17,7 +17,8 @@
17
17
 
18
18
  * **Cassowary solver** - constraint-based layouts via `@lume/kiwi`
19
19
  * **Orientation-aware** - define portrait and landscape rules in one layout, solver toggles automatically
20
- * **Micro-transforms** - visual-only transforms (scale, rotation, offset) that bypass the solver
20
+ * **Micro-transforms** - transforms (scale, rotation, offset) that bypass the solver; input follows them
21
+ * **Masks** - analytic shader masks (rectangle, rounded rectangle, ellipse) with soft edges and input clipping
21
22
  * **Color adjustment** - per-element hue/saturation/lightness and additive blend mode
22
23
  * **Resize policies** - Cover, Fit, FixedHeight, FixedWidth, Cross strategies
23
24
  * **Modular particles** - separate `laymur/particles` entry point, import only if needed
@@ -107,7 +108,36 @@ element.micro.scaleX = Math.sin(Date.now() * 0.001) + 1;
107
108
  element.micro.rotation += 0.01;
108
109
  ```
109
110
 
110
- ### 4. Color Adjustment
111
+ Input follows micro-transforms: a moved, rotated or scaled element is hit where it is drawn. Turn it off for effects where the hit area should stay put, such as shrinking a button while it is pressed:
112
+
113
+ ```typescript
114
+ button.micro.affectsInput = false;
115
+ ```
116
+
117
+ ### 4. Masks
118
+
119
+ `UIMask` follows the rectangle of a source element or of the layer, so it is laid out with constraints. Masks are computed in the shader: edges can be soft and masked elements keep batching together.
120
+
121
+ ```typescript
122
+ import { UIDummy, UIMask, UIMaskShape } from 'laymur';
123
+
124
+ // Scroll view: content moves, the viewport stays
125
+ const viewport = new UIDummy(layer);
126
+ const mask = new UIMask(viewport, { radius: 24, softness: 8, padding: 10 });
127
+ for (const item of items) {
128
+ item.mask = mask;
129
+ }
130
+
131
+ // Round avatar
132
+ avatar.mask = new UIMask(avatarFrame, { shape: UIMaskShape.ELLIPSE, softness: 2 });
133
+
134
+ // Tutorial spotlight: taps inside the hole reach the button below the overlay
135
+ dimOverlay.mask = new UIMask(ctaButton, { shape: UIMaskShape.ELLIPSE, inverted: true, softness: 40 });
136
+ ```
137
+
138
+ A mask also clips input and lives as long as its source. Particles are not clipped; three.js materials of your own can be, through `UIMaskMaterialPatch`.
139
+
140
+ ### 5. Color Adjustment
111
141
 
112
142
  Every element supports per-element color tweaks that run in the shader, independent of the layout solver.
113
143
 
@@ -122,7 +152,7 @@ element.lightness = 0.1; // offset (0 = unchanged)
122
152
  element.blendMode = UIBlendMode.ADDITIVE;
123
153
  ```
124
154
 
125
- ### 5. Particle System
155
+ ### 6. Particle System
126
156
 
127
157
  Modular pipeline: Spawn -> Behavior -> Rendering.
128
158
 
@@ -140,7 +170,7 @@ const emitter = new UIEmitter(
140
170
  emitter.play(60); // particles/sec
141
171
  ```
142
172
 
143
- ### 6. Debug Overlay
173
+ ### 7. Debug Overlay
144
174
 
145
175
  `laymur/debug` renders visual overlays for constraints - useful during development to inspect layout relationships.
146
176
 
@@ -174,12 +204,18 @@ Most commonly used exports (not exhaustive):
174
204
 
175
205
  ### Core
176
206
 
177
- UIFullscreenLayer, UIImage, UIAnimatedImage, UIText, UINineSlice, UIProgress
207
+ UIFullscreenLayer, UIImage, UIAnimatedImage, UIText, UINineSlice, UIProgress, UIMask
178
208
 
179
209
  ### Constraints
180
210
 
181
211
  UIAspectConstraint, UIHorizontalDistanceConstraint, UIVerticalDistanceConstraint, UIHorizontalProportionConstraint, UIVerticalProportionConstraint, UICoverConstraintBuilder, UIFitConstraintBuilder
182
212
 
213
+ ### Extension Points
214
+
215
+ UIElement, UIArea, UIResizePolicy, UIProgressMaskFunction, UIMaskMaterialPatch, UIAffineMatrix3
216
+
217
+ UIRenderingModule, UISpawnModule, UIBehaviorModule (laymur/particles)
218
+
183
219
  ### Particles (laymur/particles)
184
220
 
185
221
  UIEmitter, UISpawnRectangle, UISpawnRandomLifetime, UIBehaviorDirectionalGravity, UIBehaviorVelocityDamping, UIRenderingTexture, UIRenderingColorOverLife
@@ -34,8 +34,8 @@ export declare class UIAnchor implements UILayerElement, UIPointElement {
34
34
  /** Y coordinate relative to layer origin (bottom-left) */
35
35
  set y(value: number);
36
36
  /**
37
- * Removes element from its layer together with the constraints that refer to it.
38
- * Does nothing if the element is already destroyed.
37
+ * Removes element from its layer together with the constraints that refer to it and the
38
+ * masks that follow it. Does nothing if the element is already destroyed.
39
39
  */
40
40
  destroy(): void;
41
41
  /** Solver variables of the element; constraints that use any of them are destroyed with it */
@@ -50,8 +50,8 @@ export class UIAnchor {
50
50
  this.solverWrapper.suggestVariableValue(this.yVariable, value);
51
51
  }
52
52
  /**
53
- * Removes element from its layer together with the constraints that refer to it.
54
- * Does nothing if the element is already destroyed.
53
+ * Removes element from its layer together with the constraints that refer to it and the
54
+ * masks that follow it. Does nothing if the element is already destroyed.
55
55
  */
56
56
  destroy() {
57
57
  if (this.destroyedInternal) {
@@ -59,6 +59,7 @@ export class UIAnchor {
59
59
  }
60
60
  this.destroyedInternal = true;
61
61
  this.layer.destroyConstraintsUsingVariables(this.getSolverVariables());
62
+ this.layer.destroyMasksUsingSource(this);
62
63
  this.destroyInternal();
63
64
  this.layer.removeElement(this);
64
65
  }
@@ -1,4 +1,5 @@
1
1
  import type { UIArea } from "../../miscellaneous/area/UIArea.js";
2
+ import type { UIMask } from "../../miscellaneous/mask/UIMask.js";
2
3
  import { UIMode } from "../../miscellaneous/UIMode.js";
3
4
  import type { UIAnchorOptions } from "../UIAnchor/UIAnchor.Internal.js";
4
5
  import type { UIDummy } from "./UIDummy.js";
@@ -23,6 +24,8 @@ export interface UIDummyOptions extends UIAnchorOptions {
23
24
  interactionArea: UIArea;
24
25
  /** Controls visibility and interactivity */
25
26
  mode: UIMode;
27
+ /** Mask clipping the element, see UIDummy.mask */
28
+ mask: UIMask | null;
26
29
  }
27
30
  export declare const DUMMY_DEFAULT_WIDTH = 64;
28
31
  export declare const DUMMY_DEFAULT_HEIGHT = 32;
@@ -1,7 +1,10 @@
1
1
  import type { FerrsignView1 } from "ferrsign";
2
2
  import { Ferrsign1 } from "ferrsign";
3
+ import { Matrix4 } from "three";
3
4
  import type { UILayer } from "../../layers/UILayer/UILayer.js";
4
5
  import type { UIArea } from "../../miscellaneous/area/UIArea.js";
6
+ import type { UIMask } from "../../miscellaneous/mask/UIMask.js";
7
+ import type { UIMicro } from "../../miscellaneous/micro/UIMicro.js";
5
8
  import type { UIPlaneElement } from "../../miscellaneous/shared.js";
6
9
  import { UIMode } from "../../miscellaneous/UIMode.js";
7
10
  import type { UIInputWrapperView } from "../../wrappers/UIInputWrapper/UIInputWrapper.Internal.js";
@@ -19,6 +22,7 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
19
22
  protected readonly inputWrapper: UIInputWrapperView;
20
23
  private readonly catcherHandler;
21
24
  private wasPointerInside;
25
+ private maskInternal;
22
26
  private readonly signalPointerPressedInternal;
23
27
  private readonly signalPointerMovedInternal;
24
28
  private readonly signalPointerReleasedInternal;
@@ -50,6 +54,8 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
50
54
  * order of creation, a later one on top.
51
55
  */
52
56
  get zIndex(): number;
57
+ /** Mask clipping the element (input only, for an element that draws nothing); null for none */
58
+ get mask(): UIMask | null;
53
59
  /** Signal fired when pointer is pressed */
54
60
  get signalPointerPressed(): FerrsignView1<UIInputEventData>;
55
61
  /** Signal fired when pointer is moved */
@@ -81,10 +87,36 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
81
87
  * order of creation, a later one on top.
82
88
  */
83
89
  set zIndex(value: number);
90
+ /**
91
+ * Mask clipping the element (input only, for an element that draws nothing); null for none
92
+ * @throws If the mask is destroyed or belongs to another layer
93
+ */
94
+ set mask(value: UIMask | null);
95
+ /**
96
+ * Transform of the full element rectangle as drawn: maps the unit square
97
+ * (0,0 = bottom-left, 1,1 = top-right) to layer coordinates.
98
+ * @param includeMicro Whether to apply the micro transform, if the element has one
99
+ * @param result Matrix to write into
100
+ * @param depth Translation z of the result, such as the render depth
101
+ * @returns The result matrix
102
+ */
103
+ computeVisualTransform(includeMicro: boolean, result: Matrix4, depth?: number): Matrix4;
104
+ /**
105
+ * Micro transform the element is drawn with. Elements that have one override this, so that
106
+ * input and masks follow it; see {@link UIMicro.affectsInput}.
107
+ */
108
+ protected getMicro(): UIMicro | undefined;
84
109
  protected getSolverVariables(): number[];
85
110
  protected destroyInternal(): void;
86
111
  protected readonly catchPointerDown: (x: number, y: number, identifier: number) => boolean;
87
112
  protected readonly catchPointerMove: (x: number, y: number, identifier: number) => boolean;
88
113
  protected readonly catchPointerUp: (x: number, y: number, identifier: number) => boolean;
89
114
  protected handleInputEvent(x: number, y: number, identifier: number, signal: Ferrsign1<UIInputEventData>): boolean;
115
+ /**
116
+ * Whether a point in layer coordinates hits the element: it is in the visible part of the
117
+ * mask, if the mask clips input, and in the interaction area of the rectangle as drawn, when
118
+ * micro affects input.
119
+ */
120
+ private isInputPointInside;
121
+ private assertValidMask;
90
122
  }
@@ -1,11 +1,13 @@
1
1
  import { Ferrsign1 } from "ferrsign";
2
- import { MathUtils } from "three";
2
+ import { MathUtils, Matrix4 } from "three";
3
3
  import { UIAreaRectangle } from "../../miscellaneous/area/UIAreaRectangle.js";
4
4
  import { assertValidNumber, assertValidPositiveNumber } from "../../miscellaneous/asserts.js";
5
+ import { computeTransformMatrix } from "../../miscellaneous/computeTransform.js";
5
6
  import { isUIModeInteractive, UIMode } from "../../miscellaneous/UIMode.js";
6
7
  import { UIPriority } from "../../miscellaneous/UIPriority.js";
7
8
  import { UIAnchor } from "../UIAnchor/UIAnchor.js";
8
9
  import { DUMMY_DEFAULT_HEIGHT, DUMMY_DEFAULT_MODE, DUMMY_DEFAULT_WIDTH, DUMMY_DEFAULT_Z_INDEX, } from "./UIDummy.Internal.js";
10
+ const TEMP_INPUT_TRANSFORM = new Matrix4();
9
11
  /** Rectangular area with dimensions but no rendering */
10
12
  export class UIDummy extends UIAnchor {
11
13
  /**
@@ -21,6 +23,7 @@ export class UIDummy extends UIAnchor {
21
23
  assertValidPositiveNumber(h, "UIDummy.constructor.height");
22
24
  super(layer, options);
23
25
  this.wasPointerInside = false;
26
+ this.maskInternal = null;
24
27
  this.signalPointerPressedInternal = new Ferrsign1();
25
28
  this.signalPointerMovedInternal = new Ferrsign1();
26
29
  this.signalPointerReleasedInternal = new Ferrsign1();
@@ -42,6 +45,12 @@ export class UIDummy extends UIAnchor {
42
45
  this.hVariable = this.solverWrapper.createVariable(h, UIPriority.P6);
43
46
  this.catcherHandler = this.inputWrapper.createInputCatcher(this.catchPointerDown, this.catchPointerMove, this.catchPointerUp, DUMMY_DEFAULT_Z_INDEX);
44
47
  this.inputWrapper.setActive(this.catcherHandler, isUIModeInteractive(this.modeInternal));
48
+ const mask = options?.mask ?? null;
49
+ if (mask !== null) {
50
+ this.assertValidMask(mask, "UIDummy.constructor.options.mask");
51
+ this.maskInternal = mask;
52
+ mask.attach(this);
53
+ }
45
54
  }
46
55
  /** Width in world units */
47
56
  get width() {
@@ -78,6 +87,10 @@ export class UIDummy extends UIAnchor {
78
87
  get zIndex() {
79
88
  return this.inputWrapper.getZIndex(this.catcherHandler);
80
89
  }
90
+ /** Mask clipping the element (input only, for an element that draws nothing); null for none */
91
+ get mask() {
92
+ return this.maskInternal;
93
+ }
81
94
  /** Signal fired when pointer is pressed */
82
95
  get signalPointerPressed() {
83
96
  return this.signalPointerPressedInternal;
@@ -156,10 +169,60 @@ export class UIDummy extends UIAnchor {
156
169
  assertValidNumber(value, "UIDummy.zIndex");
157
170
  this.inputWrapper.setZIndex(this.catcherHandler, value);
158
171
  }
172
+ /**
173
+ * Mask clipping the element (input only, for an element that draws nothing); null for none
174
+ * @throws If the mask is destroyed or belongs to another layer
175
+ */
176
+ set mask(value) {
177
+ this.assertNotDestroyed("UIDummy.mask");
178
+ if (value === this.maskInternal) {
179
+ return;
180
+ }
181
+ if (value !== null) {
182
+ this.assertValidMask(value, "UIDummy.mask");
183
+ }
184
+ this.maskInternal?.detach(this);
185
+ this.maskInternal = value;
186
+ value?.attach(this);
187
+ }
188
+ /**
189
+ * Transform of the full element rectangle as drawn: maps the unit square
190
+ * (0,0 = bottom-left, 1,1 = top-right) to layer coordinates.
191
+ * @param includeMicro Whether to apply the micro transform, if the element has one
192
+ * @param result Matrix to write into
193
+ * @param depth Translation z of the result, such as the render depth
194
+ * @returns The result matrix
195
+ */
196
+ computeVisualTransform(includeMicro, result, depth = 0) {
197
+ const micro = includeMicro ? this.getMicro() : undefined;
198
+ if (micro === undefined) {
199
+ return result.makeScale(this.width, this.height, 1).setPosition(this.x, this.y, depth);
200
+ }
201
+ return result.copy(computeTransformMatrix(this.x, this.y, this.width, this.height, depth, micro.x, micro.y, micro.anchorX, micro.anchorY, micro.scaleX, micro.scaleY, micro.rotation, micro.anchorMode));
202
+ }
203
+ /**
204
+ * Takes the mask off the element when the mask is destroyed. Works on a destroyed element
205
+ * too, since a mask may be destroyed as part of destroying its own source.
206
+ * @internal
207
+ */
208
+ releaseMask(mask) {
209
+ if (this.maskInternal === mask) {
210
+ this.maskInternal = null;
211
+ }
212
+ }
213
+ /**
214
+ * Micro transform the element is drawn with. Elements that have one override this, so that
215
+ * input and masks follow it; see {@link UIMicro.affectsInput}.
216
+ */
217
+ getMicro() {
218
+ return undefined;
219
+ }
159
220
  getSolverVariables() {
160
221
  return [...super.getSolverVariables(), this.wVariable, this.hVariable];
161
222
  }
162
223
  destroyInternal() {
224
+ this.maskInternal?.detach(this);
225
+ this.maskInternal = null;
163
226
  this.solverWrapper.removeVariable(this.hVariable);
164
227
  this.solverWrapper.removeVariable(this.wVariable);
165
228
  this.inputWrapper.destroyInputCatcher(this.catcherHandler);
@@ -169,7 +232,7 @@ export class UIDummy extends UIAnchor {
169
232
  assertValidNumber(x, "UIDummy.handleInputEvent.x");
170
233
  assertValidNumber(y, "UIDummy.handleInputEvent.y");
171
234
  assertValidNumber(identifier, "UIDummy.handleInputEvent.identifier");
172
- const isPointerInside = this.interactionArea.contains(MathUtils.mapLinear(x, this.x, this.oppositeX, 0, 1), MathUtils.mapLinear(y, this.y, this.oppositeY, 0, 1));
235
+ const isPointerInside = this.isInputPointInside(x, y);
173
236
  if (isPointerInside) {
174
237
  signal.emit({ x, y, identifier, element: this });
175
238
  }
@@ -187,4 +250,40 @@ export class UIDummy extends UIAnchor {
187
250
  this.wasPointerInside = isPointerInside;
188
251
  return this.modeInternal !== UIMode.INTERACTIVE_TRANSPARENT && isPointerInside;
189
252
  }
253
+ /**
254
+ * Whether a point in layer coordinates hits the element: it is in the visible part of the
255
+ * mask, if the mask clips input, and in the interaction area of the rectangle as drawn, when
256
+ * micro affects input.
257
+ */
258
+ isInputPointInside(x, y) {
259
+ const mask = this.maskInternal;
260
+ if (mask !== null && mask.clipInput && !mask.containsPoint(x, y)) {
261
+ return false;
262
+ }
263
+ const micro = this.getMicro();
264
+ if (micro?.affectsInput !== true) {
265
+ return this.interactionArea.contains(MathUtils.mapLinear(x, this.x, this.oppositeX, 0, 1), MathUtils.mapLinear(y, this.y, this.oppositeY, 0, 1));
266
+ }
267
+ const e = this.computeVisualTransform(true, TEMP_INPUT_TRANSFORM).elements;
268
+ const axisXx = e[0];
269
+ const axisXy = e[1];
270
+ const axisYx = e[4];
271
+ const axisYy = e[5];
272
+ const determinant = axisXx * axisYy - axisYx * axisXy;
273
+ // Scaled to nothing: the element is not on screen
274
+ if (Math.abs(determinant) < Number.EPSILON) {
275
+ return false;
276
+ }
277
+ const deltaX = x - e[12];
278
+ const deltaY = y - e[13];
279
+ return this.interactionArea.contains((deltaX * axisYy - axisYx * deltaY) / determinant, (axisXx * deltaY - deltaX * axisXy) / determinant);
280
+ }
281
+ assertValidMask(mask, subject) {
282
+ if (mask.destroyed) {
283
+ throw new Error(`${subject}: mask is destroyed`);
284
+ }
285
+ if (mask.layer !== this.layer) {
286
+ throw new Error(`${subject}: mask belongs to another layer`);
287
+ }
288
+ }
190
289
  }
@@ -1,4 +1,5 @@
1
1
  import type { WebGLRenderer } from "three";
2
+ import { Matrix4 } from "three";
2
3
  import type { UILayer } from "../../layers/UILayer/UILayer.js";
3
4
  import type { UIProperty } from "../../miscellaneous/generic-plane/shared.js";
4
5
  import { UIMicro } from "../../miscellaneous/micro/UIMicro.js";
@@ -8,7 +9,13 @@ import type { UITransparencyMode } from "../../miscellaneous/UITransparencyMode.
8
9
  import type { UISceneWrapperView } from "../../wrappers/UISceneWrapper/UISceneWrapper.Internal.js";
9
10
  import { UIDummy } from "../UIDummy/UIDummy.js";
10
11
  import type { UIElementOptions } from "./UIElement.Internal.js";
11
- /** Base class for renderable UI elements */
12
+ /**
13
+ * Base class for renderable UI elements: a quad drawn with a custom fragment shader.
14
+ *
15
+ * The source defines `vec4 draw()` and reads `p_uv` and each property as `p_<name>`.
16
+ * Textures are uniforms, other properties are per instance, so elements sharing the source
17
+ * and textures batch together. Update properties with `sceneWrapper.setProperties`.
18
+ */
12
19
  export declare abstract class UIElement extends UIDummy {
13
20
  /** Transforms that don't affect constraints */
14
21
  readonly micro: UIMicro;
@@ -24,6 +31,10 @@ export declare abstract class UIElement extends UIDummy {
24
31
  private hslDirty;
25
32
  private readonly hslValue;
26
33
  private visibilityDirty;
34
+ /** Mask as last applied to the plane; compared every frame, see applyMask */
35
+ private appliedMask;
36
+ private appliedMaskVersion;
37
+ private appliedMaskHandler;
27
38
  /**
28
39
  * Creates a new UIElement instance.
29
40
  *
@@ -64,7 +75,18 @@ export declare abstract class UIElement extends UIDummy {
64
75
  set mode(value: UIMode);
65
76
  /** Frees resources of the element */
66
77
  protected destroyInternal(): void;
78
+ protected getMicro(): UIMicro;
67
79
  protected setPlaneTransform(): void;
80
+ /**
81
+ * Replaces the plane with one drawn by another shader source, keeping the visibility,
82
+ * transparency, blend, color adjustment and mask of the element.
83
+ */
84
+ protected recreatePlane(source: string, properties: Record<string, UIProperty>, transform: Matrix4): void;
68
85
  protected onWillRender(renderer: WebGLRenderer, deltaTime: number): void;
86
+ /**
87
+ * Brings the plane mask up to date. Pulled every frame rather than pushed: the mask data
88
+ * depends on the layout and micro of the mask source, whose dirty flags belong to the source.
89
+ */
90
+ private applyMask;
69
91
  private readonly handleWillRender;
70
92
  }
@@ -1,10 +1,16 @@
1
1
  import { Matrix4 } from "three";
2
- import { computeTransformMatrix } from "../../miscellaneous/computeTransform.js";
3
2
  import { UIMicro } from "../../miscellaneous/micro/UIMicro.js";
4
3
  import { isUIModeVisible } from "../../miscellaneous/UIMode.js";
5
4
  import { UIDummy } from "../UIDummy/UIDummy.js";
6
5
  import { blendModeToFactor, ELEMENT_DEFAULT_BLEND_MODE, ELEMENT_DEFAULT_HUE, ELEMENT_DEFAULT_LIGHTNESS, ELEMENT_DEFAULT_SATURATION, ELEMENT_DEFAULT_TRANSPARENCY_MODE, packHSL, } from "./UIElement.Internal.js";
7
- /** Base class for renderable UI elements */
6
+ const TEMP_TRANSFORM = new Matrix4();
7
+ /**
8
+ * Base class for renderable UI elements: a quad drawn with a custom fragment shader.
9
+ *
10
+ * The source defines `vec4 draw()` and reads `p_uv` and each property as `p_<name>`.
11
+ * Textures are uniforms, other properties are per instance, so elements sharing the source
12
+ * and textures batch together. Update properties with `sceneWrapper.setProperties`.
13
+ */
8
14
  export class UIElement extends UIDummy {
9
15
  /**
10
16
  * Creates a new UIElement instance.
@@ -21,6 +27,10 @@ export class UIElement extends UIDummy {
21
27
  this.hslDirty = false;
22
28
  this.hslValue = { h: 0, s: 0, l: 0 };
23
29
  this.visibilityDirty = false;
30
+ /** Mask as last applied to the plane; compared every frame, see applyMask */
31
+ this.appliedMask = null;
32
+ this.appliedMaskVersion = -1;
33
+ this.appliedMaskHandler = -1;
24
34
  this.handleWillRender = (renderer, deltaTime) => {
25
35
  this.onWillRender(renderer, deltaTime);
26
36
  };
@@ -111,12 +121,24 @@ export class UIElement extends UIDummy {
111
121
  this.sceneWrapper.destroyPlane(this.planeHandler);
112
122
  super.destroyInternal();
113
123
  }
124
+ getMicro() {
125
+ return this.micro;
126
+ }
114
127
  setPlaneTransform() {
115
128
  if (this.micro.dirty || this.inputWrapper.dirty || this.solverWrapper.dirty) {
116
- this.sceneWrapper.setTransform(this.planeHandler, computeTransformMatrix(this.x, this.y, this.width, this.height, this.renderDepth, this.micro.x, this.micro.y, this.micro.anchorX, this.micro.anchorY, this.micro.scaleX, this.micro.scaleY, this.micro.rotation, this.micro.anchorMode));
129
+ this.sceneWrapper.setTransform(this.planeHandler, this.computeVisualTransform(true, TEMP_TRANSFORM, this.renderDepth));
117
130
  this.micro.setDirtyFalse();
118
131
  }
119
132
  }
133
+ /**
134
+ * Replaces the plane with one drawn by another shader source, keeping the visibility,
135
+ * transparency, blend, color adjustment and mask of the element.
136
+ */
137
+ recreatePlane(source, properties, transform) {
138
+ this.sceneWrapper.destroyPlane(this.planeHandler);
139
+ this.planeHandler = this.sceneWrapper.createPlane(source, properties, transform, isUIModeVisible(this.modeInternal), this.transparencyModeInternal, blendModeToFactor(this.blendModeInternal), packHSL(this.hslValue, this.hueInternal, this.saturationInternal, this.lightnessInternal));
140
+ this.applyMask();
141
+ }
120
142
  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Required by UILayer event interface but not used in base implementation
121
143
  onWillRender(renderer, deltaTime) {
122
144
  if (this.transparencyModeDirty) {
@@ -135,6 +157,31 @@ export class UIElement extends UIDummy {
135
157
  this.sceneWrapper.setVisibility(this.planeHandler, isUIModeVisible(this.modeInternal));
136
158
  this.visibilityDirty = false;
137
159
  }
160
+ this.applyMask();
138
161
  this.setPlaneTransform();
139
162
  }
163
+ /**
164
+ * Brings the plane mask up to date. Pulled every frame rather than pushed: the mask data
165
+ * depends on the layout and micro of the mask source, whose dirty flags belong to the source.
166
+ */
167
+ applyMask() {
168
+ const mask = this.mask;
169
+ const planeChanged = this.appliedMaskHandler !== this.planeHandler;
170
+ if (mask !== this.appliedMask || planeChanged) {
171
+ this.appliedMask = mask;
172
+ this.appliedMaskHandler = this.planeHandler;
173
+ this.appliedMaskVersion = -1;
174
+ if (mask === null) {
175
+ this.sceneWrapper.setMask(this.planeHandler, null);
176
+ return;
177
+ }
178
+ }
179
+ if (mask !== null) {
180
+ mask.resolve();
181
+ if (mask.version !== this.appliedMaskVersion) {
182
+ this.sceneWrapper.setMask(this.planeHandler, mask.data);
183
+ this.appliedMaskVersion = mask.version;
184
+ }
185
+ }
186
+ }
140
187
  }
@@ -1,6 +1,6 @@
1
- import { Matrix3 } from "three";
2
1
  import { createCanvas, createCanvasTexture } from "../../miscellaneous/canvas.js";
3
2
  import { UIColor } from "../../miscellaneous/color/UIColor.js";
3
+ import { UIAffineMatrix3 } from "../../miscellaneous/UIAffineMatrix3.js";
4
4
  import source from "../../shaders/UIImage.js";
5
5
  import { UIElement } from "../UIElement/UIElement.js";
6
6
  import { GRAPHICS_DEFAULT_HEIGHT, GRAPHICS_DEFAULT_WIDTH, GRAPHICS_TEMP_COLOR, } from "./UIGraphics.Internal.js";
@@ -25,7 +25,7 @@ export class UIGraphics extends UIElement {
25
25
  texture.needsUpdate = true;
26
26
  super(layer, source, {
27
27
  texture: texture,
28
- textureTransform: new Matrix3(),
28
+ textureTransform: new UIAffineMatrix3(),
29
29
  color,
30
30
  }, options);
31
31
  this.canvas = canvas;
@@ -4,10 +4,8 @@ import { UIColor } from "../../miscellaneous/color/UIColor.js";
4
4
  import { computeTrimmedTransformMatrix } from "../../miscellaneous/computeTransform.js";
5
5
  import { UIProgressMaskFunctionDirectional } from "../../miscellaneous/mask-function/UIProgressMaskFunctionDirectional.js";
6
6
  import { UITextureView } from "../../miscellaneous/texture/UITextureView.js";
7
- import { isUIModeVisible } from "../../miscellaneous/UIMode.js";
8
7
  import source from "../../shaders/UIProgress.js";
9
8
  import { UIElement } from "../UIElement/UIElement.js";
10
- import { blendModeToFactor, packHSL } from "../UIElement/UIElement.Internal.js";
11
9
  import { PROGRESS_DEFAULT_VALUE } from "./UIProgress.Internal.js";
12
10
  /** Progress bar with customizable fill direction */
13
11
  export class UIProgress extends UIElement {
@@ -145,17 +143,16 @@ export class UIProgress extends UIElement {
145
143
  }
146
144
  }
147
145
  rebuildPlane() {
148
- this.sceneWrapper.destroyPlane(this.planeHandler);
149
146
  const micro = this.micro;
150
147
  const textureTrim = this.texture.trim;
151
- this.planeHandler = this.sceneWrapper.createPlane(this.maskFunctionInternal.source + source, {
148
+ this.recreatePlane(this.maskFunctionInternal.source + source, {
152
149
  texture: this.texture.texture,
153
150
  textureTransform: this.texture.calculateUVTransform(this.textureTransform),
154
151
  textureResolution: this.texture.getResolution(this.textureResolution),
155
152
  color: this.colorInternal,
156
153
  progress: this.progressInternal,
157
154
  ...this.maskFunctionInternal.enumerateProperties(),
158
- }, computeTrimmedTransformMatrix(this.x, this.y, this.width, this.height, this.renderDepth, micro.x, micro.y, micro.anchorX, micro.anchorY, micro.scaleX, micro.scaleY, micro.rotation, micro.anchorMode, textureTrim.left, textureTrim.right, textureTrim.top, textureTrim.bottom), isUIModeVisible(this.mode), this.transparencyMode, blendModeToFactor(this.blendMode), packHSL({ h: 0, s: 0, l: 0 }, this.hue, this.saturation, this.lightness));
155
+ }, computeTrimmedTransformMatrix(this.x, this.y, this.width, this.height, this.renderDepth, micro.x, micro.y, micro.anchorX, micro.anchorY, micro.scaleX, micro.scaleY, micro.rotation, micro.anchorMode, textureTrim.left, textureTrim.right, textureTrim.top, textureTrim.bottom));
159
156
  this.colorInternal.setDirtyFalse();
160
157
  this.texture.setTextureDirtyFalse();
161
158
  this.texture.setUVTransformDirtyFalse();
@@ -1,6 +1,7 @@
1
- import { Color, LinearFilter, MathUtils, Matrix3, PerspectiveCamera, RGBAFormat, Scene, UnsignedByteType, WebGLRenderTarget, } from "three";
1
+ import { Color, LinearFilter, MathUtils, PerspectiveCamera, RGBAFormat, Scene, UnsignedByteType, WebGLRenderTarget, } from "three";
2
2
  import { assertValidPositiveNumber } from "../../miscellaneous/asserts.js";
3
3
  import { UIColor } from "../../miscellaneous/color/UIColor.js";
4
+ import { UIAffineMatrix3 } from "../../miscellaneous/UIAffineMatrix3.js";
4
5
  import source from "../../shaders/UIImage.js";
5
6
  import { DUMMY_DEFAULT_HEIGHT, DUMMY_DEFAULT_WIDTH, } from "../UIDummy/UIDummy.Internal.js";
6
7
  import { UIElement } from "../UIElement/UIElement.js";
@@ -34,7 +35,7 @@ export class UIScene extends UIElement {
34
35
  const color = new UIColor(options.color);
35
36
  super(layer, source, {
36
37
  texture: renderTarget.texture,
37
- textureTransform: new Matrix3(),
38
+ textureTransform: new UIAffineMatrix3(),
38
39
  color,
39
40
  }, options);
40
41
  this.evenFrame = true;
@@ -1,9 +1,9 @@
1
- import { Matrix3 } from "three";
2
1
  import { createCanvas, createCanvasTexture } from "../../miscellaneous/canvas.js";
3
2
  import { UIColor } from "../../miscellaneous/color/UIColor.js";
4
3
  import { UIInsets } from "../../miscellaneous/insets/UIInsets.js";
5
4
  import { UITextSpan } from "../../miscellaneous/text-span/UITextSpan.js";
6
5
  import { UITextStyle } from "../../miscellaneous/text-style/UITextStyle.js";
6
+ import { UIAffineMatrix3 } from "../../miscellaneous/UIAffineMatrix3.js";
7
7
  import source from "../../shaders/UIImage.js";
8
8
  import { UIElement } from "../UIElement/UIElement.js";
9
9
  import { detectIsRTL } from "./UIText.Bidi.js";
@@ -30,7 +30,7 @@ export class UIText extends UIElement {
30
30
  const color = new UIColor(options.color);
31
31
  super(layer, source, {
32
32
  texture: texture,
33
- textureTransform: new Matrix3(),
33
+ textureTransform: new UIAffineMatrix3(),
34
34
  color,
35
35
  }, options);
36
36
  /** Padding last set by auto padding; any other value means it was changed by hand */