* include/freetype/ftlogging.h: New header file, it contains logging

related public APIs.

	[base] Added a public API to change the levels of tracing components.

	* src/base/ftdebug.c: Added new variables.
	(ft_debug_init): Updates to support the change of levels of tracing
	components of FreeType at run-time.
	(FT_Trace_Set_Level): New function to change the levels of tracing
	components at run-time.
	(FT_Trace_Set_Default_Level): New function to reset the levels of
	tracing components back to default.

	* include/freetype/ftchapters.h: Added `debugging_apis' section under
        `support_api' chapter.

include/freetype/ftchapters.h

@@ -123,6 +123,7 @@
    *   gzip
    *   lzw
    *   bzip2
+   *   debugging_apis
    *
    */
 

include/freetype/ftlogging.h

@@ -0,0 +1,89 @@
+/****************************************************************************
+ *
+ * ftlogging.h
+ *
+ *   Additional debugging APIs.
+ *
+ * Copyright (C) 2008-2020 by
+ * David Turner, Robert Wilhelm, and Werner Lemberg.
+ *
+ * This file is part of the FreeType project, and may only be used,
+ * modified, and distributed under the terms of the FreeType project
+ * license, LICENSE.TXT.  By continuing to use, modify, or distribute
+ * this file you indicate that you have read the license and
+ * understand and accept it fully.
+ *
+ */
+
+
+#ifndef FTLOGGING_H_
+#define FTLOGGING_H_
+
+#include <ft2build.h>
+#include FT_CONFIG_CONFIG_H
+
+FT_BEGIN_HEADER
+
+  /**************************************************************************
+   *
+   * @section:
+   *   debugging_apis
+   *
+   * @title:
+   *   External Debugging APIs
+   *
+   * @abstract:
+   *   Pubic APIs to use while debugging using `FT_LOGGING' macro
+   *
+   * @description:
+   *   This section contains the declaration of the public  APIs which can be
+   *   used to debug an application using `FT_LOGGING'.
+   *
+   */
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Trace_Set_Level
+   *
+   * @description:
+   *   To change the levels of tracing components of FreeType, at run time.
+   *
+   * @input:
+   *
+   *   tracing_level ::
+   *     New tracing values of FreeType's components.
+   *
+   * @example:
+   *   This function can be used to change the levels of tracing components
+   *   of FreeType as follows:
+   *
+   *   ```
+   *     new_levels  = "any:7 memory:0";
+   *     FT_Trace_Set_Level( new_levels );
+   *   ```
+   */
+  FT_EXPORT( void )
+  FT_Trace_Set_Level( const char* tracing_level );
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Trace_Set_Default_Level
+   *
+   * @description:
+   *   If previously, `FT_Trace_Set_Level'  functions is used  to set new
+   *   tracing values of FreeType components, this function could be  used to
+   *   reset the tracing values of FreeType's components to the default value.
+   *
+   */
+  FT_EXPORT( void )
+  FT_Trace_Set_Default_Level( void );
+
+  /* */
+
+FT_END_HEADER
+
+#endif /* FTLOGGING_H_ */

include/freetype/internal/ftdebug.h

@@ -41,6 +41,7 @@
 #ifdef FT_LOGGING
 #include <../src/dlg/dlg/dlg.h>
 #include <../src/dlg/dlg/output.h>
+#include <freetype/ftlogging.h>
 #endif /* FT_LOGGING */
 
 

src/base/ftdebug.c

@@ -66,6 +66,9 @@
    * 6. ft_have_newline_char: It is used to differentiate between a log
    *    message with '\n' char and log message without '\n' char
    *
+   * 7. ft_custom_trace_level: stores the value of custom trace level which
+   *    is provided by user at run-time.
+   *
    * Static Variables are defined here to remove [ -Wunused-variable ]
    * warning
    *
@@ -76,6 +79,7 @@
   static bool ft_component_flag = false;
   static bool ft_timestamp_flag = false;
   static bool ft_have_newline_char = true;
+  static const char* ft_custom_trace_level = NULL;
 
   dlg_handler ft_default_log_handler = NULL;
 
@@ -231,8 +235,18 @@
   FT_BASE_DEF( void )
   ft_debug_init( void )
   {
-    const char*  ft2_debug = ft_getenv( "FT2_DEBUG" );
+    const char*  ft2_debug = NULL;
+
+#ifdef FT_LOGGING
+
+if( ft_custom_trace_level != NULL )
+    ft2_debug = ft_custom_trace_level;
+else
+    ft2_debug = ft_default_trace_level;
 
+#else
+    ft2_debug = ft_getenv( "FT2_DEBUG" );
+#endif /* FT_LOGGIGN */
 
     if ( ft2_debug )
     {
@@ -460,6 +474,28 @@
     dlg_remove_tag( tag, NULL );
   }
 
+/* documentation is in ftlogging.h */
+
+  FT_EXPORT_DEF( void )
+  FT_Trace_Set_Level( const char* level )
+  {
+    ft_component_flag = NULL;
+    ft_timestamp_flag = NULL;
+    ft_custom_trace_level = level;
+    ft_debug_init();
+  }
+
+/* documentation is in ftlogging.h */
+
+  FT_EXPORT_DEF( void )
+  FT_Trace_Set_Default_Level( void )
+  {
+    ft_component_flag = NULL;
+    ft_timestamp_flag = NULL;
+    ft_custom_trace_level = NULL ;
+    ft_debug_init();
+  }
+
 #endif /* FT_LOGGING */
 
 /* END */