Kanzi  3.9.4
Kanzi Engine API
kanzi::GlyphCache Class Reference

Glyph cache renders different characters on a texture with the font and font size that you use in your Kanzi application. More...

#include <kanzi/core.ui/font/glyph_cache.hpp>

Classes

struct  TextureCoordinates
 Coordinates to the position of a single glyph in a glyph cache texture. More...
 

Public Member Functions

void clear ()
 Removes all stored glyphs from the glyph cache. More...
 
TextureSharedPtr getTexture () const
 Returns the texture that the glyph cache uses. More...
 
 GlyphCache (TextureSharedPtr texture, FontFileSharedPtr font, float glyphSize)
 Constructor. More...
 
void remove (const GlyphKey &glyphKey)
 Removes a stored glyph from the glyph cache. More...
 
unsigned int retrieveMultipleTextureCoordinates (const GlyphKey *glyphKeys, unsigned int glyphCount, unsigned int stride, byte *outData)
 Gets the texture coordinates for multiple glyphs. More...
 
unsigned int retrieveMultipleTextureCoordinatesWithClipping (const GlyphKey *glyphKeys, unsigned int glyphCount, unsigned int stride, const float *clippingCoordinates, byte *outData)
 Gets the texture coordinates for multiple glyphs that can be partially clipped. More...
 
TextureCoordinates retrieveTextureCoordinates (const GlyphKey &glyphKey)
 Gets the texture coordinates for the given glyph. More...
 
TextureCoordinates retrieveTextureCoordinatesRecycling (const GlyphKey &glyphKey)
 Gets the texture coordinates for the given glyph. More...
 
 ~GlyphCache ()
 Destructor. More...
 

Detailed Description

Glyph cache renders different characters on a texture with the font and font size that you use in your Kanzi application.

The default size is 512 by 512 pixels. The upper size limit depends on the GPU, but is usually 2048 by 2048 pixels. To ensure optimal performance of your Kanzi application, adjust the size of the glyph cache so that the size of the glyph cache is large enough to fit all the glyphs that your Kanzi application uses. However, keep in mind that larger glyph cache consumes more memory.

If the glyph cache becomes full, Kanzi removes from the texture the least used glyphs to make room for the new glyphs. This decreases Kanzi application performance. To avoid a decrease in the performance, adjust the size of the glyph cache so that all glyphs fit into the glyph cache. You can fit more glyphs into the glyph cache by using smaller font sizes.

You can adjust the size of glyph cache textures using these application configuration properties:

You can retrieve the coordinates of the glyphs from a glyph cache. If Kanzi already rendered a certain glyph, when you retrieve the coordinates of that glyph, that does not trigger new rendering of that glyph. Kanzi creates a glyph cache for every font and font size combination.

To learn more about the glyph cache, in Kanzi documentation see Working with > Application configuration > Application configuration reference > Glyph cache texture size

Constructor & Destructor Documentation

◆ GlyphCache()

kanzi::GlyphCache::GlyphCache ( TextureSharedPtr  texture,
FontFileSharedPtr  font,
float  glyphSize 
)
explicit

Constructor.

Parameters
texturePointer to the texture that the glyph cache uses. Must be in the format GraphicsFormatLUMINANCE8_ALPHA8_UNORM.
fontPointer to the font that the glyph cache uses.
glyphSizeSize of the font in pixels that the glyph cache uses.

◆ ~GlyphCache()

kanzi::GlyphCache::~GlyphCache ( )

Destructor.

Member Function Documentation

◆ clear()

void kanzi::GlyphCache::clear ( )

Removes all stored glyphs from the glyph cache.

◆ remove()

void kanzi::GlyphCache::remove ( const GlyphKey glyphKey)

Removes a stored glyph from the glyph cache.

Parameters
glyphKeyGlyphKey of the glyph in the used font.

◆ retrieveTextureCoordinates()

TextureCoordinates kanzi::GlyphCache::retrieveTextureCoordinates ( const GlyphKey glyphKey)

Gets the texture coordinates for the given glyph.

If the glyph is not in the glyph cache texture, Kanzi renders it to that textures using the font that Kanzi used to create the glyph cache. If there is no room in the glyph cache for a new glyph, the texture coordinates are zero and TextureCoordinates::success is false.

Parameters
glyphKeyGlyphKey of the glyph in the used font.
Returns
Texture coordinates for the glyph.

◆ retrieveTextureCoordinatesRecycling()

TextureCoordinates kanzi::GlyphCache::retrieveTextureCoordinatesRecycling ( const GlyphKey glyphKey)

Gets the texture coordinates for the given glyph.

If the glyph is not in the glyph cache texture, Kanzi renders it to that texture using the font that Kanzi used to create the glyph cache. If there is no room left in the glyph cache for a new glyph, Kanzi replaces the least used glyphs with the new glyph.

Parameters
glyphKeyGlyphKey of the glyph in the used font.
Returns
Texture coordinates for the glyph.

◆ retrieveMultipleTextureCoordinates()

unsigned int kanzi::GlyphCache::retrieveMultipleTextureCoordinates ( const GlyphKey glyphKeys,
unsigned int  glyphCount,
unsigned int  stride,
byte outData 
)

Gets the texture coordinates for multiple glyphs.

If a glyph is not in the glyph cache texture, Kanzi renders it to that texture using the font that Kanzi used to create the glyph cache. Kanzi writes the 12 texture coordinates of a glyph to the output parameter outData. If there is no room left in the glyph cache for a new glyph, Kanzi does not write that and the following glyphs.

Parameters
glyphKeysPointer to the array containing multiple glyph keys. See GlyphKey,
glyphCountNumber of glyph indices in the array.
strideStride for the output array. Must be at least 2*sizeof(float).
outDataPointer to the byte array for the output data. For each glyph must have at least 2*6*sizeof(float) space.
Returns
The number of glyphs written to the output.

◆ retrieveMultipleTextureCoordinatesWithClipping()

unsigned int kanzi::GlyphCache::retrieveMultipleTextureCoordinatesWithClipping ( const GlyphKey glyphKeys,
unsigned int  glyphCount,
unsigned int  stride,
const float *  clippingCoordinates,
byte outData 
)

Gets the texture coordinates for multiple glyphs that can be partially clipped.

Parameters
glyphKeysPointer to the array containing multiple glyph keys. See GlyphKey,
glyphCountNumber of glyph indices in the array.
strideStride for the output array. Must be at least 2*sizeof(float).
clippingCoordinatesPointer to the array with clipping coordinates for the glyphs. Amount of clipping as fraction of glyph size, from the clipped edge. For each glyph: left, right, bottom, and top.
outDataPointer to the byte array for the output data. For each glyph must have at least 2*6*sizeof(float) space.
Returns
The number of glyphs written to the output.

◆ getTexture()

TextureSharedPtr kanzi::GlyphCache::getTexture ( ) const

Returns the texture that the glyph cache uses.

Returns
The texture used by the glyph cache.

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