1 | # gl-text [![unstable](https://img.shields.io/badge/stability-unstable-green.svg)](http://github.com/badges/stability-badges)
|
2 |
|
3 | Render bitmap text in WebGL via [font-atlas](https://ghub.io/font-atlas).
|
4 |
|
5 | ## Usage
|
6 |
|
7 | [![npm install gl-text](https://nodei.co/npm/gl-text.png?mini=true)](https://npmjs.org/package/gl-text/)
|
8 |
|
9 | ```js
|
10 | const Text = require('gl-text')
|
11 |
|
12 | let text1 = new Text()
|
13 |
|
14 | text1.update({
|
15 | position: [50, 50],
|
16 | text: 'ABC',
|
17 | font: '16px Helvetica, sans-serif'
|
18 | })
|
19 | text1.render()
|
20 |
|
21 | // create another text renderer on the same context
|
22 | let text2 = new Text(text1.gl)
|
23 | text2.update({
|
24 | font: {
|
25 | family: ['Helvetica', 'Arial', 'sans-serif'],
|
26 | size: '1rem'
|
27 | }
|
28 | })
|
29 | ```
|
30 |
|
31 | ## API
|
32 |
|
33 | ### `let text = Text(gl|regl|canvas|container|options?)`
|
34 |
|
35 | Create text renderer instance for the WebGL context `gl`, [`regl`](https://ghub.io/regl) instance, `canvas`/`container` element or based on `options`:
|
36 |
|
37 | Option | Meaning
|
38 | ---|---
|
39 | `regl` | Existing `regl` instance. By default new one is created.
|
40 | `gl`/`context` | Existing WebGL context. By default new one is created.
|
41 | `canvas` | Existing `canvas` element.
|
42 | `container` | Existing `container` element. By default new canvas is created within the container.
|
43 |
|
44 | No arguments call creates new fullscreen canvas.
|
45 |
|
46 | ### `text.update(options)`
|
47 |
|
48 | Update state of a `Text` instance.
|
49 |
|
50 | Option | Description
|
51 | ---|---
|
52 | `text` | Text string to print.
|
53 | `position` | Position of the text on the screen or within the `range`, a couple `[x, y]`.
|
54 | `align` | Horizontal alignment relative to the `position`. Can be one of `left`, `right`, `center`/`middle`, `start`, `end`, or a number of em units. By default `left`.
|
55 | `baseline` | Vertical alignment value, by default `middle`. Can be a string one of `top`, `hanging`, `middle`, `alphabetic`, `ideographic`, `bottom` etc. (see [font-measure](https://ghub.io/font-measure)) or a number of em units, denoting `0` as alphabetic baseline.
|
56 | `font` | Font family, CSS font string or an object with font properties like `{family, size, style}`, see [css-font](https://ghub.io/css-font).
|
57 | `fontSize`/`em` | Font-size, can be changed independently of `font`.
|
58 | `range` | Data area corresponding to position in viewport. Useful for organizing zoom/pan. By default is the same as the viewport `[0, 0, canvas.width, canvas.height]`.
|
59 | `scale`/`translate` | An alternative to `range`.
|
60 | `viewport` | Visible area within the canvas, an array `[left, top, width, height]` or rectangle `{x, y, width, height}`, see [parse-rect](https://ghub.io/parse-rect).
|
61 | `kerning` | Enable font kerning, by default `true`. Disable for the case of monospace fonts. See [detect-kerning](https://ghub.io/detect-kerning) package.
|
62 | `offset` | Shift `position` by the number of ems. Useful for organizing multiple lines, indentation, sub/sup script etc. Does not get affected by `position` change. Can be a number for x-offset only or an array `[x, y]`.
|
63 |
|
64 |
|
65 |
|
66 |
|
67 |
|
68 | ### `text.render()`
|
69 |
|
70 | Draw text.
|
71 |
|
72 | ### `text.destroy()`
|
73 |
|
74 | Dispose text renderer.
|
75 |
|
76 | ### Properties
|
77 |
|
78 | * `text.gl` - WebGL context.
|
79 | * `text.canvas` - canvas element.
|
80 | * `text.regl` - regl instance.
|
81 |
|
82 |
|
83 | ## License
|
84 |
|
85 | © 2018 Dmitry Yv. MIT License
|
86 |
|
87 | Development supported by [plot.ly](https://github.com/plotly/).
|