Renders strings using a font made of BppImage objects for glyphs. More...

#include <BppFont.hpp>

Inheritance diagram for duds::ui::graphics::BppFont:

Collaboration diagram for duds::ui::graphics::BppFont:

Public Types
typedef duds::general::BitFlags< struct BppFontRenderingFlags >	Flags
	Option flags that affect how text is rendered. More...

Public Member Functions
	BppFont ()=default

	BppFont (const std::string &path)
	Loads glyphs from an image archive in the specified file. More...

	BppFont (std::istream &is)
	Loads glyphs from an input stream. More...

void	add (char32_t gc, const ConstBppImageSptr &img)
	Adds or replaces a glyph in the font. More...

void	add (char32_t gc, ConstBppImageSptr &&img)
	Adds or replaces a glyph in the font. More...

ImageDimensions	estimatedMaxCharacterSize ()
	Returns a somewhat decent estimate of the largest size of a character without actually inspecting all characters. More...

const ConstBppImageSptr &	get (char32_t gc)
	Returns the glyph of the specified character code. More...

ImageDimensions	lineDimensions (const std::string &text, Flags flags=Flags::Zero())
	Returns the dimensions of a single-line string without the overhead of rendering the string. More...

ImageDimensions	lineDimensions (const std::u32string &text, Flags flags=Flags::Zero())
	Returns the dimensions of a single-line string without the overhead of rendering the string. More...

void	load (const std::string &path)
	Loads glyphs from an image archive in the specified file. More...

void	load (std::istream &is)
	Loads glyphs from an input stream. More...

BppImageSptr	render (const std::string &text, Flags flags=AlignLeft)
	Renders the given text using this object's font. More...

BppImageSptr	render (const std::u32string &text, Flags flags=AlignLeft)
	Renders the given text using this object's font. More...

ConstBppImageSptr	tryGet (char32_t gc)
	Returns the glyph of the specified character code. More...

Static Public Member Functions
static std::shared_ptr< BppFont >	make ()
	Returns a shared pointer to a new BppFont object. More...

static std::shared_ptr< BppFont >	make (const std::string &path)
	Returns a shared pointer to a new BppFont object constructed using the BppFont(const std::string &) constructor. More...

static std::shared_ptr< BppFont >	make (std::istream &is)
	Returns a shared pointer to a new BppFont object constructed using the BppFont(std::istream &) constructor. More...

Static Public Attributes
static constexpr Flags	AlignCenter = Flags::Bit(3)
	Center each line in the resulting image. More...

static constexpr Flags	AlignLeft = Flags::Zero()
	Align each line to the left. More...

static constexpr Flags	AlignMask = AlignCenter \| AlignRight
	All alignment flags. More...

static constexpr Flags	AlignRight = Flags::Bit(4)
	Align each line to the right. More...

static constexpr Flags	FixedWidth = Flags::Bit(0)
	All glyphs rendered with the same width using the maximum width of the glyphs used in the string. More...

static constexpr Flags	FixedWidthPerLine = Flags::Bit(1)
	Compute fixed width individually for each line, so each line may have a different width per glyph. More...

static constexpr Flags	VariableHeight = Flags::Bit(2)
	Each line will have the height of its tallest glyph rather than the tallest glyph of the entire string. More...

Protected Member Functions
virtual ConstBppImageSptr	renderGlyph (char32_t gc)
	Called to render the requested glyph when it is not present in the glyphs map. More...

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

std::unordered_map< char32_t, ConstBppImageSptr >	glyphs
	The glyph images keyed by character. More...

Detailed Description

Renders strings using a font made of BppImage objects for glyphs.

The glyph images may come from a BppImage archive file or stream, may be provided using the add() function, or can be generated in a renderGlyph() function implemented by a derived class. A cache of glyph images is maintained by this base class. The renderGlyph() function is called whenever a glyph is requested but not already in the cache of glyph images.

Author: Jeff Jackowski

Definition at line 30 of file BppFont.hpp.

Member Typedef Documentation

◆ Flags

typedef duds::general::BitFlags<struct BppFontRenderingFlags> duds::ui::graphics::BppFont::Flags

Option flags that affect how text is rendered.

Definition at line 165 of file BppFont.hpp.

Constructor & Destructor Documentation

◆ BppFont() [1/3]

duds::ui::graphics::BppFont::BppFont ( )

default

◆ BppFont() [2/3]

duds::ui::graphics::BppFont::BppFont ( const std::string & path )

inline

Loads glyphs from an image archive in the specified file.

The glyphs from the archive will augment what is already stored in this object, and will replace glyphs if there is a collision.

Note: Only images with a name that is just a single character will be kept. All other images will be discarded.

Parameters

path	The path of the archive file to load.

Exceptions

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 59 of file BppFont.hpp.

◆ BppFont() [3/3]

duds::ui::graphics::BppFont::BppFont ( std::istream & is )

inline

Loads glyphs from an input stream.

The glyphs from the archive stream will augment what is already stored in this object, and will replace glyphs if there is a collision.

Parameters

is	The input stream that will provide the image archive.

Exceptions

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 65 of file BppFont.hpp.

Member Function Documentation

◆ add() [1/2]

void duds::ui::graphics::BppFont::add	(	char32_t	gc,
		const ConstBppImageSptr &	img
	)

Adds or replaces a glyph in the font.

Todo:: change param names; the image is the glyph.

Parameters

gc	The character code of the glyph.
img	The image to store.

Definition at line 78 of file BppFont.cpp.

Referenced by make().

◆ add() [2/2]

void duds::ui::graphics::BppFont::add	(	char32_t	gc,
		ConstBppImageSptr &&	img
	)

Adds or replaces a glyph in the font.

Parameters

gc	The character code of the glyph.
img	The image to store. The shared pointer will be moved.

Definition at line 83 of file BppFont.cpp.

◆ estimatedMaxCharacterSize()

ImageDimensions duds::ui::graphics::BppFont::estimatedMaxCharacterSize ( )

Returns a somewhat decent estimate of the largest size of a character without actually inspecting all characters.

If the result is zero, the estimation failed.

Note: This simplistic font code lacks any real font metrics, so the result from this function may not be very good. It should do well with fixed width fonts. It may fail completely for fonts that are actually a set of icons and lack many characters.

Definition at line 115 of file BppFont.cpp.

Referenced by make().

◆ get()

const ConstBppImageSptr & duds::ui::graphics::BppFont::get ( char32_t gc )

Returns the glyph of the specified character code.

The returned reference is to the internally stored shared pointer rather than a new shared pointer. This makes get() prefered over tryGet() unless it is uncertain if the requested glyph exists in the font.

Parameters

gc	The character code of the glyph.

Returns: A shared pointer to the requested glyph image.

Exceptions

GlyphNotFoundError The glyph is not provided by the font.

Definition at line 88 of file BppFont.cpp.

◆ lineDimensions() [1/2]

ImageDimensions duds::ui::graphics::BppFont::lineDimensions	(	const std::string &	text,
		Flags	flags = `Flags::Zero()`
	)

Returns the dimensions of a single-line string without the overhead of rendering the string.

Parameters

text	The text to consider in a UTF-8 string.
flags	Either zero, for a potentially variable width, or FixedWidth to produce a width where each glyph is the width of the widest glyph in the text.

Exceptions

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

Definition at line 317 of file BppFont.cpp.

◆ lineDimensions() [2/2]

ImageDimensions duds::ui::graphics::BppFont::lineDimensions	(	const std::u32string &	text,
		Flags	flags = `Flags::Zero()`
	)

Returns the dimensions of a single-line string without the overhead of rendering the string.

Parameters

text	The text to consider.
flags	Either zero, for a potentially variable width, or FixedWidth to produce a width where each glyph is the width of the widest glyph in the text.

Exceptions

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

Definition at line 323 of file BppFont.cpp.

◆ load() [1/2]

void duds::ui::graphics::BppFont::load ( const std::string & path )

Loads glyphs from an image archive in the specified file.

The glyphs from the archive will augment what is already stored in this object, and will replace glyphs if there is a collision.

Note: Only images with a name that is just a single character will be kept. All other images will be discarded.

Parameters

path	The path of the archive file to load.

Exceptions

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 40 of file BppFont.cpp.

Referenced by BppFont(), and make().

◆ load() [2/2]

void duds::ui::graphics::BppFont::load ( std::istream & is )

Loads glyphs from an input stream.

The glyphs from the archive stream will augment what is already stored in this object, and will replace glyphs if there is a collision.

Parameters

is	The input stream that will provide the image archive.

Exceptions

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 56 of file BppFont.cpp.

◆ make() [1/3]

static std::shared_ptr<BppFont> duds::ui::graphics::BppFont::make ( )

inlinestatic

Returns a shared pointer to a new BppFont object.

Examples:: bppmenu.cpp.

Definition at line 71 of file BppFont.hpp.

Referenced by duds::ui::graphics::BppFontPool::addWithCache(), duds::ui::graphics::BppFontPool::addWithoutCache(), and duds::ui::graphics::BppStringCache::make().

◆ make() [2/3]

static std::shared_ptr<BppFont> duds::ui::graphics::BppFont::make ( const std::string & path )

inlinestatic

Returns a shared pointer to a new BppFont object constructed using the BppFont(const std::string &) constructor.

Definition at line 78 of file BppFont.hpp.

◆ make() [3/3]

static std::shared_ptr<BppFont> duds::ui::graphics::BppFont::make ( std::istream & is )

inlinestatic

Returns a shared pointer to a new BppFont object constructed using the BppFont(std::istream &) constructor.

Definition at line 85 of file BppFont.hpp.

◆ render() [1/2]

BppImageSptr duds::ui::graphics::BppFont::render	(	const std::string &	text,
		Flags	flags = `AlignLeft`
	)

Renders the given text using this object's font.

The newline character can be used to denote the start of another line. Lines are only made explicitly.

Variable sized glyphs are supported. Glyphs are aligned vertically along their lower edge. This places shorter glyphs lower than taller ones.

Parameters

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

Returns: A new image with the rendered text.

Bug:: Only tested for rendering a single line of text.

Exceptions

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

Definition at line 167 of file BppFont.cpp.

◆ render() [2/2]

BppImageSptr duds::ui::graphics::BppFont::render	(	const std::u32string &	text,
		Flags	flags = `AlignLeft`
	)

Renders the given text using this object's font.

The newline character can be used to denote the start of another line. Lines are only made explicitly.

Variable sized glyphs are supported. Glyphs are aligned vertically along their lower edge. This places shorter glyphs lower than taller ones.

Parameters

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

Returns: A new image with the rendered text.

Bug:: Only tested for rendering a single line of text.

Exceptions

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

Definition at line 173 of file BppFont.cpp.

◆ renderGlyph()

ConstBppImageSptr duds::ui::graphics::BppFont::renderGlyph ( char32_t gc )

protectedvirtual

Called to render the requested glyph when it is not present in the glyphs map.

The base implementation will return the white square glyph (value 9633, 0x25A1) if the font has it, or it will throw GlyphNotFoundError along with a Character attribute. Implementors should either render the glyph and add it to the glyphs map, or call the base implementation.

Note: The thread will have a lock on block when this function is called.

Exceptions

GlyphNotFoundError The glyph is not provided by the font.

Parameters

gc	The character code of the glyph.

Returns: The glyph image.

Definition at line 26 of file BppFont.cpp.

Referenced by get(), lineDimensions(), render(), and tryGet().

◆ tryGet()

ConstBppImageSptr duds::ui::graphics::BppFont::tryGet ( char32_t gc )

Returns the glyph of the specified character code.

Parameters

gc	The character code of the glyph.

Returns: A shared pointer to the requested glyph image, or an empty shared pointer if the font lacks the glyph.

Definition at line 100 of file BppFont.cpp.

Referenced by estimatedMaxCharacterSize(), and make().

Member Data Documentation

◆ AlignCenter

constexpr BppFont::Flags duds::ui::graphics::BppFont::AlignCenter = Flags::Bit(3)

static

Center each line in the resulting image.

Definition at line 188 of file BppFont.hpp.

Referenced by render().

◆ AlignLeft

constexpr BppFont::Flags duds::ui::graphics::BppFont::AlignLeft = Flags::Zero()

static

Align each line to the left.

This is the default.

Definition at line 184 of file BppFont.hpp.

Referenced by duds::ui::menu::renderers::BppMenuRenderer::render(), and duds::ui::graphics::BppStringCache::strings().

◆ AlignMask

constexpr BppFont::Flags duds::ui::graphics::BppFont::AlignMask = AlignCenter | AlignRight

static

All alignment flags.

Definition at line 196 of file BppFont.hpp.

◆ AlignRight

constexpr BppFont::Flags duds::ui::graphics::BppFont::AlignRight = Flags::Bit(4)

static

Align each line to the right.

Definition at line 192 of file BppFont.hpp.

Referenced by render(), and duds::ui::menu::renderers::BppMenuRenderer::render().

◆ block

duds::general::Spinlock duds::ui::graphics::BppFont::block

mutableprotected

Used for thread safety.

Definition at line 39 of file BppFont.hpp.

Referenced by add(), estimatedMaxCharacterSize(), get(), lineDimensions(), load(), render(), and tryGet().

◆ FixedWidth

constexpr BppFont::Flags duds::ui::graphics::BppFont::FixedWidth = Flags::Bit(0)

static

All glyphs rendered with the same width using the maximum width of the glyphs used in the string.

Definition at line 170 of file BppFont.hpp.

Referenced by lineDimensions(), and render().

◆ FixedWidthPerLine

constexpr BppFont::Flags duds::ui::graphics::BppFont::FixedWidthPerLine = Flags::Bit(1)

static

Compute fixed width individually for each line, so each line may have a different width per glyph.

Takes precedence over FixedWidth.

Definition at line 175 of file BppFont.hpp.

Referenced by lineDimensions(), and render().

◆ glyphs

std::unordered_map<char32_t, ConstBppImageSptr> duds::ui::graphics::BppFont::glyphs

protected

The glyph images keyed by character.

Definition at line 35 of file BppFont.hpp.

Referenced by add(), estimatedMaxCharacterSize(), get(), lineDimensions(), load(), render(), renderGlyph(), and tryGet().

◆ VariableHeight

constexpr BppFont::Flags duds::ui::graphics::BppFont::VariableHeight = Flags::Bit(2)

static

Each line will have the height of its tallest glyph rather than the tallest glyph of the entire string.

Definition at line 180 of file BppFont.hpp.

Referenced by render().

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

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ Flags

Constructor & Destructor Documentation

◆ BppFont() [1/3]

◆ BppFont() [2/3]

◆ BppFont() [3/3]

Member Function Documentation

◆ add() [1/2]

◆ add() [2/2]

◆ estimatedMaxCharacterSize()

◆ get()

◆ lineDimensions() [1/2]

◆ lineDimensions() [2/2]

◆ load() [1/2]

◆ load() [2/2]

◆ make() [1/3]

◆ make() [2/3]

◆ make() [3/3]

◆ render() [1/2]

◆ render() [2/2]

◆ renderGlyph()

◆ tryGet()

Member Data Documentation

◆ AlignCenter

◆ AlignLeft

◆ AlignMask

◆ AlignRight

◆ block

◆ FixedWidth

◆ FixedWidthPerLine

◆ glyphs

◆ VariableHeight