Text
new Text()High-quality SDF-based text rendering with GPU-accelerated glyph generation.
Architecture
- Multi-channel SDF (Signed Distance Field) atlas for sharp text at any scale
- Dynamic glyph packing and layout via
troika-three-text - TSL node-based material for advanced effects (outlines, fills)
- Async
sync()generates glyphs on-demand with automatic atlas management
Features
- Crisp text rendering at any distance/angle
- Fill and outline with independent colors/opacity
- Text alignment, wrapping, and layout control
- Custom positioning/coloring via TSL node hooks
- Efficient instancing for many text instances via
BatchedText
Events
syncstart: Fired when layout/atlas generation beginssynccomplete: Fired when geometry and material are ready
Example
import { Text, textLetterId } from '@three-blocks/core';
import { sin, positionLocal, Fn } from 'three/tsl';
const text = new Text();
text.text = 'Hello Three Blocks!';
text.fontSize = 0.5;
text.color = 0x00ff00;
text.anchorX = 'center';
text.anchorY = 'middle';
// Optional outline
text.outlineWidth = '5%';
text.outlineColor = 0x000000;
scene.add(text);
// Custom TSL position hook using standard NodeMaterial API
text.material.positionNode = Fn(() => {
const pos = positionLocal.toVar();
pos.y.addAssign(sin(textLetterId.mul(10)).mul(0.1));
return pos;
})();
Properties
# .textRenderInfo : Object|null
Get the computed text layout and SDF atlas information.
# .billboarding : boolean
Enable yaw-only billboarding so text always faces the camera. When enabled, text rotates around the Y-axis to face the camera while remaining upright.
# .glyphGeometryDetail : number
Geometry tessellation detail level (1-3).
Methods
sync#
sync(callback : function, renderer : THREE.WebGPURenderer)Trigger asynchronous glyph layout and SDF atlas generation. Called automatically before render if text properties changed.
Parameters
callbackoptionalfunctionCalled when sync completes.
rendereroptionalTHREE.WebGPURendererRenderer for GPU SDF generation.
onBeforeRender#
onBeforeRender(renderer : THREE.WebGPURenderer, scene : THREE.Scene, camera : THREE.Camera, geometry : THREE.BufferGeometry, material : THREE.Material)Pre-render hook: ensures text is synced and material configured.
Parameters
rendererTHREE.WebGPURenderersceneTHREE.ScenecameraTHREE.CamerageometryTHREE.BufferGeometrymaterialTHREE.MaterialonAfterRender#
onAfterRender(renderer : THREE.WebGPURenderer, scene : THREE.Scene, camera : THREE.Camera, geometry : THREE.BufferGeometry, material : THREE.Material)Post-render hook: restores material side setting.
Parameters
rendererTHREE.WebGPURenderersceneTHREE.ScenecameraTHREE.CamerageometryTHREE.BufferGeometrymaterialTHREE.Materialdispose#
dispose()Dispose of geometry resources.