2
* FTGL - OpenGL font library
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>
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:
16
* The above copyright notice and this permission notice shall be
17
* included in all copies or substantial portions of the Software.
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.
29
# warning This header is deprecated. Please use <FTGL/ftgl.h> from now.
30
# include <FTGL/ftgl.h>
41
* FTFont is the public interface for the FTGL library.
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
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.
56
class FTGL_EXPORT FTFont
60
* Open and read a font file. Sets Error flag.
62
* @param fontFilePath font file path.
64
FTFont(char const *fontFilePath);
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.
71
* @param pBufferBytes the in-memory buffer
72
* @param bufferSizeInBytes the length of the buffer in bytes
74
FTFont(const unsigned char *pBufferBytes, size_t bufferSizeInBytes);
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;
87
* Internal FTGL FTFont constructor. For private use only.
89
* @param pImpl Internal implementation object. Will be destroyed
90
* upon FTFont deletion.
92
FTFont(FTFontImpl *pImpl);
98
* Attach auxilliary file to font e.g font metrics.
100
* Note: not all font formats implement this function.
102
* @param fontFilePath auxilliary font file path.
103
* @return <code>true</code> if file has been attached
106
virtual bool Attach(const char* fontFilePath);
109
* Attach auxilliary data to font e.g font metrics, from memory.
111
* Note: not all font formats implement this function.
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
118
virtual bool Attach(const unsigned char *pBufferBytes,
119
size_t bufferSizeInBytes);
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.
126
* @param flags The glyph loading flags.
128
virtual void GlyphLoadFlags(FT_Int flags);
131
* Set the character map for the face.
133
* @param encoding Freetype enumerate for char map code.
134
* @return <code>true</code> if charmap was valid and
137
virtual bool CharMap(FT_Encoding encoding);
140
* Get the number of character maps in this face.
142
* @return character map count.
144
virtual unsigned int CharMapCount() const;
147
* Get a list of character maps in this face.
149
* @return pointer to the first encoding.
151
virtual FT_Encoding* CharMapList();
154
* Set the char size for the current face.
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
160
virtual bool FaceSize(const unsigned int size,
161
const unsigned int res = 72);
164
* Get the current face size in points (1/72 inch).
168
virtual unsigned int FaceSize() const;
171
* Set the extrusion distance for the font. Only implemented by
174
* @param depth The extrusion distance.
176
virtual void Depth(float depth);
179
* Set the outset distance for the font. Only implemented by
180
* FTOutlineFont, FTPolygonFont and FTExtrudeFont
182
* @param outset The outset distance.
184
virtual void Outset(float outset);
187
* Set the front and back outset distances for the font. Only
188
* implemented by FTExtrudeFont
190
* @param front The front outset distance.
191
* @param back The back outset distance.
193
virtual void Outset(float front, float back);
196
* Enable or disable the use of Display Lists inside FTGL
198
* @param useList <code>true</code> turns ON display lists.
199
* <code>false</code> turns OFF display lists.
201
virtual void UseDisplayList(bool useList);
204
* Get the global ascender height for the face.
206
* @return Ascender height
208
virtual float Ascender() const;
211
* Gets the global descender height for the face.
213
* @return Descender height
215
virtual float Descender() const;
218
* Gets the line spacing for the font.
220
* @return Line height
222
virtual float LineHeight() const;
225
* Get the bounding box for a string.
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
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.
236
virtual FTBBox BBox(const char *string, const int len = -1,
237
FTPoint position = FTPoint(),
238
FTPoint spacing = FTPoint());
241
* Get the bounding box for a string (deprecated).
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.
251
void BBox(const char* string, float& llx, float& lly, float& llz,
252
float& urx, float& ury, float& urz)
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();
260
* Get the bounding box for a string.
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
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.
271
virtual FTBBox BBox(const wchar_t *string, const int len = -1,
272
FTPoint position = FTPoint(),
273
FTPoint spacing = FTPoint());
276
* Get the bounding box for a string (deprecated).
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.
286
void BBox(const wchar_t* string, float& llx, float& lly, float& llz,
287
float& urx, float& ury, float& urz)
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();
295
* Get the advance for a string.
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
301
* @param spacing A displacement vector to add after each character
302
* has been checked (optional).
303
* @return The string's advance width.
305
virtual float Advance(const char* string, const int len = -1,
306
FTPoint spacing = FTPoint());
309
* Get the advance for a string.
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
315
* @param spacing A displacement vector to add after each character
316
* has been checked (optional).
317
* @return The string's advance width.
319
virtual float Advance(const wchar_t* string, const int len = -1,
320
FTPoint spacing = FTPoint());
323
* Render a string of characters.
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
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.
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);
341
* Render a string of characters
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
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.
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);
359
virtual void PreRender();
362
virtual void PostRender();
366
* Queries the Font for errors.
368
* @return The current error code.
370
virtual FT_Error Error() const;
373
/* Allow impl to access MakeGlyph */
374
friend class FTFontImpl;
377
* Construct a glyph of the correct type.
379
* Clients must override the function and return their specialised
382
* @param slot A FreeType glyph slot.
383
* @return An FT****Glyph or <code>null</code> on failure.
385
virtual FTGlyph* MakeGlyph(FT_GlyphSlot slot) = 0;
389
* Internal FTGL FTFont implementation object. For private use only.
399
* FTGLfont is the public interface for the FTGL library.
401
* It is good practice after using these functions to test the error
402
* code returned. <code>FT_Error Error()</code>. Check the freetype file
403
* fterrdef.h for error definitions.
406
typedef struct _FTGLfont FTGLfont;
409
* Create a custom FTGL font object.
411
* @param fontFilePath The font file name.
412
* @param data A pointer to private data that will be passed to callbacks.
413
* @param makeglyphCallback A glyph-making callback function.
414
* @return An FTGLfont* object.
416
FTGL_EXPORT FTGLfont *ftglCreateCustomFont(char const *fontFilePath,
418
FTGLglyph * (*makeglyphCallback) (FT_GlyphSlot, void *));
421
* Destroy an FTGL font object.
423
* @param font An FTGLfont* object.
425
FTGL_EXPORT void ftglDestroyFont(FTGLfont* font);
428
* Attach auxilliary file to font e.g. font metrics.
430
* Note: not all font formats implement this function.
432
* @param font An FTGLfont* object.
433
* @param path Auxilliary font file path.
434
* @return 1 if file has been attached successfully.
436
FTGL_EXPORT int ftglAttachFile(FTGLfont* font, const char* path);
439
* Attach auxilliary data to font, e.g. font metrics, from memory.
441
* Note: not all font formats implement this function.
443
* @param font An FTGLfont* object.
444
* @param data The in-memory buffer.
445
* @param size The length of the buffer in bytes.
446
* @return 1 if file has been attached successfully.
448
FTGL_EXPORT int ftglAttachData(FTGLfont* font, const unsigned char * data,
452
* Set the character map for the face.
454
* @param font An FTGLfont* object.
455
* @param encoding Freetype enumerate for char map code.
456
* @return 1 if charmap was valid and set correctly.
458
FTGL_EXPORT int ftglSetFontCharMap(FTGLfont* font, FT_Encoding encoding);
461
* Get the number of character maps in this face.
463
* @param font An FTGLfont* object.
464
* @return character map count.
466
FTGL_EXPORT unsigned int ftglGetFontCharMapCount(FTGLfont* font);
469
* Get a list of character maps in this face.
471
* @param font An FTGLfont* object.
472
* @return pointer to the first encoding.
474
FTGL_EXPORT FT_Encoding* ftglGetFontCharMapList(FTGLfont* font);
477
* Set the char size for the current face.
479
* @param font An FTGLfont* object.
480
* @param size The face size in points (1/72 inch).
481
* @param res The resolution of the target device, or 0 to use the default
483
* @return 1 if size was set correctly.
485
FTGL_EXPORT int ftglSetFontFaceSize(FTGLfont* font, unsigned int size,
489
* Get the current face size in points (1/72 inch).
491
* @param font An FTGLfont* object.
494
FTGL_EXPORT unsigned int ftglGetFontFaceSize(FTGLfont* font);
497
* Set the extrusion distance for the font. Only implemented by
500
* @param font An FTGLfont* object.
501
* @param depth The extrusion distance.
503
FTGL_EXPORT void ftglSetFontDepth(FTGLfont* font, float depth);
506
* Set the outset distance for the font. Only FTOutlineFont, FTPolygonFont
507
* and FTExtrudeFont implement front outset. Only FTExtrudeFont implements
510
* @param font An FTGLfont* object.
511
* @param front The front outset distance.
512
* @param back The back outset distance.
514
FTGL_EXPORT void ftglSetFontOutset(FTGLfont* font, float front, float back);
517
* Enable or disable the use of Display Lists inside FTGL.
519
* @param font An FTGLfont* object.
520
* @param useList 1 turns ON display lists.
521
* 0 turns OFF display lists.
523
FTGL_EXPORT void ftglSetFontDisplayList(FTGLfont* font, int useList);
526
* Get the global ascender height for the face.
528
* @param font An FTGLfont* object.
529
* @return Ascender height
531
FTGL_EXPORT float ftglGetFontAscender(FTGLfont* font);
534
* Gets the global descender height for the face.
536
* @param font An FTGLfont* object.
537
* @return Descender height
539
FTGL_EXPORT float ftglGetFontDescender(FTGLfont* font);
542
* Gets the line spacing for the font.
544
* @param font An FTGLfont* object.
545
* @return Line height
547
FTGL_EXPORT float ftglGetFontLineHeight(FTGLfont* font);
550
* Get the bounding box for a string.
552
* @param font An FTGLfont* object.
553
* @param string A char buffer
554
* @param len The length of the string. If < 0 then all characters will be
555
* checked until a null character is encountered (optional).
556
* @param bounds An array of 6 float values where the bounding box's lower
557
* left near and upper right far 3D coordinates will be stored.
559
FTGL_EXPORT void ftglGetFontBBox(FTGLfont* font, const char *string,
560
int len, float bounds[6]);
563
* Get the advance width for a string.
565
* @param font An FTGLfont* object.
566
* @param string A char string.
567
* @return Advance width
569
FTGL_EXPORT float ftglGetFontAdvance(FTGLfont* font, const char *string);
572
* Render a string of characters.
574
* @param font An FTGLfont* object.
575
* @param string Char string to be output.
576
* @param mode Render mode to display.
578
FTGL_EXPORT void ftglRenderFont(FTGLfont* font, const char *string, int mode);
581
* Query a font for errors.
583
* @param font An FTGLfont* object.
584
* @return The current error code.
586
FTGL_EXPORT FT_Error ftglGetFontError(FTGLfont* font);
added
removed
PsychSourceGL/Cohorts/FTGLTextRenderer/FTGL/FTFont.h
