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)
 }