doc/debug.txt

   1 Debug Messages
   2 --------------
   3
   4 The GFXprim library includes a debug message infrastructure in order to ease
   5 the debugging.
   6
   7 Many places of the library uses debug messages to report warnings, bugs, or
   8 generally important events (i.e. pixmap has been allocated, filter function
   9 has been called).
  10
  11 Debug messages are printed into the stderr and could be redirected to custom
  12 handler.
  13
  14 The verbosity of the messages could be changed by the debug level. The debug
  15 level is an unsigned integer (by default set to '0') and only messages that have
  16 debug level lower or equal to debug level are printed.
  17
  18 There are few special debug message types with negative debug level (that
  19 means that they are always printed), and as so these are used on various error
  20 conditions, see below for more information.
  21
  22 [source,c]
  23 -------------------------------------------------------------------------------
  24 #include <core/GP_Debug.h>
  25 /* or */
  26 #include <GP.h>
  27
  28 void GP_SetDebugLevel(unsigned int level);
  29
  30 unsigned int GP_GetDebugLevel(void);
  31 -------------------------------------------------------------------------------
  32
  33 Sets or gets library debug level. The default level is '0' at which only
  34 'FATAL', 'BUG', 'WARNING', 'TODO' and messages with debug level '0' are shown.
  35
  36 Increasing this number would cause the library to be more verbose in debugging
  37 messages.
  38
  39 Setting debug level to '1' would expose debug messages when object was created
  40 or destroyed or when particular algorithm has been started.
  41
  42 Setting debug level to value higher than '1' would expose even more verbose
  43 messages the current maximum used by debug messages is '4'.
  44
  45 The debug level may also be set by setting the 'GP_DEBUG' environment
  46 variable. In such case the debug level is set accordingly to its value when
  47 first debug message is about to be printed.
  48
  49 [source,c]
  50 -------------------------------------------------------------------------------
  51 #include <core/GP_Debug.h>
  52 /* or */
  53 #include <GP.h>
  54
  55 GP_DEBUG(level, ...)
  56
  57 GP_TODO(...)
  58
  59 GP_WARN(...)
  60
  61 GP_BUG(...)
  62
  63 GP_FATAL(...)
  64
  65 void GP_DebugPrint(int level, const char *file, const char *function, int line,
  66                    const char *fmt, ...);
  67 -------------------------------------------------------------------------------
  68
  69 Printf-like macros used to print debug messages. All of them calls the
  70 'GP_DebugPrint()' function with slightly different parameters.
  71
  72 NOTE: 'GP_DebugPrint()' function preserves errno.
  73
  74 [source,c]
  75 -------------------------------------------------------------------------------
  76 enum GP_DebugType {
  77         GP_DEBUG_TODO  = -1,
  78         GP_DEBUG_WARN  = -2,
  79         GP_DEBUG_BUG   = -3,
  80         GP_DEBUG_FATAL = -4,
  81 };
  82
  83 /*
  84  * Custom debug message handler structure.
  85  */
  86 struct GP_DebugMsg {
  87         int level;
  88         const char *file;
  89         const char *fn;
  90         unsigned int line;
  91         const char *msg;
  92 };
  93
  94 /*
  95  * Sets custom debug message handler.
  96  *
  97  * If NULL is passed, custom handler is disabled and debug messages are printed
  98  * into the stderr.
  99  */
 100 void GP_SetDebugHandler(void (*handler)(const struct GP_DebugMsg *msg));
 101
 102 -------------------------------------------------------------------------------
 103
 104 By default debug messages are printed into the stderr you can redirect them
 105 to your debug handler by this function.
 106
 107 NOTE: For more information see debug message handler
 108       link:example_debug_handler.html[example].