Merge pull request #12 from dboddie/update-freetype

Update FreeType to the latest code

1 files changed, 195 insertions, 106 deletions

diff --git a/include/freetype/fterrors.h b/include/freetype/fterrors.h
index 1def4f9c..27c0ece5 100644
--- a/include/freetype/fterrors.h
+++ b/include/freetype/fterrors.h
@@ -1,98 +1,130 @@
-/***************************************************************************/
-/*                                                                         */
-/*  fterrors.h                                                             */
-/*                                                                         */
-/*    FreeType error code handling (specification).                        */
-/*                                                                         */
-/*  Copyright 1996-2001, 2002 by                                           */
-/*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
-/*                                                                         */
-/*  This file is part of the FreeType project, and may only be used,       */
-/*  modified, and distributed under the terms of the FreeType project      */
-/*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
-/*  this file you indicate that you have read the license and              */
-/*  understand and accept it fully.                                        */
-/*                                                                         */
-/***************************************************************************/
-
-
-  /*************************************************************************/
-  /*                                                                       */
-  /* This special header file is used to define the handling of FT2        */
-  /* enumeration constants.  It can also be used to generate error message */
-  /* strings with a small macro trick explained below.                     */
-  /*                                                                       */
-  /* I - Error Formats                                                     */
-  /* -----------------                                                     */
-  /*                                                                       */
-  /*   Since release 2.1, the error constants have changed.  The lower     */
-  /*   byte of the error value gives the "generic" error code, while the   */
-  /*   higher byte indicates in which module the error occurred.           */
-  /*                                                                       */
-  /*   You can use the macro FT_ERROR_BASE(x) macro to extract the generic */
-  /*   error code from an FT_Error value.                                  */
-  /*                                                                       */
-  /*   The configuration macro FT_CONFIG_OPTION_USE_MODULE_ERRORS can be   */
-  /*   undefined in ftoption.h in order to make the higher byte always     */
-  /*   zero, in case you need to be compatible with previous versions of   */
-  /*   FreeType 2.                                                         */
-  /*                                                                       */
-  /*                                                                       */
-  /* II - Error Message strings                                            */
-  /* --------------------------                                            */
-  /*                                                                       */
-  /*   The error definitions below are made through special macros that    */
-  /*   allow client applications to build a table of error message strings */
-  /*   if they need it.  The strings are not included in a normal build of */
-  /*   FreeType 2 to save space (most client applications do not use       */
-  /*   them).                                                              */
-  /*                                                                       */
-  /*   To do so, you have to define the following macros before including  */
-  /*   this file:                                                          */
-  /*                                                                       */
-  /*   FT_ERROR_START_LIST ::                                              */
-  /*     This macro is called before anything else to define the start of  */
-  /*     the error list.  It is followed by several FT_ERROR_DEF calls     */
-  /*     (see below).                                                      */
-  /*                                                                       */
-  /*   FT_ERROR_DEF( e, v, s ) ::                                          */
-  /*     This macro is called to define one single error.                  */
-  /*     `e' is the error code identifier (e.g. FT_Err_Invalid_Argument).  */
-  /*     `v' is the error numerical value.                                 */
-  /*     `s' is the corresponding error string.                            */
-  /*                                                                       */
-  /*   FT_ERROR_END_LIST ::                                                */
-  /*     This macro ends the list.                                         */
-  /*                                                                       */
-  /*   Additionally, you have to undefine __FTERRORS_H__ before #including */
-  /*   this file.                                                          */
-  /*                                                                       */
-  /*   Here is a simple example:                                           */
-  /*                                                                       */
-  /*     {                                                                 */
-  /*       #undef __FTERRORS_H__                                           */
-  /*       #define FT_ERRORDEF( e, v, s )  { e, s },                       */
-  /*       #define FT_ERROR_START_LIST     {                               */
-  /*       #define FT_ERROR_END_LIST       { 0, 0 } };                     */
-  /*                                                                       */
-  /*       const struct                                                    */
-  /*       {                                                               */
-  /*         int          err_code;                                        */
-  /*         const char*  err_msg                                          */
-  /*       } ft_errors[] =                                                 */
-  /*                                                                       */
-  /*       #include FT_ERRORS_H                                            */
-  /*     }                                                                 */
-  /*                                                                       */
-  /*************************************************************************/
-
-
-#ifndef __FTERRORS_H__
+/****************************************************************************
+ *
+ * fterrors.h
+ *
+ *   FreeType error code handling (specification).
+ *
+ * Copyright (C) 1996-2024 by
+ * David Turner, Robert Wilhelm, and Werner Lemberg.
+ *
+ * This file is part of the FreeType project, and may only be used,
+ * modified, and distributed under the terms of the FreeType project
+ * license, LICENSE.TXT.  By continuing to use, modify, or distribute
+ * this file you indicate that you have read the license and
+ * understand and accept it fully.
+ *
+ */
+
+
+  /**************************************************************************
+   *
+   * @section:
+   *   error_enumerations
+   *
+   * @title:
+   *   Error Enumerations
+   *
+   * @abstract:
+   *   How to handle errors and error strings.
+   *
+   * @description:
+   *   The header file `fterrors.h` (which is automatically included by
+   *   `freetype.h`) defines the handling of FreeType's enumeration
+   *   constants.  It can also be used to generate error message strings
+   *   with a small macro trick explained below.
+   *
+   *   **Error Formats**
+   *
+   *   The configuration macro `FT_CONFIG_OPTION_USE_MODULE_ERRORS` can be
+   *   defined in `ftoption.h` in order to make the higher byte indicate the
+   *   module where the error has happened (this is not compatible with
+   *   standard builds of FreeType~2, however).  See the file `ftmoderr.h`
+   *   for more details.
+   *
+   *   **Error Message Strings**
+   *
+   *   Error definitions are set up with special macros that allow client
+   *   applications to build a table of error message strings.  The strings
+   *   are not included in a normal build of FreeType~2 to save space (most
+   *   client applications do not use them).
+   *
+   *   To do so, you have to define the following macros before including
+   *   this file.
+   *
+   *   ```
+   *     FT_ERROR_START_LIST
+   *   ```
+   *
+   *   This macro is called before anything else to define the start of the
+   *   error list.  It is followed by several `FT_ERROR_DEF` calls.
+   *
+   *   ```
+   *     FT_ERROR_DEF( e, v, s )
+   *   ```
+   *
+   *   This macro is called to define one single error.  'e' is the error
+   *   code identifier (e.g., `Invalid_Argument`), 'v' is the error's
+   *   numerical value, and 's' is the corresponding error string.
+   *
+   *   ```
+   *     FT_ERROR_END_LIST
+   *   ```
+   *
+   *   This macro ends the list.
+   *
+   *   Additionally, you have to undefine `FTERRORS_H_` before #including
+   *   this file.
+   *
+   *   Here is a simple example.
+   *
+   *   ```
+   *     #undef FTERRORS_H_
+   *     #define FT_ERRORDEF( e, v, s )  { e, s },
+   *     #define FT_ERROR_START_LIST     {
+   *     #define FT_ERROR_END_LIST       { 0, NULL } };
+   *
+   *     const struct
+   *     {
+   *       int          err_code;
+   *       const char*  err_msg;
+   *     } ft_errors[] =
+   *
+   *     #include <freetype/fterrors.h>
+   *   ```
+   *
+   *   An alternative to using an array is a switch statement.
+   *
+   *   ```
+   *     #undef FTERRORS_H_
+   *     #define FT_ERROR_START_LIST     switch ( error_code ) {
+   *     #define FT_ERRORDEF( e, v, s )    case v: return s;
+   *     #define FT_ERROR_END_LIST       }
+   *   ```
+   *
+   *   If you use `FT_CONFIG_OPTION_USE_MODULE_ERRORS`, `error_code` should
+   *   be replaced with `FT_ERROR_BASE(error_code)` in the last example.
+   */
+
+  /* */
+
+  /* In previous FreeType versions we used `__FTERRORS_H__`.  However, */
+  /* using two successive underscores in a non-system symbol name      */
+  /* violates the C (and C++) standard, so it was changed to the       */
+  /* current form.  In spite of this, we have to make                  */
+  /*                                                                   */
+  /* ```                                                               */
+  /*   #undefine __FTERRORS_H__                                        */
+  /* ```                                                               */
+  /*                                                                   */
+  /* work for backward compatibility.                                  */
+  /*                                                                   */
+#if !( defined( FTERRORS_H_ ) && defined ( __FTERRORS_H__ ) )
+#define FTERRORS_H_
 #define __FTERRORS_H__
 
 
   /* include module base error codes */
-#include FT_MODULE_ERRORS_H
+#include <freetype/ftmoderr.h>
 
 
   /*******************************************************************/
@@ -106,15 +138,9 @@
 
 #undef  FT_NEED_EXTERN_C
 
-#undef  FT_ERR_XCAT
-#undef  FT_ERR_CAT
-
-#define FT_ERR_XCAT( x, y )  x ## y
-#define FT_ERR_CAT( x, y )   FT_ERR_XCAT( x, y )
-
 
   /* FT_ERR_PREFIX is used as a prefix for error identifiers. */
-  /* By default, we use `FT_Err_'.                            */
+  /* By default, we use `FT_Err_`.                            */
   /*                                                          */
 #ifndef FT_ERR_PREFIX
 #define FT_ERR_PREFIX  FT_Err_
@@ -142,6 +168,8 @@
   /*                                                           */
 #ifndef FT_ERRORDEF
 
+#define FT_INCLUDE_ERR_PROTOS
+
 #define FT_ERRORDEF( e, v, s )  e = v,
 #define FT_ERROR_START_LIST     enum {
 #define FT_ERROR_END_LIST       FT_ERR_CAT( FT_ERR_PREFIX, Max ) };
@@ -155,11 +183,11 @@
 
 
   /* this macro is used to define an error */
-#define FT_ERRORDEF_( e, v, s )   \
+#define FT_ERRORDEF_( e, v, s )                                             \
           FT_ERRORDEF( FT_ERR_CAT( FT_ERR_PREFIX, e ), v + FT_ERR_BASE, s )
 
-  /* this is only used for FT_Err_Ok, which must be 0! */
-#define FT_NOERRORDEF_( e, v, s ) \
+  /* this is only used for <module>_Err_Ok, which must be 0! */
+#define FT_NOERRORDEF_( e, v, s )                             \
           FT_ERRORDEF( FT_ERR_CAT( FT_ERR_PREFIX, e ), v, s )
 
 
@@ -168,8 +196,8 @@
 #endif
 
 
-  /* no include the error codes */
-#include FT_ERROR_DEFINITIONS_H
+  /* now include the error codes */
+#include <freetype/fterrdef.h>
 
 
 #ifdef FT_ERROR_END_LIST
@@ -197,11 +225,72 @@
 #undef FT_NOERRORDEF_
 
 #undef FT_NEED_EXTERN_C
-#undef FT_ERR_PREFIX
 #undef FT_ERR_BASE
-#undef FT_ERR_CONCAT
 
-#endif /* __FTERRORS_H__ */
+  /* FT_ERR_PREFIX is needed internally */
+#ifndef FT2_BUILD_LIBRARY
+#undef FT_ERR_PREFIX
+#endif
+
+  /* FT_INCLUDE_ERR_PROTOS: Control whether function prototypes should be */
+  /*                        included with                                 */
+  /*                                                                      */
+  /*                          #include <freetype/fterrors.h>              */
+  /*                                                                      */
+  /*                        This is only true where `FT_ERRORDEF` is      */
+  /*                        undefined.                                    */
+  /*                                                                      */
+  /* FT_ERR_PROTOS_DEFINED: Actual multiple-inclusion protection of       */
+  /*                        `fterrors.h`.                                 */
+#ifdef FT_INCLUDE_ERR_PROTOS
+#undef FT_INCLUDE_ERR_PROTOS
+
+#ifndef FT_ERR_PROTOS_DEFINED
+#define FT_ERR_PROTOS_DEFINED
+
+
+FT_BEGIN_HEADER
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Error_String
+   *
+   * @description:
+   *   Retrieve the description of a valid FreeType error code.
+   *
+   * @input:
+   *   error_code ::
+   *     A valid FreeType error code.
+   *
+   * @return:
+   *   A C~string or `NULL`, if any error occurred.
+   *
+   * @note:
+   *   FreeType has to be compiled with `FT_CONFIG_OPTION_ERROR_STRINGS` or
+   *   `FT_DEBUG_LEVEL_ERROR` to get meaningful descriptions.
+   *   'error_string' will be `NULL` otherwise.
+   *
+   *   Module identification will be ignored:
+   *
+   *   ```c
+   *     strcmp( FT_Error_String(  FT_Err_Unknown_File_Format ),
+   *             FT_Error_String( BDF_Err_Unknown_File_Format ) ) == 0;
+   *   ```
+   */
+  FT_EXPORT( const char* )
+  FT_Error_String( FT_Error  error_code );
+
+  /* */
+
+FT_END_HEADER
+
+
+#endif /* FT_ERR_PROTOS_DEFINED */
+
+#endif /* FT_INCLUDE_ERR_PROTOS */
+
+#endif /* !(FTERRORS_H_ && __FTERRORS_H__) */
 
 
 /* END */