Hexr Txtr

Hexr Text Utility. Uses Canvas API to write directly to a texture map. It's intended, primarily, for in game captions and speech bubbles etc. Key features:

• Uses a power of 2 texture for full filtering options
• COnfigurable blending mode for the material
• word wrapping with configurable width and maximum number of lines per 'page'
• divides the available space in the raw texture map into 'pages' which can be owned by... things.
• Each page has its own mesh with the proper UV co-ords.
• mesh is dynamically sized to the height and width of the current text on that 'page'
• uses THREE.PlaneBufferGeometry

I'll just show the API.

var hexrTxtr = require('hexr-txtr')(config);

The default config, btw, looks like this:

var defaultConfig = {
    fontSizePx : 20, // 
    maxLines : 5,
    lineWidthRatio : 20,
    blend : THREE.NormalBlending,
    minFilter : THREE.LinearFilter,
    magFilter: THREE.LinearFilter
};

There's no clever merging of the defaults implemented yet, so if you're going to override the defaults you need to override the lot.

About that configuration:

fontSizePx

Canvas uses this for the font height. It is also the canonical height of each line. (and yes, this causes a problem with fonts that draw above/below)

The larger the font size, the more detailed the texture (allowing you to scale it more) but the mesh that is generated will still be 1 THREE.JS Unit per line.

maxLines

Hexr Txtr will wrap strings to a specified maximum number of lines. This defines the maximum height of a page. The more lines, the fewer pages you will be able to get from a single Hexr Txtr instance.

lineWidthRatio

Okay so if your font height is 20px and your lineWidthRatio is 20 then that means the width of a line is 20 * 20 or 400px. This is kept as a ratio so that you can tinker with the font

Bear in mind that the width of the raw texture map is rounded up to the nearest power of two, so if you're using very large fonts with very large ratios you could be generating ENORMOUS texture maps which will probably seriously hurt your performance.

blend

Set the THREE constant for the blend mode of the material. Normal blending is good if you want black on white. Additive blending is good for opaque background and white writing.

minFilter

magFilter

You can set the exact texture filters you want here.

Hexr Txtr API

hexrTxtr.getMaxPages()

Gets the number of available pages for this instance.

hexrTxt.getPage(pageIndex)

Pages are zero indexed, so the first page is always zero.

Hexr Txtr Page API

page.mesh

A reference to the page's mesh. Yours to do with what you will.

page.setBackgroundColour(cssHexString)

Set the background colour for the page

page.setTextColour(cssHexString)

Set the text colour for the page

page.setAlignment(left|center|right)

You can only control the horizontal alignment, but this is how you do that.

page.setFont(fontname)

Every page can use its own font as well.

It's up to you to make sure that the font you're using is available to the browser. You have to use the font in a normal HTML element with normal CSS styles otherwise some browsers won't bother to download it.

page.write(string)

Set the current text of the page. You can force a line break with \n, btw. This function returns an object with a width and height property. You can use this to position the text mesh correctly or add some sort of border to it.

License

MIT

Contributing

Yes please.