OSDL::Video::TwoDimensional::Text::FixedFont Class Reference

Models fixed fonts, a category which gathers all fonts whose rendering demands little resources, but cannot be scaled, as opposed to Truetype fonts. More...

#include <OSDLFixedFont.h>

Inheritance diagram for OSDL::Video::TwoDimensional::Text::FixedFont:

[legend]

Collaboration diagram for OSDL::Video::TwoDimensional::Text::FixedFont:

[legend]

List of all members.

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
	FixedFont (Length characterWidth, Length characterHeight, RenderingStyle renderingStyle=Normal, bool convertToDisplay=true, RenderCache cacheSettings=GlyphCached, AllowedCachePolicy cachePolicy=DropLessRequestedFirst, Ceylan::System::Size quota=0)
	FixedFont (const std::string &fontFilename, bool convertToDisplay=true, RenderCache cacheSettings=GlyphCached, AllowedCachePolicy cachePolicy=DropLessRequestedFirst, Ceylan::System::Size quota=0)
	Creates a new Fixed font from specified font file.
virtual	~FixedFont () throw ()
	Fixed font virtual destructor.
virtual Width	getWidth () const
	Returns the maximum pixel width of all glyphs of this font.
virtual Width	getWidth (Ceylan::Latin1Char character) const
	Returns the width of the specified glyph, rendered with this font.
virtual SignedWidth	getWidthOffset (Ceylan::Latin1Char character) const
	Returns the width of the abscissa offset for the specified glyph, rendered with this font.
virtual SignedHeight	getHeightAboveBaseline (Ceylan::Latin1Char character) const
	Returns the height above baseline of the specified glyph, rendered with this font.
virtual SignedLength	getAdvance () const
	Returns the advance (recommended width containing a glyph, so that they can be chained in a word), which with fixed fonts does not depend on the specific character being rendered.
virtual SignedLength	getAdvance (Ceylan::Latin1Char character) const
	Returns the advance (recommended width containing a glyph, so that they can be chained in a word), which with fixed fonts does not depend on the specific character being rendered.
virtual Width	getInterGlyphWidth () const
	Returns the width of the recommended space between two glyphs.
virtual Text::Height	getHeight () const
	Returns the maximum pixel height of all glyphs of this font.
virtual SignedHeight	getAscent () const
	Returns the maximum pixel ascent (height above baseline) of all glyphs of this font.
virtual SignedHeight	getDescent () const
	Returns the maximum pixel descent (height below baseline) of all glyphs of this font.
virtual Text::Height	getLineSkip () const
	Returns the recommended pixel height of a rendered line of text of this font.
virtual UprightRectangle &	getBoundingBox () const
	Returns a rectangular bounding box corresponding to the rendering of a glyph (with fixed fonts all characters are of the same size).
virtual UprightRectangle &	getBoundingBoxFor (const std::string &word) const
	Returns a rectangular bounding box corresponding to the rendering of specified word, encoded in ASCII.
virtual Surface &	renderLatin1Glyph (Ceylan::Latin1Char character, RenderQuality quality=Solid, Pixels::ColorDefinition glyphColor=Pixels::White)
	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)
	Blits specified glyph (Latin-1 character) in specified color, on specified location of given surface.
virtual Surface &	renderLatin1GlyphAlpha (Ceylan::Latin1Char character, RenderQuality quality=Solid, Pixels::ColorDefinition glyphColor=Pixels::White)
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const
	Returns an user-friendly description of the state of this object.
virtual RenderingStyle	getRenderingStyle () const
	Returns the current rendering style.
virtual void	setRenderingStyle (RenderingStyle newStyle)
	Sets the current rendering style for this font.
virtual void	setBackgroundColor (Pixels::ColorDefinition newBackgroundColor)
	Sets the current background color for this font.
Pixels::ColorDefinition	getBackgroundColor () const
	Returns the current background color.
virtual Width	getAlineaWidth () const
	Returns the current alinea width, expressed in pixels.
virtual void	setAlineaWidth (Width newAlineaWidth)
	Sets the current alinea width, in pixels.
virtual std::string	describeGlyphFor (Ceylan::Latin1Char character) const
	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
	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
	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)
	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)
	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)
	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)
	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)
	Blits specified text, encoded in Latin-1, in specified color, in specified location of specified surface, in a box of specified dimensions.
Static Public Member Functions
static RenderQuality	GetObtainedQualityFor (RenderQuality targetedQuality)
	Returns which quality would be used if specified rendering quality was requested.
static void	SetFontSettings (const Ceylan::Byte *fontData, Length characterWidth, Length characterHeight)
	Sets, if necessary, the parameters of the font used by the text back-end.
static std::string	InterpretRenderingStyle (RenderingStyle style)
	Returns a description of the specified rendering style.
Static Public Attributes
static Ceylan::System::FileLocator	FixedFontFileLocator
	Allows to keep track of fixed font directories.
static std::string	FontFileExtension = ".fnt"
	Extension of fixed font files ('.fnt').
static const Ceylan::Float32	SpaceWidthFactor = 0.7f
	The multiplying factor to apply to the font space width to compute the actual space width.
static std::string	FontPathEnvironmentVariable = "FONT_PATH"
	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 = 0x00
	Normal font rendering style.
static const RenderingStyle	Bold = 0x01
	Normal font rendering style.
static const RenderingStyle	Italic = 0x02
	Italic font rendering style.
static const RenderingStyle	Underline = 0x04
	Underline font rendering style.
static const Ceylan::System::Size	DefaultGlyphCachedQuota = 4 * 1024 * 1024
	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 = 6 * 1024 * 1024
	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 = 8 * 1024 * 1024
	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 = 6
	Defines the default width for an alinea as a multiple of the width of a space.
Protected Member Functions
virtual void	loadFontFrom (const std::string &fontFilename)
	Loads the fixed font from specified file.
virtual const Surface &	submitLatin1GlyphToCache (Ceylan::Latin1Char character, Pixels::ColorDefinition glyphColor)
	Renders specified glyph, puts it in cache, and returns a 'const' reference whose ownership is kept by the cache (hence the caller should not deallocate the returned surface).
virtual Surface &	basicRenderLatin1Glyph (Ceylan::Latin1Char character, Pixels::ColorDefinition glyphColor)
	Renders specified glyph (Latin-1 character) in specified color, on a new surface, directly thanks to the font backend: no quality nor cache are taken into account.
virtual void	basicBlitLatin1Glyph (Surface &targetSurface, Coordinate x, Coordinate y, Ceylan::Latin1Char character, Pixels::ColorDefinition glyphColor)
	Blits specified glyph (Latin-1 character) in specified color, on specified location of given surface, directly thanks to the font backend: no quality nor cache are taken into account.
Surface &	renderLatin1TextWithWordCached (const std::string &text, RenderQuality quality, Pixels::ColorDefinition textColor)
	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)
	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)
	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)
	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)
	Renders specified Latin-1 text with specified quality, in specified color, directly thanks to the font backend: no cache is taken into account.
Static Protected Member Functions
static std::string	BuildFontFilenameFor (Length characterWidth, Length characterHeight, RenderingStyle renderingStyle)
	Returns the name of the font file which would correspond to the specified settings.
static void	GetFontAttributesFrom (const std::string &filename, Length &characterWidth, Length &characterHeight, RenderingStyle &renderingStyle)
	Returns in specified variables the font attributes guessed from the filename.
Protected Attributes
Length	_width
	The character width for this font.
Length	_height
	The character height for this font.
char *	_fontData
	The data describing the characters of the font.
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.
Static Protected Attributes
static const RenderQuality	DefaultQuality = Solid
	As no specific quality is managed, a default quality is passed in cache entries.
static const Ceylan::Uint16	FontCharacterCount = 256
	Defines the number of potential different characters in a fixed font.
Private Member Functions
	FixedFont (const FixedFont &source)
	Copy constructor made private to ensure that it will be never called.
FixedFont &	operator= (const FixedFont &source)
	Assignment operator made private to ensure that it will be never called.

Detailed Description

Models fixed fonts, a category which gathers all fonts whose rendering demands little resources, but cannot be scaled, as opposed to Truetype fonts.

Fixed fonts usually have a character set including at least all alphanumerical characters, including capital letters, plus most special characters. They should provide at least a full support for characters encoded according to Latin-1.

For these fonts, the baseline is chosen to be at the very bottom of the glyph: no glyph goes below the baseline.

These fonts are loaded from font files, whose extension is usually '.fnt'. The font files are searched first 'as specified', using directly the specified filename (which may be absolute or relative to the current directory), then using the fixed font locator, then the overall font locator.

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 by hidden only by the pixels corresponding to the text.

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.

Only the blit and render methods for glyphs are declared and defined in this class, since their counterparts for words and texts are built upon them and already available through inheritance (Font mother class).

Font rendering should only occur after the video has been initialized (setMode).

See also:: http://jcatki.no-ip.org/SDL_ttf/metrics.png for informations about glyph metrics.

Note:: Most lenghts are given alongside a directed axis, and therefore they can be negative.

Definition at line 185 of file OSDLFixedFont.h.

Member Enumeration Documentation

enum OSDL::Video::TwoDimensional::Text::Font::AllowedCachePolicy [inherited]

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 548 of file OSDLFont.h.

enum OSDL::Video::TwoDimensional::Text::Font::RenderCache [inherited]

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 520 of file OSDLFont.h.

enum OSDL::Video::TwoDimensional::Text::Font::RenderQuality [inherited]

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 325 of file OSDLFont.h.

Constructor & Destructor Documentation

FixedFont::FixedFont	(	Length	characterWidth,
		Length	characterHeight,
		RenderingStyle	renderingStyle = `Normal`,
		bool	convertToDisplay = `true`,
		RenderCache	cacheSettings = `GlyphCached`,
		AllowedCachePolicy	cachePolicy = `DropLessRequestedFirst`,
		Ceylan::System::Size	quota = `0`
	)

Definition at line 185 of file OSDLFixedFont.cc.

References BuildFontFilenameFor(), and loadFontFrom().

FixedFont::FixedFont	(	const std::string &	fontFilename,
		bool	convertToDisplay = `true`,
		RenderCache	cacheSettings = `GlyphCached`,
		AllowedCachePolicy	cachePolicy = `DropLessRequestedFirst`,
		Ceylan::System::Size	quota = `0`
	)			`[explicit]`

Creates a new Fixed font from specified font file.

Parameters:

	fontFilename	the filename of the file where the font is stored, usually a .fnt file. These fonts are loaded from font files, whose extension is usually '.fnt'. The font files are searched first 'as specified', using directly the specified filename (which may be absolute or relative to the current directory), then using the fixed font locator, then the overall font locator.
	renderingStyle	the desired rendering style, which can be only one of the listed rendering styles (no combination of attributes allowed).
	convertToDisplay	tells whether a returned or cached rendering should have already been converted to display. Useful for classical 2D rendering, useless for OpenGL since surfaces will have to be converted nonetheless.
	cacheSettings	determines which renderings should be cached. The recommended - and default - setting is 'GlyphCached', since with fixed fonts words can be easily drawn from prerendered glyphs.
	cachePolicy	determines how the cache should behave regarding renderings being put in cache (store everything, enforce a maximum size taken 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'.

Exceptions:

FontException

if no corresponding font file could be found, or if cache setting is not known, etc.

Note:: The rendering style and the dimensions are deduced from the font file name.

Definition at line 207 of file OSDLFixedFont.cc.

References _height, OSDL::Video::TwoDimensional::Text::Font::_renderingStyle, _width, GetFontAttributesFrom(), and loadFontFrom().

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

Fixed font virtual destructor.

Definition at line 228 of file OSDLFixedFont.cc.

References _fontData.

OSDL::Video::TwoDimensional::Text::FixedFont::FixedFont ( const FixedFont & source ) [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

void FixedFont::basicBlitLatin1Glyph	(	Surface &	targetSurface,
		Coordinate	x,
		Coordinate	y,
		Ceylan::Latin1Char	character,
		Pixels::ColorDefinition	glyphColor
	)			`[protected, virtual]`

Blits specified glyph (Latin-1 character) in specified color, on specified location of given surface, directly thanks to the font backend: no quality nor cache are taken into account.

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

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. For fixed font, only the 'Solid' quality is available.
	glyphColor	the color definition for the glyph.

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

Exceptions:

FontException

on error.

Definition at line 979 of file OSDLFixedFont.cc.

References _fontData, _height, _width, OSDL::Video::Pixels::convertColorDefinitionToRawPixelColor(), OSDL::Utils::getBackendLastError(), OSDL::Video::Surface::getSDLSurface(), and SetFontSettings().

Referenced by basicRenderLatin1Glyph().

Surface & FixedFont::basicRenderLatin1Glyph	(	Ceylan::Latin1Char	character,
		Pixels::ColorDefinition	glyphColor
	)			`[protected, virtual]`

Renders specified glyph (Latin-1 character) in specified color, on a new surface, directly thanks to the font backend: no quality nor cache are taken into account.

Colorkeys and conversion to display are however enforced.

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

Definition at line 922 of file OSDLFixedFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_convertToDisplay, _height, _width, OSDL::Video::Pixels::areEqual(), basicBlitLatin1Glyph(), OSDL::Video::Pixels::Black, OSDL::Video::Surface::ColorkeyBlit, OSDL::Video::Pixels::convertColorDefinitionToPixelColor(), OSDL::Video::Surface::convertToDisplay(), OSDL::Video::Surface::fill(), OSDL::Video::Surface::getPixelFormat(), OSDL::Video::Pixels::getRecommendedColorMasks(), OSDL::Video::Surface::Hardware, OSDL::Video::Surface::RLEColorkeyBlit, OSDL::Video::Surface::setColorKey(), and OSDL::Video::Pixels::White.

Referenced by submitLatin1GlyphToCache().

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

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:

FontException

on error.

Definition at line 1507 of file OSDLFont.cc.

Referenced by OSDL::Video::TwoDimensional::Text::Font::blitLatin1Word(), OSDL::Video::TwoDimensional::Text::Font::getConstLatin1WordFromCache(), OSDL::Video::TwoDimensional::Text::Font::renderLatin1Text(), and OSDL::Video::TwoDimensional::Text::Font::renderLatin1TextWithTextCached().

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`
	)			`[pure virtual, inherited]`

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:

FontException

on error.

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

Referenced by OSDL::Video::TwoDimensional::Text::Font::basicRenderLatin1Text().

virtual void OSDL::Video::TwoDimensional::Text::FixedFont::blitLatin1Glyph	(	Surface &	targetSurface,
		Coordinate	x,
		Coordinate	y,
		Ceylan::Latin1Char	character,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	glyphColor = `Pixels::White`
	)			`[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. For fixed fonts, only the 'Solid' quality is available.
	glyphColor	the color definition for the glyph.

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

Exceptions:

FontException

on error.

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`
	)			`[virtual, inherited]`

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:

FontException

on error.

Definition at line 1006 of file OSDLFont.cc.

References OSDL::Video::Surface::blitTo(), and OSDL::Video::TwoDimensional::Text::Font::renderLatin1MultiLineText().

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`
	)			`[virtual, inherited]`

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:

FontException

on error.

Definition at line 983 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::UprightRectangle::getHeight(), OSDL::Video::TwoDimensional::UprightRectangle::getUpperLeftAbscissa(), OSDL::Video::TwoDimensional::UprightRectangle::getUpperLeftOrdinate(), OSDL::Video::TwoDimensional::UprightRectangle::getWidth(), OSDL::Video::Surface::toString(), and OSDL::Video::TwoDimensional::UprightRectangle::toString().

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

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:

FontException

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

Definition at line 481 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_cacheSettings, OSDL::Video::TwoDimensional::Text::Font::_textCache, OSDL::Video::Surface::blitTo(), OSDL::Video::TwoDimensional::Text::Font::renderLatin1Text(), and OSDL::Video::TwoDimensional::Text::Font::TextCached.

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

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:

FontException

on error.

Definition at line 1371 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_cacheSettings, OSDL::Video::TwoDimensional::Text::Font::basicRenderLatin1Text(), OSDL::Video::Surface::blitTo(), OSDL::Video::TwoDimensional::Text::Font::getConstLatin1WordFromCache(), OSDL::Video::TwoDimensional::Text::Font::TextCached, and OSDL::Video::TwoDimensional::Text::Font::WordCached.

string FixedFont::BuildFontFilenameFor	(	Length	characterWidth,
		Length	characterHeight,
		RenderingStyle	renderingStyle
	)			`[static, protected]`

Returns the name of the font file which would correspond to the specified settings.

Parameters:

	characterWidth	the character width.
	characterHeight	the character height.
	renderingStyle	the rendering style. For fixed fonts, attributes (bold, italic, etc.) cannot be mixed.

Exceptions:

FontException

if the settings could not be satisfied.

Definition at line 1016 of file OSDLFixedFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::Bold, FontFileExtension, OSDL::Video::TwoDimensional::Text::Font::Italic, toString(), OSDL::Video::Pixels::toString(), and OSDL::Video::TwoDimensional::Text::Font::Underline.

Referenced by FixedFont().

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

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 395 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::getAdvance(), OSDL::Video::TwoDimensional::Text::Font::getHeightAboveBaseline(), OSDL::Video::TwoDimensional::Text::Font::getWidth(), OSDL::Video::TwoDimensional::Text::Font::getWidthOffset(), OSDL::Video::TwoDimensional::Text::Font::toString(), and OSDL::Video::Pixels::toString().

SignedLength FixedFont::getAdvance ( Ceylan::Latin1Char character ) const [virtual]

Returns the advance (recommended width containing a glyph, so that they can be chained in a word), which with fixed fonts does not depend on the specific character being rendered.

Parameters:

character

any character has the same advance.

Exceptions:

FontException

if the glyph metrics could not be retrieved.

Note:: This method exists only because the interface demands it.

See also:: getAdvance()

Implements OSDL::Video::TwoDimensional::Text::Font.

Definition at line 284 of file OSDLFixedFont.cc.

References _width.

SignedLength FixedFont::getAdvance ( ) const [virtual]

Returns the advance (recommended width containing a glyph, so that they can be chained in a word), which with fixed fonts does not depend on the specific character being rendered.

This method is not inherited from Font.

Exceptions:

FontException

if the glyph metrics could not be retrieved.

Definition at line 275 of file OSDLFixedFont.cc.

References _width.

Referenced by getBoundingBox(), and getBoundingBoxFor().

Width Font::getAlineaWidth ( ) const [virtual, inherited]

Returns the current alinea width, expressed in pixels.

Definition at line 379 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_alineaWidth.

SignedHeight FixedFont::getAscent ( ) const [virtual]

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

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

Remember that multiline printing is not enabled here, so the user is responsible for line spacing, see getLineSkip as well.

Note:: At the moment, no baseline information is available in descriptions of fixed fonts. The baseline is thus chosen to be at the very bottom of the glyphs, hence the ascent is equal to the height returned by getHeight.

Implements OSDL::Video::TwoDimensional::Text::Font.

Definition at line 312 of file OSDLFixedFont.cc.

References _height.

OSDL::Video::Pixels::ColorDefinition Font::getBackgroundColor ( ) const [inherited]

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 370 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_backgroundColor.

UprightRectangle & FixedFont::getBoundingBox ( ) const [virtual]

Returns a rectangular bounding box corresponding to the rendering of a glyph (with fixed fonts all characters are of the same size).

The returned height is the same as the one you can get using the getHeight method.

The upright rectangle has its lower left corner set to the origin.

Returns:: an upright rectangle enclosing the character (bounding box), whose lower left corner is located at the origin.

Exceptions:

FontException

if an error occured.

Definition at line 343 of file OSDLFixedFont.cc.

References getAdvance(), and getLineSkip().

UprightRectangle & FixedFont::getBoundingBoxFor ( const std::string & word ) const [virtual]

Returns a rectangular bounding box corresponding to the rendering of specified word, encoded in ASCII.

The returned height is the same as the one you can get using the getHeight method.

The upright rectangle has its lower left corner set to the origin.

Parameters:

word

the nonempty ASCII encoded string to size up. This must be a word, therefore including no whitespace, since they have to be handled separately, depending on the container room.

Returns:: an upright rectangle enclosing the word (bounding box), whose lower left corner is located at the origin.

Note:: After the last character, no other character is expected to be added, therefore no advance is taken into account for this last character.

Exceptions:

FontException

if an error occured, for example if the specified word is empty.

Definition at line 352 of file OSDLFixedFont.cc.

References _height, _width, and getAdvance().

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

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:

FontException

on error.

Definition at line 1439 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_textCache, and OSDL::Video::TwoDimensional::Text::Font::basicRenderLatin1Text().

Referenced by OSDL::Video::TwoDimensional::Text::Font::blitLatin1Word(), OSDL::Video::TwoDimensional::Text::Font::renderLatin1MultiLineText(), and OSDL::Video::TwoDimensional::Text::Font::renderLatin1TextWithWordCached().

SignedHeight FixedFont::getDescent ( ) const [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 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 here, so the user is responsible for line spacing, see getLineSkip as well.

Note:: At the moment, no baseline information is available in descriptions of fixed fonts. The baseline is thus chosen to be at the very bottom of the glyphs, hence the descent is equal to zero.

Implements OSDL::Video::TwoDimensional::Text::Font.

Definition at line 319 of file OSDLFixedFont.cc.

void FixedFont::GetFontAttributesFrom	(	const std::string &	filename,
		Length &	characterWidth,
		Length &	characterHeight,
		RenderingStyle &	renderingStyle
	)			`[static, protected]`

Returns in specified variables the font attributes guessed from the filename.

Parameters:

	the	input filename, without any path (ex: '10x20.fnt', '8x13B.fnt', etc.)
	characterWidth	where the guessed width is stored.
	characterHeight	where the guessed height is stored.
	renderingStyle	where the guessed style is stored.

Exceptions:

FontException

if the font settings could not be guessed from the filename.

Definition at line 1067 of file OSDLFixedFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::Bold, FontFileExtension, OSDL::Video::TwoDimensional::Text::Font::Italic, OSDL::Video::TwoDimensional::Text::Font::Normal, and OSDL::Video::TwoDimensional::Text::Font::Underline.

Referenced by FixedFont().

Text::Height FixedFont::getHeight ( ) const [virtual]

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

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

Remember that multiline printing is not enabled here, so the user is responsible for line spacing, see getLineSkip as well.

Implements OSDL::Video::TwoDimensional::Text::Font.

Definition at line 303 of file OSDLFixedFont.cc.

References _height.

SignedHeight FixedFont::getHeightAboveBaseline ( Ceylan::Latin1Char character ) const [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:

FontException

if the glyph metrics could not be retrieved.

Note:: For fixed font, height above baseline does not depend on the specific character being chosen, and is equal to the height of this fixed font.

Implements OSDL::Video::TwoDimensional::Text::Font.

Definition at line 265 of file OSDLFixedFont.cc.

References _height.

Width FixedFont::getInterGlyphWidth ( ) const [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.

The default value is one pixel.

Reimplemented from OSDL::Video::TwoDimensional::Text::Font.

Definition at line 294 of file OSDLFixedFont.cc.

Text::Height FixedFont::getLineSkip ( ) const [virtual]

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

This is usually larger than the value returned by getHeight.

Implements OSDL::Video::TwoDimensional::Text::Font.

Definition at line 328 of file OSDLFixedFont.cc.

References _height.

Referenced by getBoundingBox().

static RenderQuality OSDL::Video::TwoDimensional::Text::FixedFont::GetObtainedQualityFor ( RenderQuality targetedQuality ) [static]

Returns which quality would be used if specified rendering quality was requested.

RenderingStyle Font::getRenderingStyle ( ) const [virtual, inherited]

Returns the current rendering style.

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

Definition at line 342 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_renderingStyle.

Width FixedFont::getWidth ( Ceylan::Latin1Char character ) const [virtual]

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

Parameters:

character

the character whose width will be returned.

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

Note:: For fixed font, width does not depend on the specific character being chosen.

See also:: getAdvance

Implements OSDL::Video::TwoDimensional::Text::Font.

Definition at line 247 of file OSDLFixedFont.cc.

References _width.

Width FixedFont::getWidth ( ) const [virtual]

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

You may use this width for rendering text as close together horizontally as possible. At least one pixel should be added, so that glyphs cannot touch.

Note:: Width is constant in this fixed font special case.

Definition at line 238 of file OSDLFixedFont.cc.

References _width.

Referenced by loadFontFrom().

SignedWidth FixedFont::getWidthOffset ( Ceylan::Latin1Char character ) const [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.

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

Exceptions:

FontException

if the glyph metrics could not be retrieved.

Note:: For fixed font, offset width does not depend on the specific character chosen, and is null, as already taken into account into character width.

Implements OSDL::Video::TwoDimensional::Text::Font.

Definition at line 256 of file OSDLFixedFont.cc.

string Font::InterpretRenderingStyle ( RenderingStyle style ) [static, inherited]

Returns a description of the specified rendering style.

Parameters:

style

the rendering style to describe.

Definition at line 1124 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::Bold, OSDL::Video::TwoDimensional::Text::Font::Italic, OSDL::Video::TwoDimensional::Text::Font::Normal, and OSDL::Video::TwoDimensional::Text::Font::Underline.

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

void FixedFont::loadFontFrom ( const std::string & fontFilename ) [protected, virtual]

Loads the fixed font from specified file.

Parameters:

fontFilename

the font filename, whose extension is generally '.fnt';

Exceptions:

FontException

if the font coud not be loaded.

Definition at line 758 of file OSDLFixedFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_alineaWidth, _fontData, OSDL::Video::TwoDimensional::Text::Font::_spaceWidth, OSDL::Video::TwoDimensional::Text::Font::DefaultSpaceBasedAlineaWidth, FixedFontFileLocator, OSDL::Video::TwoDimensional::Text::Font::FontFileLocator, OSDL::Video::TwoDimensional::Text::Font::FontPathEnvironmentVariable, getWidth(), SpaceWidthFactor, and toString().

Referenced by FixedFont().

FixedFont& OSDL::Video::TwoDimensional::Text::FixedFont::operator= ( const FixedFont & source ) [private]

Assignment operator made private to ensure that it will be never called.

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

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

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:

FontException

on error.

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

virtual Surface& OSDL::Video::TwoDimensional::Text::FixedFont::renderLatin1Glyph	(	Ceylan::Latin1Char	character,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	glyphColor = `Pixels::White`
	)			`[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 only 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. For fixed fonts, only the 'Solid' quality is available.
	glyphColor	the color definition for the glyph.

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

Exceptions:

FontException

on error.

virtual Surface& OSDL::Video::TwoDimensional::Text::FixedFont::renderLatin1GlyphAlpha	(	Ceylan::Latin1Char	character,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	glyphColor = `Pixels::White`
	)			`[virtual]`

Note:: This method should not be used.

This method was kept so that one day this alpha-blending based version of 'renderLatin1Glyph' method could work. We never managed to have it working despite numerous attempts. This is not too disappointing since colorkey is probably a better solution than alpha for characters.

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`
	)			`[virtual, inherited]`

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.

Note:: if there is a word too long to fit (even alone) on one line, the rendering will not fail but will stop before that word.

Exceptions:

FontException

on error.

Definition at line 555 of file OSDLFont.cc.

Referenced by OSDL::Video::TwoDimensional::Text::Font::blitLatin1MultiLineText(), and OSDL::Video::TwoDimensional::TextWidget::redrawBackBuffer().

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

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:

FontException

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

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

Definition at line 432 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_cacheSettings, OSDL::Video::TwoDimensional::Text::Font::basicRenderLatin1Text(), OSDL::Video::TwoDimensional::Text::Font::GlyphCached, OSDL::Video::TwoDimensional::Text::Font::None, OSDL::Video::TwoDimensional::Text::Font::renderLatin1TextWithTextCached(), OSDL::Video::TwoDimensional::Text::Font::renderLatin1TextWithWordCached(), OSDL::Video::TwoDimensional::Text::Font::TextCached, and OSDL::Video::TwoDimensional::Text::Font::WordCached.

Referenced by OSDL::Video::TwoDimensional::Text::Font::blitLatin1Text().

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

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:

FontException

on error.

Definition at line 1312 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_textCache, and OSDL::Video::TwoDimensional::Text::Font::basicRenderLatin1Text().

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

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

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:

FontException

on error.

Definition at line 1146 of file OSDLFont.cc.

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

void Font::setAlineaWidth ( Width newAlineaWidth ) [virtual, inherited]

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 386 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_alineaWidth.

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

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 361 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_backgroundColor.

void FixedFont::SetFontSettings	(	const Ceylan::Byte *	fontData,
		Length	characterWidth,
		Length	characterHeight
	)			`[static]`

Sets, if necessary, the parameters of the font used by the text back-end.

Parameters:

	fontData	the data describing the glyphs of the font, probably read from a font file. Use a null (0) pointer to specify that the SDL_gfx internal font should be used.
	characterWidth	the width of characters of this font.
	characterHeight	the height of characters of this font.

Note:: This method should be called instead of 'gfxPrimitivesSetFont', i.e. whenever wanting to change font.

This method remembers last fixed font settings and allows to reset SDL_gfx parameters (including its glyph cache) only when necessary, i.e. only when the specified settings do not match the current ones. Otherwise at each glyph rendering, even if the same font had just been used, we would have to reset SDL_gfx state (cache) since we would not be able to know whether it had been reset between the rendering of the two glyphs.

Exceptions:

FontException

if the operation failed or is not supported.

Definition at line 697 of file OSDLFixedFont.cc.

Referenced by basicBlitLatin1Glyph(), and OSDL::Video::TwoDimensional::Text::printBasic().

void Font::setRenderingStyle ( RenderingStyle newStyle ) [virtual, inherited]

Sets the current rendering style for this font.

Exceptions:

FontException

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 351 of file OSDLFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_renderingStyle.

const Surface & FixedFont::submitLatin1GlyphToCache	(	Ceylan::Latin1Char	character,
		Pixels::ColorDefinition	glyphColor
	)			`[protected, virtual]`

Renders specified glyph, puts it in cache, and returns a 'const' reference whose ownership is kept by the cache (hence the caller should not deallocate the returned surface).

The specified character should not be already in cache ; its key should not already be associated.

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 glyph cache when the specified key is still to be associated. It does that independently of the cache settings (glyph, word, text, etc.).

One should ensure the corresponding cache key is not already in use, notably if the 'NeverDrop' cache policy is chosen.

Parameters:

	character	the Latin-1 character to have rendered.
	glyphColor	the color definition for the glyph.

Returns:: a 'const' referencec to a glyph in cache.

Exceptions:

FontException

on error, including 'NeverDrop' policy being used and an entry already existing.

Definition at line 875 of file OSDLFixedFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_glyphCache, basicRenderLatin1Glyph(), DefaultQuality, and OSDL::Video::Pixels::toString().

const string FixedFont::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const [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 from OSDL::Video::TwoDimensional::Text::Font.

Definition at line 660 of file OSDLFixedFont.cc.

References _height, and _width.

Referenced by BuildFontFilenameFor(), and loadFontFrom().

Member Data Documentation

Width OSDL::Video::TwoDimensional::Text::Font::_alineaWidth [protected, inherited]

Records the width of an alinea space, in pixels, to be put at the beginning of a paragraph.

Note:: All child classes should initialize it appropriately, in their constructors.

Definition at line 1651 of file OSDLFont.h.

Referenced by OSDL::Video::TwoDimensional::Text::Font::getAlineaWidth(), OSDL::Video::TwoDimensional::Text::TrueTypeFont::load(), loadFontFrom(), OSDL::Video::TwoDimensional::Text::Font::renderLatin1MultiLineText(), and OSDL::Video::TwoDimensional::Text::Font::setAlineaWidth().

Pixels::ColorDefinition OSDL::Video::TwoDimensional::Text::Font::_backgroundColor [protected, inherited]

Defines what is the background color, for 'Shaded' quality.

Definition at line 1623 of file OSDLFont.h.

Referenced by OSDL::Video::TwoDimensional::Text::TrueTypeFont::basicRenderUnicodeGlyph(), OSDL::Video::TwoDimensional::Text::Font::getBackgroundColor(), OSDL::Video::TwoDimensional::Text::TrueTypeFont::renderLatin1Text(), OSDL::Video::TwoDimensional::Text::TrueTypeFont::renderUnicodeText(), OSDL::Video::TwoDimensional::Text::TrueTypeFont::renderUTF8Text(), and OSDL::Video::TwoDimensional::Text::Font::setBackgroundColor().

RenderCache OSDL::Video::TwoDimensional::Text::Font::_cacheSettings [protected, inherited]

Describes the settings of the render cache.

Definition at line 1586 of file OSDLFont.h.

Referenced by OSDL::Video::TwoDimensional::Text::Font::blitLatin1Text(), OSDL::Video::TwoDimensional::Text::Font::blitLatin1Word(), OSDL::Video::TwoDimensional::Text::Font::Font(), OSDL::Video::TwoDimensional::Text::Font::renderLatin1MultiLineText(), OSDL::Video::TwoDimensional::Text::Font::renderLatin1Text(), OSDL::Video::TwoDimensional::Text::TrueTypeFont::renderUnicodeGlyph(), and OSDL::Video::TwoDimensional::Text::Font::toString().

bool OSDL::Video::TwoDimensional::Text::Font::_convertToDisplay [protected, inherited]

Tells whether returned and cached renderings should be converted to display beforehand.

Definition at line 1581 of file OSDLFont.h.

char* OSDL::Video::TwoDimensional::Text::FixedFont::_fontData [protected]

The data describing the characters of the font.

Definition at line 1008 of file OSDLFixedFont.h.

Referenced by basicBlitLatin1Glyph(), loadFontFrom(), and ~FixedFont().

Ceylan::SmartResourceManager<CharColorQualityKey>* OSDL::Video::TwoDimensional::Text::Font::_glyphCache [protected, inherited]

The smart resource manager that would cache rendered glyphs, should the GlyphCached render cache be selected.

The keys used to specify a glyph are made of a Latin-1 character and a color specification.

Definition at line 1600 of file OSDLFont.h.

Referenced by OSDL::Video::TwoDimensional::Text::Font::Font(), OSDL::Video::TwoDimensional::Text::TrueTypeFont::renderUnicodeGlyph(), submitLatin1GlyphToCache(), OSDL::Video::TwoDimensional::Text::Font::toString(), and OSDL::Video::TwoDimensional::Text::Font::~Font().

Length OSDL::Video::TwoDimensional::Text::FixedFont::_height [protected]

The character height for this font.

Definition at line 1003 of file OSDLFixedFont.h.

Referenced by basicBlitLatin1Glyph(), basicRenderLatin1Glyph(), FixedFont(), getAscent(), getBoundingBoxFor(), getHeight(), getHeightAboveBaseline(), getLineSkip(), and toString().

RenderingStyle OSDL::Video::TwoDimensional::Text::Font::_renderingStyle [protected, inherited]

Records the current rendering style (Normal, Bold, etc.

) of this font.

Definition at line 1572 of file OSDLFont.h.

Referenced by FixedFont(), OSDL::Video::TwoDimensional::Text::Font::getRenderingStyle(), OSDL::Video::TwoDimensional::Text::Font::setRenderingStyle(), and OSDL::Video::TwoDimensional::Text::Font::toString().

Width OSDL::Video::TwoDimensional::Text::Font::_spaceWidth [protected, inherited]

Records the width of a space, in pixels, if not null.

Useful for example with word cache, since two successive words have to be separated by such interval.

Note:: All child classes should initialize it appropriately, in their constructors.

Definition at line 1639 of file OSDLFont.h.

Referenced by OSDL::Video::TwoDimensional::Text::TrueTypeFont::load(), loadFontFrom(), OSDL::Video::TwoDimensional::Text::Font::renderLatin1MultiLineText(), and OSDL::Video::TwoDimensional::Text::Font::renderLatin1TextWithWordCached().

Ceylan::SmartResourceManager<StringColorQualityKey>* OSDL::Video::TwoDimensional::Text::Font::_textCache [protected, inherited]

The smart resource manager that would cache rendered words and/or text, should the WordCached or TextCached render cache be selected.

The keys used to specify a glyph are made of a Latin-1 encoded string and a color specification.

Definition at line 1614 of file OSDLFont.h.

Referenced by OSDL::Video::TwoDimensional::Text::Font::blitLatin1Text(), OSDL::Video::TwoDimensional::Text::Font::Font(), OSDL::Video::TwoDimensional::Text::Font::getConstLatin1WordFromCache(), OSDL::Video::TwoDimensional::Text::Font::renderLatin1MultiLineText(), OSDL::Video::TwoDimensional::Text::Font::renderLatin1TextWithTextCached(), OSDL::Video::TwoDimensional::Text::Font::toString(), and OSDL::Video::TwoDimensional::Text::Font::~Font().

Length OSDL::Video::TwoDimensional::Text::FixedFont::_width [protected]

The character width for this font.

Definition at line 998 of file OSDLFixedFont.h.

Referenced by basicBlitLatin1Glyph(), basicRenderLatin1Glyph(), FixedFont(), getAdvance(), getBoundingBoxFor(), getWidth(), and toString().

const RenderingStyle Font::Bold = 0x01 [static, inherited]

Normal font rendering style.

Definition at line 1327 of file OSDLFont.h.

Referenced by BuildFontFilenameFor(), GetFontAttributesFrom(), OSDL::Video::TwoDimensional::Text::Font::InterpretRenderingStyle(), and OSDL::Video::TwoDimensional::Text::Font::toString().

const Ceylan::System::Size Font::DefaultGlyphCachedQuota = 4 * 1024 * 1024 [static, inherited]

Defines the default quota value (maximum size of cached surfaces in memory, in bytes) if the cache is glyph-based.

This default quota is equal to 4 megabytes.

Definition at line 1350 of file OSDLFont.h.

Referenced by OSDL::Video::TwoDimensional::Text::Font::Font().

const RenderQuality OSDL::Video::TwoDimensional::Text::FixedFont::DefaultQuality = Solid [static, protected]

As no specific quality is managed, a default quality is passed in cache entries.

Definition at line 870 of file OSDLFixedFont.h.

Referenced by submitLatin1GlyphToCache().

const Ceylan::Uint8 Font::DefaultSpaceBasedAlineaWidth = 6 [static, inherited]

Defines the default width for an alinea as a multiple of the width of a space.

Definition at line 1386 of file OSDLFont.h.

Referenced by OSDL::Video::TwoDimensional::Text::TrueTypeFont::load(), and loadFontFrom().

const Ceylan::System::Size Font::DefaultTextCachedQuota = 8 * 1024 * 1024 [static, inherited]

Defines the default quota value (maximum size of cached surfaces in memory, in bytes) if the cache is text-based.

This default quota is equal to 8 megabytes.

Definition at line 1376 of file OSDLFont.h.

Referenced by OSDL::Video::TwoDimensional::Text::Font::Font(), and OSDL::Video::TwoDimensional::Text::Font::renderLatin1MultiLineText().

const Ceylan::System::Size Font::DefaultWordCachedQuota = 6 * 1024 * 1024 [static, inherited]

Defines the default quota value (maximum size of cached surfaces in memory, in bytes) if the cache is word-based.

This default quota is equal to 6 megabytes.

Definition at line 1363 of file OSDLFont.h.

Referenced by OSDL::Video::TwoDimensional::Text::Font::Font().

Ceylan::System::FileLocator Text::FixedFont::FixedFontFileLocator [static]

Allows to keep track of fixed font directories.

Definition at line 842 of file OSDLFixedFont.h.

Referenced by loadFontFrom().

const Ceylan::Uint16 Text::FixedFont::FontCharacterCount = 256 [static, protected]

Defines the number of potential different characters in a fixed font.

Definition at line 1073 of file OSDLFixedFont.h.

string Text::FixedFont::FontFileExtension = ".fnt" [static]

Extension of fixed font files ('.fnt').

Definition at line 847 of file OSDLFixedFont.h.

Referenced by BuildFontFilenameFor(), and GetFontAttributesFrom().

Ceylan::System::FileLocator Text::Font::FontFileLocator [static, inherited]

Allows to keep track of font directories.

Automatically gathers the list of directories specified as the value of the environment variable named as specified in FontPathEnvironmentVariable (FONT_PATH).

Definition at line 1297 of file OSDLFont.h.

Referenced by OSDL::Video::TwoDimensional::Text::TrueTypeFont::FindPathFor(), and loadFontFrom().

string Text::Font::FontPathEnvironmentVariable = "FONT_PATH" [static, inherited]

The name of the environment variable that may contain directory names that should contain font files.

Definition at line 1284 of file OSDLFont.h.

Referenced by OSDL::Video::TwoDimensional::Text::TrueTypeFont::FindPathFor(), and loadFontFrom().

const RenderingStyle Font::Italic = 0x02 [static, inherited]

Italic font rendering style.

Definition at line 1332 of file OSDLFont.h.

Referenced by BuildFontFilenameFor(), GetFontAttributesFrom(), OSDL::Video::TwoDimensional::Text::Font::InterpretRenderingStyle(), and OSDL::Video::TwoDimensional::Text::Font::toString().