laymur 0.27.1 → 0.29.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 (138) hide show
  1. package/README.md +99 -5
  2. package/dist/core/constraints/UIAspectConstraint/UIAspectConstraint.d.ts +14 -3
  3. package/dist/core/constraints/UIAspectConstraint/UIAspectConstraint.js +40 -6
  4. package/dist/core/constraints/UICustomConstraint.js +2 -2
  5. package/dist/core/constraints/UIHeightConstraint/UIHeightConstraint.js +3 -2
  6. package/dist/core/constraints/UIHorizontalDistanceConstraint/UIHorizontalDistanceConstraint.js +3 -2
  7. package/dist/core/constraints/UIHorizontalInterpolationConstraint/UIHorizontalInterpolationConstraint.js +3 -2
  8. package/dist/core/constraints/UIHorizontalProportionConstraint/UIHorizontalProportionConstraint.js +3 -2
  9. package/dist/core/constraints/UISingleParameterConstraint/UISingleParameterConstraint.d.ts +6 -0
  10. package/dist/core/constraints/UISingleParameterConstraint/UISingleParameterConstraint.js +8 -0
  11. package/dist/core/constraints/UIVerticalDistanceConstraint/UIVerticalDistanceConstraint.js +3 -2
  12. package/dist/core/constraints/UIVerticalInterpolationConstraint/UIVerticalInterpolationConstraint.js +3 -2
  13. package/dist/core/constraints/UIVerticalProportionConstraint/UIVerticalProportionConstraint.js +3 -2
  14. package/dist/core/constraints/UIWidthConstraint/UIWidthConstraint.js +3 -2
  15. package/dist/core/constraints/constraintAsserts.d.ts +41 -0
  16. package/dist/core/constraints/constraintAsserts.js +171 -0
  17. package/dist/core/elements/UICanvasElement/UICanvasElement.d.ts +54 -0
  18. package/dist/core/elements/UICanvasElement/UICanvasElement.js +70 -0
  19. package/dist/core/elements/UIDummy/UIDummy.Internal.d.ts +2 -0
  20. package/dist/core/elements/UIDummy/UIDummy.d.ts +8 -5
  21. package/dist/core/elements/UIDummy/UIDummy.js +24 -11
  22. package/dist/core/elements/UIElement/UIElement.Internal.d.ts +6 -5
  23. package/dist/core/elements/UIElement/UIElement.Internal.js +0 -4
  24. package/dist/core/elements/UIElement/UIElement.d.ts +12 -6
  25. package/dist/core/elements/UIElement/UIElement.js +14 -7
  26. package/dist/core/elements/UIGraphics/UIGraphics.Internal.d.ts +42 -2
  27. package/dist/core/elements/UIGraphics/UIGraphics.Internal.js +2 -2
  28. package/dist/core/elements/UIGraphics/UIGraphics.d.ts +48 -34
  29. package/dist/core/elements/UIGraphics/UIGraphics.js +196 -93
  30. package/dist/core/elements/UIImage/UIImage.d.ts +11 -1
  31. package/dist/core/elements/UIImage/UIImage.js +14 -0
  32. package/dist/core/elements/UIScene/UIScene.Internal.d.ts +10 -1
  33. package/dist/core/elements/UIScene/UIScene.Internal.js +1 -0
  34. package/dist/core/elements/UIScene/UIScene.d.ts +11 -1
  35. package/dist/core/elements/UIScene/UIScene.js +29 -5
  36. package/dist/core/elements/UIText/UIText.Interfaces.d.ts +2 -2
  37. package/dist/core/elements/UIText/UIText.Internal.d.ts +14 -1
  38. package/dist/core/elements/UIText/UIText.Internal.js +12 -0
  39. package/dist/core/elements/UIText/UIText.Measuring.d.ts +9 -4
  40. package/dist/core/elements/UIText/UIText.Measuring.js +17 -6
  41. package/dist/core/elements/UIText/UIText.Rendering.d.ts +7 -16
  42. package/dist/core/elements/UIText/UIText.Rendering.js +212 -46
  43. package/dist/core/elements/UIText/UIText.d.ts +64 -29
  44. package/dist/core/elements/UIText/UIText.js +134 -149
  45. package/dist/core/index.d.ts +10 -4
  46. package/dist/core/index.js +5 -1
  47. package/dist/core/layers/UILayer/UILayer.d.ts +17 -3
  48. package/dist/core/layers/UILayer/UILayer.js +35 -4
  49. package/dist/core/layers/UIViewportLayer/UIViewportLayer.d.ts +2 -0
  50. package/dist/core/layers/UIViewportLayer/UIViewportLayer.js +4 -1
  51. package/dist/core/miscellaneous/UIBlendMode.d.ts +5 -0
  52. package/dist/core/miscellaneous/UIBlendMode.js +7 -0
  53. package/dist/core/miscellaneous/asserts.d.ts +0 -41
  54. package/dist/core/miscellaneous/asserts.js +0 -170
  55. package/dist/core/miscellaneous/canvas-surface/UICanvasSurface.d.ts +46 -0
  56. package/dist/core/miscellaneous/canvas-surface/UICanvasSurface.js +86 -0
  57. package/dist/core/miscellaneous/color/UIColor.d.ts +17 -0
  58. package/dist/core/miscellaneous/color/UIColor.js +22 -0
  59. package/dist/core/miscellaneous/color/canvasColor.d.ts +9 -0
  60. package/dist/core/miscellaneous/color/canvasColor.js +15 -0
  61. package/dist/core/miscellaneous/insets/UIInsets.d.ts +3 -0
  62. package/dist/core/miscellaneous/insets/UIInsets.js +15 -0
  63. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.d.ts +10 -7
  64. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.js +11 -8
  65. package/dist/core/miscellaneous/paint/UIGradient.Internal.d.ts +37 -0
  66. package/dist/core/miscellaneous/paint/UIGradient.Internal.js +14 -0
  67. package/dist/core/miscellaneous/paint/UIGradient.d.ts +18 -0
  68. package/dist/core/miscellaneous/paint/UIGradient.js +35 -0
  69. package/dist/core/miscellaneous/paint/UILinearGradient.d.ts +14 -0
  70. package/dist/core/miscellaneous/paint/UILinearGradient.js +22 -0
  71. package/dist/core/miscellaneous/paint/UIPaint.Internal.d.ts +21 -0
  72. package/dist/core/miscellaneous/paint/UIPaint.Internal.js +1 -0
  73. package/dist/core/miscellaneous/paint/UIPaint.d.ts +17 -0
  74. package/dist/core/miscellaneous/paint/UIPaint.js +21 -0
  75. package/dist/core/miscellaneous/paint/UIRadialGradient.d.ts +18 -0
  76. package/dist/core/miscellaneous/paint/UIRadialGradient.js +33 -0
  77. package/dist/core/miscellaneous/shared.d.ts +14 -0
  78. package/dist/core/miscellaneous/shared.js +11 -0
  79. package/dist/core/miscellaneous/text-style/UITextStyle.Internal.d.ts +91 -30
  80. package/dist/core/miscellaneous/text-style/UITextStyle.Internal.js +12 -8
  81. package/dist/core/miscellaneous/text-style/UITextStyle.d.ts +41 -63
  82. package/dist/core/miscellaneous/text-style/UITextStyle.js +165 -291
  83. package/dist/core/miscellaneous/texture/UITextureView.Internal.d.ts +2 -1
  84. package/dist/core/miscellaneous/texture/UITextureView.Internal.js +12 -3
  85. package/dist/core/shaders/UIProgressMaskFunctionCircular.js +1 -2
  86. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.Internal.d.ts +7 -3
  87. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.d.ts +2 -1
  88. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.js +19 -10
  89. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.Internal.d.ts +6 -2
  90. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.d.ts +41 -9
  91. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.js +97 -35
  92. package/dist/particles/behaviorModules/UIBehaviorAlignToVelocity.d.ts +44 -0
  93. package/dist/particles/behaviorModules/UIBehaviorAlignToVelocity.js +75 -0
  94. package/dist/particles/behaviorModules/UIBehaviorBounce.d.ts +51 -0
  95. package/dist/particles/behaviorModules/UIBehaviorBounce.js +107 -0
  96. package/dist/particles/behaviorModules/UIBehaviorOrbit.d.ts +39 -0
  97. package/dist/particles/behaviorModules/UIBehaviorOrbit.js +73 -0
  98. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.d.ts +7 -2
  99. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.js +9 -5
  100. package/dist/particles/behaviorModules/UIBehaviorSeek.d.ts +38 -0
  101. package/dist/particles/behaviorModules/UIBehaviorSeek.js +75 -0
  102. package/dist/particles/elements/UIEmitter.Internal.d.ts +48 -1
  103. package/dist/particles/elements/UIEmitter.Internal.js +26 -1
  104. package/dist/particles/elements/UIEmitter.Schedule.d.ts +31 -0
  105. package/dist/particles/elements/UIEmitter.Schedule.js +81 -0
  106. package/dist/particles/elements/UIEmitter.d.ts +79 -9
  107. package/dist/particles/elements/UIEmitter.js +241 -83
  108. package/dist/particles/index.d.ts +13 -1
  109. package/dist/particles/index.js +11 -1
  110. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.d.ts +6 -0
  111. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.js +27 -0
  112. package/dist/particles/instancedParticle/UIInstancedParticle.d.ts +7 -1
  113. package/dist/particles/instancedParticle/UIInstancedParticle.js +12 -1
  114. package/dist/particles/miscellaneous/miscellaneous.d.ts +22 -0
  115. package/dist/particles/miscellaneous/miscellaneous.js +38 -0
  116. package/dist/particles/renderingModules/UIRenderingFlipbook.d.ts +41 -0
  117. package/dist/particles/renderingModules/UIRenderingFlipbook.js +70 -0
  118. package/dist/particles/renderingModules/UIRenderingModule.d.ts +2 -1
  119. package/dist/particles/renderingModules/UIRenderingModule.js +2 -1
  120. package/dist/particles/renderingModules/UIRenderingRandomColor.d.ts +19 -0
  121. package/dist/particles/renderingModules/UIRenderingRandomColor.js +28 -0
  122. package/dist/particles/renderingModules/UIRenderingShape.d.ts +31 -0
  123. package/dist/particles/renderingModules/UIRenderingShape.js +54 -0
  124. package/dist/particles/renderingModules/UIRenderingTexture.d.ts +1 -1
  125. package/dist/particles/renderingModules/UIRenderingTexture.js +4 -28
  126. package/dist/particles/shaders/UIRenderingFlipbook.d.ts +5 -0
  127. package/dist/particles/shaders/UIRenderingFlipbook.js +19 -0
  128. package/dist/particles/shaders/UIRenderingRandomColor.d.ts +2 -0
  129. package/dist/particles/shaders/UIRenderingRandomColor.js +10 -0
  130. package/dist/particles/shaders/UIRenderingShape.d.ts +6 -0
  131. package/dist/particles/shaders/UIRenderingShape.js +15 -0
  132. package/dist/particles/shaders/UIRenderingTexture.d.ts +4 -2
  133. package/dist/particles/shaders/UIRenderingTexture.js +27 -2
  134. package/dist/particles/spawnModules/UISpawnCircle.d.ts +44 -0
  135. package/dist/particles/spawnModules/UISpawnCircle.js +81 -0
  136. package/dist/particles/spawnModules/UISpawnRadialVelocity.d.ts +37 -0
  137. package/dist/particles/spawnModules/UISpawnRadialVelocity.js +75 -0
  138. package/package.json +1 -1
@@ -34,6 +34,31 @@ const PARTICLE_BUILTIN_MACROS = [
34
34
  ["PARTICLE_RANDOM_E", BUILTIN_OFFSET_RANDOM_E],
35
35
  ["PARTICLE_RANDOM_F", BUILTIN_OFFSET_RANDOM_F],
36
36
  ];
37
+ /** Builtin random values handed out to rendering modules that read `PARTICLE_RANDOM`, in order */
38
+ const RENDERING_RANDOM_MACROS = [
39
+ "PARTICLE_RANDOM_A",
40
+ "PARTICLE_RANDOM_B",
41
+ "PARTICLE_RANDOM_C",
42
+ "PARTICLE_RANDOM_D",
43
+ "PARTICLE_RANDOM_E",
44
+ ];
45
+ /**
46
+ * Gives each rendering module that reads `PARTICLE_RANDOM` a random value of its own, the next of
47
+ * `PARTICLE_RANDOM_A`-`E` in module order, so two modules do not pick alike
48
+ * @returns Sources with `PARTICLE_RANDOM` renamed accordingly
49
+ */
50
+ export function assignRenderingRandomValues(sources, debugContext) {
51
+ let next = 0;
52
+ return sources.map((source, index) => {
53
+ if (!isIdentifierReferenced(source, "PARTICLE_RANDOM")) {
54
+ return source;
55
+ }
56
+ if (next === RENDERING_RANDOM_MACROS.length) {
57
+ throw new Error(`${debugContext}[${index}]: more than ${RENDERING_RANDOM_MACROS.length} rendering modules read PARTICLE_RANDOM`);
58
+ }
59
+ return source.replace(/\bPARTICLE_RANDOM\b/g, RENDERING_RANDOM_MACROS[next++]);
60
+ });
61
+ }
37
62
  export function collectProperties(keeper, modules, debugContext) {
38
63
  for (const module of modules) {
39
64
  if (module.requiredProperties === undefined) {
@@ -163,6 +188,7 @@ export function buildParticleFragmentShader(uniformDeclarations, fieldDeclaratio
163
188
  discard;
164
189
  }
165
190
  gl_FragColor = linearToOutputTexel(diffuseColor);
191
+ gl_FragColor = vec4(gl_FragColor.rgb * gl_FragColor.a, gl_FragColor.a * p_blendFactor);
166
192
  }
167
193
  `;
168
194
  }
@@ -239,6 +265,7 @@ export function buildParticleMaterial(sources, uniformProperties, varyingPropert
239
265
  forceSinglePass: true,
240
266
  depthWrite: false,
241
267
  depthTest: true,
268
+ premultipliedAlpha: true,
242
269
  });
243
270
  return { material, varyingRowCount: packed.rowCount };
244
271
  }
@@ -20,7 +20,13 @@ export declare class UIInstancedParticle extends Mesh {
20
20
  */
21
21
  limitUploadToLiveInstances(): void;
22
22
  setOrigin(x: number, y: number): void;
23
- removeDeadParticles(): void;
23
+ /** Output-alpha multiplier of the premultiplied shader, see `blendModeToFactor` */
24
+ setBlendFactor(value: number): void;
25
+ /**
26
+ * Removes the particles whose age reached their lifetime, keeping the order of the others
27
+ * @param onDead Called for each dead particle before its slot is reused
28
+ */
29
+ removeDeadParticles(onDead: (builtinArray: ArrayLike<number>, itemOffset: number) => void): void;
24
30
  drop(): void;
25
31
  destroy(): void;
26
32
  private ensureCapacity;
@@ -81,7 +81,15 @@ export class UIInstancedParticle extends Mesh {
81
81
  const uniform = resolvePropertyUniform("origin", this.shaderMaterial);
82
82
  uniform.value.set(x, y);
83
83
  }
84
- removeDeadParticles() {
84
+ /** Output-alpha multiplier of the premultiplied shader, see `blendModeToFactor` */
85
+ setBlendFactor(value) {
86
+ resolvePropertyUniform("blendFactor", this.shaderMaterial).value = value;
87
+ }
88
+ /**
89
+ * Removes the particles whose age reached their lifetime, keeping the order of the others
90
+ * @param onDead Called for each dead particle before its slot is reused
91
+ */
92
+ removeDeadParticles(onDead) {
85
93
  const builtinBuffer = this.propertyBuffers.builtin;
86
94
  if (builtinBuffer === undefined) {
87
95
  return;
@@ -104,6 +112,9 @@ export class UIInstancedParticle extends Mesh {
104
112
  }
105
113
  writeIndex++;
106
114
  }
115
+ else {
116
+ onDead(builtinArray, offset);
117
+ }
107
118
  }
108
119
  this.instancedGeometry.instanceCount = writeIndex;
109
120
  }
@@ -11,8 +11,30 @@ export interface UIRange {
11
11
  export type UIRangeConfig = UIRange | [number, number] | number;
12
12
  export type UIVector2Config = Vector2Like | Vector2Tuple | number;
13
13
  export type UIAspectConfig = number | UITextureConfig;
14
+ /** Easing of an interpolation between two values */
15
+ export declare enum UIEasing {
16
+ /** Constant rate */
17
+ LINEAR = 0,
18
+ /** Starts slow, quadratic */
19
+ IN = 1,
20
+ /** Ends slow, quadratic */
21
+ OUT = 2,
22
+ /** Starts and ends slow, smoothstep */
23
+ IN_OUT = 3
24
+ }
25
+ /**
26
+ * Eases an interpolation factor
27
+ * @param t Factor in [0, 1]
28
+ * @returns Eased factor, 0 at t = 0 and 1 at t = 1
29
+ */
30
+ export declare function applyEasing(easing: UIEasing, t: number): number;
14
31
  /** Formats a number as a GLSL float literal */
15
32
  export declare function toGLSLFloat(value: number): string;
33
+ /**
34
+ * GLSL expression of a whole float in [0, count) from a fraction in [0, 1]: the index of the cell
35
+ * the fraction falls in, the last cell taking 1
36
+ */
37
+ export declare function buildIndexExpression(fraction: string, count: number): string;
16
38
  /** GLSL expression of the u that samples a gradient texture of `size` texels at t in [0, 1] */
17
39
  export declare function buildGradientCoordinate(t: string, size: number): string;
18
40
  export declare function resolveUIRangeConfig(config: UIRangeConfig): UIRange;
@@ -2,11 +2,49 @@ import { makeNoise2D } from "fast-simplex-noise";
2
2
  import { ClampToEdgeWrapping, DataTexture, LinearFilter, RGBAFormat, SRGBColorSpace, Texture, UnsignedByteType, UVMapping, } from "three";
3
3
  export { assertValidNonNegativeInteger, assertValidUnitNumber, } from "../../core/miscellaneous/asserts.js";
4
4
  import { getTextureImageSize } from "../../core/miscellaneous/texture/UITextureView.Internal.js";
5
+ /** Easing of an interpolation between two values */
6
+ export var UIEasing;
7
+ (function (UIEasing) {
8
+ /** Constant rate */
9
+ UIEasing[UIEasing["LINEAR"] = 0] = "LINEAR";
10
+ /** Starts slow, quadratic */
11
+ UIEasing[UIEasing["IN"] = 1] = "IN";
12
+ /** Ends slow, quadratic */
13
+ UIEasing[UIEasing["OUT"] = 2] = "OUT";
14
+ /** Starts and ends slow, smoothstep */
15
+ UIEasing[UIEasing["IN_OUT"] = 3] = "IN_OUT";
16
+ })(UIEasing || (UIEasing = {}));
17
+ /**
18
+ * Eases an interpolation factor
19
+ * @param t Factor in [0, 1]
20
+ * @returns Eased factor, 0 at t = 0 and 1 at t = 1
21
+ */
22
+ export function applyEasing(easing, t) {
23
+ switch (easing) {
24
+ case UIEasing.LINEAR:
25
+ return t;
26
+ case UIEasing.IN:
27
+ return t * t;
28
+ case UIEasing.OUT:
29
+ return t * (2 - t);
30
+ case UIEasing.IN_OUT:
31
+ return t * t * (3 - 2 * t);
32
+ }
33
+ }
5
34
  /** Formats a number as a GLSL float literal */
6
35
  export function toGLSLFloat(value) {
7
36
  const literal = String(value);
8
37
  return /[.e]/.test(literal) ? literal : `${literal}.0`;
9
38
  }
39
+ /**
40
+ * GLSL expression of a whole float in [0, count) from a fraction in [0, 1]: the index of the cell
41
+ * the fraction falls in, the last cell taking 1
42
+ */
43
+ export function buildIndexExpression(fraction, count) {
44
+ const size = toGLSLFloat(count);
45
+ // Clamped below the count: at mediump precision a value just below it can round up to it
46
+ return `floor(min(${fraction} * ${size}, ${size} - 0.5))`;
47
+ }
10
48
  /** GLSL expression of the u that samples a gradient texture of `size` texels at t in [0, 1] */
11
49
  export function buildGradientCoordinate(t, size) {
12
50
  // Texel centers: the first stop at t = 0, the last at t = 1.
@@ -0,0 +1,41 @@
1
+ import type { UIProperty, UIPropertyName } from "../../core/miscellaneous/generic-plane/shared.js";
2
+ import type { UITextureConfig } from "../../core/miscellaneous/texture/UITextureView.Internal.js";
3
+ import { UIRenderingModule } from "./UIRenderingModule.js";
4
+ /** How `UIRenderingFlipbook` picks the frame of a particle */
5
+ export declare enum UIFlipbookMode {
6
+ /** Plays all frames once over the particle's life */
7
+ LIFE = 0,
8
+ /** Plays frames at a frame rate, looped */
9
+ RATE = 1,
10
+ /** One random frame for the whole life */
11
+ RANDOM = 2
12
+ }
13
+ /** Configuration options for UIRenderingFlipbook */
14
+ export interface UIRenderingFlipbookOptions {
15
+ /** Number of frames, if the last row is not full. All cells by default. */
16
+ frameCount: number;
17
+ /** How the frame is picked */
18
+ mode: UIFlipbookMode;
19
+ /** Frames per second in RATE mode, 24 by default */
20
+ frameRate: number;
21
+ /** Whether each particle starts RATE playback at a random frame */
22
+ randomStartFrame: boolean;
23
+ }
24
+ /**
25
+ * Renders particles with frames of a sprite sheet: a grid of equal cells in one texture or atlas
26
+ * region, read row by row from the top left.
27
+ *
28
+ * The frame is computed in the shader, so the number of frames costs no uniforms.
29
+ */
30
+ export declare class UIRenderingFlipbook extends UIRenderingModule {
31
+ readonly requiredProperties: Record<string, UIPropertyName>;
32
+ readonly requiredUniforms: Record<string, UIProperty>;
33
+ readonly source: string;
34
+ /**
35
+ * @param config - Texture or atlas region holding the sheet
36
+ * @param columns - Cells per row
37
+ * @param rows - Rows of cells
38
+ * @param options - Frame count and playback
39
+ */
40
+ constructor(config: UITextureConfig, columns: number, rows: number, options?: Partial<UIRenderingFlipbookOptions>);
41
+ }
@@ -0,0 +1,70 @@
1
+ import { assertValidPositiveNumber } from "../../core/miscellaneous/asserts.js";
2
+ import { UITextureView } from "../../core/miscellaneous/texture/UITextureView.js";
3
+ import { assertValidNonNegativeInteger, buildIndexExpression, toGLSLFloat, } from "../miscellaneous/miscellaneous.js";
4
+ import { buildFlipbookSource } from "../shaders/UIRenderingFlipbook.js";
5
+ import { UIRenderingModule } from "./UIRenderingModule.js";
6
+ /** How `UIRenderingFlipbook` picks the frame of a particle */
7
+ export var UIFlipbookMode;
8
+ (function (UIFlipbookMode) {
9
+ /** Plays all frames once over the particle's life */
10
+ UIFlipbookMode[UIFlipbookMode["LIFE"] = 0] = "LIFE";
11
+ /** Plays frames at a frame rate, looped */
12
+ UIFlipbookMode[UIFlipbookMode["RATE"] = 1] = "RATE";
13
+ /** One random frame for the whole life */
14
+ UIFlipbookMode[UIFlipbookMode["RANDOM"] = 2] = "RANDOM";
15
+ })(UIFlipbookMode || (UIFlipbookMode = {}));
16
+ const FLIPBOOK_DEFAULT_FRAME_RATE = 24;
17
+ /**
18
+ * Renders particles with frames of a sprite sheet: a grid of equal cells in one texture or atlas
19
+ * region, read row by row from the top left.
20
+ *
21
+ * The frame is computed in the shader, so the number of frames costs no uniforms.
22
+ */
23
+ export class UIRenderingFlipbook extends UIRenderingModule {
24
+ /**
25
+ * @param config - Texture or atlas region holding the sheet
26
+ * @param columns - Cells per row
27
+ * @param rows - Rows of cells
28
+ * @param options - Frame count and playback
29
+ */
30
+ constructor(config, columns, rows, options = {}) {
31
+ super();
32
+ this.requiredProperties = {
33
+ builtin: "Matrix4",
34
+ };
35
+ assertValidNonNegativeInteger(columns, "UIRenderingFlipbook.constructor.columns");
36
+ assertValidPositiveNumber(columns, "UIRenderingFlipbook.constructor.columns");
37
+ assertValidNonNegativeInteger(rows, "UIRenderingFlipbook.constructor.rows");
38
+ assertValidPositiveNumber(rows, "UIRenderingFlipbook.constructor.rows");
39
+ const frameCount = options.frameCount ?? columns * rows;
40
+ assertValidNonNegativeInteger(frameCount, "UIRenderingFlipbook.constructor.frameCount");
41
+ assertValidPositiveNumber(frameCount, "UIRenderingFlipbook.constructor.frameCount");
42
+ if (frameCount > columns * rows) {
43
+ throw new Error(`UIRenderingFlipbook.constructor.frameCount: ${frameCount} frames do not fit ${columns}x${rows} cells`);
44
+ }
45
+ const frameRate = options.frameRate ?? FLIPBOOK_DEFAULT_FRAME_RATE;
46
+ assertValidPositiveNumber(frameRate, "UIRenderingFlipbook.constructor.frameRate");
47
+ const view = new UITextureView(config);
48
+ this.requiredUniforms = {
49
+ texture: view.texture,
50
+ textureTransform: view.calculateUVTransform(),
51
+ };
52
+ this.source = buildFlipbookSource(buildFrameExpression(options.mode ?? UIFlipbookMode.LIFE, frameCount, frameRate, options.randomStartFrame === true), columns, rows);
53
+ }
54
+ }
55
+ /** GLSL expression of the frame number, a whole float in [0, frameCount) */
56
+ function buildFrameExpression(mode, frameCount, frameRate, randomStartFrame) {
57
+ switch (mode) {
58
+ case UIFlipbookMode.LIFE:
59
+ return buildIndexExpression("clamp(PARTICLE_AGE / PARTICLE_LIFETIME, 0.0, 1.0)", frameCount);
60
+ case UIFlipbookMode.RANDOM:
61
+ return buildIndexExpression("PARTICLE_RANDOM", frameCount);
62
+ case UIFlipbookMode.RATE: {
63
+ const count = toGLSLFloat(frameCount);
64
+ const start = randomStartFrame ? ` + PARTICLE_RANDOM * ${count}` : "";
65
+ // Frames played so far, wrapped. mod divides, and at mediump precision a quotient just
66
+ // below a whole number gives the count itself, hence the clamp.
67
+ return `floor(min(mod(floor(PARTICLE_AGE * ${toGLSLFloat(frameRate)}${start}), ${count}), ${count} - 0.5))`;
68
+ }
69
+ }
70
+ }
@@ -4,7 +4,8 @@ import type { UIProperty, UIPropertyName } from "../../core/miscellaneous/generi
4
4
  *
5
5
  * The source defines `vec4 draw()`; the colors of all rendering modules are multiplied. It reads
6
6
  * `p_uv`, uniforms and properties as `p_<name>`, and builtin values through the `PARTICLE_*`
7
- * macros, which are cheaper than reading `p_builtin` as a whole. Uniforms belong to the module:
7
+ * macros, which are cheaper than reading `p_builtin` as a whole. `PARTICLE_RANDOM` is a random
8
+ * value of the module's own, constant over the particle's life, and needs the builtin property. Uniforms belong to the module:
8
9
  * the emitter renames them per module, so modules of one type keep their own values.
9
10
  */
10
11
  export declare abstract class UIRenderingModule {
@@ -3,7 +3,8 @@
3
3
  *
4
4
  * The source defines `vec4 draw()`; the colors of all rendering modules are multiplied. It reads
5
5
  * `p_uv`, uniforms and properties as `p_<name>`, and builtin values through the `PARTICLE_*`
6
- * macros, which are cheaper than reading `p_builtin` as a whole. Uniforms belong to the module:
6
+ * macros, which are cheaper than reading `p_builtin` as a whole. `PARTICLE_RANDOM` is a random
7
+ * value of the module's own, constant over the particle's life, and needs the builtin property. Uniforms belong to the module:
7
8
  * the emitter renames them per module, so modules of one type keep their own values.
8
9
  */
9
10
  export class UIRenderingModule {
@@ -0,0 +1,19 @@
1
+ import type { UIColor } from "../../core/index.js";
2
+ import type { UIProperty, UIPropertyName } from "../../core/miscellaneous/generic-plane/shared.js";
3
+ import { UIRenderingModule } from "./UIRenderingModule.js";
4
+ /**
5
+ * Colors each particle with one color of a palette, picked at random for its whole life.
6
+ *
7
+ * The palette is one texture, read at the texel center, so the number of colors costs no
8
+ * uniforms.
9
+ */
10
+ export declare class UIRenderingRandomColor extends UIRenderingModule {
11
+ readonly requiredProperties: Record<string, UIPropertyName>;
12
+ readonly requiredUniforms: Record<string, UIProperty>;
13
+ readonly source: string;
14
+ /**
15
+ * @param colors - Palette to pick from
16
+ */
17
+ constructor(colors: UIColor[]);
18
+ destroy(): void;
19
+ }
@@ -0,0 +1,28 @@
1
+ import { buildGradientTexture } from "../miscellaneous/miscellaneous.js";
2
+ import { buildRandomColorSource } from "../shaders/UIRenderingRandomColor.js";
3
+ import { UIRenderingModule } from "./UIRenderingModule.js";
4
+ /**
5
+ * Colors each particle with one color of a palette, picked at random for its whole life.
6
+ *
7
+ * The palette is one texture, read at the texel center, so the number of colors costs no
8
+ * uniforms.
9
+ */
10
+ export class UIRenderingRandomColor extends UIRenderingModule {
11
+ /**
12
+ * @param colors - Palette to pick from
13
+ */
14
+ constructor(colors) {
15
+ super();
16
+ this.requiredProperties = {
17
+ builtin: "Matrix4",
18
+ };
19
+ if (colors.length === 0) {
20
+ throw new Error("UIRenderingRandomColor.constructor.colors: colors array cannot be empty");
21
+ }
22
+ this.requiredUniforms = { paletteTexture: buildGradientTexture(colors) };
23
+ this.source = buildRandomColorSource(colors.length);
24
+ }
25
+ destroy() {
26
+ this.requiredUniforms.paletteTexture.dispose();
27
+ }
28
+ }
@@ -0,0 +1,31 @@
1
+ import type { UIProperty } from "../../core/miscellaneous/generic-plane/shared.js";
2
+ import { UIRenderingModule } from "./UIRenderingModule.js";
3
+ /** Shapes of `UIRenderingShape`, each filling the particle quad */
4
+ export declare enum UIParticleShape {
5
+ /** Disc touching the quad edges */
6
+ CIRCLE = 0,
7
+ /** Ring whose outer edge touches the quad edges */
8
+ RING = 1,
9
+ /** Four-point star with concave sides, its points at the quad edge centers */
10
+ SPARKLE = 2
11
+ }
12
+ /** Configuration options for UIRenderingShape */
13
+ export interface UIRenderingShapeOptions {
14
+ /** Part of the shape that fades out toward its edge, from 0 (hard edge) to 1 */
15
+ softness: number;
16
+ /** Ring width as a part of the radius, from 0 to 1 */
17
+ thickness: number;
18
+ }
19
+ /**
20
+ * Renders particles as a white shape computed in the shader, without a texture. Color modules
21
+ * tint it: the colors of all rendering modules are multiplied.
22
+ */
23
+ export declare class UIRenderingShape extends UIRenderingModule {
24
+ readonly requiredUniforms: Record<string, UIProperty>;
25
+ readonly source: string;
26
+ /**
27
+ * @param shape - Shape to draw
28
+ * @param options - Edge softness and ring thickness
29
+ */
30
+ constructor(shape: UIParticleShape, options?: Partial<UIRenderingShapeOptions>);
31
+ }
@@ -0,0 +1,54 @@
1
+ import { assertValidUnitNumber } from "../../core/miscellaneous/asserts.js";
2
+ import { toGLSLFloat } from "../miscellaneous/miscellaneous.js";
3
+ import { buildShapeSource } from "../shaders/UIRenderingShape.js";
4
+ import { UIRenderingModule } from "./UIRenderingModule.js";
5
+ /** Shapes of `UIRenderingShape`, each filling the particle quad */
6
+ export var UIParticleShape;
7
+ (function (UIParticleShape) {
8
+ /** Disc touching the quad edges */
9
+ UIParticleShape[UIParticleShape["CIRCLE"] = 0] = "CIRCLE";
10
+ /** Ring whose outer edge touches the quad edges */
11
+ UIParticleShape[UIParticleShape["RING"] = 1] = "RING";
12
+ /** Four-point star with concave sides, its points at the quad edge centers */
13
+ UIParticleShape[UIParticleShape["SPARKLE"] = 2] = "SPARKLE";
14
+ })(UIParticleShape || (UIParticleShape = {}));
15
+ /** Smallest softness: smoothstep is undefined for equal edges */
16
+ const SHAPE_MIN_SOFTNESS = 0.001;
17
+ /** Smallest ring thickness: the ring distance divides by it */
18
+ const SHAPE_MIN_THICKNESS = 0.001;
19
+ const SHAPE_DEFAULT_SOFTNESS = 0.2;
20
+ const SHAPE_DEFAULT_THICKNESS = 0.25;
21
+ /**
22
+ * Renders particles as a white shape computed in the shader, without a texture. Color modules
23
+ * tint it: the colors of all rendering modules are multiplied.
24
+ */
25
+ export class UIRenderingShape extends UIRenderingModule {
26
+ /**
27
+ * @param shape - Shape to draw
28
+ * @param options - Edge softness and ring thickness
29
+ */
30
+ constructor(shape, options = {}) {
31
+ super();
32
+ this.requiredUniforms = {};
33
+ const softness = options.softness ?? SHAPE_DEFAULT_SOFTNESS;
34
+ assertValidUnitNumber(softness, "UIRenderingShape.constructor.softness");
35
+ const thickness = options.thickness ?? SHAPE_DEFAULT_THICKNESS;
36
+ assertValidUnitNumber(thickness, "UIRenderingShape.constructor.thickness");
37
+ this.source = buildShapeSource(buildDistanceExpression(shape, Math.max(thickness, SHAPE_MIN_THICKNESS)), Math.max(softness, SHAPE_MIN_SOFTNESS));
38
+ }
39
+ }
40
+ /** GLSL expression of the shape distance in `p`, 1 on the edge */
41
+ function buildDistanceExpression(shape, thickness) {
42
+ switch (shape) {
43
+ case UIParticleShape.CIRCLE:
44
+ return "length(p)";
45
+ case UIParticleShape.RING: {
46
+ // Distance from the ring's middle line, in half widths
47
+ const halfWidth = toGLSLFloat(thickness / 2);
48
+ return `abs(length(p) - (1.0 - ${halfWidth})) / ${halfWidth}`;
49
+ }
50
+ case UIParticleShape.SPARKLE:
51
+ // sqrt|x| + sqrt|y| = 1 is an astroid-like star with its points on the axes
52
+ return "sqrt(abs(p.x)) + sqrt(abs(p.y))";
53
+ }
54
+ }
@@ -5,7 +5,7 @@ import { UIRenderingModule } from "./UIRenderingModule.js";
5
5
  * Renders particles with a texture.
6
6
  *
7
7
  * Accepts a single texture config or an array of configs from the same atlas.
8
- * When an array is provided, each particle picks one texture randomly using PARTICLE_RANDOM_A.
8
+ * When an array is provided, each particle picks one texture randomly using PARTICLE_RANDOM.
9
9
  * All configs in the array must share the same underlying Three.js Texture object.
10
10
  */
11
11
  export declare class UIRenderingTexture extends UIRenderingModule {
@@ -1,35 +1,11 @@
1
1
  import { UITextureView } from "../../core/miscellaneous/texture/UITextureView.js";
2
- import source from "../shaders/UIRenderingTexture.js";
2
+ import { buildMultiTextureSource, textureSource } from "../shaders/UIRenderingTexture.js";
3
3
  import { UIRenderingModule } from "./UIRenderingModule.js";
4
- function buildMultiTextureShader(count) {
5
- const branches = [];
6
- for (let i = 0; i < count; i++) {
7
- if (i === 0) {
8
- branches.push(` if (idx == 0) t = p_textureTransform0;`);
9
- }
10
- else if (i === count - 1) {
11
- branches.push(` else t = p_textureTransform${i};`);
12
- }
13
- else {
14
- branches.push(` else if (idx == ${i}) t = p_textureTransform${i};`);
15
- }
16
- }
17
- return [
18
- "vec4 draw() {",
19
- // Clamped: at mediump precision a value just below 1 can round up to 1
20
- ` int idx = int(min(PARTICLE_RANDOM_A * ${count}.0, ${count}.0 - 0.5));`,
21
- " mat3 t;",
22
- ...branches,
23
- " vec2 transformedUV = (t * vec3(p_uv, 1.0)).xy;",
24
- " return srgbTexture2D(p_texture, transformedUV);",
25
- "}",
26
- ].join("\n");
27
- }
28
4
  /**
29
5
  * Renders particles with a texture.
30
6
  *
31
7
  * Accepts a single texture config or an array of configs from the same atlas.
32
- * When an array is provided, each particle picks one texture randomly using PARTICLE_RANDOM_A.
8
+ * When an array is provided, each particle picks one texture randomly using PARTICLE_RANDOM.
33
9
  * All configs in the array must share the same underlying Three.js Texture object.
34
10
  */
35
11
  export class UIRenderingTexture extends UIRenderingModule {
@@ -40,7 +16,7 @@ export class UIRenderingTexture extends UIRenderingModule {
40
16
  super();
41
17
  if (!Array.isArray(config) || config.length === 1) {
42
18
  const view = new UITextureView(Array.isArray(config) ? config[0] : config);
43
- this.source = source;
19
+ this.source = textureSource;
44
20
  this.requiredUniforms = {
45
21
  texture: view.texture,
46
22
  textureTransform: view.calculateUVTransform(),
@@ -63,6 +39,6 @@ export class UIRenderingTexture extends UIRenderingModule {
63
39
  }
64
40
  this.requiredProperties = { builtin: "Matrix4" };
65
41
  this.requiredUniforms = uniforms;
66
- this.source = buildMultiTextureShader(views.length);
42
+ this.source = buildMultiTextureSource(views.length);
67
43
  }
68
44
  }
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Source of a flipbook: `frameExpression` gives the frame number as a whole float in
3
+ * [0, frameCount), frames read row by row from the top left of the sheet
4
+ */
5
+ export declare function buildFlipbookSource(frameExpression: string, columns: number, rows: number): string;
@@ -0,0 +1,19 @@
1
+ import { toGLSLFloat } from "../miscellaneous/miscellaneous.js";
2
+ /**
3
+ * Source of a flipbook: `frameExpression` gives the frame number as a whole float in
4
+ * [0, frameCount), frames read row by row from the top left of the sheet
5
+ */
6
+ export function buildFlipbookSource(frameExpression, columns, rows) {
7
+ const columnCount = toGLSLFloat(columns);
8
+ const rowCount = toGLSLFloat(rows);
9
+ return `
10
+ vec4 draw() {
11
+ float frame = ${frameExpression};
12
+ // Offset by half a frame, so that floor does not drop a whole quotient computed just below it
13
+ float row = floor((frame + 0.5) / ${columnCount});
14
+ float column = frame - row * ${columnCount};
15
+ vec2 cellUV = (vec2(column, ${rowCount} - 1.0 - row) + p_uv) / vec2(${columnCount}, ${rowCount});
16
+ return srgbTexture2D(p_texture, (p_textureTransform * vec3(cellUV, 1.0)).xy);
17
+ }
18
+ `;
19
+ }
@@ -0,0 +1,2 @@
1
+ /** Source that reads one texel of a palette texture by `PARTICLE_RANDOM` */
2
+ export declare function buildRandomColorSource(paletteSize: number): string;
@@ -0,0 +1,10 @@
1
+ import { buildIndexExpression, toGLSLFloat } from "../miscellaneous/miscellaneous.js";
2
+ /** Source that reads one texel of a palette texture by `PARTICLE_RANDOM` */
3
+ export function buildRandomColorSource(paletteSize) {
4
+ return `
5
+ vec4 draw() {
6
+ float index = ${buildIndexExpression("PARTICLE_RANDOM", paletteSize)};
7
+ return srgbTexture2D(p_paletteTexture, vec2((index + 0.5) / ${toGLSLFloat(paletteSize)}, 0.5));
8
+ }
9
+ `;
10
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Source of a white shape whose alpha falls off over `softness` of its edge distance
3
+ * @param distanceExpression GLSL expression of the distance in the quad point `p`, from -1 to 1:
4
+ * below 1 inside the shape, 1 on its edge
5
+ */
6
+ export declare function buildShapeSource(distanceExpression: string, softness: number): string;
@@ -0,0 +1,15 @@
1
+ import { toGLSLFloat } from "../miscellaneous/miscellaneous.js";
2
+ /**
3
+ * Source of a white shape whose alpha falls off over `softness` of its edge distance
4
+ * @param distanceExpression GLSL expression of the distance in the quad point `p`, from -1 to 1:
5
+ * below 1 inside the shape, 1 on its edge
6
+ */
7
+ export function buildShapeSource(distanceExpression, softness) {
8
+ return `
9
+ vec4 draw() {
10
+ vec2 p = p_uv * 2.0 - 1.0;
11
+ float shapeDistance = ${distanceExpression};
12
+ return vec4(1.0, 1.0, 1.0, 1.0 - smoothstep(${toGLSLFloat(1 - softness)}, 1.0, shapeDistance));
13
+ }
14
+ `;
15
+ }
@@ -1,2 +1,4 @@
1
- declare const source: string;
2
- export default source;
1
+ /** Source that draws one texture region */
2
+ export declare const textureSource = "\nvec4 draw() {\n vec2 transformedUV = (p_textureTransform * vec3(p_uv, 1.0)).xy;\n return srgbTexture2D(p_texture, transformedUV);\n}\n";
3
+ /** Source that draws one of `count` regions of a texture, picked by `PARTICLE_RANDOM` */
4
+ export declare function buildMultiTextureSource(count: number): string;
@@ -1,7 +1,32 @@
1
- const source = `
1
+ import { buildIndexExpression } from "../miscellaneous/miscellaneous.js";
2
+ /** Source that draws one texture region */
3
+ export const textureSource = `
2
4
  vec4 draw() {
3
5
  vec2 transformedUV = (p_textureTransform * vec3(p_uv, 1.0)).xy;
4
6
  return srgbTexture2D(p_texture, transformedUV);
5
7
  }
6
8
  `;
7
- export default source;
9
+ /** Source that draws one of `count` regions of a texture, picked by `PARTICLE_RANDOM` */
10
+ export function buildMultiTextureSource(count) {
11
+ const branches = [];
12
+ for (let i = 0; i < count; i++) {
13
+ if (i === 0) {
14
+ branches.push(` if (idx == 0) t = p_textureTransform0;`);
15
+ }
16
+ else if (i === count - 1) {
17
+ branches.push(` else t = p_textureTransform${i};`);
18
+ }
19
+ else {
20
+ branches.push(` else if (idx == ${i}) t = p_textureTransform${i};`);
21
+ }
22
+ }
23
+ return [
24
+ "vec4 draw() {",
25
+ ` int idx = int(${buildIndexExpression("PARTICLE_RANDOM", count)});`,
26
+ " mat3 t;",
27
+ ...branches,
28
+ " vec2 transformedUV = (t * vec3(p_uv, 1.0)).xy;",
29
+ " return srgbTexture2D(p_texture, transformedUV);",
30
+ "}",
31
+ ].join("\n");
32
+ }