WebGL Support has been temporarily disabled.

High-performance batched rendering for multiple Text instances with GPU-accelerated culling, sorting, and instancing. Renders thousands of text labels in a single draw call with automatic transparency sorting for correct z-ordering.

Why BatchedText is Fast

Single Draw Call Architecture

• Renders all text instances in ONE draw call vs N draw calls
• Eliminates CPU overhead from state changes and draw call submission
• Uses GPU instancing with StorageBufferAttribute for transforms and styles
• Shared SDF atlas texture across all text members

GPU Compute Pipeline (WebGPU)

• Frustum culling runs entirely on GPU via compute shaders
• LOD-based glyph sampling reduces overdraw for distant text
• Automatic back-to-front sorting for transparent SDF text in the GPU via bitonic sorting in compute shaders
• Indirect draw commands updated on GPU without CPU readback
• Dynamic workgroup dispatch via computeIndirect for efficient scaling

Transparency Z-Ordering

• Sorted glyph packing ensures correct depth ordering for SDF anti-aliasing
• Per-member prefix sum computes glyph offsets in sorted order
• Glyphs scattered to packed buffer preserving back-to-front order
• Eliminates z-fighting between overlapping transparent text

Dynamic Updates with Pre-allocation

• Set maxTextCount and maxGlyphCount to pre-allocate buffers for dynamic addText()
• Without pre-allocation, buffers are sized to initial content (no dynamic growth)
• computeIndirect dynamically adjusts GPU workgroup counts
• Uniform-based count tracking avoids shader recompilation within capacity

Features

• Batched Rendering: Single draw call for unlimited text instances
• GPU Frustum Culling: Skip rendering off-screen text (WebGPU only)
• LOD Sampling: Reduce glyph count for distant text
• Billboarding: Camera-facing text in world space
• Per-Instance Styling: Color, outline, opacity per text member
• Dynamic Updates: Add/remove/modify text at runtime via sync()
• Static Mode: batch.staticMode = true. Lock layout after initial pack for maximum performance
• Transparency Sorting: Correct z-order for SDF anti-aliased edges
• TSL Hooks: Custom positionNode, opacityNode, colorNode still work

Usage

Performance Tips

• Use static: true if text content never changes after initial setup
• Enable perObjectFrustumCulled for large scenes with many off-screen labels
• Use _cullOptions.lodMode to enable/disable LOD sampling
• Range LOD uses _cullOptions.lodNear + _cullOptions.lodFar
• Exp LOD uses _cullOptions.lodNear + _cullOptions.lodDensity (exp density). lodNear shifts the start of the exp curve.
• Call sync() only when text content changes, not every frame

LOD API

// Range mode (distance-based fade)
batch._cullOptions.lodMode = LOD_MODE_RANGE;
batch._cullOptions.lodNear = 50;    // start distance
batch._cullOptions.lodFar = 400;    // end distance

// Exp mode (density-based fade)
batch._cullOptions.lodMode = LOD_MODE_EXP;
batch._cullOptions.lodNear = 50;        // start distance
batch._cullOptions.lodDensity = 0.00025; // exp density

// Disable LOD
batch._cullOptions.lodMode = LOD_MODE_DISABLED;

// Optional: create the culler immediately (before first render)
batch.initCuller( renderer );
batch.culler.lodMode.value = LOD_MODE_EXP;

WebGL Limitations

• GPU frustum culling requires WebGPU (compute shaders not available in WebGL)
• perObjectFrustumCulled automatically disabled on WebGL backend
• All other features (batching, billboarding, styling) work in WebGL