OSDL::Video::TwoDimensional::Text::TrueTypeFont Class Reference

#include <OSDLTrueTypeFont.h>

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

[legend]

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

[legend]

List of all members.

Detailed Description

Truetype font.

A font can contain faces, which are specific sub-fonts, with particular size and style.

These fonts can be drawn with different qualities.

Latin-1 is an extension of ASCII, where ASCII only defines characters 0 through 127. Latin-1 continues and adds more common international symbols to define through character 255.

Plain ASCII is UTF-8 compatible.

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

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

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

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

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.
There exist some Truetype fonts that are actually 'fixed width'. They are supported by this class, even if the special case of fixed font could be managed thanks to the FixedFont class too.

Definition at line 121 of file OSDLTrueTypeFont.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
	TrueTypeFont (const std::string &fontFilename, PointSize pointSize, FontIndex index=0, bool convertToDisplay=true, RenderCache cacheSettings=GlyphCached) throw ( TextException )
	Creates a new Truetype font.
virtual	~TrueTypeFont () throw ()
	Font virtual destructor.
virtual PointSize	getPointSize () const throw ()
	Returns the point size of this font, expressed in dots per inch.
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 Width	getWidth (Ceylan::Latin1Char character) const throw ( TextException )
	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 (Ceylan::Latin1Char character) const throw ( TextException )
	Returns the advance of the specified glyph, rendered with this font, which is the space between the leftmost part of the glyph bounding box (actually, the origin in the glyph referential) and the same part of the next glyph.
virtual 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 Height	getLineSkip () const throw ()
	Returns the recommended pixel height of a rendered line of text of this font.
virtual Ceylan::Uint16	getFacesCount () const throw ()
	Returns the number of faces ("sub-fonts") available within this font.
virtual bool	isFixedWidth () const throw ()
	Returns whether the current font face of this font is a fixed width font.
virtual std::string	getFaceFamilyName () const throw ()
	Returns the family name of the current face.
virtual std::string	getFaceStyleName () const throw ()
	Returns the style name of the current face.
virtual UprightRectangle &	getBoundingBoxFor (Ceylan::Unicode glyph, SignedLength &advance) const throw ( TextException )
	Returns the metrics of a glyph specified by its Unicode character.
virtual UprightRectangle &	getBoundingBoxFor (const std::string &text) const throw ( TextException )
	Returns a rectangular bounding box corresponding to the rendering of specified text, encoded in Latin-1.
virtual UprightRectangle &	getBoundingBoxForUTF8 (const std::string &text) const throw ( TextException )
	Returns a rectangular bounding box corresponding to the rendering of specified text, encoded in UTF-8.
virtual UprightRectangle &	getBoundingBoxForUnicode (const Ceylan::Unicode *text) const throw ( TextException )
	Returns a rectangular bounding box corresponding to the rendering of specified text, encoded in Unicode.
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 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 &	renderUnicodeGlyph (Ceylan::Unicode character, RenderQuality quality=Solid, Pixels::ColorDefinition textColor=Pixels::White) throw ( TextException )
	Renders specified glyph, specified as a Unicode-encoded character, in specified color, in a returned 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.
virtual Surface &	renderUTF8Text (const std::string &text, RenderQuality quality=Solid, Pixels::ColorDefinition textColor=Pixels::White) throw ( TextException )
	Renders specified text, encoded in UTF-8, in specified color, in a returned surface.
virtual Surface &	renderUnicodeText (const Ceylan::Unicode *text, RenderQuality quality=Solid, Pixels::ColorDefinition textColor=Pixels::Black) throw ( TextException )
	Renders specified text, encoded in Unicode, in specified color, in a returned surface.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const throw ()
	Returns an user-friendly description of the state of this object.
void	SetUnicodeSwapStatus (bool newStatus) throw ()
	Determines whether Unicode data is to be swapped relative to the CPU endianness.
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	getInterGlyphWidth () const throw ()
	Returns the width of the recommended space between two glyphs.
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 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 std::string	DescribeLastError () throw ()
	Returns a textual description of the last error that occured relatively to Truetype fonts.
static std::string	InterpretRenderingStyle (RenderingStyle style) throw ()
	Returns a description of the specified rendering style.
Static Public Attributes
static Ceylan::System::FileLocator	TrueTypeFontFileLocator
	Allows to keep track of Truetype font directories.
static std::string	TrueTypeFontFileExtension = ".ttf"
	Recommended extension of TrueType font files.
static const Ceylan::Float32	SpaceWidthFactor = 1
	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 Surface &	basicRenderUnicodeGlyph (Ceylan::Unicode character, RenderQuality quality, Pixels::ColorDefinition glyphColor) throw ( TextException )
	Renders specified glyph (Unicode character) in specified color, on a new surface, directly thanks to the font backend: no cache is 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.
Protected Attributes
PointSize	_pointSize
	The size of a point, based on 72 dots per inch.
LowLevelTTFFont *	_actualFont
	Stores the actual TTF 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 Ceylan::Uint32	FontCounter = 0
	Records how many fonts are currently on use, to perform back-end clean-up as soon as no font is in use anymore.
Private Member Functions
	TrueTypeFont (const TrueTypeFont &source) throw ()
	Copy constructor made private to ensure that it will be never called.
TrueTypeFont &	operator= (const TrueTypeFont &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

TrueTypeFont::TrueTypeFont	(	const std::string &	fontFilename,
		PointSize	pointSize,
		FontIndex	index = `0`,
		bool	convertToDisplay = `true`,
		RenderCache	cacheSettings = `GlyphCached`
	)			throw ( TextException )

Creates a new Truetype font.

Parameters:

	fontFilename	the filename of the file where the font is stored, usually a .ttf, .TTF or a .FON file. The filename will be interpreted first 'as is', i.e. as an absolute path or a relative path to the current directory. If it does not succeed, the font file will be searched through directories listed in the Truetype file locator. If it fails again, the list of directories specified in the FONT_PATH environment variable will be scanned for that filename, if any.
	pointSize	the size of a point, based on 72 dots per inch. This basically translates to pixel height.
	index	the index of this font in specified file.
	convertToDisplay	tells whether a returned or cached rendering should have already been converted to display.
	cacheSettings	determines which renderings should be cached. The recommended - and default - setting is 'GlyphCached'.

Exceptions:

TextException

if the file could not be found or if the font library did not initialize properly.

Definition at line 63 of file OSDLTrueTypeFont.cc.

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

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

Font virtual destructor.

Definition at line 173 of file OSDLTrueTypeFont.cc.

References _actualFont, and FontCounter.

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

PointSize TrueTypeFont::getPointSize ( ) const throw () [virtual]

Returns the point size of this font, expressed in dots per inch.

Definition at line 192 of file OSDLTrueTypeFont.cc.

References _pointSize.

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

Returns the current rendering style.

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

Definition at line 200 of file OSDLTrueTypeFont.cc.

References _actualFont.

Referenced by setRenderingStyle().

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

Sets the current rendering style for this font.

Exceptions:

TextException

if the specified style is not supported.

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

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

Definition at line 217 of file OSDLTrueTypeFont.cc.

References _actualFont, and getRenderingStyle().

Width TrueTypeFont::getWidth ( Ceylan::Latin1Char character ) const throw ( TextException ) [virtual]

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

Parameters:

character

the character whose width will be returned.

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

Exceptions:

TextException

if the glyph metrics could not be retrieved.

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

Definition at line 245 of file OSDLTrueTypeFont.cc.

References _actualFont, DescribeLastError(), and getAdvance().

SignedWidth TrueTypeFont::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.

Exceptions:

TextException

if the glyph metrics could not be retrieved.

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

Definition at line 281 of file OSDLTrueTypeFont.cc.

References _actualFont, and DescribeLastError().

SignedHeight TrueTypeFont::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.

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

Definition at line 308 of file OSDLTrueTypeFont.cc.

References _actualFont, and DescribeLastError().

OSDL::Video::SignedLength TrueTypeFont::getAdvance ( Ceylan::Latin1Char character ) const throw ( TextException ) [virtual]

Returns the advance of the specified glyph, rendered with this font, which is the space between the leftmost part of the glyph bounding box (actually, the origin in the glyph referential) and the same part of the next glyph.

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

Parameters:

character

the character whose advance will be returned.

Exceptions:

TextException

if the glyph metrics could not be retrieved.

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

Definition at line 335 of file OSDLTrueTypeFont.cc.

References _actualFont, and DescribeLastError().

Referenced by getWidth().

Text::Height TrueTypeFont::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 it will space it, so they cannot touch.

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

See also:: getLineSkip

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

Definition at line 362 of file OSDLTrueTypeFont.cc.

References _actualFont.

Text::SignedHeight TrueTypeFont::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 it will space it, so they cannot touch.

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

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

Definition at line 379 of file OSDLTrueTypeFont.cc.

References _actualFont.

Text::SignedHeight TrueTypeFont::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 it with the glyph's maxy metric to resolve the top of the rectangle used when blitting the glyph on the screen.

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

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

Definition at line 396 of file OSDLTrueTypeFont.cc.

References _actualFont.

Text::Height TrueTypeFont::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 413 of file OSDLTrueTypeFont.cc.

References _actualFont.

Ceylan::Uint16 TrueTypeFont::getFacesCount ( ) const throw () [virtual]

Returns the number of faces ("sub-fonts") available within this font.

This is a count of the number of specific fonts contained in this font.

Note:: For the moment, no specific use of this information can be done through the library.

Definition at line 429 of file OSDLTrueTypeFont.cc.

References _actualFont.

Referenced by toString().

bool TrueTypeFont::isFixedWidth ( ) const throw () [virtual]

Returns whether the current font face of this font is a fixed width font.

Fixed width fonts are monospace, meaning all characters that exist in the font have the same width, thus you can assume that a rendered string's width is going to be the result of a simple calculation: stringWidth = glyphWidth * stringLength.

Definition at line 446 of file OSDLTrueTypeFont.cc.

References _actualFont.

Referenced by toString().

string TrueTypeFont::getFaceFamilyName ( ) const throw () [virtual]

Returns the family name of the current face.

Definition at line 463 of file OSDLTrueTypeFont.cc.

References _actualFont.

Referenced by toString().

string TrueTypeFont::getFaceStyleName ( ) const throw () [virtual]

Returns the style name of the current face.

Definition at line 480 of file OSDLTrueTypeFont.cc.

References _actualFont.

Referenced by toString().

UprightRectangle & TrueTypeFont::getBoundingBoxFor	(	Ceylan::Unicode	glyph,
		SignedLength &	advance
	)			const throw ( TextException ) `[virtual]`

Returns the metrics of a glyph specified by its Unicode character.

Parameters:

	glyph	the glyph whose metrics are to be returned.
	advance	will be set to the advance of this glyph.

The metrics are described as an upright rectangle which contains the glyph, defined from its upper left corner (xMin, yMax) to its lower right corner, (xMax, yMin) as shown in: http://jcatki.no-ip.org/SDL_ttf/metrics.png

Returns:: an upright rectangle enclosing the glyph (bounding box).

The caller gets ownership of this returned rectangle, it has therefore to delete it when the rectange is not to be used any more.

Exceptions:

TextException

on error, for example if the specified character does not exist in this font.

Width is xMax - xMin. Height is yMax - yMin. BearingX is xMin BearingY is yMax.

Definition at line 501 of file OSDLTrueTypeFont.cc.

References _actualFont, and DescribeLastError().

UprightRectangle & TrueTypeFont::getBoundingBoxFor ( const std::string & text ) const throw ( TextException ) [virtual]

Returns a rectangular bounding box corresponding to the rendering of specified text, encoded in Latin-1.

Correct kerning is done to get the actual width. The height returned is the same as you can get using the getHeight method.

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

The caller gets ownership of this returned rectangle, it has therefore to delete it when the rectange is not to be used any more.

Parameters:

text

the Latin-1 encoded string to size up.

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

Exceptions:

TextException

if an error occured, for example if a requested glyph does not exist.

Definition at line 534 of file OSDLTrueTypeFont.cc.

References _actualFont, and DescribeLastError().

UprightRectangle & TrueTypeFont::getBoundingBoxForUTF8 ( const std::string & text ) const throw ( TextException ) [virtual]

Returns a rectangular bounding box corresponding to the rendering of specified text, encoded in UTF-8.

Correct kerning is done to get the actual width. The height returned is the same as you can get using the getHeight method.

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

The caller gets ownership of this returned rectangle, it has therefore to delete it when the rectange is not to be used any more.

Parameters:

text

the UTF-8 encoded null terminated string to size up.

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

Exceptions:

TextException

if an error occured, for example if a requested glyph does not exist.

Definition at line 561 of file OSDLTrueTypeFont.cc.

References _actualFont, and DescribeLastError().

UprightRectangle & TrueTypeFont::getBoundingBoxForUnicode ( const Ceylan::Unicode * text ) const throw ( TextException ) [virtual]

Returns a rectangular bounding box corresponding to the rendering of specified text, encoded in Unicode.

Correct kerning is done to get the actual width. The height returned is the same as you can get using the getHeight method.

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

The caller gets ownership of this returned rectangle, it has therefore to delete it when the rectange is not to be used any more.

Parameters:

text

the Unicode encoded null terminated string to size up.

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

Exceptions:

TextException

if an error occured, for example if a requested glyph does not exist.

Definition at line 588 of file OSDLTrueTypeFont.cc.

References _actualFont, and DescribeLastError().

OSDL::Video::Surface & TrueTypeFont::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 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. If 'Shaded', the current background color will be used.
	glyphColor	the color definition for the glyph.

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

Exceptions:

TextException

on error.

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

Definition at line 623 of file OSDLTrueTypeFont.cc.

References renderUnicodeGlyph().

void TrueTypeFont::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. If 'Shaded', the current background color will be used.
	glyphColor	the color definition for the glyph.

Exceptions:

TextException

on error.

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

Definition at line 638 of file OSDLTrueTypeFont.cc.

References OSDL::Video::Surface::blitTo(), and renderUnicodeGlyph().

OSDL::Video::Surface & TrueTypeFont::renderUnicodeGlyph	(	Ceylan::Unicode	character,
		RenderQuality	quality = `Solid`,
		Pixels::ColorDefinition	textColor = `Pixels::White`
	)			throw ( TextException ) `[virtual]`

Renders specified glyph, specified as a Unicode-encoded character, in specified color, in a returned surface.

Unicode management is available with Truetype fonts, but may be not for other types of fonts.

The caller is responsible for deleting the returned surface.

Parameters:

	character	the character, encoded in Unicode, to render.
	quality	the chosen rendering quality. If 'Shaded', the current background color will be used.
	textColor	the color definition for the glyph. This becomes first index of colormap, in Solid and Shaded qualities.

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

Exceptions:

TextException

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

Definition at line 658 of file OSDLTrueTypeFont.cc.

References OSDL::Video::TwoDimensional::Text::Font::_cacheSettings, OSDL::Video::TwoDimensional::Text::Font::_glyphCache, basicRenderUnicodeGlyph(), and OSDL::Video::TwoDimensional::Text::Font::GlyphCached.

Referenced by blitLatin1Glyph(), and renderLatin1Glyph().

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

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

The caller is responsible for deleting the returned surface.

Parameters:

	text	the text, encoded in Latin-1, to render.
	quality	the chosen rendering quality. If 'Shaded', the current background color will be used.
	textColor	the color definition for the text. This becomes first index of colormap, in Solid and Shaded qualities.

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

Exceptions:

TextException

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

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

Definition at line 734 of file OSDLTrueTypeFont.cc.

References _act

OSDL::Video::TwoDimensional::Text::TrueTypeFont Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Private Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation