diff options
Diffstat (limited to 'src/3rdparty/freetype/docs/DEBUG')
| -rw-r--r-- | src/3rdparty/freetype/docs/DEBUG | 229 |
1 files changed, 168 insertions, 61 deletions
diff --git a/src/3rdparty/freetype/docs/DEBUG b/src/3rdparty/freetype/docs/DEBUG index 828f29434d..7398df69b1 100644 --- a/src/3rdparty/freetype/docs/DEBUG +++ b/src/3rdparty/freetype/docs/DEBUG @@ -11,20 +11,20 @@ located in the file `ftoption.h'. The macros are: FT_DEBUG_LEVEL_ERROR - #define this macro if you want to compile the FT_ERROR macro calls - to print error messages during program execution. This will not - stop the program. Very useful to spot invalid fonts during + #define this macro if you want to compile the `FT_ERROR' macro + calls to print error messages during program execution. This does + not stop the program. Very useful to spot invalid fonts during development and to code workarounds for them. FT_DEBUG_LEVEL_TRACE - #define this macro if you want to compile both macros FT_ERROR and - FT_TRACE. This also includes the variants FT_TRACE0, FT_TRACE1, - FT_TRACE2, ..., FT_TRACE7. + #define this macro if you want to compile both macros `FT_ERROR' + and `FT_TRACE'. This also includes the variants `FT_TRACE0', + `FT_TRACE1', `FT_TRACE2', ..., `FT_TRACE7'. The trace macros are used to send debugging messages when an appropriate `debug level' is configured at runtime through the - FT2_DEBUG environment variable (more on this later). + `FT2_DEBUG' environment variable (more on this later). FT_DEBUG_MEMORY @@ -32,18 +32,33 @@ located in the file `ftoption.h'. The macros are: small but effective debugging memory manager that tracks all allocations and frees that are performed within the font engine. - When the FT2_DEBUG_MEMORY environment variable is defined at - runtime, a call to FT_Done_FreeType will dump memory statistics, - including the list of leaked memory blocks with the source - locations where these were allocated. It is always a very good - idea to define this in development builds. This works with _any_ - program linked to FreeType, but requires a big deal of memory (the - debugging memory manager never frees the blocks to the heap in - order to detect double frees). + When the `FT2_DEBUG_MEMORY' environment variable is defined at + runtime, a call to `FT_Done_FreeType' dumps memory statistics, + including the list of leaked memory blocks and optionally with the + source locations where these were allocated. It is always a very + good idea to define this in development builds. This works with + _any_ program linked to FreeType, but requires a big deal of + memory (the debugging memory manager never frees the blocks to the + heap in order to detect double frees). - When FT2_DEBUG_MEMORY isn't defined at runtime, the debugging + When `FT2_DEBUG_MEMORY' isn't defined at runtime, the debugging memory manager is ignored, and performance is unaffected. + FT_DEBUG_LOGGING + + #define this macro for enhanced logging support; it automatically + sets `FT_DEBUG_LEVEL_TRACE' and `FT_DEBUG_LEVEL_ERROR'. + + If defined, `FT_TRACE' and `FT_ERROR' can send tracing and + debugging messages to a file. The location of the log file has to + be set with the `FT_LOGGING_FILE' environment variable (more on + this later). + + The main enhancements are the possibility of logging the time and + the name of the `FT_COMPONENT' macro together with the affected + `FT_TRACE' or `FT_ERROR' calls. See below how to activate this in + the `FT2_DEBUG' environment variable. + II. Debugging macros -------------------- @@ -55,10 +70,10 @@ debugging its code: 1. FT_ERROR(( ... )) This macro is used to send debug messages that indicate relatively - serious errors (like broken font files), but will not stop the + serious errors (like broken font files) without stopping the execution of the running program. Its code is compiled only when - either FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE are defined in - `ftoption.h'. + either `FT_DEBUG_LEVEL_ERROR' or `FT_DEBUG_LEVEL_TRACE' are + defined in `ftoption.h'. Note that you have to use a printf-like signature, but with double parentheses, like in @@ -69,53 +84,53 @@ debugging its code: 2. FT_ASSERT( condition ) This macro is used to check strong assertions at runtime. If its - condition isn't TRUE, the program will abort with a panic message. - Its code is compiled when either FT_DEBUG_LEVEL_ERROR or - FT_DEBUG_LEVEL_TRACE are defined. You don't need double - parentheses here. For example + condition isn't TRUE, the program aborts with a panic message. + Its code is compiled when either `FT_DEBUG_LEVEL_ERROR' or + `FT_DEBUG_LEVEL_TRACE' are defined. You don't need double + parentheses here. Example: FT_ASSERT( ptr != NULL ); 3. FT_TRACE( level, (message...) ) - The FT_TRACE macro is used to send general-purpose debugging + The `FT_TRACE' macro is used to send general-purpose debugging messages during program execution. This macro uses an *implicit* - macro named FT_COMPONENT used to name the current FreeType + macro named `FT_COMPONENT', which names the current FreeType component being run. - The developer should always define FT_COMPONENT as appropriate, + The developer should always define `FT_COMPONENT' as appropriate, for example as in #undef FT_COMPONENT #define FT_COMPONENT io - The value of the FT_COMPONENT macro is one of the component - names defined in the internal file `internal/fttrace.h'. If you - modify FreeType source and insert new FT_COMPONENT macro, you must - register it in `fttrace.h'. If you insert or remove many trace - macros, you can check the undefined or the unused trace macro by - `src/tools/chktrcmp.py'. + The value of the `FT_COMPONENT' macro is one of the component + names defined in the internal file `internal/fttrace.h'. If you + modify the FreeType source code and insert a new `FT_COMPONENT' + macro, you must register it in `fttrace.h'. If you insert or + remove many trace macros, you can test for undefined or unused + trace macros with the script `src/tools/chktrcmp.py'. - Each such component is assigned a `debug level', ranging from 0 to - 7, through the use of the FT2_DEBUG environment variable - (described below) when a program linked with FreeType starts. + Each such component is assigned a `debug level', ranging from + value 0 to 7, through the use of the `FT2_DEBUG' environment + variable (described below) when a program linked with FreeType + starts. - When FT_TRACE is called, its level is compared to the one of the + When `FT_TRACE' is called, its level is compared to the one of the corresponding component. Messages with trace levels *higher* than - the corresponding component level are filtered and never printed. - - This means that trace messages with level 0 are always printed, - those with level 2 are only printed when the component level is - *at least* 2. + the corresponding component level are filtered out and never + printed. This means that trace messages with level 0 are always + printed, those with level 2 are only printed when the component + level is *at least* 2, etc. - The second parameter to FT_TRACE must contain parentheses and - correspond to a printf-like call, as in + The second parameter to `FT_TRACE' must contain parentheses and + corresponds to a printf-like call, as in FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) ) - The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2, ..., - FT_TRACE7 can be used with constant level indices, and are much + The shortcut macros `FT_TRACE0', `FT_TRACE1', `FT_TRACE2', ..., + `FT_TRACE7' can be used with constant level indices, and are much cleaner to use, as in FT_TRACE2(( "your %s is not %s\n", "foo", "bar" )); @@ -131,7 +146,7 @@ behaviour of FreeType at runtime. FT2_DEBUG This variable is only used when FreeType is built with - FT_DEBUG_LEVEL_TRACE defined. It contains a list of component + `FT_DEBUG_LEVEL_TRACE' defined. It contains a list of component level definitions, following this format: component1:level1 component2:level2 component3:level3 ... @@ -140,57 +155,149 @@ behaviour of FreeType at runtime. in `fttrace.h'. `levelX' is the corresponding level to use at runtime. - `any' is a special component name that will be interpreted as - `any/all components'. For example, the following definitions + `any' is a special component name that is interpreted as `any/all + components'. For example, the following definitions set FT2_DEBUG=any:2 memory:5 io:4 (on Windows) export FT2_DEBUG="any:2 memory:5 io:4" (on Linux with bash) both stipulate that all components should have level 2, except for - the memory and io components which will be set to trace levels 5 + the memory and io components, which are set to the trace levels 5 and 4, respectively. + If `FT_DEBUG_LOGGING' is defined, two more options are available. + + * -v: Print also the name of FreeType's component from which the + current log is produced, together with the tracing level. + + * -t: Print also the time. + + Here are some examples how the output might look like. + + FT2_DEBUG="any:7 memory:5 -vt" + + => [20:32:02:44969 ttload:2] table directory loaded + + FT2_DEBUG="any:7 memory:5 -t" + + => [20:32:02:44969] table directory loaded + + FT2_DEBUG="any:7 memory:5 -v" + + => [ttload:2] table directory loaded + + + FT_LOGGING_FILE + + This variable is only used if FreeType is built with the + `FT_DEBUG_LOGGING' macro defined. It contains the path to the + file where the user wants to put his log file. If it is not set, + FreeType uses stderr. + + Examples: + + On UNIX-like systems with bash: + export FT_LOGGING_FILE="/tmp/freetype2.log" + + On Windows: + set FT_LOGGING_FILE=C:\Users\AppData\Local\Temp\freetype2.log + FT2_DEBUG_MEMORY This environment variable, when defined, tells FreeType to use a - debugging memory manager that will track leaking memory blocks as - well as other common errors like double frees. It is also capable - of reporting _where_ the leaking blocks were allocated, which + debugging memory manager that tracks leaking memory blocks as well + as other common errors like double frees. It is also capable of + reporting _where_ the leaking blocks were allocated, which considerably saves time when debugging new additions to the library. This code is only compiled when FreeType is built with the - FT_DEBUG_MEMORY macro #defined in `ftoption.h' though, it will be + `FT_DEBUG_MEMORY' macro #defined in `ftoption.h' though, it is ignored in other builds. FT2_ALLOC_TOTAL_MAX - This variable is ignored if FT2_DEBUG_MEMORY is not defined. It + This variable is ignored if `FT2_DEBUG_MEMORY' is not defined. It allows you to specify a maximum heap size for all memory allocations performed by FreeType. This is very useful to test the robustness of the font engine and programs that use it in tight memory conditions. - If it is undefined, or if its value is not strictly positive, then - no allocation bounds are checked at runtime. + If it is undefined, or if its value is not strictly positive, no + allocation bounds are checked at runtime. FT2_ALLOC_COUNT_MAX - This variable is ignored if FT2_DEBUG_MEMORY is not defined. It + This variable is ignored if `FT2_DEBUG_MEMORY' is not defined. It allows you to specify a maximum number of memory allocations performed by FreeType before returning the error - FT_Err_Out_Of_Memory. This is useful for debugging and testing + `FT_Err_Out_Of_Memory'. This is useful for debugging and testing the engine's robustness. - If it is undefined, or if its value is not strictly positive, then - no allocation bounds are checked at runtime. + If it is undefined, or if its value is not strictly positive, no + allocation bounds are checked at runtime. + + + FT2_KEEP_ALIVE + + This variable is ignored if `FT2_DEBUG_MEMORY' is not defined. + `Keep alive' means that freed blocks aren't released to the heap. + This is useful to detect double-frees or weird heap corruption, + reporting the source code location of the original allocation and + deallocation in case of a problem. It uses large amounts of + memory, however. + + If it is undefined, or if its value is not strictly positive, + freed blocks are released at runtime. + + +IV. Additional Capabilities with `FT_DEBUG_LOGGING' +--------------------------------------------------- + +If `FT_DEBUG_LOGGING' is defined, four APIs are available to provide +additional debugging support. Use + + #include <freetype/ftlogging.h> + +to access them. + + FT_Trace_Set_Level( const char* level ) + + By default, FreeType uses the tracing levels set in the + `FT2_DEBUG' environment variable. Use this function to override + the value with `level'. Use value `NULL' to disable tracing. + + FT_Trace_Set_Default_Level( void ) + + Reset the tracing levels to the default value, i.e., the value of + the `FT2_DEBUG' environment variable or no tracing if not set. + + FT_Set_Log_Handler( ft_custom_log_handler handler ) + + Use `handler' as a custom handler for formatting tracing and error + messages. The `ft_custom_log_handler' typedef has the following + prototype. + + void + (*ft_custom_log_handler)( const char* ft_component, + const char* fmt, + va_list args ); + + `ft_component' is the current component like `ttload', `fmt' is the + first argument of `FT_TRACE' or `FT_ERROR', and `args' holds the + remaining arguments. + + FT_Set_Default_Log_Handler( void ) + + Reset the log handler to the default version. + ------------------------------------------------------------------------ -Copyright (C) 2002-2019 by +Copyright (C) 2002-2023 by David Turner, Robert Wilhelm, and Werner Lemberg. This file is part of the FreeType project, and may only be used, |