1 #ifndef __FT_OBJECT_H__ 2 #define __FT_OBJECT_H__ 3 4 #include <ft2build.h> 5 #include FT_FREETYPE_H 6 7 FT_BEGIN_HEADER 8 9 /************************************************************** 10 * 11 * @type: FT_Object 12 * 13 * @description: 14 * handle to a FreeType Object. See @FT_ObjectRec 15 */ 16 typedef struct FT_ObjectRec_* FT_Object; 17 18 19 /************************************************************** 20 * 21 * @type: FT_Class 22 * 23 * @description: 24 * handle to a constant class handle to a FreeType Object. 25 * 26 * Note that a class is itself a @FT_Object and are dynamically 27 * allocated on the heap. 28 * 29 * @also: 30 * @FT_ClassRec, @FT_Object, @FT_ObjectRec, @FT_Type, @FT_TypeRec 31 */ 32 typedef const struct FT_ClassRec_* FT_Class; 33 34 35 /************************************************************** 36 * 37 * @type: FT_Type 38 * 39 * @description: 40 * handle to a constant structure (of type @FT_TypeRec) used 41 * to describe a given @FT_Class type to the FreeType object 42 * sub-system. 43 */ 44 typedef const struct FT_TypeRec_* FT_Type; 45 46 47 48 /************************************************************** 49 * 50 * @struct: FT_ObjectRec 51 * 52 * @description: 53 * a structure describing the root fields of all @FT_Object 54 * class instances in FreeType 55 * 56 * @fields: 57 * clazz :: handle to the object's class 58 * ref_count :: object's reference count. Starts at 1 59 */ 60 typedef struct FT_ObjectRec_ 61 { 62 FT_Class clazz; 63 FT_Int ref_count; 64 65 } FT_ObjectRec; 66 67 68 /************************************************************** 69 * 70 * @macro: FT_OBJECT (x) 71 * 72 * @description: 73 * a useful macro to type-cast anything to a @FT_Object 74 * handle. No check performed.. 75 */ 76 #define FT_OBJECT(x) ((FT_Object)(x)) 77 78 79 /************************************************************** 80 * 81 * @macro: FT_OBJECT_P (x) 82 * 83 * @description: 84 * a useful macro to type-cast anything to a pointer to 85 * @FT_Object handle. 86 */ 87 #define FT_OBJECT_P(x) ((FT_Object*)(x)) 88 89 90 /************************************************************** 91 * 92 * @macro: FT_OBJECT__CLASS (obj) 93 * 94 * @description: 95 * a useful macro to return the class of any object 96 */ 97 #define FT_OBJECT__CLASS(x) FT_OBJECT(x)->clazz 98 99 100 /************************************************************** 101 * 102 * @macro: FT_OBJECT__REF_COUNT (obj) 103 * 104 * @description: 105 * a useful macro to return the reference count of any object 106 */ 107 #define FT_OBJECT__REF_COUNT(x) FT_OBJECT(x)->ref_count 108 109 110 /************************************************************** 111 * 112 * @macro: FT_OBJECT__MEMORY (obj) 113 * 114 * @description: 115 * a useful macro to return a handle to the memory manager 116 * used to allocate a given object 117 */ 118 #define FT_OBJECT__MEMORY(x) FT_CLASS__MEMORY(FT_OBJECT(x)->clazz) 119 120 121 /************************************************************** 122 * 123 * @macro: FT_OBJECT__LIBRARY (obj) 124 * 125 * @description: 126 * a useful macro to return a handle to the library handle 127 * that owns the object 128 */ 129 #define FT_OBJECT__LIBRARY(x) FT_CLASS__LIBRARY(FT_OBJECT(x)->clazz) 130 131 132 /************************************************************** 133 * 134 * @functype: FT_Object_InitFunc 135 * 136 * @description: 137 * a function used to initialize a new object 138 * 139 * @input: 140 * object :: target object handle 141 * init_data :: optional pointer to initialization data 142 * 143 * @return: 144 * error code. 0 means success 145 */ 146 typedef FT_Error (*FT_Object_InitFunc)( FT_Object object, 147 FT_Pointer init_data ); 148 149 /************************************************************** 150 * 151 * @functype: FT_Object_DoneFunc 152 * 153 * @description: 154 * a function used to finalize a given object 155 * 156 * @input: 157 * object :: handle to target object 158 */ 159 typedef void (*FT_Object_DoneFunc)( FT_Object object ); 160 161 162 /************************************************************** 163 * 164 * @struct: FT_ClassRec 165 * 166 * @description: 167 * a structure used to describe a given object class within 168 * FreeType 169 * 170 * @fields: 171 * object :: root @FT_ObjectRec fields, since each class is 172 * itself an object. (it's an instance of the 173 * "metaclass", a special object of the FreeType 174 * object sub-system.) 175 * 176 * magic :: a 32-bit magic number used for decoding 177 * super :: pointer to super class 178 * type :: the @FT_Type descriptor of this class 179 * memory :: the current memory manager handle 180 * library :: the current library handle 181 * info :: an opaque pointer to class-specific information 182 * managed by the FreeType object sub-system 183 * 184 * class_done :: the class destructor function 185 * 186 * obj_size :: size of class instances in bytes 187 * obj_init :: class instance constructor 188 * obj_done :: class instance destructor 189 */ 190 typedef struct FT_ClassRec_ 191 { 192 FT_ObjectRec object; 193 FT_UInt32 magic; 194 FT_Class super; 195 FT_Type type; 196 FT_Memory memory; 197 FT_Library library; 198 FT_Pointer info; 199 200 FT_Object_DoneFunc class_done; 201 202 FT_UInt obj_size; 203 FT_Object_InitFunc obj_init; 204 FT_Object_DoneFunc obj_done; 205 206 } FT_ClassRec; 207 208 209 /************************************************************** 210 * 211 * @macro: FT_CLASS (x) 212 * 213 * @description: 214 * a useful macro to convert anything to a class handle 215 * without checks 216 */ 217 #define FT_CLASS(x) ((FT_Class)(x)) 218 219 220 /************************************************************** 221 * 222 * @macro: FT_CLASS_P (x) 223 * 224 * @description: 225 * a useful macro to convert anything to a pointer to a class 226 * handle without checks 227 */ 228 #define FT_CLASS_P(x) ((FT_Class*)(x)) 229 230 231 /************************************************************** 232 * 233 * @macro: FT_CLASS__MEMORY (clazz) 234 * 235 * @description: 236 * a useful macro to return the memory manager handle of a 237 * given class 238 */ 239 #define FT_CLASS__MEMORY(x) FT_CLASS(x)->memory 240 241 242 /************************************************************** 243 * 244 * @macro: FT_CLASS__LIBRARY (clazz) 245 * 246 * @description: 247 * a useful macro to return the library handle of a 248 * given class 249 */ 250 #define FT_CLASS__LIBRARY(x) FT_CLASS(x)->library 251 252 253 254 /************************************************************** 255 * 256 * @macro: FT_CLASS__TYPE (clazz) 257 * 258 * @description: 259 * a useful macro to return the type of a given class 260 * given class 261 */ 262 #define FT_CLASS__TYPE(x) FT_CLASS(x)->type 263 264 /* */ 265 #define FT_CLASS__INFO(x) FT_CLASS(x)->info 266 #define FT_CLASS__MAGIC(x) FT_CLASS(x)->magic 267 268 269 /************************************************************** 270 * 271 * @struct: FT_TypeRec 272 * 273 * @description: 274 * a structure used to describe a given class to the FreeType 275 * object sub-system. 276 * 277 * @fields: 278 * name :: class name. only used for debugging 279 * super :: type of super-class. NULL if none 280 * 281 * class_size :: size of class structure in bytes 282 * class_init :: class constructor 283 * class_done :: class finalizer 284 * 285 * obj_size :: instance size in bytes 286 * obj_init :: instance constructor. can be NULL 287 * obj_done :: instance destructor. can be NULL 288 * 289 * @note: 290 * if 'obj_init' is NULL, the class will use it's parent 291 * constructor, if any 292 * 293 * if 'obj_done' is NULL, the class will use it's parent 294 * finalizer, if any 295 * 296 * the object sub-system allocates a new class, copies 297 * the content of its super-class into the new structure, 298 * _then_ calls 'clazz_init'. 299 * 300 * 'class_init' and 'class_done' can be NULL, in which case 301 * the parent's class constructor and destructor wil be used 302 */ 303 typedef struct FT_TypeRec_ 304 { 305 const char* name; 306 FT_Type super; 307 308 FT_UInt class_size; 309 FT_Object_InitFunc class_init; 310 FT_Object_DoneFunc class_done; 311 312 FT_UInt obj_size; 313 FT_Object_InitFunc obj_init; 314 FT_Object_DoneFunc obj_done; 315 316 } FT_TypeRec; 317 318 319 /************************************************************** 320 * 321 * @macro: FT_TYPE (x) 322 * 323 * @description: 324 * a useful macro to convert anything to a class type handle 325 * without checks 326 */ 327 #define FT_TYPE(x) ((FT_Type)(x)) 328 329 330 /************************************************************** 331 * 332 * @function: ft_object_check 333 * 334 * @description: 335 * checks that a handle points to a valid @FT_Object 336 * 337 * @input: 338 * obj :: handle/pointer 339 * 340 * @return: 341 * 1 iff the handle points to a valid object. 0 otherwise 342 */ 343 FT_BASE( FT_Int ) 344 ft_object_check( FT_Pointer obj ); 345 346 347 /************************************************************** 348 * 349 * @function: ft_object_is_a 350 * 351 * @description: 352 * checks that a handle points to a valid @FT_Object that 353 * is an instance of a given class (or of any of its sub-classes) 354 * 355 * @input: 356 * obj :: handle/pointer 357 * clazz :: class handle to check 358 * 359 * @return: 360 * 1 iff the handle points to a valid 'clazz' instance. 0 361 * otherwise. 362 */ 363 FT_BASE( FT_Int ) 364 ft_object_is_a( FT_Pointer obj, 365 FT_Class clazz ); 366 367 368 /************************************************************** 369 * 370 * @function: ft_object_create 371 * 372 * @description: 373 * create a new object (class instance) 374 * 375 * @output: 376 * aobject :: new object handle. NULL in case of error 377 * 378 * @input: 379 * clazz :: object's class pointer 380 * init_data :: optional pointer to initialization data 381 * 382 * @return: 383 * error code. 0 means success 384 */ 385 FT_BASE( FT_Error ) 386 ft_object_create( FT_Object *aobject, 387 FT_Class clazz, 388 FT_Pointer init_data ); 389 390 391 /************************************************************** 392 * 393 * @function: ft_object_create_from_type 394 * 395 * @description: 396 * create a new object (class instance) from a @FT_Type 397 * 398 * @output: 399 * aobject :: new object handle. NULL in case of error 400 * 401 * @input: 402 * type :: object's type descriptor 403 * init_data :: optional pointer to initialization data 404 * 405 * @return: 406 * error code. 0 means success 407 * 408 * @note: 409 * this function is slower than @ft_object_create 410 * 411 * this is equivalent to calling @ft_class_from_type followed by 412 * @ft_object_create 413 */ 414 FT_BASE( FT_Error ) 415 ft_object_create_from_type( FT_Object *aobject, 416 FT_Type type, 417 FT_Pointer init_data, 418 FT_Library library ); 419 420 421 422 /************************************************************** 423 * 424 * @macro FT_OBJ_CREATE (object,class,init) 425 * 426 * @description: 427 * a convenient macro used to create new objects. see 428 * @ft_object_create for details 429 */ 430 #define FT_OBJ_CREATE( _obj, _clazz, _init ) \ 431 ft_object_create( FT_OBJECT_P(&(_obj)), _clazz, _init ) 432 433 434 /************************************************************** 435 * 436 * @macro FT_CREATE (object,class,init) 437 * 438 * @description: 439 * a convenient macro used to create new objects. It also 440 * sets an _implicit_ local variable named "error" to the error 441 * code returned by the object constructor. 442 */ 443 #define FT_CREATE( _obj, _clazz, _init ) \ 444 FT_SET_ERROR( FT_OBJ_CREATE( _obj, _clazz, _init ) ) 445 446 /************************************************************** 447 * 448 * @macro FT_OBJ_CREATE_FROM_TYPE (object,type,init) 449 * 450 * @description: 451 * a convenient macro used to create new objects. see 452 * @ft_object_create_from_type for details 453 */ 454 #define FT_OBJ_CREATE_FROM_TYPE( _obj, _type, _init, _lib ) \ 455 ft_object_create_from_type( FT_OBJECT_P(&(_obj)), _type, _init, _lib ) 456 457 458 /************************************************************** 459 * 460 * @macro FT_CREATE_FROM_TYPE (object,type,init) 461 * 462 * @description: 463 * a convenient macro used to create new objects. It also 464 * sets an _implicit_ local variable named "error" to the error 465 * code returned by the object constructor. 466 */ 467 #define FT_CREATE_FROM_TYPE( _obj, _type, _init, _lib ) \ 468 FT_SET_ERROR( FT_OBJ_CREATE_FROM_TYPE( _obj, _type, _init, _lib ) ) 469 470 471 /* */ 472 473 /************************************************************** 474 * 475 * @function: ft_class_from_type 476 * 477 * @description: 478 * retrieves the class object corresponding to a given type 479 * descriptor. The class is created when needed 480 * 481 * @output: 482 * aclass :: handle to corresponding class object. NULL in 483 * case of error 484 * 485 * @input: 486 * type :: type descriptor handle 487 * library :: library handle 488 * 489 * @return: 490 * error code. 0 means success 491 */ 492 FT_BASE( FT_Error ) 493 ft_class_from_type( FT_Class *aclass, 494 FT_Type type, 495 FT_Library library ); 496 497 498 /* */ 499 500 #include FT_INTERNAL_HASH_H 501 502 typedef struct FT_ClassHNodeRec_* FT_ClassHNode; 503 504 typedef struct FT_ClassHNodeRec_ 505 { 506 FT_HashNodeRec hnode; 507 FT_Type type; 508 FT_Class clazz; 509 510 } FT_ClassHNodeRec; 511 512 typedef struct FT_MetaClassRec_ 513 { 514 FT_ClassRec clazz; /* the meta-class is a class itself */ 515 FT_HashRec type_to_class; /* the type => class hash table */ 516 517 } FT_MetaClassRec, *FT_MetaClass; 518 519 520 /* initialize meta class */ 521 FT_BASE( FT_Error ) 522 ft_metaclass_init( FT_MetaClass meta, 523 FT_Library library ); 524 525 /* finalize meta class - destroy all registered class objects */ 526 FT_BASE( void ) 527 ft_metaclass_done( FT_MetaClass meta ); 528 529 /* */ 530 531 FT_END_HEADER 532 533 #endif /* __FT_OBJECT_H__ */ 534