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

* include/freetype/ftlogging.h: New header file.

* include/freetype/internal/ftdebug.h [FT_LOGGING]: Include
`ftlogging.h`.

* src/base/ftdebug.c (ft_custom_trace_level): New variable.
(ft_debug_init): Update to support 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.

5 files changed, 163 insertions, 2 deletions

diff --git a/ChangeLog b/ChangeLog
index 7ab4f5014..f3f113ebd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,22 @@
 2020-11-28  Priyesh Kumar  <priyeshkkumar@gmail.com>
 
+	[base] Add public API to change the levels of tracing components.
+
+	* include/freetype/ftlogging.h: New header file.
+
+	* include/freetype/internal/ftdebug.h [FT_LOGGING]: Include
+	`ftlogging.h`.
+
+	* src/base/ftdebug.c (ft_custom_trace_level): New variable.
+	(ft_debug_init): Update to support 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.
+
+2020-11-28  Priyesh Kumar  <priyeshkkumar@gmail.com>
+
 	[base] Updates to print timestamp and name of `FT_COMPONENT` in logs.
 
 	* include/freetype/internal/ftdebug.h (FT_LOGGING_TAG,
diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h
index 2a41fca05..4f32cc88c 100644
--- a/include/freetype/ftchapters.h
+++ b/include/freetype/ftchapters.h
@@ -124,6 +124,7 @@
    *   gzip
    *   lzw
    *   bzip2
+   *   debugging_apis
    *
    */
 
diff --git a/include/freetype/ftlogging.h b/include/freetype/ftlogging.h
new file mode 100644
index 000000000..6f5c4f04b
--- /dev/null
+++ b/include/freetype/ftlogging.h
@@ -0,0 +1,102 @@
+/****************************************************************************
+ *
+ * ftlogging.h
+ *
+ *   Additional debugging APIs.
+ *
+ * Copyright (C) 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:
+   *   Public APIs to control the `FT_LOGGING` macro.
+   *
+   * @description:
+   *   This section contains the declarations of public functions that
+   *   enables fine control of what the `FT_LOGGING` macro outputs.
+   *
+   */
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Trace_Set_Level
+   *
+   * @description:
+   *   Change the levels of tracing components of FreeType at run time.
+   *
+   * @input:
+   *   tracing_level ::
+   *     New tracing value.
+   *
+   * @example:
+   *   The following call makes FreeType trace everything but the 'memory'
+   *   component.
+   *
+   *   ```
+   *   FT_Trace_Set_Level( "any:7 memory:0 );
+   *   ```
+   *
+   * @note:
+   *   This function is only available if compilation option `@FT_LOGGING`
+   *   is set.
+   */
+  FT_EXPORT( void )
+  FT_Trace_Set_Level( const char*  tracing_level );
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Trace_Set_Default_Level
+   *
+   * @description:
+   *   Reset tracing value of FreeType's components to the default value
+   *   (i.e., to the value of the `FT2_DEBUG` environment value or to NULL
+   *   if `FT2_DEBUG` is not set).
+   *
+   *
+   * @note:
+   *   This function is only available if compilation option `@FT_LOGGING`
+   *   is set.
+   */
+  FT_EXPORT( void )
+  FT_Trace_Set_Default_Level( void );
+
+  /* */
+
+
+FT_END_HEADER
+
+#endif /* FTLOGGING_H_ */
+
+
+/* END */
diff --git a/include/freetype/internal/ftdebug.h b/include/freetype/internal/ftdebug.h
index 666c26d58..8fe88464b 100644
--- a/include/freetype/internal/ftdebug.h
+++ b/include/freetype/internal/ftdebug.h
@@ -34,7 +34,9 @@
 #ifdef FT_LOGGING
 #include <../src/dlg/dlg/dlg.h>
 #include <../src/dlg/dlg/output.h>
-#endif
+
+#include <freetype/ftlogging.h>
+#endif /* FT_LOGGING */
 
 
 FT_BEGIN_HEADER
diff --git a/src/base/ftdebug.c b/src/base/ftdebug.c
index e422bc284..f8d5f034d 100644
--- a/src/base/ftdebug.c
+++ b/src/base/ftdebug.c
@@ -68,6 +68,9 @@
    * 6. `ft_have_newline_char` is used to differentiate between a log
    *    message with and without a trailing newline character.
    *
+   * 7. `ft_custom_trace_level` stores the custom trace level value, which
+   *    is provided by the user at run-time.
+   *
    * We use `static` to avoid 'unused variable' warnings.
    *
    */
@@ -77,6 +80,7 @@
   static FT_Bool      ft_component_flag      = FALSE;
   static FT_Bool      ft_timestamp_flag      = FALSE;
   static FT_Bool      ft_have_newline_char   = TRUE;
+  static const char*  ft_custom_trace_level  = NULL;
 
   dlg_handler  ft_default_log_handler = NULL;
 
@@ -232,8 +236,17 @@
   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
 
     if ( ft2_debug )
     {
@@ -479,6 +492,32 @@
     dlg_remove_tag( tag, NULL );
   }
 
+
+  /* documentation is in ftlogging.h */
+
+  FT_EXPORT_DEF( void )
+  FT_Trace_Set_Level( const char*  level )
+  {
+    ft_component_flag     = FALSE;
+    ft_timestamp_flag     = FALSE;
+    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     = FALSE;
+    ft_timestamp_flag     = FALSE;
+    ft_custom_trace_level = NULL;
+
+    ft_debug_init();
+  }
+
 #endif /* FT_LOGGING */