freetype2/freetype/ftbdf.h

0001 /****************************************************************************
0002  *
0003  * ftbdf.h
0004  *
0005  *   FreeType API for accessing BDF-specific strings (specification).
0006  *
0007  * Copyright (C) 2002-2023 by
0008  * David Turner, Robert Wilhelm, and Werner Lemberg.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017
0018
0019 #ifndef FTBDF_H_
0020 #define FTBDF_H_
0021
0022 #include <freetype/freetype.h>
0023
0024 #ifdef FREETYPE_H
0025 #error "freetype.h of FreeType 1 has been loaded!"
0026 #error "Please fix the directory search order for header files"
0027 #error "so that freetype.h of FreeType 2 is found first."
0028 #endif
0029
0030
0031 FT_BEGIN_HEADER
0032
0033
0034   /**************************************************************************
0035    *
0036    * @section:
0037    *   bdf_fonts
0038    *
0039    * @title:
0040    *   BDF and PCF Files
0041    *
0042    * @abstract:
0043    *   BDF and PCF specific API.
0044    *
0045    * @description:
0046    *   This section contains the declaration of functions specific to BDF and
0047    *   PCF fonts.
0048    *
0049    */
0050
0051
0052   /**************************************************************************
0053    *
0054    * @enum:
0055    *    BDF_PropertyType
0056    *
0057    * @description:
0058    *    A list of BDF property types.
0059    *
0060    * @values:
0061    *    BDF_PROPERTY_TYPE_NONE ::
0062    *      Value~0 is used to indicate a missing property.
0063    *
0064    *    BDF_PROPERTY_TYPE_ATOM ::
0065    *      Property is a string atom.
0066    *
0067    *    BDF_PROPERTY_TYPE_INTEGER ::
0068    *      Property is a 32-bit signed integer.
0069    *
0070    *    BDF_PROPERTY_TYPE_CARDINAL ::
0071    *      Property is a 32-bit unsigned integer.
0072    */
0073   typedef enum  BDF_PropertyType_
0074   {
0075     BDF_PROPERTY_TYPE_NONE     = 0,
0076     BDF_PROPERTY_TYPE_ATOM     = 1,
0077     BDF_PROPERTY_TYPE_INTEGER  = 2,
0078     BDF_PROPERTY_TYPE_CARDINAL = 3
0079
0080   } BDF_PropertyType;
0081
0082
0083   /**************************************************************************
0084    *
0085    * @type:
0086    *    BDF_Property
0087    *
0088    * @description:
0089    *    A handle to a @BDF_PropertyRec structure to model a given BDF/PCF
0090    *    property.
0091    */
0092   typedef struct BDF_PropertyRec_*  BDF_Property;
0093
0094
0095   /**************************************************************************
0096    *
0097    * @struct:
0098    *    BDF_PropertyRec
0099    *
0100    * @description:
0101    *    This structure models a given BDF/PCF property.
0102    *
0103    * @fields:
0104    *    type ::
0105    *      The property type.
0106    *
0107    *    u.atom ::
0108    *      The atom string, if type is @BDF_PROPERTY_TYPE_ATOM.  May be
0109    *      `NULL`, indicating an empty string.
0110    *
0111    *    u.integer ::
0112    *      A signed integer, if type is @BDF_PROPERTY_TYPE_INTEGER.
0113    *
0114    *    u.cardinal ::
0115    *      An unsigned integer, if type is @BDF_PROPERTY_TYPE_CARDINAL.
0116    */
0117   typedef struct  BDF_PropertyRec_
0118   {
0119     BDF_PropertyType  type;
0120     union {
0121       const char*     atom;
0122       FT_Int32        integer;
0123       FT_UInt32       cardinal;
0124
0125     } u;
0126
0127   } BDF_PropertyRec;
0128
0129
0130   /**************************************************************************
0131    *
0132    * @function:
0133    *    FT_Get_BDF_Charset_ID
0134    *
0135    * @description:
0136    *    Retrieve a BDF font character set identity, according to the BDF
0137    *    specification.
0138    *
0139    * @input:
0140    *    face ::
0141    *      A handle to the input face.
0142    *
0143    * @output:
0144    *    acharset_encoding ::
0145    *      Charset encoding, as a C~string, owned by the face.
0146    *
0147    *    acharset_registry ::
0148    *      Charset registry, as a C~string, owned by the face.
0149    *
0150    * @return:
0151    *   FreeType error code.  0~means success.
0152    *
0153    * @note:
0154    *   This function only works with BDF faces, returning an error otherwise.
0155    */
0156   FT_EXPORT( FT_Error )
0157   FT_Get_BDF_Charset_ID( FT_Face       face,
0158                          const char*  *acharset_encoding,
0159                          const char*  *acharset_registry );
0160
0161
0162   /**************************************************************************
0163    *
0164    * @function:
0165    *    FT_Get_BDF_Property
0166    *
0167    * @description:
0168    *    Retrieve a BDF property from a BDF or PCF font file.
0169    *
0170    * @input:
0171    *    face ::
0172    *      A handle to the input face.
0173    *
0174    *    name ::
0175    *      The property name.
0176    *
0177    * @output:
0178    *    aproperty ::
0179    *      The property.
0180    *
0181    * @return:
0182    *   FreeType error code.  0~means success.
0183    *
0184    * @note:
0185    *   This function works with BDF _and_ PCF fonts.  It returns an error
0186    *   otherwise.  It also returns an error if the property is not in the
0187    *   font.
0188    *
0189    *   A 'property' is a either key-value pair within the STARTPROPERTIES
0190    *   ... ENDPROPERTIES block of a BDF font or a key-value pair from the
0191    *   `info->props` array within a `FontRec` structure of a PCF font.
0192    *
0193    *   Integer properties are always stored as 'signed' within PCF fonts;
0194    *   consequently, @BDF_PROPERTY_TYPE_CARDINAL is a possible return value
0195    *   for BDF fonts only.
0196    *
0197    *   In case of error, `aproperty->type` is always set to
0198    *   @BDF_PROPERTY_TYPE_NONE.
0199    */
0200   FT_EXPORT( FT_Error )
0201   FT_Get_BDF_Property( FT_Face           face,
0202                        const char*       prop_name,
0203                        BDF_PropertyRec  *aproperty );
0204
0205   /* */
0206
0207 FT_END_HEADER
0208
0209 #endif /* FTBDF_H_ */
0210
0211
0212 /* END */