Crazy Eddie's GUI System  0.8.4
CEGUI::Font Class Reference

Class that encapsulates a typeface. More...

Inherits CEGUI::PropertySet, CEGUI::EventSet, and CEGUI::AllocatedObject< Font >.

Inherited by CEGUI::FreeTypeFont, and CEGUI::PixmapFont.

+ Collaboration diagram for CEGUI::Font:

List of all members.

Public Member Functions

virtual ~Font ()
 Destructor.
const StringgetName () const
 Return the string holding the font name.
const StringgetTypeName () const
 Return the type of the font.
const StringgetFileName () const
 Return the filename of the used font.
bool isCodepointAvailable (utf32 cp) const
 Return whether this Font can draw the specified code-point.
float drawText (GeometryBuffer &buffer, const String &text, const Vector2f &position, const Rectf *clip_rect, const ColourRect &colours, const float space_extra=0.0f, const float x_scale=1.0f, const float y_scale=1.0f) const
 Draw text into a specified area of the display.
void setNativeResolution (const Sizef &size)
 Set the native resolution for this Font.
const SizefgetNativeResolution () const
 Return the native display size for this Font. This is only relevant if the Font is being auto-scaled.
void setAutoScaled (const AutoScaledMode auto_scaled)
 Enable or disable auto-scaling for this Font.
AutoScaledMode getAutoScaled () const
 Checks whether this font is being auto-scaled and how.
virtual void notifyDisplaySizeChanged (const Sizef &size)
 Notify the Font that the display size may have changed.
float getLineSpacing (float y_scale=1.0f) const
 Return the pixel line spacing value for.
float getFontHeight (float y_scale=1.0f) const
 return the exact pixel height of the font.
float getBaseline (float y_scale=1.0f) const
 Return the number of pixels from the top of the highest glyph to the baseline.
float getTextExtent (const String &text, float x_scale=1.0f) const
 Return the pixel width of the specified text if rendered with this Font.
float getTextAdvance (const String &text, float x_scale=1.0f) const
 Return pixel advance of the specified text when rendered with this Font.
size_t getCharAtPixel (const String &text, float pixel, float x_scale=1.0f) const
 Return the index of the closest text character in String text that corresponds to pixel location pixel if the text were rendered.
size_t getCharAtPixel (const String &text, size_t start_char, float pixel, float x_scale=1.0f) const
 Return the index of the closest text character in String text, starting at character index start_char, that corresponds to pixel location pixel if the text were to be rendered.
void writeXMLToStream (XMLSerializer &xml_stream) const
 Writes an xml representation of this Font to out_stream.
const FontGlyphgetGlyphData (utf32 codepoint) const
 Return a pointer to the glyphDat struct for the given codepoint, or 0 if the codepoint does not have a glyph defined.

Static Public Member Functions

static void setDefaultResourceGroup (const String &resourceGroup)
 Sets the default resource group to be used when loading font data.
static const StringgetDefaultResourceGroup ()
 Returns the default resource group currently set for Fonts.

Static Public Attributes

static const argb_t DefaultColour
 Colour value used whenever a colour is not specified.
static const String EventNamespace
 Event namespace for font events.
static const String EventRenderSizeChanged

Protected Types

typedef std::map< utf32,
FontGlyph, std::less< utf32 >
CEGUI_MAP_ALLOC(utf32,
FontGlyph)> 
CodepointMap
 Definition of CodepointMap type.

Protected Member Functions

 Font (const String &name, const String &type_name, const String &filename, const String &resource_group, const AutoScaledMode auto_scaled, const Sizef &native_res)
 Constructor.
virtual void rasterise (utf32 start_codepoint, utf32 end_codepoint) const
 This function prepares a certain range of glyphs to be ready for displaying. This means that after returning from this function glyphs from d_cp_map[start_codepoint] to d_cp_map[end_codepoint] should have their d_image member set. If there is an error during rasterisation of some glyph, it's okay to leave the d_image field set to NULL, in which case such glyphs will be skipped from display.
virtual void updateFont ()=0
 Update the font as needed, according to the current parameters.
virtual void writeXMLToStream_impl (XMLSerializer &xml_stream) const =0
 implementaion version of writeXMLToStream.
void addFontProperties ()
 Register all properties of this class.
virtual void onRenderSizeChanged (FontEventArgs &args)
 event trigger function for when the font rendering size changes.
void setMaxCodepoint (utf32 codepoint)
 Set the maximal glyph index. This reserves the respective number of bits in the d_glyphPageLoaded array.
virtual const FontGlyphfindFontGlyph (const utf32 codepoint) const
 finds FontGlyph in map and returns it, or 0 if none.

Protected Attributes

String d_name
 Name of this font.
String d_type
 Type name string for this font (not used internally)
String d_filename
 Name of the file used to create this font (font file or imagset)
String d_resourceGroup
 Name of the font file's resource group.
float d_ascender
 maximal font ascender (pixels above the baseline)
float d_descender
 maximal font descender (negative pixels below the baseline)
float d_height
 (ascender - descender) + linegap
AutoScaledMode d_autoScaled
 which mode should we use for auto-scaling
Sizef d_nativeResolution
 native resolution for this Font.
float d_horzScaling
 current horizontal scaling factor.
float d_vertScaling
 current vertical scaling factor.
utf32 d_maxCodepoint
 Maximal codepoint for font glyphs.
uint * d_glyphPageLoaded
 This bitmap holds information about loaded 'pages' of glyphs. A glyph page is a set of 256 codepoints, starting at 256-multiples. For example, the 1st glyph page is 0-255, fourth is 1024-1279 etc. When a specific glyph is required for painting, the corresponding bit is checked to see if the respective page has been rasterised. If not, the rasterise() method is invoked, which prepares the glyphs from the respective glyph page for being painted.
CodepointMap d_cp_map
 Contains mappings from code points to Image objects.

Static Protected Attributes

static String d_defaultResourceGroup
 Holds default resource group for font loading.

Detailed Description

Class that encapsulates a typeface.

A Font object is created for each unique typeface required. The Font class provides methods for loading typefaces from various sources, and then for outputting text via the Renderer object.

This class is not specific to any font renderer, it just provides the basic interfaces needed to manage fonts.


Member Function Documentation

float CEGUI::Font::drawText ( GeometryBuffer buffer,
const String text,
const Vector2f position,
const Rectf clip_rect,
const ColourRect colours,
const float  space_extra = 0.0f,
const float  x_scale = 1.0f,
const float  y_scale = 1.0f 
) const

Draw text into a specified area of the display.

Parameters:
bufferGeometryBuffer object where the geometry for the text be queued.
textString object containing the text to be drawn.
positionReference to a Vector2 object describing the location at which the text is to be drawn.
clip_rectRect object describing the clipping area for the drawing. No drawing will occur outside this Rect.
coloursColourRect object describing the colours to be applied when drawing the text. NB: The colours specified in here are applied to each glyph, rather than the text as a whole.
space_extraNumber of additional pixels of spacing to be added to space characters.
x_scaleScaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
y_scaleScaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
Returns:
The x co-ord where subsequent text should be rendered to ensure correct positioning (which is not possible to determine accurately by using the extent measurement functions).

Checks whether this font is being auto-scaled and how.

Returns:
AutoScaledMode describing how this font should be auto scaled
float CEGUI::Font::getBaseline ( float  y_scale = 1.0f) const [inline]

Return the number of pixels from the top of the highest glyph to the baseline.

Parameters:
y_scaleScaling factor to be applied to the baseline distance, where 1.0f is considered to be 'normal'.
Returns:
pixel spacing from top of front glyphs to baseline
size_t CEGUI::Font::getCharAtPixel ( const String text,
float  pixel,
float  x_scale = 1.0f 
) const [inline]

Return the index of the closest text character in String text that corresponds to pixel location pixel if the text were rendered.

Parameters:
textString object containing the text.
pixelSpecifies the (horizontal) pixel offset to return the character index for.
x_scaleScaling factor to be applied to each glyph's x axis when measuring the text extent, where 1.0f is considered to be 'normal'.
Returns:
Returns a character index into String text for the character that would be rendered closest to horizontal pixel offset pixel if the text were to be rendered via this Font. Range of the return is from 0 to text.length(), so may actually return an index past the end of the string, which indicates pixel was beyond the last character.

References getCharAtPixel().

Referenced by getCharAtPixel().

size_t CEGUI::Font::getCharAtPixel ( const String text,
size_t  start_char,
float  pixel,
float  x_scale = 1.0f 
) const

Return the index of the closest text character in String text, starting at character index start_char, that corresponds to pixel location pixel if the text were to be rendered.

Parameters:
textString object containing the text.
start_charindex of the first character to consider. This is the lowest value that will be returned from the call.
pixelSpecifies the (horizontal) pixel offset to return the character index for.
x_scaleScaling factor to be applied to each glyph's x axis when measuring the text extent, where 1.0f is considered to be 'normal'.
Returns:
Returns a character index into String text for the character that would be rendered closest to horizontal pixel offset pixel if the text were to be rendered via this Font. Range of the return is from 0 to text.length(), so may actually return an index past the end of the string, which indicates pixel was beyond the last character.
static const String& CEGUI::Font::getDefaultResourceGroup ( ) [inline, static]

Returns the default resource group currently set for Fonts.

Returns:
String describing the default resource group identifier that will be used when loading font data.
float CEGUI::Font::getFontHeight ( float  y_scale = 1.0f) const [inline]

return the exact pixel height of the font.

Parameters:
y_scaleScaling factor to be applied to the height, where 1.0f is considered to be 'normal'.
Returns:
float value describing the pixel height of the font without any additional padding.
const FontGlyph* CEGUI::Font::getGlyphData ( utf32  codepoint) const

Return a pointer to the glyphDat struct for the given codepoint, or 0 if the codepoint does not have a glyph defined.

Parameters:
codepointutf32 codepoint to return the glyphDat structure for.
Returns:
Pointer to the glyphDat struct for codepoint, or 0 if no glyph is defined for codepoint.
float CEGUI::Font::getLineSpacing ( float  y_scale = 1.0f) const [inline]

Return the pixel line spacing value for.

Parameters:
y_scaleScaling factor to be applied to the line spacing, where 1.0f is considered to be 'normal'.
Returns:
Number of pixels between vertical base lines, i.e. The minimum pixel space between two lines of text.

Return the native display size for this Font. This is only relevant if the Font is being auto-scaled.

Returns:
Size object describing the native display size for this Font.
float CEGUI::Font::getTextAdvance ( const String text,
float  x_scale = 1.0f 
) const

Return pixel advance of the specified text when rendered with this Font.

Parameters:
textString object containing the text to return the pixel advance for.
x_scaleScaling factor to be applied to each glyph's x axis when measuring the advance, where 1.0f is considered to be 'normal'.
Returns:
pixel advance of text when rendered with this Font.
Note:
The difference between the advance and the extent of a text string is important for numerous reasons. Picture some scenario where a glyph has a swash which extends way beyond the subsequent glyph - the text extent of those two glyphs is to the end of the swash on the first glyph whereas the advance of those two glyphs is to the start of a theoretical third glyph - still beneath the swash of the first glyph. The difference can basically be summarised as follows:
  • the extent is the total rendered width of all glyphs in the string.
  • the advance is the width to the point where the next character would have been drawn.
See also:
getTextExtent
float CEGUI::Font::getTextExtent ( const String text,
float  x_scale = 1.0f 
) const

Return the pixel width of the specified text if rendered with this Font.

Parameters:
textString object containing the text to return the rendered pixel width for.
x_scaleScaling factor to be applied to each glyph's x axis when measuring the extent, where 1.0f is considered to be 'normal'.
Returns:
Number of pixels that text will occupy when rendered with this Font.
Note:
The difference between the advance and the extent of a text string is important for numerous reasons. Picture some scenario where a glyph has a swash which extends way beyond the subsequent glyph - the text extent of those two glyphs is to the end of the swash on the first glyph whereas the advance of those two glyphs is to the start of a theoretical third glyph - still beneath the swash of the first glyph. The difference can basically be summarised as follows:
  • the extent is the total rendered width of all glyphs in the string.
  • the advance is the width to the point where the next character would have been drawn.
See also:
getTextAdvance
bool CEGUI::Font::isCodepointAvailable ( utf32  cp) const [inline]

Return whether this Font can draw the specified code-point.

Parameters:
cputf32 code point that is the subject of the query.
Returns:
true if the font contains a mapping for code point cp, false if it does not contain a mapping for cp.
virtual void CEGUI::Font::notifyDisplaySizeChanged ( const Sizef size) [virtual]

Notify the Font that the display size may have changed.

Parameters:
sizeSize object describing the display resolution
virtual void CEGUI::Font::rasterise ( utf32  start_codepoint,
utf32  end_codepoint 
) const [protected, virtual]

This function prepares a certain range of glyphs to be ready for displaying. This means that after returning from this function glyphs from d_cp_map[start_codepoint] to d_cp_map[end_codepoint] should have their d_image member set. If there is an error during rasterisation of some glyph, it's okay to leave the d_image field set to NULL, in which case such glyphs will be skipped from display.

Parameters:
start_codepointThe lowest codepoint that should be rasterised
end_codepointThe highest codepoint that should be rasterised

Reimplemented in CEGUI::FreeTypeFont.

void CEGUI::Font::setAutoScaled ( const AutoScaledMode  auto_scaled)

Enable or disable auto-scaling for this Font.

Parameters:
auto_scaledAutoScaledMode describing how this font should be auto scaled
See also:
AutoScaledMode
static void CEGUI::Font::setDefaultResourceGroup ( const String resourceGroup) [inline, static]

Sets the default resource group to be used when loading font data.

Parameters:
resourceGroupString describing the default resource group identifier to be used.
Returns:
Nothing.
void CEGUI::Font::setNativeResolution ( const Sizef size)

Set the native resolution for this Font.

Parameters:
sizeSize object describing the new native screen resolution for this Font.
void CEGUI::Font::writeXMLToStream ( XMLSerializer xml_stream) const

Writes an xml representation of this Font to out_stream.

Parameters:
xml_streamStream where xml data should be output.
Returns:
Nothing.

Member Data Documentation

uint* CEGUI::Font::d_glyphPageLoaded [protected]

This bitmap holds information about loaded 'pages' of glyphs. A glyph page is a set of 256 codepoints, starting at 256-multiples. For example, the 1st glyph page is 0-255, fourth is 1024-1279 etc. When a specific glyph is required for painting, the corresponding bit is checked to see if the respective page has been rasterised. If not, the rasterise() method is invoked, which prepares the glyphs from the respective glyph page for being painted.

This array is big enough to hold at least max_codepoint bits. If this member is NULL, all glyphs are considered pre-rasterised.

Event fired when the font internal state has changed such that the rendered size of they glyphs is different. Handlers are passed a const FontEventArgs reference with FontEventArgs::font set to the Font whose rendered size has changed.

 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends