1 /****************************************************************************
   2  *
   3  * ftbdf.h
   4  *
   5  *   FreeType API for accessing BDF-specific strings (specification).
   6  *
   7  * Copyright (C) 2002-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 FTBDF_H_
  20 #define FTBDF_H_
  21 
  22 #include <ft2build.h>
  23 #include FT_FREETYPE_H
  24 
  25 #ifdef FREETYPE_H
  26 #error "freetype.h of FreeType 1 has been loaded!"
  27 #error "Please fix the directory search order for header files"
  28 #error "so that freetype.h of FreeType 2 is found first."
  29 #endif
  30 
  31 
  32 FT_BEGIN_HEADER
  33 
  34 
  35   /**************************************************************************
  36    *
  37    * @section:
  38    *   bdf_fonts
  39    *
  40    * @title:
  41    *   BDF and PCF Files
  42    *
  43    * @abstract:
  44    *   BDF and PCF specific API.
  45    *
  46    * @description:
  47    *   This section contains the declaration of functions specific to BDF and
  48    *   PCF fonts.
  49    *
  50    */
  51 
  52 
  53   /**************************************************************************
  54    *
  55    * @enum:
  56    *    BDF_PropertyType
  57    *
  58    * @description:
  59    *    A list of BDF property types.
  60    *
  61    * @values:
  62    *    BDF_PROPERTY_TYPE_NONE ::
  63    *      Value~0 is used to indicate a missing property.
  64    *
  65    *    BDF_PROPERTY_TYPE_ATOM ::
  66    *      Property is a string atom.
  67    *
  68    *    BDF_PROPERTY_TYPE_INTEGER ::
  69    *      Property is a 32-bit signed integer.
  70    *
  71    *    BDF_PROPERTY_TYPE_CARDINAL ::
  72    *      Property is a 32-bit unsigned integer.
  73    */
  74   typedef enum  BDF_PropertyType_
  75   {
  76     BDF_PROPERTY_TYPE_NONE     = 0,
  77     BDF_PROPERTY_TYPE_ATOM     = 1,
  78     BDF_PROPERTY_TYPE_INTEGER  = 2,
  79     BDF_PROPERTY_TYPE_CARDINAL = 3
  80 
  81   } BDF_PropertyType;
  82 
  83 
  84   /**************************************************************************
  85    *
  86    * @type:
  87    *    BDF_Property
  88    *
  89    * @description:
  90    *    A handle to a @BDF_PropertyRec structure to model a given BDF/PCF
  91    *    property.
  92    */
  93   typedef struct BDF_PropertyRec_*  BDF_Property;
  94 
  95 
  96   /**************************************************************************
  97    *
  98    * @struct:
  99    *    BDF_PropertyRec
 100    *
 101    * @description:
 102    *    This structure models a given BDF/PCF property.
 103    *
 104    * @fields:
 105    *    type ::
 106    *      The property type.
 107    *
 108    *    u.atom ::
 109    *      The atom string, if type is @BDF_PROPERTY_TYPE_ATOM.  May be
 110    *      `NULL`, indicating an empty string.
 111    *
 112    *    u.integer ::
 113    *      A signed integer, if type is @BDF_PROPERTY_TYPE_INTEGER.
 114    *
 115    *    u.cardinal ::
 116    *      An unsigned integer, if type is @BDF_PROPERTY_TYPE_CARDINAL.
 117    */
 118   typedef struct  BDF_PropertyRec_
 119   {
 120     BDF_PropertyType  type;
 121     union {
 122       const char*     atom;
 123       FT_Int32        integer;
 124       FT_UInt32       cardinal;
 125 
 126     } u;
 127 
 128   } BDF_PropertyRec;
 129 
 130 
 131   /**************************************************************************
 132    *
 133    * @function:
 134    *    FT_Get_BDF_Charset_ID
 135    *
 136    * @description:
 137    *    Retrieve a BDF font character set identity, according to the BDF
 138    *    specification.
 139    *
 140    * @input:
 141    *    face ::
 142    *      A handle to the input face.
 143    *
 144    * @output:
 145    *    acharset_encoding ::
 146    *      Charset encoding, as a C~string, owned by the face.
 147    *
 148    *    acharset_registry ::
 149    *      Charset registry, as a C~string, owned by the face.
 150    *
 151    * @return:
 152    *   FreeType error code.  0~means success.
 153    *
 154    * @note:
 155    *   This function only works with BDF faces, returning an error otherwise.
 156    */
 157   FT_EXPORT( FT_Error )
 158   FT_Get_BDF_Charset_ID( FT_Face       face,
 159                          const char*  *acharset_encoding,
 160                          const char*  *acharset_registry );
 161 
 162 
 163   /**************************************************************************
 164    *
 165    * @function:
 166    *    FT_Get_BDF_Property
 167    *
 168    * @description:
 169    *    Retrieve a BDF property from a BDF or PCF font file.
 170    *
 171    * @input:
 172    *    face ::
 173    *      A handle to the input face.
 174    *
 175    *    name ::
 176    *      The property name.
 177    *
 178    * @output:
 179    *    aproperty ::
 180    *      The property.
 181    *
 182    * @return:
 183    *   FreeType error code.  0~means success.
 184    *
 185    * @note:
 186    *   This function works with BDF _and_ PCF fonts.  It returns an error
 187    *   otherwise.  It also returns an error if the property is not in the
 188    *   font.
 189    *
 190    *   A 'property' is a either key-value pair within the STARTPROPERTIES
 191    *   ... ENDPROPERTIES block of a BDF font or a key-value pair from the
 192    *   `info->props` array within a `FontRec` structure of a PCF font.
 193    *
 194    *   Integer properties are always stored as 'signed' within PCF fonts;
 195    *   consequently, @BDF_PROPERTY_TYPE_CARDINAL is a possible return value
 196    *   for BDF fonts only.
 197    *
 198    *   In case of error, `aproperty->type` is always set to
 199    *   @BDF_PROPERTY_TYPE_NONE.
 200    */
 201   FT_EXPORT( FT_Error )
 202   FT_Get_BDF_Property( FT_Face           face,
 203                        const char*       prop_name,
 204                        BDF_PropertyRec  *aproperty );
 205 
 206   /* */
 207 
 208 FT_END_HEADER
 209 
 210 #endif /* FTBDF_H_ */
 211 
 212 
 213 /* END */