src/irrlicht_changes/CGUITTFont.h

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