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
@@ -1,8 +1,10 @@
1
1
  import { DoubleSide, Float32BufferAttribute, InstancedBufferAttribute, InstancedBufferGeometry, Matrix3, Matrix4, ShaderMaterial, Uint16BufferAttribute, Vector2, Vector3, Vector4, } from "three";
2
+ import maskSource from "../../../shaders/UIMask.js";
2
3
  import { UIColor } from "../../color/UIColor.js";
3
4
  import { UITransparencyMode } from "../../UITransparencyMode.js";
4
5
  import { buildGenericPlaneFragmentShader, resolveGLSLTypeInfo } from "../shared.js";
5
- import { buildPackedAttributeDeclarations, buildPackedFieldSpec, buildPackedLayout, resolvePackedField, } from "./UIGenericInstancedPlane.Layout.js";
6
+ import { isIdentifierReferenced, packVaryings } from "../varyingPacking.js";
7
+ import { buildPackedAttributeDeclarations, buildPackedFieldComponents, buildPackedFieldSpec, buildPackedLayout, resolvePackedField, } from "./UIGenericInstancedPlane.Layout.js";
6
8
  export const INSTANCED_PLANE_GEOMETRY = (() => {
7
9
  const geometry = new InstancedBufferGeometry();
8
10
  const indices = new Uint16Array([0, 2, 1, 2, 3, 1]);
@@ -16,8 +18,21 @@ export const INSTANCED_PLANE_GEOMETRY = (() => {
16
18
  export const CAPACITY_STEP = 4;
17
19
  export const INITIAL_CAPACITY = 1;
18
20
  const TEMP_COLOR_VECTOR = new Vector4();
19
- export function writePropertyToArray(value, array, offset) {
20
- if (value instanceof UIColor) {
21
+ /**
22
+ * Flattens a property value into the array.
23
+ * @param affine Write a Matrix3 as a 2D affine transform: its three columns without the bottom row
24
+ */
25
+ export function writePropertyToArray(value, array, offset, affine = false) {
26
+ if (affine && value instanceof Matrix3) {
27
+ const elements = value.elements;
28
+ array[offset] = elements[0];
29
+ array[offset + 1] = elements[1];
30
+ array[offset + 2] = elements[3];
31
+ array[offset + 3] = elements[4];
32
+ array[offset + 4] = elements[6];
33
+ array[offset + 5] = elements[7];
34
+ }
35
+ else if (value instanceof UIColor) {
21
36
  value.toGLSLColor(TEMP_COLOR_VECTOR);
22
37
  array[offset] = TEMP_COLOR_VECTOR.x;
23
38
  array[offset + 1] = TEMP_COLOR_VECTOR.y;
@@ -53,11 +68,23 @@ export const BUILTIN_TRANSFORM = "instanceTransform";
53
68
  export const BUILTIN_VISIBILITY = "instanceVisibility";
54
69
  export const BUILTIN_BLEND = "instanceBlend";
55
70
  export const BUILTIN_HSL = "instanceHSL";
71
+ /** Rows of the layer -> mask-local map, see MASK_DATA_SIZE; present on masked planes only */
72
+ export const BUILTIN_MASK_ROW0 = "instanceMaskRow0";
73
+ export const BUILTIN_MASK_ROW1 = "instanceMaskRow1";
74
+ /** Half width, half height, corner radius and softness of the mask */
75
+ export const BUILTIN_MASK_SHAPE = "instanceMaskShape";
76
+ /** Mask shape + 2 when inverted */
77
+ export const BUILTIN_MASK_MODE = "instanceMaskMode";
56
78
  /**
57
79
  * Builtin fields only the vertex shader reads. Every other field, builtin blend and HSL included,
58
80
  * is passed on to the fragment shader as a p_* varying.
59
81
  */
60
- const BUILTIN_VERTEX_ONLY = [BUILTIN_TRANSFORM, BUILTIN_VISIBILITY];
82
+ const BUILTIN_VERTEX_ONLY = [
83
+ BUILTIN_TRANSFORM,
84
+ BUILTIN_VISIBILITY,
85
+ BUILTIN_MASK_ROW0,
86
+ BUILTIN_MASK_ROW1,
87
+ ];
61
88
  /**
62
89
  * The transform is a Matrix4, but the plane is a unit quad at z = 0 and every element transform
63
90
  * is affine: the z basis column only ever multiplies 0 and the bottom row is always (0, 0, 0, 1).
@@ -75,13 +102,16 @@ const BUILTIN_TRANSFORM_SPEC = {
75
102
  { sourceOffset: 12, size: 3 },
76
103
  ],
77
104
  };
78
- export function buildPlaneLayout(varyingProperties) {
105
+ export function buildPlaneLayout(varyingProperties, masked) {
79
106
  const specs = [
80
107
  BUILTIN_TRANSFORM_SPEC,
81
108
  buildPackedFieldSpec(BUILTIN_VISIBILITY, resolveGLSLTypeInfo("number")),
82
109
  buildPackedFieldSpec(BUILTIN_BLEND, resolveGLSLTypeInfo("number")),
83
110
  buildPackedFieldSpec(BUILTIN_HSL, resolveGLSLTypeInfo("Vector3")),
84
111
  ];
112
+ if (masked) {
113
+ specs.push(buildPackedFieldSpec(BUILTIN_MASK_ROW0, resolveGLSLTypeInfo("Vector3")), buildPackedFieldSpec(BUILTIN_MASK_ROW1, resolveGLSLTypeInfo("Vector3")), buildPackedFieldSpec(BUILTIN_MASK_SHAPE, resolveGLSLTypeInfo("Vector4")), buildPackedFieldSpec(BUILTIN_MASK_MODE, resolveGLSLTypeInfo("number")));
114
+ }
85
115
  for (const name in varyingProperties) {
86
116
  specs.push(buildPackedFieldSpec(name, varyingProperties[name].glslTypeInfo));
87
117
  }
@@ -90,11 +120,9 @@ export function buildPlaneLayout(varyingProperties) {
90
120
  export function buildPackedAttribute(itemSize, capacity) {
91
121
  return new InstancedBufferAttribute(new Float32Array(capacity * itemSize), itemSize);
92
122
  }
93
- export function buildMaterial(source, uniformProperties, layout, transparency) {
123
+ export function buildMaterial(source, uniformProperties, layout, transparency, masked) {
94
124
  const uniforms = {};
95
125
  const uniformDeclarations = [];
96
- const varyingDeclarations = [];
97
- const vertexAssignments = [];
98
126
  for (const name in uniformProperties) {
99
127
  const { value, glslTypeInfo } = uniformProperties[name];
100
128
  uniforms[`p_${name}`] = {
@@ -102,26 +130,59 @@ export function buildMaterial(source, uniformProperties, layout, transparency) {
102
130
  };
103
131
  uniformDeclarations.push(`uniform ${glslTypeInfo.glslTypeName} p_${name};`);
104
132
  }
133
+ // Every value the fragment shader may read, as p_* fields
134
+ const candidates = [
135
+ { name: "p_uv", glslTypeName: "vec2", components: ["uv.x", "uv.y"] },
136
+ ];
105
137
  for (const [name, field] of layout.fields) {
106
- if (BUILTIN_VERTEX_ONLY.includes(name)) {
107
- continue;
138
+ if (!BUILTIN_VERTEX_ONLY.includes(name)) {
139
+ candidates.push({
140
+ name: `p_${name}`,
141
+ glslTypeName: field.glslTypeName,
142
+ components: buildPackedFieldComponents(layout, field),
143
+ affine: field.affine,
144
+ });
108
145
  }
109
- varyingDeclarations.push(`varying ${field.glslTypeName} p_${name};`);
110
- vertexAssignments.push(`p_${name} = ${field.expression};`);
111
146
  }
112
147
  const visibility = resolvePackedField(layout, BUILTIN_VISIBILITY).expression;
113
148
  const transform = resolvePackedField(layout, BUILTIN_TRANSFORM).expression;
149
+ let maskVertex = "";
150
+ if (masked) {
151
+ const row0 = resolvePackedField(layout, BUILTIN_MASK_ROW0).expression;
152
+ const row1 = resolvePackedField(layout, BUILTIN_MASK_ROW1).expression;
153
+ candidates.push({
154
+ name: "p_instanceMaskLocal",
155
+ glslTypeName: "vec2",
156
+ components: ["maskLocal.x", "maskLocal.y"],
157
+ });
158
+ // worldPosition.z carries the zIndex, the mask map only takes the plane position
159
+ maskVertex = `
160
+ vec3 maskPoint = vec3(worldPosition.xy, 1.0);
161
+ vec2 maskLocal = vec2(dot(${row0}, maskPoint), dot(${row1}, maskPoint));
162
+ `;
163
+ }
164
+ const alphaTestValue = 0.0075;
165
+ const premultipliedAlpha = transparency === UITransparencyMode.BLEND;
166
+ const maskFragment = masked ? maskSource : undefined;
167
+ // Only fields the fragment shader reads take varyings: the blend factor, for one, is read by
168
+ // premultiplied shaders only. The shader without fields tells which ones it reads.
169
+ const unpackedFragment = buildGenericPlaneFragmentShader(uniformDeclarations, [], [], source, alphaTestValue, premultipliedAlpha, maskFragment);
170
+ const fields = candidates.filter(({ name }) => isIdentifierReferenced(unpackedFragment, name));
171
+ const packed = packVaryings(fields);
172
+ const fieldDeclarations = [...packed.declarations];
173
+ const fieldAssignments = [];
174
+ for (const { name, glslTypeName } of fields) {
175
+ fieldDeclarations.push(`${glslTypeName} ${name};`);
176
+ fieldAssignments.push(`${name} = ${packed.fragmentExpressions.get(name) ?? ""};`);
177
+ }
114
178
  const vertexShader = `
115
179
  ${buildPackedAttributeDeclarations(layout).join("\n")}
116
180
 
117
181
  // Uniforms
118
182
  ${uniformDeclarations.join("\n")}
119
183
 
120
- // Builtin varyings
121
- varying vec3 p_position;
122
- varying vec2 p_uv;
123
-
124
- ${varyingDeclarations.join("\n")}
184
+ // Packed varyings
185
+ ${packed.declarations.join("\n")}
125
186
 
126
187
  void main() {
127
188
  if (${visibility} < 0.5) {
@@ -129,19 +190,15 @@ export function buildMaterial(source, uniformProperties, layout, transparency) {
129
190
  return;
130
191
  }
131
192
 
132
- ${vertexAssignments.join("\n")}
133
-
134
- p_position = position;
135
- p_uv = uv;
136
-
137
193
  vec3 worldPosition = ${transform} * vec3(position.xy, 1.0);
138
194
  gl_Position = projectionMatrix * vec4(worldPosition, 1.0);
195
+ ${maskVertex}
196
+
197
+ ${packed.vertexAssignments.join("\n")}
139
198
  }
140
199
  `;
141
- const alphaTestValue = 0.0075;
142
- const premultipliedAlpha = transparency === UITransparencyMode.BLEND;
143
- const fragmentShader = buildGenericPlaneFragmentShader(uniformDeclarations, varyingDeclarations, source, alphaTestValue, premultipliedAlpha);
144
- return new ShaderMaterial({
200
+ const fragmentShader = buildGenericPlaneFragmentShader(uniformDeclarations, fieldDeclarations, fieldAssignments, source, alphaTestValue, premultipliedAlpha, maskFragment);
201
+ const material = new ShaderMaterial({
145
202
  uniforms,
146
203
  vertexShader,
147
204
  fragmentShader,
@@ -154,6 +211,11 @@ export function buildMaterial(source, uniformProperties, layout, transparency) {
154
211
  forceSinglePass: true,
155
212
  premultipliedAlpha,
156
213
  });
214
+ if (masked) {
215
+ // fwidth on WebGL1 (three.js before r163); WebGL2 has derivatives built in
216
+ material.extensions.derivatives = true;
217
+ }
218
+ return { material, varyingRowCount: packed.rowCount };
157
219
  }
158
220
  /**
159
221
  * Shift buffer region within the same array.
@@ -13,6 +13,8 @@ export interface PackedFieldSpec {
13
13
  glslTypeName: string;
14
14
  flatSize: number;
15
15
  columns: readonly PackedColumnSpec[];
16
+ /** A mat3 stored as three columns of two, see GLTypeInfo.affine */
17
+ affine?: boolean;
16
18
  }
17
19
  /**
18
20
  * A column placed into the packed attribute attributeIndex, starting at its component
@@ -30,6 +32,8 @@ export interface PackedField {
30
32
  glslTypeName: string;
31
33
  columns: readonly PackedColumn[];
32
34
  expression: string;
35
+ /** A mat3 stored as three columns of two, see GLTypeInfo.affine */
36
+ affine: boolean;
33
37
  }
34
38
  /**
35
39
  * attributeSizes holds the item size (1..4) of each packed attribute. Two layouts with an equal
@@ -49,4 +53,9 @@ export declare function buildPackedFieldSpec(name: string, glslTypeInfo: GLTypeI
49
53
  */
50
54
  export declare function buildPackedLayout(specs: readonly PackedFieldSpec[]): PackedLayout;
51
55
  export declare function resolvePackedField(layout: PackedLayout, name: string): PackedField;
56
+ /**
57
+ * Vertex shader expressions of the scalar components of a packed field, in the order the GLSL
58
+ * constructor of its type takes them; used to pass the field on through packed varyings.
59
+ */
60
+ export declare function buildPackedFieldComponents(layout: PackedLayout, field: PackedField): string[];
52
61
  export declare function buildPackedAttributeDeclarations(layout: PackedLayout): string[];
@@ -19,7 +19,7 @@ export function packedAttributeName(attributeIndex) {
19
19
  return `a_packed${attributeIndex}`;
20
20
  }
21
21
  export function buildPackedFieldSpec(name, glslTypeInfo) {
22
- const { glslTypeName, bufferSize, columnCount, instantiable } = glslTypeInfo;
22
+ const { glslTypeName, bufferSize, columnCount, instantiable, affine } = glslTypeInfo;
23
23
  if (!instantiable) {
24
24
  throw new Error(`buildPackedFieldSpec.glslTypeInfo: "${name}" (${glslTypeName}) is not instantiable`);
25
25
  }
@@ -28,7 +28,7 @@ export function buildPackedFieldSpec(name, glslTypeInfo) {
28
28
  for (let i = 0; i < columnCount; i++) {
29
29
  columns.push({ sourceOffset: i * columnSize, size: columnSize });
30
30
  }
31
- return { name, glslTypeName, flatSize: bufferSize, columns };
31
+ return { name, glslTypeName, flatSize: bufferSize, columns, affine: affine === true };
32
32
  }
33
33
  function compareNames(a, b) {
34
34
  return a < b ? -1 : a > b ? 1 : 0;
@@ -89,10 +89,17 @@ export function buildPackedLayout(specs) {
89
89
  ? attributeName
90
90
  : `${attributeName}.${SWIZZLE_COMPONENTS.slice(componentOffset, componentOffset + size)}`;
91
91
  });
92
- const expression = columnExpressions.length === 1
93
- ? columnExpressions[0]
94
- : `${spec.glslTypeName}(${columnExpressions.join(", ")})`;
95
- fields.set(spec.name, { glslTypeName: spec.glslTypeName, columns, expression });
92
+ const expression = spec.affine === true
93
+ ? `mat3(vec3(${columnExpressions[0]}, 0.0), vec3(${columnExpressions[1]}, 0.0), vec3(${columnExpressions[2]}, 1.0))`
94
+ : columnExpressions.length === 1
95
+ ? columnExpressions[0]
96
+ : `${spec.glslTypeName}(${columnExpressions.join(", ")})`;
97
+ fields.set(spec.name, {
98
+ glslTypeName: spec.glslTypeName,
99
+ columns,
100
+ expression,
101
+ affine: spec.affine === true,
102
+ });
96
103
  const sourceOffsets = columns.map(({ sourceOffset }) => sourceOffset).join(",");
97
104
  signatureParts.push(`${spec.name}:${spec.glslTypeName}[${sourceOffsets}]=${expression}`);
98
105
  }
@@ -105,6 +112,22 @@ export function resolvePackedField(layout, name) {
105
112
  }
106
113
  return field;
107
114
  }
115
+ /**
116
+ * Vertex shader expressions of the scalar components of a packed field, in the order the GLSL
117
+ * constructor of its type takes them; used to pass the field on through packed varyings.
118
+ */
119
+ export function buildPackedFieldComponents(layout, field) {
120
+ const components = [];
121
+ for (const { attributeIndex, componentOffset, size } of field.columns) {
122
+ const attributeName = packedAttributeName(attributeIndex);
123
+ for (let i = 0; i < size; i++) {
124
+ components.push(layout.attributeSizes[attributeIndex] === 1
125
+ ? attributeName
126
+ : `${attributeName}.${SWIZZLE_COMPONENTS[componentOffset + i]}`);
127
+ }
128
+ }
129
+ return components;
130
+ }
108
131
  export function buildPackedAttributeDeclarations(layout) {
109
132
  return layout.attributeSizes.map((size, index) => `attribute ${PACKED_ATTRIBUTE_TYPES[size - 1]} ${packedAttributeName(index)};`);
110
133
  }
@@ -1,7 +1,8 @@
1
1
  import { Mesh } from "three";
2
- import { assertVertexAttributeBudget } from "../../asserts.js";
2
+ import { assertVaryingBudget, assertVertexAttributeBudget } from "../../asserts.js";
3
+ import { MASK_DATA_MODE_OFFSET, MASK_DATA_ROW0_OFFSET, MASK_DATA_ROW1_OFFSET, MASK_DATA_SHAPE_OFFSET, } from "../../mask/UIMask.Internal.js";
3
4
  import { arePropertiesPartiallyCompatible, cloneGLProperties, resolvePropertyUniform, TRANSFORM_ZINDEX_OFFSET, } from "../shared.js";
4
- import { BUILTIN_BLEND, BUILTIN_HSL, BUILTIN_TRANSFORM, BUILTIN_VISIBILITY, buildMaterial, buildPackedAttribute, buildPlaneLayout, CAPACITY_STEP, copyBetweenBuffers, INITIAL_CAPACITY, INSTANCED_PLANE_GEOMETRY, shiftBufferRegion, writePropertyToArray, } from "./UIGenericInstancedPlane.Internal.js";
5
+ import { BUILTIN_BLEND, BUILTIN_HSL, BUILTIN_MASK_MODE, BUILTIN_MASK_ROW0, BUILTIN_MASK_ROW1, BUILTIN_MASK_SHAPE, BUILTIN_TRANSFORM, BUILTIN_VISIBILITY, buildMaterial, buildPackedAttribute, buildPlaneLayout, CAPACITY_STEP, copyBetweenBuffers, INITIAL_CAPACITY, INSTANCED_PLANE_GEOMETRY, shiftBufferRegion, writePropertyToArray, } from "./UIGenericInstancedPlane.Internal.js";
5
6
  import { packedAttributeName, resolvePackedField } from "./UIGenericInstancedPlane.Layout.js";
6
7
  const TEMP_FIELD_VALUES = new Float32Array(16);
7
8
  /**
@@ -14,10 +15,13 @@ const TEMP_FIELD_VALUES = new Float32Array(16);
14
15
  * property) is packed into as few vertex attributes as possible, see
15
16
  * UIGenericInstancedPlane.Layout.ts. The zIndex is read back from the packed transform.
16
17
  *
18
+ * A masked plane is a separate shader variant with the builtin mask fields added; unmasked
19
+ * planes pay nothing for masking. See UIMask.Internal.ts for the mask data.
20
+ *
17
21
  * @internal
18
22
  */
19
23
  export class UIGenericInstancedPlane extends Mesh {
20
- constructor(source, properties, transparency, initialCapacity = INITIAL_CAPACITY) {
24
+ constructor(source, properties, transparency, masked, initialCapacity = INITIAL_CAPACITY) {
21
25
  const uniformProperties = {};
22
26
  const varyingProperties = {};
23
27
  for (const name in properties) {
@@ -29,18 +33,20 @@ export class UIGenericInstancedPlane extends Mesh {
29
33
  uniformProperties[name] = descriptor;
30
34
  }
31
35
  }
32
- const layout = buildPlaneLayout(varyingProperties);
36
+ const layout = buildPlaneLayout(varyingProperties, masked);
33
37
  const instancedGeometry = INSTANCED_PLANE_GEOMETRY.clone();
34
- const shaderMaterial = buildMaterial(source, uniformProperties, layout, transparency);
38
+ const { material: shaderMaterial, varyingRowCount } = buildMaterial(source, uniformProperties, layout, transparency, masked);
35
39
  super(instancedGeometry, shaderMaterial);
36
40
  this.onBeforeRenderInternal = (renderer) => {
37
41
  assertVertexAttributeBudget(renderer, this.vertexAttributeCount, this.vertexAttributeSubject);
42
+ assertVaryingBudget(renderer, this.varyingRowCount, this.vertexAttributeSubject);
38
43
  };
39
44
  this.frustumCulled = false;
40
45
  this.matrixAutoUpdate = false;
41
46
  this.matrixWorldAutoUpdate = false;
42
47
  this.source = source;
43
48
  this.transparency = transparency;
49
+ this.masked = masked;
44
50
  this.instancedGeometry = instancedGeometry;
45
51
  this.shaderMaterial = shaderMaterial;
46
52
  this.properties = properties;
@@ -51,6 +57,15 @@ export class UIGenericInstancedPlane extends Mesh {
51
57
  this.visibilityField = resolvePackedField(layout, BUILTIN_VISIBILITY);
52
58
  this.blendField = resolvePackedField(layout, BUILTIN_BLEND);
53
59
  this.hslField = resolvePackedField(layout, BUILTIN_HSL);
60
+ // Same order as the mask data: row 0, row 1, shape, mode
61
+ this.maskFields = masked
62
+ ? [
63
+ resolvePackedField(layout, BUILTIN_MASK_ROW0),
64
+ resolvePackedField(layout, BUILTIN_MASK_ROW1),
65
+ resolvePackedField(layout, BUILTIN_MASK_SHAPE),
66
+ resolvePackedField(layout, BUILTIN_MASK_MODE),
67
+ ]
68
+ : undefined;
54
69
  const zIndexColumn = this.transformField.columns.find(({ sourceOffset, size }) => sourceOffset <= TRANSFORM_ZINDEX_OFFSET && TRANSFORM_ZINDEX_OFFSET < sourceOffset + size);
55
70
  if (zIndexColumn === undefined) {
56
71
  throw new Error(`UIGenericInstancedPlane.constructor: transform layout lacks the zIndex`);
@@ -61,6 +76,7 @@ export class UIGenericInstancedPlane extends Mesh {
61
76
  this.vertexAttributeCount =
62
77
  Object.keys(INSTANCED_PLANE_GEOMETRY.attributes).length + layout.attributeSizes.length;
63
78
  this.vertexAttributeSubject = `UIGenericInstancedPlane.onBeforeRender.properties (${Object.keys(varyingProperties).join(", ")})`;
79
+ this.varyingRowCount = varyingRowCount;
64
80
  this.onBeforeRender = this.onBeforeRenderInternal;
65
81
  this.capacity = Math.max(Math.ceil(initialCapacity / CAPACITY_STEP) * CAPACITY_STEP, CAPACITY_STEP);
66
82
  this.instancesCountInternal = 0;
@@ -84,7 +100,7 @@ export class UIGenericInstancedPlane extends Mesh {
84
100
  /**
85
101
  * Insert instance at given index. Elements at [index..end) are shifted right.
86
102
  */
87
- insertAt(index, properties, transform, visibility, blend, hsl) {
103
+ insertAt(index, properties, transform, visibility, blend, hsl, mask) {
88
104
  if (index < 0 || index > this.instancesCountInternal) {
89
105
  throw new Error(`UIGenericInstancedPlane.insertAt.index: out of bounds (index=${index}, count=${this.instancesCountInternal})`);
90
106
  }
@@ -97,6 +113,9 @@ export class UIGenericInstancedPlane extends Mesh {
97
113
  this.writeBlend(index, blend);
98
114
  this.writeHSL(index, hsl);
99
115
  this.writeProperties(index, properties);
116
+ if (mask !== null) {
117
+ this.writeMask(index, mask);
118
+ }
100
119
  this.instancesCountInternal++;
101
120
  this.instancedGeometry.instanceCount = this.instancesCountInternal;
102
121
  }
@@ -148,6 +167,13 @@ export class UIGenericInstancedPlane extends Mesh {
148
167
  }
149
168
  this.writeHSL(index, hsl);
150
169
  }
170
+ /** Update mask data at given index; the plane must be masked */
171
+ setMaskAt(index, mask) {
172
+ if (index < 0 || index >= this.instancesCountInternal) {
173
+ throw new Error(`UIGenericInstancedPlane.setMaskAt.index: out of bounds (index=${index}, count=${this.instancesCountInternal})`);
174
+ }
175
+ this.writeMask(index, mask);
176
+ }
151
177
  /** Get zIndex at given index (from transform buffer) */
152
178
  getZIndexAt(index) {
153
179
  if (index < 0 || index >= this.instancesCountInternal) {
@@ -189,7 +215,7 @@ export class UIGenericInstancedPlane extends Mesh {
189
215
  throw new Error(`UIGenericInstancedPlane.split.atIndex: must be in range (0, count) (atIndex=${atIndex}, count=${this.instancesCountInternal})`);
190
216
  }
191
217
  const tailCount = this.instancesCountInternal - atIndex;
192
- const newPlane = new UIGenericInstancedPlane(this.source, cloneGLProperties(this.properties), this.transparency, tailCount);
218
+ const newPlane = new UIGenericInstancedPlane(this.source, cloneGLProperties(this.properties), this.transparency, this.masked, tailCount);
193
219
  for (let i = 0; i < this.packedAttributes.length; i++) {
194
220
  const thisAttribute = this.packedAttributes[i];
195
221
  const newAttribute = newPlane.packedAttributes[i];
@@ -206,18 +232,20 @@ export class UIGenericInstancedPlane extends Mesh {
206
232
  /**
207
233
  * Check if this plane can accept elements with given parameters.
208
234
  */
209
- isCompatibleWith(source, properties, transparency) {
235
+ isCompatibleWith(source, properties, transparency, masked) {
210
236
  return (this.source === source &&
211
237
  this.transparency === transparency &&
238
+ this.masked === masked &&
212
239
  arePropertiesPartiallyCompatible(this.properties, properties));
213
240
  }
214
241
  /**
215
- * Check if another plane can be merged into this one: same shader source and transparency, same
216
- * attribute layout and the same uniform values.
242
+ * Check if another plane can be merged into this one: same shader source, transparency and
243
+ * mask variant, same attribute layout and the same uniform values.
217
244
  */
218
245
  canMerge(other) {
219
246
  return (this.source === other.source &&
220
247
  this.transparency === other.transparency &&
248
+ this.masked === other.masked &&
221
249
  this.layout.signature === other.layout.signature &&
222
250
  arePropertiesPartiallyCompatible(this.uniformProperties, other.uniformProperties) &&
223
251
  arePropertiesPartiallyCompatible(other.uniformProperties, this.uniformProperties));
@@ -275,7 +303,9 @@ export class UIGenericInstancedPlane extends Mesh {
275
303
  for (const name in properties) {
276
304
  const { value, glslTypeInfo } = properties[name];
277
305
  if (glslTypeInfo.instantiable) {
278
- writePropertyToArray(value, TEMP_FIELD_VALUES, 0);
306
+ // The layout of the plane decides, so a plain Matrix3 fits an affine field too
307
+ const affine = this.properties[name].glslTypeInfo.affine === true;
308
+ writePropertyToArray(value, TEMP_FIELD_VALUES, 0, affine);
279
309
  this.writeField(index, resolvePackedField(this.layout, name), TEMP_FIELD_VALUES);
280
310
  }
281
311
  else {
@@ -299,6 +329,16 @@ export class UIGenericInstancedPlane extends Mesh {
299
329
  TEMP_FIELD_VALUES[2] = hsl.l;
300
330
  this.writeField(index, this.hslField, TEMP_FIELD_VALUES);
301
331
  }
332
+ writeMask(index, mask) {
333
+ if (this.maskFields === undefined) {
334
+ throw new Error(`UIGenericInstancedPlane.writeMask: plane is not masked`);
335
+ }
336
+ const [row0Field, row1Field, shapeField, modeField] = this.maskFields;
337
+ this.writeField(index, row0Field, mask.subarray(MASK_DATA_ROW0_OFFSET));
338
+ this.writeField(index, row1Field, mask.subarray(MASK_DATA_ROW1_OFFSET));
339
+ this.writeField(index, shapeField, mask.subarray(MASK_DATA_SHAPE_OFFSET));
340
+ this.writeField(index, modeField, mask.subarray(MASK_DATA_MODE_OFFSET));
341
+ }
302
342
  writeField(index, field, values) {
303
343
  for (const { attributeIndex, componentOffset, sourceOffset, size } of field.columns) {
304
344
  const attribute = this.packedAttributes[attributeIndex];
@@ -14,5 +14,7 @@ export interface PlaneState {
14
14
  transparency: UITransparencyMode;
15
15
  blend: number;
16
16
  hsl: HSLAdjustment;
17
+ /** Packed mask data (see UIMask.Internal.ts), null for an unmasked plane */
18
+ mask: Float32Array | null;
17
19
  zIndex: number;
18
20
  }
@@ -1,3 +1,4 @@
1
+ import { Matrix3 } from "three";
1
2
  import { cloneGLProperties, cloneProperties, convertUIPropertiesToGLProperties, extractZIndex, } from "../shared.js";
2
3
  import { UIGenericInstancedPlane } from "../UIGenericInstancedPlane/UIGenericInstancedPlane.js";
3
4
  /**
@@ -45,6 +46,7 @@ export class UIPlaneRegistry {
45
46
  transparency,
46
47
  blend,
47
48
  hsl: { h: hsl.h, s: hsl.s, l: hsl.l },
49
+ mask: null,
48
50
  zIndex,
49
51
  };
50
52
  this.handlerToState.set(handler, state);
@@ -81,6 +83,9 @@ export class UIPlaneRegistry {
81
83
  for (const name in glProperties) {
82
84
  const newProp = glProperties[name];
83
85
  const oldProp = state.properties[name];
86
+ if (oldProp === undefined) {
87
+ throw new Error(`UIPlaneRegistry.setProperties.properties: unknown property "${name}" for handler ${handler}`);
88
+ }
84
89
  if (!newProp.glslTypeInfo.instantiable) {
85
90
  if (oldProp.value !== newProp.value) {
86
91
  textureChanged = true;
@@ -88,7 +93,11 @@ export class UIPlaneRegistry {
88
93
  }
89
94
  state.properties[name] = {
90
95
  value: newProp.value,
91
- glslTypeInfo: newProp.glslTypeInfo,
96
+ // A mat3 field keeps the layout it was created with for any Matrix3, affine or full,
97
+ // see UIAffineMatrix3; the element stays in its batch
98
+ glslTypeInfo: oldProp.glslTypeInfo.glslTypeName === "mat3" && newProp.value instanceof Matrix3
99
+ ? oldProp.glslTypeInfo
100
+ : newProp.glslTypeInfo,
92
101
  };
93
102
  }
94
103
  if (textureChanged && !this.pendingCreate.has(handler)) {
@@ -162,6 +171,37 @@ export class UIPlaneRegistry {
162
171
  descriptor.mesh.setHSLAt(descriptor.instanceIndex, hsl);
163
172
  }
164
173
  }
174
+ /**
175
+ * Updates plane mask; null removes it. Data is copied.
176
+ * Masked and unmasked planes are different shader variants, so adding or removing the mask
177
+ * relocates the element on flush(); changing the data of a masked plane is applied immediately.
178
+ */
179
+ setMask(handler, mask) {
180
+ const state = this.resolveState(handler);
181
+ const wasMasked = state.mask !== null;
182
+ if (mask === null) {
183
+ state.mask = null;
184
+ }
185
+ else if (state.mask === null) {
186
+ state.mask = new Float32Array(mask);
187
+ }
188
+ else {
189
+ state.mask.set(mask);
190
+ }
191
+ if (wasMasked !== (mask !== null)) {
192
+ if (!this.pendingCreate.has(handler)) {
193
+ this.pendingRelocate.add(handler);
194
+ this.needsFlush = true;
195
+ }
196
+ return;
197
+ }
198
+ if (state.mask !== null) {
199
+ const descriptor = this.handlerToDescriptor.get(handler);
200
+ if (descriptor && !this.pendingRelocate.has(handler)) {
201
+ descriptor.mesh.setMaskAt(descriptor.instanceIndex, state.mask);
202
+ }
203
+ }
204
+ }
165
205
  /**
166
206
  * Updates plane transparency mode.
167
207
  * Element will be relocated on flush() if transparency changes.
@@ -299,7 +339,8 @@ export class UIPlaneRegistry {
299
339
  }
300
340
  }
301
341
  insertSingleElement(handler, state) {
302
- const { source, properties, transform, visibility, transparency, blend, hsl, zIndex } = state;
342
+ const { source, properties, transform, visibility, transparency, blend, hsl, mask, zIndex } = state;
343
+ const masked = mask !== null;
303
344
  let newMeshIndex = this.orderedMeshes.length;
304
345
  for (let i = 0; i < this.orderedMeshes.length; i++) {
305
346
  const mesh = this.orderedMeshes[i];
@@ -313,9 +354,9 @@ export class UIPlaneRegistry {
313
354
  break;
314
355
  }
315
356
  if (zIndex <= meshMaxZ) {
316
- if (mesh.isCompatibleWith(source, properties, transparency)) {
357
+ if (mesh.isCompatibleWith(source, properties, transparency, masked)) {
317
358
  const instanceIndex = this.findInstanceIndexInMesh(mesh, zIndex);
318
- mesh.insertAt(instanceIndex, properties, transform, visibility, blend, hsl);
359
+ mesh.insertAt(instanceIndex, properties, transform, visibility, blend, hsl, mask);
319
360
  this.shiftHandlerIndices(mesh, instanceIndex, 1);
320
361
  this.handlerToDescriptor.set(handler, { mesh, instanceIndex });
321
362
  return;
@@ -335,8 +376,8 @@ export class UIPlaneRegistry {
335
376
  }
336
377
  newMeshIndex = i + 1;
337
378
  }
338
- const mesh = new UIGenericInstancedPlane(source, cloneGLProperties(properties), transparency);
339
- mesh.insertAt(0, properties, transform, visibility, blend, hsl);
379
+ const mesh = new UIGenericInstancedPlane(source, cloneGLProperties(properties), transparency, masked);
380
+ mesh.insertAt(0, properties, transform, visibility, blend, hsl, mask);
340
381
  this.orderedMeshes.splice(newMeshIndex, 0, mesh);
341
382
  this.scene.add(mesh);
342
383
  this.handlerToDescriptor.set(handler, { mesh, instanceIndex: 0 });
@@ -1,9 +1,10 @@
1
1
  import type { IUniform, ShaderMaterial } from "three";
2
2
  import { Matrix3, Matrix4, Texture, Vector2, Vector3, Vector4 } from "three";
3
3
  import { UIColor } from "../color/UIColor.js";
4
+ import { UIAffineMatrix3 } from "../UIAffineMatrix3.js";
4
5
  export type UIProperty = Texture | UIColor | Vector2 | Vector3 | Vector4 | Matrix3 | Matrix4 | number;
5
- export type UIPropertyName = "Texture" | "UIColor" | "Vector2" | "Vector3" | "Vector4" | "Matrix3" | "Matrix4" | "number";
6
- export type UIPropertyConstructor = typeof Texture | typeof UIColor | typeof Vector2 | typeof Vector3 | typeof Vector4 | typeof Matrix3 | typeof Matrix4 | NumberConstructor;
6
+ export type UIPropertyName = "Texture" | "UIColor" | "Vector2" | "Vector3" | "Vector4" | "Matrix3" | "UIAffineMatrix3" | "Matrix4" | "number";
7
+ export type UIPropertyConstructor = typeof Texture | typeof UIColor | typeof Vector2 | typeof Vector3 | typeof Vector4 | typeof Matrix3 | typeof UIAffineMatrix3 | typeof Matrix4 | NumberConstructor;
7
8
  export type UIPropertyCopyTo = UIColor | Vector2 | Vector3 | Vector4 | Matrix3 | Matrix4;
8
9
  export type UIPropertyCopyFrom = UIColor & Vector2 & Vector3 & Vector4 & Matrix3 & Matrix4;
9
10
  export interface GLTypeInfo {
@@ -16,6 +17,11 @@ export interface GLTypeInfo {
16
17
  */
17
18
  columnCount: number;
18
19
  instantiable: boolean;
20
+ /**
21
+ * Whether a mat3 is stored as a 2D affine transform: three columns of two floats, the bottom
22
+ * row taken as (0, 0, 1). See UIAffineMatrix3.
23
+ */
24
+ affine?: boolean;
19
25
  }
20
26
  export interface GLProperty {
21
27
  value: UIProperty;
@@ -43,4 +49,10 @@ export declare function cloneGLProperties(properties: Record<string, GLProperty>
43
49
  export declare const TRANSFORM_ZINDEX_OFFSET = 14;
44
50
  /** Extracts zIndex from transform matrix (translation.z component) */
45
51
  export declare function extractZIndex(transform: Matrix4): number;
46
- export declare function buildGenericPlaneFragmentShader(uniformDeclarations: string[], varyingDeclarations: string[], source: string, alphaTestValue: number, usePremultipliedAlpha: boolean): string;
52
+ /**
53
+ * Builds the fragment shader of a plane. The p_* fields the source reads are plain globals,
54
+ * filled from the packed varyings at the start of main (see varyingPacking.ts).
55
+ * @param fieldDeclarations Packed varying and p_* global declarations
56
+ * @param fieldAssignments Statements filling the p_* globals from the packed varyings
57
+ */
58
+ export declare function buildGenericPlaneFragmentShader(uniformDeclarations: string[], fieldDeclarations: string[], fieldAssignments: string[], source: string, alphaTestValue: number, usePremultipliedAlpha: boolean, maskSource?: string): string;