debug.h

#include <modkit/debug.h>38 functions · 2 enums · 2 typedefs · 19 macros

Debug mode, overlay text, console logging, and debug primitives.

Provides a comprehensive debug system with:Debug mode flags (wireframe, FPS, stats, console, etc.)VGA-style debug text overlay using embedded bitmap fontConsole logging with stdout output and in-game overlayDebug primitives for bounding boxes, lights, etc.

Functions

mk_console_clearfunction

void mk_console_clear(void)

Clear console buffer.

mk_console_set_log_levelfunction

void mk_console_set_log_level(mk_log_level_t level)

Set minimum log level for console output.

Messages below this level are not shown in console (but still go to stdout).

Parameter	Type	Description
level	mk_log_level_t	Minimum level to display

mk_console_set_max_linesfunction

void mk_console_set_max_lines(int lines)

Set maximum number of lines in console buffer.

Parameter	Type	Description
lines	int	Number of lines (default 100)

mk_console_showfunction

void mk_console_show(bool show)

Show or hide console.

Parameter	Type	Description
show	bool	true to show, false to hide

mk_console_togglefunction

void mk_console_toggle(void)

Toggle console visibility.

mk_console_visiblefunction

bool mk_console_visible(void)

Check if console is visible.

Returns true if visible

mk_debug_clearfunction

void mk_debug_clear(uint8_t attr)

Clear debug text buffer.

Parameter	Type	Description
attr	uint8_t	Background attribute to fill with (use MK_DEBUG_ATTR(bg, 0))

mk_debug_disablefunction

void mk_debug_disable(uint32_t flags)

Disable specific debug flags (AND NOT with current).

Parameter	Type	Description
flags	uint32_t	Flags to disable

mk_debug_enablefunction

void mk_debug_enable(uint32_t flags)

Enable specific debug flags (OR with current).

Parameter	Type	Description
flags	uint32_t	Flags to enable

mk_debug_getfunction

uint32_t mk_debug_get(void)

Get current debug flags.

Returns Current flags

mk_debug_get_font_scalefunction

float mk_debug_get_font_scale(void)

Get the current debug font scale multiplier.

Default is 2.0 (16x16 pixel glyphs at 1x DPI).

Returns The resulting value.

mk_debug_get_fpsfunction

float mk_debug_get_fps(void)

Get current FPS (frames per second).

Returns rolling average over last 60 frames.

Returns The resulting value.

mk_debug_get_frame_time_msfunction

float mk_debug_get_frame_time_ms(void)

Get current frame time in milliseconds.

Returns rolling average over last 60 frames.

Returns The resulting value.

mk_debug_get_frame_time_rangefunction

void mk_debug_get_frame_time_range(float *min_ms, float *max_ms)

Get min/max frame times over recent history.

Parameter	Type	Description
min_ms	float *	Output: minimum frame time in ms (can be NULL)
max_ms	float *	Output: maximum frame time in ms (can be NULL)

mk_debug_get_text_sizefunction

void mk_debug_get_text_size(uint16_t *cols, uint16_t *rows)

Get debug text buffer dimensions in character cells.

Parameter	Type	Description
cols	uint16_t *	Output: number of columns (can be NULL)
rows	uint16_t *	Output: number of rows (can be NULL)

mk_debug_initfunction

mk_result mk_debug_init(void)

Initialize the debug.

Returns MK_SUCCESS or an error result.

mk_debug_is_enabledfunction

bool mk_debug_is_enabled(uint32_t flag)

Check if a specific debug flag is enabled.

Parameter	Type	Description
flag	uint32_t	Single flag to check

Returns true if enabled

mk_debug_load_fontfunction

mk_result mk_debug_load_font(const char *path)

Load a custom BDF or PSF bitmap font for debug text overlay.

Replaces the built-in default font (Terminus 8x14). Font width is always 8 pixels; height comes from the font file. Can also be set via the MK_DEBUG_FONT environment variable (checked at init).

Parameter	Type	Description
path	const char *	Path to .bdf or .psf font file

Returns MK_SUCCESS or error code

mk_debug_load_font_memfunction

mk_result mk_debug_load_font_mem(const void *data, uint32_t size, const char *name_hint)

Load a custom BDF or PSF bitmap font from memory.

Parameter	Type	Description
data	const void *	Raw font file data
size	uint32_t	Size of data in bytes
name_hint	const char *	Filename hint for format detection (may be NULL)

Returns MK_SUCCESS or error code

mk_debug_printfunction

void mk_debug_print(uint16_t x, uint16_t y, uint8_t attr, const char *text)

Print debug text at character position (no formatting).

Position is relative to the main window's safe area.

Parameter	Type	Description
x	uint16_t	Column position
y	uint16_t	Row position
attr	uint8_t	Color attribute
text	const char *	Text string to display

mk_debug_printffunction

void mk_debug_printf(uint16_t x, uint16_t y, uint8_t attr, const char *fmt,...)

Print formatted debug text at character position.

Position is in character cells relative to the main window's safe area. Text is rendered when MK_DEBUG_TEXT flag is enabled.

Parameter	Type	Description
x	uint16_t	Column position (0 = left edge)
y	uint16_t	Row position (0 = top edge)
attr	uint8_t	Color attribute (use MK_DEBUG_ATTR(bg, fg))
fmt	const char *	Printf-style format string
	...	—

mk_debug_renderfunction

void mk_debug_render(uint16_t width, uint16_t height)

Perform the debug render operation.

Parameter	Type	Description
width	uint16_t	Value for width.
height	uint16_t	Value for height.

mk_debug_reset_fontfunction

void mk_debug_reset_font(void)

Reset debug text to the built-in VGA 8x16 font.

Frees any previously loaded custom font data.

mk_debug_reset_statsfunction

void mk_debug_reset_stats(void)

Reset frame time statistics.

mk_debug_screenshotfunction

mk_result mk_debug_screenshot(const char *path)

Take a screenshot and save to file.

If path is NULL, generates timestamped filename in current directory.

Parameter	Type	Description
path	const char *	Output file path (NULL for auto-generated name)

Returns MK_SUCCESS or error code

mk_debug_setfunction

void mk_debug_set(uint32_t flags)

Set debug flags (replaces current flags).

Parameter	Type	Description
flags	uint32_t	Combination of MK_DEBUG_* flags

mk_debug_set_font_scalefunction

void mk_debug_set_font_scale(float scale)

Set the debug font scale multiplier.

Clamped to [0.5, 8.0]. Triggers text buffer recalculation.

Parameter	Type	Description
scale	float	Scale multiplier (1.0 = 8x8, 2.0 = 16x16, etc.)

mk_debug_shutdownfunction

void mk_debug_shutdown(void)

Perform the debug shutdown operation.

mk_debug_togglefunction

void mk_debug_toggle(uint32_t flags)

Toggle specific debug flags (XOR with current).

Parameter	Type	Description
flags	uint32_t	Flags to toggle

mk_debug_updatefunction

void mk_debug_update(float delta_time)

Update debug.

Parameter	Type	Description
delta_time	float	Value for delta time.

mk_logfunction

void mk_log(mk_log_level_t level, const char *fmt,...)

Log a message with specified level.

Outputs to both stdout (with ANSI colors) and overlay console.

Parameter	Type	Description
level	mk_log_level_t	Log level
fmt	const char *	Printf-style format string
	...	—

mk_log_debugfunction

void mk_log_debug(const char *fmt,...)

Log a debug message.

Parameter	Type	Description
fmt	const char *	Value for fmt.
	...	—

mk_log_errorfunction

void mk_log_error(const char *fmt,...)

Log an error message.

Parameter	Type	Description
fmt	const char *	Value for fmt.
	...	—

mk_log_get_levelfunction

mk_log_level_t mk_log_get_level(void)

Get the current minimum stdout log level.

Returns The resulting handle or value.

mk_log_infofunction

void mk_log_info(const char *fmt,...)

Log an info message.

Parameter	Type	Description
fmt	const char *	Value for fmt.
	...	—

mk_log_set_levelfunction

void mk_log_set_level(mk_log_level_t level)

Set the minimum level for stdout log output.

Messages below this level are not printed to stdout (default MK_LOG_TRACE = show everything). This is independent of the overlay console threshold (mk_console_set_log_level). Also configurable at startup via the MK_LOG_LEVEL env var, e.g. MK_LOG_LEVEL=warn (accepts trace|debug|info|warn|error|off, or 0-4). An explicit mk_log_set_level() call overrides the env var.

Parameter	Type	Description
level	mk_log_level_t	Value for level.

mk_log_tracefunction

void mk_log_trace(const char *fmt,...)

Log a trace message.

Parameter	Type	Description
fmt	const char *	Value for fmt.
	...	—

mk_log_warnfunction

void mk_log_warn(const char *fmt,...)

Log a warning message.

Parameter	Type	Description
fmt	const char *	Value for fmt.
	...	—

Enums

mk_debug_flagsenum

Debug mode flags (bitmask).

Use with mk_debug_set(), mk_debug_enable(), mk_debug_disable(), mk_debug_toggle().

Value	Description
MK_DEBUG_NONE	Selects none.
MK_DEBUG_TEXT	Enable debug text overlay.
MK_DEBUG_WIREFRAME	Enable wireframe rendering.
MK_DEBUG_FPS	Display FPS counter.
MK_DEBUG_STATS	Display render stats.
MK_DEBUG_PRIMITIVES	Enable debug primitive drawing.
MK_DEBUG_CONSOLE	Enable overlay console.
MK_DEBUG_PROFILER	Show profiler status (Tracy).
MK_DEBUG_RENDERDOC	Show RenderDoc status, F11 to capture.
MK_DEBUG_GPU_INSPECTOR	Permit on-demand GPU inspector snapshots.
MK_DEBUG_ALL	Selects all.

mk_log_levelenum

Log levels for mk_log().

Value	Description
MK_LOG_TRACE	Detailed tracing.
MK_LOG_DEBUG	Debug information.
MK_LOG_INFO	General information.
MK_LOG_WARN	Warning messages.
MK_LOG_ERROR	Error messages.

Typedefs

mk_debug_flags_ttypedef

typedef enum mk_debug_flags mk_debug_flags_t

Debug mode flags (bitmask).

Use with mk_debug_set(), mk_debug_enable(), mk_debug_disable(), mk_debug_toggle().

mk_log_level_ttypedef

typedef enum mk_log_level mk_log_level_t

Log levels for mk_log().

Macros

MK_DEBUG_ATTRdefine

MK_DEBUG_ATTR(bg, fg)

Create debug text color attribute.

MK_DEBUG_ATTR_Tdefine

MK_DEBUG_ATTR_T(fg)

Create attribute with transparent background.

MK_DEBUG_BLACKdefine

MK_DEBUG_BLACK

Constant for debug black.

MK_DEBUG_BLUEdefine

MK_DEBUG_BLUE

Constant for debug blue.

MK_DEBUG_BROWNdefine

MK_DEBUG_BROWN

Constant for debug brown.

MK_DEBUG_CYANdefine

MK_DEBUG_CYAN

Constant for debug cyan.

MK_DEBUG_DARKGRAYdefine

MK_DEBUG_DARKGRAY

Constant for debug darkgray.

MK_DEBUG_GREENdefine

MK_DEBUG_GREEN

Constant for debug green.

MK_DEBUG_LIGHTBLUEdefine

MK_DEBUG_LIGHTBLUE

Constant for debug lightblue.

MK_DEBUG_LIGHTCYANdefine

MK_DEBUG_LIGHTCYAN

Constant for debug lightcyan.

MK_DEBUG_LIGHTGRAYdefine

MK_DEBUG_LIGHTGRAY

Constant for debug lightgray.

MK_DEBUG_LIGHTGREENdefine

MK_DEBUG_LIGHTGREEN

Constant for debug lightgreen.

MK_DEBUG_LIGHTMAGENTAdefine

MK_DEBUG_LIGHTMAGENTA

Constant for debug lightmagenta.

MK_DEBUG_LIGHTREDdefine

MK_DEBUG_LIGHTRED

Constant for debug lightred.

MK_DEBUG_MAGENTAdefine

MK_DEBUG_MAGENTA

Constant for debug magenta.

MK_DEBUG_NOBGdefine

MK_DEBUG_NOBG

Transparent background (no visible background behind text).

MK_DEBUG_REDdefine

MK_DEBUG_RED

Constant for debug red.

MK_DEBUG_WHITEdefine

MK_DEBUG_WHITE

Constant for debug white.

MK_DEBUG_YELLOWdefine

MK_DEBUG_YELLOW

Constant for debug yellow.