[freetype2] priyesh_LogLibrary 4f472b5: * include/freetype/ftlogging.h (FT_Trace_Set_Level): Use more relevant

[Priyesh Kumar]

branch: priyesh_LogLibrary
commit 4f472b5799642f0111c276a961d3133e7a145412
Author: Priyeshkkumar <priyeshkkumar@gmail.com>
Commit: Priyeshkkumar <priyeshkkumar@gmail.com>

        * include/freetype/ftlogging.h (FT_Trace_Set_Level): Use more relevant
        parameters name in function declaration.
        (FT_Custom_Log_Handler): Changed function name `ft_custom_log_handler'->
        `FT_Custom_Log_Handler'.
        Updated documentation.
    
        * include/freetype/ftchapters.h: Added `debugging_apis' section under
        `support_api' chapter.
    
        * .gitmodules: Updated submodule to track recent changes in dlg library.
    
        * src/base/ftdebug.c (ft_log_handler): Updated code according to the
        recent updates in dlg library.
        (ft_logging_init): Added environment variable `FT_LOGGING_FILE', the
        variable `ft_fileptr' stores it's value.
        Changed function name `ft_custom_log_handler'->
        `FT_Custom_Log_Handler'.
    
        * include/freetype/internal/ftdebug.h: Changed function name
        `ft_custom_log_handler'-> `FT_Custom_Log_Handler'.
    
        * README.git: Updated documentation.
    
        * docs/DEBUG: Updated documentation.
---
 .gitmodules                         |   1 -
 README.git                          |   7 ++
 [priyesh]ChangeLog                  |  27 +++++++
 docs/DEBUG                          | 116 +++++++++++++++++++++++++++++
 include/freetype/ftchapters.h       |   1 +
 include/freetype/ftlogging.h        | 143 ++++++++++++++++++++++++++++++------
 include/freetype/internal/ftdebug.h |   2 +-
 src/base/ftdebug.c                  |  38 +++-------
 submodules/dlg                      |   2 +-
 9 files changed, 284 insertions(+), 53 deletions(-)

diff --git a/.gitmodules b/.gitmodules
index 3b47f17..c02c831 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,4 +1,3 @@
-
 [submodule "submodules/dlg"]
        path = submodules/dlg
        url = https://github.com/nyorain/dlg.git
diff --git a/README.git b/README.git
index c4f0033..3b8338a 100644
--- a/README.git
+++ b/README.git
@@ -35,6 +35,13 @@ Similarly, a  build with  `cmake' can  be done  directly 
from  the git
 repository.
 
 
+For using the `FT_LOGGING' macro while debugging(see docs/DEBUG for 
+more information) use the following git commands to checkout `dlg' 
+library as a git submodule.
+
+  git submodule init
+  git submodule update
+
 ----------------------------------------------------------------------
 
 Copyright (C) 2005-2020 by
diff --git a/[priyesh]ChangeLog b/[priyesh]ChangeLog
index f5e1ddf..a8b1ae5 100644
--- a/[priyesh]ChangeLog
+++ b/[priyesh]ChangeLog
@@ -1,3 +1,30 @@
+2020-08-24  Priyesh Kumar  <priyeshkkumar@gmail.com>
+
+    * include/freetype/ftlogging.h (FT_Trace_Set_Level): Use more relevant
+    parameters name in function declaration. 
+    (FT_Custom_Log_Handler): Changed function name `ft_custom_log_handler'->
+    `FT_Custom_Log_Handler'. 
+    Updated documentation.
+
+    * include/freetype/ftchapters.h: Added `debugging_apis' section under 
+    `support_api' chapter.
+
+    * .gitmodules: Updated submodule to track recent changes in dlg library.
+
+    * src/base/ftdebug.c (ft_log_handler): Updated code according to the 
+    recent updates in dlg library.
+    (ft_logging_init): Added environment variable `FT_LOGGING_FILE', the 
+    variable `ft_fileptr' stores it's value.
+    Changed function name `ft_custom_log_handler'->
+    `FT_Custom_Log_Handler'. 
+
+    * include/freetype/internal/ftdebug.h: Changed function name 
+    `ft_custom_log_handler'-> `FT_Custom_Log_Handler'. 
+
+    * README.git: Updated documentation.
+
+    * docs/DEBUG: Updated documentation. 
+
 2020-08-21  Priyesh Kumar  <priyeshkkumar@gmail.com>
 
     * include/freetype/internal/ftdebug.h (FT_LOG ): Use more relevant
diff --git a/docs/DEBUG b/docs/DEBUG
index a96b5e2..49365ba 100644
--- a/docs/DEBUG
+++ b/docs/DEBUG
@@ -26,6 +26,33 @@ located in the file `ftoption.h'.  The macros are:
     appropriate  `debug level'  is configured  at runtime  through the
     `FT2_DEBUG' environment variable (more on this later).
 
+  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  with name `freetype2.log' will be
+    generated in the same directory where the executable is placed.  
+
+    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).
+    
+  
   FT_DEBUG_MEMORY
 
     If this  macro is #defined, the  FreeType engine is linked  with a
@@ -150,6 +177,31 @@ 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
+
 
   FT2_DEBUG_MEMORY
 
@@ -201,6 +253,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
diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h
index 2ee2697..833d75d 100644
--- a/include/freetype/ftchapters.h
+++ b/include/freetype/ftchapters.h
@@ -123,6 +123,7 @@
    *   gzip
    *   lzw
    *   bzip2
+   *   debugging_apis
    *
    */
 
diff --git a/include/freetype/ftlogging.h b/include/freetype/ftlogging.h
index 21ffb49..e5bc647 100644
--- a/include/freetype/ftlogging.h
+++ b/include/freetype/ftlogging.h
@@ -1,47 +1,144 @@
-#include FT_CONFIG_CONFIG_H
+/****************************************************************************
+ *
+ * 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
 
- /***************************************************************************
-  * 
-  * If FT_LOGGING is enabled, user can change the trace level at run time 
-  * using the function `FT_Trace_Set_Level()` by passing the desired trace
-  * level as an argument.
-  * User can also set the default trace level which is supplied by 
-  * environment variable `FT2_DEBUG`
-  * See ftdebug.c for definitions
-  * 
-  */ 
+  /**************************************************************************
+   *
+   * @section:
+   *   debugging_apis
+   *
+   * @title:
+   *   External Debugginng APIs
+   *
+   * @abstract:
+   *   Pubic APIs to use while debugging using `FT_LOGGING' macro
+   *
+   * @description:
+   *   This section contains the  declaration  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 at run time.
+   *
+   * @input:
+   * 
+   *   tracing_level ::
+   *     New levels of of tracing components. 
+   *
+   * @example:
+   *   This function can be used to change the tracing levels of  FreeType's
+   *   component as follows:
+   *
+   *   ```
+   *     new_levels  = "any:7 memory:0";
+   *     FT_Trace_Set_Level( new_levels );
+   *   ```
+   */
   FT_EXPORT( void )
-  FT_Trace_Set_Level( const char* level );
+  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
+   *   values of the tracing components of  FreeType, this function could
+   *   be  used to reset the level of  tracing  components to the default
+   *   value.
+   *
+   */
   FT_EXPORT( void )
   FT_Trace_Set_Default_Level( void );
 
 
-  /* An external callback function to be used to define an output handler */
+  /**************************************************************************
+   *
+   * @functype:
+   *   FT_Custom_Log_Handler
+   *
+   * @description:
+   *   A function used  to  handle the logging of tracing and debug messages
+   *   on a file system. 
+   *
+   * @input:
+   *   ft_component ::
+   *     The name of `FT_COMPONENT' from  which  the  current debug or error
+   *     message is produced. 
+   *
+   *   fmt ::
+   *     Actual debug or tracing message.
+   * 
+   *   args::
+   *     Arguments of debug or tracing messages.
+   *     
+   */
   typedef void 
-  (*ft_custom_log_handler)( const char* ft_component, const char* fmt, 
+  (*FT_Custom_Log_Handler)( const char* ft_component, const char* fmt, 
                             va_list args ); 
 
 
   /**************************************************************************
+   *
+   * @function:
+   *   FT_Set_Log_Handler
+   *
+   * @description:
+   *   A function to set a custom log handler
+   * 
+   * @input:
    * 
-   * If FT_LOGGING is enabled user can provide their own function to handle 
-   * the log messages using the function `FT_Set_Log_Handler()` by passing 
-   * the function name which they want to use.
-   * User could also revert back to use FreeType's inbuilt function to 
-   * handle logs using function `FT_Set_Default_Log_Handler()` 
-   * Defined in src/base/ftdebug.c
-   *
-   */ 
+   *   handler ::
+   *     New logging function 
+   *
+   */
   FT_EXPORT( void )
-  FT_Set_Log_Handler( ft_custom_log_handler handler ); 
+  FT_Set_Log_Handler( FT_Custom_Log_Handler handler ); 
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Set_Default_Log_Handler
+   *
+   * @description:
+   *   If previously, `FT_Set_Log_Handler'  functions is used  to set new
+   *   custom logging function, this API could be  used to reset the back 
+   *   the log handler to FreeType's inbuilt log handler.
+   *
+   */
 
   FT_EXPORT( void )
   FT_Set_Default_Log_Handler( void );
diff --git a/include/freetype/internal/ftdebug.h 
b/include/freetype/internal/ftdebug.h
index 96da630..2c9b41a 100644
--- a/include/freetype/internal/ftdebug.h
+++ b/include/freetype/internal/ftdebug.h
@@ -388,7 +388,7 @@ ft_remove_tag( const char* tag );
    * 
    * These are defined in ftdebug.c
    */ 
-  extern ft_custom_log_handler custom_output_handler;
+  extern FT_Custom_Log_Handler custom_output_handler;
   extern dlg_handler ft_default_log_handler;
 
   /**************************************************************************
diff --git a/src/base/ftdebug.c b/src/base/ftdebug.c
index 3e6b67a..68fb039 100644
--- a/src/base/ftdebug.c
+++ b/src/base/ftdebug.c
@@ -79,25 +79,9 @@
   static bool ft_timestamp_flag = false;
   static bool ft_have_newline_char = true;
 
-  ft_custom_log_handler custom_output_handler = NULL;
+  FT_Custom_Log_Handler custom_output_handler = NULL;
   dlg_handler ft_default_log_handler = NULL;
 
-  /* different types of dlg features to be used according to the flags     */
-  /* passed in FT2_DEBUG environment variable                              */
-
-  static unsigned int features_component = dlg_output_threadsafe 
-                                          | dlg_output_tags;
-  static unsigned int features_timestamp = dlg_output_threadsafe 
-                                          | dlg_output_time
-                                          | dlg_output_time_msecs; 
-  static unsigned int features_both = dlg_output_threadsafe 
-                                      | dlg_output_time_msecs 
-                                      |dlg_output_time
-                                      | dlg_output_tags ;
-  static unsigned int features_none = dlg_output_threadsafe;
-
-
-
 #endif
 
 
@@ -428,7 +412,7 @@ else
   {
     ft_default_log_handler = ft_log_handler;
     ft_default_trace_level = ft_getenv( "FT2_DEBUG" );
-    ft_fileptr = fopen( "freetype2.log", "w" );
+    ft_fileptr = fopen( ft_getenv( "FT_LOGGING_FILE" ), "w" );
     
     ft_debug_init();
     /* We need to set the default FreeType specific dlg's output handler */
@@ -452,19 +436,19 @@ else
                               const char* string, void* data )
   {
     ( void ) data;
-     static unsigned int features ;
+     const char* features ;
      if( ft_timestamp_flag && ft_component_flag && ft_have_newline_char )
-      features = features_both;
+      features = "[%h:%m  %t]    %c";
      else if( ft_component_flag && ft_have_newline_char)
-      features = features_component;
+      features = "[%t]    %c";
      else if( ft_timestamp_flag && ft_have_newline_char )
-      features = features_timestamp;
+      features = "[%t]    %c";
      else
-      features = features_none;
+      features = "%c";
+
+          dlg_generic_outputf_stream( ft_fileptr, features, origin, string, 
+                                dlg_default_output_styles, true );
 
-      
-          dlg_generic_output_stream( ft_fileptr, features, origin, string, 
-                                dlg_default_output_styles );
 
      if( strchr( string, '\n' ) )
        ft_have_newline_char = true;   
@@ -509,7 +493,7 @@ else
  */
   
   FT_EXPORT_DEF( void )
-  FT_Set_Log_Handler( ft_custom_log_handler handler )
+  FT_Set_Log_Handler( FT_Custom_Log_Handler handler )
   {
     custom_output_handler = handler;
   }
diff --git a/submodules/dlg b/submodules/dlg
index 407e385..a489761 160000
--- a/submodules/dlg
+++ b/submodules/dlg
@@ -1 +1 @@
-Subproject commit 407e385d2e40e11a1f1643cdf698fd09d62561ca
+Subproject commit a4897614699fb8e76f23a2d50a63b4d674e39f90