概念：分级日志
XGE 内置了一个轻量级日志系统，支持 6 个级别。引擎内部的警告和错误都通过此系统输出。你也可以在自己的代码中使用它，获得统一的日志格式。
日志级别
| 常量 | 值 | 用途 |
|---|---|---|
XGE_LOG_TRACE | 0 | 最详细的跟踪信息（循环内每帧） |
XGE_LOG_DEBUG | 1 | 调试信息（开发时使用） |
XGE_LOG_INFO | 2 | 一般信息（启动、加载完成） |
XGE_LOG_WARN | 3 | 警告（可恢复的异常） |
XGE_LOG_ERROR | 4 | 错误（功能失败） |
XGE_LOG_FATAL | 5 | 致命错误（引擎无法继续） |
XGE_LOG_OFF | 6 | 关闭所有日志输出 |
API 速查
| 函数 | 说明 |
|---|---|
int xgeLogSetLevel(int iLevel) | 设置最低输出级别（低于此级别的日志被过滤） |
int xgeLogGetLevel(void) | 获取当前日志级别 |
int xgeLogWrite(int iLevel, const char* sTag, const char* sMessage) | 写入一条日志 |
int xgeLogFlush(void) | 刷新日志缓冲区到输出 |
编译本章示例
gcc -O2 -I. -o ch07.exe ch07_main.c build\xge.lib -lm -lws2_32 -liphlpapi -lgdi32 -luser32 -lshell32 -lopengl32 -lole32 -lwinmm -lavrt
.\ch07.exe示例：使用日志系统
#include "xge.h"
int main(void) {
// 设置日志级别为 DEBUG（显示 DEBUG 及以上）
xgeLogSetLevel(XGE_LOG_DEBUG);
// 写入不同级别的日志
xgeLogWrite(XGE_LOG_INFO, "App", "Application starting...");
xgeLogWrite(XGE_LOG_DEBUG, "Init", "Loading textures...");
xgeLogWrite(XGE_LOG_WARN, "GL", "Texture size exceeds recommended max");
xgeLogWrite(XGE_LOG_ERROR, "File", "Failed to load: assets/hero.png");
// TRACE 级别不会输出（当前级别为 DEBUG）
xgeLogWrite(XGE_LOG_TRACE, "Loop", "Frame 1"); // 被过滤
xgeLogFlush(); // 确保全部输出
// ... 初始化引擎 ...
return 0;
}
输出目标：日志默认输出到
stdout（控制台）。在 Windows GUI 应用中，如果没有控制台窗口，日志不可见。Debug 版本（xgedbg.dll）可能额外输出到 OutputDebugString。
典型用法：Release 中静默
// Release 构建中只显示警告和错误
#ifdef NDEBUG
xgeLogSetLevel(XGE_LOG_WARN);
#else
xgeLogSetLevel(XGE_LOG_TRACE); // Debug 全部显示
#endif要点与陷阱
- 日志级别是全局的——影响引擎内部和你的代码。设为
XGE_LOG_OFF可完全静默。 - sTag 用于分类——建议使用短标签如 "GL"、"Audio"、"UI"，便于 grep 过滤。
- 不要在帧回调中写 TRACE 日志——60 FPS × 日志 I/O = 性能灾难。仅在需要时临时开启。
- xgeLogFlush 的时机：日志可能有缓冲。在崩溃前调用 Flush 确保信息不丢失。
进阶练习
- 封装一个
LOG_INFO(tag, fmt, ...)宏，内部调用xgeLogWrite。 - 在帧回调中每 60 帧输出一次 FPS 日志（INFO 级别）。
- 将日志级别设为
XGE_LOG_OFF，验证引擎内部警告也不再输出。
xgeLogWrite，并用颜色区分 INFO、DEBUG、WARN 与 ERROR；可用 --frames 1 验证非交互运行。