ref: fffc303a7f397d08eee719eca351bdb55b3a1e83
parent: 53be1753dea9bd3e586f3e6f3ffc55b31080d450
author: Werner Lemberg <wl@gnu.org>
date: Tue Jul 28 14:28:10 EDT 2020
Formatting, improving comments.
--- a/include/freetype/config/public-macros.h
+++ b/include/freetype/config/public-macros.h
@@ -15,81 +15,101 @@
*
*/
-/* The definitions in this file are used by the public FreeType headers,
- * and thus should be considered part of the public API.
- *
- * Other compiler-specific macro definitions that are not exposed by the
- * FreeType API should go into include/freetype/internal/compiler-macros.h
- * instead.
- */
+ /*
+ * The definitions in this file are used by the public FreeType headers
+ * and thus should be considered part of the public API.
+ *
+ * Other compiler-specific macro definitions that are not exposed by the
+ * FreeType API should go into
+ * `include/freetype/internal/compiler-macros.h` instead.
+ */
#ifndef FREETYPE_CONFIG_PUBLIC_MACROS_H_
#define FREETYPE_CONFIG_PUBLIC_MACROS_H_
-/* FT_BEGIN_HEADER and FT_END_HEADER might have already been defined by
- * <freetype/config/ftheader.h>, but we don't want to include this header
- * here, so redefine the macros here only when needed. Their definition is
- * very stable, so keeping them in sync with the ones in the header should
- * not be a maintenance issue.
- */
+ /*
+ * `FT_BEGIN_HEADER` and `FT_END_HEADER` might have already been defined
+ * by `freetype/config/ftheader.h`, but we don't want to include this
+ * header here, so redefine the macros here only when needed. Their
+ * definition is very stable, so keeping them in sync with the ones in the
+ * header should not be a maintenance issue.
+ */
#ifndef FT_BEGIN_HEADER
-# ifdef __cplusplus
-# define FT_BEGIN_HEADER extern "C" {-# else
-# define FT_BEGIN_HEADER /* nothing */
-# endif
-#endif /* FT_END_HEADER */
+#ifdef __cplusplus
+#define FT_BEGIN_HEADER extern "C" {+#else
+#define FT_BEGIN_HEADER /* empty */
+#endif
+#endif /* FT_BEGIN_HEADER */
#ifndef FT_END_HEADER
-# ifdef __cplusplus
-# define FT_END_HEADER }
-# else
-# define FT_END_HEADER /* nothing */
-# endif
+#ifdef __cplusplus
+#define FT_END_HEADER }
+#else
+#define FT_END_HEADER /* empty */
+#endif
#endif /* FT_END_HEADER */
+
FT_BEGIN_HEADER
-/* Mark a function declaration as public. This ensures it will be properly
- * exported to client code. Place this before a function declaration.
- *
- * NOTE: This macro should be considered an internal implementation detail, and
- * not part of the FreeType API. It is only defined here because it is needed
- * by FT_EXPORT()
- */
-#if defined(_WIN32)
-# if defined(FT2_BUILD_LIBRARY) && defined( DLL_EXPORT )
-# define FT_PUBLIC_FUNCTION_ATTRIBUTE __declspec( dllexport )
-# elif defined( DLL_IMPORT )
-# define FT_PUBLIC_FUNCTION_ATTRIBUTE __declspec( dllimport )
-# endif
-#elif (defined(__GNUC__) && __GNUC__ >= 4) || defined(__clang__)
-# define FT_PUBLIC_FUNCTION_ATTRIBUTE __attribute__((visibility("default")))-#elif defined(__SUNPRO_C) && __SUNPRO_C >= 0x550
-# define FT_PUBLIC_FUNCTION_ATTRIBUTE __global
+ /*
+ * Mark a function declaration as public. This ensures it will be
+ * properly exported to client code. Place this before a function
+ * declaration.
+ *
+ * NOTE: This macro should be considered an internal implementation
+ * detail, and not part of the FreeType API. It is only defined here
+ * because it is needed by `FT_EXPORT`.
+ */
+
+ /* Visual C, mingw */
+#if defined( _WIN32 )
+
+#if defined( FT2_BUILD_LIBRARY ) && defined( DLL_EXPORT )
+#define FT_PUBLIC_FUNCTION_ATTRIBUTE __declspec( dllexport )
+#elif defined( DLL_IMPORT )
+#define FT_PUBLIC_FUNCTION_ATTRIBUTE __declspec( dllimport )
#endif
+ /* gcc, clang */
+#elif ( defined( __GNUC__ ) && __GNUC__ >= 4 ) || defined( __clang__ )
+#define FT_PUBLIC_FUNCTION_ATTRIBUTE \
+ __attribute__(( visibility( "default" ) ))
+
+ /* Sun */
+#elif defined( __SUNPRO_C ) && __SUNPRO_C >= 0x550
+#define FT_PUBLIC_FUNCTION_ATTRIBUTE __global
+#endif
+
+
#ifndef FT_PUBLIC_FUNCTION_ATTRIBUTE
-# define FT_PUBLIC_FUNCTION_ATTRIBUTE /* nothing */
+#define FT_PUBLIC_FUNCTION_ATTRIBUTE /* empty */
#endif
-/* Define a public FreeType API function. This ensures it is properly exported
- * or imported at build time. The macro parameter is the function's return type
- * as in:
- *
- * FT_EXPORT( FT_Bool ) FT_Object_Method( FT_Object obj, ... );
- *
- * NOTE: This requires that all FT_EXPORT() uses are inside FT_BEGIN_HEADER ..
- * FT_END_HEADER blocks. This guarantees that the functions are exported with
- * C linkage, even when the header is included by a C++ source file.
- */
+
+ /*
+ * Define a public FreeType API function. This ensures it is properly
+ * exported or imported at build time. The macro parameter is the
+ * function's return type as in:
+ *
+ * FT_EXPORT( FT_Bool )
+ * FT_Object_Method( FT_Object obj,
+ * ... );
+ *
+ * NOTE: This requires that all `FT_EXPORT` uses are inside
+ * `FT_BEGIN_HEADER ... FT_END_HEADER` blocks. This guarantees that the
+ * functions are exported with C linkage, even when the header is included
+ * by a C++ source file.
+ */
#define FT_EXPORT( x ) FT_PUBLIC_FUNCTION_ATTRIBUTE extern x
- /* `FT_UNUSED` indicates that a given parameter is not used -- */
- /* this is only used to get rid of unpleasant compiler warnings. */
- /* */
- /* Technically, this was not meant to be part of the public API, */
- /* but some third-party code depends on it. */
- /* */
+ /*
+ * `FT_UNUSED` indicates that a given parameter is not used -- this is
+ * only used to get rid of unpleasant compiler warnings.
+ *
+ * Technically, this was not meant to be part of the public API, but some
+ * third-party code depends on it.
+ */
#ifndef FT_UNUSED
#define FT_UNUSED( arg ) ( (arg) = (arg) )
#endif
--- a/include/freetype/internal/compiler-macros.h
+++ b/include/freetype/internal/compiler-macros.h
@@ -36,50 +36,60 @@
# endif
#endif
-/* When defining a macro that expands to a non-trivial C statement, use
- * FT_BEGIN_STMNT and FT_END_STMNT to enclose the macro's body. This ensures
- * there are no surprises when the macro is invoked in conditional branches.
- *
- * E.g.:
- * #define LOG(...) \
- * FT_BEGIN_STMNT \
- * if (logging_enabled) \
- * log(__VA_ARGS__); \
- * FT_END_STMNT
- */
+ /*
+ * When defining a macro that expands to a non-trivial C statement, use
+ * FT_BEGIN_STMNT and FT_END_STMNT to enclose the macro's body. This
+ * ensures there are no surprises when the macro is invoked in conditional
+ * branches.
+ *
+ * Example:
+ *
+ * #define LOG( ... ) \
+ * FT_BEGIN_STMNT \
+ * if ( logging_enabled ) \
+ * log( __VA_ARGS__ ); \
+ * FT_END_STMNT
+ */
#define FT_BEGIN_STMNT do {#define FT_END_STMNT } while ( 0 )
-/* FT_DUMMY_STMNT expands to an empty C statement. Useful for conditionally
- * define statement macros, as in:
- *
- * #ifdef BUILD_CONFIG_LOGGING
- * # define LOG(...) \
- * FT_BEGIN_STMNT \
- * if (logging_enabled) \
- * log(__VA_ARGS__); \
- * FT_END_STMNT
- * #else
- * # define LOG(...) FT_DUMMY_STMNT
- * #endif
- */
+ /*
+ * FT_DUMMY_STMNT expands to an empty C statement. Useful for
+ * conditionally defined statement macros.
+ *
+ * Example:
+ *
+ * #ifdef BUILD_CONFIG_LOGGING
+ * #define LOG( ... ) \
+ * FT_BEGIN_STMNT \
+ * if ( logging_enabled ) \
+ * log( __VA_ARGS__ ); \
+ * FT_END_STMNT
+ * #else
+ * # define LOG( ... ) FT_DUMMY_STMNT
+ * #endif
+ */
#define FT_DUMMY_STMNT FT_BEGIN_STMNT FT_END_STMNT
#ifdef _WIN64
- /* only 64bit Windows uses the LLP64 data model, i.e., */
- /* 32-bit integers, 64-bit pointers. */
-#define FT_UINT_TO_POINTER( x ) (void*)(unsigned __int64)(x)
+ /* only 64bit Windows uses the LLP64 data model, i.e., */
+ /* 32-bit integers, 64-bit pointers. */
+#define FT_UINT_TO_POINTER( x ) (void *)(unsigned __int64)(x)
#else
-#define FT_UINT_TO_POINTER( x ) (void*)(unsigned long)(x)
+#define FT_UINT_TO_POINTER( x ) (void *)(unsigned long)(x)
#endif
-/* Use FT_TYPEOF(type) to cast a value to |type|. This is useful to suppress
- * signedness compilation warnings in macros as in:
- *
- * #define PAD_(x, n) ( (x) & ~FT_TYPEOF( x )( (n) - 1 ) )
- *
- * `typeof` condition taken from gnulib's `intprops.h` header file
- */
+ /*
+ * Use `FT_TYPEOF( type )` to cast a value to `type`. This is useful to
+ * suppress signedness compilation warnings in macros.
+ *
+ * Example:
+ *
+ * #define PAD_( x, n ) ( (x) & ~FT_TYPEOF( x )( (n) - 1 ) )
+ *
+ * (The `typeof` condition is taken from gnulib's `intprops.h` header
+ * file.)
+ */
#if ( ( defined( __GNUC__ ) && __GNUC__ >= 2 ) || \
( defined( __IBMC__ ) && __IBMC__ >= 1210 && \
defined( __IBM__TYPEOF__ ) ) || \
@@ -89,49 +99,59 @@
#define FT_TYPEOF( type ) /* empty */
#endif
-/* Mark a function declaration as internal to the library. This ensures that
- * it will not be exposed by default to client code, and helps generate smaller
- * and faster code on ELF-based platforms. Place this before a function
- * declaration.
- */
-#if (defined(__GNUC__) && __GNUC__ >= 4) || defined(__clang__)
-#define FT_INTERNAL_FUNCTION_ATTRIBUTE __attribute__((visibility("hidden")))+ /*
+ * Mark a function declaration as internal to the library. This ensures
+ * that it will not be exposed by default to client code, and helps
+ * generate smaller and faster code on ELF-based platforms. Place this
+ * before a function declaration.
+ */
+#if ( defined( __GNUC__ ) && __GNUC__ >= 4 ) || defined( __clang__ )
+#define FT_INTERNAL_FUNCTION_ATTRIBUTE \
+ __attribute__(( visibility( "hidden" ) ))
#else
-#define FT_INTERNAL_FUNCTION_ATTRIBUTE /* nothing */
+#define FT_INTERNAL_FUNCTION_ATTRIBUTE /* empty */
#endif
-/* FreeType supports compiling its C sources to be compiled as C++ instead,
- * this introduces a number of subtle issues.
- *
- * The main one is that a C++ function declaration and its definition must have
- * the same 'linkage'. Because all FreeType headers declare their function with
- * C linkage (i.e. within an extern "C" { .. } block, due to the magic of- * FT_BEGIN_HEADER and FT_END_HEADER), then their definition in FreeType
- * sources should also be prefixed with 'extern "C"' when compiled in C++ mode.
- *
- * The FT_FUNCTION_DECLARATION() and FT_FUNCTION_DEFINITION() macros are
- * provided to deal with this case, as well as FT_CALLBACK_DEF et al below.
- */
+ /*
+ * FreeType supports compilation of its C sources with a C++ compiler (in
+ * C++ mode); this introduces a number of subtle issues.
+ *
+ * The main one is that a C++ function declaration and its definition must
+ * have the same 'linkage'. Because all FreeType headers declare their
+ * functions with C linkage (i.e., within an `extern "C" { ... }` block+ * due to the magic of FT_BEGIN_HEADER and FT_END_HEADER), their
+ * definition in FreeType sources should also be prefixed with `extern
+ * "C"` when compiled in C++ mode.
+ *
+ * The `FT_FUNCTION_DECLARATION` and `FT_FUNCTION_DEFINITION` macros are
+ * provided to deal with this case, as well as `FT_CALLBACK_DEF` and its
+ * siblings below.
+ */
-/* FT_FUNCTION_DECLARATION(type) can be used to write a C function declaration,
- * and ensure it will have C linkage when the library is built with a C++
- * compiler. The parameter is the function's return type, so a declaration
- * would look like:
- *
- * FT_FUNCTION_DECLARATION(int) foo(int x);
- *
- * NOTE: This requires that all uses are inside FT_BEGIN_HEADER..FT_END_HEADER
- * blocks. Which guarantees that the declarations have C linkage when the
- * headers are included by C++ sources.
- *
- * NOTE: Do not use directly, use FT_LOCAL()/FT_BASE()/FT_EXPORT() instead.
- */
+ /*
+ * `FT_FUNCTION_DECLARATION( type )` can be used to write a C function
+ * declaration to ensure it will have C linkage when the library is built
+ * with a C++ compiler. The parameter is the function's return type, so a
+ * declaration would look like
+ *
+ * FT_FUNCTION_DECLARATION( int )
+ * foo( int x );
+ *
+ * NOTE: This requires that all uses are inside of `FT_BEGIN_HEADER ...
+ * FT_END_HEADER` blocks, which guarantees that the declarations have C
+ * linkage when the headers are included by C++ sources.
+ *
+ * NOTE: Do not use directly. Use `FT_LOCAL`, `FT_BASE`, and `FT_EXPORT`
+ * instead.
+ */
#define FT_FUNCTION_DECLARATION( x ) extern x
-/* Same as FT_FUNCTION_DECLARATION(), but for function definitions instead.
- * NOTE: Do not use directly, use FT_LOCAL_DEF()/FT_BASE_DEF()/FT_EXPORT_DEF()
- * instead.
- */
+ /*
+ * Same as `FT_FUNCTION_DECLARATION`, but for function definitions instead.
+ *
+ * NOTE: Do not use directly. Use `FT_LOCAL_DEF`, `FT_BASE_DEF`, and
+ * `FT_EXPORT_DEF` instead.
+ */
#ifdef __cplusplus
#define FT_FUNCTION_DEFINITION( x ) extern "C" x
#else
@@ -138,45 +158,54 @@
#define FT_FUNCTION_DEFINITION( x ) x
#endif
-/* Use FT_LOCAL()/FT_LOCAL_DEF() to declare and define an internal FreeType
- * function that is only used by the sources of a single src/module/ directory.
- * This ensures the functions are turned into static ones at build time,
- * resulting in smaller and faster code.
- */
+ /*
+ * Use `FT_LOCAL` and `FT_LOCAL_DEF` to declare and define, respectively,
+ * an internal FreeType function that is only used by the sources of a
+ * single `src/module/` directory. This ensures that the functions are
+ * turned into static ones at build time, resulting in smaller and faster
+ * code.
+ */
#ifdef FT_MAKE_OPTION_SINGLE_OBJECT
-# define FT_LOCAL( x ) static x
-# define FT_LOCAL_DEF( x ) static x
+#define FT_LOCAL( x ) static x
+#define FT_LOCAL_DEF( x ) static x
#else
-#define FT_LOCAL( x ) FT_INTERNAL_FUNCTION_ATTRIBUTE FT_FUNCTION_DECLARATION( x )
+#define FT_LOCAL( x ) FT_INTERNAL_FUNCTION_ATTRIBUTE \
+ FT_FUNCTION_DECLARATION( x )
#define FT_LOCAL_DEF( x ) FT_FUNCTION_DEFINITION( x )
#endif /* FT_MAKE_OPTION_SINGLE_OBJECT */
-/* Use FT_LOCAL_ARRAY()/FT_LOCAL_ARRAY_DEF() to declare and define a constant
- * array that must be accessed from several sources in the same src/module/
- * sub-directory, but are otherwise internal to the library.
- */
-#define FT_LOCAL_ARRAY( x ) FT_INTERNAL_FUNCTION_ATTRIBUTE extern const x
+ /*
+ * Use `FT_LOCAL_ARRAY` and `FT_LOCAL_ARRAY_DEF` to declare and define,
+ * respectively, a constant array that must be accessed from several
+ * sources in the same `src/module/` sub-directory, and which are internal
+ * to the library.
+ */
+#define FT_LOCAL_ARRAY( x ) FT_INTERNAL_FUNCTION_ATTRIBUTE \
+ extern const x
#define FT_LOCAL_ARRAY_DEF( x ) FT_FUNCTION_DEFINITION( const x )
-/* Use FT_BASE()/FT_BASE_DEF() to declare or define an internal library
- * function that are used by more than one single module.
- */
-#define FT_BASE( x ) FT_INTERNAL_FUNCTION_ATTRIBUTE FT_FUNCTION_DECLARATION( x )
+ /*
+ * `Use FT_BASE` and `FT_BASE_DEF` to declare and define, respectively, an
+ * internal library function that is used by more than a single module.
+ */
+#define FT_BASE( x ) FT_INTERNAL_FUNCTION_ATTRIBUTE \
+ FT_FUNCTION_DECLARATION( x )
#define FT_BASE_DEF( x ) FT_FUNCTION_DEFINITION( x )
-/* NOTE: Conditionally define FT_EXPORT_VAR() due to its definition in
- * src/smooth/ftgrays.h to make the header more portable.
- */
+ /*
+ * NOTE: Conditionally define `FT_EXPORT_VAR` due to its definition in
+ * `src/smooth/ftgrays.h` to make the header more portable.
+ */
#ifndef FT_EXPORT_VAR
-#define FT_EXPORT_VAR( x ) FT_FUNCTION_DECLARATION( x )
+#define FT_EXPORT_VAR( x ) FT_FUNCTION_DECLARATION( x )
#endif
- /* When compiling FreeType as a DLL or DSO with hidden visibility */
+ /* When compiling FreeType as a DLL or DSO with hidden visibility, */
/* some systems/compilers need a special attribute in front OR after */
/* the return type of function declarations. */
/* */
@@ -211,8 +240,8 @@
/* To export a variable, use `FT_EXPORT_VAR`. */
/* */
-/* See <freetype/config/compiler_macros.h> for the FT_EXPORT() definition */
-#define FT_EXPORT_DEF( x ) FT_FUNCTION_DEFINITION( x )
+ /* See `freetype/config/compiler_macros.h` for the `FT_EXPORT` definition */
+#define FT_EXPORT_DEF( x ) FT_FUNCTION_DEFINITION( x )
/* The following macros are needed to compile the library with a */
/* C++ compiler and with 16bit compilers. */