v0.5.0

Text Colour Areas

Paint Unicode character ranges on Syncromesh text renderables without rich-text markup.

Text colour areas provide rich per-range colour without modifying the text string or introducing markup. They are stored by the shared Helix text renderable and are available to Syncromesh board scripts through Helix/Renderable.

Import and handle #

import * as Entity from 'Syncromesh/Entity';
import * as Renderable from 'Helix/Renderable';

const handle = await Entity.getRenderable(entityId, textRenderableIndex);

API #

Renderable.addColourArea
Paints the half-open Unicode code-point range [start, end) and returns a stable area ID.
Renderable.addColourArea(handle, start, end, colour): Promise<number>
Renderable.listColourAreas
Lists areas in insertion order. Each colour is returned as normalized [r, g, b, a].
Renderable.listColourAreas(handle): Promise<Array<{ id, start, end, colour }>>
Renderable.deleteColourArea
Deletes an area and returns whether it existed.
Renderable.deleteColourArea(handle, areaId): Promise<boolean>

Range and overlap semantics #

  • start is inclusive and end is exclusive.
  • Indices count Unicode code points rather than UTF-8 bytes; whitespace and newlines count as characters.
  • Areas may overlap. The most recently added matching area takes precedence.
  • Deleting a newer overlap reveals the previous area beneath it. With no matching area, the glyph uses the text renderable's base colour.
  • Base-colour animation remains available for uncovered glyphs. Renderable/entity opacity multiplies both base and area alpha.
const red = await Renderable.addColourArea(handle, 0, 8, [1, 0.15, 0.1, 1]);
const gold = await Renderable.addColourArea(handle, 5, 12, [1, 0.8, 0.1, 1]); // wins on 5..7

console.log(await Renderable.listColourAreas(handle));
await Renderable.deleteColourArea(handle, gold); // red is visible again on 5..7
Note

American-spelling aliases addColorArea, listColorAreas, and deleteColorArea are available in both Koya and Syncromesh.

← EventsGPU Particles →