< GeeXLab Reference Guide />

gh_font library

Description

gh_font is the module that manages TrueType Fonts (TTF) or OpenType Fonts (OTF). This module is available on all platforms (Windows, Linux, macOS, Raspberry Pi and Tinker Board).

Number of functions: 24

gh_font.build_texture ()
gh_font.clear ()
gh_font.create ()
gh_font.create_from_buffer ()
gh_font.create_from_sqlite3_blob ()
gh_font.create_from_zip ()
gh_font.create_v2 ()
gh_font.create_v3 ()
gh_font.get_text_width ()
gh_font.get_text_width_w ()
gh_font.get_texture ()
gh_font.render ()
gh_font.set_scale ()
gh_font.text_2d ()
gh_font.text_2d_v2 ()
gh_font.text_3d ()
gh_font.update ()
gh_font.update_texture_2d_array_layer ()
gh_font.wtext_2d ()
gh_font.wtext_2d_v2 ()
gh_font.get_num_strings ()
gh_font.get_string_num_chars ()
gh_font.set_string_char_position_offset ()
gh_font.set_string_char_color_factor ()

build_texture

Description

Builds the font texture.

Syntax

gh_font.build_texture( font_id, tex_unit )

Languages

Parameters

font_id [ID]: font identifier
tex_unit [INTEGER]: texture unit

Return Values

This function has no return value(s).

Code sample


gh_font.build_texture(font_id, 0)

clear

Description

This function clears the draw text list. This function is used with dynamic texts.

Syntax

gh_font.clear( font_id )

Languages

Parameters

font_id [ID]: font identifier

Return Values

This function has no return value(s).

Code sample


gh_font.clear(font_id)
gh_font.text_2d(font_id, x, y, r, g, b, a, "Hello!")
gh_font.update(font_id, 0)
gh_font.render(font_id)

create

Description

Creates a font object from a TTF or an OTF file.

Syntax

font_id = gh_font.create( font_filename, font_height, font_tex_width, font_texture_height )

Languages

Parameters

font_filename [STRING]: absolute path of the TTF/OTF file
font_height [INTEGER]: height of the font
font_tex_width [INTEGER]: width in pixels of the texture font
font_texture_height [INTEGER]: height in pixels of the texture font

Return Values

font_id [ID]: font identifier

Code sample


local demo_dir = gh_utils.get_demo_dir()
font_id = gh_font.create(demo_dir .. "./data/kool.ttf", 24, 512, 512)

create_from_buffer

Description

Creates a font from a memory buffer.

Syntax

font_id = gh_font.create_from_buffer( buff_ptr, buff_size, font_height, font_tex_width, font_texture_height, char_offset_start, num_chars )

Languages

Parameters

buff_ptr [POINTER]: pointer to the buffer
buff_size [INTEGER]: size of the buffer in bytes
font_height [INTEGER]: height of the font
font_tex_width [INTEGER]: width in pixels of the texture font
font_texture_height [INTEGER]: height in pixels of the texture font
char_offset_start [INTEGER]: start char offset (0 … 254). Default value: 32
num_chars [INTEGER]: number of chars in the texture. Default value: 256

Return Values

font_id [ID]: font identifier

Code sample


local demo_dir = gh_utils.get_demo_dir()
filename = demo_dir .. "assets/arial.ttf"
buffer, buffer_size = gh_utils.file_buffer_create(filename)

font_id = gh_font.create_from_buffer(buffer, buffer_size, 24, 512, 512, 32, 256)

gh_utils.file_buffer_kill(buffer)

create_from_sqlite3_blob

Description

Creates a font from raw data stored a in a SQLite3 blob.

Syntax

font_id = gh_font.create_from_sqlite3_blob( db_id, column, font_height, font_tex_width, font_texture_height, char_offset_start, num_chars )

Languages

Parameters

db_id [ID]: database identifier
column [INTEGER]: index of the column
font_height [INTEGER]: height of the font
font_tex_width [INTEGER]: width in pixels of the texture font
font_texture_height [INTEGER]: height in pixels of the texture font
char_offset_start [INTEGER]: start char offset (0 … 254). Default value: 32
num_chars [INTEGER]: number of chars in the texture. Default value: 256

Return Values

font_id [ID]: font identifier

Code sample


font_id = gh_font.create_from_sqlite3_blob(db_id, column, 24, 512, 512, 32, 256)

create_from_zip

Description

Creates a font from a file stored in a zip archive.

Syntax

font_id = gh_font.create_from_zip( zip_filename, filename, font_height, font_tex_width, font_texture_height, char_offset_start, num_chars )

Languages

Parameters

zip_filename [STRING]: absolute path of the zip file
filename [STRING]: font file in the zip archive
font_height [INTEGER]: height of the font
font_tex_width [INTEGER]: width in pixels of the texture font
font_texture_height [INTEGER]: height in pixels of the texture font
char_offset_start [INTEGER]: start char offset (0 … 254). Default value: 32
num_chars [INTEGER]: number of chars in the texture. Default value: 256

Return Values

font_id [ID]: font identifier

Code sample


zip_filename = demo_dir .. "data.zip"
font_id = gh_font.create_from_zip_v1(zip_filename, "fonts/arial.ttf", 24, 512, 512, 32, 256)

create_v2

Description

Creates a font object from a built-in TrueType (TTF) font.

Syntax

font_id = gh_font.create_v2( font_name, font_height, font_tex_width, font_texture_height )

Languages

Parameters

font_name [ENUM]: the name of the built-in TTF font (see name in the code snippet)
font_height [INTEGER]: height of the font
font_tex_width [INTEGER]: width in pixels of the texture font
font_texture_height [INTEGER]: height in pixels of the texture font

Return Values

font_id [ID]: font identifier

Code sample


local built_in_fonts = {"roboto_bold", "roboto_medium", "roboto_medium_italic", "technott", "hacked", "top_secret", "timeless_bold", "vcr_osd_mono1"}

font_id = gh_font.create_v2(built_in_fonts[1], 24, 512, 512)

create_v3

Description

Creates a font object from a TTF or an OTF file. The range of characters that must be loaded is also specified. Useful to load fonts with Chinese characters for example.

Syntax

font_id = gh_font.create_v3( font_filename, font_height, font_tex_width, font_texture_height, char_offset_start, num_chars )

Languages

Parameters

font_filename [STRING]: absolute path of the TTF/OTF file
font_height [INTEGER]: height of the font
font_tex_width [INTEGER]: width in pixels of the texture font
font_texture_height [INTEGER]: height in pixels of the texture font
char_offset_start [INTEGER]: offset of the first character (default: 32)
num_chars [INTEGER]: number of characters (default: 256)

Return Values

font_id [ID]: font identifier

Code sample


char_offset_start = 32
num_chars = 256
font_id = gh_font.create(demo_dir .. "data/kool.ttf", 24, 512, 512, char_offset_start, num_chars)

get_text_width

Description

Returns the width of the text in pixels according to the TrueType font and the font size.

Syntax

width = gh_font.get_text_width( font_id, text )

Languages

Parameters

font_id [ID]: font identifier
text [STRING]: text

Return Values

width [INTEGER]: width of the text

Code sample


text_width = gh_font.get_text_width(font_id, "Hello!")

get_text_width_w

Description

Wide character / unicode version of get_text_width. Returns the width of the text in pixels according to the TrueType font and the font size.

Syntax

width = gh_font.get_text_width_w( font_id, text )

Languages

Parameters

font_id [ID]: font identifier
text [STRING]: text

Return Values

width [INTEGER]: width of the text

Code sample


text_width = gh_font.get_text_width_w(font_id, "Hello!")

get_texture

Description

Gets the front texture identifier.

Syntax

font_tex_id = gh_font.get_texture( font_id )

Languages

Parameters

font_id [ID]: font identifier

Return Values

font_tex_id [ID]: font texture identifier

Code sample


font_tex = gh_font.get_texture(font_id)
...
gh_texture.bind(font_tex, 0)

render

Description

Renders the font. Performs the real drawing.

Syntax

gh_font.render( font_id )

Languages

Parameters

font_id [ID]: font identifier

Return Values

This function has no return value(s).

Code sample


gh_font.render(font_id)

set_scale

Description

Sets the scale for rendering.

Syntax

gh_font.set_scale( font_id, scale )

Languages

Parameters

font_id [ID]: font identifier
scale [REAL]: scale factor (default: 1.0)

Return Values

This function has no return value(s).

Code sample


gh_font.set_scale(font_id, 2.0)

text_2d

Description

Sets a text in 2D. The text is added in a list and the real draw will occur later with a call to gh_font.render().

Syntax

gh_font.text_2d( font_id, x, y, r, g, b, a, text )

Languages

Parameters

font_id [ID]: font identifier
x, y [REAL]: start position of the text
r, g, b, a [REAL]: RGBA text color
text [STRING]: text

Return Values

This function has no return value(s).

Code sample


gh_font.text_2d(font_id, x, y, r, g, b, a, "Hello!")

text_2d_v2

Description

Like text_2d(), text_2d_v2() sets a text in 2D. But this function takes no position. It simply appends the text on the same line than the previous one.

Syntax

gh_font.text_2d_v2( font_id, r, g, b, a, text )

Languages

Parameters

font_id [ID]: font identifier
r, g, b, a [REAL]: RGBA text color
text [STRING]: text

Return Values

This function has no return value(s).

Code sample


gh_font.text_2d(font_id, x, y, r, g, b, a, "Hello...")
gh_font.text_2d_v2(font_id, r, g, b, a, " from GeeXLab!")

text_3d

Description

Sets a text in 3D. The text is added in a list and the real draw will occur later with a call to gh_font.render().

Syntax

gh_font.text_3d( font_id, x, y, z, r, g, b, a )

Languages

Parameters

font_id [ID]: font identifier
x, y, z [REAL]: start position of the text
r, g, b, a [REAL]: RGBA text color

Return Values

This function has no return value(s).

Code sample


gh_font.text_3d(font_id, x, y, z, r, g, b, a, "Hello!")

update

Description

Updates the font before the real rendering.

Syntax

gh_font.update( font_id, mapped_gpu_memory )

Languages

Parameters

font_id [ID]: font identifier
mapped_gpu_memory [BOOLEAN]: GPU memory mapping for direct updating: 1 (enabled) or 0 (disabled)

Return Values

This function has no return value(s).

Code sample


gh_font.clear(font_id)
gh_font.text_2d(font_id, x, y, r, g, b, a, "Hello!")
gh_font.update(font_id, 0)
gh_font.render(font_id)

update_texture_2d_array_layer

Description

Update a layer of a texture array with the font texture.

Syntax

gh_font.update_texture_2d_array_layer( font_id, texarray_id, layer )

Languages

Parameters

font_id [ID]: font identifier
texarray_id [ID]: texture array identifier
layer [INTEGER]: index of the layer in the texture array

Return Values

This function has no return value(s).

Code sample


layer = 0
gh_font.update_texture_2d_array_layer(font_id, texarray_id, layer)

wtext_2d

Description

Sets a text in 2D. The text is added in a list and the real draw will occur later with a call to gh_font.render().

Syntax

gh_font.wtext_2d( font_id, x, y, r, g, b, a, text )

Languages

Parameters

font_id [ID]: font identifier
x, y [REAL]: start position of the text
r, g, b, a [REAL]: RGBA text color
text [STRING]: text

Return Values

This function has no return value(s).

Code sample


gh_font.wtext_2d(font_id, x, y, r, g, b, a, "Hello!")

wtext_2d_v2

Description

Like wtext_2d(), wtext_2d_v2() sets a text in 2D. But this function takes no position. It simply appends the text on the same line than the previous one.

Syntax

gh_font.wtext_2d_v2( font_id, r, g, b, a, text )

Languages

Parameters

font_id [ID]: font identifier
r, g, b, a [REAL]: RGBA text color
text [STRING]: text

Return Values

This function has no return value(s).

Code sample


gh_font.wtext_2d(font_id, x, y, r, g, b, a, "Hello...")
gh_font.wtext_2d_v2(font_id, r, g, b, a, " from GeeXLab!")

get_num_strings

Description

Returns the number of strings in a font (added with text_2d() for example) since the last call to gh_font_clear().

Syntax

num_strings = gh_font.get_num_strings( font_id )

Languages

Parameters

font_id [ID]: font identifier

Return Values

num_strings [INTEGER]: number of strings

Code sample


num_strings = gh_font.get_num_strings(font_id)

get_string_num_chars

Description

Returns the number of characters of a particular string of a font.

Syntax

num_chars = gh_font.get_string_num_chars( font_id, string_index )

Languages

Parameters

font_id [ID]: font identifier
string_index [INTEGER]: string index

Return Values

num_chars [INTEGER]: number of characters

Code sample


num_chars = gh_font.get_string_num_chars(font_id, string_index)

set_string_char_position_offset

Description

Translates a particular character with a {x, y, z} offset.

Syntax

gh_font.set_string_char_position_offset( font_id, string_index, char_index, x, y, z )

Languages

Parameters

font_id [ID]: font identifier
string_index [INTEGER]: string index
char_index [INTEGER]: character index
x, y, z [REAL]: offset vector

Return Values

This function has no return value(s).

Code sample


gh_font.set_string_char_position_offset(font_id, string_index, char_index, x, y, z)

set_string_char_color_factor

Description

Sets a color factor to a character. This color factor is multplied by the color of the string.

Syntax

gh_font.set_string_char_color_factor( font_id, string_index, char_index, r, g, b, a )

Languages

Parameters

font_id [ID]: font identifier
string_index [INTEGER]: string index
char_index [INTEGER]: character index
r, g, b, a [REAL]: color factor

Return Values

This function has no return value(s).

Code sample


gh_font.set_string_char_color_factor(font_id, string_index, char_index, r, g, b, a)

GeeXLab Rootard Guide | Downloads | Contact