1.1.0
Classes | Functions
Font

All the functions and types that deal with fonts and font-cooking. More...

Classes

class  fc::font
 A wrapper class for fc_font. More...
 
struct  fc_font
 A fc_font struct represents all data and metadata about a font. More...
 

Functions

struct fc_fontfc_construct (uint8_t const *font_data, struct fc_font_size font_size, struct fc_color font_color)
 Constructs a fc_font structure with the provided font, a size (either in pixels or points) and a font color in RGBA. More...
 
void fc_add (struct fc_font *font, uint32_t first, uint32_t last)
 Adds the given unicode range to the list of blocks to be cooked. You must add blocks before calling fc_cook. More...
 
void fc_cook (struct fc_font *font)
 Generates a bitmap and corresponding character information for a font. More...
 
struct fc_render_result fc_render (struct fc_font const *font, unsigned char const *text, size_t byte_count, struct fc_character_mapping *mapping)
 Produces a list of source and target rectangles that can be used as clipping rects (or UV maps) for the source texture and as target space coordinates. More...
 
struct fc_render_result fc_render_wrapped (struct fc_font const *font, unsigned char const *text, size_t byte_count, size_t line_width, float line_height_multiplier, enum fc_alignment alignment, struct fc_character_mapping *mapping)
 A shortcut for rendering and then wrapping the result. More...
 
void fc_destruct (struct fc_font *font)
 Destroys and frees all memory allocated by this library. More...
 
struct fc_font_size fc_get_font_size (struct fc_font const *font)
 Returns the font size set to this font at construction time. More...
 
struct fc_color fc_get_color (struct fc_font const *font)
 Returns the font color set to this font at construction time. More...
 
const uint8_t * fc_get_font_data (struct fc_font const *font)
 Returns the font data specified in fc_construct. More...
 
size_t fc_get_block_count (struct fc_font const *font)
 Returns count of added blocks in this font. More...
 
struct fc_unicode_block fc_get_block_at (struct fc_font const *font, size_t index)
 Returns a unicode block at the index position. More...
 
struct fc_pixels const * fc_get_pixels (struct fc_font const *font)
 Returns the pixel data after for a font generated after a fc_cook was called. More...
 
struct fc_size fc_get_space_metrics (struct fc_font const *font)
 Returns the space glyph width and height for this font at its specified size. More...
 

Detailed Description

All the functions and types that deal with fonts and font-cooking.

Function Documentation

◆ fc_construct()

struct fc_font* fc_construct ( uint8_t const *  font_data,
struct fc_font_size  font_size,
struct fc_color  font_color 
)

Constructs a fc_font structure with the provided font, a size (either in pixels or points) and a font color in RGBA.

It does not have any pixel data yet, you need to call fc_add to add unicode ranges and fc_cook to produce a 4 byte-per-pixel, RGBA, bitmap.

Example

// fully reads a file to memory and returns a pointer to it
uint8_t * read_file(char const * path);
void main() {
uint8_t * font_buffer = read_file("times.ttf"); // replace with real font path
struct fc_font * font = fc_construct(font_buffer, fc_px(12), fc_color_red);
// font is ready to be used
}
Parameters
font_dataA pointer to the in-memory font-data (it will NOT be managed nor free'd by font-chef).
font_sizeA size either in pixels or points to apply when packing
font_colorThe color of the characters in the rendered bitmap
Examples
main.c.

◆ fc_add()

void fc_add ( struct fc_font font,
uint32_t  first,
uint32_t  last 
)

Adds the given unicode range to the list of blocks to be cooked. You must add blocks before calling fc_cook.

Note that calling this function multiple times with the same block will add the same block again (although resulting image won't have duplicated blocks).

Also note that no overlapping management is done.

If you call this function after calling fc_cook, you will need to call fc_cook again. It is advised not to do this, add all the ranges you will be using before.

Example

void main() {
struct fc_font * font; // suppose already initialized with fc_construct
fc_add(font, fc_unicode_block_basic_latin.fist, fc_unicode_block_basic_latin.last);
fc_add(font, fc_unicode_block_latin_1_supplement.fist, fc_unicode_block_latin_1_supplement.last);
// font is ready for `fc_cook`
}
Parameters
fontA pointer to the fc_font instance
firstThe first unicode point in this block
lastThe last unicode point in this block
Examples
main.c.

◆ fc_cook()

void fc_cook ( struct fc_font font)

Generates a bitmap and corresponding character information for a font.

It uses all blocks added with fc_add to generate a bitmap that later can be used to render text with fc_render. You must call fc_add before calling this function.

If you call fc_add after calling this function, you will need to call call it again. It is advisable to call fc_cook just once.

Example

// suppose this creates a 4bpp texture from pixel data
void * create_texture(void * pixel_data, size_t width, size_t height);
void main() {
struct fc_font * font; // suppose `fc_construct` and `fc_add` was called
fc_cook(&font);
void * texutre = create_texture(
fc_get_pixels(font)->data,
fc_get_pixels(font)->dimensions
);
// now you're ready for `fc_render`
}
Parameters
fontA pointer to a fc_font value to generate pixels and mapping
Examples
main.c.

◆ fc_render()

struct fc_render_result fc_render ( struct fc_font const *  font,
unsigned char const *  text,
size_t  byte_count,
struct fc_character_mapping mapping 
)

Produces a list of source and target rectangles that can be used as clipping rects (or UV maps) for the source texture and as target space coordinates.

This function uses data produced by fc_cook and information inside the font data to map all the characters passed in to a list of source and target coordinates. It also takes in consideration the kerning for each character pair.

Also observe that the source and target rect is in pixel coordinates (from 0,0 to w,h), not from 0 to 1

** Adjusting baseline ** Baseline is the line (a y coordinate) that the characters will extend above and below it (e.g, observe the letter "g"). Font Chef produces destination rectangles with a baseline y = 0. This means that before rendering, you will have to add the desired baseline to both top and bottom values of the destination rectangle.

Example

// suppose a function that renders a texture clipped by `src` at coordinates `dst`
void render_clip(void * texture, fc_rect src, fc_rect dst);
void main() {
struct fc_font * font; // suppose `fc_construct`, `fc_add` and `fc_cook` already called
void * texture; // suppose texture created as in `fc_cook` examples
struct fc_character_mapping mapping[13];
char const * hello_world = "Hello, World!";
int glyph_count = fc_render(font, hello_world, 13, &mapping);
for (int i = 0; i < glyph_count; ++i) {
render_clip(texture, mapping[i].source, mapping[i].destination);
}
}
Parameters
fontA pointer to a fc_font value that will be used
textA pointer to a character array containing the text to map
byte_countHow many bytes are there in the character array
mappingAn array of fc_character_mapping values that must be at least byte_count long.
Returns
how many glyphs and lines were produced
See also
fc_render_result

◆ fc_render_wrapped()

struct fc_render_result fc_render_wrapped ( struct fc_font const *  font,
unsigned char const *  text,
size_t  byte_count,
size_t  line_width,
float  line_height_multiplier,
enum fc_alignment  alignment,
struct fc_character_mapping mapping 
)

A shortcut for rendering and then wrapping the result.

This function is a shorthand for calling fc_render and fc_wrap in sequence. It uses vertical metrics contained in the font to automatically deduce the font's default line height. See the documentation for fc_wrap for more information about wrapping.

Parameters
fontA pointer to a fc_font value that will be used
textA pointer to a character array containing the text to map
byte_countHow many bytes are there in the character array
line_widthThe maximum line width, in target/screen size (e.g, pixels)
line_height_multiplierA value that can be used to increase the line height/spacing
alignmentWhich aligment should lines follow
mappingAn array of fc_character_mapping values that must be at least byte_count long.
Returns
how many glyphs and lines were produced
See also
fc_render
fc_wrap
fc::render_result::wrap
Examples
main.c.

◆ fc_destruct()

void fc_destruct ( struct fc_font font)

Destroys and frees all memory allocated by this library.

You must call this once done with a fc_font value else your memory will leak. Using it beyond this point will most likely cause segmentation fault.

Parameters
fontPointer to the fc_font value that will be destroyed.
Examples
main.c.

◆ fc_get_font_size()

struct fc_font_size fc_get_font_size ( struct fc_font const *  font)

Returns the font size set to this font at construction time.

There is no function to set a font size because setting it after cooking has no effect, and sure enough someone would try it and file a bug report.

Parameters
fontA pointer to a fc_font value to get the size from
Returns
The font size specified

◆ fc_get_color()

struct fc_color fc_get_color ( struct fc_font const *  font)

Returns the font color set to this font at construction time.

There is no function to set a font color because setting it after cooking has no effect, and sure enough someone would try it and file a bug report.

Parameters
fontA pointer to a fc_font value to get the color from
Returns
The color specified

◆ fc_get_font_data()

const uint8_t* fc_get_font_data ( struct fc_font const *  font)

Returns the font data specified in fc_construct.

Warning
Font-cache does not know the font data buffer size (because it is irrelevant to it) so it is impossible to return it.
Parameters
fontThe font to get the font data from
Returns
The font data

◆ fc_get_block_count()

size_t fc_get_block_count ( struct fc_font const *  font)

Returns count of added blocks in this font.

Parameters
fontThe font to get the packed blocks count from
Returns
The count of added blocks

◆ fc_get_block_at()

struct fc_unicode_block fc_get_block_at ( struct fc_font const *  font,
size_t  index 
)

Returns a unicode block at the index position.

Parameters
fontThe font to get the packed block from
indexThe pack block index
Returns
A fc_unicode_block value containing the block information

◆ fc_get_pixels()

struct fc_pixels const* fc_get_pixels ( struct fc_font const *  font)

Returns the pixel data after for a font generated after a fc_cook was called.

Parameters
fontThe font to get the pixel data from
Returns
A value of fc_pixels
Examples
main.c.

◆ fc_get_space_metrics()

struct fc_size fc_get_space_metrics ( struct fc_font const *  font)

Returns the space glyph width and height for this font at its specified size.

It considers both the left side bearing (space after previous character) and the actual glyph height. This is mostly useful when doing wrapping calculations.

Parameters
fontThe font to get the space metrics from
Returns
The width and height of a space glyph
fc_cook
void fc_cook(struct fc_font *font)
Generates a bitmap and corresponding character information for a font.
fc_color_red
struct fc_color const fc_color_red
RGBA: #FF0000FF
fc_construct
struct fc_font * fc_construct(uint8_t const *font_data, struct fc_font_size font_size, struct fc_color font_color)
Constructs a fc_font structure with the provided font, a size (either in pixels or points) and a font...
fc_font
A fc_font struct represents all data and metadata about a font.
fc_add
void fc_add(struct fc_font *font, uint32_t first, uint32_t last)
Adds the given unicode range to the list of blocks to be cooked. You must add blocks before calling f...
fc_character_mapping::source
struct fc_rect source
The source rectangle that should be used to clip the texture/surface.
Definition: character-mapping.h:38
fc_get_pixels
struct fc_pixels const * fc_get_pixels(struct fc_font const *font)
Returns the pixel data after for a font generated after a fc_cook was called.
fc_render
struct fc_render_result fc_render(struct fc_font const *font, unsigned char const *text, size_t byte_count, struct fc_character_mapping *mapping)
Produces a list of source and target rectangles that can be used as clipping rects (or UV maps) for t...
fc_rect
Represents a rectangle with left, top, right and bottom float values.
Definition: rect.h:33
fc_character_mapping
Specifies source and target rectangles to render the specified codepoint.
Definition: character-mapping.h:34
fc_px
struct fc_font_size fc_px(float value)
Constructs and returns a fc_size value specified as pixels.