src/cguittfont/CGUITTFont.h

   1 /*
   2    CGUITTFont FreeType class for Irrlicht
   3    Copyright (c) 2009-2010 John Norman
   4
   5    This software is provided 'as-is', without any express or implied
   6    warranty. In no event will the authors be held liable for any
   7    damages arising from the use of this software.
   8
   9    Permission is granted to anyone to use this software for any
  10    purpose, including commercial applications, and to alter it and
  11    redistribute it freely, subject to the following restrictions:
  12
  13    1. The origin of this software must not be misrepresented; you
  14       must not claim that you wrote the original software. If you use
  15       this software in a product, an acknowledgment in the product
  16       documentation would be appreciated but is not required.
  17
  18    2. Altered source versions must be plainly marked as such, and
  19       must not be misrepresented as being the original software.
  20
  21    3. This notice may not be removed or altered from any source
  22       distribution.
  23
  24    The original version of this class can be located at:
  25    http://irrlicht.suckerfreegames.com/
  26
  27    John Norman
  28    john@suckerfreegames.com
  29 */
  30
  31 #ifndef __C_GUI_TTFONT_H_INCLUDED__
  32 #define __C_GUI_TTFONT_H_INCLUDED__
  33
  34 #include <irrlicht.h>
  35 #include <ft2build.h>
  36 #include FT_FREETYPE_H
  37
  38 namespace irr
  39 {
  40 namespace gui
  41 {
  42         struct SGUITTFace;
  43         class CGUITTFont;
  44
  45         //! Class to assist in deleting glyphs.
  46         class CGUITTAssistDelete
  47         {
  48                 public:
  49                         template <class T, typename TAlloc>
  50                         static void Delete(core::array<T, TAlloc>& a)
  51                         {
  52                                 TAlloc allocator;
  53                                 allocator.deallocate(a.pointer());
  54                         }
  55         };
  56
  57         //! Structure representing a single TrueType glyph.
  58         struct SGUITTGlyph
  59         {
  60                 //! Constructor.
  61                 SGUITTGlyph() : isLoaded(false), glyph_page(0), surface(0), parent(0) {}
  62
  63                 //! Destructor.
  64                 ~SGUITTGlyph() { unload(); }
  65
  66                 //! Preload the glyph.
  67                 //!     The preload process occurs when the program tries to cache the glyph from FT_Library.
  68                 //! However, it simply defines the SGUITTGlyph's properties and will only create the page
  69                 //! textures if necessary.  The actual creation of the textures should only occur right
  70                 //! before the batch draw call.
  71                 void preload(u32 char_index, FT_Face face, video::IVideoDriver* driver, u32 font_size, const FT_Int32 loadFlags);
  72
  73                 //! Unloads the glyph.
  74                 void unload();
  75
  76                 //! Creates the IImage object from the FT_Bitmap.
  77                 video::IImage* createGlyphImage(const FT_Bitmap& bits, video::IVideoDriver* driver) const;
  78
  79                 //! If true, the glyph has been loaded.
  80                 bool isLoaded;
  81
  82                 //! The page the glyph is on.
  83                 u32 glyph_page;
  84
  85                 //! The source rectangle for the glyph.
  86                 core::recti source_rect;
  87
  88                 //! The offset of glyph when drawn.
  89                 core::vector2di offset;
  90
  91                 //! Glyph advance information.
  92                 FT_Vector advance;
  93
  94                 //! This is just the temporary image holder.  After this glyph is paged,
  95                 //! it will be dropped.
  96                 mutable video::IImage* surface;
  97
  98                 //! The pointer pointing to the parent (CGUITTFont)
  99                 CGUITTFont* parent;
 100         };
 101
 102         //! Holds a sheet of glyphs.
 103         class CGUITTGlyphPage
 104         {
 105                 public:
 106                         CGUITTGlyphPage(video::IVideoDriver* Driver, const io::path& texture_name) :texture(0), available_slots(0), used_slots(0), dirty(false), driver(Driver), name(texture_name) {}
 107                         ~CGUITTGlyphPage()
 108                         {
 109                                 if (texture)
 110                                 {
 111                                         if (driver)
 112                                                 driver->removeTexture(texture);
 113                                         else texture->drop();
 114                                 }
 115                         }
 116
 117                         //! Create the actual page texture,
 118                         bool createPageTexture(const u8& pixel_mode, const core::dimension2du& texture_size)
 119                         {
 120                                 if( texture )
 121                                         return false;
 122
 123                                 bool flgmip = driver->getTextureCreationFlag(video::ETCF_CREATE_MIP_MAPS);
 124                                 driver->setTextureCreationFlag(video::ETCF_CREATE_MIP_MAPS, false);
 125
 126                                 // Set the texture color format.
 127                                 switch (pixel_mode)
 128                                 {
 129                                         case FT_PIXEL_MODE_MONO:
 130                                                 texture = driver->addTexture(texture_size, name, video::ECF_A1R5G5B5);
 131                                                 break;
 132                                         case FT_PIXEL_MODE_GRAY:
 133                                         default:
 134                                                 texture = driver->addTexture(texture_size, name, video::ECF_A8R8G8B8);
 135                                                 break;
 136                                 }
 137
 138                                 // Restore our texture creation flags.
 139                                 driver->setTextureCreationFlag(video::ETCF_CREATE_MIP_MAPS, flgmip);
 140                                 return texture ? true : false;
 141                         }
 142
 143                         //! Add the glyph to a list of glyphs to be paged.
 144                         //! This collection will be cleared after updateTexture is called.
 145                         void pushGlyphToBePaged(const SGUITTGlyph* glyph)
 146                         {
 147                                 glyph_to_be_paged.push_back(glyph);
 148                         }
 149
 150                         //! Updates the texture atlas with new glyphs.
 151                         void updateTexture()
 152                         {
 153                                 if (!dirty) return;
 154
 155                                 void* ptr = texture->lock();
 156                                 video::ECOLOR_FORMAT format = texture->getColorFormat();
 157                                 core::dimension2du size = texture->getOriginalSize();
 158                                 video::IImage* pageholder = driver->createImageFromData(format, size, ptr, true, false);
 159
 160                                 for (u32 i = 0; i < glyph_to_be_paged.size(); ++i)
 161                                 {
 162                                         const SGUITTGlyph* glyph = glyph_to_be_paged[i];
 163                                         if (glyph && glyph->isLoaded)
 164                                         {
 165                                                 if (glyph->surface)
 166                                                 {
 167                                                         glyph->surface->copyTo(pageholder, glyph->source_rect.UpperLeftCorner);
 168                                                         glyph->surface->drop();
 169                                                         glyph->surface = 0;
 170                                                 }
 171                                                 else
 172                                                 {
 173                                                         ; // TODO: add error message?
 174                                                         //currently, if we failed to create the image, just ignore this operation.
 175                                                 }
 176                                         }
 177                                 }
 178
 179                                 pageholder->drop();
 180                                 texture->unlock();
 181                                 glyph_to_be_paged.clear();
 182                                 dirty = false;
 183                         }
 184
 185                         video::ITexture* texture;
 186                         u32 available_slots;
 187                         u32 used_slots;
 188                         bool dirty;
 189
 190                         core::array<core::vector2di> render_positions;
 191                         core::array<core::recti> render_source_rects;
 192
 193                 private:
 194                         core::array<const SGUITTGlyph*> glyph_to_be_paged;
 195                         video::IVideoDriver* driver;
 196                         io::path name;
 197         };
 198
 199         //! Class representing a TrueType font.
 200         class CGUITTFont : public IGUIFont
 201         {
 202                 public:
 203                         //! Creates a new TrueType font and returns a pointer to it.  The pointer must be drop()'ed when finished.
 204                         //! \param env The IGUIEnvironment the font loads out of.
 205                         //! \param filename The filename of the font.
 206                         //! \param size The size of the font glyphs in pixels.  Since this is the size of the individual glyphs, the true height of the font may change depending on the characters used.
 207                         //! \param antialias set the use_monochrome (opposite to antialias) flag
 208                         //! \param transparency set the use_transparency flag
 209                         //! \return Returns a pointer to a CGUITTFont.  Will return 0 if the font failed to load.
 210                         static CGUITTFont* createTTFont(IGUIEnvironment *env, const io::path& filename, const u32 size, const bool antialias = true, const bool transparency = true, const u32 shadow = 0, const u32 shadow_alpha = 255);
 211                         static CGUITTFont* createTTFont(IrrlichtDevice *device, const io::path& filename, const u32 size, const bool antialias = true, const bool transparency = true);
 212                         static CGUITTFont* create(IGUIEnvironment *env, const io::path& filename, const u32 size, const bool antialias = true, const bool transparency = true);
 213                         static CGUITTFont* create(IrrlichtDevice *device, const io::path& filename, const u32 size, const bool antialias = true, const bool transparency = true);
 214
 215                         //! Destructor
 216                         virtual ~CGUITTFont();
 217
 218                         //! Sets the amount of glyphs to batch load.
 219                         virtual void setBatchLoadSize(u32 batch_size) { batch_load_size = batch_size; }
 220
 221                         //! Sets the maximum texture size for a page of glyphs.
 222                         virtual void setMaxPageTextureSize(const core::dimension2du& texture_size) { max_page_texture_size = texture_size; }
 223
 224                         //! Get the font size.
 225                         virtual u32 getFontSize() const { return size; }
 226
 227                         //! Check the font's transparency.
 228                         virtual bool isTransparent() const { return use_transparency; }
 229
 230                         //! Check if the font auto-hinting is enabled.
 231                         //! Auto-hinting is FreeType's built-in font hinting engine.
 232                         virtual bool useAutoHinting() const { return use_auto_hinting; }
 233
 234                         //! Check if the font hinting is enabled.
 235                         virtual bool useHinting()        const { return use_hinting; }
 236
 237                         //! Check if the font is being loaded as a monochrome font.
 238                         //! The font can either be a 256 color grayscale font, or a 2 color monochrome font.
 239                         virtual bool useMonochrome()  const { return use_monochrome; }
 240
 241                         //! Tells the font to allow transparency when rendering.
 242                         //! Default: true.
 243                         //! \param flag If true, the font draws using transparency.
 244                         virtual void setTransparency(const bool flag);
 245
 246                         //! Tells the font to use monochrome rendering.
 247                         //! Default: false.
 248                         //! \param flag If true, the font draws using a monochrome image.  If false, the font uses a grayscale image.
 249                         virtual void setMonochrome(const bool flag);
 250
 251                         //! Enables or disables font hinting.
 252                         //! Default: Hinting and auto-hinting true.
 253                         //! \param enable If false, font hinting is turned off. If true, font hinting is turned on.
 254                         //! \param enable_auto_hinting If true, FreeType uses its own auto-hinting algorithm.  If false, it tries to use the algorithm specified by the font.
 255                         virtual void setFontHinting(const bool enable, const bool enable_auto_hinting = true);
 256
 257                         //! Draws some text and clips it to the specified rectangle if wanted.
 258                         virtual void draw(const core::stringw& text, const core::rect<s32>& position,
 259                                 video::SColor color, bool hcenter=false, bool vcenter=false,
 260                                 const core::rect<s32>* clip=0);
 261
 262                         //! Returns the dimension of a character produced by this font.
 263                         virtual core::dimension2d<u32> getCharDimension(const wchar_t ch) const;
 264
 265                         //! Returns the dimension of a text string.
 266                         virtual core::dimension2d<u32> getDimension(const wchar_t* text) const;
 267                         virtual core::dimension2d<u32> getDimension(const core::ustring& text) const;
 268
 269                         //! Calculates the index of the character in the text which is on a specific position.
 270                         virtual s32 getCharacterFromPos(const wchar_t* text, s32 pixel_x) const;
 271                         virtual s32 getCharacterFromPos(const core::ustring& text, s32 pixel_x) const;
 272
 273                         //! Sets global kerning width for the font.
 274                         virtual void setKerningWidth(s32 kerning);
 275
 276                         //! Sets global kerning height for the font.
 277                         virtual void setKerningHeight(s32 kerning);
 278
 279                         //! Gets kerning values (distance between letters) for the font. If no parameters are provided,
 280                         virtual s32 getKerningWidth(const wchar_t* thisLetter=0, const wchar_t* previousLetter=0) const;
 281                         virtual s32 getKerningWidth(const uchar32_t thisLetter=0, const uchar32_t previousLetter=0) const;
 282
 283                         //! Returns the distance between letters
 284                         virtual s32 getKerningHeight() const;
 285
 286                         //! Define which characters should not be drawn by the font.
 287                         virtual void setInvisibleCharacters(const wchar_t *s);
 288                         virtual void setInvisibleCharacters(const core::ustring& s);
 289
 290                         //! Get the last glyph page if there's still available slots.
 291                         //! If not, it will return zero.
 292                         CGUITTGlyphPage* getLastGlyphPage() const;
 293
 294                         //! Create a new glyph page texture.
 295                         //! \param pixel_mode the pixel mode defined by FT_Pixel_Mode
 296                         //should be better typed. fix later.
 297                         CGUITTGlyphPage* createGlyphPage(const u8& pixel_mode);
 298
 299                         //! Get the last glyph page's index.
 300                         u32 getLastGlyphPageIndex() const { return Glyph_Pages.size() - 1; }
 301
 302                         //! Create corresponding character's software image copy from the font,
 303                         //! so you can use this data just like any ordinary video::IImage.
 304                         //! \param ch The character you need
 305                         virtual video::IImage* createTextureFromChar(const uchar32_t& ch);
 306
 307                         //! This function is for debugging mostly. If the page doesn't exist it returns zero.
 308                         //! \param page_index Simply return the texture handle of a given page index.
 309                         virtual video::ITexture* getPageTextureByIndex(const u32& page_index) const;
 310
 311                         //! Add a list of scene nodes generated by putting font textures on the 3D planes.
 312                         virtual core::array<scene::ISceneNode*> addTextSceneNode
 313                                 (const wchar_t* text, scene::ISceneManager* smgr, scene::ISceneNode* parent = 0,
 314                                  const video::SColor& color = video::SColor(255, 0, 0, 0), bool center = false );
 315
 316                 protected:
 317                         bool use_monochrome;
 318                         bool use_transparency;
 319                         bool use_hinting;
 320                         bool use_auto_hinting;
 321                         u32 size;
 322                         u32 batch_load_size;
 323                         core::dimension2du max_page_texture_size;
 324
 325                 private:
 326                         // Manages the FreeType library.
 327                         static FT_Library c_library;
 328                         static core::map<io::path, SGUITTFace*> c_faces;
 329                         static bool c_libraryLoaded;
 330                         static scene::IMesh* shared_plane_ptr_;
 331                         static scene::SMesh  shared_plane_;
 332
 333                         CGUITTFont(IGUIEnvironment *env);
 334                         bool load(const io::path& filename, const u32 size, const bool antialias, const bool transparency);
 335                         void reset_images();
 336                         void update_glyph_pages() const;
 337                         void update_load_flags()
 338                         {
 339                                 // Set up our loading flags.
 340                                 load_flags = FT_LOAD_DEFAULT | FT_LOAD_RENDER;
 341                                 if (!useHinting()) load_flags |= FT_LOAD_NO_HINTING;
 342                                 if (!useAutoHinting()) load_flags |= FT_LOAD_NO_AUTOHINT;
 343                                 if (useMonochrome()) load_flags |= FT_LOAD_MONOCHROME | FT_LOAD_TARGET_MONO | FT_RENDER_MODE_MONO;
 344                                 else load_flags |= FT_LOAD_TARGET_NORMAL;
 345                         }
 346                         u32 getWidthFromCharacter(wchar_t c) const;
 347                         u32 getWidthFromCharacter(uchar32_t c) const;
 348                         u32 getHeightFromCharacter(wchar_t c) const;
 349                         u32 getHeightFromCharacter(uchar32_t c) const;
 350                         u32 getGlyphIndexByChar(wchar_t c) const;
 351                         u32 getGlyphIndexByChar(uchar32_t c) const;
 352                         core::vector2di getKerning(const wchar_t thisLetter, const wchar_t previousLetter) const;
 353                         core::vector2di getKerning(const uchar32_t thisLetter, const uchar32_t previousLetter) const;
 354                         core::dimension2d<u32> getDimensionUntilEndOfLine(const wchar_t* p) const;
 355
 356                         void createSharedPlane();
 357
 358                         irr::IrrlichtDevice* Device;
 359                         gui::IGUIEnvironment* Environment;
 360                         video::IVideoDriver* Driver;
 361                         io::path filename;
 362                         FT_Face tt_face;
 363                         FT_Size_Metrics font_metrics;
 364                         FT_Int32 load_flags;
 365
 366                         mutable core::array<CGUITTGlyphPage*> Glyph_Pages;
 367                         mutable core::array<SGUITTGlyph> Glyphs;
 368
 369                         s32 GlobalKerningWidth;
 370                         s32 GlobalKerningHeight;
 371                         core::ustring Invisible;
 372                         u32 shadow_offset;
 373                         u32 shadow_alpha;
 374         };
 375
 376 } // end namespace gui
 377 } // end namespace irr
 378
 379 #endif // __C_GUI_TTFONT_H_INCLUDED__