OSDL: OSDL::Video::TwoDimensional::Text::Font Class Reference

For each font, a glyph (a character) or a line of text (a series of glyphs) can be rendered, according to various encodings (all fonts should support at least the Latin-1 encoding), qualities (some types of fonts allows for several ones, others will have the selected quality mapped to available choices) and text color.

Various cache settings are supported to speed up the rendering when the same glyph or text is requested more than once. Most of the time, especially if multiline text rendering will be requested, the 'WordCached' policy should be selected.

With a Font instance, independently of its inner working, everything from the simple glyph to the full multiline justified text with paragraphs and alinea, can be rendered.

The principle of these rendering methods is to return a surface with the chosen glyph(s) drawn with the specified color, with no visible background : thanks to color key or alpha-blending, only the text can be seen, so that this returned surface can be directly blitted onto any already existing background that will be hidden only by the pixels corresponding to the text.

Words and texts are rendered so that all glyphs lie on a common baseline, but glyphs are rendered in individual surfaces of different height. Hence drawing a text is more difficult than just blitting all glyphs from the same height, and usually applications do not use direct glyph rendering : most of the time words or texts are preferably rendered as a whole.

As a returned surface is encoded with a RLE-color key and/or can be hardware, it is especially important to lock this surface before reading and/or writing its pixels, and to unlock it afterwards.

This returned surface is to be owned by the caller of the render method. This caller will have to deallocate it when the surface will not be of use anymore.

Each child class should initialize itself the '_spaceWidth' and '_alineaWidth' members, it cannot be done at the level of this Font mother class.

Definition at line 177 of file OSDLFont.h.


Public Types
enum	RenderQuality { Solid, Shaded, Blended }
	Describes the various rendering qualities available for texts. More...
enum	RenderCache { None, GlyphCached, WordCached, TextCached }
	As rendering glyphs can demand a lot of resources, they can be put in cache so that the same request is not rendered twice. More...
enum	AllowedCachePolicy { NeverDrop, DropLessRequestedFirst }
	Describes which of the cache policies made available by the Smart Resource manager are allowed for fonts. More...
Public Member Functions
	Font (bool convertToDisplay=true, RenderCache cacheSettings=GlyphCached, AllowedCachePolicy cachePolicy=DropLessRequestedFirst, Ceylan::System::Size quota=0) throw ()
	Creates an abstract font.
virtual	~Font () throw ()
	Virtual destructor.
virtual RenderingStyle	getRenderingStyle () const throw ()
	Returns the current rendering style.
virtual void	setRenderingStyle (RenderingStyle newStyle) throw ( TextException )
	Sets the current rendering style for this font.
virtual void	setBackgroundColor (Pixels::ColorDefinition newBackgroundColor) throw ()
	Sets the current background color for this font.
Pixels::ColorDefinition	getBackgroundColor () const throw ()
	Returns the current background color.
virtual Width	getWidth (Ceylan::Latin1Char character) const=0 throw ( TextException)
	Returns the width of the specified glyph, rendered with this font.
virtual SignedWidth	getWidthOffset (Ceylan::Latin1Char character) const=0 throw ( TextException )
	Returns the width of the abscissa offset for the specified glyph, rendered with this font.
virtual SignedHeight	getHeightAboveBaseline (Ceylan::Latin1Char character) const=0 throw ( TextException )
	Returns the height above baseline of the specified glyph, rendered with this font.
virtual SignedLength	getAdvance (Ceylan::Latin1Char character) const=0 throw ( TextException )
	Returns the advance of the specified glyph, rendered with this font, which is the space between the leftmost part of the glyph bounding box and the same part of the next glyph.
virtual Width	getInterGlyphWidth () const throw ()
	Returns the width of the recommended space between two glyphs.
virtual Height	getHeight () const=0 throw ()
	Returns the maximum pixel height of all glyphs of this font.
virtual SignedHeight	getAscent () const=0 throw ()
	Returns the maximum pixel ascent (height above baseline) of all glyphs of this font.
virtual SignedHeight	getDescent () const=0 throw ()
	Returns the maximum pixel descent (height below baseline) of all glyphs of this font.
virtual Height	getLineSkip () const=0 throw ()
	Returns the recommended pixel height of a rendered line of text of this font.
virtual Width	getAlineaWidth () const throw ()
	Returns the current alinea width, expressed in pixels.
virtual void	setAlineaWidth (Width newAlineaWidth) throw ()
	Sets the current alinea width, in pixels.
virtual std::string	describeGlyphFor (Ceylan::Latin1Char character) const throw ()
	Returns a text describing the metrics of the glyph corresponding to the specified character.
virtual Surface &	renderLatin1Glyph (Ceylan::Latin1Char character, RenderQuality quality=Solid, Pixels::ColorDefinition glyphColor=Pixels::White)=0 throw ( TextException )
	Renders specified glyph (Latin-1 character) in specified color, in a returned new surface.
virtual void	blitLatin1Glyph (Surface &targetSurface, Coordinate x, Coordinate y, Ceylan::Latin1Char character, RenderQuality quality=Solid, Pixels::ColorDefinition glyphColor=Pixels::White)=0 throw ( TextException )
	Blits specified glyph (Latin-1 character) in specified color, on specified location of given surface.
virtual Surface &	renderLatin1Text (const std::string &text, RenderQuality quality=Solid, Pixels::ColorDefinition textColor=Pixels::White) throw ( TextException )
	Renders specified text, encoded in Latin-1, in specified color, in a returned surface, in one line that will not be broken (no multi-line).
virtual void	blitLatin1Text (Surface &targetSurface, Coordinate x, Coordinate y, const std::string &text, RenderQuality quality=Solid, Pixels::ColorDefinition textColor=Pixels::White) throw ( TextException )
	Blits specified text, encoded in Latin-1, in specified color, on specified location of given surface, in one line that will not be broken (no multi-line).
virtual Surface &	renderLatin1MultiLineText (Length width, Length height, const std::string &text, TextIndex &renderIndex, Coordinate &lastOrdinateUsed, RenderQuality quality=Solid, Pixels::ColorDefinition textColor=Pixels::White, bool justified=true) throw ( TextException )
	Renders specified text, encoded in Latin-1, in specified color, in a returned surface of specified dimensions.
virtual void	blitLatin1MultiLineText (Surface &targetSurface, const UprightRectangle &clientArea, const std::string &text, TextIndex &renderIndex, RenderQuality quality=Solid, Pixels::ColorDefinition textColor=Pixels::White, bool justified=true) throw ( TextException )
	Blits specified text, encoded in Latin-1, in specified color, in specified location of specified surface, in a box of specified dimensions.
virtual void	blitLatin1MultiLineText (Surface &targetSurface, Coordinate x, Coordinate y, Length width, Length height, const std::string &text, TextIndex &renderIndex, RenderQuality quality=Solid, Pixels::ColorDefinition textColor=Pixels::White, bool justified=true) throw ( TextException )
	Blits specified text, encoded in Latin-1, in specified color, in specified location of specified surface, in a box of specified dimensions.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const throw ()
	Returns an user-friendly description of the state of this object.
Static Public Member Functions
static std::string	InterpretRenderingStyle (RenderingStyle style) throw ()
	Returns a description of the specified rendering style.
Static Public Attributes
static std::string	FontPathEnvironmentVariable
	The name of the environment variable that may contain directory names that should contain font files.
static Ceylan::System::FileLocator	FontFileLocator
	Allows to keep track of font directories.
static const RenderingStyle	Normal
	Normal font rendering style.
static const RenderingStyle	Bold
	Normal font rendering style.
static const RenderingStyle	Italic
	Italic font rendering style.
static const RenderingStyle	Underline
	Underline font rendering style.
static const Ceylan::System::Size	DefaultGlyphCachedQuota
	Defines the default quota value (maximum size of cached surfaces in memory, in bytes) if the cache is glyph-based.
static const Ceylan::System::Size	DefaultWordCachedQuota
	Defines the default quota value (maximum size of cached surfaces in memory, in bytes) if the cache is word-based.
static const Ceylan::System::Size	DefaultTextCachedQuota
	Defines the default quota value (maximum size of cached surfaces in memory, in bytes) if the cache is text-based.
static const Ceylan::Uint8	DefaultSpaceBasedAlineaWidth
	Defines the default width for an alinea as a multiple of the width of a space.
Protected Member Functions
Surface &	renderLatin1TextWithWordCached (const std::string &text, RenderQuality quality, Pixels::ColorDefinition textColor) throw ( TextException )
	Renders specified Latin-1 text with specified quality, in specified color, so that the word cache is used.
Surface &	renderLatin1TextWithTextCached (const std::string &text, RenderQuality quality, Pixels::ColorDefinition textColor) throw ( TextException )
	Renders specified Latin-1 text with specified quality, in specified color, so that the text cache is used.
virtual void	blitLatin1Word (Surface &targetSurface, Coordinate x, Coordinate y, const std::string &word, RenderQuality quality=Solid, Pixels::ColorDefinition wordColor=Pixels::White) throw ( TextException )
	Blits specified word, encoded with Latin-1 characters, in specified color, with specified quality, on specified location of given surface.
virtual const Surface &	getConstLatin1WordFromCache (const std::string &word, RenderQuality quality, Pixels::ColorDefinition wordColor) throw ( TextException )
	Ensures that specified word rendering is in text cache, and returns a 'const' reference to it : if the rendering is not already in text cache, it will be added.
Surface &	basicRenderLatin1Text (const std::string &text, RenderQuality quality, Pixels::ColorDefinition textColor) throw ( TextException )
	Renders specified Latin-1 text with specified quality, in specified color, directly thanks to the font backend : no cache is taken into account.
Protected Attributes
RenderingStyle	_renderingStyle
	Records the current rendering style (Normal, Bold, etc.
bool	_convertToDisplay
	Tells whether returned and cached renderings should be converted to display beforehand.
RenderCache	_cacheSettings
	Describes the settings of the render cache.
Ceylan::SmartResourceManager< CharColorQualityKey > *	_glyphCache
	The smart resource manager that would cache rendered glyphs, should the GlyphCached render cache be selected.
Ceylan::SmartResourceManager< StringColorQualityKey > *	_textCache
	The smart resource manager that would cache rendered words and/or text, should the WordCached or TextCached render cache be selected.
Pixels::ColorDefinition	_backgroundColor
	Defines what is the background color, for 'Shaded' quality.
Width	_spaceWidth
	Records the width of a space, in pixels, if not null.
Width	_alineaWidth
	Records the width of an alinea space, in pixels, to be put at the beginning of a paragraph.
Private Member Functions
	Font (const Font &source) throw ()
	Copy constructor made private to ensure that it will be never called.
Font &	operator= (const Font &source) throw ()
	Assignment operator made private to ensure that it will be never called.
Classes
class	CharColorQualityKey
	Cache key to manage colored characters with various qualities. More...
class	StringColorQualityKey
	Cache key to manage colored strings, both for word only and full text. More...

Member Enumeration Documentation

enum OSDL::Video::TwoDimensional::Text::Font::RenderQuality

Describes the various rendering qualities available for texts.

Note that not all qualities are available for all fonts. This applies mostly for TrueType fonts, since other systems seldom have different qualities.

The actual rendering quality will be the closest available one, compared to the requested one.

These informations on the internal format of the rendered surfaces are valid only as long as no conversion to display occurs :

Solid : Quick and Dirty

Creates an 8-bit palettized surface and renders the given text at fast quality with the given font and color.

The 0 pixel value is the colorkey, giving a transparent background, and the 1 pixel value is set to the text color.

The colormap is set to have the desired foreground color at index 1, this allows you to change the color without having to render the text again.

Colormap index 0 is of course not drawn, since it is the colorkey, and thus transparent, though its actual color is 255 minus each RGB component of the foreground.

This is the fastest rendering speed of all the rendering modes.

This results in no box around the text, but the text is not as smooth as obtained with other qualities : the 'Solid' one is quite poor. By using a render cache, at the expense of more memory used, other qualities could demand low CPU resources as well.

The resulting surface should blit faster than the Blended one. Use this mode for frame per second counters and other fast changing text displays.

Shaded : Slow and Nice (and Recommended quality for most outputs)

Creates a 32-bit RGB RLE-colorkeyed surface (with no alpha) and renders the given text at high quality with the given font and colors. Apart the background, the other pixels have varying degrees of the foreground color from the background color. This background color should be managed as a state variable of the corresponding font object. Its default value is pure black.

The text is antialiased. This will render slower than Solid, but in about the same time as Blended mode.

The resulting surface should blit quite as fast as Solid, once it is made. Use this when you need nice text.

Blended : Slow Slow Slow, but Ultra Nice over another image.

Creates a 32-bit ARGB surface and render the given text at high quality, using alpha blending to dither the font with the given color.

This results in a surface with alpha transparency, so you do not have a solid colored box around the text.

The text is antialiased. This will render slower than Solid, but in about the same time as Shaded mode.

The resulting surface will blit slower than if you had used Solid or Shaded.

Use this when you want high quality, and the text is not changing too fast.

Enumerator:

Solid
Shaded
Blended

Definition at line 277 of file OSDLFont.h.

enum OSDL::Video::TwoDimensional::Text::Font::RenderCache

As rendering glyphs can demand a lot of resources, they can be put in cache so that the same request is not rendered twice.

The various settings for the render cache are :

None : when no caching is wanted (prefer memory to CPU)
GlyphCached : put in cache individual glyphs
WordCached : put in cache full words. This can be useful for example with Truetype fonts, since a word cannot be easily rendered from the set of its glyphs, due, for instance, to kerning.
TextCached : allows for full lines, including whitespaces, to be cached as blocks. Useful when the same sequence of words has to be rendered multiple times.

Enumerator:

None
GlyphCached
WordCached
TextCached

Definition at line 470 of file OSDLFont.h.

enum OSDL::Video::TwoDimensional::Text::Font::AllowedCachePolicy

Describes which of the cache policies made available by the Smart Resource manager are allowed for fonts.

See also:: Ceylan::SmartResourceManager for the description of the various allowed policies.

This enum is a convenient way too of overcoming the impossibility of specifying a cache policy independently of the key chosen to instantiate the manager : this is an additional level of indirection, so that in the font constructor the cache policy can be specified directly, and not as : Ceylan::SmartResourceManager <StringColorQualityKey>CachePolicy for example, which would prevent to be able to specify a Ceylan::SmartResourceManager <CharColorQualityKey>CachePolicy needed for the glyph cache.

Enumerator:

NeverDrop
DropLessRequestedFirst

Definition at line 497 of file OSDLFont.h.

Constructor & Destructor Documentation

Font::Font	(	bool	convertToDisplay = `true`,
		RenderCache	cacheSettings = `GlyphCached`,
		AllowedCachePolicy	cachePolicy = `DropLessRequestedFirst`,
		Ceylan::System::Size	quota = `0`
	)			throw () `[explicit]`

Creates an abstract font.

Parameters:

convertToDisplay

tells whether a returned rendering should have already been converted to display. Any cached rendering follows this choice too. Pre-converting is useful for classical 2D rendering, useless for OpenGL since surfaces will have to be expressed according to OpenGL convention nonetheless.

If the conversion to display is chosen, then at each change of the display format, the renderings will have to be converted again.

Parameters:

	cacheSettings	determines what will be put in cache in terms of rendering (glyphs, or words, or texts, etc.)
	cachePolicy	determines how the cache should behave regarding renderings being put in cache (store everything, enforce a maximum size in memory, etc.)
	quota	Should an upper-bound to the memory size of cached renderings apply (depending on the chosen cache policy), determines its actual value. If a null (0) quota is passed, then the default value of the quota for the selected cache settings will be chosen. For example, if cacheSettings is 'WordCached' and cachePolicy is 'DropLessRequestedFirst' (this policy uses a quota), and if a null quota is specified, then the actual quota being used will be 'DefaultWordCachedQuota'.

Definition at line 76 of file OSDLFont.cc.

References OSDL::Video::OpenGL::None.

Font::~Font ( ) throw () [virtual]

Virtual destructor.

Definition at line 265 of file OSDLFont.cc.

References _glyphCache, and _textCache.

OSDL::Video::TwoDimensional::Text::Font::Font ( const Font & source ) throw () [private]

Copy constructor made private to ensure that it will be never called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.

Member Function Documentation

RenderingStyle Font::getRenderingStyle ( ) const throw () [virtual]

Returns the current rendering style.

Reimplemented in OSDL::Video::TwoDimensional::Text::TrueTypeFont.

Definition at line 278 of file OSDLFont.cc.

References _renderingStyle.

void Font::setRenderingStyle ( RenderingStyle newStyle ) throw ( TextException ) [virtual]

Sets the current rendering style for this font.

Exceptions:

TextException

if the specified style is not supported.

Note:: Some fonts (ex : some fixed fonts) support only the rendering style they had at their creation. In this case, this method throws systematically an exception if the rendering style is changed. The solution would be to create a new Font subclass with the desired rendering style, instead of changing an already existing font instance.

Reimplemented in OSDL::Video::TwoDimensional::Text::TrueTypeFont.

Definition at line 287 of file OSDLFont.cc.

void Font::setBackgroundColor ( Pixels::ColorDefinition newBackgroundColor ) throw () [virtual]

Sets the current background color for this font.

Parameters:

newBackgroundColor

the new background color.

Note:: The concept of background color only applies when the 'Shaded' quality is chosen, since with other rendering qualities the background is transparent.

Definition at line 297 of file OSDLFont.cc.

OSDL::Video::Pixels::ColorDefinition Font::getBackgroundColor ( ) const throw ()

Returns the current background color.

Note:: The concept of background color only applies when the 'Shaded' quality is chosen, since with other rendering qualities the background is transparent.

Definition at line 306 of file OSDLFont.cc.

References _backgroundColor.

virtual Width OSDL::Video::TwoDimensional::Text::Font::getWidth ( Ceylan::Latin1Char character ) const throw ( TextException) [pure virtual]

Returns the width of the specified glyph, rendered with this font.

Parameters:

character

the character whose width will be returned.

Note:: There is no argument-less getWidth since for most fonts it depends too heavily on the selected glyph.

Exceptions:

TextException

if the glyph metrics could not be retrieved.

Implemented in OSDL::Video::TwoDimensional::Text::FixedFont, and OSDL::Video::TwoDimensional::Text::TrueTypeFont.

Referenced by getInterGlyphWidth().

virtual SignedWidth OSDL::Video::TwoDimensional::Text::Font::getWidthOffset ( Ceylan::Latin1Char character ) const throw ( TextException ) [pure virtual]

Returns the width of the abscissa offset for the specified glyph, rendered with this font.

This offset corresponds to the first abscissa from which the glyph should be rendered from a given location.

Parameters:

character

the character whose abscissa offset will be returned.

Exceptions:

TextException

if the glyph metrics could not be retrieved.

Implemented in OSDL::Video::TwoDimensional::Text::FixedFont, and OSDL::Video::TwoDimensional::Text::TrueTypeFont.

virtual SignedHeight OSDL::Video::TwoDimensional::Text::Font::getHeightAboveBaseline ( Ceylan::Latin1Char character ) const throw ( TextException ) [pure virtual]

Returns the height above baseline of the specified glyph, rendered with this font.

Parameters:

character

the character whose height above baseline will be returned.

Exceptions:

TextException

if the glyph metrics could not be retrieved.

Implemented in OSDL::Video::TwoDimensional::Text::FixedFont, and OSDL::Video::TwoDimensional::Text::TrueTypeFont.

virtual SignedLength OSDL::Video::TwoDimensional::Text::Font::getAdvance ( Ceylan::Latin1Char character ) const throw ( TextException ) [pure virtual]

Returns the advance of the specified glyph, rendered with this font, which is the space between the leftmost part of the glyph bounding box and the same part of the next glyph.

It includes therefore the width of this glyph and the space between the next glyph that could be rendered afterwards.

Parameters:

character

the character whose advance will be returned.

Exceptions:

TextException

if the glyph metrics could not be retrieved.

Implemented in OSDL::Video::TwoDimensional::Text::FixedFont, and OSDL::Video::TwoDimensional::Text::TrueTypeFont.

Width Font::getInterGlyphWidth ( ) const throw () [virtual]

Returns the width of the recommended space between two glyphs.

Simple text rendering can rely on constant space between glyphs, but for more complex cases such as multi-line printing, more complex rules should be used.

Returns:: a value computed that is an evaluation which may not be consistent with the character-based advances that can be requested.

Reimplemented in OSDL::Video::TwoDimensional::Text::FixedFont.

Definition at line 356 of file OSDLFont.cc.

References getWidth().

virtual Height OSDL::Video::TwoDimensional::Text::Font::getHeight ( ) const throw () [pure virtual]

Returns the maximum pixel height of all glyphs of this font.

You may use this height for rendering text as c lose together vertically as possible, though adding at least one pixel height to it will space it, so they cannot touch.

Remember that multiline printing is not enabled, so the user is responsible for line spacing.

See also:: getLineSkip

Implemented in OSDL::Video::TwoDimensional::Text::FixedFont, and OSDL::Video::TwoDimensional::Text::TrueTypeFont.

virtual SignedHeight OSDL::Video::TwoDimensional::Text::Font::getAscent ( ) const throw () [pure virtual]

Returns the maximum pixel ascent (height above baseline) of all glyphs of this font.

You may use this height for rendering text as c lose together vertically as possible, though adding at least one pixel height to it will space it, so they cannot touch.

Remember that multiline printing is not enabled, so the user is responsible for line spacing.

See also:: getLineSkip

Implemented in OSDL::Video::TwoDimensional::Text::FixedFont, and OSDL::Video::TwoDimensional::Text::TrueTypeFont.

virtual SignedHeight OSDL::Video::TwoDimensional::Text::Font::getDescent ( ) const throw () [pure virtual]

Returns the maximum pixel descent (height below baseline) of all glyphs of this font.

If at least a glyph has parts below the abscissa axis, the descent is negative.

It could be used when drawing an individual glyph relative to a bottom point, by combining it with the glyph's vertical metrics to resolve the top of the rectangle used when blitting the glyph on the screen.

Remember that multiline printing is not enabled, so the user is responsible for line spacing.

See also:: getLineSkip

Implemented in OSDL::Video::TwoDimensional::Text::FixedFont, and OSDL::Video::TwoDimensional::Text::TrueTypeFont.

virtual Height OSDL::Video::TwoDimensional::Text::Font::getLineSkip ( ) const throw () [pure virtual]

Returns the recommended pixel height of a rendered line of text of this font.

It is usually larger than the value returned by getHeight.

Implemented in OSDL::Video::TwoDimensional::Text::FixedFont, and OSDL::Video::TwoDimensional::Text::TrueTypeFont.

Width Font::getAlineaWidth ( ) const throw () [virtual]

Returns the current alinea width, expressed in pixels.

Definition at line 315 of file OSDLFont.cc.

References _alineaWidth.

void Font::setAlineaWidth ( Width newAlineaWidth ) throw () [virtual]

Sets the current alinea width, in pixels.

Setting a null (zero) value disables the alinea feature.

Parameters:

newAlineaWidth

the new value, in pixel, for the alinea.

Definition at line 323 of file OSDLFont.cc.

std::string Font::describeGlyphFor ( Ceylan::Latin1Char character ) const throw () [virtual]

Returns a text describing the metrics of the glyph corresponding to the specified character.

Parameters:

character

the character whose glyph is to be described.

Returns:: a description of the corresponding glyph.

Definition at line 332 of file OSDLFont.cc.

References OSDL::Video::Pixels::toString().

virtual Surface& OSDL::Video::TwoDimensional::Text::Font::renderLatin1Glyph	(	Ceylan::Latin1Char	character,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	glyphColor = `Pixels::White`
	)			throw ( TextException ) `[pure virtual]`

Renders specified glyph (Latin-1 character) in specified color, in a returned new surface.

Depending on the settings, the returned surface can be a clone of a pre-rendered (cached) character or, if not available, be put in cache itself so that it is rendered once.

Otherwise, if no cache feature is allowed, each character will be rendered as many times as requested.

The caller is responsible for deleting the returned surface.

Parameters:

	character	the Latin-1 character to render.
	quality	the chosen rendering quality.
	glyphColor	the color definition for the glyph.

Returns:: a newly allocated Surface, whose ownership is transferred to the caller. This surface is encoded with RLE colorkey for maximum efficiency.

Exceptions:

TextException

on error.

Implemented in OSDL::Video::TwoDimensional::Text::TrueTypeFont.

virtual void OSDL::Video::TwoDimensional::Text::Font::blitLatin1Glyph	(	Surface &	targetSurface,
		Coordinate	x,
		Coordinate	y,
		Ceylan::Latin1Char	character,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	glyphColor = `Pixels::White`
	)			throw ( TextException ) `[pure virtual]`

Blits specified glyph (Latin-1 character) in specified color, on specified location of given surface.

Parameters:

	targetSurface	the surface the glyph will be blitted to.
	x	the abscissa in target surface of the top-left corner of the glyph blit.
	y	the ordinate in target surface of the top-left corner of the glyph blit.
	character	the Latin-1 character to render.
	quality	the chosen rendering quality.
	glyphColor	the color definition for the glyph.

Exceptions:

TextException

on error.

Implemented in OSDL::Video::TwoDimensional::Text::TrueTypeFont.

OSDL::Video::Surface & Font::renderLatin1Text	(	const std::string &	text,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	textColor = `Pixels::White`
	)			throw ( TextException ) `[virtual]`

Renders specified text, encoded in Latin-1, in specified color, in a returned surface, in one line that will not be broken (no multi-line).

The caller is responsible for deleting the returned surface.

Parameters:

	text	the text, encoded in Latin-1, to render.
	quality	the chosen rendering quality.
	textColor	the color definition for the text.

Returns:: a newly allocated Surface, whose ownership is transferred to the caller.

Exceptions:

TextException

on error, for example if a specified glyph was not found.

Reimplemented in OSDL::Video::TwoDimensional::Text::TrueTypeFont.

Definition at line 369 of file OSDLFont.cc.

References OSDL::Video::OpenGL::None.

Referenced by OSDL::Video::TwoDimensional::Text::TrueTypeFont::renderLatin1Text().

void Font::blitLatin1Text	(	Surface &	targetSurface,
		Coordinate	x,
		Coordinate	y,
		const std::string &	text,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	textColor = `Pixels::White`
	)			throw ( TextException ) `[virtual]`

Blits specified text, encoded in Latin-1, in specified color, on specified location of given surface, in one line that will not be broken (no multi-line).

Parameters:

	targetSurface	the surface the text will be blitted to.
	x	the abscissa in target surface of the top-left corner of the text blit.
	y	the ordinate in target surface of the top-left corner of the text blit.
	text	the text, encoded in Latin-1, to render.
	quality	the chosen rendering quality.
	textColor	the color definition for the text.

Exceptions:

TextException

on error, for example if a specified glyph was not found.

Definition at line 418 of file OSDLFont.cc.

References OSDL::Video::Surface::blitTo().

OSDL::Video::Surface & Font::renderLatin1MultiLineText	(	Length	width,
		Length	height,
		const std::string &	text,
		TextIndex &	renderIndex,
		Coordinate &	lastOrdinateUsed,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	textColor = `Pixels::White`,
		bool	justified = `true`
	)			throw ( TextException ) `[virtual]`

Renders specified text, encoded in Latin-1, in specified color, in a returned surface of specified dimensions.

The text will be rendered on as many lines as needed, and will be automatically justified if requested.

If the text is too long to fit in the box, then all the words that fit in will be rendered.

If a word is too wide to be rendered at all in the box, then the rendering will stop before it.

This method will return in 'renderIndex' the index of the first character from the specified text that could not have been rendered, if any.

Words are not broken : only full words are rendered.

The caller is responsible for deleting the returned surface.

Note:: Multiline text rendering is recommended for use with one of the two most useful cases regarding text caches : the 'WordCached' and 'TextCached' policies. Using 'GlyphCached' or no cache at all works but is far less efficient. Notably, a temporary word cache will be used, which may use more peak memory space than wanted.

Parameters:

	width	the width of the box in which the text is to be rendered.
	height	the height of the box in which the text is to be rendered.
	text	the text, encoded in Latin-1, to render.
	renderIndex	the method will assign this user-provided variable the index of the first character that could not be rendered. Hence if the full text could be rendered in the container, then 'renderIndex' will be equal to the length of 'text'.

For example, if the text is 'Hello OSDL' and only 'Hello' could be rendered, then 'renderIndex' (starting from zero) will be assigned to 6, the index of the 'O' of OSDL (leading spaces are ignored).

Parameters:

	lastOrdinateUsed	the method will assign this user-provided variable the ordinate of the last row used in the returned surface : depending on the text, the requested surface will be filled at different levels. This ordinate is useful for example to align vertically a text in its container. No ordinate beyond container height can be returned.
	quality	the chosen rendering quality.
	textColor	the color definition for the text.
	justified	tells whether the text should be justified, i.e. should be vertically aligned on both edges.

Returns:: a newly allocated Surface, whose ownership is transferred to the caller.

Exceptions:

TextException

on error.

Definition at line 492 of file OSDLFont.cc.

References OSDL::Video::Pixels::areEqual(), OSDL::Video::Pixels::Black, OSDL::Video::Surface::ColorkeyBlit, OSDL::Video::Surface::fill(), OSDL::Video::Pixels::getRecommendedColorMasks(), OSDL::Video::Surface::Hardware, OSDL::Video::OpenGL::None, OSDL::Video::Pixels::toString(), and OSDL::Video::Pixels::White.

Referenced by OSDL::Video::TwoDimensional::TextWidget::redrawBackBuffer().

void Font::blitLatin1MultiLineText	(	Surface &	targetSurface,
		const UprightRectangle &	clientArea,
		const std::string &	text,
		TextIndex &	renderIndex,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	textColor = `Pixels::White`,
		bool	justified = `true`
	)			throw ( TextException ) `[virtual]`

Blits specified text, encoded in Latin-1, in specified color, in specified location of specified surface, in a box of specified dimensions.

The text will be rendered on as many lines as needed, and will be automatically justified. If the text is too long to fit in the box, then all the words that fit in will be rendered.

This method will return in 'renderIndex' the index of the first character from the specified text that could not have been rendered, if any.

Words are not broken : only full words are rendered.

Note:: Multiline text rendering is for the moment only implemented for the two most useful cases regarding text caches : this rendering is available for the 'WordCached' and 'TextCached' policies. It is not implemented for 'GlyphCached', or no cache at all, yet.

Parameters:

	targetSurface	the surface the text will be blitted to.
	clientArea	a rectangle enclosing the usable area for text rendering in targetSurface, expressed in the referential of this surface.
	text	the text, encoded in Latin-1, to render.
	renderIndex	the method will assign this user-provided variable the index of the first character that could not be rendered. Hence if the full text could be rendered, then 'renderIndex' will be equal to the length of 'text'.

For example, if the text is 'Hello OSDL' and only 'Hello' could be rendered, then 'renderIndex' (starting from zero) will be assigned to 6, the index of the 'O' of OSDL (leading spaces are ignored).

Parameters:

	quality	the chosen rendering quality.
	textColor	the color definition for the text.
	justified	tells whether the text should be justified, i.e. should be vertically aligned on both edges.

Exceptions:

TextException

on error.

Definition at line 892 of file OSDLFont.cc.

void Font::blitLatin1MultiLineText	(	Surface &	targetSurface,
		Coordinate	x,
		Coordinate	y,
		Length	width,
		Length	height,
		const std::string &	text,
		TextIndex &	renderIndex,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	textColor = `Pixels::White`,
		bool	justified = `true`
	)			throw ( TextException ) `[virtual]`

Blits specified text, encoded in Latin-1, in specified color, in specified location of specified surface, in a box of specified dimensions.

The text will be rendered on as many lines as needed, and will be automatically justified. If the text is too long to fit in the box, then all the words that fit in will be rendered.

This method will return in 'renderIndex' the index of the first character from the specified text that could not have been rendered, if any.

Words are not broken : only full words are rendered.

Note:: Multiline text rendering is for the moment only implemented for the two most useful cases regarding text caches : this rendering is available for the 'WordCached' and 'TextCached' policies. It is not implemented for 'GlyphCached', or no cache at all, yet.

Parameters:

	targetSurface	the surface the text will be blitted to.
	x	the abscissa in target surface of the top-left corner of the text blit.
	y	the ordinate in target surface of the top-left corner of the text blit.
	width	the width of the box in which the text is to be rendered.
	height	the height of the box in which the text is to be rendered.
	text	the text, encoded in Latin-1, to render.
	renderIndex	the method will assign this user-provided variable the index of the first character that could not be rendered. Hence if the full text could be rendered, then 'renderIndex' will be equal to the length of 'text'.

For example, if the text is 'Hello OSDL' and only 'Hello' could be rendered, then 'renderIndex' (starting from zero) will be assigned to 6, the index of the 'O' of OSDL (leading spaces are ignored).

Parameters:

	quality	the chosen rendering quality.
	textColor	the color definition for the text.
	justified	tells whether the text should be justified, i.e. should be vertically aligned on both edges.

Exceptions:

TextException

on error.

Definition at line 916 of file OSDLFont.cc.

const string Font::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const throw () [virtual]

Returns an user-friendly description of the state of this object.

Parameters:

level

the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: Ceylan::TextDisplayable

Reimplemented in OSDL::Video::TwoDimensional::Text::FixedFont, and OSDL::Video::TwoDimensional::Text::TrueTypeFont.

Definition at line 943 of file OSDLFont.cc.

string Font::InterpretRenderingStyle ( RenderingStyle style ) throw () [static]

Returns a description of the specified rendering style.

Parameters:

style

the rendering style to describe.

Definition at line 1035 of file OSDLFont.cc.

Surface& OSDL::Video::TwoDimensional::Text::Font::renderLatin1TextWithWordCached	(	const std::string &	text,
		RenderQuality	quality,
		Pixels::ColorDefinition	textColor
	)			throw ( TextException ) `[protected]`

Renders specified Latin-1 text with specified quality, in specified color, so that the word cache is used.

This method is meant to be used as an helper function so that user-exposed methods can be easily implemented.

Parameters:

	text	the Latin-1 text to render.
	quality	the chosen rendering quality.
	textColor	the color definition for the text.

Returns:: a newly allocated Surface, whose ownership is transferred to the caller.

Exceptions:

TextException

on error.

Surface& OSDL::Video::TwoDimensional::Text::Font::renderLatin1TextWithTextCached	(	const std::string &	text,
		RenderQuality	quality,
		Pixels::ColorDefinition	textColor
	)			throw ( TextException ) `[protected]`

Renders specified Latin-1 text with specified quality, in specified color, so that the text cache is used.

This method is meant to be used as an helper function so that user-exposed methods can be easily implemented.

Parameters:

	text	the Latin-1 text to render.
	quality	the chosen rendering quality.
	textColor	the color definition for the text.

Returns:: a newly allocated Surface, whose ownership is transferred to the caller.

Exceptions:

TextException

on error.

void Font::blitLatin1Word	(	Surface &	targetSurface,
		Coordinate	x,
		Coordinate	y,
		const std::string &	word,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	wordColor = `Pixels::White`
	)			throw ( TextException ) `[protected, virtual]`

Blits specified word, encoded with Latin-1 characters, in specified color, with specified quality, on specified location of given surface.

The cache is interrogated so that a previous rendering for this word can be used again. If not, the rendering is performed and proposed to the word cache, if activated.

Parameters:

	targetSurface	the surface the word will be blitted to.
	x	the abscissa in target surface of the top-left corner of the word blit.
	y	the ordinate in target surface of the top-left corner of the word blit.
	word	the Latin-1 encoded word to render.
	quality	the chosen rendering quality. For fixed font, only the 'Solid' quality is available.
	wordColor	the color definition for the word.

Returns:: the width of the blit surface.

Exceptions:

TextException

on error.

Definition at line 1283 of file OSDLFont.cc.

const OSDL::Video::Surface & Font::getConstLatin1WordFromCache	(	const std::string &	word,
		RenderQuality	quality,
		Pixels::ColorDefinition	wordColor
	)			throw ( TextException ) `[protected, virtual]`

Ensures that specified word rendering is in text cache, and returns a 'const' reference to it : if the rendering is not already in text cache, it will be added.

This helper method is especially useful for blits, since otherwise they would have to call a render method which would create a copy for the cache, whereas blits can use the cached entry directly. It saves an useless copy/deleting.

It does not check the cache for a previous entry since its purpose is to feed the text cache. It does that independently of the cache settings (glyph, word, text, etc.). If the 'NeverDrop' cache policy is chosen, then one should ensure the corresponding cache key is not already in use.

Parameters:

	word	the Latin-1 encoded word to have rendered.
	quality	the chosen rendering quality.
	wordColor	the color definition for the word.

Returns:: a 'const' reference to a surface which is a rendering of the specified word. The surface is still owned by the cache, and should therefore not be deallocated by the caller.

Exceptions:

TextException

on error.

Definition at line 1351 of file OSDLFont.cc.

OSDL::Video::Surface & Font::basicRenderLatin1Text	(	const std::string &	text,
		RenderQuality	quality,
		Pixels::ColorDefinition	textColor
	)			throw ( TextException ) `[protected]`

Renders specified Latin-1 text with specified quality, in specified color, directly thanks to the font backend : no cache is taken into account.

This method is meant to be used as an helper function so that user-exposed methods can be easily implemented.

Parameters:

	text	the Latin-1 text to render.
	quality	the chosen rendering quality.
	textColor	the color definition for the text.

Returns:: a newly allocated Surface, whose ownership is transferred to the caller.

Exceptions:

TextException

on error.

Definition at line 1419 of file OSDLFont.cc.

OSDL::Video::TwoDimensional::Text::Font Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Private Member Functions

Classes

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation