FontManager manages font rendering with OpenGL utilizing freetype and harfbuzz as a glyph rendering and layout back end. More...

#include <font_manager.h>

Detailed Description

FontManager manages font rendering with OpenGL utilizing freetype and harfbuzz as a glyph rendering and layout back end.

It opens speficied OpenType/TrueType font and rasterize to OpenGL texture. An application can use the generated texture for a text rendering.

Warning: The class is not threadsafe, it's expected to be only used from within OpenGL rendering thread.

Public Member Functions
	FontManager ()
	The default constructor for FontManager.

	FontManager (const mathfu::vec2i &cache_size, int32_t max_slices)
	Constructor for FontManager with a given cache size. More...

	~FontManager ()
	The destructor for FontManager.

bool	Open (const char *font_name)
	Open a font face, TTF, OT font. More...

bool	Open (const FontFamily &family)
	Open a font face, TTF, OT font by FontFamily structure. Use this version of API when opening a font with a family name, with a font collection index etc. More...

bool	Close (const char *font_name)
	Discard a font face that has been opened via `Open()`. More...

bool	Close (const FontFamily &family)
	Discard a font face that has been opened via `Open()`. Use this version of API when closeing a font opened with FontFamily. More...

bool	SelectFont (const char *font_name)
	Select the current font face. The font face will be used by a glyph rendering. More...

bool	SelectFont (const FontFamily &family)
	Select the current font face with a FontFamily.

bool	SelectFont (const char *font_names[], int32_t count)
	Select the current font faces with a fallback priority. More...

bool	SelectFont (const FontFamily family_names[], int32_t count)
	Select the current font faces with a fallback priority. More...

FontBuffer *	GetBuffer (const char *text, size_t length, const FontBufferParameters &parameters)
	Retrieve a vertex buffer for a font rendering using glyph cache. More...

FontBuffer *	GetHtmlBuffer (const char *html, const FontBufferParameters &parameters)
	Retrieve a vertex buffer for basic HTML rendering. More...

void	ReleaseBuffer (FontBuffer *buffer)
	Release the FonBuffer instance. If the FontBuffer is a reference counting buffer, the API decrements the reference count of the buffer and when it reaches 0, the buffer becomes invalid. If the buffer is non-reference counting buffer, the buffer is invalidated immediately and all references to the FontBuffer with same parameters become invalid. It is not a problem for those non-reference counting buffers because they are expected to create/fetch a buffer each render cycle.

void	RemapBuffers (bool flush_cache)
	Optionally flush the glyph cache and update existing FontBuffer's UV information. The API doesn't change a reference count of buffers. Note that current implementation references font instances and it is the caller's responsibility not to close font files in use. More...

bool	FontLoaded ()

void	StartLayoutPass ()
	Indicate a start of new layout pass. More...

bool	FlushAndUpdate ()
	Flush the existing glyph cache contents and start new layout pass. More...

void	FlushLayout ()
	Flush the existing FontBuffer in the cache. More...

bool	StartRenderPass ()
	Indicates a start of new render pass. More...

fplbase::Texture *	GetAtlasTexture (int32_t slice)

void	SetSizeSelector (std::function< int32_t(const int32_t)> selector)
	The user can supply a size selector function to adjust glyph sizes when storing a glyph cache entry. By doing that, multiple strings with slightly different sizes can share the same glyph cache entry, so that the user can reduce a total # of cached entries. More...

void	SetLocale (const char *locale)

const char *	GetLanguage ()

void	SetScript (const char *script)
	Set a script used for a script layout. More...

void	SetLayoutDirection (const TextLayoutDirection direction)
	Set a script layout direction. More...

void	SetupHyphenationPatternPath (const char *hyb_path)
	Set up hyphenation pattern path. Since the hyphenation pattern is different per locale, current locale needs to be set properly for the hyphnation to work. More...

TextLayoutDirection	GetLayoutDirection ()

HbFont *	GetCurrentFont ()

void	EnableColorGlyph ()
	Enable an use of color glyphs in supporting OTF/TTF font. The API will initialize internal glyph cache for color glyphs.

void	SetTextEllipsis (const char *ellipsis, EllipsisMode mode=kEllipsisModeTruncateCharacter)
	Set an ellipsis string used in label/edit widgets. More...

FontBufferStatus	GetFontBufferStatus (const FontBuffer &font_buffer) const
	Check a status of the font buffer. More...

Constructor & Destructor Documentation

flatui::FontManager::FontManager	(	const mathfu::vec2i &	cache_size,
		int32_t	max_slices
	)

Constructor for FontManager with a given cache size.

Note: The given size is rounded up to nearest power of 2 internally to be used as an OpenGL texture sizes.

Parameters

[in]	cache_size	The size of the cache, in pixels as x & y values.
[in]	max_slices	The maximum number of cache slices. When a glyph slice gets full with glyph entries, the cache allocates another slices for more cache spaces up to the value.

Member Function Documentation

bool flatui::FontManager::Close ( const char * font_name )

Discard a font face that has been opened via Open().

Parameters

[in] font_name A C-string in UTF-8 format representing the name of the font.

Returns: Returns true if the font was closed successfully. Otherwise it returns false.

bool flatui::FontManager::Close ( const FontFamily & family )

Discard a font face that has been opened via Open(). Use this version of API when closeing a font opened with FontFamily.

Parameters

[in] family A FontFamily structure indicating font parameters.

Returns: Returns true if the font was closed successfully. Otherwise it returns false.

bool flatui::FontManager::FlushAndUpdate ( )

inline

Flush the existing glyph cache contents and start new layout pass.

Call this API while in a layout pass when the glyph cache is fragmented.

void flatui::FontManager::FlushLayout ( )

inline

Flush the existing FontBuffer in the cache.

Call this API when FontBuffers are not used anymore.

bool flatui::FontManager::FontLoaded ( )

inline

Returns: Returns true if a font has been loaded. Otherwise it returns false.

fplbase::Texture* flatui::FontManager::GetAtlasTexture ( int32_t slice )

inline

Returns: Returns font atlas texture.

Parameters

[in] slice an index indicating an atlas texture. An index with kGlyphFormatsColor indicates that the slice is a multi channel buffer for color glyphs.

FontBuffer* flatui::FontManager::GetBuffer	(	const char *	text,
		size_t	length,
		const FontBufferParameters &	parameters
	)

Retrieve a vertex buffer for a font rendering using glyph cache.

Parameters

[in]	text	A C-string in UTF-8 format with the text for the FontBuffer.
[in]	length	The length of the text string.
[in]	parameters	The FontBufferParameters specifying the parameters for the FontBuffer.

Returns: Returns nullptr if the string does not fit in the glyph cache. When this happens, caller may flush the glyph cache with FlushAndUpdate() call and re-try the GetBuffer() call.

HbFont* flatui::FontManager::GetCurrentFont ( )

inline

Returns: Returns the current font.

FontBufferStatus flatui::FontManager::GetFontBufferStatus ( const FontBuffer & font_buffer ) const

Check a status of the font buffer.

Parameters

[in] font_buffer font buffer to check.

Returns: Returns a status of the FontBuffer if it's ready to use with current texture atlas contents.

FontBuffer* flatui::FontManager::GetHtmlBuffer	(	const char *	html,
		const FontBufferParameters &	parameters
	)

Retrieve a vertex buffer for basic HTML rendering.

Parameters

[in]	html	A C-string in UTF-8 format with the HTML to be rendered. Note that we support only a limited subset of HTML at the moment, including anchors, paragraphs, and breaks.
[in]	parameters	The FontBufferParameters specifying the parameters for the FontBuffer.

Note: call get_links() on the returned FontBuffer to receive information on where the anchor links are located, and the linked-to addresses.

Returns: Returns nullptr if the HTML does not fit in the glyph cache. When this happens, caller may flush the glyph cache with FlushAndUpdate() call and re-try the GetBuffer() call.

const char* flatui::FontManager::GetLanguage ( )

inline

Returns: Returns the current language setting as a std::string.

TextLayoutDirection flatui::FontManager::GetLayoutDirection ( )

inline

Returns: Returns the current layout direciton.

bool flatui::FontManager::Open ( const char * font_name )

Open a font face, TTF, OT font.

In this version it supports only single face at a time.

Parameters

[in] font_name A C-string in UTF-8 format representing the name of the font.

Returns: Returns false when failing to open font, such as a file open error, an invalid file format etc. Returns true if the font is opened successfully.

bool flatui::FontManager::Open ( const FontFamily & family )

Open a font face, TTF, OT font by FontFamily structure. Use this version of API when opening a font with a family name, with a font collection index etc.

Parameters

[in] family A FontFamily structure indicating font parameters.

Returns: Returns false when failing to open font, such as a file open error, an invalid file format etc. Returns true if the font is opened successfully.

void flatui::FontManager::RemapBuffers ( bool flush_cache )

Optionally flush the glyph cache and update existing FontBuffer's UV information. The API doesn't change a reference count of buffers. Note that current implementation references font instances and it is the caller's responsibility not to close font files in use.

Parameters

[in] flush_cache set true to flush existing glyph cache contents.

bool flatui::FontManager::SelectFont ( const char * font_name )

Select the current font face. The font face will be used by a glyph rendering.

Note: The font face needs to have been opened by Open().

Parameters

[in] font_name A C-string in UTF-8 format representing the name of the font.

Returns: Returns true if the font was selected successfully. Otherwise it returns false.

bool flatui::FontManager::SelectFont	(	const char *	font_names[],
		int32_t	count
	)

Select the current font faces with a fallback priority.

Parameters

[in]	font_names	An array of C-string corresponding to the name of the font. Font names in the array are stored in a priority order.
[in]	count	A count of font names in the array.

Returns: Returns true if the fonts were selected successfully. Otherwise it returns false.

bool flatui::FontManager::SelectFont	(	const FontFamily	family_names[],
		int32_t	count
	)

Select the current font faces with a fallback priority.

Parameters

[in]	family_names	An array of FontFamily structure that holds font family information.
[in]	count	A count of font family in the array.

Returns: Returns true if the fonts were selected successfully. Otherwise it returns false.

void flatui::FontManager::SetLayoutDirection ( const TextLayoutDirection direction )

inline

Set a script layout direction.

Parameters

[in] direction Text layout direction. TextLayoutDirectionLTR & TextLayoutDirectionRTL are supported.

void flatui::FontManager::SetLocale ( const char * locale )

Parameters

[in] locale A C-string corresponding to the of the language defined in ISO 639 and the country code difined in ISO 3166 separated by '-'. (e.g. 'en-US').

Note: The API sets language, script and layout direction used for following text renderings based on the locale.

void flatui::FontManager::SetScript ( const char * script )

Set a script used for a script layout.

Parameters

[in] language ISO 15924 based script code. Default setting is 'Latn' (Latin). For more detail, refer http://unicode.org/iso15924/iso15924-codes.html

void flatui::FontManager::SetSizeSelector ( std::function< int32_t(const int32_t)> selector )

inline

The user can supply a size selector function to adjust glyph sizes when storing a glyph cache entry. By doing that, multiple strings with slightly different sizes can share the same glyph cache entry, so that the user can reduce a total # of cached entries.

Parameters

[in] selector The callback argument is a request for the glyph size in pixels. The callback should return the desired glyph size that should be used for the glyph sizes.

void flatui::FontManager::SetTextEllipsis	(	const char *	ellipsis,
		EllipsisMode	mode = `kEllipsisModeTruncateCharacter`
	)

inline

Set an ellipsis string used in label/edit widgets.

Parameters

[in]	ellipsis	A C-string specifying characters used as an ellipsis. Can be multiple characters, typically '...'. When a string in a widget doesn't fit to the given size, the string is truncated to fit the ellipsis string appended at the end.
[in]	mode	A flag controlling appending behavior of the ellipsis. Default is kEllipsisModeTruncateCharacter.

Note: FontManager doesn't support dynamic change of the ellipsis string in current version. FontBuffer contents that has been created are not updated when the ellipsis string is changed.

void flatui::FontManager::SetupHyphenationPatternPath ( const char * hyb_path )

inline

Set up hyphenation pattern path. Since the hyphenation pattern is different per locale, current locale needs to be set properly for the hyphnation to work.

Parameters

[in] hyb_path A file path to search the hyb (dictionary files required for the hyphenation process. On Android, "/system/usr/hyphen-data" is the default search path.

void flatui::FontManager::StartLayoutPass ( )

Indicate a start of new layout pass.

Call the API each time the user starts a layout pass.

Note: The user of the font_manager class is expected to use the class in 2 passes: a layout pass and a render pass.

During the layout pass, the user invokes GetBuffer() calls to fetch all required glyphs into the cache. Once in the cache, the user can retrieve the size of the strings to position them.

Once the layout pass finishes, the user invokes StartRenderPass() to upload cache images to the atlas texture, and use the texture in the render pass. This design helps to minimize the frequency of the atlas texture upload.

bool flatui::FontManager::StartRenderPass ( )

inline

Indicates a start of new render pass.

Call the API each time the user starts a render pass.

The documentation for this class was generated from the following file:

font_manager.h

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation