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