1  /****************************************************************************
       2   *
       3   * ftlogging.h
       4   *
       5   *   Additional debugging APIs.
       6   *
       7   * Copyright (C) 2020-2023 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 */