Context Navigation

CEGUIFont.h @ 692

Revision 692, 38.8 KB checked in by mattausch, 19 years ago (diff)
adding ogre 1.2 and dependencies

Line
1	/************************************************************************
2	filename: CEGUIFont.h
3	created: 21/2/2004
4	author: Paul D Turner
5
6	purpose: Defines interface for the Font class
7	*************************************************************************/
8	/*************************************************************************
9	Crazy Eddie's GUI System (http://www.cegui.org.uk)
10	Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
11
12	This library is free software; you can redistribute it and/or
13	modify it under the terms of the GNU Lesser General Public
14	License as published by the Free Software Foundation; either
15	version 2.1 of the License, or (at your option) any later version.
16
17	This library is distributed in the hope that it will be useful,
18	but WITHOUT ANY WARRANTY; without even the implied warranty of
19	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20	Lesser General Public License for more details.
21
22	You should have received a copy of the GNU Lesser General Public
23	License along with this library; if not, write to the Free Software
24	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
25	*************************************************************************/
26	#ifndef _CEGUIFont_h_
27	#define _CEGUIFont_h_
28
29	#include "CEGUIBase.h"
30	#include "CEGUIString.h"
31	#include "CEGUIRect.h"
32	#include "CEGUIVector.h"
33	#include "CEGUIColourRect.h"
34
35	#include <map>
36
37
38	#if defined(_MSC_VER)
39	# pragma warning(push)
40	# pragma warning(disable : 4251)
41	#endif
42
43
44	// Start of CEGUI namespace section
45	namespace CEGUI
46	{
47	/*!
48	\brief
49	Enumerated type that contains the valid flags that can be passed to createFont when creating a new font.
50	*/
51	enum FontFlag
52	{
53	Default, //!< Default / None.
54	NoAntiAlias //!< Fonts generated from TrueType files should not be anti-aliased.
55	};
56
57
58	/*!
59	\brief
60	Enumerated type that contains valid formatting types that can be specified when rendering text into a Rect area (the formatting Rect).
61	*/
62	enum TextFormatting
63	{
64	LeftAligned, //!< All text is printed on a single line. The left-most character is aligned with the left edge of the formatting Rect.
65	RightAligned, //!< All text is printed on a single line. The right-most character is aligned with the right edge of the formatting Rect.
66	Centred, //!< All text is printed on a single line. The text is centred horizontally in the formatting Rect.
67	Justified, //!< All text is printed on a single line. The left-most and right-most characters are aligned with the edges of the formatting Rect.
68	WordWrapLeftAligned, //!< Text is broken into multiple lines no wider than the formatting Rect. The left-most character of each line is aligned with the left edge of the formatting Rect.
69	WordWrapRightAligned, //!< Text is broken into multiple lines no wider than the formatting Rect. The right-most character of each line is aligned with the right edge of the formatting Rect.
70	WordWrapCentred, //!< Text is broken into multiple lines no wider than the formatting Rect. Each line is centred horizontally in the formatting Rect.
71	WordWrapJustified //!< Text is broken into multiple lines no wider than the formatting Rect. The left-most and right-most characters of each line are aligned with the edges of the formatting Rect.
72	};
73
74	/*!
75	\brief
76	Class that encapsulates text rendering functionality for a typeface
77
78	A Font object is created for each unique typeface required. The Font class provides
79	methods for loading typefaces from various sources, and then for outputting text via
80	the Renderer object.
81	*/
82	class CEGUIEXPORT Font
83	{
84	friend class Font_xmlHandler;
85	public:
86	/*************************************************************************
87	Constants
88	*************************************************************************/
89	static const argb_t DefaultColour; //!< Colour value used whenever a colour is not specified.
90
91
92	/*************************************************************************
93	Text drawing methods
94	*************************************************************************/
95	/*!
96	\brief
97	Draw text into a specified area of the display.
98
99	\param text
100	String object containing the text to be drawn.
101
102	\param draw_area
103	Rect object describing the area of the display where the text is to be rendered. The text is not clipped to this Rect, but is formatted
104	using this Rect depending upon the option specified in \a fmt.
105
106	\param z
107	flat value specifying the z co-ordinate for the drawn text.
108
109	\param clip_rect
110	Rect object describing the clipping area for the drawing. No drawing will occur outside this Rect.
111
112	\param fmt
113	One of the TextFormatting values specifying the text formatting required.
114
115	\param colours
116	ColourRect object describing the colours to be applied when drawing the text. NB: The colours specified in here are applied to each glyph,
117	rather than the text as a whole.
118
119	\param x_scale
120	Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
121
122	\param y_scale
123	Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
124
125	\return
126	The number of lines output. NB: This does not consider clipping, so if all text was clipped, this would still return >=1.
127	*/
128	size_t drawText(const String& text, const Rect& draw_area, float z, const Rect& clip_rect, TextFormatting fmt, const ColourRect& colours, float x_scale = 1.0f, float y_scale = 1.0f) const;
129
130
131	/*!
132	\brief
133	Draw text into a specified area of the display using default colours.
134
135	\param text
136	String object containing the text to be drawn.
137
138	\param draw_area
139	Rect object describing the area of the display where the text is to be rendered. The text is not clipped to this Rect, but is formatted
140	using this Rect depending upon the option specified in \a fmt.
141
142	\param z
143	flat value specifying the z co-ordinate for the drawn text.
144
145	\param clip_rect
146	Rect object describing the clipping area for the drawing. No drawing will occur outside this Rect.
147
148	\param fmt
149	One of the TextFormatting values specifying the text formatting required.
150
151	\param x_scale
152	Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
153
154	\param y_scale
155	Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
156
157	\return
158	The number of lines output. NB: This does not consider clipping, so if all text was clipped, this would still return >=1.
159	*/
160	size_t drawText(const String& text, const Rect& draw_area, float z, const Rect& clip_rect, TextFormatting fmt, float x_scale = 1.0f, float y_scale = 1.0f) const
161	{ return drawText(text, draw_area, z, clip_rect, fmt, ColourRect(DefaultColour, DefaultColour, DefaultColour, DefaultColour), x_scale, y_scale); }
162
163
164	/*!
165	\brief
166	Draw text into a specified area of the display with default colours and default formatting (LeftAligned).
167
168	\param text
169	String object containing the text to be drawn.
170
171	\param draw_area
172	Rect object describing the area of the display where the text is to be rendered. The text is not clipped to this Rect, but is formatted
173	using this Rect depending upon the option specified in \a fmt.
174
175	\param z
176	flat value specifying the z co-ordinate for the drawn text.
177
178	\param clip_rect
179	Rect object describing the clipping area for the drawing. No drawing will occur outside this Rect.
180
181	\param x_scale
182	Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
183
184	\param y_scale
185	Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
186
187	\return
188	Nothing.
189	*/
190	void drawText(const String& text, const Rect& draw_area, float z, const Rect& clip_rect, float x_scale = 1.0f, float y_scale = 1.0f) const
191	{ drawText(text, draw_area, z, clip_rect, LeftAligned, ColourRect(DefaultColour, DefaultColour, DefaultColour, DefaultColour), x_scale, y_scale); }
192
193
194	/*!
195	\brief
196	Draw text into a specified area of the display.
197
198	\param text
199	String object containing the text to be drawn.
200
201	\param draw_area
202	Rect object describing the area of the display where the text is to be rendered. The text is formatted using this Rect depending
203	upon the option specified in \a fmt. Additionally, the drawn text is clipped to be within this Rect (applies to non-word wrapped formatting
204	where the text may otherwise have fallen outside this Rect).
205
206	\param z
207	flat value specifying the z co-ordinate for the drawn text.
208
209	\param fmt
210	One of the TextFormatting values specifying the text formatting required.
211
212	\param colours
213	ColourRect object describing the colours to be applied when drawing the text. NB: The colours specified in here are applied to each glyph,
214	rather than the text as a whole.
215
216	\param x_scale
217	Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
218
219	\param y_scale
220	Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
221
222	\return
223	The number of lines output. NB: This does not consider clipping, so if all text was clipped, this would still return >=1.
224	*/
225	size_t drawText(const String& text, const Rect& draw_area, float z, TextFormatting fmt, const ColourRect& colours, float x_scale = 1.0f, float y_scale = 1.0f) const
226	{ return drawText(text, draw_area, z, draw_area, fmt, colours, x_scale, y_scale); }
227
228
229	/*!
230	\brief
231	Draw text into a specified area of the display with default colours.
232
233	\param text
234	String object containing the text to be drawn.
235
236	\param draw_area
237	Rect object describing the area of the display where the text is to be rendered. The text is formatted using this Rect depending
238	upon the option specified in \a fmt. Additionally, the drawn text is clipped to be within this Rect (applies to non-word wrapped formatting
239	where the text may otherwise have fallen outside this Rect).
240
241	\param z
242	flat value specifying the z co-ordinate for the drawn text.
243
244	\param fmt
245	One of the TextFormatting values specifying the text formatting required.
246
247	\param x_scale
248	Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
249
250	\param y_scale
251	Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
252
253	\return
254	The number of lines output. NB: This does not consider clipping, so if all text was clipped, this would still return >=1.
255	*/
256	size_t drawText(const String& text, const Rect& draw_area, float z, TextFormatting fmt, float x_scale = 1.0f, float y_scale = 1.0f) const
257	{ return drawText(text, draw_area, z, draw_area, fmt, ColourRect(DefaultColour, DefaultColour, DefaultColour, DefaultColour), x_scale, y_scale); }
258
259
260	/*!
261	\brief
262	Draw text into a specified area of the display with default colours and default formatting (LeftAligned).
263
264	\param text
265	String object containing the text to be drawn.
266
267	\param draw_area
268	Rect object describing the area of the display where the text is to be rendered. The text is formatted using this Rect depending
269	upon the option specified in \a fmt. Additionally, the drawn text is clipped to be within this Rect (applies to non-word wrapped formatting
270	where the text may otherwise have fallen outside this Rect).
271
272	\param z
273	flat value specifying the z co-ordinate for the drawn text.
274
275	\param x_scale
276	Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
277
278	\param y_scale
279	Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
280
281	\return
282	Nothing.
283	*/
284	void drawText(const String& text, const Rect& draw_area, float z, float x_scale = 1.0f, float y_scale = 1.0f) const
285	{ drawText(text, draw_area, z, draw_area, LeftAligned, ColourRect(DefaultColour, DefaultColour, DefaultColour, DefaultColour), x_scale, y_scale); }
286
287
288	/*!
289	\brief
290	Draw text at the specified location.
291
292	\param text
293	String object containing the text to be drawn.
294
295	\param position
296	Vector3 object describing the location for the text. NB: The position specified here corresponds to the text baseline and not the
297	top of any glyph. The baseline spacing required can be retrieved by calling getBaseline().
298
299	\param clip_rect
300	Rect object describing the clipping area for the drawing. No drawing will occur outside this Rect.
301
302	\param colours
303	ColourRect object describing the colours to be applied when drawing the text. NB: The colours specified in here are applied to each glyph,
304	rather than the text as a whole.
305
306	\param x_scale
307	Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
308
309	\param y_scale
310	Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
311
312	\return
313	Nothing.
314	*/
315	void drawText(const String& text, const Vector3& position, const Rect& clip_rect, const ColourRect& colours, float x_scale = 1.0f, float y_scale = 1.0f) const
316	{ drawText(text, Rect(position.d_x, position.d_y, position.d_x, position.d_y), position.d_z, clip_rect, LeftAligned, colours, x_scale, y_scale); }
317
318
319	/*!
320	\brief
321	Draw text at the specified location with default colours.
322
323	\param text
324	String object containing the text to be drawn.
325
326	\param position
327	Vector3 object describing the location for the text. NB: The position specified here corresponds to the text baseline and not the
328	top of any glyph. The baseline spacing required can be retrieved by calling getBaseline().
329
330	\param clip_rect
331	Rect object describing the clipping area for the drawing. No drawing will occur outside this Rect.
332
333	\param x_scale
334	Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
335
336	\param y_scale
337	Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.
338
339	\return
340	Nothing.
341	*/
342	void drawText(const String& text, const Vector3& position, const Rect& clip_rect, float x_scale = 1.0f, float y_scale = 1.0f) const
343	{ drawText(text, Rect(position.d_x, position.d_y, position.d_x, position.d_y), position.d_z, clip_rect, LeftAligned, ColourRect(DefaultColour, DefaultColour, DefaultColour, DefaultColour), x_scale, y_scale); }
344
345
346	/*************************************************************************
347	Methods to define available glyphs (truetype fonts only)
348	*************************************************************************/
349	/*!
350	\brief
351	Define the set of code points to be renderable by the font.
352
353	\note
354	This function can take some time to execute depending upon the size of the code point set, and the size of the
355	font being operated upon.
356
357	\param glyph_set
358	String object describing all the code points that will be renderable by this font
359
360	\return
361	Nothing
362
363	\exception InvalidRequestException thrown if the font is based on a bitmap rather than a true-type font.
364	\exception RendererException thrown if the Renderer can't support a texture large enough to hold the glyph imagery.
365	\exception MemoryException thrown if allocation of imagery construction buffer fails.
366	*/
367	void defineFontGlyphs(const String& glyph_set);
368
369
370	/*!
371	\brief
372	Define the range of code points to be renderable by the font.
373
374	\note
375	This function can take some time to execute depending upon the size of the code point set, and the size of the
376	font being operated upon.
377
378	\note
379	The code point arguments must satisfy the following: \a first_code_point <= \a last_code_point, otherwise results are undefined
380
381	\param first_code_point
382	utf32 value describing the first code point that will be renderable by this font.
383
384	\param last_code_point
385	utf32 value describing the last code point that will be renderable by this font.
386
387	\return
388	Nothing
389
390	\exception InvalidRequestException thrown if the font is based on a bitmap rather than a true-type font.
391	\exception RendererException thrown if the Renderer can't support a texture large enough to hold the glyph imagery.
392	\exception MemoryException thrown if allocation of imagery construction buffer fails.
393	*/
394	void defineFontGlyphs(utf32 first_code_point, utf32 last_code_point);
395
396
397	/*!
398	\brief
399	Set the native resolution for this Font
400
401	\param size
402	Size object describing the new native screen resolution for this Font.
403
404	\return
405	Nothing
406	*/
407	void setNativeResolution(const Size& size);
408
409
410	/*!
411	\brief
412	Notify the Font of the current (usually new) display resolution.
413
414	\param size
415	Size object describing the display resolution
416
417	\return
418	Nothing
419	*/
420	void notifyScreenResolution(const Size& size);
421
422
423	/*!
424	\brief
425	Enable or disable auto-scaling for this Font.
426
427	\param setting
428	true to enable auto-scaling, false to disable auto-scaling.
429
430	\return
431	Nothing.
432	*/
433	void setAutoScalingEnabled(bool setting);
434
435
436	/*!
437	\brief
438	Set whether the font is anti-aliased or not. Only relevant for dynamic fonts, this setting is
439	ignored for bitmapped fonts.
440
441	\param setting
442	- true if the font should be anti-aliased.
443	- false if the font should not be anti-aliased.
444
445	\return
446	Nothing.
447	*/
448	void setAntiAliased(bool setting);
449
450
451	/*************************************************************************
452	Informational methods
453	*************************************************************************/
454	/*!
455	\brief
456	Return the pixel width of the specified text if rendered with this Font.
457
458	\param text
459	String object containing the text to return the rendered pixel width for.
460
461	\param x_scale
462	Scaling factor to be applied to each glyph's x axis when measuring the extent, where 1.0f is considered to be 'normal'.
463
464	\return
465	Number of pixels that \a text will occupy when rendered with this Font.
466	*/
467	float getTextExtent(const String& text, float x_scale = 1.0f) const;
468
469
470	/*!
471	\brief
472	Return the pixel line spacing value for.
473
474	\param y_scale
475	Scaling factor to be applied to the line spacing, where 1.0f is considered to be 'normal'.
476
477	\return
478	Number of pixels between vertical base lines, i.e. The minimum pixel space between two lines of text.
479	*/
480	float getLineSpacing(float y_scale = 1.0f) const {return d_lineSpacing * y_scale;}
481
482
483	/*!
484	\brief
485	return the exact pixel height of the font.
486
487	\param y_scale
488	Scaling factor to be applied to the height, where 1.0f is considered to be 'normal'.
489
490	\return
491	float value describing the pixel height of the font without any additional padding.
492	*/
493	float getFontHeight(float y_scale = 1.0f) const {return d_lineHeight * y_scale;}
494
495
496	/*!
497	\brief
498	Return the number of pixels from the top of the highest glyph to the baseline
499
500	\param y_scale
501	Scaling factor to be applied to the baseline distance, where 1.0f is considered to be 'normal'.
502
503	\return
504	pixel spacing from top of front glyphs to baseline
505	*/
506	float getBaseline(float y_scale = 1.0f) const {return d_max_bearingY * y_scale;}
507
508
509	/*!
510	\brief
511	Return the index of the closest text character in String \a text that corresponds to pixel location \a pixel if the text were rendered.
512
513	\param text
514	String object containing the text.
515
516	\param pixel
517	Specifies the (horizontal) pixel offset to return the character index for.
518
519	\param x_scale
520	Scaling factor to be applied to each glyph's x axis when measuring the text extent, where 1.0f is considered to be 'normal'.
521
522	\return
523	Returns a character index into String \a text for the character that would be rendered closest to horizontal pixel offset \a pixel if the
524	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
525	the string, which indicates \a pixel was beyond the last character.
526	*/
527	size_t getCharAtPixel(const String& text, float pixel, float x_scale = 1.0f) const {return getCharAtPixel(text, 0, pixel, x_scale);}
528
529
530	/*!
531	\brief
532	Return the index of the closest text character in String \a text, starting at character index \a start_char, that corresponds
533	to pixel location \a pixel if the text were to be rendered.
534
535	\param text
536	String object containing the text.
537
538	\param start_char
539	index of the first character to consider. This is the lowest value that will be returned from the call.
540
541	\param pixel
542	Specifies the (horizontal) pixel offset to return the character index for.
543
544	\param x_scale
545	Scaling factor to be applied to each glyph's x axis when measuring the text extent, where 1.0f is considered to be 'normal'.
546
547	\return
548	Returns a character index into String \a text for the character that would be rendered closest to horizontal pixel offset \a pixel if the
549	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
550	the string, which indicates \a pixel was beyond the last character.
551	*/
552	size_t getCharAtPixel(const String& text, size_t start_char, float pixel, float x_scale = 1.0f) const;
553
554
555	/*!
556	\brief
557	Return the name of this font.
558
559	\return
560	String object holding the name of this font.
561	*/
562	const String& getName(void) const {return d_name;}
563
564
565	/*!
566	\brief
567	Return the native display size for this Font. This is only relevant if the Font is being auto-scaled.
568
569	\return
570	Size object describing the native display size for this Font.
571	*/
572	Size getNativeResolution(void) const {return Size(d_nativeHorzRes, d_nativeVertRes);}
573
574
575	/*!
576	\brief
577	Return whether this Font is auto-scaled.
578
579	\return
580	true if the Font is auto-scaled, false if not.
581	*/
582	bool isAutoScaled(void) const {return d_autoScale;}
583
584
585	/*!
586	\brief
587	Return whether this Font can currently draw the specified code-point
588
589	\param cp
590	utf32 code point that is the subject of the query.
591
592	\return
593	true if the font contains a mapping for code point \a cp, false if it does not contain a mapping for \a cp.
594	*/
595	bool isCodepointAvailable(utf32 cp) const {return (d_cp_map.find(cp) != d_cp_map.end());}
596
597
598	/*!
599	\brief
600	Return the number of lines the given text would be formatted to.
601
602	Since text formatting can result in multiple lines of text being output, it can be useful to know
603	how many lines would be output without actually rendering the text.
604
605	\param text
606	String object containing the text to be measured.
607
608	\param format_area
609	Rect object describing the area to be used when formatting the text depending upon the option specified in \a fmt.
610
611	\param fmt
612	One of the TextFormatting values specifying the text formatting required.
613
614	\param x_scale
615	Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
616
617	\return
618	The number of lines produced from the specified formatting
619	*/
620	size_t getFormattedLineCount(const String& text, const Rect& format_area, TextFormatting fmt, float x_scale = 1.0f) const;
621
622
623	/*!
624	\brief
625	Return the horizontal pixel extent given text would be formatted to.
626
627	The value return by this method is basically the extent of the widest line within the formatted text.
628
629	\param text
630	String object containing the text to be measured.
631
632	\param format_area
633	Rect object describing the area to be used when formatting the text depending upon the option specified in \a fmt.
634
635	\param fmt
636	One of the TextFormatting values specifying the text formatting required.
637
638	\param x_scale
639	Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
640
641	\return
642	The widest pixel extent of the lines produced from the specified formatting.
643	*/
644	float getFormattedTextExtent(const String& text, const Rect& format_area, TextFormatting fmt, float x_scale = 1.0f) const;
645
646
647	/*!
648	\brief
649	Return whether this font is anti-aliased or not. This is only relevant for dynamic fonts created from a TrueType font file.
650
651	\return
652	- true if the font is anti-aliased.
653	- false if the font is not anti-aliased.
654	*/
655	bool isAntiAliased(void) const;
656
657
658	/*!
659	\brief
660	Return a String object that contains the code-points that the font is currently configured to render.
661
662	\return
663	Reference to a String object.
664	*/
665	const String& getAvailableGlyphs(void) const;
666
667
668	/*!
669	\brief
670	Return the point size of a dynamic (ttf based) font.
671
672	\return
673	uint value indicating the point size specified when the dynamic font was created.
674
675	\exception InvalidRequestException thrown if the font is a static (bitmap based) font which do not support point sizes.
676	*/
677	uint getPointSize(void) const;
678
679
680	private:
681	/*************************************************************************
682	Implementation Constants
683	*************************************************************************/
684	static const char FontSchemaName[]; //!< Filename of the XML schema used for validating Font files.
685	static const uint InterGlyphPadSpace; //!< Pad space between glyphs.
686
687
688	/*************************************************************************
689	Friends so that only FontManager can create and destroy font objects
690	*************************************************************************/
691	friend class FontManager;
692
693	/*************************************************************************
694	Private forward refs
695	*************************************************************************/
696	struct FontImplData;
697
698
699	/*************************************************************************
700	Construction & Destruction
701	*************************************************************************/
702	/*!
703	\brief
704	Constructs a new Font object
705
706	\param filename
707	The filename of the "font definition file" to be used in creating this font.
708
709	\param resourceGroup
710	Resource group identifier to be passed to the resource provider to load the font
711	definition file.
712
713	\exception FileIOException thrown if there was some problem accessing or parsing the file \a filename
714	\exception InvalidRequestException thrown if an invalid filename was provided.
715	\exception AlreadyExistsException thrown if a Font Imageset clashes with one already defined in the system.
716	\exception GenericException thrown if something goes wrong while accessing a true-type font referenced in file \a filename.
717	\exception RendererException thrown if the Renderer can't support a texture large enough to hold the requested glyph imagery.
718	\exception MemoryException thrown if allocation of imagery construction buffer fails.
719	*/
720	Font(const String& filename, const String& resourceGroup, FontImplData* dat);
721
722
723	/*!
724	\brief
725	Constructs a new Font object, with 7-bit ASCII glyphs
726
727	\param name
728	The unique name that will be used to identify this Font.
729
730	\param fontname
731	filename of the true-type font to be loaded.
732
733	\param resourceGroup
734	Resource group identifier to pass to the resource provider when loading the true-type
735	font file.
736
737	\param size
738	Point size of the new font.
739
740	\param flags
741	Combination of the FontFlag enumerated values specifying required options for creating this Font.
742
743	\exception AlreadyExistsException thrown if an auto-generated Imageset clashes with one already defined in the system.
744	\exception GenericException thrown if something goes wrong while accessing the true-type font \a fontname.
745	\exception RendererException thrown if the Renderer can't support a texture large enough to hold the requested glyph imagery.
746	\exception MemoryException thrown if allocation of imagery construction buffer fails.
747	*/
748	Font(const String& name, const String& fontname, const String& resourceGroup, uint size, uint flags, FontImplData* dat);
749
750
751	/*!
752	\brief
753	Constructs a new Font object, with the specified set of glyphs
754
755	\param name
756	The unique name that will be used to identify this Font.
757
758	\param fontname
759	filename of the true-type font to be loaded.
760
761	\param resourceGroup
762	Resource group identifier to pass to the resource provider when loading the true-type
763	font file.
764
765	\param size
766	Point size of the new font.
767
768	\param flags
769	Combination of the FontFlag enumerated values specifying required options for creating this Font.
770
771	\param glyph_set
772	String containing the set of glyphs to have available in this font.
773
774	\exception AlreadyExistsException thrown if an auto-generated Imageset clashes with one already defined in the system.
775	\exception GenericException thrown if something goes wrong while accessing the true-type font \a fontname.
776	\exception RendererException thrown if the Renderer can't support a texture large enough to hold the requested glyph imagery.
777	\exception MemoryException thrown if allocation of imagery construction buffer fails.
778	*/
779	Font(const String& name, const String& fontname, const String& resourceGroup, uint size, uint flags, const String& glyph_set, FontImplData* dat);
780
781
782	/*!
783	\brief
784	Constructs a new Font object, with a specified range of glyphs
785
786	\param name
787	The unique name that will be used to identify this Font.
788
789	\param fontname
790	filename of the true-type font to be loaded.
791
792	\param resourceGroup
793	Resource group identifier to pass to the resource provider when loading the true-type
794	font file.
795
796	\param size
797	Point size of the new font.
798
799	\param flags
800	Combination of the FontFlag enumerated values specifying required options for creating this Font.
801
802	\param first_code_point
803	Specifies the utf32 code point of the first glyph to be available on this font
804
805	\param last_code_point
806	Specifies the utf32 code point of the last glyph to be available on this font
807
808	\exception AlreadyExistsException thrown if an auto-generated Imageset clashes with one already defined in the system.
809	\exception GenericException thrown if something goes wrong while accessing the true-type font \a fontname.
810	\exception RendererException thrown if the Renderer can't support a texture large enough to hold the requested glyph imagery.
811	\exception MemoryException thrown if allocation of imagery construction buffer fails.
812	*/
813	Font(const String& name, const String& fontname, const String& resourceGroup, uint size, uint flags, utf32 first_code_point, utf32 last_code_point, FontImplData* dat);
814
815
816	public: // For luabind support
817	/*!
818	\brief
819	Destroys a Font object
820	*/
821	~Font(void);
822
823
824	private:
825	/*************************************************************************
826	Implementation Methods
827	*************************************************************************/
828	/*!
829	\brief
830	Load and complete construction of 'this' via an XML file
831
832	\param filename
833	String object holding the name of the XML file that holds details about the font to create.
834
835	\param resourceGroup
836	Resource group identifier to be passed to the resource provider when loading the font
837	definition file.
838
839	\return
840	Nothing.
841	*/
842	void load(const String& filename, const String& resourceGroup);
843
844
845	/*!
846	\brief
847	Unloads data associated with the font (font is then useless. this is intended for cleanup).
848
849	\return
850	Nothing.
851	*/
852	void unload(void);
853
854
855	/*!
856	\brief
857	Return the required texture size required to store imagery for the
858	glyphs specified in \a glyph_set
859
860	\param glyph_set
861	String object describing the set of code points who's glyph imagery is to be measured.
862
863	\return
864	Required pixel size for a square texture large enough to hold glyph imagery for the set of code points in \a glyph_set
865	*/
866	uint getRequiredTextureSize(const String& glyph_set);
867
868
869	/*!
870	\brief
871	Return the required texture size required to store imagery for the
872	glyphs specified in by the inclusive range [first_code_point, last_code_point]
873
874	\param first_code_point
875	utf32 code point of the first character in the range to be measured
876
877	\param last_code_point
878	utf32 code point of the last character in the range to be measured
879
880	\return
881	Required pixel size for a square texture large enough to hold glyph imagery for the specified range of code points.
882	*/
883	uint getRequiredTextureSize(utf32 first_code_point, utf32 last_code_point);
884
885
886	/*!
887	\brief
888	Paint the set of glyphs required for all code points in \a glyph_set into the buffer \a buffer,
889	which has a size of \a size pixels (not bytes) square. This also defines an Image for each
890	glyph in the Imageset for this font, and creates an entry in the code point to Image map.
891
892	\param glyph_set
893	String object containing the set of code points whos glyphs are to be loaded into the buffer.
894
895	\param size
896	Width of \a buffer in pixels (not bytes).
897
898	\param buffer
899	Pointer to a memory buffer large enough to receive the glyph image data.
900
901	\return
902	Nothing.
903	*/
904	void createFontGlyphSet(const String& glyph_set, uint size, argb_t* buffer);
905
906
907	/*!
908	\brief
909	Paint the set of glyphs required for all code points in the range [\a first_code_point, \a last_code_point]
910	into the buffer \a buffer, which has a size of \a size pixels (not bytes) square. This also defines an
911	Image for each glyph in the Imageset for this font, and creates an entry in the code point to Image map.
912
913	\param first_code_point
914	utf32 code point that is the first code point in a range whos glyph are to be loaded into the buffer.
915
916	\param last_code_point
917	utf32 code point that is the last code point in a range whos glyph are to be loaded into the buffer.
918
919	\param size
920	Width of \a buffer in pixels (not bytes).
921
922	\param buffer
923	Pointer to a memory buffer large enough to receive the glyph image data.
924
925	\return
926	Nothing.
927	*/
928	void createFontGlyphSet(utf32 first_code_point, utf32 last_code_point, uint size, argb_t* buffer);
929
930
931	/*!
932	\brief
933	Copy the current glyph data into \a buffer, which has a width of \a buf_width pixels (not bytes).
934
935	\param buffer
936	Memory buffer large enough to receive the imagery for the currently loaded glyph.
937
938	\param buf_width
939	Width of \a buffer in pixels (where each pixel is a argb_t).
940
941	\return
942	Nothing.
943	*/
944	void drawGlyphToBuffer(argb_t* buffer, uint buf_width);
945
946
947	/*!
948	\brief
949	draws wrapped text. returns number of lines output.
950	*/
951	size_t drawWrappedText(const String& text, const Rect& draw_area, float z, const Rect& clip_rect, TextFormatting fmt, const ColourRect& colours, float x_scale = 1.0f, float y_scale = 1.0f) const;
952
953
954	/*!
955	\brief
956	helper function for renderWrappedText to get next word of a string
957	*/
958	size_t getNextWord(const String& in_string, size_t start_idx, String& out_string) const;
959
960
961	/*!
962	\brief
963	Draw a line of text. No formatting is applied.
964	*/
965	void drawTextLine(const String& text, const Vector3& position, const Rect& clip_rect, const ColourRect& colours, float x_scale = 1.0f, float y_scale = 1.0f) const;
966
967
968	/*!
969	\brief
970	Draw a justified line of text.
971	*/
972	void drawTextLineJustified(const String& text, const Rect& draw_area, const Vector3& position, const Rect& clip_rect, const ColourRect& colours, float x_scale = 1.0f, float y_scale = 1.0f) const;
973
974
975	/*!
976	\brief
977	Set the size of the free-type font (via d_face which should already be setup) and render the glyphs in d_glyphset.
978	*/
979	void createFontFromFT_Face(uint size, uint horzDpi, uint vertDpi);
980
981
982	/*!
983	\brief
984	Update the font as required according to the current scaling
985	*/
986	void updateFontScaling(void);
987
988
989	/*!
990	\brief
991	Calculate the vertical spacing fields for a static / bitmap font
992	*/
993	void calculateStaticVertSpacing(void);
994
995	/*!
996	\brief
997	Function to do real work of constructor. Used to save duplication in the various constructor overloads.
998	*/
999	void constructor_impl(const String& name, const String& fontname, const String& resourceGroup, uint size, uint flags, const String& glyph_set);
1000
1001
1002	/*!
1003	\brief
1004	Defines the set of code points on the font. (implementation).
1005
1006	\note
1007	This function can take some time to execute depending upon the size of the code point set, and the size of the
1008	font being operated upon.
1009
1010	\return
1011	Nothing
1012
1013	\exception InvalidRequestException thrown if the font is based on a bitmap rather than a true-type font.
1014	\exception RendererException thrown if the Renderer can't support a texture large enough to hold the glyph imagery.
1015	\exception MemoryException thrown if allocation of imagery construction buffer fails.
1016	*/
1017	void defineFontGlyphs_impl(void);
1018
1019
1020	/*!
1021	\brief
1022	returns extent of widest line of wrapped text.
1023	*/
1024	float getWrappedTextExtent(const String& text, float wrapWidth, float x_scale = 1.0f) const;
1025
1026
1027	/*!
1028	\brief
1029	Writes an xml representation of this Font to \a out_stream.
1030
1031	\param out_stream
1032	Stream where xml data should be output.
1033
1034	\return
1035	Nothing.
1036	*/
1037	void writeXMLToStream(OutStream& out_stream) const;
1038
1039
1040	/*************************************************************************
1041	Implementation structs
1042	*************************************************************************/
1043	/*!
1044	\brief
1045	struct to hold extra details about a glyph (required for proper rendering)
1046	*/
1047	struct glyphDat
1048	{
1049	const Image* d_image; //!< The image which will be rendered.
1050	int d_horz_advance; //!< Amount to advance the pen after rendering this glyph
1051	int d_horz_advance_unscaled; //!< original unscaled advance value (only used with static / bitmap fonts).
1052	};
1053
1054	/*************************************************************************
1055	Implementation Data
1056	*************************************************************************/
1057	typedef std::map<utf32, glyphDat> CodepointMap;
1058	CodepointMap d_cp_map; //!< Contains mappings from code points to Image objects
1059
1060	String d_name; //!< Name of this font.
1061	Imageset* d_glyph_images; //!< Imageset that holds the glyphs for this font.
1062	String d_sourceFilename; //!< Holds the name of the file used to create this font (either font file or imagset)
1063
1064	bool d_freetype; //!< true when the font is a FreeType based font
1065	float d_lineHeight; //!< Exact pixel height of font.
1066	float d_lineSpacing; //!< Spacing between multiple lines.
1067	float d_max_bearingY; //!< Maximum bearingY value (gives required spacing down to baseline).
1068	uint d_maxGlyphHeight; //!< Height of the largest glyph (calculated in getRequiredTextureSize)
1069
1070	FontImplData* d_impldat; //!< Implementation data
1071	uint d_ptSize; //!< Point size of font.
1072	String d_glyphset; //!< set of glyphs for the dynamic font.
1073
1074	// auto-scaling fields
1075	bool d_autoScale; //!< true when auto-scaling is enabled.
1076	float d_horzScaling; //!< current horizontal scaling factor.
1077	float d_vertScaling; //!< current vertical scaling factor.
1078	float d_nativeHorzRes; //!< native horizontal resolution for this Imageset.
1079	float d_nativeVertRes; //!< native vertical resolution for this Imageset.
1080
1081	bool d_antiAliased; //!< True if the font should be rendered as anti-alaised by freeType.
1082	};
1083
1084	} // End of CEGUI namespace section
1085
1086	#if defined(_MSC_VER)
1087	# pragma warning(pop)
1088	#endif
1089
1090
1091	#endif // end of guard _CEGUIFont_h_

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: OGRE/trunk/ogre_dependencies/Dependencies/include/CEGUI/CEGUIFont.h @ 692

Download in other formats: