diff options
Diffstat (limited to 'src/3rdparty/freetype/docs/DEBUG')
| -rw-r--r-- | src/3rdparty/freetype/docs/DEBUG | 182 |
1 files changed, 92 insertions, 90 deletions
diff --git a/src/3rdparty/freetype/docs/DEBUG b/src/3rdparty/freetype/docs/DEBUG index 3d6acd3bb0..d8c79d187a 100644 --- a/src/3rdparty/freetype/docs/DEBUG +++ b/src/3rdparty/freetype/docs/DEBUG @@ -4,63 +4,63 @@ Debugging within the FreeType sources I. Configuration macros ----------------------- -There are several ways to enable debugging features in a FreeType 2 -builds. This is controlled through the definition of special macros +There are several ways to enable debugging features in a FreeType 2 +builds. This is controlled through the definition of special macros located in the file `ftoptions.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 will 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, + #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 + 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). FT_DEBUG_MEMORY - If this macro is #defined, the FreeType engine is linked with a - small but effective debugging memory manager that tracks all + If this macro is #defined, the FreeType engine is linked with a + 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 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 FT2_DEBUG_MEMORY isn't defined at runtime, the debugging memory - manager is ignored, and performance is unaffected. + When FT2_DEBUG_MEMORY isn't defined at runtime, the debugging + memory manager is ignored, and performance is unaffected. II. Debugging macros -------------------- -Several macros can be used within the FreeType sources to help debugging -its code: +Several macros can be used within the FreeType sources to help +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 - execution of the running program. Its code is compiled only when - either FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE are defined in + This macro is used to send debug messages that indicate relatively + serious errors (like broken font files), but will not stop 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'. - Note that you have to use a printf-like signature, but with double + Note that you have to use a printf-like signature, but with double parentheses, like in FT_ERROR(( "your %s is not %s\n", "foo", "bar" )); @@ -68,128 +68,130 @@ 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 + 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 FT_ASSERT( ptr != NULL ); 3. FT_TRACE( level, (message...) ) - 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 component - being run. + 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 + component being run. - The developer should always define FT_COMPONENT as appropriate, for - example as in + The developer should always define FT_COMPONENT as appropriate, + for example as in #undef FT_COMPONENT #define FT_COMPONENT trace_io - The value of the FT_COMPONENT macro is an enumeration named - trace_XXXX where XXXX is one of the component names defined in the - internal file `freetype/internal/fttrace.h'. If you modify FreeType - source and insert new trace_XXXX 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 an enumeration named + `trace_XXXX' where `XXXX' is one of the component names defined in + the internal file `internal/fttrace.h'. If you modify FreeType + source and insert new `trace_XXXX' 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'. - Each such component is assigned a `debug level', ranging from 0 - to 7, through the use of the FT2_DEBUG environment variable + 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. - When FT_TRACE is called, its level is compared to the one of the - corresponding component. Messages with trace levels *higher* than + 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. + 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 second parameter to FT_TRACE must contain parentheses and + The second parameter to FT_TRACE must contain parentheses and correspond 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 cleaner to - use, as in + 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" )); + FT_TRACE2(( "your %s is not %s\n", "foo", "bar" )); III. Environment variables -------------------------- -The following environment variables control debugging output and +The following environment variables control debugging output and 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 level - definitions, following this format: + This variable is only used when FreeType is built with + FT_DEBUG_LEVEL_TRACE defined. It contains a list of component + level definitions, following this format: - component1:level1 component2:level2 component3:level3 ... + component1:level1 component2:level2 component3:level3 ... - where `componentX' is the name of a tracing component, as defined in - `fttrace.h', but without the `trace_' prefix. `levelX' is the + where `componentX' is the name of a tracing component, as defined + in `fttrace.h', but without the `trace_' prefix. `levelX' is the corresponding level to use at runtime. - `any' is a special component name that will be interpreted as + `any' is a special component name that will be 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) + 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 and - 4, respectively. + both stipulate that all components should have level 2, except for + the memory and io components which will be set to trace levels 5 + and 4, respectively. 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 - considerably saves time when debugging new additions to the library. + 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 + 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 + This code is only compiled when FreeType is built with the + FT_DEBUG_MEMORY macro #defined in `ftoption.h' though, it will be ignored in other builds. FT2_ALLOC_TOTAL_MAX - 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. + 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 + If it is undefined, or if its value is not strictly positive, then no allocation bounds are checked at runtime. FT2_ALLOC_COUNT_MAX - 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 the - engine's robustness. + 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 + the engine's robustness. - If it is undefined, or if its value is not strictly positive, then + If it is undefined, or if its value is not strictly positive, then no allocation bounds are checked at runtime. ------------------------------------------------------------------------ -Copyright 2002, 2003, 2004, 2005, 2009 by +Copyright 2002-2005, 2009, 2013 by David Turner, Robert Wilhelm, and Werner Lemberg. This file is part of the FreeType project, and may only be used, |