freetype2/freetype/ftlogging.h

0001 /****************************************************************************
0002  *
0003  * ftlogging.h
0004  *
0005  *   Additional debugging APIs.
0006  *
0007  * Copyright (C) 2020-2023 by
0008  * David Turner, Robert Wilhelm, and Werner Lemberg.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017
0018
0019 #ifndef FTLOGGING_H_
0020 #define FTLOGGING_H_
0021
0022
0023 #include <ft2build.h>
0024 #include FT_CONFIG_CONFIG_H
0025
0026
0027 FT_BEGIN_HEADER
0028
0029
0030   /**************************************************************************
0031    *
0032    * @section:
0033    *   debugging_apis
0034    *
0035    * @title:
0036    *   External Debugging APIs
0037    *
0038    * @abstract:
0039    *   Public APIs to control the `FT_DEBUG_LOGGING` macro.
0040    *
0041    * @description:
0042    *   This section contains the declarations of public functions that
0043    *   enables fine control of what the `FT_DEBUG_LOGGING` macro outputs.
0044    *
0045    */
0046
0047
0048   /**************************************************************************
0049    *
0050    * @function:
0051    *   FT_Trace_Set_Level
0052    *
0053    * @description:
0054    *   Change the levels of tracing components of FreeType at run time.
0055    *
0056    * @input:
0057    *   tracing_level ::
0058    *     New tracing value.
0059    *
0060    * @example:
0061    *   The following call makes FreeType trace everything but the 'memory'
0062    *   component.
0063    *
0064    *   ```
0065    *   FT_Trace_Set_Level( "any:7 memory:0" );
0066    *   ```
0067    *
0068    * @note:
0069    *   This function does nothing if compilation option `FT_DEBUG_LOGGING`
0070    *   isn't set.
0071    *
0072    * @since:
0073    *   2.11
0074    *
0075    */
0076   FT_EXPORT( void )
0077   FT_Trace_Set_Level( const char*  tracing_level );
0078
0079
0080   /**************************************************************************
0081    *
0082    * @function:
0083    *   FT_Trace_Set_Default_Level
0084    *
0085    * @description:
0086    *   Reset tracing value of FreeType's components to the default value
0087    *   (i.e., to the value of the `FT2_DEBUG` environment value or to NULL
0088    *   if `FT2_DEBUG` is not set).
0089    *
0090    * @note:
0091    *   This function does nothing if compilation option `FT_DEBUG_LOGGING`
0092    *   isn't set.
0093    *
0094    * @since:
0095    *   2.11
0096    *
0097    */
0098   FT_EXPORT( void )
0099   FT_Trace_Set_Default_Level( void );
0100
0101
0102   /**************************************************************************
0103    *
0104    * @functype:
0105    *   FT_Custom_Log_Handler
0106    *
0107    * @description:
0108    *   A function typedef that is used to handle the logging of tracing and
0109    *   debug messages on a file system.
0110    *
0111    * @input:
0112    *   ft_component ::
0113    *     The name of `FT_COMPONENT` from which the current debug or error
0114    *     message is produced.
0115    *
0116    *   fmt ::
0117    *     Actual debug or tracing message.
0118    *
0119    *   args::
0120    *     Arguments of debug or tracing messages.
0121    *
0122    * @since:
0123    *   2.11
0124    *
0125    */
0126   typedef void
0127   (*FT_Custom_Log_Handler)( const char*  ft_component,
0128                             const char*  fmt,
0129                             va_list      args );
0130
0131
0132   /**************************************************************************
0133    *
0134    * @function:
0135    *   FT_Set_Log_Handler
0136    *
0137    * @description:
0138    *   A function to set a custom log handler.
0139    *
0140    * @input:
0141    *   handler ::
0142    *     New logging function.
0143    *
0144    * @note:
0145    *   This function does nothing if compilation option `FT_DEBUG_LOGGING`
0146    *   isn't set.
0147    *
0148    * @since:
0149    *   2.11
0150    *
0151    */
0152   FT_EXPORT( void )
0153   FT_Set_Log_Handler( FT_Custom_Log_Handler  handler );
0154
0155
0156   /**************************************************************************
0157    *
0158    * @function:
0159    *   FT_Set_Default_Log_Handler
0160    *
0161    * @description:
0162    *   A function to undo the effect of @FT_Set_Log_Handler, resetting the
0163    *   log handler to FreeType's built-in version.
0164    *
0165    * @note:
0166    *   This function does nothing if compilation option `FT_DEBUG_LOGGING`
0167    *   isn't set.
0168    *
0169    * @since:
0170    *   2.11
0171    *
0172    */
0173   FT_EXPORT( void )
0174   FT_Set_Default_Log_Handler( void );
0175
0176   /* */
0177
0178
0179 FT_END_HEADER
0180
0181 #endif /* FTLOGGING_H_ */
0182
0183
0184 /* END */