CL_Font::draw_to_gb

Inserts data into a CL_GlyphBuffer, treating the glyphs already there as part of a previous draw_to_gb().

	int draw_to_gb(
		const std::string& str, CL_GlyphBuffer& gb, CL_Size max_size = CL_Size(0, 0));

	int draw_to_gb(
		std::string::const_iterator start, std::string::const_iterator end, CL_GlyphBuffer& gb, CL_Size max_size = CL_Size(0, 0));

Parameters:

str

The input string to draw.

start

String position to begin drawing at, inclusive.

end

String position to end drawing at, exclusive.

max_size

Sets size for word wrapping and height truncating. Either can be zero to disable that feature.

gb

The glyph buffer to mess with.

Return value:

The number of glyphs that were inserted. This could be negative if it backtracks.

Detailed description:

The CL_GlyphBuffer's contents (the glyphs vector, the font markers map, and the effects maps), if any, must not have been created/altered by anything but CL_Font::draw_to_gb() and/or CL_TextStyler::draw_to_gb() for this method to work.

If you are doing draw_to_gb several sequential times to the same CL_GlyphBuffer, then you must pass the same maximum width to each call of draw_to_gb.

Each glyph inserted into the CL_GlyphBuffer corresponds with exactly one character of the input string, with the order in the vector and the order in the string being the same. That is, if you start out with an empty CL_GlyphBuffer, run this method on it, and afterwords the CL_GlyphBuffer contains 100 glyphs, then you know the first 100 characters of the source string range were processed. This includes whitespace and newline characters.

If you call this method on a CL_GlyphBuffer with a last line that is center-justified or left-justified, be aware that there's no way for this function to differentiate that line from a left-justified line with an indent, and it always assumes the latter.

You can tell when you've filled the buffer up to the height in max_size when a call to this method returns anything less than the size of the string. There's also the chance that it will backtrack and return a negative value if it runs out of vertical space in the process of wrapping a just-completed word; this is still a sign that you've ran out of vertical space.

See also:

CL_Font | CL_GlyphBuffer | CL_Size | CL_TextStyler