@ -44,6 +44,32 @@ located in the file `ftoption.h'. The macros are:
When `FT2_DEBUG_MEMORY' isn't defined at runtime, the debugging
memory manager is ignored, and performance is unaffected.
FT_LOGGING
As mentioned above if `FT_DEBUG_LEVEL_ERROR' and
`FT_DEBUG_LEVEL_TRACE' macros are defined, FreeType will send the
debug and trace logs outputted from `FT_ERROR' and `FT_TRACE'
macros to `stderr'.
`FT_LOGGING' is a new macro which is introduced to enhance the
capabilities of `FT_TRACE' and `FT_ERROR' macros.
`FT_LOGGING' macro depends on `FT_DEBUG_LEVEL_TRACE' and
`FT_DEBUG_LEVEL_ERROR', therefore these macros will automatically
be #defined once `FT_LOGGING' macro is #defined and
the behaviour of `FT_TRACE' and `FT_ERROR' macros will change.
Now, `FT_TRACE' and `FT_ERROR' macros will start sending the
tracing and debugging messages to the file system instead of
`stderr'.
On the file system the log file will be generated on the path
specified using `FT_LOGGING_FILE' environment variable(more on
this later).
There is an additional support of logging Time and the name of
the `FT_COMPONENT' from which the current log is generated along
with the actual tracing and debugging message, and for this user
will have to define additional tags under the `FT2_DEBUG'
environment variable(More details under section `FT2_DEBUG' under
Environment Variables heading).
II. Debugging macros
--------------------
@ -150,6 +176,48 @@ behaviour of FreeType at runtime.
the memory and io components, which are set to the trace levels 5
and 4, respectively.
`FT_LOGGING' related tags:
As mentioned above in the `FT_LOGGING' section below are the
additional tags which can be added in `FT2_DEBUG' environment
variable to log the time and the value of `FT_COMPONENT' in the
actual log message:
* -v: For printing the name of FreeType's component from which
the current log is produced.
* -t: For printing the time(in milliseconds) along with actual
log message.
Example:
Case 1: FT2_DEBUG="any:7 memory:5 -vt"
[20:32:02:44969 ttload] table directory loaded
Case 2: FT2_DEBUG="any:7 memory:5 -t"
[20:32:02:44969 ttload] table directory loaded
Case 3: FT2_DEBUG="any:7 memory:5 -v"
[ttload] table directory loaded
FT_LOGGING_FILE
This variable is only used when FreeType is built with
`FT_LOGGING' macro defined. It contains the path to the file where
the user wants to put his log file.
On Linux with bash:
export FT_LOGGING_FILE="/tmp/freetype2.log"
On Windows:
set FT_LOGGING_FILE=C:\Users\AppData\Local\Temp\freetype2.log
Use the following `FT_LOGGING_FILE' value to print logs to stderr.
export FT_LOGGING_FILE=/dev/stderr
FT2_DEBUG_MEMORY
@ -201,6 +269,70 @@ behaviour of FreeType at runtime.
If it is undefined, or if its value is not strictly positive,
freed blocks are released at runtime.
IV. Additional Capabilities with `FT_LOGGING'
--------------------------------------------
With the support of `FT_LOGGING', four APIs have been introduced for
providing additional debugging support to the applications using
FreeType.
FT_Trace_Set_Level( const char* )
If FreeType is configured with `FT_LOGGING' the levels of tracing
component set using `FT2_DEBUG' environment variable is considered
as a default value.
And this function can be used change/set the value of the levels
of tracing components at run-time.
NOTE: If the environment variable `FT2_DEBUG is not defined the
default value of the levels of tracing components will be NULL.
FT_Trace_Set_Default_Level():
If previously, `FT_Trace_Set_Level' functions is used to set new
values of the tracing components of FreeType, this function could
be used to reset the level of tracing components to the default
value.
Hence, the functions `FT_Trace_Set_Default_Level' and
`FT_Trace_Set_Level' could be combined and used together to
change the trace levels of FreeType's components for a particular
block of code.
FT_Set_Log_Handler( ft_custom_log_handler ):
This API has been provided under the `FT_LOGGING' macro to support
a feature wherein a custom log handler can be provided based on
user’s choice. Doing so, FreeType will start calling the custom
handler for new log messages and will no longer write these
messages in predefined log file of FreeType. It will totally
depend on user how the log messages will be handled.
User just need to call this API with an argument of type
ft_custom_log_handler which should match following function
prototype:
void (*ft_custom_log_handler)( const char* ft_component,
const char* fmt,
va_list args );
FT_Set_Default_Log_Handler():
If the user has chosen to set a custom log handler using the
`FT_Set_Log_Handler' API above, the current API can be used to
reset back the log handler to the Freetype's inbuilt log handler.
Hence, the functions `FT_Set_Default_Log_Handler' and
`FT_Set_Log_Handler' in combination can be used to separately
handle the trace or error logs generated by a particular block
of code.
Applications need to #include the following header file to avail the
above APIs:
#include<freetype/ftlogging.h>
------------------------------------------------------------------------
Copyright (C) 2002-2020 by
Priyeshkkumar
4 years ago