Mercurial > molko
annotate libcore/core/debug.h @ 147:b386d25832c8
doc: use new nomenclature, closes #2497
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 15 Oct 2020 09:21:04 +0200 |
parents | c46f80820b42 |
children |
rev | line source |
---|---|
79
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
1 /* |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
2 * debug.h -- debugging interfaces |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
3 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
4 * Copyright (c) 2020 David Demelier <markand@malikania.fr> |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
5 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
6 * Permission to use, copy, modify, and/or distribute this software for any |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
7 * purpose with or without fee is hereby granted, provided that the above |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
8 * copyright notice and this permission notice appear in all copies. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
9 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
17 */ |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
18 |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
19 #ifndef MOLKO_DEBUG_H |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
20 #define MOLKO_DEBUG_H |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
21 |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
22 /** |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
23 * \file debug.h |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
24 * \brief Debugging interfaces. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
25 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
26 * This module provides functions to draw debugging information within the game |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
27 * window. It is mostly used for information only when state of the game is |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
28 * better inspected via direct window information rather than writing in the |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
29 * console. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
30 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
31 * Predefined core states may print debugging information if |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
32 * debug_options.enabled variable is set to true. However, you need to specify |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
33 * the font to use in order to work. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
34 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
35 * Each call to \ref debug_printf or \ref debug_vprintf automatically adjust |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
36 * next coordinate for rendering the text. As such, user may simply print |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
37 * several lines of text without having to deal with that manually. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
38 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
39 * Example, activate global debugging. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
40 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
41 * \code |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
42 * struct font *f = font_openf("foo.ttf", 10); |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
43 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
44 * if (!f) |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
45 * error_fatal(); |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
46 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
47 * debug_options.default_font = f; |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
48 * debug_options.enabled = true; |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
49 * \endcode |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
50 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
51 * Example, print debugging information manually. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
52 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
53 * \code |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
54 * struct debug_report report = { |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
55 * .color = 0x00ff00ff, |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
56 * .font = myfont // Optional if debug_options.default_font is set. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
57 * }; |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
58 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
59 * debug_printf("current position: %d, %d\n", x, y); |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
60 * \endcode |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
61 */ |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
62 |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
63 #include <stdbool.h> |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
64 #include <stdarg.h> |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
65 |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
66 #include "font.h" |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
67 |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
68 /** |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
69 * Maximum content length per report. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
70 */ |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
71 #define DEBUG_LINE_MAX 1024 |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
72 |
133
c46f80820b42
core: revamp debug using theme
David Demelier <markand@malikania.fr>
parents:
121
diff
changeset
|
73 struct theme; |
c46f80820b42
core: revamp debug using theme
David Demelier <markand@malikania.fr>
parents:
121
diff
changeset
|
74 |
79
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
75 /** |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
76 * \brief Debugging options. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
77 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
78 * Fill this structure with appropriate values to change debugging behavior |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
79 * in core API. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
80 */ |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
81 struct debug_options { |
147
b386d25832c8
doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents:
133
diff
changeset
|
82 bool enable; /*!< (+) Enable core API debugging. */ |
79
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
83 }; |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
84 |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
85 /** |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
86 * \brief Debug context. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
87 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
88 * Use this structure each time you need to print one or more messages. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
89 */ |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
90 struct debug_report { |
147
b386d25832c8
doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents:
133
diff
changeset
|
91 struct theme *theme; /*!< (+&?) Theme to use. */ |
b386d25832c8
doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents:
133
diff
changeset
|
92 unsigned long color; /*!< (+) Font foreground color to use. */ |
b386d25832c8
doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents:
133
diff
changeset
|
93 unsigned int count; /*!< (-) Number of messages already printed. */ |
79
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
94 }; |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
95 |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
96 /** |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
97 * Global debugging options. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
98 */ |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
99 extern struct debug_options debug_options; |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
100 |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
101 /** |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
102 * Convenient macro to initialize \ref debug_report with default values. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
103 */ |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
104 #define DEBUG_INIT_DEFAULTS { \ |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
105 .font = debug_options.default_font, \ |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
106 .color = debug_options.default_color, \ |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
107 .style = debug_options.default_style \ |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
108 } |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
109 |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
110 /** |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
111 * Print debugging information into the screen. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
112 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
113 * \pre report != NULL |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
114 * \pre fmt != NULL |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
115 * \param report the reporting context |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
116 * \param fmt the printf(3) format string |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
117 * \note The message length must not exceed DEBUG_LINE_MAX, otherwise its |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
118 * result is truncated. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
119 */ |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
120 void |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
121 debug_printf(struct debug_report *report, const char *fmt, ...); |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
122 |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
123 /** |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
124 * Similar to \ref debug_printf but with a va_list object. |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
125 * |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
126 * \see \ref debug_printf |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
127 */ |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
128 void |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
129 debug_vprintf(struct debug_report *report, const char *fmt, va_list ap); |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
130 |
8f95462ac5f8
core: create a debugging API, closes #2469 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
131 #endif /* !MOLKO_DEBUG_H */ |