laymur 0.25.2 → 0.27.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 (186) hide show
  1. package/README.md +114 -34
  2. package/dist/core/constraints/UICustomConstraint.d.ts +1 -1
  3. package/dist/core/constraints/UIHorizontalInterpolationConstraint/UIHorizontalInterpolationConstraint.js +1 -1
  4. package/dist/core/constraints/UIVerticalInterpolationConstraint/UIVerticalInterpolationConstraint.js +1 -1
  5. package/dist/core/constraints/builders/UIConstraint2DBuilder.d.ts +2 -3
  6. package/dist/core/elements/UIAnchor/UIAnchor.d.ts +2 -2
  7. package/dist/core/elements/UIAnchor/UIAnchor.js +3 -2
  8. package/dist/core/elements/UIAnimatedImage/UIAnimatedImage.d.ts +2 -2
  9. package/dist/core/elements/UIAnimatedImage/UIAnimatedImage.js +24 -12
  10. package/dist/core/elements/UIDummy/UIDummy.Internal.d.ts +13 -0
  11. package/dist/core/elements/UIDummy/UIDummy.d.ts +74 -5
  12. package/dist/core/elements/UIDummy/UIDummy.js +222 -29
  13. package/dist/core/elements/UIElement/UIElement.Internal.d.ts +1 -1
  14. package/dist/core/elements/UIElement/UIElement.d.ts +37 -1
  15. package/dist/core/elements/UIElement/UIElement.js +84 -6
  16. package/dist/core/elements/UIGraphics/UIGraphics.Internal.d.ts +1 -1
  17. package/dist/core/elements/UIGraphics/UIGraphics.d.ts +1 -1
  18. package/dist/core/elements/UIGraphics/UIGraphics.js +4 -4
  19. package/dist/core/elements/UIImage/UIImage.d.ts +2 -2
  20. package/dist/core/elements/UIImage/UIImage.js +10 -8
  21. package/dist/core/elements/UINineSlice/UINineSlice.d.ts +4 -4
  22. package/dist/core/elements/UINineSlice/UINineSlice.js +11 -9
  23. package/dist/core/elements/UIProgress/UIProgress.d.ts +2 -2
  24. package/dist/core/elements/UIProgress/UIProgress.js +17 -15
  25. package/dist/core/elements/UIScene/UIScene.Internal.d.ts +1 -1
  26. package/dist/core/elements/UIScene/UIScene.d.ts +3 -2
  27. package/dist/core/elements/UIScene/UIScene.js +21 -14
  28. package/dist/core/elements/UIText/UIText.Measuring.d.ts +1 -1
  29. package/dist/core/elements/UIText/UIText.d.ts +3 -3
  30. package/dist/core/elements/UIText/UIText.js +8 -8
  31. package/dist/core/index.d.ts +60 -11
  32. package/dist/core/index.js +22 -7
  33. package/dist/core/layers/UILayer/UILayer.d.ts +45 -5
  34. package/dist/core/layers/UILayer/UILayer.js +103 -10
  35. package/dist/core/layers/UIViewportLayer/UIViewportLayer.Internal.d.ts +27 -0
  36. package/dist/core/layers/{UIFullscreenLayer/UIFullscreenLayer.Internal.js → UIViewportLayer/UIViewportLayer.Internal.js} +1 -1
  37. package/dist/core/layers/UIViewportLayer/UIViewportLayer.d.ts +98 -0
  38. package/dist/core/layers/UIViewportLayer/UIViewportLayer.js +251 -0
  39. package/dist/core/miscellaneous/UIAffineMatrix3.d.ts +13 -0
  40. package/dist/core/miscellaneous/UIAffineMatrix3.js +13 -0
  41. package/dist/core/miscellaneous/area/UIArea.d.ts +10 -1
  42. package/dist/core/miscellaneous/area/UIArea.js +4 -1
  43. package/dist/core/miscellaneous/area/UIAreaCircle.d.ts +1 -0
  44. package/dist/core/miscellaneous/area/UIAreaCircle.js +0 -1
  45. package/dist/core/miscellaneous/area/UIAreaPolygon.d.ts +1 -0
  46. package/dist/core/miscellaneous/area/UIAreaPolygon.js +0 -1
  47. package/dist/core/miscellaneous/area/UIAreaRectangle.d.ts +1 -0
  48. package/dist/core/miscellaneous/area/UIAreaRectangle.js +0 -1
  49. package/dist/core/miscellaneous/area/UIAreaRoundedRectangle.d.ts +1 -0
  50. package/dist/core/miscellaneous/area/UIAreaRoundedRectangle.js +0 -1
  51. package/dist/core/miscellaneous/asserts.d.ts +23 -0
  52. package/dist/core/miscellaneous/asserts.js +44 -0
  53. package/dist/core/miscellaneous/canvas.js +7 -2
  54. package/dist/core/miscellaneous/color/UIColor.js +5 -2
  55. package/dist/core/miscellaneous/computeTransform.d.ts +12 -0
  56. package/dist/core/miscellaneous/computeTransform.js +20 -0
  57. package/dist/core/miscellaneous/context-monitor/UIContextMonitor.d.ts +1 -0
  58. package/dist/core/miscellaneous/context-monitor/UIContextMonitor.js +60 -0
  59. package/dist/core/miscellaneous/generic-plane/UIGenericInstancedPlane/UIGenericInstancedPlane.Internal.d.ts +17 -3
  60. package/dist/core/miscellaneous/generic-plane/UIGenericInstancedPlane/UIGenericInstancedPlane.Internal.js +88 -26
  61. package/dist/core/miscellaneous/generic-plane/UIGenericInstancedPlane/UIGenericInstancedPlane.Layout.d.ts +9 -0
  62. package/dist/core/miscellaneous/generic-plane/UIGenericInstancedPlane/UIGenericInstancedPlane.Layout.js +29 -6
  63. package/dist/core/miscellaneous/generic-plane/UIGenericInstancedPlane/UIGenericInstancedPlane.js +51 -11
  64. package/dist/core/miscellaneous/generic-plane/UIGenericPlaneRegistry/UIGenericPlaneRegistry.Internal.d.ts +2 -0
  65. package/dist/core/miscellaneous/generic-plane/UIGenericPlaneRegistry/UIGenericPlaneRegistry.js +47 -6
  66. package/dist/core/miscellaneous/generic-plane/shared.d.ts +15 -3
  67. package/dist/core/miscellaneous/generic-plane/shared.js +38 -7
  68. package/dist/core/miscellaneous/generic-plane/varyingPacking.d.ts +46 -0
  69. package/dist/core/miscellaneous/generic-plane/varyingPacking.js +170 -0
  70. package/dist/core/miscellaneous/mask/UIMask.Internal.d.ts +61 -0
  71. package/dist/core/miscellaneous/mask/UIMask.Internal.js +56 -0
  72. package/dist/core/miscellaneous/mask/UIMask.d.ts +84 -0
  73. package/dist/core/miscellaneous/mask/UIMask.js +265 -0
  74. package/dist/core/miscellaneous/mask/UIMaskMaterialPatch.d.ts +50 -0
  75. package/dist/core/miscellaneous/mask/UIMaskMaterialPatch.js +233 -0
  76. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunction.d.ts +10 -1
  77. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunction.js +7 -1
  78. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.d.ts +2 -0
  79. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.js +0 -1
  80. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionDirectional.d.ts +2 -0
  81. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionDirectional.js +0 -1
  82. package/dist/core/miscellaneous/micro/UIMicro.Internal.d.ts +3 -0
  83. package/dist/core/miscellaneous/micro/UIMicro.Internal.js +1 -0
  84. package/dist/core/miscellaneous/micro/UIMicro.d.ts +18 -1
  85. package/dist/core/miscellaneous/micro/UIMicro.js +23 -2
  86. package/dist/core/miscellaneous/resize-policy/UIResizePolicy.d.ts +19 -1
  87. package/dist/core/miscellaneous/resize-policy/UIResizePolicy.js +16 -3
  88. package/dist/core/miscellaneous/resize-policy/UIResizePolicyCover.js +2 -2
  89. package/dist/core/miscellaneous/resize-policy/UIResizePolicyCross.js +2 -2
  90. package/dist/core/miscellaneous/resize-policy/UIResizePolicyCrossInverted.js +2 -2
  91. package/dist/core/miscellaneous/resize-policy/UIResizePolicyFit.js +2 -2
  92. package/dist/core/miscellaneous/resize-policy/UIResizePolicyFixedHeight.js +2 -2
  93. package/dist/core/miscellaneous/resize-policy/UIResizePolicyFixedWidth.js +2 -2
  94. package/dist/core/miscellaneous/text-style/UITextStyle.js +2 -2
  95. package/dist/core/miscellaneous/texture/UITextureView.d.ts +6 -2
  96. package/dist/core/miscellaneous/texture/UITextureView.js +13 -9
  97. package/dist/core/miscellaneous/viewport/UIElementViewport.d.ts +31 -0
  98. package/dist/core/miscellaneous/viewport/UIElementViewport.js +54 -0
  99. package/dist/core/miscellaneous/viewport/UIViewport.d.ts +37 -0
  100. package/dist/core/miscellaneous/viewport/UIViewport.js +31 -0
  101. package/dist/core/miscellaneous/viewport/UIWindowViewport.d.ts +13 -0
  102. package/dist/core/miscellaneous/viewport/UIWindowViewport.js +25 -0
  103. package/dist/core/miscellaneous/webglCapabilities.js +61 -55
  104. package/dist/core/shaders/UIMask.d.ts +15 -0
  105. package/dist/core/shaders/UIMask.js +45 -0
  106. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.Internal.d.ts +36 -5
  107. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.d.ts +23 -2
  108. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.js +153 -15
  109. package/dist/core/wrappers/UISceneWrapper/UISceneWrapper.Internal.d.ts +3 -1
  110. package/dist/core/wrappers/UISceneWrapper/UISceneWrapper.d.ts +1 -0
  111. package/dist/core/wrappers/UISceneWrapper/UISceneWrapper.js +3 -0
  112. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.Internal.d.ts +2 -0
  113. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.d.ts +3 -0
  114. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.js +36 -16
  115. package/dist/debug/UIAspectDebug.js +4 -0
  116. package/dist/debug/UIHeightDebug.js +4 -0
  117. package/dist/debug/UIHorizontalDistanceDebug.js +5 -0
  118. package/dist/debug/UIHorizontalInterpolationDebug.js +5 -0
  119. package/dist/debug/UILayerDebug.d.ts +7 -0
  120. package/dist/debug/UILayerDebug.js +21 -0
  121. package/dist/debug/UIVerticalDistanceDebug.js +5 -0
  122. package/dist/debug/UIVerticalInterpolationDebug.js +5 -0
  123. package/dist/debug/UIWidthDebug.js +4 -0
  124. package/dist/debug/index.d.ts +2 -0
  125. package/dist/particles/behaviorModules/UIBehaviorDirectionalGravity.d.ts +8 -1
  126. package/dist/particles/behaviorModules/UIBehaviorDirectionalGravity.js +0 -2
  127. package/dist/particles/behaviorModules/UIBehaviorModule.d.ts +12 -2
  128. package/dist/particles/behaviorModules/UIBehaviorModule.js +2 -1
  129. package/dist/particles/behaviorModules/UIBehaviorPointGravity.d.ts +8 -1
  130. package/dist/particles/behaviorModules/UIBehaviorPointGravity.js +13 -12
  131. package/dist/particles/behaviorModules/UIBehaviorScaleOscillation.d.ts +7 -0
  132. package/dist/particles/behaviorModules/UIBehaviorScaleOscillation.js +6 -6
  133. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.d.ts +7 -0
  134. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.js +4 -5
  135. package/dist/particles/behaviorModules/UIBehaviorTorqueDamping.d.ts +8 -1
  136. package/dist/particles/behaviorModules/UIBehaviorTorqueDamping.js +8 -10
  137. package/dist/particles/behaviorModules/UIBehaviorTorqueNoise.d.ts +10 -2
  138. package/dist/particles/behaviorModules/UIBehaviorTorqueNoise.js +8 -7
  139. package/dist/particles/behaviorModules/UIBehaviorVelocityDamping.d.ts +7 -0
  140. package/dist/particles/behaviorModules/UIBehaviorVelocityDamping.js +8 -10
  141. package/dist/particles/behaviorModules/UIBehaviorVelocityNoise.d.ts +13 -4
  142. package/dist/particles/behaviorModules/UIBehaviorVelocityNoise.js +12 -10
  143. package/dist/particles/elements/UIEmitter.Internal.d.ts +21 -1
  144. package/dist/particles/elements/UIEmitter.Internal.js +6 -0
  145. package/dist/particles/elements/UIEmitter.d.ts +20 -11
  146. package/dist/particles/elements/UIEmitter.js +100 -54
  147. package/dist/particles/index.d.ts +7 -1
  148. package/dist/particles/index.js +4 -0
  149. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.d.ts +19 -4
  150. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.js +117 -83
  151. package/dist/particles/instancedParticle/UIInstancedParticle.d.ts +8 -0
  152. package/dist/particles/instancedParticle/UIInstancedParticle.js +41 -4
  153. package/dist/particles/miscellaneous/miscellaneous.d.ts +34 -0
  154. package/dist/particles/miscellaneous/miscellaneous.js +72 -0
  155. package/dist/particles/renderingModules/UIRenderingColorOverLife.d.ts +4 -0
  156. package/dist/particles/renderingModules/UIRenderingColorOverLife.js +2 -4
  157. package/dist/particles/renderingModules/UIRenderingColorOverVelocity.d.ts +4 -0
  158. package/dist/particles/renderingModules/UIRenderingColorOverVelocity.js +2 -5
  159. package/dist/particles/renderingModules/UIRenderingModule.d.ts +11 -1
  160. package/dist/particles/renderingModules/UIRenderingModule.js +4 -1
  161. package/dist/particles/renderingModules/UIRenderingTexture.d.ts +4 -0
  162. package/dist/particles/renderingModules/UIRenderingTexture.js +2 -1
  163. package/dist/particles/shaders/UIRenderingColorOverLife.d.ts +1 -2
  164. package/dist/particles/shaders/UIRenderingColorOverLife.js +5 -3
  165. package/dist/particles/shaders/UIRenderingColorOverVelocity.d.ts +1 -9
  166. package/dist/particles/shaders/UIRenderingColorOverVelocity.js +6 -13
  167. package/dist/particles/spawnModules/UISpawnModule.d.ts +16 -1
  168. package/dist/particles/spawnModules/UISpawnModule.js +3 -1
  169. package/dist/particles/spawnModules/UISpawnOffset.d.ts +7 -0
  170. package/dist/particles/spawnModules/UISpawnOffset.js +0 -2
  171. package/dist/particles/spawnModules/UISpawnRandomLifetime.d.ts +8 -1
  172. package/dist/particles/spawnModules/UISpawnRandomLifetime.js +5 -7
  173. package/dist/particles/spawnModules/UISpawnRandomRotation.d.ts +7 -0
  174. package/dist/particles/spawnModules/UISpawnRandomRotation.js +5 -5
  175. package/dist/particles/spawnModules/UISpawnRandomScale.d.ts +7 -0
  176. package/dist/particles/spawnModules/UISpawnRandomScale.js +4 -5
  177. package/dist/particles/spawnModules/UISpawnRandomTorque.d.ts +7 -0
  178. package/dist/particles/spawnModules/UISpawnRandomTorque.js +5 -5
  179. package/dist/particles/spawnModules/UISpawnRandomVelocity.d.ts +7 -0
  180. package/dist/particles/spawnModules/UISpawnRandomVelocity.js +6 -6
  181. package/dist/particles/spawnModules/UISpawnRectangle.d.ts +7 -0
  182. package/dist/particles/spawnModules/UISpawnRectangle.js +6 -6
  183. package/package.json +13 -4
  184. package/dist/core/layers/UIFullscreenLayer/UIFullscreenLayer.Internal.d.ts +0 -21
  185. package/dist/core/layers/UIFullscreenLayer/UIFullscreenLayer.d.ts +0 -63
  186. package/dist/core/layers/UIFullscreenLayer/UIFullscreenLayer.js +0 -144
package/README.md CHANGED
@@ -15,13 +15,14 @@
15
15
 
16
16
  ## Features
17
17
 
18
- * **Cassowary solver** - constraint-based layouts via `@lume/kiwi`
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
21
- * **Color adjustment** - per-element hue/saturation/lightness and additive blend mode
22
- * **Resize policies** - Cover, Fit, FixedHeight, FixedWidth, Cross strategies
23
- * **Modular particles** - separate `laymur/particles` entry point, import only if needed
24
- * **Debug overlay** - separate `laymur/debug` entry point, constraint visualization
18
+ - **Cassowary solver** - constraint-based layouts via `@lume/kiwi`
19
+ - **Orientation-aware** - define portrait and landscape rules in one layout, solver toggles automatically
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
22
+ - **Color adjustment** - per-element hue/saturation/lightness and additive blend mode
23
+ - **Resize policies** - Cover, Fit, FixedHeight, FixedWidth, Cross strategies
24
+ - **Modular particles** - separate `laymur/particles` entry point, import only if needed
25
+ - **Debug overlay** - separate `laymur/debug` entry point, constraint visualization
25
26
 
26
27
  ## Installation
27
28
 
@@ -31,10 +32,29 @@ npm install laymur
31
32
 
32
33
  Peer Dependencies:
33
34
 
34
- * `three` (>=0.157.0 <0.180.0)
35
- * `@lume/kiwi` (^0.4.4)
36
- * `ferrsign` (^0.0.4)
37
- * `fast-simplex-noise` (^4.0.0) - only required when using `laymur/particles`
35
+ - `three` (>=0.157.0 <0.180.0)
36
+ - `@lume/kiwi` (^0.4.4)
37
+ - `ferrsign` (^0.0.4)
38
+ - `fast-simplex-noise` (^4.0.0) - only required when using `laymur/particles`
39
+
40
+ ### Development checks
41
+
42
+ Laymur validates arguments (finite numbers, ranges, destroyed objects) unless
43
+ `process.env.NODE_ENV` is `"production"`. A bundler replaces that expression with a string, and
44
+ the minifier then removes the checks from the production build:
45
+
46
+ - Vite and webpack set it for you (`"production"` in production builds).
47
+ - esbuild: `--define:process.env.NODE_ENV='"production"'`.
48
+ - Rollup: `@rollup/plugin-replace` with `"process.env.NODE_ENV": JSON.stringify("production")`.
49
+
50
+ Without a bundler (an import map, a CDN), `process` does not exist: define it before importing
51
+ laymur.
52
+
53
+ ```html
54
+ <script>
55
+ globalThis.process = { env: { NODE_ENV: "development" } }; // or "production"
56
+ </script>
57
+ ```
38
58
 
39
59
  ## Visual Editor & Live Examples
40
60
 
@@ -44,36 +64,45 @@ Check out visual editor and interactive examples at:
44
64
 
45
65
  **[EXAMPLES](https://jango-git.github.io/laymur/examples/index.html)**
46
66
 
47
-
48
67
  ## Core Concepts
49
68
 
50
69
  ### 1. Layers & Elements
51
70
 
52
- `UIFullscreenLayer` manages coordinate system, canvas scaling, and input. All UI elements attach to a layer.
71
+ `UIViewportLayer` manages coordinate system, canvas scaling, and input. All UI elements attach to a layer.
53
72
 
54
73
  ```typescript
55
- import { UIFullscreenLayer, UIImage, UIMode, UIResizePolicyFixedHeight } from 'laymur';
74
+ import { UIViewportLayer, UIImage, UIMode, UIResizePolicyFixedHeight } from "laymur";
56
75
 
57
- const layer = new UIFullscreenLayer({
58
- name: "MainHUD",
76
+ const layer = new UIViewportLayer({
77
+ name: "MainHUD",
59
78
  mode: UIMode.VISIBLE,
60
- resizePolicy: new UIResizePolicyFixedHeight(1080, 1920)
79
+ resizePolicy: new UIResizePolicyFixedHeight(1080, 1920),
61
80
  });
62
81
  ```
63
82
 
83
+ The layer covers the whole window by default. For a canvas that does not fill the window (an editor preview, a page with margins), pass the area it covers; the layer then takes its size and the origin of input positions from that element:
84
+
85
+ ```typescript
86
+ import { UIElementViewport, UIViewportLayer } from "laymur";
87
+
88
+ const viewport = new UIElementViewport(renderer.domElement);
89
+ const layer = new UIViewportLayer({ viewport });
90
+ // The viewport belongs to the caller and may serve several layers: destroy it after them
91
+ ```
92
+
64
93
  ### 2. Constraint System
65
94
 
66
95
  Cassowary-based constraint solver. Supports priorities, element relationships, orientation-specific rules, and inequality relations.
67
96
 
68
97
  ```typescript
69
- import {
70
- UIHorizontalDistanceConstraint,
98
+ import {
99
+ UIHorizontalDistanceConstraint,
71
100
  UIVerticalProportionConstraint,
72
101
  UIAspectConstraint,
73
- UIOrientation,
102
+ UIOrientation,
74
103
  UIPriority,
75
- UIRelation
76
- } from 'laymur';
104
+ UIRelation,
105
+ } from "laymur";
77
106
 
78
107
  // Lock aspect ratio
79
108
  new UIAspectConstraint(element);
@@ -107,47 +136,92 @@ element.micro.scaleX = Math.sin(Date.now() * 0.001) + 1;
107
136
  element.micro.rotation += 0.01;
108
137
  ```
109
138
 
110
- ### 4. Color Adjustment
139
+ 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:
140
+
141
+ ```typescript
142
+ button.micro.affectsInput = false;
143
+ ```
144
+
145
+ ### 4. Masks
146
+
147
+ `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.
148
+
149
+ ```typescript
150
+ import { UIDummy, UIMask, UIMaskShape } from "laymur";
151
+
152
+ // Scroll view: content moves, the viewport stays
153
+ const viewport = new UIDummy(layer);
154
+ const mask = new UIMask(viewport, { radius: 24, softness: 8, padding: 10 });
155
+ for (const item of items) {
156
+ item.mask = mask;
157
+ }
158
+
159
+ // Round avatar
160
+ avatar.mask = new UIMask(avatarFrame, { shape: UIMaskShape.ELLIPSE, softness: 2 });
161
+
162
+ // Tutorial spotlight: taps inside the hole reach the button below the overlay
163
+ dimOverlay.mask = new UIMask(ctaButton, {
164
+ shape: UIMaskShape.ELLIPSE,
165
+ inverted: true,
166
+ softness: 40,
167
+ });
168
+ ```
169
+
170
+ 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`.
171
+
172
+ ### 5. Color Adjustment
111
173
 
112
174
  Every element supports per-element color tweaks that run in the shader, independent of the layout solver.
113
175
 
114
176
  ```typescript
115
- import { UIBlendMode } from 'laymur';
177
+ import { UIBlendMode } from "laymur";
116
178
 
117
- element.hue = 180; // hue shift in degrees
179
+ element.hue = 180; // hue shift in degrees
118
180
  element.saturation = 0.5; // multiplier (1 = unchanged, 0 = grayscale)
119
- element.lightness = 0.1; // offset (0 = unchanged)
181
+ element.lightness = 0.1; // offset (0 = unchanged)
120
182
 
121
183
  // Additive blending (light accumulation), only affects BLEND transparency
122
184
  element.blendMode = UIBlendMode.ADDITIVE;
123
185
  ```
124
186
 
125
- ### 5. Particle System
187
+ ### 6. Particle System
126
188
 
127
189
  Modular pipeline: Spawn -> Behavior -> Rendering.
128
190
 
129
191
  ```typescript
130
- import { UIEmitter, UISpawnRectangle, UIBehaviorDirectionalGravity, UIRenderingTexture } from 'laymur/particles';
131
-
192
+ import {
193
+ UIEmitter,
194
+ UISpawnRectangle,
195
+ UISpawnRandomLifetime,
196
+ UISpawnRandomScale,
197
+ UIBehaviorDirectionalGravity,
198
+ UIRenderingTexture,
199
+ } from "laymur/particles";
200
+
201
+ // Unset, a particle lives 1 second at scale 1 (1 px)
132
202
  const emitter = new UIEmitter(
133
203
  layer,
134
- [new UISpawnRectangle([-500, 0], [500, 0])],
204
+ [
205
+ new UISpawnRectangle([-500, 0], [500, 0]),
206
+ new UISpawnRandomLifetime([2, 3]), // seconds
207
+ new UISpawnRandomScale([24, 48], particleTexture), // px, aspect from the texture
208
+ ],
135
209
  [new UIBehaviorDirectionalGravity({ x: 0, y: 100 })],
136
210
  [new UIRenderingTexture(particleTexture)],
137
- { expectedCapacity: 1024 } // Pre-allocation hint, not a hard limit
211
+ { expectedCapacity: 1024 }, // Pre-allocation hint, not a hard limit
138
212
  );
139
213
 
140
214
  emitter.play(60); // particles/sec
141
215
  ```
142
216
 
143
- ### 6. Debug Overlay
217
+ ### 7. Debug Overlay
144
218
 
145
219
  `laymur/debug` renders visual overlays for constraints - useful during development to inspect layout relationships.
146
220
 
147
221
  `UILayerDebug` automatically tracks all constraints on a layer and creates the corresponding overlays. Individual constraint types can be toggled on/off.
148
222
 
149
223
  ```typescript
150
- import { UILayerDebug } from 'laymur/debug';
224
+ import { UILayerDebug } from "laymur/debug";
151
225
 
152
226
  const debug = new UILayerDebug(layer, {
153
227
  showAspect: true,
@@ -174,12 +248,18 @@ Most commonly used exports (not exhaustive):
174
248
 
175
249
  ### Core
176
250
 
177
- UIFullscreenLayer, UIImage, UIAnimatedImage, UIText, UINineSlice, UIProgress
251
+ UIViewportLayer, UIImage, UIAnimatedImage, UIText, UINineSlice, UIProgress, UIMask
178
252
 
179
253
  ### Constraints
180
254
 
181
255
  UIAspectConstraint, UIHorizontalDistanceConstraint, UIVerticalDistanceConstraint, UIHorizontalProportionConstraint, UIVerticalProportionConstraint, UICoverConstraintBuilder, UIFitConstraintBuilder
182
256
 
257
+ ### Extension Points
258
+
259
+ UIElement, UIArea, UIResizePolicy, UIViewport, UIProgressMaskFunction, UIMaskMaterialPatch, UIAffineMatrix3
260
+
261
+ UIRenderingModule, UISpawnModule, UIBehaviorModule (laymur/particles)
262
+
183
263
  ### Particles (laymur/particles)
184
264
 
185
265
  UIEmitter, UISpawnRectangle, UISpawnRandomLifetime, UIBehaviorDirectionalGravity, UIBehaviorVelocityDamping, UIRenderingTexture, UIRenderingColorOverLife
@@ -1,7 +1,7 @@
1
1
  import type { UILayer } from "../layers/UILayer/UILayer.js";
2
2
  import type { UIExpression } from "../miscellaneous/UIExpression.js";
3
- import { UISingleParameterConstraint } from "./UISingleParameterConstraint/UISingleParameterConstraint.js";
4
3
  import type { UISingleParameterConstraintOptions } from "./UISingleParameterConstraint/UISingleParameterConstraint.Internal.js";
4
+ import { UISingleParameterConstraint } from "./UISingleParameterConstraint/UISingleParameterConstraint.js";
5
5
  /** Constraint with custom LHS and RHS expressions */
6
6
  export declare class UICustomConstraint extends UISingleParameterConstraint {
7
7
  /** Solver constraint descriptor */
@@ -31,7 +31,7 @@ export class UIHorizontalInterpolationConstraint extends UISingleParameterConstr
31
31
  this.b = b;
32
32
  this.c = c;
33
33
  this.anchorAInternal = anchorA;
34
- this.anchorBInternal = anchorA;
34
+ this.anchorBInternal = anchorB;
35
35
  this.anchorCInternal = options.anchorC ?? DEFAULT_ANCHOR;
36
36
  this.tInternal = options.t ?? DEFAULT_T;
37
37
  this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled());
@@ -31,7 +31,7 @@ export class UIVerticalInterpolationConstraint extends UISingleParameterConstrai
31
31
  this.b = b;
32
32
  this.c = c;
33
33
  this.anchorAInternal = anchorA;
34
- this.anchorBInternal = anchorA;
34
+ this.anchorBInternal = anchorB;
35
35
  this.anchorCInternal = options.anchorC ?? DEFAULT_ANCHOR;
36
36
  this.tInternal = options.t ?? DEFAULT_T;
37
37
  this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled());
@@ -1,5 +1,4 @@
1
- import type { UIElement } from "../../elements/UIElement/UIElement.js";
2
- import type { UIPlaneElement, UIPointElement } from "../../miscellaneous/shared.js";
1
+ import type { UILayerElement, UIPlaneElement, UIPointElement } from "../../miscellaneous/shared.js";
3
2
  import { UIHeightConstraint } from "../UIHeightConstraint/UIHeightConstraint.js";
4
3
  import { UIHorizontalDistanceConstraint } from "../UIHorizontalDistanceConstraint/UIHorizontalDistanceConstraint.js";
5
4
  import { UIHorizontalInterpolationConstraint } from "../UIHorizontalInterpolationConstraint/UIHorizontalInterpolationConstraint.js";
@@ -17,7 +16,7 @@ export declare class UIConstraint2DBuilder {
17
16
  * @param options Size configuration for both axes
18
17
  * @returns Width and height constraints
19
18
  */
20
- static size(element: UIElement, options?: Partial<UIConstraintSize2DOptions>): UIConstraint2DResult<UIWidthConstraint, UIHeightConstraint>;
19
+ static size(element: UIPlaneElement & UILayerElement, options?: Partial<UIConstraintSize2DOptions>): UIConstraint2DResult<UIWidthConstraint, UIHeightConstraint>;
21
20
  /**
22
21
  * Creates horizontal and vertical distance constraints.
23
22
  * @param a First element
@@ -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,10 +1,10 @@
1
1
  import type { FerrsignView0 } from "ferrsign";
2
2
  import type { WebGLRenderer } from "three";
3
3
  import type { UILayer } from "../../layers/UILayer/UILayer.js";
4
- import { UIColor } from "../../miscellaneous/color/UIColor.js";
5
4
  import type { UIColorConfig } from "../../miscellaneous/color/UIColor.Internal.js";
6
- import { UITextureView } from "../../miscellaneous/texture/UITextureView.js";
5
+ import { UIColor } from "../../miscellaneous/color/UIColor.js";
7
6
  import type { UITextureConfig } from "../../miscellaneous/texture/UITextureView.Internal.js";
7
+ import { UITextureView } from "../../miscellaneous/texture/UITextureView.js";
8
8
  import { UIElement } from "../UIElement/UIElement.js";
9
9
  import type { UIAnimatedImageOptions } from "./UIAnimatedImage.Internal.js";
10
10
  import { UIAnimatedImageLoopMode } from "./UIAnimatedImage.Internal.js";
@@ -1,7 +1,7 @@
1
1
  import { Ferrsign0 } from "ferrsign";
2
2
  import { assertValidNumber, assertValidPositiveNumber } from "../../miscellaneous/asserts.js";
3
3
  import { UIColor } from "../../miscellaneous/color/UIColor.js";
4
- import { computeTrimmedTransformMatrix } from "../../miscellaneous/computeTransform.js";
4
+ import { computeTrimmedTransformMatrix, scaleTrim } from "../../miscellaneous/computeTransform.js";
5
5
  import { UITextureView } from "../../miscellaneous/texture/UITextureView.js";
6
6
  import source from "../../shaders/UIImage.js";
7
7
  import { UIElement } from "../UIElement/UIElement.js";
@@ -18,11 +18,16 @@ export class UIAnimatedImage extends UIElement {
18
18
  * @param options - Configuration options
19
19
  */
20
20
  constructor(layer, sequence, options = {}) {
21
+ assertNonEmptySequence(sequence, "UIAnimatedImage.constructor.sequence");
21
22
  const color = new UIColor(options.color);
22
23
  const uiTextures = sequence.map((textureConfig) => new UITextureView(textureConfig));
23
24
  const frame = uiTextures[0];
24
- options.width = options.width ?? frame.width;
25
- options.height = options.height ?? frame.height;
25
+ // A copy: the caller may pass the same options to several elements
26
+ options = {
27
+ ...options,
28
+ width: options.width ?? frame.width,
29
+ height: options.height ?? frame.height,
30
+ };
26
31
  const textureTransform = frame.calculateUVTransform();
27
32
  super(layer, source, {
28
33
  texture: frame.texture,
@@ -104,22 +109,27 @@ export class UIAnimatedImage extends UIElement {
104
109
  }
105
110
  /** Replaces animation frames. Stops playback. */
106
111
  set sequence(sequence) {
112
+ assertNonEmptySequence(sequence, "UIAnimatedImage.sequence");
107
113
  this.stop();
108
- this.unsubscribeSequenceEvents();
109
114
  const newLength = sequence.length;
110
115
  const currentLength = this.sequenceInternal.length;
116
+ // Kept subscribed while set, so that the element follows the size of the new first frame
111
117
  for (let i = 0; i < Math.min(newLength, currentLength); i++) {
112
118
  this.sequenceInternal[i].set(sequence[i]);
113
119
  }
114
120
  if (newLength < currentLength) {
121
+ for (let i = newLength; i < currentLength; i++) {
122
+ this.sequenceInternal[i].signalDimensionsChanged.off(this.onTextureDimensionsChanged);
123
+ }
115
124
  this.sequenceInternal.length = newLength;
116
125
  }
117
126
  else if (newLength > currentLength) {
118
127
  for (let i = currentLength; i < newLength; i++) {
119
- this.sequenceInternal.push(new UITextureView(sequence[i]));
128
+ const frame = new UITextureView(sequence[i]);
129
+ frame.signalDimensionsChanged.on(this.onTextureDimensionsChanged);
130
+ this.sequenceInternal.push(frame);
120
131
  }
121
132
  }
122
- this.subscribeSequenceEvents();
123
133
  }
124
134
  /** Playback speed multiplier. Can be negative for reverse playback. */
125
135
  set timeScale(value) {
@@ -229,18 +239,15 @@ export class UIAnimatedImage extends UIElement {
229
239
  if (properties) {
230
240
  this.sceneWrapper.setProperties(this.planeHandler, properties);
231
241
  }
232
- const isTransformDirty = this.currentFrameIndexDirty ||
233
- this.micro.dirty ||
234
- frame.trimDirty ||
235
- this.inputWrapper.dirty ||
236
- this.solverWrapper.dirty;
242
+ const isTransformDirty = this.currentFrameIndexDirty || this.micro.dirty || frame.trimDirty || this.placementDirty;
237
243
  if (isTransformDirty) {
238
244
  const micro = this.micro;
239
- const textureTrim = frame.trim;
245
+ const textureTrim = scaleTrim(frame.trim, this.width, this.height, frame.width, frame.height);
240
246
  this.sceneWrapper.setTransform(this.planeHandler, 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));
241
247
  this.currentFrameIndexDirty = false;
242
248
  this.micro.setDirtyFalse();
243
249
  frame.setTrimDirtyFalse();
250
+ this.setPlacementDirtyFalse();
244
251
  }
245
252
  }
246
253
  subscribeSequenceEvents() {
@@ -254,3 +261,8 @@ export class UIAnimatedImage extends UIElement {
254
261
  }
255
262
  }
256
263
  }
264
+ function assertNonEmptySequence(sequence, subject) {
265
+ if (sequence.length === 0) {
266
+ throw new Error(`${subject}: sequence must have at least one frame`);
267
+ }
268
+ }
@@ -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";
@@ -13,6 +14,16 @@ export interface UIInputEventData {
13
14
  /** Element that emitted the event */
14
15
  element: UIDummy;
15
16
  }
17
+ /** What an element knows of a pointer: kept while it is over the element or pressed on it */
18
+ export interface UIDummyPointerState {
19
+ /** Last position, for signals of a cancel, which comes with none */
20
+ x: number;
21
+ y: number;
22
+ /** Over the element as of the last event */
23
+ inside: boolean;
24
+ /** Pressed on the element and not released yet: the element holds the pointer */
25
+ pressed: boolean;
26
+ }
16
27
  /** Configuration options for UIDummy */
17
28
  export interface UIDummyOptions extends UIAnchorOptions {
18
29
  /** Width in world units */
@@ -23,6 +34,8 @@ export interface UIDummyOptions extends UIAnchorOptions {
23
34
  interactionArea: UIArea;
24
35
  /** Controls visibility and interactivity */
25
36
  mode: UIMode;
37
+ /** Mask clipping the element, see UIDummy.mask */
38
+ mask: UIMask | null;
26
39
  }
27
40
  export declare const DUMMY_DEFAULT_WIDTH = 64;
28
41
  export declare const DUMMY_DEFAULT_HEIGHT = 32;
@@ -1,7 +1,9 @@
1
1
  import type { FerrsignView1 } from "ferrsign";
2
- import { Ferrsign1 } from "ferrsign";
2
+ import { Matrix4 } from "three";
3
3
  import type { UILayer } from "../../layers/UILayer/UILayer.js";
4
4
  import type { UIArea } from "../../miscellaneous/area/UIArea.js";
5
+ import type { UIMask } from "../../miscellaneous/mask/UIMask.js";
6
+ import type { UIMicro } from "../../miscellaneous/micro/UIMicro.js";
5
7
  import type { UIPlaneElement } from "../../miscellaneous/shared.js";
6
8
  import { UIMode } from "../../miscellaneous/UIMode.js";
7
9
  import type { UIInputWrapperView } from "../../wrappers/UIInputWrapper/UIInputWrapper.Internal.js";
@@ -18,12 +20,16 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
18
20
  protected modeInternal: UIMode;
19
21
  protected readonly inputWrapper: UIInputWrapperView;
20
22
  private readonly catcherHandler;
21
- private wasPointerInside;
23
+ private readonly pointers;
24
+ private maskInternal;
22
25
  private readonly signalPointerPressedInternal;
23
26
  private readonly signalPointerMovedInternal;
24
27
  private readonly signalPointerReleasedInternal;
25
28
  private readonly signalPointerEnteredInternal;
26
29
  private readonly signalPointerLeftInternal;
30
+ private readonly signalPointerCancelledInternal;
31
+ private readonly signalPointerClickedInternal;
32
+ private readonly signalPointerDraggedInternal;
27
33
  /**
28
34
  * Creates a new UIDummy instance.
29
35
  *
@@ -50,7 +56,13 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
50
56
  * order of creation, a later one on top.
51
57
  */
52
58
  get zIndex(): number;
53
- /** Signal fired when pointer is pressed */
59
+ /** Mask clipping the element (input only, for an element that draws nothing); null for none */
60
+ get mask(): UIMask | null;
61
+ /**
62
+ * Signal fired when pointer is pressed over the element. An element that catches the press
63
+ * (any interactive mode but INTERACTIVE_TRANSPARENT) holds the pointer until it is released:
64
+ * then exactly one of `signalPointerClicked` and `signalPointerCancelled` follows.
65
+ */
54
66
  get signalPointerPressed(): FerrsignView1<UIInputEventData>;
55
67
  /** Signal fired when pointer is moved */
56
68
  get signalPointerMoved(): FerrsignView1<UIInputEventData>;
@@ -58,8 +70,21 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
58
70
  get signalPointerReleased(): FerrsignView1<UIInputEventData>;
59
71
  /** Signal fired when pointer enters element */
60
72
  get signalPointerEntered(): FerrsignView1<UIInputEventData>;
61
- /** Signal fired when pointer leaves element */
73
+ /**
74
+ * Signal fired when pointer leaves element. A released or cancelled pointer leaves too: a
75
+ * mouse still over the element enters again on its next move.
76
+ */
62
77
  get signalPointerLeft(): FerrsignView1<UIInputEventData>;
78
+ /** Signal fired when a pointer pressed on the element is released over it */
79
+ get signalPointerClicked(): FerrsignView1<UIInputEventData>;
80
+ /** Signal fired when a pointer pressed on the element moves, over the element or not */
81
+ get signalPointerDragged(): FerrsignView1<UIInputEventData>;
82
+ /**
83
+ * Signal fired when a press on the element ends without a click: released outside the
84
+ * element, cancelled by the browser (a system gesture, scrolling, a popup), or the element
85
+ * stopped taking input. Reset what was started on press. The position is the last known one.
86
+ */
87
+ get signalPointerCancelled(): FerrsignView1<UIInputEventData>;
63
88
  /** Unique depth of the element among the elements of the layer, derived from `zIndex` */
64
89
  protected get renderDepth(): number;
65
90
  /** Width in world units */
@@ -81,10 +106,54 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
81
106
  * order of creation, a later one on top.
82
107
  */
83
108
  set zIndex(value: number);
109
+ /**
110
+ * Mask clipping the element (input only, for an element that draws nothing); null for none
111
+ * @throws If the mask is destroyed or belongs to another layer
112
+ */
113
+ set mask(value: UIMask | null);
114
+ /**
115
+ * Transform of the full element rectangle as drawn: maps the unit square
116
+ * (0,0 = bottom-left, 1,1 = top-right) to layer coordinates.
117
+ * @param includeMicro Whether to apply the micro transform, if the element has one
118
+ * @param result Matrix to write into
119
+ * @param depth Translation z of the result, such as the render depth
120
+ * @returns The result matrix
121
+ */
122
+ computeVisualTransform(includeMicro: boolean, result: Matrix4, depth?: number): Matrix4;
123
+ /**
124
+ * Micro transform the element is drawn with. Elements that have one override this, so that
125
+ * input and masks follow it; see {@link UIMicro.affectsInput}.
126
+ */
127
+ protected getMicro(): UIMicro | undefined;
84
128
  protected getSolverVariables(): number[];
85
129
  protected destroyInternal(): void;
86
130
  protected readonly catchPointerDown: (x: number, y: number, identifier: number) => boolean;
87
131
  protected readonly catchPointerMove: (x: number, y: number, identifier: number) => boolean;
88
132
  protected readonly catchPointerUp: (x: number, y: number, identifier: number) => boolean;
89
- protected handleInputEvent(x: number, y: number, identifier: number, signal: Ferrsign1<UIInputEventData>): boolean;
133
+ /** Signals of a cancel carry the last known position */
134
+ protected readonly catchPointerCancel: (identifier: number) => void;
135
+ /**
136
+ * Updates what the element knows of a pointer: fires the signal of the event if the pointer
137
+ * is over the element, then entered or left if that changed.
138
+ */
139
+ private trackPointer;
140
+ /**
141
+ * Ends a pointer: a press on the element ends as a click or as cancelled, and the pointer
142
+ * leaves. A released or cancelled pointer is forgotten, so that a touch, which never comes
143
+ * back with the same identifier, does not stay over the element.
144
+ */
145
+ private endPointer;
146
+ /** Ends every pointer, for an element that stops taking input */
147
+ private dropPointers;
148
+ private forgetIfUntracked;
149
+ /** Whether the event stops at the element: catchers below do not get it */
150
+ private catches;
151
+ private emitPointer;
152
+ /**
153
+ * Whether a point in layer coordinates hits the element: it is in the visible part of the
154
+ * mask, if the mask clips input, and in the interaction area of the rectangle as drawn, when
155
+ * micro affects input.
156
+ */
157
+ private isInputPointInside;
158
+ private assertValidMask;
90
159
  }