src/irrlicht_changes/CGUITTFont.h

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