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
@@ -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;
@@ -1,5 +1,11 @@
1
1
  import type { UIMicroAnchorMode, UIMicroConfig } from "./UIMicro.Internal.js";
2
- /** Transforms that don't affect constraints */
2
+ /**
3
+ * Transforms that don't affect constraints.
4
+ *
5
+ * Input follows them by default: a moved, rotated or scaled element is hit where it is drawn.
6
+ * Turn {@link affectsInput} off for effects such as shrinking a button while it is pressed,
7
+ * where the hit area should stay put under the finger.
8
+ */
3
9
  export declare class UIMicro {
4
10
  private xInternal;
5
11
  private yInternal;
@@ -9,6 +15,7 @@ export declare class UIMicro {
9
15
  private scaleYInternal;
10
16
  private rotationInternal;
11
17
  private anchorModeInternal;
18
+ private affectsInputInternal;
12
19
  private dirtyInternal;
13
20
  /**
14
21
  * Creates UIMicro instance.
@@ -34,6 +41,11 @@ export declare class UIMicro {
34
41
  get anchorMode(): UIMicroAnchorMode;
35
42
  /** Rotation in radians */
36
43
  get rotation(): number;
44
+ /**
45
+ * Whether input follows the transformed element instead of its layout rectangle. Not a
46
+ * transform itself, so `reset` and `copy` leave it as is.
47
+ */
48
+ get affectsInput(): boolean;
37
49
  /** X offset in world units */
38
50
  set x(value: number);
39
51
  /** Y offset in world units */
@@ -52,6 +64,11 @@ export declare class UIMicro {
52
64
  set rotation(value: number);
53
65
  /** Which transforms apply relative to anchor */
54
66
  set anchorMode(value: UIMicroAnchorMode);
67
+ /**
68
+ * Whether input follows the transformed element instead of its layout rectangle. Not a
69
+ * transform itself, so `reset` and `copy` leave it as is.
70
+ */
71
+ set affectsInput(value: boolean);
55
72
  /** Sets the same scale for X and Y */
56
73
  setUnifiedScale(scale: number): void;
57
74
  /** Sets the same anchor for X and Y */
@@ -1,7 +1,13 @@
1
1
  import { MathUtils } from "three";
2
2
  import { assertValidNumber } from "../asserts.js";
3
- import { MICRO_DEFAULT_ANCHOR, MICRO_DEFAULT_ANCHOR_MODE, MICRO_DEFAULT_POSITION, MICRO_DEFAULT_ROTATION, MICRO_DEFAULT_SCALE, } from "./UIMicro.Internal.js";
4
- /** Transforms that don't affect constraints */
3
+ import { MICRO_DEFAULT_AFFECTS_INPUT, MICRO_DEFAULT_ANCHOR, MICRO_DEFAULT_ANCHOR_MODE, MICRO_DEFAULT_POSITION, MICRO_DEFAULT_ROTATION, MICRO_DEFAULT_SCALE, } from "./UIMicro.Internal.js";
4
+ /**
5
+ * Transforms that don't affect constraints.
6
+ *
7
+ * Input follows them by default: a moved, rotated or scaled element is hit where it is drawn.
8
+ * Turn {@link affectsInput} off for effects such as shrinking a button while it is pressed,
9
+ * where the hit area should stay put under the finger.
10
+ */
5
11
  export class UIMicro {
6
12
  /**
7
13
  * Creates UIMicro instance.
@@ -18,6 +24,7 @@ export class UIMicro {
18
24
  this.scaleYInternal = config?.scaleY ?? MICRO_DEFAULT_SCALE;
19
25
  this.rotationInternal = config?.rotation ?? MICRO_DEFAULT_ROTATION;
20
26
  this.anchorModeInternal = config?.anchorMode ?? MICRO_DEFAULT_ANCHOR_MODE;
27
+ this.affectsInputInternal = config?.affectsInput ?? MICRO_DEFAULT_AFFECTS_INPUT;
21
28
  }
22
29
  /** X offset in world units */
23
30
  get x() {
@@ -55,6 +62,13 @@ export class UIMicro {
55
62
  get rotation() {
56
63
  return this.rotationInternal;
57
64
  }
65
+ /**
66
+ * Whether input follows the transformed element instead of its layout rectangle. Not a
67
+ * transform itself, so `reset` and `copy` leave it as is.
68
+ */
69
+ get affectsInput() {
70
+ return this.affectsInputInternal;
71
+ }
58
72
  /** @internal */
59
73
  get dirty() {
60
74
  return this.dirtyInternal;
@@ -131,6 +145,13 @@ export class UIMicro {
131
145
  this.dirtyInternal = true;
132
146
  }
133
147
  }
148
+ /**
149
+ * Whether input follows the transformed element instead of its layout rectangle. Not a
150
+ * transform itself, so `reset` and `copy` leave it as is.
151
+ */
152
+ set affectsInput(value) {
153
+ this.affectsInputInternal = value;
154
+ }
134
155
  /** Sets the same scale for X and Y */
135
156
  setUnifiedScale(scale) {
136
157
  assertValidNumber(scale, "UIMicro.setUnifiedScale.scale");
@@ -1,3 +1,21 @@
1
- /** Base class for viewport resize policies */
1
+ /**
2
+ * Base class for viewport resize policies. Subclass it for a custom scaling rule and pass it to
3
+ * `UIViewportLayer`.
4
+ */
2
5
  export declare abstract class UIResizePolicy {
6
+ private versionInternal;
7
+ /**
8
+ * Bumped when a parameter of the policy changes; every layer using the policy resizes on its
9
+ * next render. One policy may serve several layers.
10
+ */
11
+ get version(): number;
12
+ /** Call it when a parameter of the policy changes */
13
+ protected markChanged(): void;
14
+ /**
15
+ * Scale from screen pixels to world units: the layer is the viewport size times this value.
16
+ * @param width Viewport width in pixels
17
+ * @param height Viewport height in pixels
18
+ * @returns World units per pixel
19
+ */
20
+ abstract calculateScale(width: number, height: number): number;
3
21
  }
@@ -1,7 +1,20 @@
1
- /** Base class for viewport resize policies */
1
+ /**
2
+ * Base class for viewport resize policies. Subclass it for a custom scaling rule and pass it to
3
+ * `UIViewportLayer`.
4
+ */
2
5
  export class UIResizePolicy {
3
6
  constructor() {
4
- /** @internal */
5
- this.dirty = false;
7
+ this.versionInternal = 0;
8
+ }
9
+ /**
10
+ * Bumped when a parameter of the policy changes; every layer using the policy resizes on its
11
+ * next render. One policy may serve several layers.
12
+ */
13
+ get version() {
14
+ return this.versionInternal;
15
+ }
16
+ /** Call it when a parameter of the policy changes */
17
+ markChanged() {
18
+ this.versionInternal++;
6
19
  }
7
20
  }
@@ -28,7 +28,7 @@ export class UIResizePolicyCover extends UIResizePolicy {
28
28
  assertValidPositiveNumber(value, "UIResizePolicyCover.rectWidth");
29
29
  if (value !== this.rectWidthInternal) {
30
30
  this.rectWidthInternal = value;
31
- this.dirty = true;
31
+ this.markChanged();
32
32
  }
33
33
  }
34
34
  /** Target rect height */
@@ -36,7 +36,7 @@ export class UIResizePolicyCover extends UIResizePolicy {
36
36
  assertValidPositiveNumber(value, "UIResizePolicyCover.rectHeight");
37
37
  if (value !== this.rectHeightInternal) {
38
38
  this.rectHeightInternal = value;
39
- this.dirty = true;
39
+ this.markChanged();
40
40
  }
41
41
  }
42
42
  calculateScale(width, height) {
@@ -28,7 +28,7 @@ export class UIResizePolicyCross extends UIResizePolicy {
28
28
  assertValidPositiveNumber(value, "UIResizePolicyCross.fixedWidthLandscape");
29
29
  if (value !== this.fixedWidthLandscapeInternal) {
30
30
  this.fixedWidthLandscapeInternal = value;
31
- this.dirty = true;
31
+ this.markChanged();
32
32
  }
33
33
  }
34
34
  /** Target height when portrait */
@@ -36,7 +36,7 @@ export class UIResizePolicyCross extends UIResizePolicy {
36
36
  assertValidPositiveNumber(value, "UIResizePolicyCross.fixedHeightPortrait");
37
37
  if (value !== this.fixedHeightPortraitInternal) {
38
38
  this.fixedHeightPortraitInternal = value;
39
- this.dirty = true;
39
+ this.markChanged();
40
40
  }
41
41
  }
42
42
  calculateScale(width, height) {
@@ -28,7 +28,7 @@ export class UIResizePolicyCrossInverted extends UIResizePolicy {
28
28
  assertValidPositiveNumber(value, "UIResizePolicyCrossInverted.fixedHeightLandscape");
29
29
  if (value !== this.fixedHeightLandscapeInternal) {
30
30
  this.fixedHeightLandscapeInternal = value;
31
- this.dirty = true;
31
+ this.markChanged();
32
32
  }
33
33
  }
34
34
  /** Target width when portrait */
@@ -36,7 +36,7 @@ export class UIResizePolicyCrossInverted extends UIResizePolicy {
36
36
  assertValidPositiveNumber(value, "UIResizePolicyCrossInverted.fixedWidthPortrait");
37
37
  if (value !== this.fixedWidthPortraitInternal) {
38
38
  this.fixedWidthPortraitInternal = value;
39
- this.dirty = true;
39
+ this.markChanged();
40
40
  }
41
41
  }
42
42
  calculateScale(width, height) {
@@ -28,7 +28,7 @@ export class UIResizePolicyFit extends UIResizePolicy {
28
28
  assertValidPositiveNumber(value, "UIResizePolicyFit.rectWidth");
29
29
  if (value !== this.rectWidthInternal) {
30
30
  this.rectWidthInternal = value;
31
- this.dirty = true;
31
+ this.markChanged();
32
32
  }
33
33
  }
34
34
  /** Target rect height */
@@ -36,7 +36,7 @@ export class UIResizePolicyFit extends UIResizePolicy {
36
36
  assertValidPositiveNumber(value, "UIResizePolicyFit.rectHeight");
37
37
  if (value !== this.rectHeightInternal) {
38
38
  this.rectHeightInternal = value;
39
- this.dirty = true;
39
+ this.markChanged();
40
40
  }
41
41
  }
42
42
  calculateScale(width, height) {
@@ -28,7 +28,7 @@ export class UIResizePolicyFixedHeight extends UIResizePolicy {
28
28
  assertValidPositiveNumber(value, "UIResizePolicyFixedHeight.fixedHeightLandscape");
29
29
  if (value !== this.fixedHeightLandscapeInternal) {
30
30
  this.fixedHeightLandscapeInternal = value;
31
- this.dirty = true;
31
+ this.markChanged();
32
32
  }
33
33
  }
34
34
  /** Target height when portrait */
@@ -36,7 +36,7 @@ export class UIResizePolicyFixedHeight extends UIResizePolicy {
36
36
  assertValidPositiveNumber(value, "UIResizePolicyFixedHeight.fixedHeightPortrait");
37
37
  if (value !== this.fixedHeightPortraitInternal) {
38
38
  this.fixedHeightPortraitInternal = value;
39
- this.dirty = true;
39
+ this.markChanged();
40
40
  }
41
41
  }
42
42
  calculateScale(width, height) {
@@ -28,7 +28,7 @@ export class UIResizePolicyFixedWidth extends UIResizePolicy {
28
28
  assertValidPositiveNumber(value, "UIResizePolicyFixedWidth.fixedWidthLandscape");
29
29
  if (value !== this.fixedWidthLandscapeInternal) {
30
30
  this.fixedWidthLandscapeInternal = value;
31
- this.dirty = true;
31
+ this.markChanged();
32
32
  }
33
33
  }
34
34
  /** Target width when portrait */
@@ -36,7 +36,7 @@ export class UIResizePolicyFixedWidth extends UIResizePolicy {
36
36
  assertValidPositiveNumber(value, "UIResizePolicyFixedWidth.fixedWidthPortrait");
37
37
  if (value !== this.fixedWidthPortraitInternal) {
38
38
  this.fixedWidthPortraitInternal = value;
39
- this.dirty = true;
39
+ this.markChanged();
40
40
  }
41
41
  }
42
42
  calculateScale(width, height) {
@@ -148,7 +148,7 @@ export class UITextStyle {
148
148
  }
149
149
  set shadowOffsetX(value) {
150
150
  if (value !== undefined) {
151
- assertValidNonNegativeNumber(value, "UITextStyle.shadowOffsetX");
151
+ assertValidNumber(value, "UITextStyle.shadowOffsetX");
152
152
  }
153
153
  if (value !== this.shadowOffsetXInternal) {
154
154
  this.shadowOffsetXInternal = value;
@@ -157,7 +157,7 @@ export class UITextStyle {
157
157
  }
158
158
  set shadowOffsetY(value) {
159
159
  if (value !== undefined) {
160
- assertValidNonNegativeNumber(value, "UITextStyle.shadowOffsetY");
160
+ assertValidNumber(value, "UITextStyle.shadowOffsetY");
161
161
  }
162
162
  if (value !== this.shadowOffsetYInternal) {
163
163
  this.shadowOffsetYInternal = value;