freetype/config/public-macros.h

0001 /****************************************************************************
0002  *
0003  * config/public-macros.h
0004  *
0005  *   Define a set of compiler macros used in public FreeType headers.
0006  *
0007  * Copyright (C) 2020-2023 by
0008  * David Turner, Robert Wilhelm, and Werner Lemberg.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017
0018   /*
0019    * The definitions in this file are used by the public FreeType headers
0020    * and thus should be considered part of the public API.
0021    *
0022    * Other compiler-specific macro definitions that are not exposed by the
0023    * FreeType API should go into
0024    * `include/freetype/internal/compiler-macros.h` instead.
0025    */
0026 #ifndef FREETYPE_CONFIG_PUBLIC_MACROS_H_
0027 #define FREETYPE_CONFIG_PUBLIC_MACROS_H_
0028
0029   /*
0030    * `FT_BEGIN_HEADER` and `FT_END_HEADER` might have already been defined
0031    * by `freetype/config/ftheader.h`, but we don't want to include this
0032    * header here, so redefine the macros here only when needed.  Their
0033    * definition is very stable, so keeping them in sync with the ones in the
0034    * header should not be a maintenance issue.
0035    */
0036 #ifndef FT_BEGIN_HEADER
0037 #ifdef __cplusplus
0038 #define FT_BEGIN_HEADER  extern "C" {
0039 #else
0040 #define FT_BEGIN_HEADER  /* empty */
0041 #endif
0042 #endif  /* FT_BEGIN_HEADER */
0043
0044 #ifndef FT_END_HEADER
0045 #ifdef __cplusplus
0046 #define FT_END_HEADER  }
0047 #else
0048 #define FT_END_HEADER  /* empty */
0049 #endif
0050 #endif  /* FT_END_HEADER */
0051
0052
0053 FT_BEGIN_HEADER
0054
0055   /*
0056    * Mark a function declaration as public.  This ensures it will be
0057    * properly exported to client code.  Place this before a function
0058    * declaration.
0059    *
0060    * NOTE: This macro should be considered an internal implementation
0061    * detail, and not part of the FreeType API.  It is only defined here
0062    * because it is needed by `FT_EXPORT`.
0063    */
0064
0065   /* Visual C, mingw */
0066 #if defined( _WIN32 )
0067
0068 #if defined( FT2_BUILD_LIBRARY ) && defined( DLL_EXPORT )
0069 #define FT_PUBLIC_FUNCTION_ATTRIBUTE  __declspec( dllexport )
0070 #elif defined( DLL_IMPORT )
0071 #define FT_PUBLIC_FUNCTION_ATTRIBUTE  __declspec( dllimport )
0072 #endif
0073
0074   /* gcc, clang */
0075 #elif ( defined( __GNUC__ ) && __GNUC__ >= 4 ) || defined( __clang__ )
0076 #define FT_PUBLIC_FUNCTION_ATTRIBUTE \
0077           __attribute__(( visibility( "default" ) ))
0078
0079   /* Sun */
0080 #elif defined( __SUNPRO_C ) && __SUNPRO_C >= 0x550
0081 #define FT_PUBLIC_FUNCTION_ATTRIBUTE  __global
0082 #endif
0083
0084
0085 #ifndef FT_PUBLIC_FUNCTION_ATTRIBUTE
0086 #define FT_PUBLIC_FUNCTION_ATTRIBUTE  /* empty */
0087 #endif
0088
0089
0090   /*
0091    * Define a public FreeType API function.  This ensures it is properly
0092    * exported or imported at build time.  The macro parameter is the
0093    * function's return type as in:
0094    *
0095    *   FT_EXPORT( FT_Bool )
0096    *   FT_Object_Method( FT_Object  obj,
0097    *                     ... );
0098    *
0099    * NOTE: This requires that all `FT_EXPORT` uses are inside
0100    * `FT_BEGIN_HEADER ... FT_END_HEADER` blocks.  This guarantees that the
0101    * functions are exported with C linkage, even when the header is included
0102    * by a C++ source file.
0103    */
0104 #define FT_EXPORT( x )  FT_PUBLIC_FUNCTION_ATTRIBUTE extern x
0105
0106
0107   /*
0108    * `FT_UNUSED` indicates that a given parameter is not used -- this is
0109    * only used to get rid of unpleasant compiler warnings.
0110    *
0111    * Technically, this was not meant to be part of the public API, but some
0112    * third-party code depends on it.
0113    */
0114 #ifndef FT_UNUSED
0115 #define FT_UNUSED( arg )  ( (arg) = (arg) )
0116 #endif
0117
0118
0119   /*
0120    * Support for casts in both C and C++.
0121    */
0122 #ifdef __cplusplus
0123 #define FT_STATIC_CAST( type, var )       static_cast<type>(var)
0124 #define FT_REINTERPRET_CAST( type, var )  reinterpret_cast<type>(var)
0125
0126 #define FT_STATIC_BYTE_CAST( type, var )                         \
0127           static_cast<type>( static_cast<unsigned char>( var ) )
0128 #else
0129 #define FT_STATIC_CAST( type, var )       (type)(var)
0130 #define FT_REINTERPRET_CAST( type, var )  (type)(var)
0131
0132 #define FT_STATIC_BYTE_CAST( type, var )  (type)(unsigned char)(var)
0133 #endif
0134
0135
0136 FT_END_HEADER
0137
0138 #endif  /* FREETYPE_CONFIG_PUBLIC_MACROS_H_ */