source: OGRE/trunk/ogre_dependencies/Dependencies/include/CEGUI/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
45namespace 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*/
51enum 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*/
62enum 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*/
82class CEGUIEXPORT Font
83{
84        friend class Font_xmlHandler;
85public:
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
680private:
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
816public:         // For luabind support
817        /*!
818        \brief
819                Destroys a Font object
820        */
821        ~Font(void);
822
823
824private:
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.