Using a custom text type

⚠️ To use a custom font, read this article instead ! ⚠️

You don't want to use three-mesh-ui default Text component ?

Although three-mesh-ui only supports one Text component, its architecture makes it easy to stick in your own custom Text component.

All logic contained in the /components directory is Text type agnostic.
Logic related to the default Text type (MSDF text), is contained in the /content folder, in MSDFGlyph.js and MSDFText.js

The process to use your custom Text component is explained bellow, step by step :

1 - Provide your font file

You must provide a textType attribute to your Text component or one of its ancestors, containing the name of your custom text type.
Your font file must be a JSON file, that you must hand the standard way to the three-mesh-ui components :

const container = new ThreeMeshUI.Block({
	textType: 'my-text-type',
	fontFamily: YourJsonUrl,
	fontTexture: YourImageUrl // if any
});

2 - Provide individual glyph dimension

In TextManager.getGlyphDimensions, add a case with the name of your text type, and link to a getGlyphDimensions function in your custom text module :

case 'my-text-type' :
	return MyTextModule.getGlyphDimensions( options )

The options parameter passed in this function has these parameters :

font : object : your parsed font JSON file
fontSize : float : font size required by the user (default is 0.05)
glyph : string : single glyph whose dimensions must be computed
textType : string : textType attribute content

It must return an object with these parameters :

width : float : width of the glyph in world unit
height : float : height of the glyph in world unit
anchor : float : vertical offset of the glyph in world unit (if it's a "p" for instance)

3 - Provide Text mesh creation

In TextManager.createText, add a case with the name of your text type, and link to a buildText function in your custom text module :

case 'my-text-type' :
	return MyTextModule.buildText.call( this )

This function is supposed to return a THREE.Mesh of the whole text (all glyphs merged in one mesh).

In order to build the text mesh, you want to use the information contained in the Text component (this) inlines parameter.

this.inlines is an array containing, for each glyph, an object with the following parameters :

glyph : string : single glyph whose dimensions must be computed
width : float : width of the glyph in world unit
height : float : height of the glyph in world unit
offsetX : float : horizontal offset of the glyph in world unit
offsetY : float : vertical offset of the glyph in world unit
anchor : float : additional vertical offset of the glyph in world unit related to the glyph type (if it's a "p" for instance)

Unlikely to be useful for your purpose but still contained in the inline object :
fontSize : float : font size required by the user (default is 0.05)
lineBreak : null, "possible" or "mandatory", whether this glyph is line-break-friendly