Three MSDF Text WebGPU

Text rendering in Three.js with WebGPU using MSDF fonts.

Forked from three-msdf-text-utils.

MSDFs Font

This package requires using MSDF fonts which can be created using either the msdf-bmfont-xml cmd line tool or with Dom McCurdy's web tool.

Installation

``bash
npm install three-msdf-text-webgpu
`

Usage

There are two main methods to create a MSDFText mesh:

$3

`js
import * as THREE from "three/webgpu";
import { Font, FontLoader } from "three/examples/jsm/loaders/FontLoader.js";
import { MSDFText, type BMFontJSON } from "three-msdf-text-webgpu";

const fontLoader = new FontLoader();
const textureLoader = new THREE.TextureLoader();

// Load generated MSDF font files
const font = await this.fontLoader.loadAsync("/font/Roboto-Regular-msdf.json"),
const atlas = await this.textureLoader.loadAsync("/font/Roboto-Regular.png")

const options = {
text: "MSDF Text",
textStyles: {
widthPx: 500,
fontFamily: "Roboto",
fontSize: 32,
fontWeight: "400",
lineHeightPx: 50,
letterSpacingPx: 0,
textAlign: 'left',
whiteSpace: 'normal',
color: '#ff0000',
opacity: 1
}
}
const textMesh = new MSDFText(options, { atlas, data: font.data })
`

Note: The width/height of the resultant geometry will be equal to the pixel width/height of the rendered text, so the resulting mesh will need to be scaled.

The available options are:
- text (string: required)
- textStyles

With textStyles:
- widthPx (number: required) - Width of the text in pixels. Determines where text is wrapped.
- fontFamily (string): Default - Roboto
- fontSize (number px): Default - 16
- fontWeight (string): Default - "400"
- fontStyle (string): Default - "normal"
- lineHeightPx (number): Default - 16
- letterSpacingPx (number): Default - 0
- textAlign ("center" | "end" | "left" | "right" | "start"): Default - "left"
- whiteSpace ("normal" | "nowrap" | "pre" | "pre-wrap" | "pre-line" | "break-spaces"): Default - "normal"
- color (string): Default - "#000000"
- opacity (number): Default - 1

The method .update(options) can be called with partial options to update the text geometry and material.

$3

`js
import * as THREE from "three/webgpu";
import { Font, FontLoader } from "three/examples/jsm/loaders/FontLoader.js";
import { MSDFText, type BMFontJSON } from "three-msdf-text-webgpu";

const fontLoader = new FontLoader();
const textureLoader = new THREE.TextureLoader();

// Load generated MSDF font files
const font = await this.fontLoader.loadAsync("/font/Roboto-Regular-msdf.json"),
const atlas = await this.textureLoader.loadAsync("/font/Roboto-Regular.png")

const textElement = document.querySelector('[data-3d]')!;
const textMesh = new SyncMSDFText(
textElement,
{ atlas, data: font.data as unknown as BMFontJSON },
)
`

Using this method also allows mesh.update(camera: THREE.Camera) to be called which will update the transform of the mesh to align with the DOM element in the camera's view at a given depth (5 units by default).

Examples:

See the github pages site for a sandbox demo.

To run the example demo locally, run:
`bash
npm i
npm run example
``

For more information on this package, see this blog page.