minhngoc25a
/
freetype2
mirror of git://git.savannah.gnu.org/freetype/freetype2.git
2
1
Fork 2
Code Issues 4 Releases Wiki Activity

Formatting, improving comments.

This commit is contained in:
Werner Lemberg 2020-07-28 18:28:10 +02:00
parent 53be1753de
commit fffc303a7f
2 changed files with 203 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

136
include/freetype/config/public-macros.h
View File

@ -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

221
include/freetype/internal/compiler-macros.h
View File

@ -36,50 +36,60 @@ FT_BEGIN_HEADER
# 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,94 +99,113 @@ FT_BEGIN_HEADER
#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
#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 @@ FT_BEGIN_HEADER
/* 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. */