Font object

Font()

Syntax

new Font()

Return value

Font object

Description

Initialize a Font object.

The following shortcut, $Font(filelines), is equivalent to new Font().load_filelines(filelines), use it for convenience.

$Font() shortcut

Syntax

$Font(filelines)

Examples

JavaScript (CJS)

const { $Font } = require('bdfparser')

const getline = require('readlineiter') // or require('fetchline') for browsers

;(async () => {

const font = await $Font(getline('test/fonts/unifont-13.0.04.bdf'))

})()

TypeScript (strict)

import { $Font } from 'bdfparser'

import getline from 'readlineiter' // or from 'fetchline' for browsers

;(async () => {

try {

const font = await $Font(getline('test/fonts/unifont-13.0.04.bdf'))

} catch (error) {

throw error

}

})()

Parameters

Name	R/O	Type	Default Value	Description
filelines	Required	AsyncIterableIterator<string>	N/A	Asynchronous iterable iterator representing each line in string text from the font file. Go to the page of my Fetch Line JavaScript packages, choose readlineiter for node file system or fetchline for browsers. See the above example

Return value

Font object

Description

Initialize a Font object and load the BDF font file (file line async iterator).

$Font(filelines) is a shortcut for new Font().load_filelines(filelines), so you don't need to write new and .load_filelines

.headers

Syntax

.headers

Examples

JavaScript (CJS)

console.log(font.headers)

// { bdfversion: 2.1, fontname: '-gnu-Unifont-Medium-R-Normal-Sans-16-160-75-75-c-80-iso10646-1', pointsize: 16, xres: 75, yres: 75, fbbx: 16, fbby: 16, fbbxoff: 0, fbbyoff: -2, metricsset: 0 }

font.headers.fontname

// -gnu-Unifont-Medium-R-Normal-Sans-16-160-75-75-c-80-iso10646-1

TypeScript (strict)

console.log(font.headers)

// { bdfversion: 2.1, fontname: '-gnu-Unifont-Medium-R-Normal-Sans-16-160-75-75-c-80-iso10646-1', pointsize: 16, xres: 75, yres: 75, fbbx: 16, fbby: 16, fbbxoff: 0, fbbyoff: -2, metricsset: 0 }

font.headers?.fontname

// -gnu-Unifont-Medium-R-Normal-Sans-16-160-75-75-c-80-iso10646-1

Type

object (string as keys, number or string as values)

Description

This attribute of a Font object represents the header information which is typically all the information before the STARTPROPERTIES line in the font file.

Font header's names (keys / property names), value types, and their descriptions in the BDF spec:

• 'bdfversion': (number) see STARTFONT
• 'fontname': (string) see FONT
• 'pointsize': (number) see SIZE
• 'xres': (number) see SIZE
• 'yres': (number) see SIZE
• 'fbbx': (number) see FONTBOUNDINGBOX
• 'fbby': (number) see FONTBOUNDINGBOX
• 'fbbxoff': (number) see FONTBOUNDINGBOX
• 'fbbyoff': (number) see FONTBOUNDINGBOX
• 'swx0': (number) see Metrics keywords, see also SWIDTH at glyph-level
• 'swy0': (number) see Metrics keywords, see also SWIDTH at glyph-level
• 'dwx0': (number) see Metrics keywords, see also DWIDTH at glyph-level
• 'dwy0': (number) see Metrics keywords, see also DWIDTH at glyph-level
• 'swx1': (number) see Metrics keywords, see also SWIDTH1 at glyph-level
• 'swy1': (number) see Metrics keywords, see also SWIDTH1 at glyph-level
• 'dwx1': (number) see Metrics keywords, see also DWIDTH1 at glyph-level
• 'dwy1': (number) see Metrics keywords, see also DWIDTH1 at glyph-level
• 'vvectorx': (number) see Metrics keywords, see also VVECTOR at glyph-level
• 'vvectory': (number) see Metrics keywords, see also VVECTOR at glyph-level
• 'metricsset': (number) see METRICSSET
• 'contentversion': (number) see CONTENTVERSION
• 'comment': (array of strings) see COMMENT

note

Headers are to be distinguished from properties (props) which are inside the block between STARTPROPERTIES and ENDPROPERTIES lines in the font file.

Header names are defined in the spec, property names are not.

.props

Syntax

.props

Examples

JavaScript (CJS)

console.log(font.props)

// {add_style_name: 'Sans Serif', average_width: '80', cap_height: '10', ..., weight_name: 'Medium', x_height: '8'}

TypeScript (strict)

console.log(font.props)

// {add_style_name: 'Sans Serif', average_width: '80', cap_height: '10', ..., weight_name: 'Medium', x_height: '8'}

Type

object (string as keys, number or string as values)

Description

This attribute of a Font object represents the property infomation which is inside the block between STARTPROPERTIES and ENDPROPERTIES lines.

note

Properties (props) are to be distinguished from headers which are typically all the information before the STARTPROPERTIES line in the font file.

.glyphs

Syntax

.glyphs

Type

object (number as keys, array as values)

Description

This attribute of a Font object represents the raw glyph data in the font.

note

As raw data with values without their keys, you usually should not use it directly. Use other API methods instead, such as .glyph() and .iterglyphs().

.load_filelines()

Syntax

.load_filelines(filelines)

Parameters

Name	R/O	Type	Default Value	Description
filelines	Required	AsyncIterableIterator<string>	N/A	Asynchronous iterable iterator representing each line in string text from the font file. Go to the page of my Fetch Line JavaScript packages, choose readlineiter for node file system or fetchline for browsers. See the above example

Return value

Promise that will be resolved with the Font object itself with font loaded

Description

Load the BDF font file (file line async iterator).

$Font(filelines) shortcut is equivalent to new Font().load_filelines(filelines).

.length

Syntax

.length

Examples

JavaScript (CJS)

console.log(font.length)

// 57086

TypeScript (strict)

console.log(font.length)

// 57086

Parameters

No parameters

Return value

(number) Actual glyph count in the font

Description

The getter method always returns how many glyphs actually exist in the font. This could be different with the glyph count number next to the 'CHARS' keyword, if so, there would be a warning when the font is loaded.

.iterglyphs()

Syntax

.iterglyphs(order, r)

Examples

JavaScript (CJS)

// print all basic latin letters (A-Za-z)'s character and bitmap shape, in reverse order:

for (const glyph of font.iterglyphs(2, [[65, 90], [97, 122],])) {

console.log('Character "' + glyph.chr() + '"\'s shape:')

console.log(glyph.toString())

}

// remove `order=2 ,r=[(65, 90), (97, 122)]` to print all glyphs in the font in normal ascending order

TypeScript (strict)

// print all basic latin letters (A-Za-z)'s character and bitmap shape, in reverse order:

for (const glyph of font.iterglyphs(2, [[65, 90], [97, 122],])) {

console.log('Character "' + glyph?.chr() + '"\'s shape:')

console.log(glyph?.toString())

}

// remove `order=2 ,r=[(65, 90), (97, 122)]` to print all glyphs in the font in normal ascending order

Parameters

Name	R/O	Type	Default Value	Description
order	Optional	number	1	-1: reverse order in the BDF font file 0: order in the BDF font file 1: ascending codepoint order 2: descending codepoint order
r	Optional	See below	None	Codepoint range, see below

The codepoint range parameter r accepts:

• None (default): all the glyphs in the font
• number. Examples:
  • 128 (Basic Latin / ASCII)
  • 0x100 (Basic Latin and Latin-1 Supplement / cp1250 / cp1251 / cp1252)
• tuple? of two numbers. Examples:
  • [0, 127] (same as 128)
  • [0, 0xff] (same as 0x100)
  • [48, 57] (all numbers 0-9)
  • [65, 90] (all uppercase basic latin letters A-Z)
  • [97, 122] (all lowercase basic latin letters a-z)
  • [1328, 0x1032F]
• array of tuples? of two numbers. Example:
  • [[65, 90], [97, 122]] (all basic latin letters A-Za-z)
  • [[0x2E80, 0x9FFF], [0xA960, 0xA97F], [0xAC00, 0xD7FF], [0xF900, 0xFAFF], [0xFE30, 0xFE4F], [0xFF00, 0xFFEF], [0x20000, 0x3134F]] (this is roughly all CJK characters in the Unicode)

See also Wikipedia article "Unicode block"

Return value

(iterator of Glyph objects/None) An iterator of glyphs as Glyph objects. Missing glyphs are replaced by None

Description

This method returns an iterator of all the glyphs (as Glyph objects) in the font (default) or in the specified codepoint range in the font, sorted by the specified order (or by the ascending codepoint order by default).

.itercps()

Syntax

.itercps(order, r)

Examples

JavaScript (CJS)

// print every glyph's codepoint in the font

for (const codepoint of font.itercps()) {

console.log(codepoint)

}

TypeScript (strict)

// print every glyph's codepoint in the font

for (const codepoint of font.itercps()) {

console.log(codepoint)

}

Parameters

See .iterglyphs()'s "Parameters" section

Return value

(iterator of numbers) An iterator of the codepoints of glyphs

Description

This method is almost identical to .iterglyphs(), except it returns an iterator of glyph codepoints instead of an iterator of Glyph objects.

.glyph()

Syntax

.glyph(character)

Examples

JavaScript (CJS)

// get glyph "a" and print its shape:

const glyph_a = font.glyph('a')

console.log(glyph_a.toString())

TypeScript (strict)

// get glyph "a" and print its shape:

const glyph_a = font.glyph('a')

console.log(glyph_a?.toString())

Parameters

Name	R/O	Type	Default Value	Description
character	Required	string	N/A	Character (a one-character string) of the glyph you need

Return value

• Glyph object
• None if the glyph does not exist in the font

Description

Get a glyph (as Glyph object) by its character.

.glyphbycp()

Syntax

.glyphbycp(codepoint)

Examples

JavaScript (CJS)

// get glyph "a" whose codepoint is 97:

const glyph_a = font.glyphbycp(97)

TypeScript (strict)

// get glyph "a" whose codepoint is 97:

const glyph_a = font.glyphbycp(97)

Parameters

Name	R/O	Type	Default Value	Description
codepoint	Required	number	N/A	Codepoint of the glyph you need

Return value

• Glyph object
• None if the glyph does not exist in the font

Description

Get a glyph (as Glyph object) by its codepoint.

.lacksglyphs()

Syntax

.lacksglyphs(str)

Examples

JavaScript (CJS)

// This font only has latin and arabic support

const testfont = await $Font(getline('test/fonts/unifont-13.0.04-for-test.bdf'))

console.log(testfont.lacksglyphs('Bé H好Δiب')) // ['好', 'Δ']

console.log(testfont.lacksglyphs('Bé Hiب')) // null

TypeScript (strict)

// This font only has latin and arabic support

const testfont = await $Font(getline('test/fonts/unifont-13.0.04-for-test.bdf'))

console.log(testfont.lacksglyphs('Bé H好Δiب')) // ['好', 'Δ']

console.log(testfont.lacksglyphs('Bé Hiب')) // null

Parameters

Name	R/O	Type	Default Value	Description
str	Required	string	N/A	string (one or more characters)

Return value

• (array of strings) array of missing glyph(s)' characters
• None if all the glyphs in your string exist in the font

Description

Check if there is any missing glyph and gets these glyphs' character.

.draw()

Syntax

.draw(str, options)

// options = {linelimit, mode, direction, usecurrentglyphspacing, missing}

Examples

JavaScript (CJS)

const font = await $Font(getline('test/fonts/unifont-13.0.04.bdf'))

// draw 'Bdf Hi' to a bitmap:

font.draw('Bdf Hi')

// each glyph could be wider when mode: 0:

font.draw('Bdf Hi', { mode: 0 })

// right to left:

font.draw('مرحبا', { direction: 'rl' })

// each line has 30 pixels instead of 512 by default:

font.draw('Bdf Hi', { linelimit: 30 })

// This font only has latin and arabic support

const testfont = await $Font(getline('test/fonts/unifont-13.0.04-for-test.bdf'))

// You can optionally specify the missing glyphs' replacement

// instead of a 0-width-and-height empty glyph by default

testfont.draw('Bé H好Δi的', {

missing: { glyphname: 'missing glyph', codepoint: 0, bbw: 16, bbh: 16, bbxoff: 0, bbyoff: -2, swx0: 1000, swy0: 0, dwx0: 16, dwy0: 0, swx1: null, swy1: null, dwx1: null, dwy1: null, vvectorx: null, vvectory: null, hexdata: [ '0000', '0000', '0000', '3ff8', '3018', '2828', '2448', '2288', '2108', '2288', '2448', '2828', '3018', '3ff8', '0000', '0000' ] },

}) // the missing replacement is "⌧" ("x" in a rectangle box)

TypeScript (strict)

const font = await $Font(getline('test/fonts/unifont-13.0.04.bdf'))

// draw 'Bdf Hi' to a bitmap:

font.draw('Bdf Hi')

// each glyph could be wider when mode: 0:

font.draw('Bdf Hi', { mode: 0 })

// right to left:

font.draw('مرحبا', { direction: 'rl' })

// each line has 30 pixels instead of 512 by default:

font.draw('Bdf Hi', { linelimit: 30 })

// This font only has latin and arabic support

const testfont = await $Font(getline('test/fonts/unifont-13.0.04-for-test.bdf'))

// You can optionally specify the missing glyphs' replacement

// instead of a 0-width-and-height empty glyph by default

testfont.draw('Bé H好Δi的', {

missing: { glyphname: 'missing glyph', codepoint: 0, bbw: 16, bbh: 16, bbxoff: 0, bbyoff: -2, swx0: 1000, swy0: 0, dwx0: 16, dwy0: 0, swx1: null, swy1: null, dwx1: null, dwy1: null, vvectorx: null, vvectory: null, hexdata: [ '0000', '0000', '0000', '3ff8', '3018', '2828', '2448', '2288', '2108', '2288', '2448', '2828', '3018', '3ff8', '0000', '0000' ] },

}) // the missing replacement is "⌧" ("x" in a rectangle box)

---

---

---

---

---

---

Parameters

Name	R/O	Type	Default Value	Description
str	Required	string	N/A	The words, the setences, the paragraphs you want to draw
options	Optional	number	512	Maximum pixels per line (row)
(in options) linelimit	Optional	number	512	Maximum pixels per line (row)
(in options) mode	Optional	number	1	0: uses ffb, glyphs will be fixed-width (monospace) and -height 1: uses dwidth horizontally, dwidth1 vertically
(in options) direction	Optional	string	'lrtb'	Writing direction. See below
(in options) usecurrentglyphspacing	Optional	boolean	false	Useful when direction: 'rl'. For example, font.draw('a的', {direction: 'rl'}) will misplace the wider "的" on the narrower "U" because normally we use the previous glyph's spacing (dwidth). You can use font.draw('a的', {direction: 'rl', usecurrentglyphspacing: true}) to use the current one and solve the problem
(in options) missing	Optional	object or Glyph object	An empty glyph with glyphname 'empty', codepoint 8203, hexdata [] and metrics all 0	The missing glyphs will be replaced by this one. It can be a object of glyph meta information, or a Glyph object

direction:

• 'lrtb' or 'lr': left to right, lines from top to bottom (most common direction)
• 'lrbt': left to right, lines from bottom to top
• 'rltb' or 'rl': right to left, lines from top to bottom (Arabic, Hebrew, Persian, Urdu)
• 'rlbt': right to left, lines from bottom to top
• 'tbrl' or 'tb': top to bottom, lines from right to left (Chinese traditionally)
• 'tblr': top to bottom, lines from left to right
• 'btrl' or 'bt': bottom to top, lines from right to left
• 'btlr': bottom to top, lines from left to right

Return value

Bitmap object

Description

Draw (render) the glyphs of the specified words / setences / paragraphs (as a string), to a Bitmap object.

note

See the missing parameter if you need to handle potentially missing glyphs.

.drawcps()

Syntax

.drawcps(cps, options)

// options = {linelimit, mode, direction, usecurrentglyphspacing, missing}

Examples

JavaScript (CJS)

// this is the same as `font.draw('Bdf Hi')`

font.drawcps([66, 100, 102, 32, 72, 105])

TypeScript (strict)

// this is the same as `font.draw('Bdf Hi')`

font.drawcps([66, 100, 102, 32, 72, 105])

Parameters

Name	R/O	Type	Default Value	Description
cps	Required	iterable of numbers	N/A	iterable (array, generator or any other iterable) of codepoints

For the rest of the parameters (linelimit, mode, direction and usecurrentglyphspacing in options), see .draw()'s "Parameters" section

Return value

Bitmap object

Description

Draw the glyphs of the specified codepoints, to a Bitmap object.

This method is almost identical to .draw(), except in the first parameter, it uses iterable of codepoints instead of string

.drawall()

Syntax

.drawall(options)

// options = {order, r, linelimit, mode, direction, usecurrentglyphspacing}

Examples

JavaScript (CJS)

// draw all glyphs in the font, linelimit is 512 pixels by default:

font.drawall()

// change linelimit

font.drawall({linelimit: 700})

TypeScript (strict)

// draw all glyphs in the font, linelimit is 512 pixels by default:

font.drawall()

// change linelimit

font.drawall({linelimit: 700})

note

You can copy and paste <BDF size={1} func={(font) => font.drawall()}/> and <BDF size={1} func={(font) => font.drawall({linelimit: 700})}/> into the Live Demo & Code Editor to see the result for unifont-reduced.bdf.

Parameters

For parameters order and r in options, see .iterglyphs()'s "Parameters" section

For the rest of the parameters (linelimit, mode, direction and usecurrentglyphspacing in options), see .draw()'s "Parameters" section

Those parameters have the same names, meanings, optional-ness (they are all optional), types and default values as the ones in .iterglyphs() and .draw(), except one thing: mode is 0 by default (mode: 0: the glyphs will have the same width and height)

Return value

Bitmap object

Description

Draw all the glyphs in the font (default) or in the specified codepoint range in the font, sorted by the specified order (or by the ascending codepoint order by default), to a Bitmap object.

This method is like a combined version of .iterglyphs()/.itercps() and .draw()/.drawcps().

note

Read the section for Bitmap's .tobytes() to know how to output your bitmap to BMP / PNG / JPEG files.