Works with A-Frame version 0.3.0.
This component is useful for rendering bitmap and signed distance field font text in A-Frame. Basically, it wraps Matt DesLauriers' three-bmfont-text and load-bmfont.
| Property | Description | Default Value |
|---|---|---|
| text | the text you want to appear | None |
| width | width of the text box | None |
| align | 'left', 'center', 'right' | left |
| letterSpacing | the letter spacing in pixels | 0 |
| lineHeight | the line height in pixels | 38 |
| fnt | path to 'fnt' file | https://cdn.rawgit... |
| fntImage | path to font image file | None (fnt, but .png) |
| mode | 'pre' and 'nowrap' | 'normal' |
| color | by RGB, hex, or name | #000 |
| opacity | Extent of transparency. | 1.0 |
| anchor | 'left', 'center', 'right', 'align' | 1.0 |
| textscale | text scale factor | 0.005 |
More details on these properties here.
Explanation of 'mode' property here.
Write some text:
<a-entity bmfont-text="text: Hello World;"></a-entity>The effective width of the entity in A-Frame is 'width' * 'textscale'.
To change the size of the text,
- use the scale component
- position the text closer or further away.
- change 'textscale' which will change the entity dimensions unless
widthis also adjusted to match
Text can be wrapped by specifying width.
To change how A-Frame position is used to place the entity, use the 'anchor' property. For example, this will center the entity around its A-Frame position, rather than aligning to left edge:
<a-entity bmfont-text="text: Hello World; anchor:center"></a-entity>A guide for generating SDF fonts can be found here; here is an example comparing Arial Black and DejaVu. Bitmap fonts also work, but do not look nearly as good.
Different fonts can be specified with the 'fnt' and 'fntImage' properties.
<a-entity bmfont-text="text: Hello World; fnt:../fonts/DejaVu-sdf.fnt; fntImage:../fonts/DejaVu-sdf.png">
</a-entity>Thanks to RawGit, these default to hosted "DejaVu-sdf.fnt" and "DejaVu-sdf.png" files.
This component does not make use of all of the features of three-bmfont-text and its sister modules, if you require more advanced functionality such as tabSize and start and end indices, I recommend forking this component and modifying it. Pull requests are welcome, but please include a test example.
Bitmap font rendering limits you to the characters included in the font (Unicode this is not). SDF font (in particular) tends to smooth sharp edges though there are ways around this.
If you are interested in text rendering in WebGL/ThreeJS/A-Frame and want to learn more, I recommend reading the documentation for three-bmfont-text.
Here are some additional resources:
- 'It’s 2015 and drawing text is still hard (WebGL, ThreeJS)' by Parris Khachi
- Valve's original paper
- 'Hacking with THREE.js' by Matt DesLauriers
Install and use by directly including the browser files:
<head>
<title>My A-Frame Scene</title>
<script src="https://aframe.io/releases/0.3.0/aframe.min.js"></script>
<script src="https://cdn.rawgit.com/chenzlabs/aframe-bmfont-text-component/release/dist/aframe-bmfont-text-component.min.js"></script>
</head>
<body>
<a-scene>
<a-entity bmfont-text="text: Hello world"></a-entity>
</a-scene>
</body>Install via NPM:
npm install aframe-bmfont-text-componentThen register and use.
require('aframe');
require('aframe-bmfont-text-component');