Chiebot-Mirror
/
freetype
mirror of https://github.com/freetype/freetype.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

Formatting, improving comments.

Browse Source
GSoC-2020-greg
Werner Lemberg 5 years ago
parent 53be1753de
commit fffc303a7f
2 changed files with 203 additions and 154 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 136
      include/freetype/config/public-macros.h
  2. 221
      include/freetype/internal/compiler-macros.h

136
include/freetype/config/public-macros.h
Unescape 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
Unescape 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. */

Write Preview
Loading…
Cancel
Save