text

Note: This documentation is for the old 0.8.0 version of A-Frame. Check out the documentation for the current 1.6.0 version

The text component renders signed distance field (SDF) font text.

Introduction

Note that rendering text in 3D is hard. In 2D web development, text is the most basic thing because the browser’s renderer and layout engine handles everything. In a 3D context, we don’t have those luxuries. There are several other different ways to render text in A-Frame including:

• 3D Text Geometry
• HTML Materials (DOM-to-Canvas-to-Texture)
• Image Textures

As a default, we’ve selected SDF-based text to be included as a core component due to its relatively good performance and clarity. This component uses mattdesl’s three-bmfont-text library. The standard text component has a long lineage, starting out as a community component and was forked and improved several times before landing into A-Frame!

Example

Here’s a basic example of text defining just the content with not much other configuration.

<a-entity text="value: Hello World;"></a-entity>

See more examples to see configuration of alignments, anchors, baselines, scaling, and auto-sizing.

• Text Example (code)
• Text Anchors (code)
• Text Scenarios (code)
• Text Sizes (code)

Open any of these example scenes, hit <ctrl> + <alt> + i to open the Inspector, and play with all the possible values to see the effects instantly!

Properties

The implementation is based on mattdesl’s three-bmfont-text. Read more about the text properties.

Events

| Event Name | Description | |— — — -|— — — — — — — — — — — –| | textfontset | Emitted when the font source has been loaded |

Fonts

We can specify different fonts, although the process is not as simple as Web Fonts. The text component defaults to roboto which uses a multi-channel signed distance (MSDF) font. MSDF helps to preserve sharp corners and edges.

Stock Fonts

Select from one of A-Frame’s built-in fonts. These fonts will be loaded in from over a CDN. If you want your application to work better offline, download these fonts locally and point to them via a URL.

Custom Fonts

Different fonts can be specified using the font and fontImage properties.

<a-entity text="font: mozillavr; value: Via stock font name."></a-entity>
<a-entity text="font: https://cdn.aframe.io/fonts/mozillavr.fnt; value: Via URL."></a-entity>
<a-entity text="text: Hello World; font: ../fonts/DejaVu-sdf.fnt; fontImage: ../fonts/DejaVu-sdf.png"></a-entity>

If not specified, fontImage will be the font‘s name, but with the extension replaced to .png. For example, if the font path ends with mozillavr.fnt, then the fontImage texture will default to mozillavr.png.

Generating SDF Fonts

On top of the stock fonts, we can generate SDF fonts using Hiero, a bitmap font packing tool. See this guide for generating SDF fonts.

We can also generate MSDF fonts using a web-based MSDF tool, or on the commandline with msdfgen or msdf-bmfont. Tools for MSDF fonts may be less mature than the SDF alternatives.

Below is an example comparing a font generated with Hiero, Arial Black, with the SDF font, DejaVu:

Sizing

To change the size of the text, we can:

• Change the width.
• Change the wrapCount (roughly how many characters to fit inside the given width).
• Change wrapPixels.
• Change the scale component.
• Position the text closer or farther away.

Text can be wrapped by specifying width in A-Frame units.

In case we need to do custom layout or need to know the bounds of the text, the output length of the text can be pre-calculated dynamically with something like:

totalWidth = data.value.length * (data.width / data.wrapCount)

Auto-Scaling

The text component introduces special behavior when using alongside the geometry component (e.g., a background plane) to fit. Note this only works with 2D-friendly geometries that define a width and height (i.e., box, plane). The text can either be scaled, bounded, or aligned in relation to the geometry, or the text can auto-scale the geometry to fit the text.

Scaling Text to Fit Geometry

To have the text component’s width property automatically scale to match the geometry component’s width, do not specify a width for the text component:

<a-entity
  geometry="primitive: plane; width: 4; height: auto"
  material="color: blue"
  text="value: This text will be 4 units wide."></a-entity>

Scaling Geometry to Fit Text

To have the geometry automatically scale with the text, set the geometry component’s width and height properties to auto, and set the text component’s width as desired. In this example, the plane’s width will be set to 4 units, and its height will be set to match the actual height of the text:

<a-entity
  geometry="primitive: plane; height: auto; width: auto"
  material="color: blue"
  text="width: 4; value: This text will be 4 units wide."></a-entity>

Note that if neither geometry nor text specify a width, the text width property will default to 1 unit (meter), and the geometry width property will then become 1 unit as well.

<a-entity
  geometry="primitive: plane"
  material="color: blue"
  text="value: 1-wide\ndefault."></a-entity>

Limitations

The text component does not make use of all of the features of the three-bmfont-text library nor its sister modules.

Bitmap font rendering limits you to the characters included in the font (Unicode this is not). SDF font rendering tends to produce smooth sharp edges though there are ways around this.

The generated text is not suitable for raycaster intersection testing. For raycaster or cursor detection it is necessary to use a geometry component along with the text component.

Further Reading

If you are curious about the details of text rendering in WebGL, three.js, and A-Frame, below are links to some background reading:

• three-bmfont-text documentation
• Hacking with three.js
• It’s 2015 and drawing text is still hard (WebGL, ThreeJS)
• Improved Alpha-Tested Magnification for Vector Textures and Special Effects