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

#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.

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 150 of file OSDLFixedFont.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
	FixedFont (Length characterWidth, Length characterHeight, RenderingStyle renderingStyle=Normal, bool convertToDisplay=true, RenderCache cacheSettings=GlyphCached, AllowedCachePolicy cachePolicy=DropLessRequestedFirst, Ceylan::System::Size quota=0) throw ( TextException )
	FixedFont (const std::string &fontFilename, bool convertToDisplay=true, RenderCache cacheSettings=GlyphCached, AllowedCachePolicy cachePolicy=DropLessRequestedFirst, Ceylan::System::Size quota=0) throw ( TextException )
	Creates a new Fixed font from specified font file.
virtual	~FixedFont () throw ()
	Fixed font virtual destructor.
virtual Width	getWidth () const throw ()
	Returns the maximum pixel width of all glyphs of this font.
virtual Width	getWidth (Ceylan::Latin1Char character) const throw ()
	Returns the width of the specified glyph, rendered with this font.
virtual SignedWidth	getWidthOffset (Ceylan::Latin1Char character) const throw ( TextException )
	Returns the width of the abscissa offset for the specified glyph, rendered with this font.
virtual SignedHeight	getHeightAboveBaseline (Ceylan::Latin1Char character) const throw ( TextException )
	Returns the height above baseline of the specified glyph, rendered with this font.
virtual SignedLength	getAdvance () const throw ( TextException )
	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 throw ( TextException )
	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 throw ()
	Returns the width of the recommended space between two glyphs.
virtual Text::Height	getHeight () const throw ()
	Returns the maximum pixel height of all glyphs of this font.
virtual SignedHeight	getAscent () const throw ()
	Returns the maximum pixel ascent (height above baseline) of all glyphs of this font.
virtual SignedHeight	getDescent () const throw ()
	Returns the maximum pixel descent (height below baseline) of all glyphs of this font.
virtual Text::Height	getLineSkip () const throw ()
	Returns the recommended pixel height of a rendered line of text of this font.
virtual UprightRectangle &	getBoundingBox () const throw ( TextException )
	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 throw ( TextException )
	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) 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) throw ( TextException )
	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) throw ( TextException )
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const throw ()
	Returns an user-friendly description of the state of this object.
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	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.
Static Public Member Functions
static RenderQuality	GetObtainedQualityFor (RenderQuality targetedQuality) throw ()
	Returns which quality would be used if specified rendering quality was requested.
static void	SetFontSettings (const Ceylan::Byte *fontData, Length characterWidth, Length characterHeight) throw ( TextException )
	Sets, if necessary, the parameters of the font used by the text back-end.
static std::string	InterpretRenderingStyle (RenderingStyle style) throw ()
	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) throw ( TextException )
	Loads the fixed font from specified file.
virtual const Surface &	submitLatin1GlyphToCache (Ceylan::Latin1Char character, Pixels::ColorDefinition glyphColor) throw ( TextException )
	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) throw ( TextException )
	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) throw ( TextException )
	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) 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.
Static Protected Member Functions
static std::string	BuildFontFilenameFor (Length characterWidth, Length characterHeight, RenderingStyle renderingStyle) throw ( TextException )
	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) throw ( TextException )
	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) throw ()
	Copy constructor made private to ensure that it will be never called.
FixedFont &	operator= (const FixedFont &source) throw ()
	Assignment operator made private to ensure that it will be never called.

Member Enumeration Documentation

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

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 501 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`
	)			throw ( TextException )

Definition at line 152 of file OSDLFixedFont.cc.

FixedFont::FixedFont	(	const std::string &	fontFilename,
		bool	convertToDisplay = `true`,
		RenderCache	cacheSettings = `GlyphCached`,
		AllowedCachePolicy	cachePolicy = `DropLessRequestedFirst`,
		Ceylan::System::Size	quota = `0`
	)			throw ( TextException ) `[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:

TextException

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 175 of file OSDLFixedFont.cc.

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

Fixed font virtual destructor.

Definition at line 197 of file OSDLFixedFont.cc.

References _fontData.

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

Width FixedFont::getWidth ( ) const throw () [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 207 of file OSDLFixedFont.cc.

References _width.

Referenced by loadFontFrom().

Width FixedFont::getWidth ( Ceylan::Latin1Char character ) const throw () [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 216 of file OSDLFixedFont.cc.

References _width.

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

TextException

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 225 of file OSDLFixedFont.cc.

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

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 235 of file OSDLFixedFont.cc.

References _height.

SignedLength FixedFont::getAdvance ( ) const throw ( TextException ) [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:

TextException

if the glyph metrics could not be retrieved.

Definition at line 245 of file OSDLFixedFont.cc.

References _width.

Referenced by getBoundingBox(), and getBoundingBoxFor().

SignedLength FixedFont::getAdvance ( Ceylan::Latin1Char character ) const throw ( TextException ) [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:

TextException

if the glyph metrics could not be retrieved.

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

()

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

Definition at line 254 of file OSDLFixedFont.cc.

References _width.

Width FixedFont::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.

The default value is one pixel.

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

Definition at line 265 of file OSDLFixedFont.cc.

Text::Height FixedFont::getHeight ( ) const throw () [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 274 of file OSDLFixedFont.cc.

References _height.

SignedHeight FixedFont::getAscent ( ) const throw () [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 283 of file OSDLFixedFont.cc.

References _height.

SignedHeight FixedFont::getDescent ( ) const throw () [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 290 of file OSDLFixedFont.cc.

Text::Height FixedFont::getLineSkip ( ) const throw () [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 299 of file OSDLFixedFont.cc.

References _height.

Referenced by getBoundingBox().

UprightRectangle & FixedFont::getBoundingBox ( ) const throw ( TextException ) [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:

TextException

if an error occured.

Definition at line 314 of file OSDLFixedFont.cc.

References getAdvance(), and getLineSkip().

UprightRectangle & FixedFont::getBoundingBoxFor ( const std::string & word ) const throw ( TextException ) [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:

TextException

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

Definition at line 323 of file OSDLFixedFont.cc.

References _height, _width, and getAdvance().

virtual Surface& OSDL::Video::TwoDimensional::Text::FixedFont::renderLatin1Glyph	(	Ceylan::Latin1Char	character,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	glyphColor = `Pixels::White`
	)			throw ( TextException ) `[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:

TextException

on error.

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`
	)			throw ( TextException ) `[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:

TextException

on error.

virtual Surface& OSDL::Video::TwoDimensional::Text::FixedFont::renderLatin1GlyphAlpha	(	Ceylan::Latin1Char	character,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	glyphColor = `Pixels::White`
	)			throw ( TextException ) `[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.

const string FixedFont::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 from OSDL::Video::TwoDimensional::Text::Font.

Definition at line 630 of file OSDLFixedFont.cc.

References _height, _width, and OSDL::Video::Pixels::toString().

Referenced by loadFontFrom().

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

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

void FixedFont::SetFontSettings	(	const Ceylan::Byte *	fontData,
		Length	characterWidth,
		Length	characterHeight
	)			throw ( TextException ) `[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:

TextException

if the operation failed or is not supported.

Definition at line 666 of file OSDLFixedFont.cc.

Referenced by basicBlitLatin1Glyph().

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

Loads the fixed font from specified file.

Parameters:

fontFilename

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

Exceptions:

TextException

if the font coud not be loaded.

Definition at line 726 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().

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

Renders specifi

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

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Private Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation