1 /**************************************************************************** 2 * 3 * ftdebug.h 4 * 5 * Debugging and logging component (specification). 6 * 7 * Copyright (C) 1996-2020 by 8 * David Turner, Robert Wilhelm, and Werner Lemberg. 9 * 10 * This file is part of the FreeType project, and may only be used, 11 * modified, and distributed under the terms of the FreeType project 12 * license, LICENSE.TXT. By continuing to use, modify, or distribute 13 * this file you indicate that you have read the license and 14 * understand and accept it fully. 15 * 16 * 17 * IMPORTANT: A description of FreeType's debugging support can be 18 * found in 'docs/DEBUG.TXT'. Read it if you need to use or 19 * understand this code. 20 * 21 */ 22 23 24 #ifndef FTDEBUG_H_ 25 #define FTDEBUG_H_ 26 27 28 #include <ft2build.h> 29 #include FT_CONFIG_CONFIG_H 30 #include <freetype/freetype.h> 31 32 #include "compiler-macros.h" 33 34 35 FT_BEGIN_HEADER 36 37 38 /* force the definition of FT_DEBUG_LEVEL_ERROR if FT_DEBUG_LEVEL_TRACE */ 39 /* is already defined; this simplifies the following #ifdefs */ 40 /* */ 41 #ifdef FT_DEBUG_LEVEL_TRACE 42 #undef FT_DEBUG_LEVEL_ERROR 43 #define FT_DEBUG_LEVEL_ERROR 44 #endif 45 46 47 /************************************************************************** 48 * 49 * Define the trace enums as well as the trace levels array when they are 50 * needed. 51 * 52 */ 53 54 #ifdef FT_DEBUG_LEVEL_TRACE 55 56 #define FT_TRACE_DEF( x ) trace_ ## x , 57 58 /* defining the enumeration */ 59 typedef enum FT_Trace_ 60 { 61 #include <freetype/internal/fttrace.h> 62 trace_count 63 64 } FT_Trace; 65 66 67 /* a pointer to the array of trace levels, */ 68 /* provided by `src/base/ftdebug.c' */ 69 extern int* ft_trace_levels; 70 71 #undef FT_TRACE_DEF 72 73 #endif /* FT_DEBUG_LEVEL_TRACE */ 74 75 76 /************************************************************************** 77 * 78 * Define the FT_TRACE macro 79 * 80 * IMPORTANT! 81 * 82 * Each component must define the macro FT_COMPONENT to a valid FT_Trace 83 * value before using any TRACE macro. 84 * 85 */ 86 87 #ifdef FT_DEBUG_LEVEL_TRACE 88 89 /* we need two macros here to make cpp expand `FT_COMPONENT' */ 90 #define FT_TRACE_COMP( x ) FT_TRACE_COMP_( x ) 91 #define FT_TRACE_COMP_( x ) trace_ ## x 92 93 #define FT_TRACE( level, varformat ) \ 94 do \ 95 { \ 96 if ( ft_trace_levels[FT_TRACE_COMP( FT_COMPONENT )] >= level ) \ 97 FT_Message varformat; \ 98 } while ( 0 ) 99 100 #else /* !FT_DEBUG_LEVEL_TRACE */ 101 102 #define FT_TRACE( level, varformat ) do { } while ( 0 ) /* nothing */ 103 104 #endif /* !FT_DEBUG_LEVEL_TRACE */ 105 106 107 /************************************************************************** 108 * 109 * @function: 110 * FT_Trace_Get_Count 111 * 112 * @description: 113 * Return the number of available trace components. 114 * 115 * @return: 116 * The number of trace components. 0 if FreeType 2 is not built with 117 * FT_DEBUG_LEVEL_TRACE definition. 118 * 119 * @note: 120 * This function may be useful if you want to access elements of the 121 * internal trace levels array by an index. 122 */ 123 FT_BASE( FT_Int ) 124 FT_Trace_Get_Count( void ); 125 126 127 /************************************************************************** 128 * 129 * @function: 130 * FT_Trace_Get_Name 131 * 132 * @description: 133 * Return the name of a trace component. 134 * 135 * @input: 136 * The index of the trace component. 137 * 138 * @return: 139 * The name of the trace component. This is a statically allocated 140 * C~string, so do not free it after use. `NULL` if FreeType is not 141 * built with FT_DEBUG_LEVEL_TRACE definition. 142 * 143 * @note: 144 * Use @FT_Trace_Get_Count to get the number of available trace 145 * components. 146 */ 147 FT_BASE( const char* ) 148 FT_Trace_Get_Name( FT_Int idx ); 149 150 151 /************************************************************************** 152 * 153 * @function: 154 * FT_Trace_Disable 155 * 156 * @description: 157 * Switch off tracing temporarily. It can be activated again with 158 * @FT_Trace_Enable. 159 */ 160 FT_BASE( void ) 161 FT_Trace_Disable( void ); 162 163 164 /************************************************************************** 165 * 166 * @function: 167 * FT_Trace_Enable 168 * 169 * @description: 170 * Activate tracing. Use it after tracing has been switched off with 171 * @FT_Trace_Disable. 172 */ 173 FT_BASE( void ) 174 FT_Trace_Enable( void ); 175 176 177 /************************************************************************** 178 * 179 * You need two opening and closing parentheses! 180 * 181 * Example: FT_TRACE0(( "Value is %i", foo )) 182 * 183 * Output of the FT_TRACEX macros is sent to stderr. 184 * 185 */ 186 187 #define FT_TRACE0( varformat ) FT_TRACE( 0, varformat ) 188 #define FT_TRACE1( varformat ) FT_TRACE( 1, varformat ) 189 #define FT_TRACE2( varformat ) FT_TRACE( 2, varformat ) 190 #define FT_TRACE3( varformat ) FT_TRACE( 3, varformat ) 191 #define FT_TRACE4( varformat ) FT_TRACE( 4, varformat ) 192 #define FT_TRACE5( varformat ) FT_TRACE( 5, varformat ) 193 #define FT_TRACE6( varformat ) FT_TRACE( 6, varformat ) 194 #define FT_TRACE7( varformat ) FT_TRACE( 7, varformat ) 195 196 197 /************************************************************************** 198 * 199 * Define the FT_ERROR macro. 200 * 201 * Output of this macro is sent to stderr. 202 * 203 */ 204 205 #ifdef FT_DEBUG_LEVEL_ERROR 206 207 #define FT_ERROR( varformat ) FT_Message varformat 208 209 #else /* !FT_DEBUG_LEVEL_ERROR */ 210 211 #define FT_ERROR( varformat ) do { } while ( 0 ) /* nothing */ 212 213 #endif /* !FT_DEBUG_LEVEL_ERROR */ 214 215 216 /************************************************************************** 217 * 218 * Define the FT_ASSERT and FT_THROW macros. The call to `FT_Throw` makes 219 * it possible to easily set a breakpoint at this function. 220 * 221 */ 222 223 #ifdef FT_DEBUG_LEVEL_ERROR 224 225 #define FT_ASSERT( condition ) \ 226 do \ 227 { \ 228 if ( !( condition ) ) \ 229 FT_Panic( "assertion failed on line %d of file %s\n", \ 230 __LINE__, __FILE__ ); \ 231 } while ( 0 ) 232 233 #define FT_THROW( e ) \ 234 ( FT_Throw( FT_ERR_CAT( FT_ERR_PREFIX, e ), \ 235 __LINE__, \ 236 __FILE__ ) | \ 237 FT_ERR_CAT( FT_ERR_PREFIX, e ) ) 238 239 #else /* !FT_DEBUG_LEVEL_ERROR */ 240 241 #define FT_ASSERT( condition ) do { } while ( 0 ) 242 243 #define FT_THROW( e ) FT_ERR_CAT( FT_ERR_PREFIX, e ) 244 245 #endif /* !FT_DEBUG_LEVEL_ERROR */ 246 247 248 /************************************************************************** 249 * 250 * Define `FT_Message` and `FT_Panic` when needed. 251 * 252 */ 253 254 #ifdef FT_DEBUG_LEVEL_ERROR 255 256 #include "stdio.h" /* for vfprintf() */ 257 258 /* print a message */ 259 FT_BASE( void ) 260 FT_Message( const char* fmt, 261 ... ); 262 263 /* print a message and exit */ 264 FT_BASE( void ) 265 FT_Panic( const char* fmt, 266 ... ); 267 268 /* report file name and line number of an error */ 269 FT_BASE( int ) 270 FT_Throw( FT_Error error, 271 int line, 272 const char* file ); 273 274 #endif /* FT_DEBUG_LEVEL_ERROR */ 275 276 277 FT_BASE( void ) 278 ft_debug_init( void ); 279 280 FT_END_HEADER 281 282 #endif /* FTDEBUG_H_ */ 283 284 285 /* END */ 286