@luma.gl/text
@luma.gl/text provides experimental GPU-only 2D text rendering utilities.
@luma.gl/arrow owns Arrow source data, source mapping, upload, and Arrow UTF-8/dictionary preparation. It converts Arrow vectors into GPUVector objects or prepared GPU state, then constructs renderer models that only know about GPU-resident resources.
Public Architecture
| Responsibility | Public APIs |
|---|---|
Arrow facade in @luma.gl/arrow | ArrowTextRenderer, resolveArrowTextSourceVectors(), convertArrowTextToAttribute(), convertArrowTextToStorage(), convertArrowTextToDictionary() |
Pure rendering in @luma.gl/text | TextAttributeModel, TextStorageModel, TextRowIndexedStorageModel, TextDictionaryModel |
GPU input contracts in @luma.gl/text | TEXT_ATTRIBUTE_GPU_INPUT_SCHEMA, TEXT_STORAGE_GPU_INPUT_SCHEMA, TEXT_DICTIONARY_GPU_INPUT_SCHEMA |
New code should perform Arrow conversion through @luma.gl/arrow and construct one of the pure models with flat prepared props.
Attribute Path
Use convertArrowTextToAttribute() to upload Arrow source vectors, then convertArrowTextToAttributeModelProps() to build flat model props for TextAttributeModel.
The attribute path supports row colors and per-character color lists. It expands text rows into generated glyph vertex attributes and renders through a GPU table.
Storage Path
Use convertArrowTextToStorage() and convertArrowTextToStorageModelProps() when rendering with WebGPU storage buffers. Pass the resulting flat props to TextStorageModel or TextRowIndexedStorageModel.
TextRowIndexedStorageModel stores one extra source-row index per generated glyph. This avoids shader-side row lookup by binary search at the cost of a larger generated glyph vertex record.
Dictionary Path
Use convertArrowTextToDictionary() and convertArrowTextToDictionaryModelProps() for dictionary-encoded UTF-8 text. The dictionary model stores shared glyph records per dictionary value and per-row dictionary references.
Resource Ownership
Conversion results and prepared props own GPU resources. Layers should destroy converted GPUVector bundles when they are replaced or removed. Models should be constructed with ownsAttributeState or ownsStorageState when the model should destroy prepared resources.