CL_GlyphBuffer - ClanLib Game SDK

Home | All Classes | Grouped Classes | Index | Search

# Class CL_GlyphBuffer

Stores and draws glyphs in one or more fonts. More...

Derived from: none
Derived by: none
Group: Display (Fonts)

#include <ClanLib/display.h>

Construction:

CL_GlyphBuffer | Constructs a glyph buffer.

Subclasses:

Glyph | A character and position describing a glyph in the buffer, stored in the glyphs vector.
Range | Represents a subsection of the buffer

Attributes:

get_glyphs | Returns a reference to the glyphs in the buffer and their drawing positions.
get_font_markers | Returns a reference to the font map.
get_color_effects | Returns a reference to the color effect map.
get_scale_x_effects | Returns a reference to the x scale effect map.
get_scale_y_effects | Returns a reference to the y scale effect map.
get_angle_effects | Returns a reference to the character angle effect map.
get_font_for | Returns an iterator to the font_marker associated with a particular glyph.
get_width | Returns the width of the entire buffer, or a sub-Range.
get_height | Returns the height of the entire buffer, or a sub-Range.
get_size | Returns the size of the entire buffer, or a sub-Range.
get_angle | Returns current angle.
get_scale | Returns scale for x and y.
get_alignment | Returns translation hotspot for the entire glyph field.
get_rotation_hotspot | Returns rotation hotspot for the entire glyph field.
bounding_rect | Returns the area that would be drawn to if a draw were performed.
internal_rect | Returns the area occupied by glyphs inside the glyph buffer's coordinate space.
get_lines | Returns a vector of CL_GlyphBuffer::Range, each of which contains one line.
get_line | Returns a single CL_GlyphBuffer::Range containing the line that contains a given glyph.

Operations

add | Add elements onto the end of the glyphs vector.
remove | Removes an element or elements from the glyphs vector, reorganizes the font and effect maps to compensate.
change_font | Adds a font change marker, set to occur before the next glyph/location you add is drawn.
clear | Remove all the character position and font marker data in the buffer.
draw | Draw the glyphs in the buffer.
fixed_draw | Draws the glyphs in the buffer without bounding rect alignment.
justify_left | Rejustifies lines in the GlyphBuffer to the left.
justify_center | Rejustifies lines in the GlyphBuffer to the center.
justify_right | Rejustifies lines in the GlyphBuffer to the right.
set_angle | Set absolute rotation angle.
rotate | Add angle to current angle.
set_scale | Set scale for x and y directions individually.
set_alignment | Sets translation hotspot.
set_rotation_hotspot | Sets rotation hotspot.

Detailed description:

!group=Display/Fonts! !header=display.h!

CL_GlyphBuffer is mostly useful for text effects, for concatenating multiple CL_Font or CL_TextStyler draw_to_gb()s, or for when you need access to the low-level glyph positioning data. You can also use it to save time by only rendering a bit of text once when you need to, for example, both draw that text and know its bounding rectangle. But for optimiziation purposes alone when dealing with unchanging text, you should instead have CL_Font or CL_TextStyler render onto a CL_Canvas or CL_Surface.

A glyph buffer consists of a series of characters and positions, and markers for font changes and various other text-altering infomration. The internal data structures used are made accessible and mutable externally. CL_Font and CL_TextStyler both have draw_to_gb() methods, which allows them to put data into a CL_GlyphBuffer rather than drawing to a CL_GraphicContext.

The effect maps for color, angle, and scale allow you to affect those properties for individual glyphs during drawing and bounding rect calculation. The angle and scale maps are different from the GlyphBuffer angle and scale properties; the properties apply to the entire CL_GlyphBuffer as a whole, while entries in the effect maps affect individual glyphs seperately. It's not legal to insert an effect map entry for a glyph that doesn't exist.

Unlike scale effects map entries, which are multiplied by the CL_Font's existing scale, color effect map entries entirely override the CL_Font's color. No blending between the two colors is performed. Also, it's your responsibility to make sure that CL_Fonts have the right blending functions.

In functions that calculate the size or bounding rectangle of the GlyphBuffer (such as bouding_rect(), get_size(), and the alignment calculations within draw), effect properties do take effect on the final rectangle, but GlyphBuffer rotation and scaling (set with CL_GlyphBuffer::set_angle(), and CL_GlyphBuffer::set_scale(), respectively) do not. This is consistent with the behavior of CL_Sprite and CL_Surface; the content affects bounding rect calculation, but the other properties of the object do not.

Questions or comments, write to the ClanLib mailing list.