Context Navigation

source: OGRE/trunk/ogrenew/Dependencies/include/CEGUI/CEGUIFont.h @ 657

Revision 657, 38.4 KB checked in by mattausch, 19 years ago (diff)
added ogre dependencies and patched ogre sources

Rev	Line
[657]	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	Implementation structs
	1029	*************************************************************************/
	1030	/*!
	1031	\brief
	1032	struct to hold extra details about a glyph (required for proper rendering)
	1033	*/
	1034	struct glyphDat
	1035	{
	1036	const Image* d_image; //!< The image which will be rendered.
	1037	uint d_horz_advance; //!< Amount to advance the pen after rendering this glyph
	1038	uint d_horz_advance_unscaled; //!< original unscaled advance value (only used with static / bitmap fonts).
	1039	};
	1040
	1041	/*************************************************************************
	1042	Implementation Data
	1043	*************************************************************************/
	1044	typedef std::map<utf32, glyphDat> CodepointMap;
	1045	CodepointMap d_cp_map; //!< Contains mappings from code points to Image objects
	1046
	1047	String d_name; //!< Name of this font.
	1048	Imageset* d_glyph_images; //!< Imageset that holds the glyphs for this font.
	1049
	1050	bool d_freetype; //!< true when the font is a FreeType based font
	1051	float d_lineHeight; //!< Exact pixel height of font.
	1052	float d_lineSpacing; //!< Spacing between multiple lines.
	1053	float d_max_bearingY; //!< Maximum bearingY value (gives required spacing down to baseline).
	1054	uint d_maxGlyphHeight; //!< Height of the largest glyph (calculated in getRequiredTextureSize)
	1055
	1056	FontImplData* d_impldat; //!< Implementation data
	1057	uint d_ptSize; //!< Point size of font.
	1058	String d_glyphset; //!< set of glyphs for the dynamic font.
	1059
	1060	// auto-scaling fields
	1061	bool d_autoScale; //!< true when auto-scaling is enabled.
	1062	float d_horzScaling; //!< current horizontal scaling factor.
	1063	float d_vertScaling; //!< current vertical scaling factor.
	1064	float d_nativeHorzRes; //!< native horizontal resolution for this Imageset.
	1065	float d_nativeVertRes; //!< native vertical resolution for this Imageset.
	1066
	1067	bool d_antiAliased; //!< True if the font should be rendered as anti-alaised by freeType.
	1068	};
	1069
	1070	} // End of CEGUI namespace section
	1071
	1072	#if defined(_MSC_VER)
	1073	# pragma warning(pop)
	1074	#endif
	1075
	1076
	1077	#endif // end of guard _CEGUIFont_h_

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

Download in other formats: