Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/OgreMain/include/OgreFont.h @ 1

Last change on this file since 1 was 1, checked in by landauf, 17 years ago
File size: 15.0 KB
Line 
1/*-------------------------------------------------------------------------
2This source file is a part of OGRE
3(Object-oriented Graphics Rendering Engine)
4
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2006 Torus Knot Software Ltd
8Also see acknowledgements in Readme.html
9
10This library is free software; you can redistribute it and/or modify it
11under the terms of the GNU Lesser General Public License (LGPL) as
12published by the Free Software Foundation; either version 2.1 of the
13License, or (at your option) any later version.
14
15This library is distributed in the hope that it will be useful, but
16WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
17or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
18License for more details.
19
20You should have received a copy of the GNU Lesser General Public License
21along with this library; if not, write to the Free Software Foundation,
22Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA or go to
23http://www.gnu.org/copyleft/lesser.txt
24-------------------------------------------------------------------------*/
25
26#ifndef _Font_H__
27#define _Font_H__
28
29#include "OgrePrerequisites.h"
30#include "OgreResource.h"
31#include "OgreTexture.h"
32#include "OgreMaterial.h"
33#include "OgreCommon.h"
34
35namespace Ogre
36{
37    /** Enumerates the types of Font usable in the engine. */
38    enum FontType
39    {
40        /// Generated from a truetype (.ttf) font
41        FT_TRUETYPE = 1,
42        /// Loaded from an image created by an artist
43        FT_IMAGE = 2
44    };
45
46
47    /** Class representing a font in the system.
48    @remarks
49    This class is simply a way of getting a font texture into the OGRE system and
50    to easily retrieve the texture coordinates required to accurately render them.
51    Fonts can either be loaded from precreated textures, or the texture can be generated
52    using a truetype font. You can either create the texture manually in code, or you
53    can use a .fontdef script to define it (probably more practical since you can reuse
54    the definition more easily)
55        @note
56        This class extends both Resource and ManualResourceLoader since it is
57        both a resource in it's own right, but it also provides the manual load
58        implementation for the Texture it creates.
59    */
60        class _OgreExport Font : public Resource, public ManualResourceLoader
61    {
62    protected:
63                /// Command object for Font - see ParamCommand
64                class _OgreExport CmdType : public ParamCommand
65                {
66                public:
67                        String doGet(const void* target) const;
68                        void doSet(void* target, const String& val);
69                };
70                /// Command object for Font - see ParamCommand
71                class _OgreExport CmdSource : public ParamCommand
72                {
73                public:
74                        String doGet(const void* target) const;
75                        void doSet(void* target, const String& val);
76                };
77                /// Command object for Font - see ParamCommand
78                class _OgreExport CmdSize : public ParamCommand
79                {
80                public:
81                        String doGet(const void* target) const;
82                        void doSet(void* target, const String& val);
83                };
84                /// Command object for Font - see ParamCommand
85                class _OgreExport CmdResolution : public ParamCommand
86                {
87                public:
88                        String doGet(const void* target) const;
89                        void doSet(void* target, const String& val);
90                };
91                /// Command object for Font - see ParamCommand
92                class _OgreExport CmdCodePoints : public ParamCommand
93                {
94                public:
95                        String doGet(const void* target) const;
96                        void doSet(void* target, const String& val);
97                };
98
99                // Command object for setting / getting parameters
100                static CmdType msTypeCmd;
101                static CmdSource msSourceCmd;
102                static CmdSize msSizeCmd;
103                static CmdResolution msResolutionCmd;
104                static CmdCodePoints msCodePointsCmd;
105
106                /// The type of font
107        FontType mType;
108
109        /// Source of the font (either an image name or a truetype font)
110        String mSource;
111
112        /// Size of the truetype font, in points
113        Real mTtfSize;
114        /// Resolution (dpi) of truetype font
115        uint mTtfResolution;
116
117
118        public:
119                typedef Ogre::uint32 CodePoint;
120                typedef Ogre::FloatRect UVRect;
121                /// Information about the position and size of a glyph in a texture
122                struct GlyphInfo
123                {
124                        CodePoint codePoint;
125                        UVRect uvRect;
126                        Real aspectRatio;
127
128                        GlyphInfo(CodePoint id, const UVRect& rect, Real aspect)
129                                : codePoint(id), uvRect(rect), aspectRatio(aspect)
130                        {
131
132                        }
133                };
134                /// A range of code points, inclusive on both ends
135                typedef std::pair<CodePoint, CodePoint> CodePointRange;
136                typedef std::vector<CodePointRange> CodePointRangeList;
137        protected:
138                /// Map from unicode code point to texture coordinates
139                typedef std::map<CodePoint, GlyphInfo> CodePointMap;
140                CodePointMap mCodePointMap;
141
142        /// The material which is generated for this font
143        MaterialPtr mpMaterial;
144
145                /// Texture pointer
146                TexturePtr mTexture;
147
148        /// for TRUE_TYPE font only
149        bool mAntialiasColour;
150
151                /// Range of code points to generate glyphs for (truetype only)
152                CodePointRangeList mCodePointRangeList;
153
154        /// Internal method for loading from ttf
155        void createTextureFromFont(void);
156
157                /// @copydoc Resource::loadImpl
158                virtual void loadImpl();
159                /// @copydoc Resource::unloadImpl
160                virtual void unloadImpl();
161                /// @copydoc Resource::calculateSize
162                size_t calculateSize(void) const { return 0; } // permanent resource is in the texture
163    public:
164
165        /** Constructor.
166                @see Resource
167        */
168                Font(ResourceManager* creator, const String& name, ResourceHandle handle,
169                        const String& group, bool isManual = false, ManualResourceLoader* loader = 0);
170        virtual ~Font();
171
172        /** Sets the type of font. Must be set before loading. */
173        void setType(FontType ftype);
174
175        /** Gets the type of font. */
176        FontType getType(void) const;
177
178        /** Sets the source of the font.
179        @remarks
180            If you have created a font of type FT_IMAGE, this method tells the
181            Font which image to use as the source for the characters. So the parameter
182            should be the name of an appropriate image file. Note that when using an image
183            as a font source, you will also need to tell the font where each character is
184            located using setGlyphTexCoords (for each character).
185        @par
186            If you have created a font of type FT_TRUETYPE, this method tells the
187            Font which .ttf file to use to generate the text. You will also need to call
188            setTrueTypeSize and setTrueTypeResolution, and call addCodePointRange
189                        as many times as required to define the range of glyphs you want to be
190                        available.
191        @param source An image file or a truetype font, depending on the type of this font
192        */
193        void setSource(const String& source);
194
195        /** Gets the source this font (either an image or a truetype font).
196        */
197        const String& getSource(void) const;
198
199        /** Sets the size of a truetype font (only required for FT_TRUETYPE).
200        @param ttfSize The size of the font in points. Note that the
201            size of the font does not affect how big it is on the screen, just how large it is in
202            the texture and thus how detailed it is.
203        */
204        void setTrueTypeSize(Real ttfSize);
205        /** Gets the resolution (dpi) of the font used to generate the texture
206        (only required for FT_TRUETYPE).
207        @param ttfResolution The resolution in dpi
208        */
209        void setTrueTypeResolution(uint ttfResolution);
210
211        /** Gets the point size of the font used to generate the texture.
212        @remarks
213            Only applicable for FT_TRUETYPE Font objects.
214            Note that the size of the font does not affect how big it is on the screen,
215            just how large it is in the texture and thus how detailed it is.           
216        */
217        Real getTrueTypeSize(void) const;
218        /** Gets the resolution (dpi) of the font used to generate the texture.
219        @remarks
220            Only applicable for FT_TRUETYPE Font objects.
221        */
222        uint getTrueTypeResolution(void) const;
223
224
225        /** Returns the teture coordinates of the associated glyph.
226            @remarks Parameter is a short to allow both ASCII and wide chars.
227            @param id The code point (unicode)
228            @returns A rectangle with the UV coordinates, or null UVs if the
229                                code point was not present
230        */
231        inline const UVRect& getGlyphTexCoords(CodePoint id) const
232        {
233                        CodePointMap::const_iterator i = mCodePointMap.find(id);
234                        if (i != mCodePointMap.end())
235                        {
236                                return i->second.uvRect;
237                        }
238                        else
239                        {
240                                static UVRect nullRect(0.0, 0.0, 0.0, 0.0);
241                                return nullRect;
242                        }
243        }
244
245        /** Sets the texture coordinates of a glyph.
246        @remarks
247            You only need to call this if you're setting up a font loaded from a texture manually.
248        @note
249            Also sets the aspect ratio (width / height) of this character. textureAspect
250                        is the width/height of the texture (may be non-square)
251        */
252        inline void setGlyphTexCoords(CodePoint id, Real u1, Real v1, Real u2, Real v2, Real textureAspect)
253        {
254                        CodePointMap::iterator i = mCodePointMap.find(id);
255                        if (i != mCodePointMap.end())
256                        {
257                                i->second.uvRect.left = u1;
258                                i->second.uvRect.top = v1;
259                                i->second.uvRect.right = u2;
260                                i->second.uvRect.bottom = v2;
261                                i->second.aspectRatio = textureAspect * (u2 - u1)  / (v2 - v1);
262                        }
263                        else
264                        {
265                                mCodePointMap.insert(
266                                        CodePointMap::value_type(id, 
267                                                GlyphInfo(id, UVRect(u1, v1, u2, v2), 
268                                                        textureAspect * (u2 - u1)  / (v2 - v1))));
269                        }
270
271        }
272        /** Gets the aspect ratio (width / height) of this character. */
273        inline Real getGlyphAspectRatio(CodePoint id) const
274        {
275                        CodePointMap::const_iterator i = mCodePointMap.find(id);
276                        if (i != mCodePointMap.end())
277                        {
278                                return i->second.aspectRatio;
279                        }
280                        else
281                        {
282                                return 1.0;
283                        }
284        }
285        /** Sets the aspect ratio (width / height) of this character.
286        @remarks
287            You only need to call this if you're setting up a font loaded from a
288                        texture manually.
289        */
290        inline void setGlyphAspectRatio(CodePoint id, Real ratio)
291        {
292                        CodePointMap::iterator i = mCodePointMap.find(id);
293                        if (i != mCodePointMap.end())
294                        {
295                                i->second.aspectRatio = ratio;
296                        }
297        }
298
299                /** Gets the information available for a glyph corresponding to a
300                        given code point, or throws an exception if it doesn't exist;
301                */
302                const GlyphInfo& getGlyphInfo(CodePoint id) const;
303
304                /** Adds a range of code points to the list of code point ranges to generate
305                        glyphs for, if this is a truetype based font.
306                @remarks
307                        In order to save texture space, only the glyphs which are actually
308                        needed by the application are generated into the texture. Before this
309                        object is loaded you must call this method as many times as necessary
310                        to define the code point range that you need.
311                */
312                void addCodePointRange(const CodePointRange& range)
313                {
314                        mCodePointRangeList.push_back(range);
315                }
316
317                /** Clear the list of code point ranges.
318                */
319                void clearCodePointRanges()
320                {
321                        mCodePointRangeList.clear();
322                }
323                /** Get a const reference to the list of code point ranges to be used to
324                        generate glyphs from a truetype font.
325                */
326                const CodePointRangeList& getCodePointRangeList() const
327                {
328                        return mCodePointRangeList;
329                }
330        /** Gets the material generated for this font, as a weak reference.
331        @remarks
332            This will only be valid after the Font has been loaded.
333        */
334        inline const MaterialPtr& getMaterial() const
335        {
336            return mpMaterial;
337        }
338        /** Gets the material generated for this font, as a weak reference.
339        @remarks
340            This will only be valid after the Font has been loaded.
341        */
342        inline const MaterialPtr& getMaterial()
343        {
344            return mpMaterial;
345        }
346        /** Sets whether or not the colour of this font is antialiased as it is generated
347            from a true type font.
348        @remarks
349                This is valid only for a FT_TRUETYPE font. If you are planning on using
350            alpha blending to draw your font, then it is a good idea to set this to
351            false (which is the default), otherwise the darkening of the font will combine
352            with the fading out of the alpha around the edges and make your font look thinner
353            than it should. However, if you intend to blend your font using a colour blending
354            mode (add or modulate for example) then it's a good idea to set this to true, in
355            order to soften your font edges.
356        */
357        inline void setAntialiasColour(bool enabled)
358        {
359                mAntialiasColour = enabled;
360        }
361
362                /** Gets whether or not the colour of this font is antialiased as it is generated
363                from a true type font.
364                */
365        inline bool getAntialiasColour(void) const
366        {
367            return mAntialiasColour;
368        }
369
370                /** Implementation of ManualResourceLoader::loadResource, called
371                        when the Texture that this font creates needs to (re)load.
372                */
373                void loadResource(Resource* resource);
374    };
375        /** Specialisation of SharedPtr to allow SharedPtr to be assigned to FontPtr
376        @note Has to be a subclass since we need operator=.
377        We could templatise this instead of repeating per Resource subclass,
378        except to do so requires a form VC6 does not support i.e.
379        ResourceSubclassPtr<T> : public SharedPtr<T>
380        */
381        class _OgreExport FontPtr : public SharedPtr<Font> 
382        {
383        public:
384                FontPtr() : SharedPtr<Font>() {}
385                explicit FontPtr(Font* rep) : SharedPtr<Font>(rep) {}
386                FontPtr(const FontPtr& r) : SharedPtr<Font>(r) {} 
387                FontPtr(const ResourcePtr& r) : SharedPtr<Font>()
388                {
389                        // lock & copy other mutex pointer
390            OGRE_MUTEX_CONDITIONAL(r.OGRE_AUTO_MUTEX_NAME)
391            {
392                            OGRE_LOCK_MUTEX(*r.OGRE_AUTO_MUTEX_NAME)
393                            OGRE_COPY_AUTO_SHARED_MUTEX(r.OGRE_AUTO_MUTEX_NAME)
394                            pRep = static_cast<Font*>(r.getPointer());
395                            pUseCount = r.useCountPointer();
396                            if (pUseCount)
397                            {
398                                    ++(*pUseCount);
399                            }
400            }
401                }
402
403                /// Operator used to convert a ResourcePtr to a FontPtr
404                FontPtr& operator=(const ResourcePtr& r)
405                {
406                        if (pRep == static_cast<Font*>(r.getPointer()))
407                                return *this;
408                        release();
409                        // lock & copy other mutex pointer
410            OGRE_MUTEX_CONDITIONAL(r.OGRE_AUTO_MUTEX_NAME)
411            {
412                OGRE_LOCK_MUTEX(*r.OGRE_AUTO_MUTEX_NAME)
413                            OGRE_COPY_AUTO_SHARED_MUTEX(r.OGRE_AUTO_MUTEX_NAME)
414                            pRep = static_cast<Font*>(r.getPointer());
415                            pUseCount = r.useCountPointer();
416                            if (pUseCount)
417                            {
418                                    ++(*pUseCount);
419                            }
420            }
421                        else
422                        {
423                                // RHS must be a null pointer
424                                assert(r.isNull() && "RHS must be null if it has no mutex!");
425                                setNull();
426                        }
427                        return *this;
428                }
429        };
430}
431
432#endif
Note: See TracBrowser for help on using the repository browser.