1 /****************************************************************************
2 *
3 * fttypes.h
4 *
5 * FreeType simple types definitions (specification only).
6 *
7 * Copyright (C) 1996-2019 by
8 * David Turner, Robert Wilhelm, and Werner Lemberg.
9 *
10 * This file is part of the FreeType project, and may only be used,
11 * modified, and distributed under the terms of the FreeType project
12 * license, LICENSE.TXT. By continuing to use, modify, or distribute
13 * this file you indicate that you have read the license and
14 * understand and accept it fully.
15 *
16 */
17
18
19 #ifndef FTTYPES_H_
20 #define FTTYPES_H_
21
22
23 #include <ft2build.h>
24 #include FT_CONFIG_CONFIG_H
25 #include FT_SYSTEM_H
26 #include FT_IMAGE_H
27
28 #include <stddef.h>
29
30
31 FT_BEGIN_HEADER
32
33
34 /**************************************************************************
35 *
36 * @section:
37 * basic_types
38 *
39 * @title:
40 * Basic Data Types
41 *
42 * @abstract:
43 * The basic data types defined by the library.
44 *
45 * @description:
46 * This section contains the basic data types defined by FreeType~2,
47 * ranging from simple scalar types to bitmap descriptors. More
48 * font-specific structures are defined in a different section.
49 *
50 * @order:
51 * FT_Byte
52 * FT_Bytes
53 * FT_Char
54 * FT_Int
55 * FT_UInt
56 * FT_Int16
57 * FT_UInt16
58 * FT_Int32
59 * FT_UInt32
60 * FT_Int64
61 * FT_UInt64
62 * FT_Short
63 * FT_UShort
64 * FT_Long
65 * FT_ULong
66 * FT_Bool
67 * FT_Offset
68 * FT_PtrDist
69 * FT_String
70 * FT_Tag
71 * FT_Error
72 * FT_Fixed
73 * FT_Pointer
74 * FT_Pos
75 * FT_Vector
76 * FT_BBox
77 * FT_Matrix
78 * FT_FWord
79 * FT_UFWord
80 * FT_F2Dot14
81 * FT_UnitVector
82 * FT_F26Dot6
83 * FT_Data
84 *
85 * FT_MAKE_TAG
86 *
87 * FT_Generic
88 * FT_Generic_Finalizer
89 *
90 * FT_Bitmap
91 * FT_Pixel_Mode
92 * FT_Palette_Mode
93 * FT_Glyph_Format
94 * FT_IMAGE_TAG
95 *
96 */
97
98
99 /**************************************************************************
100 *
101 * @type:
102 * FT_Bool
103 *
104 * @description:
105 * A typedef of unsigned char, used for simple booleans. As usual,
106 * values 1 and~0 represent true and false, respectively.
107 */
108 typedef unsigned char FT_Bool;
109
110
111 /**************************************************************************
112 *
113 * @type:
114 * FT_FWord
115 *
116 * @description:
117 * A signed 16-bit integer used to store a distance in original font
118 * units.
119 */
120 typedef signed short FT_FWord; /* distance in FUnits */
121
122
123 /**************************************************************************
124 *
125 * @type:
126 * FT_UFWord
127 *
128 * @description:
129 * An unsigned 16-bit integer used to store a distance in original font
130 * units.
131 */
132 typedef unsigned short FT_UFWord; /* unsigned distance */
133
134
135 /**************************************************************************
136 *
137 * @type:
138 * FT_Char
139 *
140 * @description:
141 * A simple typedef for the _signed_ char type.
142 */
143 typedef signed char FT_Char;
144
145
146 /**************************************************************************
147 *
148 * @type:
149 * FT_Byte
150 *
151 * @description:
152 * A simple typedef for the _unsigned_ char type.
153 */
154 typedef unsigned char FT_Byte;
155
156
157 /**************************************************************************
158 *
159 * @type:
160 * FT_Bytes
161 *
162 * @description:
163 * A typedef for constant memory areas.
164 */
165 typedef const FT_Byte* FT_Bytes;
166
167
168 /**************************************************************************
169 *
170 * @type:
171 * FT_Tag
172 *
173 * @description:
174 * A typedef for 32-bit tags (as used in the SFNT format).
175 */
176 typedef FT_UInt32 FT_Tag;
177
178
179 /**************************************************************************
180 *
181 * @type:
182 * FT_String
183 *
184 * @description:
185 * A simple typedef for the char type, usually used for strings.
186 */
187 typedef char FT_String;
188
189
190 /**************************************************************************
191 *
192 * @type:
193 * FT_Short
194 *
195 * @description:
196 * A typedef for signed short.
197 */
198 typedef signed short FT_Short;
199
200
201 /**************************************************************************
202 *
203 * @type:
204 * FT_UShort
205 *
206 * @description:
207 * A typedef for unsigned short.
208 */
209 typedef unsigned short FT_UShort;
210
211
212 /**************************************************************************
213 *
214 * @type:
215 * FT_Int
216 *
217 * @description:
218 * A typedef for the int type.
219 */
220 typedef signed int FT_Int;
221
222
223 /**************************************************************************
224 *
225 * @type:
226 * FT_UInt
227 *
228 * @description:
229 * A typedef for the unsigned int type.
230 */
231 typedef unsigned int FT_UInt;
232
233
234 /**************************************************************************
235 *
236 * @type:
237 * FT_Long
238 *
239 * @description:
240 * A typedef for signed long.
241 */
242 typedef signed long FT_Long;
243
244
245 /**************************************************************************
246 *
247 * @type:
248 * FT_ULong
249 *
250 * @description:
251 * A typedef for unsigned long.
252 */
253 typedef unsigned long FT_ULong;
254
255
256 /**************************************************************************
257 *
258 * @type:
259 * FT_F2Dot14
260 *
261 * @description:
262 * A signed 2.14 fixed-point type used for unit vectors.
263 */
264 typedef signed short FT_F2Dot14;
265
266
267 /**************************************************************************
268 *
269 * @type:
270 * FT_F26Dot6
271 *
272 * @description:
273 * A signed 26.6 fixed-point type used for vectorial pixel coordinates.
274 */
275 typedef signed long FT_F26Dot6;
276
277
278 /**************************************************************************
279 *
280 * @type:
281 * FT_Fixed
282 *
283 * @description:
284 * This type is used to store 16.16 fixed-point values, like scaling
285 * values or matrix coefficients.
286 */
287 typedef signed long FT_Fixed;
288
289
290 /**************************************************************************
291 *
292 * @type:
293 * FT_Error
294 *
295 * @description:
296 * The FreeType error code type. A value of~0 is always interpreted as a
297 * successful operation.
298 */
299 typedef int FT_Error;
300
301
302 /**************************************************************************
303 *
304 * @type:
305 * FT_Pointer
306 *
307 * @description:
308 * A simple typedef for a typeless pointer.
309 */
310 typedef void* FT_Pointer;
311
312
313 /**************************************************************************
314 *
315 * @type:
316 * FT_Offset
317 *
318 * @description:
319 * This is equivalent to the ANSI~C `size_t` type, i.e., the largest
320 * _unsigned_ integer type used to express a file size or position, or a
321 * memory block size.
322 */
323 typedef size_t FT_Offset;
324
325
326 /**************************************************************************
327 *
328 * @type:
329 * FT_PtrDist
330 *
331 * @description:
332 * This is equivalent to the ANSI~C `ptrdiff_t` type, i.e., the largest
333 * _signed_ integer type used to express the distance between two
334 * pointers.
335 */
336 typedef ft_ptrdiff_t FT_PtrDist;
337
338
339 /**************************************************************************
340 *
341 * @struct:
342 * FT_UnitVector
343 *
344 * @description:
345 * A simple structure used to store a 2D vector unit vector. Uses
346 * FT_F2Dot14 types.
347 *
348 * @fields:
349 * x ::
350 * Horizontal coordinate.
351 *
352 * y ::
353 * Vertical coordinate.
354 */
355 typedef struct FT_UnitVector_
356 {
357 FT_F2Dot14 x;
358 FT_F2Dot14 y;
359
360 } FT_UnitVector;
361
362
363 /**************************************************************************
364 *
365 * @struct:
366 * FT_Matrix
367 *
368 * @description:
369 * A simple structure used to store a 2x2 matrix. Coefficients are in
370 * 16.16 fixed-point format. The computation performed is:
371 *
372 * ```
373 * x' = x*xx + y*xy
374 * y' = x*yx + y*yy
375 * ```
376 *
377 * @fields:
378 * xx ::
379 * Matrix coefficient.
380 *
381 * xy ::
382 * Matrix coefficient.
383 *
384 * yx ::
385 * Matrix coefficient.
386 *
387 * yy ::
388 * Matrix coefficient.
389 */
390 typedef struct FT_Matrix_
391 {
392 FT_Fixed xx, xy;
393 FT_Fixed yx, yy;
394
395 } FT_Matrix;
396
397
398 /**************************************************************************
399 *
400 * @struct:
401 * FT_Data
402 *
403 * @description:
404 * Read-only binary data represented as a pointer and a length.
405 *
406 * @fields:
407 * pointer ::
408 * The data.
409 *
410 * length ::
411 * The length of the data in bytes.
412 */
413 typedef struct FT_Data_
414 {
415 const FT_Byte* pointer;
416 FT_Int length;
417
418 } FT_Data;
419
420
421 /**************************************************************************
422 *
423 * @functype:
424 * FT_Generic_Finalizer
425 *
426 * @description:
427 * Describe a function used to destroy the 'client' data of any FreeType
428 * object. See the description of the @FT_Generic type for details of
429 * usage.
430 *
431 * @input:
432 * The address of the FreeType object that is under finalization. Its
433 * client data is accessed through its `generic` field.
434 */
435 typedef void (*FT_Generic_Finalizer)( void* object );
436
437
438 /**************************************************************************
439 *
440 * @struct:
441 * FT_Generic
442 *
443 * @description:
444 * Client applications often need to associate their own data to a
445 * variety of FreeType core objects. For example, a text layout API
446 * might want to associate a glyph cache to a given size object.
447 *
448 * Some FreeType object contains a `generic` field, of type `FT_Generic`,
449 * which usage is left to client applications and font servers.
450 *
451 * It can be used to store a pointer to client-specific data, as well as
452 * the address of a 'finalizer' function, which will be called by
453 * FreeType when the object is destroyed (for example, the previous
454 * client example would put the address of the glyph cache destructor in
455 * the `finalizer` field).
456 *
457 * @fields:
458 * data ::
459 * A typeless pointer to any client-specified data. This field is
460 * completely ignored by the FreeType library.
461 *
462 * finalizer ::
463 * A pointer to a 'generic finalizer' function, which will be called
464 * when the object is destroyed. If this field is set to `NULL`, no
465 * code will be called.
466 */
467 typedef struct FT_Generic_
468 {
469 void* data;
470 FT_Generic_Finalizer finalizer;
471
472 } FT_Generic;
473
474
475 /**************************************************************************
476 *
477 * @macro:
478 * FT_MAKE_TAG
479 *
480 * @description:
481 * This macro converts four-letter tags that are used to label TrueType
482 * tables into an unsigned long, to be used within FreeType.
483 *
484 * @note:
485 * The produced values **must** be 32-bit integers. Don't redefine this
486 * macro.
487 */
488 #define FT_MAKE_TAG( _x1, _x2, _x3, _x4 ) \
489 (FT_Tag) \
490 ( ( (FT_ULong)_x1 << 24 ) | \
491 ( (FT_ULong)_x2 << 16 ) | \
492 ( (FT_ULong)_x3 << 8 ) | \
493 (FT_ULong)_x4 )
494
495
496 /*************************************************************************/
497 /*************************************************************************/
498 /* */
499 /* L I S T M A N A G E M E N T */
500 /* */
501 /*************************************************************************/
502 /*************************************************************************/
503
504
505 /**************************************************************************
506 *
507 * @section:
508 * list_processing
509 *
510 */
511
512
513 /**************************************************************************
514 *
515 * @type:
516 * FT_ListNode
517 *
518 * @description:
519 * Many elements and objects in FreeType are listed through an @FT_List
520 * record (see @FT_ListRec). As its name suggests, an FT_ListNode is a
521 * handle to a single list element.
522 */
523 typedef struct FT_ListNodeRec_* FT_ListNode;
524
525
526 /**************************************************************************
527 *
528 * @type:
529 * FT_List
530 *
531 * @description:
532 * A handle to a list record (see @FT_ListRec).
533 */
534 typedef struct FT_ListRec_* FT_List;
535
536
537 /**************************************************************************
538 *
539 * @struct:
540 * FT_ListNodeRec
541 *
542 * @description:
543 * A structure used to hold a single list element.
544 *
545 * @fields:
546 * prev ::
547 * The previous element in the list. `NULL` if first.
548 *
549 * next ::
550 * The next element in the list. `NULL` if last.
551 *
552 * data ::
553 * A typeless pointer to the listed object.
554 */
555 typedef struct FT_ListNodeRec_
556 {
557 FT_ListNode prev;
558 FT_ListNode next;
559 void* data;
560
561 } FT_ListNodeRec;
562
563
564 /**************************************************************************
565 *
566 * @struct:
567 * FT_ListRec
568 *
569 * @description:
570 * A structure used to hold a simple doubly-linked list. These are used
571 * in many parts of FreeType.
572 *
573 * @fields:
574 * head ::
575 * The head (first element) of doubly-linked list.
576 *
577 * tail ::
578 * The tail (last element) of doubly-linked list.
579 */
580 typedef struct FT_ListRec_
581 {
582 FT_ListNode head;
583 FT_ListNode tail;
584
585 } FT_ListRec;
586
587 /* */
588
589
590 #define FT_IS_EMPTY( list ) ( (list).head == 0 )
591 #define FT_BOOL( x ) ( (FT_Bool)( (x) != 0 ) )
592
593 /* concatenate C tokens */
594 #define FT_ERR_XCAT( x, y ) x ## y
595 #define FT_ERR_CAT( x, y ) FT_ERR_XCAT( x, y )
596
597 /* see `ftmoderr.h` for descriptions of the following macros */
598
599 #define FT_ERR( e ) FT_ERR_CAT( FT_ERR_PREFIX, e )
600
601 #define FT_ERROR_BASE( x ) ( (x) & 0xFF )
602 #define FT_ERROR_MODULE( x ) ( (x) & 0xFF00U )
603
604 #define FT_ERR_EQ( x, e ) \
605 ( FT_ERROR_BASE( x ) == FT_ERROR_BASE( FT_ERR( e ) ) )
606 #define FT_ERR_NEQ( x, e ) \
607 ( FT_ERROR_BASE( x ) != FT_ERROR_BASE( FT_ERR( e ) ) )
608
609
610 FT_END_HEADER
611
612 #endif /* FTTYPES_H_ */
613
614
615 /* END */