Mercurial > molko
changeset 626:2c5514927166
ui: improve documentation (debug.h)
author | David Demelier <markand@malikania.fr> |
---|---|
date | Sat, 26 Aug 2023 10:35:53 +0200 |
parents | 20e9fd578b44 |
children | 29a121241485 |
files | examples/example-debug/example-debug.c libmlk-ui/mlk/ui/debug.c libmlk-ui/mlk/ui/debug.h |
diffstat | 3 files changed, 182 insertions(+), 22 deletions(-) [+] |
line wrap: on
line diff
--- a/examples/example-debug/example-debug.c Sat Aug 26 09:34:27 2023 +0200 +++ b/examples/example-debug/example-debug.c Sat Aug 26 10:35:53 2023 +0200 @@ -24,23 +24,65 @@ #include <mlk/core/painter.h> #include <mlk/core/panic.h> #include <mlk/core/state.h> +#include <mlk/core/texture.h> #include <mlk/core/util.h> +#include <mlk/ui/align.h> #include <mlk/ui/debug.h> +#include <mlk/ui/label.h> #include <mlk/ui/ui.h> #include <mlk/example/example.h> +static enum mlk_align align; static int mouse_x; static int mouse_y; +static struct mlk_label help = { + .text = "Keys: <Left>/<Right> arrows keys to change debug queue position." +}; + +/* + * Example of debug style drawing function to adjust position on the screen. + */ +static void +debug_draw(const char *line, unsigned int n) +{ + int x, y; + struct mlk_texture tex; + struct mlk_font *font; + unsigned long color; + unsigned int pad; + + font = &mlk_ui_fonts[MLK_UI_FONT_INTERFACE]; + color = mlk_debug_style.color; + pad = mlk_debug_style.padding; + + if (mlk_font_render(font, &tex, line, color) < 0) + mlk_panic(); + + /* Compute x position according to the user choice and text length. */ + mlk_align(align, &x, NULL, tex.w, tex.h, pad, 0, mlk_window.w - (pad * 2), 0); + + /* Compute y according to padding, n and text height. */ + y = (pad * (n + 1)) + (tex.h * n); + + mlk_texture_draw(&tex, x, y); + mlk_texture_finish(&tex); +} static void init(void) { + unsigned int w, h; + if (mlk_example_init("example-debug") < 0) mlk_panic(); + mlk_label_query(&help, &w, &h); + mlk_align(MLK_ALIGN_CENTER, &help.x, &help.y, w, h, 0, 0, mlk_window.w, mlk_window.h); + mlk_debug_options.enable = 1; + mlk_debug_style.draw = debug_draw; } static void @@ -53,6 +95,18 @@ mouse_x = ev->mouse.x; mouse_y = ev->mouse.y; break; + case MLK_EVENT_KEYDOWN: + switch (ev->key.key) { + case MLK_KEY_LEFT: + align = MLK_ALIGN_TOP_LEFT; + break; + case MLK_KEY_RIGHT: + align = MLK_ALIGN_TOP_RIGHT; + break; + default: + break; + } + break; case MLK_EVENT_QUIT: mlk_game_quit(); break; @@ -66,10 +120,11 @@ { (void)st; - struct mlk_debug_report report = {0}; + struct mlk_debug_report report = {}; mlk_painter_set_color(MLK_EXAMPLE_BG); mlk_painter_clear(); + mlk_label_draw(&help); mlk_debugf(&report, "Game running."); mlk_debugf(&report, "mouse: %d, %d", mouse_x, mouse_y); mlk_painter_present();
--- a/libmlk-ui/mlk/ui/debug.c Sat Aug 26 09:34:27 2023 +0200 +++ b/libmlk-ui/mlk/ui/debug.c Sat Aug 26 10:35:53 2023 +0200 @@ -24,6 +24,26 @@ #include "debug.h" #include "ui.h" +#include "ui_p.h" + +static void +draw(const char *line, unsigned int n) +{ + struct mlk_font *font; + struct mlk_texture tex; + int x, y; + + font = MLK__STYLE_FONT(mlk_debug_style.font, MLK_UI_FONT_INTERFACE); + + if (mlk_font_render(font, &tex, line, MLK_UI_COLOR_DEBUG) < 0) + return; + + x = mlk_debug_style.padding; + y = (mlk_debug_style.padding * (n + 1)) + (tex.h * n); + + mlk_texture_draw(&tex, x, y); + mlk_texture_finish(&tex); +} struct mlk_debug_options mlk_debug_options = { #if !defined(NDEBUG) @@ -33,15 +53,18 @@ #endif }; +struct mlk_debug_style mlk_debug_style = { + .color = MLK_UI_COLOR_DEBUG, + .padding = 10, + .draw = draw +}; + void mlk_debugf(struct mlk_debug_report *report, const char *fmt, ...) { assert(report); assert(fmt); - if (!mlk_debug_options.enable) - return; - va_list ap; va_start(ap, fmt); @@ -55,27 +78,15 @@ assert(report); assert(fmt); - char line[MLK_DEBUG_LINE_MAX]; - struct mlk_font *font; - struct mlk_texture tex; - int x, y; + char line[MLK_DEBUG_LINE_MAX] = {}; if (!mlk_debug_options.enable) return; vsnprintf(line, sizeof (line), fmt, ap); - // TODO: add style support. - font = &mlk_ui_fonts[MLK_UI_FONT_INTERFACE]; - - if (mlk_font_render(font, &tex, line, MLK_UI_COLOR_DEBUG) < 0) - return; + if (mlk_debug_style.draw) + mlk_debug_style.draw(line, report->count); - // TODO: same here. - x = 10; - y = (10 * (report->count + 1)) + (tex.h * (report->count)); report->count++; - - mlk_texture_draw(&tex, x, y); - mlk_texture_finish(&tex); }
--- a/libmlk-ui/mlk/ui/debug.h Sat Aug 26 09:34:27 2023 +0200 +++ b/libmlk-ui/mlk/ui/debug.h Sat Aug 26 10:35:53 2023 +0200 @@ -19,31 +19,125 @@ #ifndef MLK_UI_DEBUG_H #define MLK_UI_DEBUG_H +/** + * \file mlk/ui/debug.h + * \brief Debugging interfaces. + * + * This module provides simple functions to draw messages on the top of the + * screen aimed at showing debugging informations. It is simple by design as it + * should be just called in your draw function to render text with some style. + * + * In your draw loop, you have to re-use a ::mlk_debug_report object to count up + * how many lines the module has to draw. + * + * Example of use in draw function: + * + * ```c + * struct mlk_debug_report report = {}; + * + * mlk_debugf(&report, "Game running."); + * mlk_debugf(&report, "mouse: %d, %d", my_mouse_x, my_mouse_y); + * ``` + */ + #include <stdarg.h> #define MLK_DEBUG_LINE_MAX 256 -struct mlk_theme; +struct mlk_font; + +/** + * \struct mlk_debug_style + * \brief Controls the style to use. + */ +struct mlk_debug_style { + /** + * (read-write, borrowed, optional) + * + * Font to use, defaults to ::MLK_UI_FONT_INTERFACE. + */ + struct mlk_font *font; + + /** + * (read-write) + * + * Text color + */ + unsigned long color; + /** + * (read-write) + * + * Padding between elements and top left (x, y) coordinates. + */ + unsigned int padding; + + /** + * (read-write, optional) + * + * Custom drawing function. + * + * \param line the text line to show + * \param n the current line number + */ + void (*draw)(const char *line, unsigned int n); +}; + +/** + * \struct mlk_debug_options + * \brief Debug interface options. + */ struct mlk_debug_options { + /** + * (read-write) + * + * Enable the module at runtime, defauls to 1 if built as non-release + * which means with NDEBUG **not** set. + */ int enable; }; +/** + * \struct mlk_debug_report + * \brief Opaque data type to carry for each call. + */ struct mlk_debug_report { + /** \cond MLK_PRIVATE_DECLS */ unsigned int count; + /** \endcond MLK_PRIVATE_DECLS */ }; +/** + * \brief Global debugging options. + */ extern struct mlk_debug_options mlk_debug_options; +/** + * \brief Global style options. + */ +extern struct mlk_debug_style mlk_debug_style; + #if defined(__cplusplus) extern "C" { #endif +/** + * Render a debugging message using a printf(3) format string, no-op if + * ::mlk_debug_options::enable is zero. + * + * \pre report != NULL + * \pre fmt != NULL + * \param report opaque report object to pass across calls + * \param fmt the printf(3) format string + */ void -mlk_debugf(struct mlk_debug_report *, const char *, ...); +mlk_debugf(struct mlk_debug_report *report, const char *fmt, ...); +/** + * Similar to ::mlk_debugf but using a `va_list` instead. + */ void -mlk_debugva(struct mlk_debug_report *, const char *, va_list); +mlk_debugva(struct mlk_debug_report *report, const char *fmt, va_list ap); #if defined(__cplusplus) }