include/ftbdf.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftbdf.h                                                                */
   4 /*                                                                         */
   5 /*    FreeType API for accessing BDF-specific strings (specification).     */
   6 /*                                                                         */
   7 /*  Copyright 2002-2004, 2006, 2009, 2014 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 */
  48   /*    and 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
  91    *    BDF/PCF 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
 138   *    the BDF 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 :: A handle to the input face.
 173   *
 174   *    name :: The property name.
 175   *
 176   * @output:
 177   *    aproperty :: The property.
 178   *
 179   * @return:
 180   *   FreeType error code.  0~means success.
 181   *
 182   * @note:
 183   *   This function works with BDF _and_ PCF fonts.  It returns an error
 184   *   otherwise.  It also returns an error if the property is not in the
 185   *   font.
 186   *
 187   *   A `property' is a either key-value pair within the STARTPROPERTIES
 188   *   ... ENDPROPERTIES block of a BDF font or a key-value pair from the
 189   *   `info->props' array within a `FontRec' structure of a PCF font.
 190   *
 191   *   Integer properties are always stored as `signed' within PCF fonts;
 192   *   consequently, @BDF_PROPERTY_TYPE_CARDINAL is a possible return value
 193   *   for BDF fonts only.
 194   *
 195   *   In case of error, `aproperty->type' is always set to
 196   *   @BDF_PROPERTY_TYPE_NONE.
 197   */
 198   FT_EXPORT( FT_Error )
 199   FT_Get_BDF_Property( FT_Face           face,
 200                        const char*       prop_name,
 201                        BDF_PropertyRec  *aproperty );
 202
 203   /* */
 204
 205 FT_END_HEADER
 206
 207 #endif /* __FTBDF_H__ */
 208
 209
 210 /* END */