library.h File Reference

#include "macros.h"

Include dependency graph for library.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct CobbletextLibrary	CobbletextLibrary
	Opaque handle to the library's context. More...

Functions
CobbletextLibrary *	cobbletext_library_new ()
	Returns a new library context. More...
void	cobbletext_library_delete (CobbletextLibrary *library)
	Frees a library context. More...
int32_t	cobbletext_get_error_code (CobbletextLibrary *library)
	Returns error code. More...
const char *	cobbletext_get_error_message (CobbletextLibrary *library)
	Returns a textual version of the error code. More...
void	cobbletext_clear_error (CobbletextLibrary *library)
	Clears any error code or error message. More...
CobbletextFontID	cobbletext_library_get_fallback_font (CobbletextLibrary *library)
	Returns the ID for the built-in fallback font when there is no font loaded. More...
CobbletextFontID	cobbletext_library_load_font (CobbletextLibrary *library, const char *path)
	Loads a font face from a file. More...
CobbletextFontID	cobbletext_library_load_font_bytes (CobbletextLibrary *library, const uint8_t *data, uint32_t length, int32_t face_index)
	Loads a font face from the given bytes of a font file. More...
void	cobbletext_library_set_font_alternative (CobbletextLibrary *library, CobbletextFontID font_id, CobbletextFontID fallback_font_id)
	Sets an alternative font to be used if glyphs are not in the font. More...
CobbletextFontID	cobbletext_library_get_font_alternative (CobbletextLibrary *library, CobbletextFontID font_id)
	Returns the alternative font for the given font. More...
const struct CobbletextFontInfo *	cobbletext_library_get_font_info (CobbletextLibrary *library, CobbletextFontID font)
	Returns information about a loaded font. More...
const struct CobbletextGlyphInfo *	cobbletext_library_get_glyph_info (CobbletextLibrary *library, CobbletextFontID glyph)
	Returns information about a glyph from a loaded font. More...

Typedef Documentation

CobbletextLibrary

typedef struct CobbletextLibrary CobbletextLibrary

Opaque handle to the library's context.

Use cobbletext_library_new() to create one.

Once you obtain a library context, you can use it to open a layout and render engine with cobbletext_engine_new().

Cobbletext and its dependencies is not thread safe. A library context can be created for each thread. Otherwise, a simple application will only need to use a single library context.

Cached glyphs are automatically freed from memory if no engine references them. Fonts cannot be closed at this time.

Function Documentation

cobbletext_clear_error()

void cobbletext_clear_error

(

CobbletextLibrary *

library

)

Clears any error code or error message.

cobbletext_get_error_code()

int32_t cobbletext_get_error_code

(

CobbletextLibrary *

library

)

Returns error code.

The return code is usually passed through from the libraries used by Cobbletext.

Returns

0 if there is no error, a non-zero value otherwise.

cobbletext_get_error_message()

const char* cobbletext_get_error_message

(

CobbletextLibrary *

library

)

Returns a textual version of the error code.

• Value is never null.
• Do not free.

cobbletext_library_delete()

void cobbletext_library_delete

(

CobbletextLibrary *

library

)

Frees a library context.

cobbletext_library_get_fallback_font()

CobbletextFontID cobbletext_library_get_fallback_font

(

CobbletextLibrary *

library

)

Returns the ID for the built-in fallback font when there is no font loaded.

cobbletext_library_get_font_alternative()

CobbletextFontID cobbletext_library_get_font_alternative	(	CobbletextLibrary *	library,
		CobbletextFontID	font_id
	)

Returns the alternative font for the given font.

Returns

A font ID if there is an alternative set, otherwise 0.

cobbletext_library_get_font_info()

const struct CobbletextFontInfo* cobbletext_library_get_font_info	(	CobbletextLibrary *	library,
		CobbletextFontID	font
	)

Returns information about a loaded font.

• Can error.
• Do not free.
• Valid until the next function call.

cobbletext_library_get_glyph_info()

const struct CobbletextGlyphInfo* cobbletext_library_get_glyph_info	(	CobbletextLibrary *	library,
		CobbletextFontID	glyph
	)

Returns information about a glyph from a loaded font.

• Can error.
• Do not free.
• Valid until the next function call.

cobbletext_library_load_font()

CobbletextFontID cobbletext_library_load_font	(	CobbletextLibrary *	library,
		const char *	path
	)

Loads a font face from a file.

Parameters

path	Filename of the font file. If the file has multiple faces, use the fragment notation by adding # and the face index such as myfont.ttc#0.

• Can error.

cobbletext_library_load_font_bytes()

CobbletextFontID cobbletext_library_load_font_bytes	(	CobbletextLibrary *	library,
		const uint8_t *	data,
		uint32_t	length,
		int32_t	face_index
	)

Loads a font face from the given bytes of a font file.

Parameters

data	Binary contents of a font file. Tbe value is copied.
length	Size in bytes.
face_index	Face index if the file has multiple faces. Use 0 if this parameter is irrelevant.

• Can error.

cobbletext_library_new()

CobbletextLibrary* cobbletext_library_new

(

)

Returns a new library context.

• Can error.
• Free only using library.
• Null on handle allocation error. Otherwise, not null.

cobbletext_library_set_font_alternative()

void cobbletext_library_set_font_alternative	(	CobbletextLibrary *	library,
		CobbletextFontID	font_id,
		CobbletextFontID	fallback_font_id
	)

Sets an alternative font to be used if glyphs are not in the font.

By default, the engine does not try another font if a font does not have the required glyphs. By specifying an alternative font, the engine will try to use another font. This is also known as font fallback.

This function can be used to chain multiple fonts so the engine can try them in order. You can also add the built-in fallback font at the of the chain to guarantee something will be drawn.

Parameters

font_id	The font in interest.
fallback_font_id	The alternative font to select when the font in interest does not have the required glyphs.