Debug Messages
--------------

The GFXprim library includes a debug message infrastructure in order to ease
the debugging.

Many places of the library uses debug messages to report warnings, bugs, or
generally important events (i.e. pixmap has been allocated, filter function
has been called).

Debug messages are printed into the stderr and could be redirected to custom
handler.

The verbosity of the messages could be changed by the debug level. The debug
level is an unsigned integer (by default set to '0') and only messages that have
debug level lower or equal to debug level are printed.

There are few special debug message types with negative debug level (that
means that they are always printed), and as so these are used on various error
conditions, see below for more information.

[source,c]
-------------------------------------------------------------------------------
#include <core/gp_debug.h>
/* or */
#include <gfxprim.h>

void gp_set_debug_level(unsigned int level);

unsigned int gp_get_debug_level(void);
-------------------------------------------------------------------------------

Sets or gets library debug level. The default level is '0' at which only
'FATAL', 'BUG', 'WARNING', 'TODO' and messages with debug level '0' are shown.

Increasing this number would cause the library to be more verbose in debugging
messages.

Setting debug level to '1' would expose debug messages when object was created
or destroyed or when particular algorithm has been started.

Setting debug level to value higher than '1' would expose even more verbose
messages the current maximum used by debug messages is '4'.

The debug level may also be set by setting the 'GP_DEBUG' environment
variable. In such case the debug level is set accordingly to its value when
first debug message is about to be printed.

[source,c]
-------------------------------------------------------------------------------
#include <core/gp_debug.h>
/* or */
#include <gfxprim.h>

GP_DEBUG(level, ...)

GP_TODO(...)

GP_WARN(...)

GP_BUG(...)

GP_FATAL(...)

void gp_debug_print(int level, const char *file, const char *function, int line,
                   const char *fmt, ...);
-------------------------------------------------------------------------------

Printf-like macros used to print debug messages. All of them calls the
'gp_debug_print()' function with slightly different parameters.

NOTE: 'gp_debug_print()' function preserves errno.

[source,c]
-------------------------------------------------------------------------------
enum gp_debug_type {
	GP_DEBUG_TODO  = -1,
	GP_DEBUG_WARN  = -2,
	GP_DEBUG_BUG   = -3,
	GP_DEBUG_FATAL = -4,
};

/*
 * Custom debug message handler structure.
 */
struct gp_debug_msg {
	int level;
	const char *file;
	const char *fn;
	unsigned int line;
	const char *msg;
};

/*
 * Sets custom debug message handler.
 *
 * If NULL is passed, custom handler is disabled and debug messages are printed
 * into the stderr.
 */
void gp_set_debug_handler(void (*handler)(const struct gp_debug_msg *msg));

-------------------------------------------------------------------------------

By default debug messages are printed into the stderr you can redirect them
to your debug handler by this function.

NOTE: For more information see debug message handler
      link:example_debug_handler.html[example].
