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" ));
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,
projects / framework / graphics / freetype.git / blobdiff