laymur 0.1.73 → 0.2.1

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 (90) hide show
  1. package/README.md +367 -0
  2. package/dist/builders/UIConstraint2DBuilder.d.ts +130 -0
  3. package/dist/composer/UIComposer.d.ts +0 -0
  4. package/dist/composer/UIFullscreenQuad.d.ts +0 -0
  5. package/dist/composer/UIPass.d.ts +0 -0
  6. package/dist/constraints/UIAspectConstraint.d.ts +60 -0
  7. package/dist/constraints/UIConstraint.d.ts +29 -0
  8. package/dist/constraints/UICoverConstraint.d.ts +0 -0
  9. package/dist/constraints/UICustomConstraint.d.ts +60 -0
  10. package/dist/constraints/UIFitConstraint.d.ts +0 -0
  11. package/dist/constraints/UIHeightConstraint.d.ts +49 -0
  12. package/dist/constraints/UIHorizontalDistanceConstraint.d.ts +94 -0
  13. package/dist/constraints/UIHorizontalProportionConstraint.d.ts +67 -0
  14. package/dist/constraints/UISingleParameterConstraint.d.ts +108 -0
  15. package/dist/constraints/UIVerticalDistanceConstraint.d.ts +94 -0
  16. package/dist/constraints/UIVerticalProportionConstraint.d.ts +67 -0
  17. package/dist/constraints/UIWidthConstraint.d.ts +49 -0
  18. package/dist/elements/UIAnchor.d.ts +78 -0
  19. package/dist/elements/UIDummy.d.ts +72 -0
  20. package/dist/elements/UIElement.d.ts +121 -0
  21. package/dist/elements/UIImage.d.ts +88 -0
  22. package/dist/elements/UINineSline.d.ts +0 -0
  23. package/dist/elements/UIProgress.d.ts +39 -0
  24. package/dist/elements/UIScene.d.ts +199 -0
  25. package/dist/elements/UIText.d.ts +157 -0
  26. package/dist/index.d.ts +29 -31
  27. package/dist/index.js +3320 -3251
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.min.js +1 -1
  30. package/dist/index.min.js.map +1 -1
  31. package/dist/layers/UIFullscreenLayer.d.ts +112 -0
  32. package/dist/layers/UILayer.d.ts +144 -0
  33. package/dist/materials/UIInstancedMaterial.d.ts +0 -0
  34. package/dist/materials/UIMaterial.d.ts +13 -0
  35. package/dist/materials/UINineSliceMaterial.d.ts +0 -0
  36. package/dist/{Materials → materials}/UIProgressMaterial.d.ts +0 -4
  37. package/dist/miscellaneous/UIExpression.d.ts +117 -0
  38. package/dist/miscellaneous/UIMicro.d.ts +130 -0
  39. package/dist/{Miscellaneous → miscellaneous}/UIOrientation.d.ts +2 -9
  40. package/dist/miscellaneous/UIPriority.d.ts +56 -0
  41. package/dist/miscellaneous/UIRelation.d.ts +43 -0
  42. package/dist/miscellaneous/UITextPadding.d.ts +7 -0
  43. package/dist/miscellaneous/UITextSpan.d.ts +6 -0
  44. package/dist/miscellaneous/UITextStyle.d.ts +18 -0
  45. package/dist/miscellaneous/asserts.d.ts +112 -0
  46. package/dist/miscellaneous/textInterfaces.d.ts +19 -0
  47. package/dist/miscellaneous/textTools.d.ts +12 -0
  48. package/dist/scalable/UIScalableMesh.d.ts +16 -0
  49. package/dist/scalable/UIScalablePlaneMesh.d.ts +14 -0
  50. package/dist/wrappers/UISceneWrapper.d.ts +18 -0
  51. package/dist/wrappers/UISolverWrapper.d.ts +29 -0
  52. package/package.json +3 -3
  53. package/dist/Builders/UIConstraint2DBuilder.d.ts +0 -42
  54. package/dist/Builders/UIConstraintContainerBuilder.d.ts +0 -20
  55. package/dist/Builders/UIConstraintStackBuilder.d.ts +0 -24
  56. package/dist/Constraints/UIAspectConstraint.d.ts +0 -56
  57. package/dist/Constraints/UIConstraint.d.ts +0 -32
  58. package/dist/Constraints/UIConstraintPower.d.ts +0 -57
  59. package/dist/Constraints/UIConstraintRule.d.ts +0 -46
  60. package/dist/Constraints/UICoverConstraint.d.ts +0 -72
  61. package/dist/Constraints/UIFitConstraint.d.ts +0 -72
  62. package/dist/Constraints/UIHeightConstraint.d.ts +0 -55
  63. package/dist/Constraints/UIHorizontalDistanceConstraint.d.ts +0 -63
  64. package/dist/Constraints/UIHorizontalProportionConstraint.d.ts +0 -58
  65. package/dist/Constraints/UIVerticalDistanceConstraint.d.ts +0 -63
  66. package/dist/Constraints/UIVerticalProportionConstraint.d.ts +0 -58
  67. package/dist/Constraints/UIWidthConstraint.d.ts +0 -55
  68. package/dist/Elements/UIAnchor.d.ts +0 -66
  69. package/dist/Elements/UIDummy.d.ts +0 -21
  70. package/dist/Elements/UIElement.d.ts +0 -134
  71. package/dist/Elements/UIImage.d.ts +0 -57
  72. package/dist/Elements/UIProgress.d.ts +0 -127
  73. package/dist/Elements/UIScene.d.ts +0 -141
  74. package/dist/Elements/UIText.d.ts +0 -76
  75. package/dist/Layers/UIFullScreenLayer.d.ts +0 -13
  76. package/dist/Layers/UILayer.d.ts +0 -68
  77. package/dist/Materials/UIMaterial.d.ts +0 -13
  78. package/dist/Miscellaneous/UIBlending.d.ts +0 -7
  79. package/dist/Miscellaneous/UIMicro.d.ts +0 -176
  80. package/dist/Miscellaneous/UITextInterfaces.d.ts +0 -49
  81. package/dist/Miscellaneous/asserts.d.ts +0 -5
  82. package/dist/Miscellaneous/math.d.ts +0 -1
  83. package/dist/Miscellaneous/microTransformationTools.d.ts +0 -3
  84. package/dist/Miscellaneous/symbols.d.ts +0 -1
  85. package/dist/Miscellaneous/textTools.d.ts +0 -9
  86. package/dist/Passes/UIComposer.d.ts +0 -114
  87. package/dist/Passes/UIFullScreenQuad.d.ts +0 -51
  88. package/dist/Passes/UIPass.d.ts +0 -43
  89. /package/dist/{Miscellaneous → miscellaneous}/UIMode.d.ts +0 -0
  90. /package/dist/{Miscellaneous → miscellaneous}/threeInstances.d.ts +0 -0
@@ -0,0 +1,72 @@
1
+ import type { UILayer } from "../layers/UILayer";
2
+ import { type UIPlaneElement } from "../miscellaneous/asserts";
3
+ import { UIAnchor } from "./UIAnchor";
4
+ /**
5
+ * Abstract UI element that extends UIAnchor with dimensions but without rendering.
6
+ *
7
+ * UIDummy represents a rectangular area in the UI layout system that has position
8
+ * and dimensions (width and height) but does not perform any visual rendering.
9
+ * It serves as a placeholder or spacer element in constraint-based layouts,
10
+ * useful for defining layout structure without visual content.
11
+ *
12
+ * @see {@link UIAnchor} - Base class providing position functionality
13
+ * @see {@link UIPlaneElement} - Interface defining dimensional element behavior
14
+ * @see {@link UILayer} - Container layer for UI elements
15
+ */
16
+ export declare abstract class UIDummy extends UIAnchor implements UIPlaneElement {
17
+ /**
18
+ * Solver variable descriptor for the width dimension.
19
+ * This variable is managed by the constraint solver system.
20
+ */
21
+ readonly wVariable: number;
22
+ /**
23
+ * Solver variable descriptor for the height dimension.
24
+ * This variable is managed by the constraint solver system.
25
+ */
26
+ readonly hVariable: number;
27
+ /**
28
+ * Creates a new UIDummy instance with position and dimensions.
29
+ *
30
+ * @param layer - The UI layer that contains this dummy element
31
+ * @param x - Initial x-coordinate position
32
+ * @param y - Initial y-coordinate position
33
+ * @param width - Initial width dimension (defaults to 100)
34
+ * @param height - Initial height dimension (defaults to 100)
35
+ * @throws Will throw an error if width or height are not valid positive numbers
36
+ * @see {@link assertValidPositiveNumber}
37
+ */
38
+ constructor(layer: UILayer, x: number, y: number, width?: number, height?: number);
39
+ /**
40
+ * Gets the current width value from the solver.
41
+ * @returns The current width dimension
42
+ */
43
+ get width(): number;
44
+ /**
45
+ * Gets the current height value from the solver.
46
+ * @returns The current height dimension
47
+ */
48
+ get height(): number;
49
+ /**
50
+ * Sets the width value through the solver system.
51
+ * @param value - The new width dimension (must be positive)
52
+ * @throws Will throw an error if value is not a valid positive number
53
+ * @see {@link assertValidPositiveNumber}
54
+ */
55
+ set width(value: number);
56
+ /**
57
+ * Sets the height value through the solver system.
58
+ * @param value - The new height dimension (must be positive)
59
+ * @throws Will throw an error if value is not a valid positive number
60
+ * @see {@link assertValidPositiveNumber}
61
+ */
62
+ set height(value: number);
63
+ /**
64
+ * Destroys the dummy element by removing its solver variables.
65
+ *
66
+ * This method cleans up the dimension solver variables (width and height)
67
+ * associated with this dummy element, then calls the parent destroy method
68
+ * to clean up position variables. After calling this method, the dummy
69
+ * element should not be used anymore.
70
+ */
71
+ destroy(): void;
72
+ }
@@ -0,0 +1,121 @@
1
+ import { type Object3D } from "three";
2
+ import type { UILayer } from "../layers/UILayer";
3
+ import type { UIPlaneElement } from "../miscellaneous/asserts";
4
+ import { UIMicro } from "../miscellaneous/UIMicro";
5
+ import { UIMode } from "../miscellaneous/UIMode";
6
+ import type { UISceneWrapper } from "../wrappers/UISceneWrapper";
7
+ import { UIAnchor } from "./UIAnchor";
8
+ /**
9
+ * Events that can be emitted by UI elements.
10
+ */
11
+ export declare enum UIElementEvent {
12
+ /** Emitted when the element is clicked. */
13
+ CLICK = "click"
14
+ }
15
+ /**
16
+ * Abstract base class for all renderable UI elements with dimensions.
17
+ *
18
+ * UIElement serves as the fundamental building block for all other UI elements
19
+ * that need to be visually rendered. It extends UIAnchor with dimensional properties
20
+ * and integrates with the Three.js rendering system through Object3D. This class
21
+ * provides essential functionality for positioning, sizing, rendering, visibility,
22
+ * z-index management, and user interaction.
23
+ *
24
+ * @template T - The type of Three.js Object3D used for rendering
25
+ * @see {@link UIAnchor} - Base class providing position functionality
26
+ * @see {@link UIPlaneElement} - Interface defining dimensional element behavior
27
+ * @see {@link UISceneWrapper} - Scene management for rendering
28
+ * @see {@link UIMicro} - Micro-optimization utilities
29
+ */
30
+ export declare abstract class UIElement<T extends Object3D = Object3D> extends UIAnchor implements UIPlaneElement {
31
+ protected readonly object: T;
32
+ /** Micro-transformation system for non-constraint based positioning, scaling, and rotation adjustments. */
33
+ readonly micro: UIMicro;
34
+ /**
35
+ * Solver variable descriptor for the width dimension.
36
+ * This variable is managed by the constraint solver system.
37
+ */
38
+ readonly wVariable: number;
39
+ /**
40
+ * Solver variable descriptor for the height dimension.
41
+ * This variable is managed by the constraint solver system.
42
+ */
43
+ readonly hVariable: number;
44
+ /**
45
+ * Reference to the scene wrapper for rendering management.
46
+ * @see {@link UISceneWrapper}
47
+ */
48
+ protected readonly sceneWrapper: UISceneWrapper;
49
+ /** Internal storage for the current visibility/interaction mode. */
50
+ protected modeInternal: UIMode;
51
+ /**
52
+ * Creates a new UIElement instance with rendering capabilities.
53
+ *
54
+ * @param layer - The UI layer that contains this element
55
+ * @param x - Initial x-coordinate position
56
+ * @param y - Initial y-coordinate position
57
+ * @param width - Initial width dimension (must be positive)
58
+ * @param height - Initial height dimension (must be positive)
59
+ * @param object - The Three.js Object3D used for rendering this element
60
+ * @throws Will throw an error if width or height are not valid positive numbers
61
+ * @see {@link assertValidPositiveNumber}
62
+ */
63
+ constructor(layer: UILayer, x: number, y: number, width: number, height: number, object: T);
64
+ /**
65
+ * Gets the current width value from the solver.
66
+ * @returns The current width dimension
67
+ */
68
+ get width(): number;
69
+ /**
70
+ * Gets the current height value from the solver.
71
+ * @returns The current height dimension
72
+ */
73
+ get height(): number;
74
+ /**
75
+ * Gets the current z-index (depth) value from the scene.
76
+ * @returns The current z-index for rendering order
77
+ */
78
+ get zIndex(): number;
79
+ /**
80
+ * Gets the current visibility and interaction mode.
81
+ * @returns The current UIMode setting
82
+ * @see {@link UIMode}
83
+ */
84
+ get mode(): UIMode;
85
+ /**
86
+ * Sets the width value through the solver system.
87
+ * @param value - The new width dimension (must be positive)
88
+ * @throws Will throw an error if value is not a valid positive number
89
+ * @see {@link assertValidPositiveNumber}
90
+ */
91
+ set width(value: number);
92
+ /**
93
+ * Sets the height value through the solver system.
94
+ * @param value - The new height dimension (must be positive)
95
+ * @throws Will throw an error if value is not a valid positive number
96
+ * @see {@link assertValidPositiveNumber}
97
+ */
98
+ set height(value: number);
99
+ /**
100
+ * Sets the z-index (depth) value for rendering order.
101
+ * @param value - The new z-index value
102
+ * @throws Will throw an error if value is not a valid number
103
+ * @see {@link assertValidNumber}
104
+ */
105
+ set zIndex(value: number);
106
+ /**
107
+ * Sets the visibility and interaction mode.
108
+ * @param value - The new UIMode setting
109
+ * @see {@link UIMode}
110
+ */
111
+ set mode(value: UIMode);
112
+ /**
113
+ * Destroys the UI element by cleaning up all associated resources.
114
+ *
115
+ * This method removes the element from the rendering scene, cleans up
116
+ * dimension solver variables, and calls the parent destroy method to
117
+ * clean up position variables. After calling this method, the element
118
+ * should not be used anymore.
119
+ */
120
+ destroy(): void;
121
+ }
@@ -0,0 +1,88 @@
1
+ import type { Texture } from "three";
2
+ import { Mesh } from "three";
3
+ import type { UILayer } from "../layers/UILayer";
4
+ import { UIElement } from "./UIElement";
5
+ /**
6
+ * UI element for displaying textured images.
7
+ *
8
+ * UIImage is a concrete implementation of UIElement that renders a textured
9
+ * image using Three.js Mesh and UIMaterial. It automatically sizes itself
10
+ * to match the texture dimensions and provides control over visual properties
11
+ * such as color tinting, opacity, and transparency.
12
+ *
13
+ * @see {@link UIElement} - Base class providing UI element functionality
14
+ * @see {@link UIMaterial} - Material system for rendering
15
+ * @see {@link Texture} - Three.js texture for image data
16
+ */
17
+ export declare class UIImage extends UIElement<Mesh> {
18
+ /** The material used for rendering the image. */
19
+ private readonly material;
20
+ /** Internal storage for the current texture. */
21
+ private readonly textureInternal;
22
+ /**
23
+ * Creates a new UIImage instance.
24
+ *
25
+ * The image will automatically size itself to match the texture's dimensions.
26
+ * The position defaults to (0, 0) if not specified.
27
+ *
28
+ * @param layer - The UI layer that contains this image
29
+ * @param texture - The Three.js texture to display
30
+ * @param x - Initial x-coordinate position (defaults to 0)
31
+ * @param y - Initial y-coordinate position (defaults to 0)
32
+ */
33
+ constructor(layer: UILayer, texture: Texture, x?: number, y?: number);
34
+ /**
35
+ * Gets the current texture being displayed.
36
+ * @returns The current Three.js texture
37
+ */
38
+ get texture(): Texture;
39
+ /**
40
+ * Gets the current color tint applied to the image.
41
+ * @returns The color value as a number (e.g., 0xFFFFFF for white)
42
+ */
43
+ get color(): number;
44
+ /**
45
+ * Gets the current opacity level of the image.
46
+ * @returns The opacity value between 0.0 (transparent) and 1.0 (opaque)
47
+ */
48
+ get opacity(): number;
49
+ /**
50
+ * Gets whether transparency is enabled for the image.
51
+ * @returns True if transparency is enabled, false otherwise
52
+ */
53
+ get transparency(): boolean;
54
+ /**
55
+ * Sets a new texture for the image.
56
+ *
57
+ * When setting a new texture, the image will automatically resize to match
58
+ * the new texture's dimensions.
59
+ *
60
+ * @param value - The new Three.js texture to display
61
+ * @throws Will throw an error if the texture dimensions are not valid positive numbers
62
+ * @see {@link assertValidPositiveNumber}
63
+ */
64
+ set texture(value: Texture);
65
+ /**
66
+ * Sets the color tint applied to the image.
67
+ * @param value - The color value as a number (e.g., 0xFFFFFF for white)
68
+ */
69
+ set color(value: number);
70
+ /**
71
+ * Sets the opacity level of the image.
72
+ * @param value - The opacity value between 0.0 (transparent) and 1.0 (opaque)
73
+ */
74
+ set opacity(value: number);
75
+ /**
76
+ * Sets whether transparency is enabled for the image.
77
+ * @param value - True to enable transparency, false to disable
78
+ */
79
+ set transparency(value: boolean);
80
+ /**
81
+ * Destroys the image by cleaning up all associated resources.
82
+ *
83
+ * This method disposes of the material resources and calls the parent
84
+ * destroy method to clean up the underlying UI element. After calling
85
+ * this method, the image should not be used anymore.
86
+ */
87
+ destroy(): void;
88
+ }
File without changes
@@ -0,0 +1,39 @@
1
+ import type { Texture } from "three";
2
+ import { Mesh } from "three";
3
+ import type { UILayer } from "../layers/UILayer";
4
+ import { UIElement } from "./UIElement";
5
+ export interface UIProgressOptions {
6
+ x: number;
7
+ y: number;
8
+ textureBackground: Texture;
9
+ progress: number;
10
+ isForegroundDirection: boolean;
11
+ angle: number;
12
+ backgroundColor: number;
13
+ foregroundColor: number;
14
+ backgroundOpacity: number;
15
+ foregroundOpacity: number;
16
+ }
17
+ export declare class UIProgress extends UIElement<Mesh> {
18
+ private readonly material;
19
+ constructor(layer: UILayer, textureForeground: Texture, options?: Partial<UIProgressOptions>);
20
+ get progress(): number;
21
+ get backgroundTexture(): Texture | undefined;
22
+ get foregroundTexture(): Texture;
23
+ get backgroundColor(): number;
24
+ get foregroundColor(): number;
25
+ get backgroundOpacity(): number;
26
+ get foregroundOpacity(): number;
27
+ get angle(): number;
28
+ get isForwardDirection(): boolean;
29
+ set progress(value: number);
30
+ set backgroundTexture(value: Texture | undefined);
31
+ set foregroundTexture(value: Texture);
32
+ set backgroundColor(value: number);
33
+ set foregroundColor(value: number);
34
+ set backgroundOpacity(value: number);
35
+ set foregroundOpacity(value: number);
36
+ set angle(value: number);
37
+ set isForwardDirection(value: boolean);
38
+ destroy(): void;
39
+ }
@@ -0,0 +1,199 @@
1
+ import type { Camera } from "three";
2
+ import { Mesh, Scene } from "three";
3
+ import type { UILayer } from "../layers/UILayer";
4
+ import { UIElement } from "./UIElement";
5
+ /**
6
+ * Update modes for controlling when the 3D scene should be re-rendered.
7
+ */
8
+ export declare enum UISceneUpdateMode {
9
+ /** Re-render the scene every frame. */
10
+ EACH_FRAME = 1,
11
+ /** Re-render the scene every second frame for performance. */
12
+ EACH_SECOND_FRAME = 2,
13
+ /** Re-render the scene only when properties change. */
14
+ PROPERTY_CHANGED = 3,
15
+ /** Re-render the scene only when manually requested. */
16
+ MANUAL = 4
17
+ }
18
+ /**
19
+ * Configuration options for UIScene element creation.
20
+ */
21
+ export interface UISceneOptions {
22
+ /** Initial x-coordinate position. */
23
+ x: number;
24
+ /** Initial y-coordinate position. */
25
+ y: number;
26
+ /** Width of the scene render target in pixels. */
27
+ width: number;
28
+ /** Height of the scene render target in pixels. */
29
+ height: number;
30
+ /** Three.js scene to render. */
31
+ scene: Scene;
32
+ /** Camera to use for rendering the scene. */
33
+ camera: Camera;
34
+ /** Update mode controlling when the scene is re-rendered. */
35
+ updateMode: UISceneUpdateMode;
36
+ /** Resolution factor for render target sizing (0.1 to 2.0). */
37
+ resolutionFactor: number;
38
+ /** Clear color for the render target background. */
39
+ clearColor: number;
40
+ /** Clear alpha for the render target background. */
41
+ clearAlpha: number;
42
+ /** Whether to enable depth buffer for the render target. */
43
+ enableDepthBuffer: boolean;
44
+ }
45
+ /**
46
+ * UI element for rendering 3D scenes to texture within the UI system.
47
+ *
48
+ * UIScene is a concrete implementation of UIElement that renders a Three.js
49
+ * scene to a WebGL render target and displays it as a texture. It provides
50
+ * control over rendering frequency, resolution, and visual properties. This
51
+ * allows embedding complex 3D content within the 2D UI layout system with
52
+ * performance optimizations through configurable update modes.
53
+ *
54
+ * @see {@link UIElement} - Base class providing UI element functionality
55
+ * @see {@link UISceneUpdateMode} - Update mode configuration
56
+ * @see {@link Scene} - Three.js scene for 3D content
57
+ * @see {@link Camera} - Three.js camera for scene rendering
58
+ */
59
+ export declare class UIScene extends UIElement<Mesh> {
60
+ /** The material used for rendering the scene texture. */
61
+ private readonly material;
62
+ /** The WebGL render target for off-screen scene rendering. */
63
+ private readonly renderTarget;
64
+ /** Internal storage for the current Three.js scene. */
65
+ private sceneInternal;
66
+ /** Internal storage for the current camera. */
67
+ private cameraInternal;
68
+ /** Internal storage for the current update mode. */
69
+ private updateModeInternal;
70
+ /** Internal storage for the current resolution factor. */
71
+ private resolutionFactorInternal;
72
+ /** Internal storage for the current clear color. */
73
+ private clearColorInternal;
74
+ /** Internal storage for the current clear alpha. */
75
+ private clearAlphaInternal;
76
+ /** Frame alternation boolean for EACH_SECOND_FRAME update mode. */
77
+ private frameBoolean;
78
+ /** Flag indicating if properties have changed requiring a re-render. */
79
+ private propertyChanged;
80
+ /** Flag indicating if a manual render has been requested. */
81
+ private renderRequired;
82
+ /**
83
+ * Creates a new UIScene instance with 3D scene rendering capabilities.
84
+ *
85
+ * The scene element creates a WebGL render target for off-screen rendering
86
+ * and displays the result as a texture. A default perspective camera is
87
+ * created if none is provided.
88
+ *
89
+ * @param layer - The UI layer that contains this scene element
90
+ * @param options - Configuration options for scene rendering
91
+ * @throws Will throw an error if resolution factor is outside valid range (0.1-2.0)
92
+ */
93
+ constructor(layer: UILayer, options?: Partial<UISceneOptions>);
94
+ /**
95
+ * Gets the current color tint applied to the scene texture.
96
+ * @returns The color value as a number (e.g., 0xFFFFFF for white)
97
+ */
98
+ get color(): number;
99
+ /**
100
+ * Gets the current opacity level of the scene texture.
101
+ * @returns The opacity value between 0.0 (transparent) and 1.0 (opaque)
102
+ */
103
+ get opacity(): number;
104
+ /**
105
+ * Gets whether transparency is enabled for the scene texture.
106
+ * @returns True if transparency is enabled, false otherwise
107
+ */
108
+ get transparency(): boolean;
109
+ /**
110
+ * Gets the Three.js scene being rendered.
111
+ * @returns The current Three.js scene
112
+ */
113
+ get scene(): Scene;
114
+ /**
115
+ * Gets the camera used for rendering the scene.
116
+ * @returns The current Three.js camera
117
+ */
118
+ get camera(): Camera;
119
+ /**
120
+ * Gets the current update mode controlling render frequency.
121
+ * @returns The current update mode
122
+ */
123
+ get updateMode(): UISceneUpdateMode;
124
+ /**
125
+ * Gets the resolution factor for render target sizing.
126
+ * @returns The resolution factor between 0.1 and 2.0
127
+ */
128
+ get resolutionFactor(): number;
129
+ /**
130
+ * Gets the clear color used for the render target background.
131
+ * @returns The clear color as a number
132
+ */
133
+ get clearColor(): number;
134
+ /**
135
+ * Gets the clear alpha used for the render target background.
136
+ * @returns The clear alpha value between 0.0 and 1.0
137
+ */
138
+ get clearAlpha(): number;
139
+ /**
140
+ * Sets the color tint applied to the scene texture.
141
+ * @param value - The color value as a number (e.g., 0xFFFFFF for white)
142
+ */
143
+ set color(value: number);
144
+ /**
145
+ * Sets the opacity level of the scene texture.
146
+ * @param value - The opacity value between 0.0 (transparent) and 1.0 (opaque)
147
+ */
148
+ set opacity(value: number);
149
+ /**
150
+ * Sets whether transparency is enabled for the scene texture.
151
+ * @param value - True to enable transparency, false to disable
152
+ */
153
+ set transparency(value: boolean);
154
+ /**
155
+ * Sets a new Three.js scene to render and marks for re-render.
156
+ * @param value - The new Three.js scene
157
+ */
158
+ set scene(value: Scene);
159
+ /**
160
+ * Sets a new camera for rendering and marks for re-render.
161
+ * @param value - The new Three.js camera
162
+ */
163
+ set camera(value: Camera);
164
+ /**
165
+ * Sets the update mode controlling render frequency and marks for re-render.
166
+ * @param value - The new update mode
167
+ */
168
+ set updateMode(value: UISceneUpdateMode);
169
+ /**
170
+ * Sets the resolution factor and resizes the render target accordingly.
171
+ * @param value - The new resolution factor between 0.1 and 2.0
172
+ */
173
+ set resolutionFactor(value: number);
174
+ /**
175
+ * Sets the clear color for the render target background and marks for re-render.
176
+ * @param value - The new clear color as a number
177
+ */
178
+ set clearColor(value: number);
179
+ /**
180
+ * Sets the clear alpha for the render target background and marks for re-render.
181
+ * @param value - The new clear alpha value between 0.0 and 1.0
182
+ */
183
+ set clearAlpha(value: number);
184
+ /**
185
+ * Destroys the scene element by cleaning up all associated resources.
186
+ *
187
+ * This method disposes of the material and render target resources,
188
+ * and calls the parent destroy method to clean up the underlying UI element.
189
+ * After calling this method, the scene element should not be used anymore.
190
+ */
191
+ destroy(): void;
192
+ /**
193
+ * Manually requests a re-render of the scene.
194
+ *
195
+ * This method is useful when the update mode is set to MANUAL and you
196
+ * want to trigger a scene re-render without changing any properties.
197
+ */
198
+ requestRender(): void;
199
+ }
@@ -0,0 +1,157 @@
1
+ import { Mesh } from "three";
2
+ import type { UILayer } from "../layers/UILayer";
3
+ import type { UITextContent } from "../miscellaneous/textInterfaces";
4
+ import { type UITextPadding } from "../miscellaneous/UITextPadding";
5
+ import { type UITextStyle } from "../miscellaneous/UITextStyle";
6
+ import { UIElement } from "./UIElement";
7
+ /**
8
+ * Configuration options for UIText element creation.
9
+ */
10
+ export interface UITextOptions {
11
+ /** Maximum width in pixels before text wrapping occurs. */
12
+ maxWidth: number;
13
+ /** Padding configuration for text content. */
14
+ padding: Partial<UITextPadding>;
15
+ /** Common style properties applied to all text content. */
16
+ commonStyle: Partial<UITextStyle>;
17
+ }
18
+ /**
19
+ * UI element for rendering dynamic text with canvas-based rendering.
20
+ *
21
+ * UIText is a concrete implementation of UIElement that renders text content
22
+ * using HTML5 Canvas and displays it as a texture. It supports rich text
23
+ * formatting, automatic text wrapping, padding, and dynamic resizing based
24
+ * on content. The text is rendered to a canvas texture which is then applied
25
+ * to a Three.js mesh for display in the 3D scene.
26
+ *
27
+ * @see {@link UIElement} - Base class providing UI element functionality
28
+ * @see {@link UITextContent} - Text content structure
29
+ * @see {@link UITextStyle} - Text styling options
30
+ * @see {@link UITextPadding} - Padding configuration
31
+ */
32
+ export declare class UIText extends UIElement<Mesh> {
33
+ /** The material used for rendering the text texture. */
34
+ private readonly material;
35
+ /** The canvas texture containing the rendered text. */
36
+ private readonly texture;
37
+ /** The HTML canvas element used for text rendering. */
38
+ private readonly canvas;
39
+ /** The 2D rendering context for drawing text on the canvas. */
40
+ private readonly context;
41
+ /** Internal storage for the current text content. */
42
+ private contentInternal;
43
+ /** Internal storage for the maximum width before text wrapping. */
44
+ private maxWidthInternal;
45
+ /** Internal storage for the current padding configuration. */
46
+ private paddingInternal;
47
+ /** Internal storage for the common text style properties. */
48
+ private commonStyleInternal;
49
+ /** Target aspect ratio for the text element based on content. */
50
+ private targetAspectRatio;
51
+ /** Last calculated aspect ratio for comparison during rendering. */
52
+ private lastAspectRatio;
53
+ /**
54
+ * Creates a new UIText instance with dynamic text rendering.
55
+ *
56
+ * The text element will automatically size itself based on the content
57
+ * and specified options. A canvas is created for rendering the text,
58
+ * which is then used as a texture for the 3D mesh.
59
+ *
60
+ * @param layer - The UI layer that contains this text element
61
+ * @param content - The text content to display
62
+ * @param options - Configuration options for text rendering
63
+ * @param x - Initial x-coordinate position (defaults to 0)
64
+ * @param y - Initial y-coordinate position (defaults to 0)
65
+ * @throws Will throw an error if canvas context creation fails
66
+ */
67
+ constructor(layer: UILayer, content: UITextContent, options?: Partial<UITextOptions>, x?: number, y?: number);
68
+ /**
69
+ * Gets the current color tint applied to the text.
70
+ * @returns The color value as a number (e.g., 0xFFFFFF for white)
71
+ */
72
+ get color(): number;
73
+ /**
74
+ * Gets the current opacity level of the text.
75
+ * @returns The opacity value between 0.0 (transparent) and 1.0 (opaque)
76
+ */
77
+ get opacity(): number;
78
+ /**
79
+ * Gets whether transparency is enabled for the text.
80
+ * @returns True if transparency is enabled, false otherwise
81
+ */
82
+ get transparency(): boolean;
83
+ /**
84
+ * Gets the current text content being displayed.
85
+ * @returns The current text content structure
86
+ */
87
+ get content(): UITextContent;
88
+ /**
89
+ * Gets the maximum width before text wrapping occurs.
90
+ * @returns The maximum width in pixels
91
+ */
92
+ get maxWidth(): number;
93
+ /**
94
+ * Gets the current padding configuration.
95
+ * @returns The padding configuration for all sides
96
+ */
97
+ get padding(): UITextPadding;
98
+ /**
99
+ * Gets the common style properties applied to the text.
100
+ * @returns The partial text style configuration
101
+ */
102
+ get commonStyle(): Partial<UITextStyle>;
103
+ /**
104
+ * Sets the color tint applied to the text.
105
+ * @param value - The color value as a number (e.g., 0xFFFFFF for white)
106
+ */
107
+ set color(value: number);
108
+ /**
109
+ * Sets the opacity level of the text.
110
+ * @param value - The opacity value between 0.0 (transparent) and 1.0 (opaque)
111
+ */
112
+ set opacity(value: number);
113
+ /**
114
+ * Sets whether transparency is enabled for the text.
115
+ * @param value - True to enable transparency, false to disable
116
+ */
117
+ set transparency(value: boolean);
118
+ /**
119
+ * Sets new text content and triggers a rebuild.
120
+ * @param value - The new text content structure
121
+ */
122
+ set content(value: UITextContent);
123
+ /**
124
+ * Sets the maximum width before text wrapping and triggers a rebuild.
125
+ * @param value - The new maximum width in pixels
126
+ */
127
+ set maxWidth(value: number);
128
+ /**
129
+ * Sets new padding configuration and triggers a rebuild.
130
+ * @param value - The new padding configuration
131
+ */
132
+ set padding(value: UITextPadding);
133
+ /**
134
+ * Sets new common style properties and triggers a rebuild.
135
+ * @param value - The new partial text style configuration
136
+ */
137
+ set commonStyle(value: Partial<UITextStyle>);
138
+ /**
139
+ * Destroys the text element by cleaning up all associated resources.
140
+ *
141
+ * This method disposes of the material and texture resources, removes
142
+ * the canvas element from the DOM, and calls the parent destroy method
143
+ * to clean up the underlying UI element. After calling this method,
144
+ * the text element should not be used anymore.
145
+ */
146
+ destroy(): void;
147
+ /**
148
+ * Rebuilds the text canvas and texture based on current content and settings.
149
+ *
150
+ * This method calculates the text layout, resizes the canvas to fit the content
151
+ * with padding, renders the text lines to the canvas, and updates the texture.
152
+ * It also calculates and sets the target aspect ratio for proper display.
153
+ *
154
+ * @private
155
+ */
156
+ private rebuildText;
157
+ }