AnvilKit

概述

DebugRenderer 提供即时模式的线框调试绘制功能，用于可视化碰撞边界、射线、生成点和其他空间数据。所有图元以着色线段的形式渲染，每帧使用单次 LineList 绘制调用。

v0.3 变更： LineRenderer 在 v0.3 中已合并到 DebugRenderer。独立的 LineRenderer 类型不再存在。所有线段绘制需求请使用 DebugRenderer::draw_line()。

该渲染器由 anvilkit-render crate 提供：

use anvilkit_render::renderer::debug_renderer::DebugRenderer;

每帧的调试顶点数上限为 MAX_DEBUG_VERTICES（65,536）。超出部分会被静默截断。

DebugDrawCommand

DebugDrawCommand 是一个枚举，表示四种支持的图元类型：

变体	字段	说明
`Line`	`start: Vec3`, `end: Vec3`, `color: [f32; 4]`	单条线段
`Box`	`center: Vec3`, `half_extents: Vec3`, `color: [f32; 4]`	线框盒（12 条边）
`Sphere`	`center: Vec3`, `radius: f32`, `color: [f32; 4]`, `segments: u32`	线框球体（3 个轴对齐圆环）
`Point`	`position: Vec3`, `color: [f32; 4]`, `size: f32`	以三轴十字形渲染的点

DebugRenderer API

方法	签名	说明
`new`	`(device: &RenderDevice) -> Self`	创建新的调试渲染器，分配 GPU 缓冲区并编译线段着色器管线
`draw_line`	`(&mut self, start: Vec3, end: Vec3, color: [f32; 4])`	将一条线段加入队列
`draw_box`	`(&mut self, center: Vec3, half_extents: Vec3, color: [f32; 4])`	将一个线框盒加入队列
`draw_sphere`	`(&mut self, center: Vec3, radius: f32, color: [f32; 4], segments: u32)`	将一个线框球体加入队列（最少 8 段）
`draw_point`	`(&mut self, position: Vec3, color: [f32; 4], size: f32)`	将一个点加入队列（给定半臂长度的三轴十字形）
`prepare`	`(&mut self)`	将所有队列中的命令转换为线段顶点，在 `MAX_DEBUG_VERTICES` 处截断
`render`	`(&self, device: &RenderDevice, encoder: &mut CommandEncoder, target_view: &TextureView, depth_view: &TextureView, view_proj: &[[f32; 4]; 4])`	上传顶点并在单次 pass 中渲染所有调试线段
`clear`	`(&mut self)`	清除所有命令和顶点
`command_count`	`(&self) -> usize`	累计的绘制命令数量
`vertex_count`	`(&self) -> usize`	`prepare()` 后的线段顶点数量

用法示例

use anvilkit_render::renderer::debug_renderer::DebugRenderer;
use glam::Vec3;

fn debug_draw_system(debug: &mut DebugRenderer) {
    // 绘制红色线段
    debug.draw_line(
        Vec3::ZERO,
        Vec3::new(10.0, 0.0, 0.0),
        [1.0, 0.0, 0.0, 1.0],
    );

    // 绘制绿色包围盒
    debug.draw_box(
        Vec3::new(5.0, 1.0, 5.0),
        Vec3::new(1.0, 1.0, 1.0),
        [0.0, 1.0, 0.0, 1.0],
    );

    // 绘制蓝色球体
    debug.draw_sphere(
        Vec3::new(0.0, 3.0, 0.0),
        2.0,
        [0.0, 0.0, 1.0, 1.0],
        16,
    );

    // 绘制白色点
    debug.draw_point(
        Vec3::new(0.0, 5.0, 0.0),
        [1.0, 1.0, 1.0, 1.0],
        0.1,
    );
}

// 在渲染循环中：
debug.prepare();
debug.render(&device, &mut encoder, &target_view, &depth_view, &view_proj);
debug.clear();

DebugVertex 格式

每个调试顶点是一个 #[repr(C)] 结构体，适合通过 bytemuck 上传到 GPU：

字段	类型	偏移	着色器位置	说明
`position`	`[f32; 3]`	0	0	世界空间位置
`color`	`[f32; 4]`	12	1	RGBA 颜色

每个顶点总步长：28 字节。顶点缓冲区布局使用 VertexStepMode::Vertex。

调试渲染器

概述

DebugDrawCommand

DebugRenderer API

用法示例

DebugVertex 格式

目录