游戏客户端架构 / 系统课时

绘制调试图形

绘制调试图形

本课将把坐标轴、AABB 边界框、圆形碰撞体和方向辅助线直接叠加到场景中,并建立可开关、只在调试阶段生效的绘制入口,最终得到一套不干扰正式渲染的最小调试绘制方案。

学习目标

  • 理解调试图形在渲染流程中的正确位置
  • 绘制坐标轴、边界框、碰撞体和辅助线
  • 为调试绘制增加开关并验证坐标转换

调试图形应该放在哪里

调试图形应作为独立渲染通道执行:先绘制正式场景,再在同一相机坐标系中叠加辅助线,最后退出世界坐标并绘制界面。它只读取实体和碰撞数据,不修改物理状态,也不进入正式资源与材质流程。

调试图形叠加关系

所有世界空间图形都应放在相机变换内部。这样缩放、平移或跟随目标时,调试线会与实体保持重合;屏幕提示文字则应放在相机变换之外,避免随场景一起移动。

实现最小调试绘制

下面示例使用 raylib 创建窗口,并在按下 F1 时切换调试图形。代码同时绘制坐标轴、边界框、圆形碰撞体和方向线,适合作为引擎中 DebugRenderer 的最小原型。

cpp
#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 编译:

bash
g++ debug_draw.cpp -std=c++17 -o debug_draw $(pkg-config --cflags --libs raylib)
./debug_draw

预期结果:

text
窗口中显示蓝色实体;开启调试绘制时可见红绿坐标轴、黄色边界框、青色碰撞圆和指向鼠标的白色辅助线。按 F1 后这些辅助图形消失,再按一次恢复。

处理缩放与发布版本

相机缩放后,世界空间中的线宽也会被缩放。若希望调试线始终保持近似固定的屏幕粗细,可将线宽除以 camera.zoom,并为极小缩放值设置下限,避免除零或线条突然变粗。

正式构建中不应持续提交调试绘制命令。可以使用编译宏、构建配置或运行时总开关关闭入口;同时保留分类开关,例如只显示碰撞体、寻路网格或相机边界,避免复杂场景一次绘制过多辅助信息。

验收与常见错误

验收时先移动或缩放相机,确认边界框始终贴合实体;再关闭调试开关,确认正式画面不受影响。若辅助图形出现偏移,优先检查是否把世界坐标当成屏幕坐标,或在退出相机变换后才绘制。

调试绘制只负责可视化已有数据。不要在绘制函数中更新碰撞范围、改变实体位置或创建长期资源,否则同一状态可能因是否开启调试模式而产生不同结果。

本课总结

  • 调试图形应在正式场景之后、界面之前独立叠加
  • 世界空间图形必须与实体共享同一相机变换
  • 调试入口应可分类开关,并在发布构建中关闭

下一课预告

下一课将使用 AddressSanitizer 和资源所有权分析,定位悬空引用、重复释放与资源泄漏等内存问题。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

绘制调试图形

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通