2 CGUITTFont FreeType class for Irrlicht
3 Copyright (c) 2009-2010 John Norman
4 Copyright (c) 2016 Nathanaƫl Courant
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.
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:
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.
19 2. Altered source versions must be plainly marked as such, and
20 must not be misrepresented as being the original software.
22 3. This notice may not be removed or altered from any source
25 The original version of this class can be located at:
26 http://irrlicht.suckerfreegames.com/
29 john@suckerfreegames.com
38 #include <irrUString.h>
39 #include "util/enriched_string.h"
40 #include "util/basic_macros.h"
41 #include FT_FREETYPE_H
50 //! Structure representing a single TrueType glyph.
64 DISABLE_CLASS_COPY(SGUITTGlyph);
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),
72 advance(other.advance),
73 surface(other.surface),
80 ~SGUITTGlyph() { unload(); }
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);
89 //! Unloads the glyph.
92 //! Creates the IImage object from the FT_Bitmap.
93 video::IImage* createGlyphImage(const FT_Bitmap& bits, video::IVideoDriver* driver) const;
95 //! If true, the glyph has been loaded.
98 //! The page the glyph is on.
101 //! The source rectangle for the glyph.
102 core::recti source_rect;
104 //! The offset of glyph when drawn.
105 core::vector2di offset;
107 //! Glyph advance information.
110 //! This is just the temporary image holder. After this glyph is paged,
111 //! it will be dropped.
112 mutable video::IImage* surface;
114 //! The pointer pointing to the parent (CGUITTFont)
118 //! Holds a sheet of glyphs.
119 class CGUITTGlyphPage
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) {}
128 driver->removeTexture(texture);
129 else texture->drop();
133 //! Create the actual page texture,
134 bool createPageTexture(const u8& pixel_mode, const core::dimension2du& texture_size)
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);
146 // Set the texture color format.
149 case FT_PIXEL_MODE_MONO:
150 texture = driver->addTexture(texture_size, name, video::ECF_A1R5G5B5);
152 case FT_PIXEL_MODE_GRAY:
154 texture = driver->addTexture(texture_size, name, video::ECF_A8R8G8B8);
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);
163 return texture ? true : false;
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)
170 glyph_to_be_paged.push_back(glyph);
173 //! Updates the texture atlas with new glyphs.
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);
183 for (u32 i = 0; i < glyph_to_be_paged.size(); ++i)
185 const SGUITTGlyph* glyph = glyph_to_be_paged[i];
186 if (glyph && glyph->isLoaded)
190 glyph->surface->copyTo(pageholder, glyph->source_rect.UpperLeftCorner);
191 glyph->surface->drop();
196 ; // TODO: add error message?
197 //currently, if we failed to create the image, just ignore this operation.
204 glyph_to_be_paged.clear();
208 video::ITexture* texture;
213 core::array<core::vector2di> render_positions;
214 core::array<core::recti> render_source_rects;
215 core::array<video::SColor> render_colors;
218 core::array<const SGUITTGlyph*> glyph_to_be_paged;
219 video::IVideoDriver* driver;
223 //! Class representing a TrueType font.
224 class CGUITTFont : public IGUIFont
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);
240 virtual ~CGUITTFont();
242 //! Sets the amount of glyphs to batch load.
243 virtual void setBatchLoadSize(u32 batch_size) { batch_load_size = batch_size; }
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; }
248 //! Get the font size.
249 virtual u32 getFontSize() const { return size; }
251 //! Check the font's transparency.
252 virtual bool isTransparent() const { return use_transparency; }
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; }
258 //! Check if the font hinting is enabled.
259 virtual bool useHinting() const { return use_hinting; }
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; }
265 //! Tells the font to allow transparency when rendering.
267 //! \param flag If true, the font draws using transparency.
268 virtual void setTransparency(const bool flag);
270 //! Tells the font to use monochrome rendering.
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);
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);
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);
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);
290 //! Returns the dimension of a character produced by this font.
291 virtual core::dimension2d<u32> getCharDimension(const wchar_t ch) const;
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;
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;
301 //! Sets global kerning width for the font.
302 virtual void setKerningWidth(s32 kerning);
304 //! Sets global kerning height for the font.
305 virtual void setKerningHeight(s32 kerning);
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;
311 //! Returns the distance between letters
312 virtual s32 getKerningHeight() const;
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);
318 //! Get the last glyph page if there's still available slots.
319 //! If not, it will return zero.
320 CGUITTGlyphPage* getLastGlyphPage() const;
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);
327 //! Get the last glyph page's index.
328 u32 getLastGlyphPageIndex() const { return Glyph_Pages.size() - 1; }
330 //! Set font that should be used for glyphs not present in ours
331 void setFallback(gui::IGUIFont* font) { fallback = font; }
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);
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;
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 );
347 inline s32 getAscender() const { return font_metrics.ascender; }
351 bool use_transparency;
353 bool use_auto_hinting;
356 core::dimension2du max_page_texture_size;
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_;
366 CGUITTFont(IGUIEnvironment *env);
367 bool load(const io::path& filename, const u32 size, const bool antialias, const bool transparency);
369 void update_glyph_pages() const;
370 void update_load_flags()
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;
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;
389 void createSharedPlane();
391 irr::IrrlichtDevice* Device;
392 gui::IGUIEnvironment* Environment;
393 video::IVideoDriver* Driver;
396 FT_Size_Metrics font_metrics;
399 mutable core::array<CGUITTGlyphPage*> Glyph_Pages;
400 mutable core::array<SGUITTGlyph> Glyphs;
402 s32 GlobalKerningWidth;
403 s32 GlobalKerningHeight;
404 core::ustring Invisible;
408 gui::IGUIFont* fallback;
411 } // end namespace gui
412 } // end namespace irr