lib/freetype/include/freetype/internal/ftobject.h

   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__ */