AnvilKit

anvilkit-render 是 AnvilKit 的核心渲染模块，基于 wgpu 0.19 提供统一的 2D/3D 渲染能力。

入口点

AnvilKit 提供两个代理友好的渲染 API，位于完整 PBR 管线之上：

Canvas2D — 即时模式 2D 绘图（矩形、文本、精灵）。最适合原型、UI 和 2D 游戏。AI 代理可通过 MCP 工具直接绘制。
Canvas3D — 场景图 3D API，支持 PBR 材质、光照和相机控制。代理可以生成对象、设置材质和捕获帧，无需接触底层管线。
帧捕获 — Canvas2D 和 Canvas3D 都支持 capture_frame()，返回渲染图像字节。这就是 AI 优先承诺的实现：代理能看到玩家所见。

如需完全控制，请使用下面描述的多通道 PBR 管线。

渲染管线

引擎每帧执行一个多通道 HDR 管线：

Scroll to zoom · Drag to pan · Click ⛶ for fullscreen

所有通道共享每帧一个 CommandEncoder，以实现最小的 CPU 开销。

v0.3 渲染重构

在 v0.3 中，大型单体文件被拆分为有组织的目录结构：

events.rs（1414 行）拆分为 events/ 目录：mod.rs、lighting.rs、render_app.rs、gpu_init.rs、render_loop.rs、input.rs
draw.rs（568 行）拆分为 draw/ 目录：mod.rs、culling.rs、lighting.rs、commands.rs、gpu.rs

共享工具（v0.3）

CachedBuffer：共享 GPU 缓冲区缓存工具，替代了之前分散在 ui/text/sprite/line/particle 渲染器中的 5 个重复 cached_vb 模式。
ProjectionUniform：共享类型，替代了 5 个重复的 64 字节正交/场景 uniform 结构体。
DebugRenderer 现在包含了 LineRenderer 功能（两者在 v0.3 中合并；参见调试渲染器）。

资源管理

RenderAssets 通过 Handle 系统管理 GPU 资源：

let handle = render_assets.upload_texture(device, queue, &texture_data);
let mesh_handle = render_assets.upload_mesh(device, &mesh_data);

if let Some(texture) = render_assets.get_texture(handle) {
    // 使用纹理
}

BufferPool 提供高效的 GPU 缓冲区复用：

let (buffer, capacity) = pool.acquire(device, needed_size, BufferUsages::VERTEX);
// ... 使用缓冲区 ...
pool.release(buffer, capacity, BufferUsages::VERTEX);

后处理设置

统一的后处理配置 ECS 资源：

use anvilkit_render::renderer::post_process::PostProcessSettings;

app.insert_resource(PostProcessSettings {
    bloom: Some(BloomSettings { intensity: 0.3, threshold: 1.0 }),
    ssao: Some(SsaoSettings { radius: 0.5, bias: 0.025 }),
    dof: None,           // 禁用
    motion_blur: None,   // 禁用
    color_grading: None, // 禁用
    ao_input_enabled: true,
    ..Default::default()
});

执行顺序：SSAO → DOF → 运动模糊 → Bloom → 色彩分级 → Tonemap

当 Option 为 None 时自动跳过对应阶段。

StandardMaterial

高级 PBR 材质组件，支持 builder 模式：

use anvilkit_render::renderer::standard_material::StandardMaterial;

commands.spawn((
    mesh_handle,
    StandardMaterial::new()
        .with_base_color([0.8, 0.2, 0.1, 1.0])
        .with_metallic(0.9)
        .with_roughness(0.1),
    Transform::default(),
    GlobalTransform::default(),
));

render_extract_system 查询 (MeshHandle, StandardMaterial, GlobalTransform) 自动生成 DrawCommand。带有 StandardMaterial 的实体通过 DefaultMaterialHandle 使用默认 PBR 管线。

管线缓存 / BindGroup 缓存

GPU 资源去重：

PipelineCache：按 PipelineKey（vertex_format, BlendMode, CullMode）缓存渲染管线。使用 get_or_create() 避免重复的 GPU 管线创建。
BindGroupCache：按材质 ID 缓存 bind group，带 dirty flag 支持失效重建。脏条目在下次访问时自动重新创建。

let mut cache = PipelineCache::new();
let handle = cache.get_or_create(key, |k| create_pipeline(device, k));

相机投影

CameraComponent 支持透视和正交投影：

use anvilkit_render::plugin::{CameraComponent, Projection};

// 透视投影（默认）
let camera = CameraComponent::default();

// 正交投影（2D、UI）
let ortho_camera = CameraComponent {
    projection: Projection::Orthographic {
        left: -10.0, right: 10.0, bottom: -10.0, top: 10.0,
    },
    ..Default::default()
};

// 多相机：优先级越高越先渲染
let minimap = CameraComponent { priority: 10, ..Default::default() };

渲染管线概述

目录