Maintains a cache for rendered strings that helps avoid re-rendering strings that may need to be shown many times. More...

#include <BppStringCache.hpp>

Inheritance diagram for duds::ui::graphics::BppStringCache:

[legend]

Collaboration diagram for duds::ui::graphics::BppStringCache:

[legend]

Classes
struct	BppString
	Stores an image and the data used to create it using the font. More...

Public Member Functions
	BppStringCache (const BppFontSptr &font, unsigned int maxBytes=256 *1024, unsigned int maxStrings=-1)
	Creates a cache of rendered strings made using the given font. More...

	BppStringCache (BppFontSptr &&font, unsigned int maxBytes=256 *1024, unsigned int maxStrings=-1)
	Creates a cache of rendered strings made using the given font. More...

	BppStringCache (const std::string &path, unsigned int maxBytes=256 *1024, unsigned int maxStrings=-1)
	Creates a cache of rendered strings made using a font created from the given image archive path. More...

unsigned int	bytes () const
	Returns the total size in bytes of all the cached images. More...

void	clear ()
	Clears all text images from the cache. More...

const BppFontSptr &	font () const
	Returns the font object used by this cache to render text. More...

unsigned int	maxBytes () const
	Returns the maximum size of the cached images in bytes. More...

unsigned int	maxStrings () const
	Returns the maximum number of cached images. More...

unsigned int	strings () const
	Returns the number of currently stored cached strings. More...

ConstBppImageSptr	text (const std::string &str, BppFont::Flags flags=BppFont::AlignLeft)
	Returns an image of the requested string either from a pre-rendered item in the cache or by rendering a new image. More...

ConstBppImageSptr	text (const std::u32string &str, BppFont::Flags flags=BppFont::AlignLeft)
	Returns an image of the requested string either from a pre-rendered item in the cache or by rendering a new image. More...

Static Public Member Functions
static std::shared_ptr< BppStringCache >	make (const BppFontSptr &font, unsigned int maxBytes=256 *1024, unsigned int maxStrings=-1)
	Creates a cache of rendered strings made using the given font. More...

static std::shared_ptr< BppStringCache >	make (BppFontSptr &&font, unsigned int maxBytes=256 *1024, unsigned int maxStrings=-1)
	Creates a cache of rendered strings made using the given font. More...

static std::shared_ptr< BppStringCache >	make (const std::string &path, unsigned int maxBytes=256 *1024, unsigned int maxStrings=-1)
	Creates a cache of rendered strings made using a font created from the given image archive path. More...

Private Types
typedef boost::multi_index::multi_index_container< BppString, boost::multi_index::indexed_by< boost::multi_index::hashed_non_unique< boost::multi_index::tag< struct index_text >, boost::multi_index::composite_key< BppString, boost::multi_index::member< BppString, std::u32string, &BppString::text >, boost::multi_index::member< BppString, BppFont::Flags, &BppString::flags > > >, boost::multi_index::sequenced< boost::multi_index::tag< struct index_seq > > > >	Cache
	The container type for the rendered strings. More...

Private Attributes
duds::general::Spinlock	block
	Used for thread safety. More...

Cache	cache
	The cache of rendered strings. More...

unsigned int	curB = 0
	The current size of all rendered text images in the cache. More...

BppFontSptr	fnt
	The font to use for rendering. More...

unsigned int	maxB
	The maximum size of rendered text images, in bytes, the cache may hold. More...

unsigned int	maxS
	The maximum number of strings the cache may hold. More...

Detailed Description

Maintains a cache for rendered strings that helps avoid re-rendering strings that may need to be shown many times.

The cache is limited in size by the number of strings and the total size of all the rendered images in bytes. All operations are thread-safe.

Author: Jeff Jackowski

Examples:: rendertext.cpp, and st7920.cpp.

Definition at line 28 of file BppStringCache.hpp.

Member Typedef Documentation

◆ Cache

typedef boost::multi_index::multi_index_container< BppString, boost::multi_index::indexed_by< boost::multi_index::hashed_non_unique< boost::multi_index::tag<struct index_text>, boost::multi_index::composite_key< BppString, boost::multi_index::member< BppString, std::u32string, &BppString::text >, boost::multi_index::member< BppString, BppFont::Flags, &BppString::flags > > >, boost::multi_index::sequenced< boost::multi_index::tag<struct index_seq> > > > duds::ui::graphics::BppStringCache::Cache

private

The container type for the rendered strings.

It has two indices:

A combination of the string and the font rendering flags. Used to find existing items.
The sequence of access. Used to determine which item(s) to remove when the cache grows past its limits.

Definition at line 81 of file BppStringCache.hpp.

Constructor & Destructor Documentation

◆ BppStringCache() [1/3]

duds::ui::graphics::BppStringCache::BppStringCache	(	const BppFontSptr &	font,
		unsigned int	maxBytes = `256 * 1024`,
		unsigned int	maxStrings = `-1`
	)

Creates a cache of rendered strings made using the given font.

Parameters

font	The font to use to render the cached text.
maxBytes	The maximum size of the rendered string images in bytes. If this value is very low, even zero, then only one rendered image will be cached.
maxStrings	The maximum number of rendered strings that may be held by the cache. This value cannot be zero.

Exceptions

StringCacheZeroSize The cache size limits prevent any image from being kept in the cache. maxBytes is zero.

Definition at line 17 of file BppStringCache.cpp.

◆ BppStringCache() [2/3]

duds::ui::graphics::BppStringCache::BppStringCache	(	BppFontSptr &&	font,
		unsigned int	maxBytes = `256 * 1024`,
		unsigned int	maxStrings = `-1`
	)

Creates a cache of rendered strings made using the given font.

Parameters

font	The font to use to render the cached text. This object will take ownership of the font.
maxBytes	The maximum size of the rendered string images in bytes. If this value is very low, even zero, then only one rendered image will be cached.
maxStrings	The maximum number of rendered strings that may be held by the cache. This value cannot be zero.

Exceptions

StringCacheZeroSize The cache size limits prevent any image from being kept in the cache. maxBytes is zero.

Definition at line 27 of file BppStringCache.cpp.

◆ BppStringCache() [3/3]

duds::ui::graphics::BppStringCache::BppStringCache	(	const std::string &	path,
		unsigned int	maxBytes = `256 * 1024`,
		unsigned int	maxStrings = `-1`
	)

inline

Creates a cache of rendered strings made using a font created from the given image archive path.

Parameters

path	The image archive used to create the font that will be used to render the cached text. This object will take ownership of the font.
maxBytes	The maximum size of the rendered string images in bytes. If this value is very low, even zero, then only one rendered image will be cached.
maxStrings	The maximum number of rendered strings that may be held by the cache. This value cannot be zero.

Exceptions

StringCacheZeroSize	The cache size limits prevent any image from being kept in the cache. maxBytes is zero.
ImageArchiveStreamError	Failed to open the file.
ImageNotArchiveStreamError	The stream does not have an image archive stream.
ImageArchiveStreamTruncatedError	The stream appears to have an incomplete copy of the archive stream. Any images fully read prior to the error will be available.
ImageArchiveUnsupportedVersionError	The software does not support the claimed archive version.

Definition at line 163 of file BppStringCache.hpp.

Member Function Documentation

◆ bytes()

unsigned int duds::ui::graphics::BppStringCache::bytes ( ) const

inline

Returns the total size in bytes of all the cached images.

Examples:: st7920.cpp.

Definition at line 268 of file BppStringCache.hpp.

◆ clear()

void duds::ui::graphics::BppStringCache::clear ( )

Clears all text images from the cache.

Definition at line 37 of file BppStringCache.cpp.

Referenced by strings().

◆ font()

const BppFontSptr& duds::ui::graphics::BppStringCache::font ( ) const

inline

Returns the font object used by this cache to render text.

Definition at line 250 of file BppStringCache.hpp.

Referenced by make().

◆ make() [1/3]

static std::shared_ptr<BppStringCache> duds::ui::graphics::BppStringCache::make	(	const BppFontSptr &	font,
		unsigned int	maxBytes = `256 * 1024`,
		unsigned int	maxStrings = `-1`
	)

inlinestatic

Creates a cache of rendered strings made using the given font.

Parameters

font	The font to use to render the cached text.
maxBytes	The maximum size of the rendered string images in bytes. If this value is very low, even zero, then only one rendered image will be cached.
maxStrings	The maximum number of rendered strings that may be held by the cache. This value cannot be zero.

Exceptions

StringCacheZeroSize The cache size limits prevent any image from being kept in the cache. maxBytes is zero.

Examples:: bppmenu.cpp.

Definition at line 180 of file BppStringCache.hpp.

Referenced by duds::ui::graphics::BppFontPool::addWithCache().

◆ make() [2/3]

static std::shared_ptr<BppStringCache> duds::ui::graphics::BppStringCache::make	(	BppFontSptr &&	font,
		unsigned int	maxBytes = `256 * 1024`,
		unsigned int	maxStrings = `-1`
	)

inlinestatic

Creates a cache of rendered strings made using the given font.

Parameters

font	The font to use to render the cached text. This object will take ownership of the font.
maxBytes	The maximum size of the rendered string images in bytes. If this value is very low, even zero, then only one rendered image will be cached.
maxStrings	The maximum number of rendered strings that may be held by the cache. This value cannot be zero.

Exceptions

StringCacheZeroSize The cache size limits prevent any image from being kept in the cache. maxBytes is zero.

Definition at line 200 of file BppStringCache.hpp.

◆ make() [3/3]

static std::shared_ptr<BppStringCache> duds::ui::graphics::BppStringCache::make	(	const std::string &	path,
		unsigned int	maxBytes = `256 * 1024`,
		unsigned int	maxStrings = `-1`
	)

inlinestatic

Creates a cache of rendered strings made using a font created from the given image archive path.

Parameters

path	The image archive used to create the font that will be used to render the cached text. This object will take ownership of the font.
maxBytes	The maximum size of the rendered string images in bytes. If this value is very low, even zero, then only one rendered image will be cached.
maxStrings	The maximum number of rendered strings that may be held by the cache. This value cannot be zero.

Exceptions

StringCacheZeroSize	The cache size limits prevent any image from being kept in the cache. maxBytes is zero.
ImageArchiveStreamError	Failed to open the file.
ImageNotArchiveStreamError	The stream does not have an image archive stream.
ImageArchiveStreamTruncatedError	The stream appears to have an incomplete copy of the archive stream. Any images fully read prior to the error will be available.
ImageArchiveUnsupportedVersionError	The software does not support the claimed archive version.

Definition at line 236 of file BppStringCache.hpp.

◆ maxBytes()

unsigned int duds::ui::graphics::BppStringCache::maxBytes ( ) const

inline

Returns the maximum size of the cached images in bytes.

Definition at line 256 of file BppStringCache.hpp.

Referenced by make().

◆ maxStrings()

unsigned int duds::ui::graphics::BppStringCache::maxStrings ( ) const

inline

Returns the maximum number of cached images.

Definition at line 262 of file BppStringCache.hpp.

Referenced by make().

◆ strings()

unsigned int duds::ui::graphics::BppStringCache::strings ( ) const

inline

Returns the number of currently stored cached strings.

Definition at line 274 of file BppStringCache.hpp.

◆ text() [1/2]

ConstBppImageSptr duds::ui::graphics::BppStringCache::text	(	const std::string &	str,
		BppFont::Flags	flags = `BppFont::AlignLeft`
	)

Returns an image of the requested string either from a pre-rendered item in the cache or by rendering a new image.

If the text is rendered, it is done by calling BppFont::render() on this object's font. After rendering, the cache size limits are enforced by removing the cached item(s) that were last requested farthest in the past until maximums are not exceeded. Returning a copy of the image's shared pointer prevents cache evictions from destroying images before they are used.

Parameters

str	The UTF-8 string to render.
flags	The option flags. The default is to render varying width, fixed height text with each line aligned to the left.

Returns: A const image with the rendered text.

Exceptions

GlyphNotFoundError A glyph in str is not provided by the font.

Examples:: rendertext.cpp, and st7920.cpp.

Definition at line 106 of file BppStringCache.cpp.

◆ text() [2/2]

ConstBppImageSptr duds::ui::graphics::BppStringCache::text	(	const std::u32string &	str,
		BppFont::Flags	flags = `BppFont::AlignLeft`
	)

Returns an image of the requested string either from a pre-rendered item in the cache or by rendering a new image.

If the text is rendered, it is done by calling BppFont::render() on this object's font. After rendering, the cache size limits are enforced by removing the cached item(s) that were last requested farthest in the past until maximums are not exceeded. Returning a copy of the image's shared pointer prevents cache evictions from destroying images before they are used.

Parameters

str	The UTF-32 string to render. Internally the UTF-8 representation is used for the cache. This may not be the best way to do it.
flags	The option flags. The default is to render varying width, fixed height text with each line aligned to the left.

Returns: A const image with the rendered text.

Exceptions

GlyphNotFoundError A glyph in str is not provided by the font.

Definition at line 43 of file BppStringCache.cpp.

Member Data Documentation

◆ block

duds::general::Spinlock duds::ui::graphics::BppStringCache::block

private

Used for thread safety.

Definition at line 101 of file BppStringCache.hpp.

Referenced by clear(), and text().

◆ cache

Cache duds::ui::graphics::BppStringCache::cache

private

The cache of rendered strings.

Definition at line 85 of file BppStringCache.hpp.

Referenced by clear(), and text().

◆ curB

unsigned int duds::ui::graphics::BppStringCache::curB = 0

private

The current size of all rendered text images in the cache.

Definition at line 97 of file BppStringCache.hpp.

Referenced by bytes(), clear(), and text().

◆ fnt

BppFontSptr duds::ui::graphics::BppStringCache::fnt

private

The font to use for rendering.

Definition at line 32 of file BppStringCache.hpp.

Referenced by font(), and text().

◆ maxB

unsigned int duds::ui::graphics::BppStringCache::maxB

private

The maximum size of rendered text images, in bytes, the cache may hold.

Definition at line 93 of file BppStringCache.hpp.

Referenced by maxBytes(), and text().

◆ maxS

unsigned int duds::ui::graphics::BppStringCache::maxS

private

The maximum number of strings the cache may hold.

Definition at line 89 of file BppStringCache.hpp.

Referenced by BppStringCache(), maxStrings(), and text().

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

Classes

Public Member Functions

Static Public Member Functions

Private Types

Private Attributes

Detailed Description

Member Typedef Documentation

◆ Cache

Constructor & Destructor Documentation

◆ BppStringCache() [1/3]

◆ BppStringCache() [2/3]

◆ BppStringCache() [3/3]

Member Function Documentation

◆ bytes()

◆ clear()

◆ font()

◆ make() [1/3]

◆ make() [2/3]

◆ make() [3/3]

◆ maxBytes()

◆ maxStrings()

◆ strings()

◆ text() [1/2]

◆ text() [2/2]

Member Data Documentation

◆ block

◆ cache

◆ curB

◆ fnt

◆ maxB

◆ maxS