游戏客户端架构 / 系统课时
绘制调试图形
绘制调试图形
本课将把坐标轴、AABB 边界框、圆形碰撞体和方向辅助线直接叠加到场景中,并建立可开关、只在调试阶段生效的绘制入口,最终得到一套不干扰正式渲染的最小调试绘制方案。
学习目标
- 理解调试图形在渲染流程中的正确位置
- 绘制坐标轴、边界框、碰撞体和辅助线
- 为调试绘制增加开关并验证坐标转换
调试图形应该放在哪里
调试图形应作为独立渲染通道执行:先绘制正式场景,再在同一相机坐标系中叠加辅助线,最后退出世界坐标并绘制界面。它只读取实体和碰撞数据,不修改物理状态,也不进入正式资源与材质流程。

所有世界空间图形都应放在相机变换内部。这样缩放、平移或跟随目标时,调试线会与实体保持重合;屏幕提示文字则应放在相机变换之外,避免随场景一起移动。
实现最小调试绘制
下面示例使用 raylib 创建窗口,并在按下 F1 时切换调试图形。代码同时绘制坐标轴、边界框、圆形碰撞体和方向线,适合作为引擎中 DebugRenderer 的最小原型。
#include "raylib.h"
int main() {
SetConfigFlags(FLAG_MSAA_4X_HINT);
InitWindow(960, 540, "Debug Draw");
SetTargetFPS(60);
Camera2D camera{};
camera.offset = {480.0f, 270.0f};
camera.target = {0.0f, 0.0f};
camera.zoom = 1.0f;
const Vector2 entityPosition{80.0f, 40.0f};
bool debugEnabled = true;
while (!WindowShouldClose()) {
if (IsKeyPressed(KEY_F1)) {
debugEnabled = !debugEnabled;
}
const Vector2 mouseWorld =
GetScreenToWorld2D(GetMousePosition(), camera);
BeginDrawing();
ClearBackground(Color{24, 27, 33, 255});
BeginMode2D(camera);
DrawCircleV(entityPosition, 12.0f, BLUE);
if (debugEnabled) {
// 坐标轴与实体边界都使用世界坐标。
DrawLineEx({-400.0f, 0.0f}, {400.0f, 0.0f}, 2.0f, RED);
DrawLineEx({0.0f, -240.0f}, {0.0f, 240.0f}, 2.0f, GREEN);
Rectangle aabb{
entityPosition.x - 50.0f,
entityPosition.y - 30.0f,
100.0f,
60.0f
};
DrawRectangleLinesEx(aabb, 2.0f, YELLOW);
DrawCircleLines(
static_cast<int>(entityPosition.x),
static_cast<int>(entityPosition.y),
38.0f,
SKYBLUE
);
// 辅助线用于观察实体朝向或目标位置。
DrawLineEx(entityPosition, mouseWorld, 1.5f, RAYWHITE);
}
EndMode2D();
DrawText(
debugEnabled ? "F1: debug draw ON" : "F1: debug draw OFF",
16,
16,
20,
RAYWHITE
);
EndDrawing();
}
CloseWindow();
return 0;
}已安装 raylib 后,在 Linux 或 macOS 中可使用 pkg-config 编译:
g++ debug_draw.cpp -std=c++17 -o debug_draw $(pkg-config --cflags --libs raylib)
./debug_draw预期结果:
窗口中显示蓝色实体;开启调试绘制时可见红绿坐标轴、黄色边界框、青色碰撞圆和指向鼠标的白色辅助线。按 F1 后这些辅助图形消失,再按一次恢复。处理缩放与发布版本
相机缩放后,世界空间中的线宽也会被缩放。若希望调试线始终保持近似固定的屏幕粗细,可将线宽除以 camera.zoom,并为极小缩放值设置下限,避免除零或线条突然变粗。
正式构建中不应持续提交调试绘制命令。可以使用编译宏、构建配置或运行时总开关关闭入口;同时保留分类开关,例如只显示碰撞体、寻路网格或相机边界,避免复杂场景一次绘制过多辅助信息。
验收与常见错误
验收时先移动或缩放相机,确认边界框始终贴合实体;再关闭调试开关,确认正式画面不受影响。若辅助图形出现偏移,优先检查是否把世界坐标当成屏幕坐标,或在退出相机变换后才绘制。
调试绘制只负责可视化已有数据。不要在绘制函数中更新碰撞范围、改变实体位置或创建长期资源,否则同一状态可能因是否开启调试模式而产生不同结果。
本课总结
- 调试图形应在正式场景之后、界面之前独立叠加
- 世界空间图形必须与实体共享同一相机变换
- 调试入口应可分类开关,并在发布构建中关闭
下一课预告
下一课将使用 AddressSanitizer 和资源所有权分析,定位悬空引用、重复释放与资源泄漏等内存问题。