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:

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.