1 /* 2 * FTGL - OpenGL font library 3 * 4 * Copyright (c) 2001-2004 Henry Maddocks <ftgl@opengl.geek.nz> 5 * Copyright (c) 2008 Sam Hocevar <sam@zoy.org> 6 * Copyright (c) 2008 Sean Morrison <learner@brlcad.org> 7 * 8 * Permission is hereby granted, free of charge, to any person obtaining 9 * a copy of this software and associated documentation files (the 10 * "Software"), to deal in the Software without restriction, including 11 * without limitation the rights to use, copy, modify, merge, publish, 12 * distribute, sublicense, and/or sell copies of the Software, and to 13 * permit persons to whom the Software is furnished to do so, subject to 14 * the following conditions: 15 * 16 * The above copyright notice and this permission notice shall be 17 * included in all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 20 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 22 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 23 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 24 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 25 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 26 */ 27 28 #ifndef __ftgl__ 29 # warning This header is deprecated. Please use <FTGL/ftgl.h> from now. 30 # include <FTGL/ftgl.h> 31 #endif 32 33 #ifndef __FTFont__ 34 #define __FTFont__ 35 36 #ifdef __cplusplus 37 38 class FTFontImpl; 39 40 /** 41 * FTFont is the public interface for the FTGL library. 42 * 43 * Specific font classes are derived from this class. It uses the helper 44 * classes FTFace and FTSize to access the Freetype library. This class 45 * is abstract and deriving classes must implement the protected 46 * <code>MakeGlyph</code> function to create glyphs of the 47 * appropriate type. 48 * 49 * It is good practice after using these functions to test the error 50 * code returned. <code>FT_Error Error()</code>. Check the freetype file 51 * fterrdef.h for error definitions. 52 * 53 * @see FTFace 54 * @see FTSize 55 */ 56 class FTGL_EXPORT FTFont 57 { 58 protected: 59 /** 60 * Open and read a font file. Sets Error flag. 61 * 62 * @param fontFilePath font file path. 63 */ 64 FTFont(char const *fontFilePath); 65 66 /** 67 * Open and read a font from a buffer in memory. Sets Error flag. 68 * The buffer is owned by the client and is NOT copied by FTGL. The 69 * pointer must be valid while using FTGL. 70 * 71 * @param pBufferBytes the in-memory buffer 72 * @param bufferSizeInBytes the length of the buffer in bytes 73 */ 74 FTFont(const unsigned char *pBufferBytes, size_t bufferSizeInBytes); 75 76 private: 77 /* Allow our internal subclasses to access the private constructor */ 78 friend class FTBitmapFont; 79 friend class FTBufferFont; 80 friend class FTExtrudeFont; 81 friend class FTOutlineFont; 82 friend class FTPixmapFont; 83 friend class FTPolygonFont; 84 friend class FTTextureFont; 85 86 /** 87 * Internal FTGL FTFont constructor. For private use only. 88 * 89 * @param pImpl Internal implementation object. Will be destroyed 90 * upon FTFont deletion. 91 */ 92 FTFont(FTFontImpl *pImpl); 93 94 public: 95 virtual ~FTFont(); 96 97 /** 98 * Attach auxilliary file to font e.g font metrics. 99 * 100 * Note: not all font formats implement this function. 101 * 102 * @param fontFilePath auxilliary font file path. 103 * @return <code>true</code> if file has been attached 104 * successfully. 105 */ 106 virtual bool Attach(const char* fontFilePath); 107 108 /** 109 * Attach auxilliary data to font e.g font metrics, from memory. 110 * 111 * Note: not all font formats implement this function. 112 * 113 * @param pBufferBytes the in-memory buffer. 114 * @param bufferSizeInBytes the length of the buffer in bytes. 115 * @return <code>true</code> if file has been attached 116 * successfully. 117 */ 118 virtual bool Attach(const unsigned char *pBufferBytes, 119 size_t bufferSizeInBytes); 120 121 /** 122 * Set the glyph loading flags. By default, fonts use the most 123 * sensible flags when loading a font's glyph using FT_Load_Glyph(). 124 * This function allows to override the default flags. 125 * 126 * @param flags The glyph loading flags. 127 */ 128 virtual void GlyphLoadFlags(FT_Int flags); 129 130 /** 131 * Set the character map for the face. 132 * 133 * @param encoding Freetype enumerate for char map code. 134 * @return <code>true</code> if charmap was valid and 135 * set correctly. 136 */ 137 virtual bool CharMap(FT_Encoding encoding); 138 139 /** 140 * Get the number of character maps in this face. 141 * 142 * @return character map count. 143 */ 144 virtual unsigned int CharMapCount() const; 145 146 /** 147 * Get a list of character maps in this face. 148 * 149 * @return pointer to the first encoding. 150 */ 151 virtual FT_Encoding* CharMapList(); 152 153 /** 154 * Set the char size for the current face. 155 * 156 * @param size the face size in points (1/72 inch) 157 * @param res the resolution of the target device. 158 * @return <code>true</code> if size was set correctly 159 */ 160 virtual bool FaceSize(const unsigned int size, 161 const unsigned int res = 72); 162 163 /** 164 * Get the current face size in points (1/72 inch). 165 * 166 * @return face size 167 */ 168 virtual unsigned int FaceSize() const; 169 170 /** 171 * Set the extrusion distance for the font. Only implemented by 172 * FTExtrudeFont 173 * 174 * @param depth The extrusion distance. 175 */ 176 virtual void Depth(float depth); 177 178 /** 179 * Set the outset distance for the font. Only implemented by 180 * FTOutlineFont, FTPolygonFont and FTExtrudeFont 181 * 182 * @param outset The outset distance. 183 */ 184 virtual void Outset(float outset); 185 186 /** 187 * Set the front and back outset distances for the font. Only 188 * implemented by FTExtrudeFont 189 * 190 * @param front The front outset distance. 191 * @param back The back outset distance. 192 */ 193 virtual void Outset(float front, float back); 194 195 /** 196 * Enable or disable the use of Display Lists inside FTGL 197 * 198 * @param useList <code>true</code> turns ON display lists. 199 * <code>false</code> turns OFF display lists. 200 */ 201 virtual void UseDisplayList(bool useList); 202 203 /** 204 * Get the global ascender height for the face. 205 * 206 * @return Ascender height 207 */ 208 virtual float Ascender() const; 209 210 /** 211 * Gets the global descender height for the face. 212 * 213 * @return Descender height 214 */ 215 virtual float Descender() const; 216 217 /** 218 * Gets the line spacing for the font. 219 * 220 * @return Line height 221 */ 222 virtual float LineHeight() const; 223 224 /** 225 * Get the bounding box for a string. 226 * 227 * @param string A char buffer. 228 * @param len The length of the string. If < 0 then all characters 229 * will be checked until a null character is encountered 230 * (optional). 231 * @param position The pen position of the first character (optional). 232 * @param spacing A displacement vector to add after each character 233 * has been checked (optional). 234 * @return The corresponding bounding box. 235 */ 236 virtual FTBBox BBox(const char *string, const int len = -1, 237 FTPoint position = FTPoint(), 238 FTPoint spacing = FTPoint()); 239 240 /** 241 * Get the bounding box for a string (deprecated). 242 * 243 * @param string A char buffer. 244 * @param llx Lower left near x coordinate. 245 * @param lly Lower left near y coordinate. 246 * @param llz Lower left near z coordinate. 247 * @param urx Upper right far x coordinate. 248 * @param ury Upper right far y coordinate. 249 * @param urz Upper right far z coordinate. 250 */ BBox(const char * string,float & llx,float & lly,float & llz,float & urx,float & ury,float & urz)251 void BBox(const char* string, float& llx, float& lly, float& llz, 252 float& urx, float& ury, float& urz) 253 { 254 FTBBox b = BBox(string); 255 llx = b.Lower().Xf(); lly = b.Lower().Yf(); llz = b.Lower().Zf(); 256 urx = b.Upper().Xf(); ury = b.Upper().Yf(); urz = b.Upper().Zf(); 257 } 258 259 /** 260 * Get the bounding box for a string. 261 * 262 * @param string A wchar_t buffer. 263 * @param len The length of the string. If < 0 then all characters 264 * will be checked until a null character is encountered 265 * (optional). 266 * @param position The pen position of the first character (optional). 267 * @param spacing A displacement vector to add after each character 268 * has been checked (optional). 269 * @return The corresponding bounding box. 270 */ 271 virtual FTBBox BBox(const wchar_t *string, const int len = -1, 272 FTPoint position = FTPoint(), 273 FTPoint spacing = FTPoint()); 274 275 /** 276 * Get the bounding box for a string (deprecated). 277 * 278 * @param string A wchar_t buffer. 279 * @param llx Lower left near x coordinate. 280 * @param lly Lower left near y coordinate. 281 * @param llz Lower left near z coordinate. 282 * @param urx Upper right far x coordinate. 283 * @param ury Upper right far y coordinate. 284 * @param urz Upper right far z coordinate. 285 */ BBox(const wchar_t * string,float & llx,float & lly,float & llz,float & urx,float & ury,float & urz)286 void BBox(const wchar_t* string, float& llx, float& lly, float& llz, 287 float& urx, float& ury, float& urz) 288 { 289 FTBBox b = BBox(string); 290 llx = b.Lower().Xf(); lly = b.Lower().Yf(); llz = b.Lower().Zf(); 291 urx = b.Upper().Xf(); ury = b.Upper().Yf(); urz = b.Upper().Zf(); 292 } 293 294 /** 295 * Get the advance for a string. 296 * 297 * @param string 'C' style string to be checked. 298 * @param len The length of the string. If < 0 then all characters 299 * will be checked until a null character is encountered 300 * (optional). 301 * @param spacing A displacement vector to add after each character 302 * has been checked (optional). 303 * @return The string's advance width. 304 */ 305 virtual float Advance(const char* string, const int len = -1, 306 FTPoint spacing = FTPoint()); 307 308 /** 309 * Get the advance for a string. 310 * 311 * @param string A wchar_t string 312 * @param len The length of the string. If < 0 then all characters 313 * will be checked until a null character is encountered 314 * (optional). 315 * @param spacing A displacement vector to add after each character 316 * has been checked (optional). 317 * @return The string's advance width. 318 */ 319 virtual float Advance(const wchar_t* string, const int len = -1, 320 FTPoint spacing = FTPoint()); 321 322 /** 323 * Render a string of characters. 324 * 325 * @param string 'C' style string to be output. 326 * @param len The length of the string. If < 0 then all characters 327 * will be displayed until a null character is encountered 328 * (optional). 329 * @param position The pen position of the first character (optional). 330 * @param spacing A displacement vector to add after each character 331 * has been displayed (optional). 332 * @param renderMode Render mode to use for display (optional). 333 * @return The new pen position after the last character was output. 334 */ 335 virtual FTPoint Render(const char* string, const int len = -1, 336 FTPoint position = FTPoint(), 337 FTPoint spacing = FTPoint(), 338 int renderMode = FTGL::RENDER_ALL); 339 340 /** 341 * Render a string of characters 342 * 343 * @param string wchar_t string to be output. 344 * @param len The length of the string. If < 0 then all characters 345 * will be displayed until a null character is encountered 346 * (optional). 347 * @param position The pen position of the first character (optional). 348 * @param spacing A displacement vector to add after each character 349 * has been displayed (optional). 350 * @param renderMode Render mode to use for display (optional). 351 * @return The new pen position after the last character was output. 352 */ 353 virtual FTPoint Render(const wchar_t *string, const int len = -1, 354 FTPoint position = FTPoint(), 355 FTPoint spacing = FTPoint(), 356 int renderMode = FTGL::RENDER_ALL); 357 358 /** 359 * Queries the Font for errors. 360 * 361 * @return The current error code. 362 */ 363 virtual FT_Error Error() const; 364 365 protected: 366 /* Allow impl to access MakeGlyph */ 367 friend class FTFontImpl; 368 369 /** 370 * Construct a glyph of the correct type. 371 * 372 * Clients must override the function and return their specialised 373 * FTGlyph. 374 * 375 * @param slot A FreeType glyph slot. 376 * @return An FT****Glyph or <code>null</code> on failure. 377 */ 378 virtual FTGlyph* MakeGlyph(FT_GlyphSlot slot) = 0; 379 380 private: 381 /** 382 * Internal FTGL FTFont implementation object. For private use only. 383 */ 384 FTFontImpl *impl; 385 }; 386 387 #endif //__cplusplus 388 389 FTGL_BEGIN_C_DECLS 390 391 /** 392 * FTGLfont is the public interface for the FTGL library. 393 * 394 * It is good practice after using these functions to test the error 395 * code returned. <code>FT_Error Error()</code>. Check the freetype file 396 * fterrdef.h for error definitions. 397 */ 398 struct _FTGLFont; 399 typedef struct _FTGLfont FTGLfont; 400 401 /** 402 * Create a custom FTGL font object. 403 * 404 * @param fontFilePath The font file name. 405 * @param data A pointer to private data that will be passed to callbacks. 406 * @param makeglyphCallback A glyph-making callback function. 407 * @return An FTGLfont* object. 408 */ 409 FTGL_EXPORT FTGLfont *ftglCreateCustomFont(char const *fontFilePath, 410 void *data, 411 FTGLglyph * (*makeglyphCallback) (FT_GlyphSlot, void *)); 412 413 /** 414 * Destroy an FTGL font object. 415 * 416 * @param font An FTGLfont* object. 417 */ 418 FTGL_EXPORT void ftglDestroyFont(FTGLfont* font); 419 420 /** 421 * Attach auxilliary file to font e.g. font metrics. 422 * 423 * Note: not all font formats implement this function. 424 * 425 * @param font An FTGLfont* object. 426 * @param path Auxilliary font file path. 427 * @return 1 if file has been attached successfully. 428 */ 429 FTGL_EXPORT int ftglAttachFile(FTGLfont* font, const char* path); 430 431 /** 432 * Attach auxilliary data to font, e.g. font metrics, from memory. 433 * 434 * Note: not all font formats implement this function. 435 * 436 * @param font An FTGLfont* object. 437 * @param data The in-memory buffer. 438 * @param size The length of the buffer in bytes. 439 * @return 1 if file has been attached successfully. 440 */ 441 FTGL_EXPORT int ftglAttachData(FTGLfont* font, const unsigned char * data, 442 size_t size); 443 444 /** 445 * Set the character map for the face. 446 * 447 * @param font An FTGLfont* object. 448 * @param encoding Freetype enumerate for char map code. 449 * @return 1 if charmap was valid and set correctly. 450 */ 451 FTGL_EXPORT int ftglSetFontCharMap(FTGLfont* font, FT_Encoding encoding); 452 453 /** 454 * Get the number of character maps in this face. 455 * 456 * @param font An FTGLfont* object. 457 * @return character map count. 458 */ 459 FTGL_EXPORT unsigned int ftglGetFontCharMapCount(FTGLfont* font); 460 461 /** 462 * Get a list of character maps in this face. 463 * 464 * @param font An FTGLfont* object. 465 * @return pointer to the first encoding. 466 */ 467 FTGL_EXPORT FT_Encoding* ftglGetFontCharMapList(FTGLfont* font); 468 469 /** 470 * Set the char size for the current face. 471 * 472 * @param font An FTGLfont* object. 473 * @param size The face size in points (1/72 inch). 474 * @param res The resolution of the target device, or 0 to use the default 475 * value of 72. 476 * @return 1 if size was set correctly. 477 */ 478 FTGL_EXPORT int ftglSetFontFaceSize(FTGLfont* font, unsigned int size, 479 unsigned int res); 480 481 /** 482 * Get the current face size in points (1/72 inch). 483 * 484 * @param font An FTGLfont* object. 485 * @return face size 486 */ 487 FTGL_EXPORT unsigned int ftglGetFontFaceSize(FTGLfont* font); 488 489 /** 490 * Set the extrusion distance for the font. Only implemented by 491 * FTExtrudeFont. 492 * 493 * @param font An FTGLfont* object. 494 * @param depth The extrusion distance. 495 */ 496 FTGL_EXPORT void ftglSetFontDepth(FTGLfont* font, float depth); 497 498 /** 499 * Set the outset distance for the font. Only FTOutlineFont, FTPolygonFont 500 * and FTExtrudeFont implement front outset. Only FTExtrudeFont implements 501 * back outset. 502 * 503 * @param font An FTGLfont* object. 504 * @param front The front outset distance. 505 * @param back The back outset distance. 506 */ 507 FTGL_EXPORT void ftglSetFontOutset(FTGLfont* font, float front, float back); 508 509 /** 510 * Enable or disable the use of Display Lists inside FTGL. 511 * 512 * @param font An FTGLfont* object. 513 * @param useList 1 turns ON display lists. 514 * 0 turns OFF display lists. 515 */ 516 FTGL_EXPORT void ftglSetFontDisplayList(FTGLfont* font, int useList); 517 518 /** 519 * Get the global ascender height for the face. 520 * 521 * @param font An FTGLfont* object. 522 * @return Ascender height 523 */ 524 FTGL_EXPORT float ftglGetFontAscender(FTGLfont* font); 525 526 /** 527 * Gets the global descender height for the face. 528 * 529 * @param font An FTGLfont* object. 530 * @return Descender height 531 */ 532 FTGL_EXPORT float ftglGetFontDescender(FTGLfont* font); 533 534 /** 535 * Gets the line spacing for the font. 536 * 537 * @param font An FTGLfont* object. 538 * @return Line height 539 */ 540 FTGL_EXPORT float ftglGetFontLineHeight(FTGLfont* font); 541 542 /** 543 * Get the bounding box for a string. 544 * 545 * @param font An FTGLfont* object. 546 * @param string A char buffer 547 * @param len The length of the string. If < 0 then all characters will be 548 * checked until a null character is encountered (optional). 549 * @param bounds An array of 6 float values where the bounding box's lower 550 * left near and upper right far 3D coordinates will be stored. 551 */ 552 FTGL_EXPORT void ftglGetFontBBox(FTGLfont* font, const char *string, 553 int len, float bounds[6]); 554 555 /** 556 * Get the advance width for a string. 557 * 558 * @param font An FTGLfont* object. 559 * @param string A char string. 560 * @return Advance width 561 */ 562 FTGL_EXPORT float ftglGetFontAdvance(FTGLfont* font, const char *string); 563 564 /** 565 * Render a string of characters. 566 * 567 * @param font An FTGLfont* object. 568 * @param string Char string to be output. 569 * @param mode Render mode to display. 570 */ 571 FTGL_EXPORT void ftglRenderFont(FTGLfont* font, const char *string, int mode); 572 573 /** 574 * Query a font for errors. 575 * 576 * @param font An FTGLfont* object. 577 * @return The current error code. 578 */ 579 FTGL_EXPORT FT_Error ftglGetFontError(FTGLfont* font); 580 581 FTGL_END_C_DECLS 582 583 #endif // __FTFont__ 584 585