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