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
@@ -0,0 +1,265 @@
1
+ import { Matrix4 } from "three";
2
+ import { assertValidNonNegativeNumber, assertValidNumber } from "../asserts.js";
3
+ import { UIInsets } from "../insets/UIInsets.js";
4
+ import { computeMaskDistance, MASK_DATA_MODE_OFFSET, MASK_DATA_ROW0_OFFSET, MASK_DATA_ROW1_OFFSET, MASK_DATA_SHAPE_OFFSET, MASK_DATA_SIZE, MASK_DEFAULT_CLIP_INPUT, MASK_DEFAULT_INVERTED, MASK_DEFAULT_RADIUS, MASK_DEFAULT_SHAPE, MASK_DEFAULT_SOFTNESS, MASK_DEFAULT_USE_MICRO, MASK_EMPTY_OFFSET, UIMaskShape, } from "./UIMask.Internal.js";
5
+ const TEMP_TRANSFORM = new Matrix4();
6
+ const TEMP_DATA = new Float32Array(MASK_DATA_SIZE);
7
+ /**
8
+ * Tells an element from a layer without importing UIDummy as a value, which would also fail
9
+ * for an element of another copy of laymur
10
+ */
11
+ function isElementSource(source) {
12
+ return "computeVisualTransform" in source;
13
+ }
14
+ /**
15
+ * Analytic mask that follows the rectangle of a source element or layer.
16
+ *
17
+ * Elements are masked by assigning the mask to their `mask` property; one mask can serve any
18
+ * number of elements of the same layer. The mask is computed in the shader, so edges can be
19
+ * soft, masked elements keep batching together and no stencil buffer is needed. With
20
+ * `clipInput` the masked part of an element stops catching input as well.
21
+ *
22
+ * Lifetime follows the rules of constraints: destroying the source destroys the mask, and a
23
+ * destroyed mask is taken off every element it masked.
24
+ */
25
+ export class UIMask {
26
+ /**
27
+ * Creates a new UIMask instance.
28
+ *
29
+ * @param source - Element or layer whose rectangle the mask follows
30
+ * @param options - Configuration options
31
+ * @throws If the source is destroyed
32
+ */
33
+ constructor(source, options = {}) {
34
+ this.source = source;
35
+ this.consumers = new Set();
36
+ this.dataInternal = new Float32Array(MASK_DATA_SIZE);
37
+ this.versionInternal = 0;
38
+ this.destroyedInternal = false;
39
+ if (source.destroyed) {
40
+ throw new Error(`UIMask.constructor.source: source is destroyed`);
41
+ }
42
+ const radius = options.radius ?? MASK_DEFAULT_RADIUS;
43
+ const softness = options.softness ?? MASK_DEFAULT_SOFTNESS;
44
+ assertValidNonNegativeNumber(radius, "UIMask.constructor.options.radius");
45
+ assertValidNonNegativeNumber(softness, "UIMask.constructor.options.softness");
46
+ this.layer = isElementSource(source) ? source.layer : source;
47
+ this.padding = new UIInsets(options.padding);
48
+ this.shapeInternal = options.shape ?? MASK_DEFAULT_SHAPE;
49
+ this.radiusInternal = radius;
50
+ this.softnessInternal = softness;
51
+ this.invertedInternal = options.inverted ?? MASK_DEFAULT_INVERTED;
52
+ this.useMicroInternal = options.useMicro ?? MASK_DEFAULT_USE_MICRO;
53
+ this.clipInputInternal = options.clipInput ?? MASK_DEFAULT_CLIP_INPUT;
54
+ this.layer.addMask(this);
55
+ }
56
+ /** Whether the mask is destroyed, by its own `destroy` or together with its source */
57
+ get destroyed() {
58
+ return this.destroyedInternal;
59
+ }
60
+ /** Shape cut out of the source rectangle */
61
+ get shape() {
62
+ return this.shapeInternal;
63
+ }
64
+ /** Corner radius of RECTANGLE in world units */
65
+ get radius() {
66
+ return this.radiusInternal;
67
+ }
68
+ /** Width of the soft edge in world units, laid inside the shape */
69
+ get softness() {
70
+ return this.softnessInternal;
71
+ }
72
+ /** Whether the mask keeps the outside of the shape instead of the inside */
73
+ get inverted() {
74
+ return this.invertedInternal;
75
+ }
76
+ /** Whether the micro transform of the source moves the mask */
77
+ get useMicro() {
78
+ return this.useMicroInternal;
79
+ }
80
+ /** Whether masked elements also stop catching input outside the visible part */
81
+ get clipInput() {
82
+ return this.clipInputInternal;
83
+ }
84
+ /** Elements masked by this mask */
85
+ get elements() {
86
+ return [...this.consumers];
87
+ }
88
+ /**
89
+ * Incremented whenever the packed data changes.
90
+ * @internal
91
+ */
92
+ get version() {
93
+ return this.versionInternal;
94
+ }
95
+ /**
96
+ * Packed mask data, see MASK_DATA_SIZE; valid after {@link resolve}.
97
+ * @internal
98
+ */
99
+ get data() {
100
+ return this.dataInternal;
101
+ }
102
+ /** Shape cut out of the source rectangle */
103
+ set shape(value) {
104
+ this.assertNotDestroyed("UIMask.shape");
105
+ this.shapeInternal = value;
106
+ }
107
+ /** Corner radius of RECTANGLE in world units */
108
+ set radius(value) {
109
+ this.assertNotDestroyed("UIMask.radius");
110
+ assertValidNonNegativeNumber(value, "UIMask.radius");
111
+ this.radiusInternal = value;
112
+ }
113
+ /** Width of the soft edge in world units, laid inside the shape */
114
+ set softness(value) {
115
+ this.assertNotDestroyed("UIMask.softness");
116
+ assertValidNonNegativeNumber(value, "UIMask.softness");
117
+ this.softnessInternal = value;
118
+ }
119
+ /** Whether the mask keeps the outside of the shape instead of the inside */
120
+ set inverted(value) {
121
+ this.assertNotDestroyed("UIMask.inverted");
122
+ this.invertedInternal = value;
123
+ }
124
+ /** Whether the micro transform of the source moves the mask */
125
+ set useMicro(value) {
126
+ this.assertNotDestroyed("UIMask.useMicro");
127
+ this.useMicroInternal = value;
128
+ }
129
+ /** Whether masked elements also stop catching input outside the visible part */
130
+ set clipInput(value) {
131
+ this.assertNotDestroyed("UIMask.clipInput");
132
+ this.clipInputInternal = value;
133
+ }
134
+ /**
135
+ * Whether a point is in the visible part of the mask; the boundary is the shape itself,
136
+ * without the soft edge.
137
+ * @param x X in layer coordinates
138
+ * @param y Y in layer coordinates
139
+ * @throws If the mask is destroyed
140
+ */
141
+ containsPoint(x, y) {
142
+ this.assertNotDestroyed("UIMask.containsPoint");
143
+ assertValidNumber(x, "UIMask.containsPoint.x");
144
+ assertValidNumber(y, "UIMask.containsPoint.y");
145
+ this.resolve();
146
+ const data = this.dataInternal;
147
+ const localX = data[MASK_DATA_ROW0_OFFSET] * x +
148
+ data[MASK_DATA_ROW0_OFFSET + 1] * y +
149
+ data[MASK_DATA_ROW0_OFFSET + 2];
150
+ const localY = data[MASK_DATA_ROW1_OFFSET] * x +
151
+ data[MASK_DATA_ROW1_OFFSET + 1] * y +
152
+ data[MASK_DATA_ROW1_OFFSET + 2];
153
+ const inside = computeMaskDistance(localX, localY, data[MASK_DATA_SHAPE_OFFSET], data[MASK_DATA_SHAPE_OFFSET + 1], data[MASK_DATA_SHAPE_OFFSET + 2], this.shapeInternal) <= 0;
154
+ return inside !== this.invertedInternal;
155
+ }
156
+ /**
157
+ * Takes the mask off every element and removes it from its layer.
158
+ * Does nothing if the mask is already destroyed.
159
+ */
160
+ destroy() {
161
+ if (this.destroyedInternal) {
162
+ return;
163
+ }
164
+ this.destroyedInternal = true;
165
+ for (const consumer of [...this.consumers]) {
166
+ consumer.releaseMask(this);
167
+ }
168
+ this.consumers.clear();
169
+ this.layer.removeMask(this);
170
+ }
171
+ /**
172
+ * Brings the packed data up to date with the source, bumping the version on a change. Cheap
173
+ * enough to be done by every masked element every frame, so it is never a frame late.
174
+ * @internal
175
+ */
176
+ resolve() {
177
+ const data = TEMP_DATA;
178
+ this.computeData(data);
179
+ for (let i = 0; i < MASK_DATA_SIZE; i++) {
180
+ if (!Object.is(this.dataInternal[i], data[i])) {
181
+ this.dataInternal.set(data);
182
+ this.versionInternal++;
183
+ return;
184
+ }
185
+ }
186
+ }
187
+ /** @internal */
188
+ attach(consumer) {
189
+ this.consumers.add(consumer);
190
+ }
191
+ /** @internal */
192
+ detach(consumer) {
193
+ this.consumers.delete(consumer);
194
+ }
195
+ computeData(data) {
196
+ const source = this.source;
197
+ const width = source.width;
198
+ const height = source.height;
199
+ data[MASK_DATA_SHAPE_OFFSET + 3] = this.softnessInternal;
200
+ data[MASK_DATA_MODE_OFFSET] =
201
+ (this.shapeInternal === UIMaskShape.ELLIPSE ? 1 : 0) + (this.invertedInternal ? 2 : 0);
202
+ // A source collapsed by the layout has no area: nothing is inside, everything is outside
203
+ if (!(width > 0 && height > 0)) {
204
+ data.fill(0, 0, MASK_DATA_SHAPE_OFFSET + 3);
205
+ data[MASK_DATA_ROW0_OFFSET + 2] = MASK_EMPTY_OFFSET;
206
+ data[MASK_DATA_ROW1_OFFSET + 2] = MASK_EMPTY_OFFSET;
207
+ return;
208
+ }
209
+ let originX;
210
+ let originY;
211
+ let axisXx;
212
+ let axisXy;
213
+ let axisYx;
214
+ let axisYy;
215
+ if (isElementSource(source)) {
216
+ const e = source.computeVisualTransform(this.useMicroInternal, TEMP_TRANSFORM).elements;
217
+ axisXx = e[0];
218
+ axisXy = e[1];
219
+ axisYx = e[4];
220
+ axisYy = e[5];
221
+ originX = e[12];
222
+ originY = e[13];
223
+ }
224
+ else {
225
+ axisXx = width;
226
+ axisXy = 0;
227
+ axisYx = 0;
228
+ axisYy = height;
229
+ originX = source.x;
230
+ originY = source.y;
231
+ }
232
+ // The padded rectangle in the unit space of the source, so that micro scale applies to it
233
+ const u0 = this.padding.left / width;
234
+ const u1 = 1 - this.padding.right / width;
235
+ const v0 = this.padding.bottom / height;
236
+ const v1 = 1 - this.padding.top / height;
237
+ const centerU = (u0 + u1) / 2;
238
+ const centerV = (v0 + v1) / 2;
239
+ const lengthX = Math.hypot(axisXx, axisXy);
240
+ const lengthY = Math.hypot(axisYx, axisYy);
241
+ const halfWidth = Math.max(0, (u1 - u0) / 2) * lengthX;
242
+ const halfHeight = Math.max(0, (v1 - v0) / 2) * lengthY;
243
+ const centerX = originX + centerU * axisXx + centerV * axisYx;
244
+ const centerY = originY + centerU * axisXy + centerV * axisYy;
245
+ // Micro only rotates and scales, so the axes stay perpendicular; a zero axis is degenerate
246
+ const unitXx = lengthX > 0 ? axisXx / lengthX : 1;
247
+ const unitXy = lengthX > 0 ? axisXy / lengthX : 0;
248
+ const unitYx = lengthY > 0 ? axisYx / lengthY : 0;
249
+ const unitYy = lengthY > 0 ? axisYy / lengthY : 1;
250
+ data[MASK_DATA_ROW0_OFFSET] = unitXx;
251
+ data[MASK_DATA_ROW0_OFFSET + 1] = unitXy;
252
+ data[MASK_DATA_ROW0_OFFSET + 2] = -(centerX * unitXx + centerY * unitXy);
253
+ data[MASK_DATA_ROW1_OFFSET] = unitYx;
254
+ data[MASK_DATA_ROW1_OFFSET + 1] = unitYy;
255
+ data[MASK_DATA_ROW1_OFFSET + 2] = -(centerX * unitYx + centerY * unitYy);
256
+ data[MASK_DATA_SHAPE_OFFSET] = halfWidth;
257
+ data[MASK_DATA_SHAPE_OFFSET + 1] = halfHeight;
258
+ data[MASK_DATA_SHAPE_OFFSET + 2] = Math.min(this.radiusInternal, halfWidth, halfHeight);
259
+ }
260
+ assertNotDestroyed(subject) {
261
+ if (this.destroyedInternal) {
262
+ throw new Error(`${subject}: mask is destroyed`);
263
+ }
264
+ }
265
+ }
@@ -0,0 +1,50 @@
1
+ import { Material } from "three";
2
+ import type { UIMask } from "./UIMask.js";
3
+ /**
4
+ * Applies a UIMask to three.js materials that laymur does not build itself, such as those of a
5
+ * Spine skeleton or a custom object placed among the planes.
6
+ *
7
+ * The patch wraps the main() functions of the shaders: the vertex shader computes the
8
+ * mask-local position from the model matrix and the position attribute, the fragment shader
9
+ * scales the output by the mask coverage (all of it for premultiplied alpha, alpha only
10
+ * otherwise; opaque materials are cut at the middle of the edge). One {@link update} per
11
+ * frame serves every material of the patch.
12
+ *
13
+ * A patched shader stays patched for the life of the material: {@link remove} only turns its
14
+ * mask off, so nothing is recompiled. Not supported: RawShaderMaterial, GLSL3 shaders, and
15
+ * GPU-side vertex transforms such as InstancedMesh, skinning or morphing, since the mask is
16
+ * evaluated at the position attribute; Spine skeletons are deformed on the CPU and work.
17
+ *
18
+ * ```ts
19
+ * const patch = new UIMaskMaterialPatch();
20
+ * patch.apply(material); // once per material, safe to repeat
21
+ * patch.update(element.mask); // every frame, before rendering
22
+ * patch.destroy(); // turns the mask off on every material
23
+ * ```
24
+ */
25
+ export declare class UIMaskMaterialPatch {
26
+ private readonly materials;
27
+ private appliedMask;
28
+ private appliedVersion;
29
+ /**
30
+ * Patches the material. Does nothing if this patch already patched it, unless its
31
+ * onBeforeCompile was replaced since, in which case the new one is wrapped as well.
32
+ * @param material Material whose shaders get the mask
33
+ * @throws If another patch owns the material, or the material is not supported
34
+ */
35
+ apply(material: Material): void;
36
+ /**
37
+ * Turns the mask off on the material and stops updating it. The shader stays patched, so
38
+ * another patch can take the material over without a recompile.
39
+ * Does nothing if this patch does not own the material.
40
+ */
41
+ remove(material: Material): void;
42
+ /**
43
+ * Writes the mask into the uniforms of every patched material; null turns masking off.
44
+ * Call it every frame before rendering: the mask follows its source.
45
+ */
46
+ update(mask: UIMask | null): void;
47
+ /** Turns the mask off on every material of the patch */
48
+ destroy(): void;
49
+ private resolveUniforms;
50
+ }
@@ -0,0 +1,233 @@
1
+ import { GLSL3, Material, RawShaderMaterial, ShaderMaterial, Vector3, Vector4 } from "three";
2
+ import maskSource from "../../shaders/UIMask.js";
3
+ import { MASK_DATA_MODE_OFFSET, MASK_DATA_ROW0_OFFSET, MASK_DATA_ROW1_OFFSET, MASK_DATA_SHAPE_OFFSET, MASK_MODE_DISABLED, } from "./UIMask.Internal.js";
4
+ /** Matches `void main()` and `void main(void)` */
5
+ const MAIN_PATTERN = /\bvoid\s+main\s*\(\s*(?:void)?\s*\)/g;
6
+ const ORIGINAL_MAIN = "void laymurMaskOriginalMain()";
7
+ const VERTEX_HEADER = `
8
+ uniform vec3 laymurMaskRow0;
9
+ uniform vec3 laymurMaskRow1;
10
+ varying vec2 laymurMaskLocal;
11
+ `;
12
+ const VERTEX_FOOTER = `
13
+ void main() {
14
+ laymurMaskOriginalMain();
15
+ vec3 laymurMaskPoint = vec3((modelMatrix * vec4(position, 1.0)).xy, 1.0);
16
+ laymurMaskLocal = vec2(
17
+ dot(laymurMaskRow0, laymurMaskPoint),
18
+ dot(laymurMaskRow1, laymurMaskPoint)
19
+ );
20
+ }
21
+ `;
22
+ const FRAGMENT_HEADER = `
23
+ uniform vec4 laymurMaskShape;
24
+ uniform float laymurMaskMode;
25
+ varying vec2 laymurMaskLocal;
26
+ ${maskSource}
27
+ `;
28
+ const FRAGMENT_FOOTER = `
29
+ void main() {
30
+ laymurMaskOriginalMain();
31
+ if (laymurMaskMode > -0.5) {
32
+ float laymurCoverage = laymurMaskCoverage(laymurMaskLocal, laymurMaskShape, laymurMaskMode);
33
+ #ifdef OPAQUE
34
+ // Without blending the edge cannot fade, so it is cut in the middle
35
+ if (laymurCoverage < 0.5) discard;
36
+ #else
37
+ if (laymurCoverage <= 0.0) discard;
38
+ #ifdef PREMULTIPLIED_ALPHA
39
+ gl_FragColor *= laymurCoverage;
40
+ #else
41
+ gl_FragColor.a *= laymurCoverage;
42
+ #endif
43
+ #endif
44
+ }
45
+ }
46
+ `;
47
+ const CACHE_KEY_SUFFIX = "|laymur-mask";
48
+ const MATERIAL_STATES = new WeakMap();
49
+ function countMains(code) {
50
+ return code.match(MAIN_PATTERN)?.length ?? 0;
51
+ }
52
+ function renameMain(code, subject) {
53
+ if (countMains(code) !== 1) {
54
+ throw new Error(`${subject}: expected exactly one main() function in the shader`);
55
+ }
56
+ return code.replace(MAIN_PATTERN, ORIGINAL_MAIN);
57
+ }
58
+ function assertPatchable(material, subject) {
59
+ if (material instanceof RawShaderMaterial) {
60
+ throw new Error(`${subject}: RawShaderMaterial has no three.js prefix to rely on`);
61
+ }
62
+ if (material instanceof ShaderMaterial) {
63
+ if (material.glslVersion === GLSL3) {
64
+ throw new Error(`${subject}: GLSL3 shaders are not supported, use the default version`);
65
+ }
66
+ if (countMains(material.vertexShader) !== 1 || countMains(material.fragmentShader) !== 1) {
67
+ throw new Error(`${subject}: expected exactly one main() function in each shader`);
68
+ }
69
+ }
70
+ }
71
+ function createUniforms() {
72
+ return {
73
+ laymurMaskRow0: { value: new Vector3() },
74
+ laymurMaskRow1: { value: new Vector3() },
75
+ laymurMaskShape: { value: new Vector4() },
76
+ laymurMaskMode: { value: MASK_MODE_DISABLED },
77
+ };
78
+ }
79
+ /**
80
+ * Wraps the current onBeforeCompile of the material.
81
+ * @returns The installed callback
82
+ */
83
+ function install(material, uniforms, baseCacheKey) {
84
+ const previousCompile = material.onBeforeCompile;
85
+ const patchedCompile = (shader, renderer) => {
86
+ previousCompile.call(material, shader, renderer);
87
+ Object.assign(shader.uniforms, uniforms);
88
+ shader.vertexShader =
89
+ VERTEX_HEADER +
90
+ renameMain(shader.vertexShader, "UIMaskMaterialPatch.vertexShader") +
91
+ VERTEX_FOOTER;
92
+ shader.fragmentShader =
93
+ FRAGMENT_HEADER +
94
+ renameMain(shader.fragmentShader, "UIMaskMaterialPatch.fragmentShader") +
95
+ FRAGMENT_FOOTER;
96
+ };
97
+ material.onBeforeCompile = patchedCompile;
98
+ // The default key is the source of onBeforeCompile, which would now be the same wrapper for
99
+ // materials patched over different callbacks; keep the key they had before
100
+ material.customProgramCacheKey = () => (baseCacheKey === Material.prototype.customProgramCacheKey
101
+ ? previousCompile.toString()
102
+ : baseCacheKey.call(material)) + CACHE_KEY_SUFFIX;
103
+ if (material instanceof ShaderMaterial) {
104
+ // fwidth on WebGL1 (three.js before r163); built-in materials fall back to world units
105
+ material.extensions.derivatives = true;
106
+ material.defines = { ...material.defines };
107
+ material.defines["LAYMUR_MASK_DERIVATIVES"] = "";
108
+ }
109
+ material.needsUpdate = true;
110
+ return patchedCompile;
111
+ }
112
+ /**
113
+ * Applies a UIMask to three.js materials that laymur does not build itself, such as those of a
114
+ * Spine skeleton or a custom object placed among the planes.
115
+ *
116
+ * The patch wraps the main() functions of the shaders: the vertex shader computes the
117
+ * mask-local position from the model matrix and the position attribute, the fragment shader
118
+ * scales the output by the mask coverage (all of it for premultiplied alpha, alpha only
119
+ * otherwise; opaque materials are cut at the middle of the edge). One {@link update} per
120
+ * frame serves every material of the patch.
121
+ *
122
+ * A patched shader stays patched for the life of the material: {@link remove} only turns its
123
+ * mask off, so nothing is recompiled. Not supported: RawShaderMaterial, GLSL3 shaders, and
124
+ * GPU-side vertex transforms such as InstancedMesh, skinning or morphing, since the mask is
125
+ * evaluated at the position attribute; Spine skeletons are deformed on the CPU and work.
126
+ *
127
+ * ```ts
128
+ * const patch = new UIMaskMaterialPatch();
129
+ * patch.apply(material); // once per material, safe to repeat
130
+ * patch.update(element.mask); // every frame, before rendering
131
+ * patch.destroy(); // turns the mask off on every material
132
+ * ```
133
+ */
134
+ export class UIMaskMaterialPatch {
135
+ constructor() {
136
+ this.materials = new Set();
137
+ this.appliedMask = null;
138
+ this.appliedVersion = -1;
139
+ }
140
+ /**
141
+ * Patches the material. Does nothing if this patch already patched it, unless its
142
+ * onBeforeCompile was replaced since, in which case the new one is wrapped as well.
143
+ * @param material Material whose shaders get the mask
144
+ * @throws If another patch owns the material, or the material is not supported
145
+ */
146
+ apply(material) {
147
+ const subject = "UIMaskMaterialPatch.apply.material";
148
+ const state = MATERIAL_STATES.get(material);
149
+ if (state === undefined) {
150
+ assertPatchable(material, subject);
151
+ const uniforms = createUniforms();
152
+ const baseCacheKey = material.customProgramCacheKey;
153
+ MATERIAL_STATES.set(material, {
154
+ owner: this,
155
+ uniforms,
156
+ patchedCompile: install(material, uniforms, baseCacheKey),
157
+ baseCacheKey,
158
+ });
159
+ }
160
+ else {
161
+ if (state.owner !== null && state.owner !== this) {
162
+ throw new Error(`${subject}: owned by another UIMaskMaterialPatch`);
163
+ }
164
+ if (material.onBeforeCompile !== state.patchedCompile) {
165
+ assertPatchable(material, subject);
166
+ state.patchedCompile = install(material, state.uniforms, state.baseCacheKey);
167
+ }
168
+ state.owner = this;
169
+ }
170
+ if (!this.materials.has(material)) {
171
+ this.materials.add(material);
172
+ // The material gets the current mask on the next update
173
+ this.appliedVersion = -1;
174
+ }
175
+ }
176
+ /**
177
+ * Turns the mask off on the material and stops updating it. The shader stays patched, so
178
+ * another patch can take the material over without a recompile.
179
+ * Does nothing if this patch does not own the material.
180
+ */
181
+ remove(material) {
182
+ const state = MATERIAL_STATES.get(material);
183
+ if (state?.owner !== this) {
184
+ return;
185
+ }
186
+ state.owner = null;
187
+ state.uniforms.laymurMaskMode.value = MASK_MODE_DISABLED;
188
+ this.materials.delete(material);
189
+ }
190
+ /**
191
+ * Writes the mask into the uniforms of every patched material; null turns masking off.
192
+ * Call it every frame before rendering: the mask follows its source.
193
+ */
194
+ update(mask) {
195
+ if (mask !== this.appliedMask) {
196
+ this.appliedMask = mask;
197
+ this.appliedVersion = -1;
198
+ }
199
+ if (mask === null || mask.destroyed) {
200
+ for (const material of this.materials) {
201
+ this.resolveUniforms(material).laymurMaskMode.value = MASK_MODE_DISABLED;
202
+ }
203
+ return;
204
+ }
205
+ mask.resolve();
206
+ if (mask.version === this.appliedVersion) {
207
+ return;
208
+ }
209
+ this.appliedVersion = mask.version;
210
+ const data = mask.data;
211
+ for (const material of this.materials) {
212
+ const uniforms = this.resolveUniforms(material);
213
+ uniforms.laymurMaskRow0.value.fromArray(data, MASK_DATA_ROW0_OFFSET);
214
+ uniforms.laymurMaskRow1.value.fromArray(data, MASK_DATA_ROW1_OFFSET);
215
+ uniforms.laymurMaskShape.value.fromArray(data, MASK_DATA_SHAPE_OFFSET);
216
+ uniforms.laymurMaskMode.value = data[MASK_DATA_MODE_OFFSET];
217
+ }
218
+ }
219
+ /** Turns the mask off on every material of the patch */
220
+ destroy() {
221
+ for (const material of [...this.materials]) {
222
+ this.remove(material);
223
+ }
224
+ this.appliedMask = null;
225
+ }
226
+ resolveUniforms(material) {
227
+ const state = MATERIAL_STATES.get(material);
228
+ if (state === undefined) {
229
+ throw new Error(`UIMaskMaterialPatch.resolveUniforms.material: material is not patched`);
230
+ }
231
+ return state.uniforms;
232
+ }
233
+ }
@@ -1,4 +1,11 @@
1
- /** Base class for progress bar fill functions */
1
+ import type { UIProperty } from "../generic-plane/shared.js";
2
+ /**
3
+ * Base class for progress bar fill functions.
4
+ *
5
+ * The GLSL source must define `float calculateMask()`, returning the fill (0..1) of the current
6
+ * fragment; it can read `p_uv`, `p_progress`, `p_textureResolution` and every property returned
7
+ * by {@link enumerateProperties} as `p_<name>`. Set `dirtyInternal` when a property changes.
8
+ */
2
9
  export declare abstract class UIProgressMaskFunction {
3
10
  /** GLSL shader source code defining fill behavior */
4
11
  readonly source: string;
@@ -6,4 +13,6 @@ export declare abstract class UIProgressMaskFunction {
6
13
  protected constructor(
7
14
  /** GLSL shader source code defining fill behavior */
8
15
  source: string);
16
+ /** Shader properties of the function, read in GLSL as `p_<name>` */
17
+ abstract enumerateProperties(): Record<string, UIProperty>;
9
18
  }
@@ -1,4 +1,10 @@
1
- /** Base class for progress bar fill functions */
1
+ /**
2
+ * Base class for progress bar fill functions.
3
+ *
4
+ * The GLSL source must define `float calculateMask()`, returning the fill (0..1) of the current
5
+ * fragment; it can read `p_uv`, `p_progress`, `p_textureResolution` and every property returned
6
+ * by {@link enumerateProperties} as `p_<name>`. Set `dirtyInternal` when a property changes.
7
+ */
2
8
  export class UIProgressMaskFunction {
3
9
  constructor(
4
10
  /** GLSL shader source code defining fill behavior */
@@ -1,3 +1,4 @@
1
+ import type { UIProperty } from "../generic-plane/shared.js";
1
2
  import { UIProgressMaskFunction } from "./UIProgressMaskFunction.js";
2
3
  /** Circular radial progress fill */
3
4
  export declare class UIProgressMaskFunctionCircular extends UIProgressMaskFunction {
@@ -18,4 +19,5 @@ export declare class UIProgressMaskFunctionCircular extends UIProgressMaskFuncti
18
19
  set startAngle(value: number);
19
20
  /** Whether fill is counter-clockwise */
20
21
  set inverseDirection(value: boolean);
22
+ enumerateProperties(): Record<string, UIProperty>;
21
23
  }
@@ -38,7 +38,6 @@ export class UIProgressMaskFunctionCircular extends UIProgressMaskFunction {
38
38
  this.dirtyInternal = true;
39
39
  }
40
40
  }
41
- /** @internal */
42
41
  enumerateProperties() {
43
42
  return {
44
43
  direction: this.inverseDirectionInternal ? -1 : 1,
@@ -1,4 +1,5 @@
1
1
  import { Vector2 } from "three";
2
+ import type { UIProperty } from "../generic-plane/shared.js";
2
3
  import type { Vector2Like } from "../math.js";
3
4
  import { UIProgressMaskFunction } from "./UIProgressMaskFunction.js";
4
5
  /** Linear directional progress fill */
@@ -12,5 +13,6 @@ export declare class UIProgressMaskFunctionDirectional extends UIProgressMaskFun
12
13
  * @param direction - Fill direction vector. Automatically normalized.
13
14
  */
14
15
  constructor(direction?: Vector2Like);
16
+ enumerateProperties(): Record<string, UIProperty>;
15
17
  private ensureDirectionNormalized;
16
18
  }
@@ -28,7 +28,6 @@ export class UIProgressMaskFunctionDirectional extends UIProgressMaskFunction {
28
28
  this.cachedDirection.copy(this.direction);
29
29
  super.setDirtyFalse();
30
30
  }
31
- /** @internal */
32
31
  enumerateProperties() {
33
32
  this.ensureDirectionNormalized();
34
33
  return { direction: this.direction };
@@ -23,9 +23,12 @@ export interface UIMicroConfig {
23
23
  rotation: number;
24
24
  /** Which transforms apply relative to anchor */
25
25
  anchorMode: UIMicroAnchorMode;
26
+ /** Whether input follows the transformed element instead of its layout rectangle */
27
+ affectsInput: boolean;
26
28
  }
27
29
  export declare const MICRO_DEFAULT_POSITION = 0;
28
30
  export declare const MICRO_DEFAULT_ANCHOR = 0.5;
29
31
  export declare const MICRO_DEFAULT_SCALE = 1;
30
32
  export declare const MICRO_DEFAULT_ROTATION = 0;
31
33
  export declare const MICRO_DEFAULT_ANCHOR_MODE = UIMicroAnchorMode.ROTATION_SCALE;
34
+ export declare const MICRO_DEFAULT_AFFECTS_INPUT = true;
@@ -11,3 +11,4 @@ export const MICRO_DEFAULT_ANCHOR = 0.5;
11
11
  export const MICRO_DEFAULT_SCALE = 1;
12
12
  export const MICRO_DEFAULT_ROTATION = 0;
13
13
  export const MICRO_DEFAULT_ANCHOR_MODE = UIMicroAnchorMode.ROTATION_SCALE;
14
+ export const MICRO_DEFAULT_AFFECTS_INPUT = true;