lib/freetype/include/freetype/fterrors.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  fterrors.h                                                             */
   4 /*                                                                         */
   5 /*    FreeType error code handling (specification).                        */
   6 /*                                                                         */
   7 /*  Copyright 1996-2001, 2002 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   /* This special header file is used to define the handling of FT2        */
  22   /* enumeration constants.  It can also be used to generate error message */
  23   /* strings with a small macro trick explained below.                     */
  24   /*                                                                       */
  25   /* I - Error Formats                                                     */
  26   /* -----------------                                                     */
  27   /*                                                                       */
  28   /*   Since release 2.1, the error constants have changed.  The lower     */
  29   /*   byte of the error value gives the "generic" error code, while the   */
  30   /*   higher byte indicates in which module the error occurred.           */
  31   /*                                                                       */
  32   /*   You can use the macro FT_ERROR_BASE(x) macro to extract the generic */
  33   /*   error code from an FT_Error value.                                  */
  34   /*                                                                       */
  35   /*   The configuration macro FT_CONFIG_OPTION_USE_MODULE_ERRORS can be   */
  36   /*   undefined in ftoption.h in order to make the higher byte always     */
  37   /*   zero, in case you need to be compatible with previous versions of   */
  38   /*   FreeType 2.                                                         */
  39   /*                                                                       */
  40   /*                                                                       */
  41   /* II - Error Message strings                                            */
  42   /* --------------------------                                            */
  43   /*                                                                       */
  44   /*   The error definitions below are made through special macros that    */
  45   /*   allow client applications to build a table of error message strings */
  46   /*   if they need it.  The strings are not included in a normal build of */
  47   /*   FreeType 2 to save space (most client applications do not use       */
  48   /*   them).                                                              */
  49   /*                                                                       */
  50   /*   To do so, you have to define the following macros before including  */
  51   /*   this file:                                                          */
  52   /*                                                                       */
  53   /*   FT_ERROR_START_LIST ::                                              */
  54   /*     This macro is called before anything else to define the start of  */
  55   /*     the error list.  It is followed by several FT_ERROR_DEF calls     */
  56   /*     (see below).                                                      */
  57   /*                                                                       */
  58   /*   FT_ERROR_DEF( e, v, s ) ::                                          */
  59   /*     This macro is called to define one single error.                  */
  60   /*     `e' is the error code identifier (e.g. FT_Err_Invalid_Argument).  */
  61   /*     `v' is the error numerical value.                                 */
  62   /*     `s' is the corresponding error string.                            */
  63   /*                                                                       */
  64   /*   FT_ERROR_END_LIST ::                                                */
  65   /*     This macro ends the list.                                         */
  66   /*                                                                       */
  67   /*   Additionally, you have to undefine __FTERRORS_H__ before #including */
  68   /*   this file.                                                          */
  69   /*                                                                       */
  70   /*   Here is a simple example:                                           */
  71   /*                                                                       */
  72   /*     {                                                                 */
  73   /*       #undef __FTERRORS_H__                                           */
  74   /*       #define FT_ERRORDEF( e, v, s )  { e, s },                       */
  75   /*       #define FT_ERROR_START_LIST     {                               */
  76   /*       #define FT_ERROR_END_LIST       { 0, 0 } };                     */
  77   /*                                                                       */
  78   /*       const struct                                                    */
  79   /*       {                                                               */
  80   /*         int          err_code;                                        */
  81   /*         const char*  err_msg                                          */
  82   /*       } ft_errors[] =                                                 */
  83   /*                                                                       */
  84   /*       #include FT_ERRORS_H                                            */
  85   /*     }                                                                 */
  86   /*                                                                       */
  87   /*************************************************************************/
  88
  89
  90 #ifndef __FTERRORS_H__
  91 #define __FTERRORS_H__
  92
  93
  94   /* include module base error codes */
  95 #include FT_MODULE_ERRORS_H
  96
  97
  98   /*******************************************************************/
  99   /*******************************************************************/
 100   /*****                                                         *****/
 101   /*****                       SETUP MACROS                      *****/
 102   /*****                                                         *****/
 103   /*******************************************************************/
 104   /*******************************************************************/
 105
 106
 107 #undef  FT_NEED_EXTERN_C
 108
 109 #undef  FT_ERR_XCAT
 110 #undef  FT_ERR_CAT
 111
 112 #define FT_ERR_XCAT( x, y )  x ## y
 113 #define FT_ERR_CAT( x, y )   FT_ERR_XCAT( x, y )
 114
 115
 116   /* FT_ERR_PREFIX is used as a prefix for error identifiers. */
 117   /* By default, we use `FT_Err_'.                            */
 118   /*                                                          */
 119 #ifndef FT_ERR_PREFIX
 120 #define FT_ERR_PREFIX  FT_Err_
 121 #endif
 122
 123
 124   /* FT_ERR_BASE is used as the base for module-specific errors. */
 125   /*                                                             */
 126 #ifdef FT_CONFIG_OPTION_USE_MODULE_ERRORS
 127
 128 #ifndef FT_ERR_BASE
 129 #define FT_ERR_BASE  FT_Mod_Err_Base
 130 #endif
 131
 132 #else
 133
 134 #undef FT_ERR_BASE
 135 #define FT_ERR_BASE  0
 136
 137 #endif /* FT_CONFIG_OPTION_USE_MODULE_ERRORS */
 138
 139
 140   /* If FT_ERRORDEF is not defined, we need to define a simple */
 141   /* enumeration type.                                         */
 142   /*                                                           */
 143 #ifndef FT_ERRORDEF
 144
 145 #define FT_ERRORDEF( e, v, s )  e = v,
 146 #define FT_ERROR_START_LIST     enum {
 147 #define FT_ERROR_END_LIST       FT_ERR_CAT( FT_ERR_PREFIX, Max ) };
 148
 149 #ifdef __cplusplus
 150 #define FT_NEED_EXTERN_C
 151   extern "C" {
 152 #endif
 153
 154 #endif /* !FT_ERRORDEF */
 155
 156
 157   /* this macro is used to define an error */
 158 #define FT_ERRORDEF_( e, v, s )   \
 159           FT_ERRORDEF( FT_ERR_CAT( FT_ERR_PREFIX, e ), v + FT_ERR_BASE, s )
 160
 161   /* this is only used for FT_Err_Ok, which must be 0! */
 162 #define FT_NOERRORDEF_( e, v, s ) \
 163           FT_ERRORDEF( FT_ERR_CAT( FT_ERR_PREFIX, e ), v, s )
 164
 165
 166 #ifdef FT_ERROR_START_LIST
 167   FT_ERROR_START_LIST
 168 #endif
 169
 170
 171   /* no include the error codes */
 172 #include FT_ERROR_DEFINITIONS_H
 173
 174
 175 #ifdef FT_ERROR_END_LIST
 176   FT_ERROR_END_LIST
 177 #endif
 178
 179
 180   /*******************************************************************/
 181   /*******************************************************************/
 182   /*****                                                         *****/
 183   /*****                      SIMPLE CLEANUP                     *****/
 184   /*****                                                         *****/
 185   /*******************************************************************/
 186   /*******************************************************************/
 187
 188 #ifdef FT_NEED_EXTERN_C
 189   }
 190 #endif
 191
 192 #undef FT_ERROR_START_LIST
 193 #undef FT_ERROR_END_LIST
 194
 195 #undef FT_ERRORDEF
 196 #undef FT_ERRORDEF_
 197 #undef FT_NOERRORDEF_
 198
 199 #undef FT_NEED_EXTERN_C
 200 #undef FT_ERR_PREFIX
 201 #undef FT_ERR_BASE
 202 #undef FT_ERR_CONCAT
 203
 204 #endif /* __FTERRORS_H__ */
 205
 206
 207 /* END */