1 /**************************************************************************** 2 * 3 * ftlogging.h 4 * 5 * Additional debugging APIs. 6 * 7 * Copyright (C) 2020-2021 by 8 * David Turner, Robert Wilhelm, and Werner Lemberg. 9 * 10 * This file is part of the FreeType project, and may only be used, 11 * modified, and distributed under the terms of the FreeType project 12 * license, LICENSE.TXT. By continuing to use, modify, or distribute 13 * this file you indicate that you have read the license and 14 * understand and accept it fully. 15 * 16 */ 17 18 19 #ifndef FTLOGGING_H_ 20 #define FTLOGGING_H_ 21 22 23 #include <ft2build.h> 24 #include FT_CONFIG_CONFIG_H 25 26 27 FT_BEGIN_HEADER 28 29 30 /************************************************************************** 31 * 32 * @section: 33 * debugging_apis 34 * 35 * @title: 36 * External Debugging APIs 37 * 38 * @abstract: 39 * Public APIs to control the `FT_DEBUG_LOGGING` macro. 40 * 41 * @description: 42 * This section contains the declarations of public functions that 43 * enables fine control of what the `FT_DEBUG_LOGGING` macro outputs. 44 * 45 */ 46 47 48 /************************************************************************** 49 * 50 * @function: 51 * FT_Trace_Set_Level 52 * 53 * @description: 54 * Change the levels of tracing components of FreeType at run time. 55 * 56 * @input: 57 * tracing_level :: 58 * New tracing value. 59 * 60 * @example: 61 * The following call makes FreeType trace everything but the 'memory' 62 * component. 63 * 64 * ``` 65 * FT_Trace_Set_Level( "any:7 memory:0 ); 66 * ``` 67 * 68 * @note: 69 * This function does nothing if compilation option `FT_DEBUG_LOGGING` 70 * isn't set. 71 * 72 * @since: 73 * 2.11 74 * 75 */ 76 FT_EXPORT( void ) 77 FT_Trace_Set_Level( const char* tracing_level ); 78 79 80 /************************************************************************** 81 * 82 * @function: 83 * FT_Trace_Set_Default_Level 84 * 85 * @description: 86 * Reset tracing value of FreeType's components to the default value 87 * (i.e., to the value of the `FT2_DEBUG` environment value or to NULL 88 * if `FT2_DEBUG` is not set). 89 * 90 * @note: 91 * This function does nothing if compilation option `FT_DEBUG_LOGGING` 92 * isn't set. 93 * 94 * @since: 95 * 2.11 96 * 97 */ 98 FT_EXPORT( void ) 99 FT_Trace_Set_Default_Level( void ); 100 101 102 /************************************************************************** 103 * 104 * @functype: 105 * FT_Custom_Log_Handler 106 * 107 * @description: 108 * A function typedef that is used to handle the logging of tracing and 109 * debug messages on a file system. 110 * 111 * @input: 112 * ft_component :: 113 * The name of `FT_COMPONENT` from which the current debug or error 114 * message is produced. 115 * 116 * fmt :: 117 * Actual debug or tracing message. 118 * 119 * args:: 120 * Arguments of debug or tracing messages. 121 * 122 * @since: 123 * 2.11 124 * 125 */ 126 typedef void 127 (*FT_Custom_Log_Handler)( const char* ft_component, 128 const char* fmt, 129 va_list args ); 130 131 132 /************************************************************************** 133 * 134 * @function: 135 * FT_Set_Log_Handler 136 * 137 * @description: 138 * A function to set a custom log handler. 139 * 140 * @input: 141 * handler :: 142 * New logging function. 143 * 144 * @note: 145 * This function does nothing if compilation option `FT_DEBUG_LOGGING` 146 * isn't set. 147 * 148 * @since: 149 * 2.11 150 * 151 */ 152 FT_EXPORT( void ) 153 FT_Set_Log_Handler( FT_Custom_Log_Handler handler ); 154 155 156 /************************************************************************** 157 * 158 * @function: 159 * FT_Set_Default_Log_Handler 160 * 161 * @description: 162 * A function to undo the effect of @FT_Set_Log_Handler, resetting the 163 * log handler to FreeType's built-in version. 164 * 165 * @note: 166 * This function does nothing if compilation option `FT_DEBUG_LOGGING` 167 * isn't set. 168 * 169 * @since: 170 * 2.11 171 * 172 */ 173 FT_EXPORT( void ) 174 FT_Set_Default_Log_Handler( void ); 175 176 /* */ 177 178 179 FT_END_HEADER 180 181 #endif /* FTLOGGING_H_ */ 182 183 184 /* END */ 185