sdk-world v2026.11.05
PS2 SDK - world tier (copyleft-allowed, non-essential packages)
Loading...
Searching...
No Matches
fterrors.h
Go to the documentation of this file.
1/****************************************************************************
2 *
3 * fterrors.h
4 *
5 * FreeType error code handling (specification).
6 *
7 * Copyright (C) 1996-2025 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 /**************************************************************************
20 *
21 * @section:
22 * error_enumerations
23 *
24 * @title:
25 * Error Enumerations
26 *
27 * @abstract:
28 * How to handle errors and error strings.
29 *
30 * @description:
31 * The header file `fterrors.h` (which is automatically included by
32 * `freetype.h`) defines the handling of FreeType's enumeration
33 * constants. It can also be used to generate error message strings
34 * with a small macro trick explained below.
35 *
36 * **Error Formats**
37 *
38 * The configuration macro `FT_CONFIG_OPTION_USE_MODULE_ERRORS` can be
39 * defined in `ftoption.h` in order to make the higher byte indicate the
40 * module where the error has happened (this is not compatible with
41 * standard builds of FreeType~2, however). See the file `ftmoderr.h`
42 * for more details.
43 *
44 * **Error Message Strings**
45 *
46 * Error definitions are set up with special macros that allow client
47 * applications to build a table of error message strings. The strings
48 * are not included in a normal build of FreeType~2 to save space (most
49 * client applications do not use them).
50 *
51 * To do so, you have to define the following macros before including
52 * this file.
53 *
54 * ```
55 * FT_ERROR_START_LIST
56 * ```
57 *
58 * This macro is called before anything else to define the start of the
59 * error list. It is followed by several `FT_ERROR_DEF` calls.
60 *
61 * ```
62 * FT_ERROR_DEF( e, v, s )
63 * ```
64 *
65 * This macro is called to define one single error. 'e' is the error
66 * code identifier (e.g., `Invalid_Argument`), 'v' is the error's
67 * numerical value, and 's' is the corresponding error string.
68 *
69 * ```
70 * FT_ERROR_END_LIST
71 * ```
72 *
73 * This macro ends the list.
74 *
75 * Additionally, you have to undefine `FTERRORS_H_` before #including
76 * this file.
77 *
78 * Here is a simple example.
79 *
80 * ```
81 * #undef FTERRORS_H_
82 * #define FT_ERRORDEF( e, v, s ) { e, s },
83 * #define FT_ERROR_START_LIST {
84 * #define FT_ERROR_END_LIST { 0, NULL } };
85 *
86 * const struct
87 * {
88 * int err_code;
89 * const char* err_msg;
90 * } ft_errors[] =
91 *
92 * #include <freetype/fterrors.h>
93 * ```
94 *
95 * An alternative to using an array is a switch statement.
96 *
97 * ```
98 * #undef FTERRORS_H_
99 * #define FT_ERROR_START_LIST switch ( error_code ) {
100 * #define FT_ERRORDEF( e, v, s ) case v: return s;
101 * #define FT_ERROR_END_LIST }
102 * ```
103 *
104 * If you use `FT_CONFIG_OPTION_USE_MODULE_ERRORS`, `error_code` should
105 * be replaced with `FT_ERROR_BASE(error_code)` in the last example.
106 */
107
108 /* */
109
110 /* In previous FreeType versions we used `__FTERRORS_H__`. However, */
111 /* using two successive underscores in a non-system symbol name */
112 /* violates the C (and C++) standard, so it was changed to the */
113 /* current form. In spite of this, we have to make */
114 /* */
115 /* ``` */
116 /* #undefine __FTERRORS_H__ */
117 /* ``` */
118 /* */
119 /* work for backward compatibility. */
120 /* */
125#if !( defined( FTERRORS_H_ ) && defined ( __FTERRORS_H__ ) )
126#define FTERRORS_H_
127#define __FTERRORS_H__
128
129
130 /* include module base error codes */
131#include <freetype/ftmoderr.h>
132
133
134 /*******************************************************************/
135 /*******************************************************************/
136 /***** *****/
137 /***** SETUP MACROS *****/
138 /***** *****/
139 /*******************************************************************/
140 /*******************************************************************/
141
142
143#undef FT_NEED_EXTERN_C
144
145
146 /* FT_ERR_PREFIX is used as a prefix for error identifiers. */
147 /* By default, we use `FT_Err_`. */
148 /* */
149#ifndef FT_ERR_PREFIX
150#define FT_ERR_PREFIX FT_Err_
151#endif
152
153
154 /* FT_ERR_BASE is used as the base for module-specific errors. */
155 /* */
156#ifdef FT_CONFIG_OPTION_USE_MODULE_ERRORS
157
158#ifndef FT_ERR_BASE
159#define FT_ERR_BASE FT_Mod_Err_Base
160#endif
161
162#else
163
164#undef FT_ERR_BASE
165#define FT_ERR_BASE 0
166
167#endif /* FT_CONFIG_OPTION_USE_MODULE_ERRORS */
168
169
170 /* If FT_ERRORDEF is not defined, we need to define a simple */
171 /* enumeration type. */
172 /* */
173#ifndef FT_ERRORDEF
174
175#define FT_INCLUDE_ERR_PROTOS
176
177#define FT_ERRORDEF( e, v, s ) e = v,
178#define FT_ERROR_START_LIST enum {
179#define FT_ERROR_END_LIST FT_ERR_CAT( FT_ERR_PREFIX, Max ) };
180
181#ifdef __cplusplus
182#define FT_NEED_EXTERN_C
183 extern "C" {
184#endif
185
186#endif /* !FT_ERRORDEF */
187
188
189 /* this macro is used to define an error */
190#define FT_ERRORDEF_( e, v, s ) \
191 FT_ERRORDEF( FT_ERR_CAT( FT_ERR_PREFIX, e ), v + FT_ERR_BASE, s )
192
193 /* this is only used for <module>_Err_Ok, which must be 0! */
194#define FT_NOERRORDEF_( e, v, s ) \
195 FT_ERRORDEF( FT_ERR_CAT( FT_ERR_PREFIX, e ), v, s )
196
197
198#ifdef FT_ERROR_START_LIST
199 FT_ERROR_START_LIST
200#endif
201
202
203 /* now include the error codes */
204#include <freetype/fterrdef.h>
205
206
207#ifdef FT_ERROR_END_LIST
208 FT_ERROR_END_LIST
209#endif
210
211
212 /*******************************************************************/
213 /*******************************************************************/
214 /***** *****/
215 /***** SIMPLE CLEANUP *****/
216 /***** *****/
217 /*******************************************************************/
218 /*******************************************************************/
219
220#ifdef FT_NEED_EXTERN_C
221 }
222#endif
223
224#undef FT_ERROR_START_LIST
225#undef FT_ERROR_END_LIST
226
227#undef FT_ERRORDEF
228#undef FT_ERRORDEF_
229#undef FT_NOERRORDEF_
230
231#undef FT_NEED_EXTERN_C
232#undef FT_ERR_BASE
233
234 /* FT_ERR_PREFIX is needed internally */
235#ifndef FT2_BUILD_LIBRARY
236#undef FT_ERR_PREFIX
237#endif
238
239 /* FT_INCLUDE_ERR_PROTOS: Control whether function prototypes should be */
240 /* included with */
241 /* */
242 /* #include <freetype/fterrors.h> */
243 /* */
244 /* This is only true where `FT_ERRORDEF` is */
245 /* undefined. */
246 /* */
247 /* FT_ERR_PROTOS_DEFINED: Actual multiple-inclusion protection of */
248 /* `fterrors.h`. */
249#ifdef FT_INCLUDE_ERR_PROTOS
250#undef FT_INCLUDE_ERR_PROTOS
251
252#ifndef FT_ERR_PROTOS_DEFINED
253#define FT_ERR_PROTOS_DEFINED
254
255
256FT_BEGIN_HEADER
257
258 /**************************************************************************
259 *
260 * @function:
261 * FT_Error_String
262 *
263 * @description:
264 * Retrieve the description of a valid FreeType error code.
265 *
266 * @input:
267 * error_code ::
268 * A valid FreeType error code.
269 *
270 * @return:
271 * A C~string or `NULL`, if any error occurred.
272 *
273 * @note:
274 * FreeType has to be compiled with `FT_CONFIG_OPTION_ERROR_STRINGS` or
275 * `FT_DEBUG_LEVEL_ERROR` to get meaningful descriptions.
276 * 'error_string' will be `NULL` otherwise.
277 *
278 * Module identification will be ignored:
279 *
280 * ```c
281 * strcmp( FT_Error_String( FT_Err_Unknown_File_Format ),
282 * FT_Error_String( BDF_Err_Unknown_File_Format ) ) == 0;
283 * ```
284 */
285 FT_EXPORT( const char* )
286 FT_Error_String( FT_Error error_code );
287
288 /* */
289
290FT_END_HEADER
291
292
293#endif /* FT_ERR_PROTOS_DEFINED */
294
295#endif /* FT_INCLUDE_ERR_PROTOS */
296
297#endif /* !(FTERRORS_H_ && __FTERRORS_H__) */
298
299
300/* END */