Skip to content

fontstash #

Description

fontstash is a thin wrapper over https://github.com/memononen/fontstash, which in turn is a light-weight online font texture atlas builder written in C. It uses stb_truetype to render fonts on demand to a texture atlas.

Using another stb_truetype implementation

fontstash supplies an implementation of stb_truetype.h. Importing gg also imports fontstash. If another module defines STB_TRUETYPE_IMPLEMENTATION in a .c.v file, both implementations can end up in the same generated C translation unit. STBTT_STATIC gives functions internal linkage, but does not allow duplicate definitions in that unit.

Compile the other module's implementation and its stb calls in a separate C source file. Expose wrapper functions through a header, and link the source with #flag. For example, these files can live beside the other module's v.mod:

stb_bridge.c:

#include <stdlib.h>
#define STBTT_malloc(size, user) malloc(size)
#define STBTT_free(ptr, user) free(ptr)
#define STB_TRUETYPE_IMPLEMENTATION
#define STBTT_STATIC
#include "stb_truetype.h"
#include "stb_bridge.h"

int bridge_font_count(const unsigned char *data) {
    return stbtt_GetNumberOfFonts(data);
}

stb_bridge.h:

#ifndef STB_BRIDGE_H
#define STB_BRIDGE_H
int bridge_font_count(const unsigned char *data);
#endif

The module's .c.v file:

module fontbridge

#flag -I @VEXEROOT/thirdparty/fontstash
#flag @VMODROOT/stb_bridge.c
#include "@VMODROOT/stb_bridge.h"

fn C.bridge_font_count(data &u8) int

Keep STB_TRUETYPE_IMPLEMENTATION, custom allocator macros, and calls into that copy of stb_truetype inside stb_bridge.c. Do not #include that C source from V; #flag compiles it separately. Keep STBTT_STATIC there so its stb symbols do not collide at link time. Use a module-specific prefix for the exported wrapper names.

The bundled header defaults to fontstash's allocator macros. The example supplies standard C allocation hooks instead; a module can substitute its own matching allocator and deallocator.

This also lets each implementation retain its own allocation hooks. Removing an include or sharing one module's stb functions can silently select the wrong allocator.

Constants #

const invalid = C.FONS_INVALID

#flag -lfreetype

fn create_internal #

@[inline]
fn create_internal(params &C.FONSparams) &Context

create_internal returns a fontstash Context allocated on the heap.

See also: delete_internal

fn delete_internal #

@[inline]
fn delete_internal(s &Context)

delete_internal deletes and free memory of s fontstash Context.

See also: create_internal

fn Align.from #

fn Align.from[W](input W) !Align

from returns the Align value of an integer or of a field name, or an error if there is none.

fn Align.zero #

fn Align.zero() Align

zero returns a Align value with no flags set.

fn ErrorCode.from #

fn ErrorCode.from[W](input W) !ErrorCode

from returns the ErrorCode value of an integer or of a field name, or an error if there is none.

fn Flags.from #

fn Flags.from[W](input W) !Flags

from returns the Flags value of an integer or of a field name, or an error if there is none.

fn Flags.zero #

fn Flags.zero() Flags

zero returns a Flags value with no flags set.

type Context #

type Context = C.FONScontext

fn (Context) set_error_callback #

@[inline]
fn (s &Context) set_error_callback(callback fn (voidptr, i32, i32), uptr voidptr)

set_error_callback sets callback as a function to be called if fontstash encounter any errors. uptr can be used to pass custom userdata.

fn (Context) get_atlas_size #

@[inline]
fn (s &Context) get_atlas_size() (int, int)

get_atlas_size returns the current size of the texture atlas which the font is rendered to.

fn (Context) expand_atlas #

@[inline]
fn (s &Context) expand_atlas(width int, height int) int

expand_atlas expands the font texture atlas size to width x height.

fn (Context) reset_atlas #

@[inline]
fn (s &Context) reset_atlas(width int, height int) int

reset_atlas resets width x height of the font texture atlas.

fn (Context) get_font_by_name #

@[inline]
fn (s &Context) get_font_by_name(name string) int

get_font_by_name returns the id of the font with name or fontstash.invalid if no font with name could be found.

fn (Context) add_fallback_font #

@[inline]
fn (s &Context) add_fallback_font(base int, fallback int) int

add_fallback_font adds a fallback font to the base font id in the Context. fallback is expected to be the id of a previous, successfully, added font. add_fallback_font returns 1 on success, 0 otherwise.

fn (Context) add_font_mem #

@[inline]
fn (s &Context) add_font_mem(name string, data []u8, free_data bool) int

add_font_mem adds the font data located in memory to the Context. name is the human readable name for the font. free_data indicates if data should be freed after the font is added. The function returns the id of the font on success, fontstash.invalid otherwise.

fn (Context) push_state #

@[inline]
fn (s &Context) push_state()

push_state pushes a new state on the state stack. A state holds the current attributes of the rendering, attributes are things like color, size, the font in use, blur effect etc.

See also: pop_state See also: clear_state See also: set_size See also: set_color See also: set_spacing See also: set_blur See also: set_align See also: set_font

fn (Context) pop_state #

@[inline]
fn (s &Context) pop_state()

pop_state pops the current state from the state stack.

See also: push_state See also: clear_state

fn (Context) clear_state #

@[inline]
fn (s &Context) clear_state()

clear_state clears the current state.

See also: push_state See also: pop_state

fn (Context) set_size #

@[inline]
fn (s &Context) set_size(size f32)

set_size sets the font size to size on the active state.

See also: push_state See also: pop_state See also: clear_state

fn (Context) set_color #

@[inline]
fn (s &Context) set_color(color u32)

set_color sets the font color to color on the active state.

See also: push_state See also: pop_state See also: clear_state

fn (Context) set_spacing #

@[inline]
fn (s &Context) set_spacing(spacing f32)

set_spacing sets the font spacing to spacing on the active state.

See also: push_state See also: pop_state See also: clear_state

fn (Context) set_blur #

@[inline]
fn (s &Context) set_blur(blur f32)

set_blur sets the font blur effect to blur on the active state.

See also: push_state See also: pop_state See also: clear_state

fn (Context) set_align #

@[inline]
fn (s &Context) set_align(align int)

set_align sets the font aligning to align on the active state.

See also: push_state See also: pop_state See also: clear_state

fn (Context) set_alignment #

@[inline]
fn (s &Context) set_alignment(align Align)

set_alignment sets the font aligning to the align flags.

See also: push_state See also: pop_state See also: clear_state

fn (Context) set_font #

@[inline]
fn (s &Context) set_font(font_id int)

set_font sets the font used for this render on the active state. font_id is the id of the loaded font.

See also: push_state See also: pop_state See also: clear_state

fn (Context) draw_text #

@[inline]
fn (s &Context) draw_text(x f32, y f32, text string) f32

draw_text draws the text string at position x,y. The function returns the x coordinate of the resulting render.

fn (Context) text_bounds #

@[inline]
fn (s &Context) text_bounds(x f32, y f32, text string, bounds &f32) f32

text_bounds fills the bounds argument with the pixel dimensions of the rendered text at position x,y.

bounds is expected to be of type mut bounds := [4]f32{}. Call example: ctx.text_bounds(0, 0, 'example', &bounds[0]). bounds[0] is the x coordinate of the top-left point. bounds[1] is the y coordinate of the top-left point. bounds[2] is the x coordinate of the bottom-right point. bounds[3] is the y coordinate of the bottom-right point.

fn (Context) line_bounds #

@[inline]
fn (s &Context) line_bounds(y f32, miny &f32, maxy &f32)

line_bounds fills miny and maxy with the values of the minimum and maximum line bounds respectively.

fn (Context) vert_metrics #

@[inline]
fn (s &Context) vert_metrics(ascender &f32, descender &f32, lineh &f32)

vert_metrics assigns the respective values of ascender, descender and lineh.

fn (Context) text_iter_init #

@[inline]
fn (s &Context) text_iter_init(iter &C.FONStextIter, x f32, y f32, str &char, end &char) int

text_iter_init initializes the text iterator iter.

fn (Context) text_iter_next #

@[inline]
fn (s &Context) text_iter_next(iter &C.FONStextIter, quad &C.FONSquad) int

text_iter_next advances iter to the next quad.

fn (Context) get_texture_data #

@[inline]
fn (s &Context) get_texture_data(width &int, height &int) &u8

get_texture_data returns the current Context's raw texture data. width and height is assigned the size of the texture dimensions.

fn (Context) validate_texture #

@[inline]
fn (s &Context) validate_texture(dirty &int) int

validate_texture fills the dirty argument with the pixel dimensions of the dirty rectangle of the Context's raw texture, if any.

dirty is expected to be of type mut dirty := [4]int{}. Call example: is_dirty := ctx.validate_texture(&dirty[0]). The function returns 1 if the texture has a dirty rectangle, 0 otherwise.

fn (Context) draw_debug #

@[inline]
fn (s &Context) draw_debug(x f32, y f32)

draw_debug draws the stash texture for debugging.

enum Align #

@[flag]
enum Align {
	// Horizontal align
	left // Default
	center
	right
	// Vertical align
	top
	middle
	bottom
	baseline // Default
}

fn (Align) is_empty #

fn (e &Align) is_empty() bool

is_empty returns true if no flags are set.

fn (Align) has #

fn (e &Align) has(flag Align) bool

has returns true if any of the flags in flag are set.

fn (Align) all #

fn (e &Align) all(flag Align) bool

all returns true if all the flags in flag are set.

fn (Align) set #

fn (mut e Align) set(flag Align)

set sets the flags in flag.

fn (Align) set_all #

fn (mut e Align) set_all()

set_all sets all the flags.

fn (Align) clear #

fn (mut e Align) clear(flag Align)

clear clears the flags in flag.

fn (Align) clear_all #

fn (mut e Align) clear_all()

clear_all clears all the flags.

fn (Align) toggle #

fn (mut e Align) toggle(flag Align)

toggle flips the flags in flag.

enum ErrorCode #

enum ErrorCode {
	// Font atlas is full.
	atlas_full = 1
	// Scratch memory used to render glyphs is full, requested size reported in 'val', you may need to bump up FONS_SCRATCH_BUF_SIZE.
	scratch_full = 2
	// Calls to fonsPushState has created too large stack, if you need deep state stack bump up FONS_MAX_STATES.
	states_overflow = 3
	// Trying to pop too many states fonsPopState().
	states_underflow = 4
}

enum Flags #

@[flag]
enum Flags {
	top_left
	bottom_left
}

fn (Flags) is_empty #

fn (e &Flags) is_empty() bool

is_empty returns true if no flags are set.

fn (Flags) has #

fn (e &Flags) has(flag Flags) bool

has returns true if any of the flags in flag are set.

fn (Flags) all #

fn (e &Flags) all(flag Flags) bool

all returns true if all the flags in flag are set.

fn (Flags) set #

fn (mut e Flags) set(flag Flags)

set sets the flags in flag.

fn (Flags) set_all #

fn (mut e Flags) set_all()

set_all sets all the flags.

fn (Flags) clear #

fn (mut e Flags) clear(flag Flags)

clear clears the flags in flag.

fn (Flags) clear_all #

fn (mut e Flags) clear_all()

clear_all clears all the flags.

fn (Flags) toggle #

fn (mut e Flags) toggle(flag Flags)

toggle flips the flags in flag.

struct C.FONScontext #

struct C.FONScontext {
pub:
	params  C.FONSparams
	itw     f32
	ith     f32
	texData &u8 = unsafe { nil }
}

struct C.FONSfont #

struct C.FONSfont {}

struct C.FONSparams #

struct C.FONSparams {
	width   i32
	height  i32
	flags   char
	userPtr voidptr
	// int (*renderCreate)(void* uptr, int width, int height)
	renderCreate fn (uptr voidptr, width i32, height i32) i32 = unsafe { nil }
	// int (*renderResize)(void* uptr, int width, int height)
	renderResize fn (uptr voidptr, width i32, height i32) i32 = unsafe { nil }
	// void (*renderUpdate)(void* uptr, int* rect, const unsigned char* data)
	renderUpdate fn (uptr voidptr, rect &i32, data &u8) = unsafe { nil }
	// void (*renderDraw)(void* uptr, const float* verts, const float* tcoords, const unsigned int* colors, int nverts)
	renderDraw fn (uptr voidptr, verts &f32, tcoords &f32, colors &u32, nverts i32) = unsafe { nil }
	// void (*renderDelete)(void* uptr)
	renderDelete fn (uptr voidptr) = unsafe { nil }
}

struct C.FONSquad #

struct C.FONSquad {
	x0 f32
	y0 f32
	s0 f32
	t0 f32
	x1 f32
	y1 f32
	s1 f32
	t1 f32
}

struct C.FONStextIter #

struct C.FONStextIter {
	x              f32
	y              f32
	nextx          f32
	nexty          f32
	scale          f32
	spacing        f32
	codepoint      u32
	isize          i16
	iblur          i16
	font           &C.FONSfont = unsafe { nil }
	prevGlyphIndex i32
	str            &u8
	next           &u8
	end            &u8
	utf8state      u32
}