import { Text as TroikaText } from 'troika-three-text'; import { ContextManager, Observable } from '@zcomponent/core'; import * as THREE from 'three'; import { Mesh } from '../meshes/Mesh'; export interface TextConstructorProps { material?: THREE.Material; /** @zprop * URL of a custom font to be used. Font files can be in .ttf, .otf, or .woff (not .woff2) formats. * Defaults to the Roboto font loaded from Google Fonts. * @zvalues files *.+(ttf|otf|woff) */ font: string; /** * To avoid long pauses when first displaying a piece of text in your scene, * you can preload fonts and optionally pre-generate the SDF textures for particular glyphs up front. * @zprop * @zdefault 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.,!?-+/():;%&`\'*#=[]" ' */ characters: string; } export declare enum Unit { 'number' = "number", '%' = "%" } export declare enum TextAlign { Left = "left", Center = "center", Right = "right" } export declare enum OverflowWrap { Normal = "normal", BreakWord = "break-word" } export declare enum WhiteSpace { Normal = "normal", Nowrap = "nowrap" } export declare enum Direction { Auto = "auto", LTF = "ltf", RTL = "rtl" } /** * * Root element: [Troika Text](https://protectwise.github.io/troika/troika-three-text/#text) * @zcomponent * @zicon abc * @ztag three/Object3D/Mesh/Text * @zparents three/Object3D/Group/** */ export declare class Text extends Mesh { element: TroikaText; private _characters; /** * @zprop * @zgroup Text * @ztype text-multiline * @zgrouppriority 21 * @zdefault ... */ text: Observable; /** * Defines the horizontal position in the text block that should line up with the local origin. * Can be specified as a numeric x position in local units, a string percentage of the total * text block width e.g. `'25%'`, or one of the following keyword strings: 'left', 'center', * or 'right'. * @zprop * @zdefault 0 * @zgroup Advanced * @zgrouppriority 20 */ anchorX: Observable; /** * Defines the vertical position in the text block that should line up with the local origin. * Can be specified as a numeric y position in local units (note: down is negative y), a string * percentage of the total text block height e.g. `'25%'`, or one of the following keyword strings: * 'top', 'top-baseline', 'top-cap', 'top-ex', 'middle', 'bottom-baseline', or 'bottom'. * @zprop * @zdefault 0 * @zgroup Advanced * @zgrouppriority 20 */ anchorY: Observable; /** * Defines a cylindrical radius along which the text's plane will be curved. Positive numbers put * the cylinder's centerline (oriented vertically) that distance in front of the text, for a concave * curvature, while negative numbers put it behind the text for a convex curvature. The centerline * will be aligned with the text's local origin; you can use `anchorX` to offset it. * * Since each glyph is by default rendered with a simple quad, each glyph remains a flat plane * internally. You can use `glyphGeometryDetail` to add more vertices for curvature inside glyphs. * @zprop * @zdefault 0 * @zgroup Advanced * @zgrouppriority 20 */ curveRadius: Observable; /** * Sets the base direction for the text. The default value of "auto" will choose a direction based * on the text's content according to the bidi spec. A value of "ltr" or "rtl" will force the direction. * @zprop * @zdefault auto * @zgroup Advanced * @zgrouppriority 21 */ direction: Observable; /** * The size at which to render the font in local units; corresponds to the em-box height * of the chosen `font`. * @zprop * @zdefault 0.1 * @zgroup Text * @zgrouppriority 20 */ fontSize: Observable; /** * Sets a uniform adjustment to spacing between letters after kerning is applied. Positive * numbers increase spacing and negative numbers decrease it. * @zprop * @zdefault 0 * @zgroup Advanced * @zgrouppriority 20 */ letterSpacing: Observable; /** * Sets the height of each line of text, as a multiple of the `fontSize`. Defaults to 'normal' (0) * which chooses a reasonable height based on the chosen font's ascender/descender metrics. * @zprop * @zdefault 0 * @zgroup Advanced * @zgrouppriority 20 */ lineHeight: Observable; /** * The maximum width of the text block, above which text may start wrapping according to the * `whiteSpace` and `overflowWrap` properties. * @zprop * @zdefault Infinity * @zgroup Advanced * @zgrouppriority 20 */ maxWidth: Observable; /** * Defines how text wraps if the `whiteSpace` property is `normal`. Can be either `'normal'` * to break at whitespace characters, or `'break-word'` to allow breaking within words. * Defaults to `'normal'`. * @zprop * @zdefault normal * @zgroup Advanced * @zgrouppriority 20 */ overflowWrap: Observable; /** * The horizontal alignment of each line of text within the overall text bounding box. * @zprop * @zdefault left * @zgroup Advanced * @zgrouppriority 20 */ textAlign: Observable; /** * Indentation for the first character of a line; see CSS `text-indent`. * @zprop * @zdefault 0 * @zgroup Advanced * @zgrouppriority 20 */ textIndent: Observable; /** * Defines whether text should wrap when a line reaches the `maxWidth`. Can * be either `'normal'` (the default), to allow wrapping according to the `overflowWrap` property, * or `'nowrap'` to prevent wrapping. Note that `'normal'` here honors newline characters to * manually break lines, making it behave more like `'pre-wrap'` does in CSS. * @zprop * @zdefault normal * @zgroup Advanced * @zgrouppriority 20 */ whiteSpace: Observable; /** @zprop * This is a shortcut for setting the `color` of the text's material. You can use this * if you don't want to specify a whole custom `material`. Also, if you do use a custom * `material`, this color will only be used for this particuar Text instance, even if * that same material instance is shared across multiple Text objects. * @zgroup Text * @ztype color-norm-rgb-linear * @zdefault [0, 0, 0] * @zgrouppriority 20 */ color: Observable<[number, number, number], never>; /** @zprop * WARNING: This API is experimental and may change. * The width of an outline/halo to be drawn around each text glyph using the `outlineColor` and `outlineOpacity`. * Can be specified as either an absolute number in local units, or as a percentage string e.g. * `"12%"` which is treated as a percentage of the `fontSize`. Defaults to `0`, which means * no outline will be drawn unless an `outlineOffsetX/Y` or `outlineBlur` is set. * @zgroup Advanced * @zdefault [0, "number"] * @zgrouppriority 20 */ outlineWidth: Observable<[value: number, unit: Unit], never>; /** @zprop * WARNING: This API is experimental and may change. * The color of the text stroke, if `strokeWidth` is greater than zero. Defaults to gray. * @zgroup Advanced * @zgrouppriority 20 * @ztype color-norm-rgb-linear * @zdefault [0, 0, 0] */ outlineColor: Observable<[number, number, number], never>; /** @zprop * WARNING: This API is experimental and may change. * The opacity of the outline, if `outlineWidth`/`outlineBlur`/`outlineOffsetX/Y` are set. * Defaults to `1`. * @ztype proportion * @zdefault 1 * @zgroup Advanced * @zgrouppriority 20 */ outlineOpacity: Observable; /** @zprop * WARNING: This API is experimental and may change. * A blur radius applied to the outer edge of the text's outline. If the `outlineWidth` is * zero, the blur will be applied at the glyph edge, like CSS's `text-shadow` blur radius. * Can be specified as either an absolute number in local units, or as a percentage string e.g. * `"12%"` which is treated as a percentage of the `fontSize`. Defaults to `0`. * @zgroup Advanced * @zdefault [0, "number"] * @zgrouppriority 20 */ outlineBlur: Observable<[value: number, unit: Unit], never>; /** @zprop * WARNING: This API is experimental and may change. * A horizontal offset for the text outline. * Can be specified as either an absolute number in local units, or as a percentage string e.g. `"12%"` * which is treated as a percentage of the `fontSize`. Defaults to `0`. * @zgroup Advanced * @zdefault [0, "number"] * @zgrouppriority 20 */ outlineOffsetX: Observable<[value: number, unit: Unit], never>; /** @zprop * WARNING: This API is experimental and may change. * A vertical offset for the text outline. * Can be specified as either an absolute number in local units, or as a percentage string e.g. `"12%"` * which is treated as a percentage of the `fontSize`. Defaults to `0`. * @zgroup Advanced * @zdefault [0, "number"] * @zgrouppriority 20 */ outlineOffsetY: Observable<[value: number, unit: Unit], never>; /** @zprop * WARNING: This API is experimental and may change. * The width of an inner stroke drawn inside each text glyph using the `strokeColor` and `strokeOpacity`. * Can be specified as either an absolute number in local units, or as a percentage string e.g. `"12%"` * which is treated as a percentage of the `fontSize`. Defaults to `0`. * @zgroup Advanced * @zdefault [0, "number"] * @zgrouppriority 20 */ strokeWidth: Observable<[value: number, unit: Unit], never>; /** @zprop * WARNING: This API is experimental and may change. * The color of the text stroke, if `strokeWidth` is greater than zero. Defaults to gray. * @zgroup Advanced * @zgrouppriority 20 * @ztype color-norm-rgb-linear * @zdefault [0.8, 0.8, 0.8] */ strokeColor: Observable<[number, number, number], never>; /** * WARNING: This API is experimental and may change. * The opacity of the stroke, if `strokeWidth` is greater than zero. Defaults to `1`. * @zprop * @ztype proportion * @zdefault 1 * @zgroup Advanced * @zgrouppriority 20 */ strokeOpacity: Observable; /** * WARNING: This API is experimental and may change. * The opacity of the glyph's fill from 0 to 1. This behaves like the material's `opacity` but allows * giving the fill a different opacity than the `strokeOpacity`. A fillOpacity of `0` makes the * interior of the glyph invisible, leaving just the `strokeWidth`. Defaults to `1`. * @zprop * @zgroup Advanced * @zgrouppriority 20 * @ztype proportion * @zdefault 1 */ fillOpacity: Observable; /** * This is a shortcut for setting the material's `polygonOffset` and related properties, * which can be useful in preventing z-fighting when this text is laid on top of another * plane in the scene. Positive numbers are further from the camera, negatives closer. * @zprop * @zdefault 0 * @zgroup Advanced * @zgrouppriority 20 */ depthOffset: Observable; /** * If specified, defines a `[minX, minY, maxX, maxY]` of a rectangle outside of which all * pixels will be discarded. This can be used for example to clip overflowing text when * @zprop * @zdefault [ -100, -100, 100, 100] * @zgroup Advanced * @zgrouppriority 20 */ clipRect: Observable<[minX: number, minY: number, maxX: number, maxY: number], never>; /** * Defines the axis plane on which the text should be laid out when the mesh has no extra * rotation transform. It is specified as a string with two axes: the horizontal axis with * positive pointing right, and the vertical axis with positive pointing up. By default this * is '+x+y', meaning the text sits on the xy plane with the text's top toward positive y * and facing positive z. A value of '+x-z' would place it on the xz plane with the text's * top toward negative z and facing positive y. * @zprop * @zdefault '+x+y' * @zgroup Advanced * @zgrouppriority 20 */ orientation: Observable; /** * Controls number of vertical/horizontal segments that make up each glyph's rectangular * plane. Defaults to 1. This can be increased to provide more geometrical detail for custom * vertex shader effects, for example. * @zprop * @zdefault 1 * @zgroup Advanced * @zgrouppriority 20 */ glyphGeometryDetail: Observable; /** * The size of each glyph's SDF (signed distance field) used for rendering. This must be a * power-of-two number. Defaults to 64 which is generally a good balance of size and quality * for most fonts. Larger sizes can improve the quality of glyph rendering by increasing * the sharpness of corners and preventing loss of very thin lines, at the expense of * increased memory footprint and longer SDF generation time. * @zprop * @zdefault 64 * @zgroup Advanced * @zgrouppriority 20 */ sdfGlyphSize: Observable; /** * When `true`, the SDF generation process will be GPU-accelerated with WebGL when possible, * making it much faster especially for complex glyphs, and falling back to a JavaScript version * executed in web workers when support isn't available. It should automatically detect support, * but it's still somewhat experimental, so you can set it to `false` to force it to use the JS * version if you encounter issues with it. * @zprop * @zdefault true * @zgroup Advanced * @zgrouppriority 20 */ gpuAccelerateSDF: Observable; /** * @zprop * @zdefault false * @zgroup Advanced * @zgrouppriority 20 */ debugSDF: Observable; /** * A shortcut for setting the material's `side` property. If `true`, the text will be visible * from both sides of the mesh. Defaults to `false`. * If the text element has a custom material, this property will have no effect. * @zprop * @zdefault false * @zgroup Advanced * @zgrouppriority 20 */ doubleSide: Observable; constructor(contextManager: ContextManager, props: TextConstructorProps); private _load; dispose: () => never; }