font_system.h File Reference

A system responsible for the management of bitmap and system fonts. More...

#include "identifiers/khandle.h"
#include "kresources/kresource_types.h"
#include "math/math_types.h"
#include "strings/kname.h"

Go to the source code of this file.

Data Structures
struct	system_font_variant
struct	font_system_bitmap_font_config
	The configuration for a bitmap font in the font system config. More...
struct	font_system_system_font_config
	The configuration for a system font in the font system config. More...
struct	font_system_config
	The configuration of the font system. Should be setup by the application during the boot process. More...
struct	font_geometry

Typedefs
typedef enum font_type	font_type
typedef struct system_font_variant	system_font_variant
typedef struct font_system_bitmap_font_config	font_system_bitmap_font_config
	The configuration for a bitmap font in the font system config. More...
typedef struct font_system_system_font_config	font_system_system_font_config
	The configuration for a system font in the font system config. More...
typedef struct font_system_config	font_system_config
	The configuration of the font system. Should be setup by the application during the boot process. More...
typedef struct font_geometry	font_geometry

Enumerations
enum	font_type { FONT_TYPE_BITMAP , FONT_TYPE_SYSTEM }

Functions
b8	font_system_deserialize_config (const char *config_str, font_system_config *out_config)
	Deserializes font system configuration from the provided string. More...
b8	font_system_initialize (u64 *memory_requirement, void *memory, font_system_config *config)
	Initializes the font system. As with other systems, this should be called twice; once to get the memory requirement (where memory = 0), and a second time passing allocated memory. More...
void	font_system_shutdown (struct font_system_state *state)
	Shuts down the font system. More...
KAPI b8	font_system_bitmap_font_acquire (struct font_system_state *state, kname name, khandle *out_font)
	Attempts to acquire a bitmap font of the given name. Must be a registered/loaded font. More...
KAPI b8	font_system_bitmap_font_load (struct font_system_state *state, kname asset_name, kname package_name)
	Attempts to load a bitmap font from the given named resource. More...
KAPI b8	font_system_bitmap_font_measure_string (struct font_system_state *state, khandle font, const char *text, vec2 *out_size)
	Measures the given string to find out how large it is at the widest/tallest point using the given bitmap font. More...
KAPI ktexture	font_system_bitmap_font_atlas_get (struct font_system_state *state, khandle font)
	Gets a pointer to the font's atlas. More...
KAPI f32	font_system_bitmap_font_line_height_get (struct font_system_state *state, khandle font)
	Gets the line height of the given font. More...
KAPI b8	font_system_bitmap_font_generate_geometry (struct font_system_state *state, khandle font, const char *text, font_geometry *out_geometry)
	Generates geometry data for a bitmap font. More...
KAPI b8	font_system_system_font_acquire (struct font_system_state *state, kname name, u16 font_size, system_font_variant *out_variant)
	Attempts to acquire a system font variant of the given name and size. Must be a registered/loaded font. More...
KAPI b8	font_system_system_font_load (struct font_system_state *state, kname resource_name, kname package_name, u16 default_size)
	Attempts to load a system font from the given named resource. More...
KAPI b8	font_system_system_font_verify_atlas (struct font_system_state *state, system_font_variant variant, const char *text)
	Verifies the atlas of the provided system font contains the characters in text. More...
KAPI b8	font_system_system_font_measure_string (struct font_system_state *state, system_font_variant variant, const char *text, vec2 *out_size)
	Measures the given string to find out how large it is at the widest/tallest point using the given system font. More...
KAPI f32	font_system_system_font_line_height_get (struct font_system_state *state, system_font_variant variant)
	Gets the line height of the given font. More...
KAPI b8	font_system_system_font_generate_geometry (struct font_system_state *state, system_font_variant variant, const char *text, font_geometry *out_geometry)
	Generates geometry data for a system font variant. More...
KAPI ktexture	font_system_system_font_atlas_get (struct font_system_state *state, system_font_variant variant)
	Gets a pointer to the font's atlas. More...

Detailed Description

A system responsible for the management of bitmap and system fonts.

Author

Travis Vroman (travi.nosp@m.s@ko.nosp@m.hieng.nosp@m.ine..nosp@m.com)

Version

2.0

Date

2023-01-18

Copyright

Kohi Game Engine is Copyright (c) Travis Vroman 2021-2024

A "bitmap" font uses an image containing pre-rendered glyphs which are then referenced in an internal lookup table by character codepoint. The display of characters for this font type is thus limited to characters contained within the image and configuration asset.

A "system" font uses a .ttf or .ttc font file and generates glyphs to an internal atlas on the fly, as needed (although standard ascii characters are rendered to it by default). Display of characters is limited only by those contained in the font. System fonts have "variants", one per font-size (i.e. a font size of 19 and a size of 20 would be unique variants). Each variant keeps its own internal atlas and list of codepoints contained, based on the needs of the string being rendered. These can be updated on the fly. See font_system_system_font_verify_atlas().

Typedef Documentation

font_geometry

typedef struct font_geometry font_geometry

Geometry generated from either a bitmap or system font.

font_system_bitmap_font_config

typedef struct font_system_bitmap_font_config font_system_bitmap_font_config

The configuration for a bitmap font in the font system config.

font_system_config

typedef struct font_system_config font_system_config

The configuration of the font system. Should be setup by the application during the boot process.

font_system_system_font_config

typedef struct font_system_system_font_config font_system_system_font_config

The configuration for a system font in the font system config.

font_type

typedef enum font_type font_type

system_font_variant

typedef struct system_font_variant system_font_variant

Represents a system font size variant and its "base" font. This is used to acquire a system font and its size variant, and contains handles to both.

Enumeration Type Documentation

font_type

enum font_type

Enumerator
FONT_TYPE_BITMAP
FONT_TYPE_SYSTEM

Function Documentation

font_system_bitmap_font_acquire()

KAPI b8 font_system_bitmap_font_acquire	(	struct font_system_state *	state,
		kname	name,
		khandle *	out_font
	)

Attempts to acquire a bitmap font of the given name. Must be a registered/loaded font.

Parameters

state	A pointer to the font system state.
name	The name of the font to acquire.
out_font	A pointer to hold a handle to bitmap font if successful. Required.

Returns

True on load success; otherwise false.

font_system_bitmap_font_atlas_get()

KAPI ktexture font_system_bitmap_font_atlas_get	(	struct font_system_state *	state,
		khandle	font
	)

Gets a pointer to the font's atlas.

Parameters

state	A pointer to the font system state.
font	A handle to the bitmap font to use for measuring.

Returns

A pointer to the font's atlas if successful; otherwise 0.

font_system_bitmap_font_generate_geometry()

KAPI b8 font_system_bitmap_font_generate_geometry	(	struct font_system_state *	state,
		khandle	font,
		const char *	text,
		font_geometry *	out_geometry
	)

Generates geometry data for a bitmap font.

Parameters

state	A pointer to the font system state.
font	A handle to the bitmap font to use for generation.
text	The text to use for generation.
out_size	A pointer to hold the generated font geometry, if successful. Required.

Returns

True on success; otherwise false.

font_system_bitmap_font_line_height_get()

KAPI f32 font_system_bitmap_font_line_height_get	(	struct font_system_state *	state,
		khandle	font
	)

Gets the line height of the given font.

Parameters

state	A pointer to the font system state.
font	A handle to the bitmap font to use.

Returns

The line height. Can return 0 if font is not found.

font_system_bitmap_font_load()

KAPI b8 font_system_bitmap_font_load	(	struct font_system_state *	state,
		kname	asset_name,
		kname	package_name
	)

Attempts to load a bitmap font from the given named resource.

Parameters

state	A pointer to the font system state.
asset_name	The name of the font asset to load.
package_name	The name of the package containing the resource.

Returns

True on load success; otherwise false.

font_system_bitmap_font_measure_string()

KAPI b8 font_system_bitmap_font_measure_string	(	struct font_system_state *	state,
		khandle	font,
		const char *	text,
		vec2 *	out_size
	)

Measures the given string to find out how large it is at the widest/tallest point using the given bitmap font.

Parameters

state	A pointer to the font system state.
font	A handle to the bitmap font to use for measuring.
text	The text to be measured.
out_size	A pointer to hold the measured size, if successful. Required.

Returns

True on success; otherwise false.

font_system_deserialize_config()

b8 font_system_deserialize_config	(	const char *	config_str,
		font_system_config *	out_config
	)

Deserializes font system configuration from the provided string.

Parameters

config_str	The configuration in string format to be deserialized. Required.
out_config	A pointer to hold the deserialized configuration. Required.

Returns

True if successful; otherwise false.

font_system_initialize()

b8 font_system_initialize	(	u64 *	memory_requirement,
		void *	memory,
		font_system_config *	config
	)

Initializes the font system. As with other systems, this should be called twice; once to get the memory requirement (where memory = 0), and a second time passing allocated memory.

Parameters

memory_requirement	A pointer to hold the memory requirement.
memory	The allocated memory for the system state.
config	The font system config.

Returns

True on success; otherwise false.

font_system_shutdown()

void font_system_shutdown

(

struct font_system_state *

state

)

Shuts down the font system.

Parameters

state

The system state memory.

font_system_system_font_acquire()

KAPI b8 font_system_system_font_acquire	(	struct font_system_state *	state,
		kname	name,
		u16	font_size,
		system_font_variant *	out_variant
	)

Attempts to acquire a system font variant of the given name and size. Must be a registered/loaded font.

Parameters

state	A pointer to the font system state.
name	The name of the font to acquire.
font_size	The font size. Ignored for bitmap fonts.
out_variant	A pointer to hold a system font variant, with handles to both the "base" font and the size variant. if successful. Required.

Returns

True if successful; otherwise false.

font_system_system_font_atlas_get()

KAPI ktexture font_system_system_font_atlas_get	(	struct font_system_state *	state,
		system_font_variant	variant
	)

Gets a pointer to the font's atlas.

Parameters

state	A pointer to the font system state.
variant	The system font variant to use for retrieval.

Returns

A pointer to the font's atlas if successful; otherwise 0.

font_system_system_font_generate_geometry()

KAPI b8 font_system_system_font_generate_geometry	(	struct font_system_state *	state,
		system_font_variant	variant,
		const char *	text,
		font_geometry *	out_geometry
	)

Generates geometry data for a system font variant.

Parameters

state	A pointer to the font system state.
variant	The system font variant to use for generation.
text	The text to use for generation.
out_size	A pointer to hold the generated font geometry, if successful. Required.

Returns

True on success; otherwise false.

font_system_system_font_line_height_get()

KAPI f32 font_system_system_font_line_height_get	(	struct font_system_state *	state,
		system_font_variant	variant
	)

Gets the line height of the given font.

Parameters

state	A pointer to the font system state.
variant	The system font variant to use.

Returns

The line height. Can return 0 if font is not found.

font_system_system_font_load()

KAPI b8 font_system_system_font_load	(	struct font_system_state *	state,
		kname	resource_name,
		kname	package_name,
		u16	default_size
	)

Attempts to load a system font from the given named resource.

Parameters

state	A pointer to the font system state.
resource_name	The name of the font resource to load.
package_name	The name of the package containing the resource.
default_size	The default font size. Clamped to an acceptable range.

Returns

True on load success; otherwise false.

font_system_system_font_measure_string()

KAPI b8 font_system_system_font_measure_string	(	struct font_system_state *	state,
		system_font_variant	variant,
		const char *	text,
		vec2 *	out_size
	)

Measures the given string to find out how large it is at the widest/tallest point using the given system font.

Parameters

state	A pointer to the font system state.
variant	The system font variant to use for measuring.
text	The text to be measured.
out_size	A pointer to hold the measured size, if successful. Required.

Returns

True on success; otherwise false.

font_system_system_font_verify_atlas()

KAPI b8 font_system_system_font_verify_atlas	(	struct font_system_state *	state,
		system_font_variant	variant,
		const char *	text
	)

Verifies the atlas of the provided system font contains the characters in text.

Parameters

state	A pointer to the font system state.
variant	The system font variant to verify.
text	The text containing the characters required.

Returns

True on success; otherwise false.