engine.h File Reference

#include <stdint.h>
#include <stdbool.h>
#include "uchar_helper.h"
#include "common.h"
#include "encoding.h"
#include "engine_properties.h"
#include "library.h"
#include "macros.h"
#include "script_direction.h"
#include "text_properties.h"

Include dependency graph for engine.h:

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

Go to the source code of this file.

Typedefs
typedef struct CobbletextEngine	CobbletextEngine
	Opaque handle to a layout and render engine. More...

Functions
CobbletextEngine *	cobbletext_engine_new (CobbletextLibrary *library)
	Creates a new layout engine. More...
void	cobbletext_engine_delete (CobbletextEngine *engine)
	Frees the engine. More...
const struct CobbletextEngineProperties *	cobbletext_engine_get_properties (CobbletextEngine *engine)
	Returns the engine properties. More...
void	cobbletext_engine_set_properties (CobbletextEngine *engine, const struct CobbletextEngineProperties *properties)
	Sets engine properties. More...
const struct CobbletextTextProperties *	cobbletext_engine_get_text_properties (CobbletextEngine *engine)
	Returns the current text properties. More...
void	cobbletext_engine_set_text_properties (CobbletextEngine *engine, const struct CobbletextTextProperties *text_properties)
	Sets the current text properties. More...
void	cobbletext_engine_add_text (CobbletextEngine *engine, const uint8_t *data, int32_t length, CobbletextEncoding encoding)
	Append encoded bytes to the text buffer. More...
void	cobbletext_engine_add_text_utf8 (CobbletextEngine *engine, const char *text, int32_t length)
	Append UTF-8 code units to the text buffer. More...
void	cobbletext_engine_add_text_utf16 (CobbletextEngine *engine, const CobbletextChar16 *text, int32_t length)
	Append UTF-16 code units to the text buffer. More...
void	cobbletext_engine_add_text_utf32 (CobbletextEngine *engine, const CobbletextChar32 *text, int32_t length)
	Append UTF-32 code units to the text buffer. More...
void	cobbletext_engine_add_inline_object (CobbletextEngine *engine, CobbletextInlineObjectID id, uint32_t width, uint32_t height)
	Append a placeholder for an object to the text buffer. More...
void	cobbletext_engine_clear (CobbletextEngine *engine)
	Empty the text buffer. More...
void	cobbletext_engine_clear_tiles (CobbletextEngine *engine)
	Clear associated tiles and glyphs. More...
void	cobbletext_engine_lay_out (CobbletextEngine *engine)
	Process and shape the text. More...
bool	cobbletext_engine_tiles_valid (CobbletextEngine *engine)
	Returns whether the associated glyphs to this engine is not stale. More...
void	cobbletext_engine_rasterize (CobbletextEngine *engine)
	Convert the glyphs required by this engine to coverages maps for drawing the text. More...
bool	cobbletext_engine_pack_tiles (CobbletextEngine *engine, uint32_t width, uint32_t height)
	Texture pack the associated glyphs. More...
void	cobbletext_engine_prepare_tiles (CobbletextEngine *engine)
	Prepares an array of tiles required for getting glyph images. More...
uint32_t	cobbletext_engine_get_tile_count (CobbletextEngine *engine)
	Returns the number of tiles in the tiles array. More...
const struct CobbletextTileInfo **	cobbletext_engine_get_tiles (CobbletextEngine *engine)
	Returns the array of tiles. More...
void	cobbletext_engine_prepare_advances (CobbletextEngine *engine)
	Prepare an array of advances required for positioning glyphs. More...
uint32_t	cobbletext_engine_get_advance_count (CobbletextEngine *engine)
	Return the number advances in the advances array. More...
const struct CobbletextAdvanceInfo **	cobbletext_engine_get_advances (CobbletextEngine *engine)
	Return the advances array. More...
const struct CobbletextOutputInfo *	cobbletext_engine_get_output_info (CobbletextEngine *engine)
	Returns information about the lay out operation. More...

Typedef Documentation

CobbletextEngine

typedef struct CobbletextEngine CobbletextEngine

Opaque handle to a layout and render engine.

Use cobbletext_engine_new() to create one.

An engine is used repeatedly to process text.

You can have multiple engines such as one engine for GUI elements that do not change frequently and multiple engines for user chat room messages.

Function Documentation

cobbletext_engine_add_inline_object()

void cobbletext_engine_add_inline_object	(	CobbletextEngine *	engine,
		CobbletextInlineObjectID	id,
		uint32_t	width,
		uint32_t	height
	)

Append a placeholder for an object to the text buffer.

Parameters

id	A user-provided value.
width	Width in pixels of the object.
height	Height in pixels of the object.

cobbletext_engine_add_text()

void cobbletext_engine_add_text	(	CobbletextEngine *	engine,
		const uint8_t *	data,
		int32_t	length,
		CobbletextEncoding	encoding
	)

Append encoded bytes to the text buffer.

Parameters

data	Encoded bytes.
length	Non-negative size of the given bytes.
encoding	Encoding of the bytes.

cobbletext_engine_add_text_utf16()

void cobbletext_engine_add_text_utf16	(	CobbletextEngine *	engine,
		const CobbletextChar16 *	text,
		int32_t	length
	)

Append UTF-16 code units to the text buffer.

Parameters

text	UTF-16 code units.
length	Number of code units, otherwise, negative value to detect null terminator.

cobbletext_engine_add_text_utf32()

void cobbletext_engine_add_text_utf32	(	CobbletextEngine *	engine,
		const CobbletextChar32 *	text,
		int32_t	length
	)

Append UTF-32 code units to the text buffer.

Parameters

text	UTF-32 code units.
length	Number of code units, otherwise, negative value to detect null terminator.

cobbletext_engine_add_text_utf8()

void cobbletext_engine_add_text_utf8	(	CobbletextEngine *	engine,
		const char *	text,
		int32_t	length
	)

Append UTF-8 code units to the text buffer.

Parameters

text	UTF-8 code units.
length	Number of code units, otherwise, negative value to detect null terminator.

cobbletext_engine_clear()

void cobbletext_engine_clear

(

CobbletextEngine *

engine

)

Empty the text buffer.

This empties the text buffer so the engine can be used to process anther set of text. The properties are not reset and tiles are not cleared.

cobbletext_engine_clear_tiles()

void cobbletext_engine_clear_tiles

(

CobbletextEngine *

engine

)

Clear associated tiles and glyphs.

The library context caches glyphs until no engine has a reference to them. This function can be called to reduce memory usage or clear a full texture atlas. This is especially important if your text sources are from user generated content.

This function doesn't affect properties or buffered text, and does not affect other engines. If you have associated data structures, such as a texture atlas, remember to clear those too.

cobbletext_engine_delete()

void cobbletext_engine_delete

(

CobbletextEngine *

engine

)

Frees the engine.

cobbletext_engine_get_advance_count()

uint32_t cobbletext_engine_get_advance_count

(

CobbletextEngine *

engine

)

Return the number advances in the advances array.

Precondition

Call cobbletext_engine_prepare_advances().

cobbletext_engine_get_advances()

const struct CobbletextAdvanceInfo** cobbletext_engine_get_advances

(

CobbletextEngine *

engine

)

Return the advances array.

• Do not free.
• Valid until the next call (excluding getters).

cobbletext_engine_get_output_info()

const struct CobbletextOutputInfo* cobbletext_engine_get_output_info

(

CobbletextEngine *

engine

)

Returns information about the lay out operation.

• Do not free.
• Valid until the next call (excluding getters).

cobbletext_engine_get_properties()

const struct CobbletextEngineProperties* cobbletext_engine_get_properties

(

CobbletextEngine *

engine

)

Returns the engine properties.

• Never null.
• Do not free.
• Owned by engine.

cobbletext_engine_get_text_properties()

const struct CobbletextTextProperties* cobbletext_engine_get_text_properties

(

CobbletextEngine *

engine

)

Returns the current text properties.

• Never null.
• Do not free.
• Owned by engine.

cobbletext_engine_get_tile_count()

uint32_t cobbletext_engine_get_tile_count

(

CobbletextEngine *

engine

)

Returns the number of tiles in the tiles array.

Precondition

Call cobbletext_engine_prepare_tiles().

cobbletext_engine_get_tiles()

const struct CobbletextTileInfo** cobbletext_engine_get_tiles

(

CobbletextEngine *

engine

)

Returns the array of tiles.

Precondition

Call cobbletext_engine_prepare_tiles().

• Do not free.
• Valid until the next call (excluding getters).

cobbletext_engine_lay_out()

void cobbletext_engine_lay_out

(

CobbletextEngine *

engine

)

Process and shape the text.

• Can error.

cobbletext_engine_new()

CobbletextEngine* cobbletext_engine_new

(

CobbletextLibrary *

library

)

Creates a new layout engine.

• Can error.
• Free only using library.
• Null on error.

cobbletext_engine_pack_tiles()

bool cobbletext_engine_pack_tiles	(	CobbletextEngine *	engine,
		uint32_t	width,
		uint32_t	height
	)

Texture pack the associated glyphs.

Returns

true if the glyphs won't fit within the texture size, false if everything is OK.

cobbletext_engine_prepare_advances()

void cobbletext_engine_prepare_advances

(

CobbletextEngine *

engine

)

Prepare an array of advances required for positioning glyphs.

• Can error

cobbletext_engine_prepare_tiles()

void cobbletext_engine_prepare_tiles

(

CobbletextEngine *

engine

)

Prepares an array of tiles required for getting glyph images.

If you have rasterized the glyphs, use cobbletext_library_get_glyph_info() to retreive the images.

• Can error.

cobbletext_engine_rasterize()

void cobbletext_engine_rasterize

(

CobbletextEngine *

engine

)

Convert the glyphs required by this engine to coverages maps for drawing the text.

To get the glyphs needed, use cobbletext_engine_prepare_tiles().

• Can error.

cobbletext_engine_set_properties()

void cobbletext_engine_set_properties	(	CobbletextEngine *	engine,
		const struct CobbletextEngineProperties *	properties
	)

Sets engine properties.

• Parameters

  properties

  The properties to be applied. Fields will be copied.

cobbletext_engine_set_text_properties()

void cobbletext_engine_set_text_properties	(	CobbletextEngine *	engine,
		const struct CobbletextTextProperties *	text_properties
	)

Sets the current text properties.

The propreties will be applied to subsequent text.

Parameters

text_properties

The properties to be applied. Fields will be copied.

cobbletext_engine_tiles_valid()

bool cobbletext_engine_tiles_valid

(

CobbletextEngine *

engine

)

Returns whether the associated glyphs to this engine is not stale.

If the value is true, then a call to cobbletext_engine_rasterize() and cobbletext_engine_pack_tiles() is not required.

If the value is false, a new tile and glyph as been associated with this engine instance. If you're using a texture atlas, you will need to rebuild your texture by adding additional or replacing existing tile metadata, and redrawing the entire texture.

Precondition

Call cobbletext_engine_lay_out()