API 参考手册（免读源码版）

为不想读源代码的人和 AI 准备的速查 API 参考。覆盖：Color / ColorF64、Transform2D、Camera2D、Render2D、RStates 及 builder 责任链、相关小类型。完整的概念讲解（坐标系、Layer、KeyState 边沿、物理/逻辑像素、页池…）见 ENGINE_GUIDE.md。

约定：所有坐标单位为世界像素；Y+ 指向屏幕下方；layer 数值小先画。

还有：本项目使用的 wgpu 版本为 30.0.0，与常用的 0.20.0 的 API 有诸多不同，建议使用 rjw_render::wgpu 的重导出

1. Color / ColorF64（颜色）
2. Transform2D（变换）
3. Camera2D（相机）
4. SpriteRect（精灵矩形）
5. Render2D（2D 批渲染器）
6. RStates 渲染状态与 Builder 责任链
7. ClearConfig（清屏配置）
8. DynamicAtlas（纹理图集）
9. Text（文本渲染）
10. 其他常用小类型速查

1. Color / ColorF64（颜色）

crate：rjw_color

`Color`（f32 存储）

函数	签名 / 用法	说明
`Color::rgba`	`Color::rgba(r: f32, g: f32, b: f32, a: f32)`	0..=1 浮点颜色
`Color::rgb`	`Color::rgb(r, g, b)`	alpha=1.0
`Color::rgba_u8`	`Color::rgba_u8(r: u8, g: u8, b: u8, a: u8)`	0..=255
`Color::rgb_u8`	`Color::rgb_u8(r, g, b)`	alpha=255
常量	`Color::RED` `Color::GREEN` `Color::BLUE` `Color::WHITE` `Color::BLACK` 等	见 `consts` 模块

use rjw_color::Color;

let red = Color::rgba(1.0, 0.0, 0.0, 0.5);
let green = Color::rgba_u8(60, 200, 80, 255);
let arr: [f32; 4] = Color::WHITE.into();

`ColorF64`（f64 存储，用于 wgpu 清屏）

函数	用法	说明
`ColorF64::rgba`	`ColorF64::rgba(f64, f64, f64, f64)`	高精度
`.into()`	`let c: wgpu::Color = ColorF64::rgba(...).into();`	直接转换给 `ClearConfig.color`

2. Transform2D（变换）

crate：rjw_transform

pub struct Transform2D {
    pub pos:      glam::Vec2,
    pub scale:    glam::Vec2,
    pub rotation: f32,
}

构建器（返回新值，链式）

函数	用法	说明
`IDENTITY`	`Transform2D::IDENTITY`	单位变换
`with_pos`	`.with_pos(Vec2::new(x, y))`	设置位置
`with_scale`	`.with_scale(Vec2::new(sx, sy))`	设置缩放
`with_rot`	`.with_rot(0.5)`	设置旋转（弧度）
`with_move_by`	`.with_move_by(delta)`	平移 delta
`with_walk_by`	`.with_walk_by(local)`	按当前旋转方向位移
`with_scale_by`	`.with_scale_by(factor)`	缩放乘
`with_rotate_by`	`.with_rotate_by(rad)`	旋转加

空间运算

函数	说明
`transform_point(local)`	局部点 → 父/世界点
`inverse_transform_point(world)`	世界点 → 局部点（命中检测用）
`transform_vec(local_vec)`	局部方向 → 世界方向
`inverse_transform_vec(world_vec)`	反过来
`with_transform(&parent)`	组合父级：`result = parent * self`
`inverse()`	逆变换对象

💡 旋转中心 = pos：让精灵绕自身中心转，矩形写成 SpriteRect::from_texture(Vec2::splat(-w/2), Vec2::splat(w))。

3. Camera2D（相机）

crate：rjw_transform

pub struct Camera2D {
    pub position:     Vec2,  // 相机中心（世界）
    pub rotation:     f32,
    pub zoom:         Vec2,
    pub viewport_pos: Vec2,  // 视口左上角（窗口像素）
    pub viewport_size: Vec2, // 视口尺寸（像素）
}

构造 / 视口

函数	用法	说明
`Camera2D::new`	`Camera2D::new(Vec2::new(w, h))`	以窗口尺寸建相机；之后必须 `set_vp`
`set_vp`	`cam.set_vp(Vec2::new(w, h), Vec2::ZERO)`	设置视口大小 + 位置（高 DPI 用 `render.size()` 的物理像素）

移动

函数	用法	说明
`move_by`	`cam.move_by(Vec2::new(dx, dy))`	绝对平移（不随旋转）
`walk_xy`	`cam.walk_xy(Vec2::new(lx, ly))`	沿相机自身方向移动
`walk_xplus`	`cam.walk_xplus(v)`	沿相机横向 + 方向走 v
`walk_yplus`	`cam.walk_yplus(v)`	沿相机纵向 + 方向走 v

矩阵 / 坐标转换

函数	说明
`vp_matrix()`	列主序 VP（P×V），直接喂 `render2d.set_mvp(...)`
`screen_to_world(screen_px)`	窗口像素 → 世界坐标
`world_to_screen(world)`	世界 → 窗口像素
`world_transform()`	把相机看作 `Transform2D`

// 鼠标指向的世界点
let mouse_px = ctx.mouse.get_mouse_position();
let world = cam.screen_to_world(Vec2::new(mouse_px.0 as f32, mouse_px.1 as f32));

4. SpriteRect（精灵矩形）

crate：rjw_2d_render（data 模块）

pub struct SpriteRect {
    pub mesh_tl: Vec2, // 世界坐标左上角
    pub mesh_wh: Vec2, // 世界尺寸
    pub uv_tl:   Vec2, // 归一化 UV 左上 (0..1)
    pub uv_wh:   Vec2, // 归一化 UV 尺寸 (0..1)
}

函数	用法	说明
`from_texture`	`SpriteRect::from_texture(tl, wh)`	整张贴图
`from_texture_px`	`SpriteRect::from_texture_px(tl, wh, uv_tl_px, uv_wh_px, inv_tex_wh)`	按像素取纹理子区
`new`	`SpriteRect::new(tl, wh, uv_tl, uv_wh)`	全手动（UV 归一化）

use rjw_2d_render::SpriteRect;
use glam::Vec2;

let a = SpriteRect::from_texture(Vec2::ZERO, Vec2::splat(32.0));
let b = SpriteRect::from_texture_px(
    Vec2::ZERO, Vec2::splat(32.0),
    Vec2::ZERO, Vec2::splat(32.0),
    Vec2::new(1.0 / 128.0, 1.0 / 128.0),
);

5. Render2D（2D 批渲染器）

crate：rjw_2d_render

生命周期：Render2D::new(&RenderContext) 持有 surface 的 'static 引用，要求 RenderContext 比 Render2D 活得更久。

5.1 创建 / 全局

函数	用法	说明
`new`	`Render2D::new(&render_ctx)`	基于 `RenderContext` 创建
`set_mvp`	`r2d.set_mvp(cam.vp_matrix())`	设置 VP（每帧渲染前调用）
`create_texture`	`r2d.create_texture("label", &rgba8, w, h)`	建纹理（RGBA8，`len==wh4` 否则 panic），返回 `ArcTextureWrapped`
`white_texture()`	`r2d.white_texture()`	1×1 白色默认纹理引用
`device()` / `queue()`	`r2d.device()` / `r2d.queue()`	暴露底层 wgpu 给高级用法

5.2 全局默认渲染状态（责任链，返回 `&mut Self`）

函数	说明
`reset_default_state()`	重置为"出厂默认"（全零 bitfield）
`default_blend(mode)`	设置默认 BlendMode
`default_samp_mag(f)` / `default_samp_min(f)` / `default_samp_mip(f)`	设置默认采样器过滤
`default_samp_addr_u(a)` / `default_samp_addr_v(a)` / `default_samp_addr_w(a)`	设置默认寻址模式
`default_cull(c)` / `default_polygon(p)` / `default_front_face(f)`	默认剔除/光栅化
`default_conservative_raster(b)`	默认保守光栅化
`default_depth_test(b)` / `default_depth_write(b)` / `default_depth_compare(f)`	默认深度状态
`default_stencil_test(b)` / `default_stencil_write(b)` / `default_stencil_compare(f)`	默认模板状态
`default_blend_state(d)` / `default_samp_state(d)` / `default_raster_state(s)` / `default_depth_state(s)` / `default_stencil_state(s)`	批量设置

render2d
    .default_blend(BlendMode::Additive)
    .default_depth_test(true)
    .default_depth_write(true)
    .default_samp_addr_u(AddressMode::Repeat);
// 此后所有不链式的 add_* 命令都继承这些状态

5.3 Sprite 绘制（返回 `Sprite2DBuilder`）

函数	用法	说明
`add_sprite2d`	`r2d.add_sprite2d(rect, color, transform, layer, &tex)`	贴纹理精灵
`add_sprite2d_solid`	`r2d.add_sprite2d_solid(rect, color, transform, layer)`	纯色精灵（内部用 1×1 白纹理）

// 绕中心旋转的精灵
let tf = Transform2D::IDENTITY
    .with_pos(Vec2::new(0.0, 0.0))
    .with_rot(t * 0.8);
r2d.add_sprite2d(
    SpriteRect::from_texture(Vec2::splat(-48.0), Vec2::splat(96.0)),
    Color::WHITE, tf, 0.0, &my_texture,
);
// 可链式设渲染状态：
r2d.add_sprite2d(rect, Color::WHITE, tf, 0.0, &tex)
    .blend(BlendMode::Additive)
    .samp_mag(FilterMode::Nearest);

5.4 Mesh / 多边形（返回 `MeshBuilder`）

函数	用法	说明
`add_mesh`	`r2d.add_mesh(&verts, &tri_indices, color, layer)`	显式顶点+三角形索引（世界坐标）
`add_polygon_fan`	`r2d.add_polygon_fan(&verts, color, layer)`	顶点数组自动三角形扇
`add_polygon_strip`	`r2d.add_polygon_strip(&verts, color, layer)`	三角形条带
`add_polygon_fan_uv`	`r2d.add_polygon_fan_uv(&verts, &uvs, color, layer)`	三角形扇 + UV 坐标
`add_polygon_strip_uv`	`r2d.add_polygon_strip_uv(&verts, &uvs, color, layer)`	三角形条带 + UV 坐标
`add_mesh_fn`	`r2d.add_mesh_fn(color, layer, \|sink\| { ... })`	流程式安全建网格
`add_mesh_fn_prealloc`	`r2d.add_mesh_fn_prealloc(max_verts, max_tris, color, layer, \|v_slice, t_slice\| { ... })`	已知顶点/三角形数，直接写预分配切片

// 画一个圆（中心 c, 半径 r）
let mut verts = Vec::with_capacity(24);
verts.push(c);
for i in 0..=22 {
    let a = i as f32 / 22.0 * std::f32::consts::TAU;
    verts.push(c + Vec2::new(a.cos(), a.sin()) * r);
}
r2d.add_polygon_fan(&verts, Color::CYAN, 1.0);

// Mesh 可链式设纹理：
r2d.add_polygon_fan(&verts, Color::CYAN, 96.0)
    .set_texture(&tex)
    .blend(BlendMode::Multiply);

💡 MeshBuilder 独有 .set_texture(&ArcTextureWrapped)——mesh 默认白色纹理，此方法覆盖。

5.4.1 外部自定义绘制（`add_custom` / `CustomDraw`，返回 `CustomBuilder`）

函数	用法	说明
`add_custom`	`r2d.add_custom(layer, \|pass\| { ... })`	注入一段原生 wgpu 绘制调用，参与 (layer, states) 排序

// 闭包直接传（blanket impl）—— pass 是 &mut wgpu::RenderPass
r2d.add_custom(1.0, |pass| {
    // 这里可以用任意原生 wgpu API：set_pipeline / draw / 自行绑定缓冲……
    // 注意：pass 管理器已在引擎内打开，不要 begin_render_pass
});

// 或实现 CustomDraw trait 的结构体
struct MyFx;
impl rjw_2d_render::CustomDraw for MyFx {
    fn draw(&self, pass: &mut wgpu::RenderPass<'_>) {
        // 自定义绘制……
    }
}
r2d.add_custom(1.0, MyFx);

要点：

签名：add_custom<CD: CustomDraw + 'static>(&mut self, layer, cd) -> CustomBuilder<'_>；CustomDraw: Send + Sync，闭包 Fn(&mut wgpu::RenderPass) + Send + Sync 自动实现。
排序位置：返回的 CustomBuilder 可链式设置 RStates（.blend(...) / .depth_test(...) 等，但注意 CustomBuilder 没有 .set_texture()），这些值参与 (layer, states) 排序，决定该闭包在 Sprite/Mesh 之间的执行顺序。
执行时机：闭包在 render() 或 flush() 的 draw() 阶段被调用；buf_custom_draws 每帧结束后 clear()，请勿跨帧持有 add_custom 内部状态。
适用场景：引擎封装之外的管线（自定义 shader、线框调试、后处理、自定义顶点格式等）。
若不链式调用 RStates，则 CustomBuilder 仍按 default_rstates 参与排序（resolve 后为整数值相加大致落在默认位置）。

5.5 提交

函数	用法	说明
`render`	`r2d.render(&ClearConfig { ... })`	全流程：begin_frame → 创建 pass → 绘制 → 提交呈现
`flush`	`r2d.flush(&mut pass)`	只录制绘制到用户自己建的 pass
`begin_frame`	`r2d.begin_frame() -> Option<(SurfaceTexture, TextureView)>`	手动获取表面

r2d.render(&ClearConfig {
    color: Some(wgpu::Color { r: 0.1, g: 0.2, b: 0.15, a: 1.0 }),
    depth: None,
    stencil: None,
});

5.6 分页机制（无需手动处理）

实例缓冲是页池：单帧精灵数量可超 MAX_INSTANCES_PER_DRAW(8192)
prepare() 自动分页、每页只写一次、draw() 逐页绑定/绘制

6. RStates 渲染状态与 Builder 责任链

crate：rjw_2d_render（rstates 模块）

RStates 是 u64 bitfield，涵盖 6 个控制域：Blend / Sampler / Cull+Raster / Depth / Stencil / Reserved。

6.1 RStates 自身方法（用于构造，不可变链式）

分类	方法	说明
Blend	`blend(BlendMode)` / `blend_state(BlendDesc)`	Alpha/Additive/Multiply/Premultiplied/Inverse/Subtract/Min/Max/Disabled
Sampler	`samp_mag(f)` / `samp_min(f)` / `samp_mip(f)`	Linear / Nearest
	`samp_addr_u(a)` / `samp_addr_v(a)` / `samp_addr_w(a)`	ClampToEdge / Repeat / MirrorRepeat
	`samp_state(SamplerDesc)`	批量设置采样器
Cull+Raster	`cull(CullMode)` / `polygon(PolygonMode)` / `front_face(FrontFaceWinding)` / `conservative_raster(bool)`	None/Front/Back; Fill/Line/Point; Ccw/Cw
	`raster_state(RasterState)`	批量设置光栅化
Depth	`depth_test(bool)` / `depth_write(bool)` / `depth_compare(CompareFunc)`	Less/LessEq/Greater/...
	`depth_state(DepthState)`	批量设置深度
Stencil	`stencil_test(bool)` / `stencil_write(bool)` / `stencil_compare(CompareFunc)`	Always/Never/...
	`stencil_state(StencilState)`	批量设置模板

6.2 Builder 链方法（`Sprite2DBuilder` / `MeshBuilder` 通用）

分类	方法
Blend	`.blend(m)` / `.blend_state(d)`
Sampler	`.samp_mag(f)` / `.samp_min(f)` / `.samp_mip(f)` / `.samp_addr_u(a)` / `.samp_addr_v(a)` / `.samp_addr_w(a)` / `.samp_state(d)`
Cull+Raster	`.cull(c)` / `.polygon(p)` / `.front_face(f)` / `.conservative_raster(b)` / `.raster_state(s)`
Depth	`.depth_test(b)` / `.depth_write(b)` / `.depth_compare(f)` / `.depth_state(s)`
Stencil	`.stencil_test(b)` / `.stencil_write(b)` / `.stencil_compare(f)` / `.stencil_state(s)`
MeshBuilder only	`.set_texture(&tex)`

不链式调用 = rstates: None → draw() 阶段 resolve 为 Render2D.default_rstates。

6.3 重要类型一览

类型	值
`RStates`	u64 bitfield，`RStates::default() / new()` = 全零（默认）
`BlendMode`	`Alpha` / `Additive` / `Multiply` / `Premultiplied` / `Inverse` / `Subtract` / `Min` / `Max` / `Disabled`
`FilterMode`	`Linear` / `Nearest`
`AddressMode`	`ClampToEdge` / `Repeat` / `MirrorRepeat`
`CullMode`	`None` / `Front` / `Back`
`PolygonMode`	`Fill` / `Line` / `Point`
`FrontFaceWinding`	`Ccw` / `Cw`
`CompareFunc`	`Never` / `Less` / `Equal` / `LessEq` / `Greater` / `NotEq` / `GreaterEq` / `Always`
`BlendDesc`	`{ blend_mode: BlendMode }`
`SamplerDesc`	`{ mag, min, mip: FilterMode, addr_u, addr_v, addr_w: AddressMode }`
`RasterState`	`{ cull: CullMode, polygon: PolygonMode, front_face: FrontFaceWinding, conservative: bool }`
`DepthState`	`{ test: bool, write: bool, compare: CompareFunc }`
`StencilState`	`{ test: bool, write: bool, compare: CompareFunc }`

6.4 使用示例

use rjw_2d_render::{BlendMode, FilterMode, AddressMode, DepthState, CompareFunc};

// 不链式 = 默认
render2d.add_sprite2d(rect, Color::WHITE, tf, 0.0, &tex);

// 单条链式覆盖
render2d.add_sprite2d(rect, Color::WHITE, tf, 0.0, &tex)
    .blend(BlendMode::Additive)
    .samp_addr_u(AddressMode::Repeat)
    .samp_mag(FilterMode::Nearest);

// Mesh + set_texture + 渲染状态
render2d.add_polygon_fan(&verts, Color::CYAN, 96.0)
    .set_texture(&tex)
    .blend(BlendMode::Multiply);

// 批量设置
render2d.add_sprite2d(rect, Color::WHITE, tf, 0.0, &tex)
    .depth_state(DepthState { test: true, write: true, compare: CompareFunc::Less });

// 全局默认（责任链，返回 &mut Render2D）
render2d
    .default_blend(BlendMode::Additive)
    .default_depth_test(true)
    .default_depth_write(true);

7. ClearConfig（清屏配置）

pub struct ClearConfig {
    pub color:   Option<wgpu::Color>,
    pub depth:   Option<f32>,
    pub stencil: Option<u32>,
}

r2d.render(&ClearConfig {
    color: Some(wgpu::Color::BLACK),
    depth: Some(1.0),
    stencil: None,
});

8. DynamicAtlas（纹理图集）

crate：rjw_atlas

pub struct AtlasConfig { pub max_pages: usize, pub padding: u32, pub lifetime: u32 }
pub struct AtlasRegion { pub tl_px: (u32,u32), pub wh_px: (u32,u32), pub origin_px: (u32,u32), pub page_uid: u64 }
pub struct DynamicAtlas<const PAGE_SIZE: u32 = 2048>
pub struct StaticAtlas  // (serde feature only)

方法	说明
`DynamicAtlas::new(device, queue, layout, config)`	创建空图集
`insert(name, rgba, w, h, origin_px, clamp_margin)`	插入/替换精灵（完整参数）
`insert_ex(name, rgba, w, h)`	★ 最常用：origin=(0,0), clamp_margin=true，自动保存源数据
`insert_ex_origin(name, rgba, w, h, origin_px)`	指定原点，clamp_margin=true
`insert_ex_permanent(name, rgba, w, h)`	常驻精灵（不会过期踢出）
`insert_dyn(name, w, h, origin_px, clamp_margin, regen)`	动态再生精灵（每次复活调生成器）
`insert_no_clamp(name, rgba, w, h)`	origin=(0,0), clamp_margin=false
`insert_white()`	插入 1×1 白像素
`get(name)`	查找（重置寿命，不触发复活）
`get_or_revive(name)`	★ 查找；若被踢出则自动复活
`load_toml(toml_str, rgba_provider)`	从 TOML 批量导入（闭包提供源纹理 RGBA）
`export_toml()`	导出当前 entries 为 TOML 文本
`end_frame()`	寿命-1，有源数据→墓碑；常驻直接删除
`compact()`	重建 skyline
`page_size()` / `page_count()` / `texture_uid_of(name)`	查询
`parse_toml_entries(toml_str)`	辅助：解析 TOML 返回原始条目表
`StaticAtlas::from_toml(s)`	从 TOML 反序列化
`StaticAtlas::get(name)`	查找

9. Text（文本渲染）

crate：rjw_text

基于 cosmic-text 排版 + swash 字形光栅化 + DynamicAtlas 字形缓存。

pub struct Text { /* font_system: FontSystem, glyph_cache: DynamicAtlas<cosmic_text::CacheKey>, ... */ }

方法	说明
`Text::new(device, queue, layout)`	创建字体管理器（自动加载系统字体）
`load_font_data(data: Vec<u8>)`	加载额外的 ttf/otf 字体数据
`create_buffer(text, attrs, size, line_height, align)`	创建已排版 cosmic-text Buffer
`draw_label(r2d, text, color, size, line_height, pos, family, align, layer) -> Vec2`	★ 一行渲染：pos=左上角，返回内容宽高
`draw_label_ex(r2d, text, color, size, line_height, pos, family, align, layer, origin) -> Vec2`	扩展版：origin 归一化到 [0,1]，(0.5,0.5)=居中
`draw_text(buffer, callback)`	遍历字形精灵，闭包自定义绘制
`draw_text_sprite(r2d, buffer, color, layer)`	将字形渲染到 Render2D

use rjw_text::{Text, Align};

let mut font = Text::new(device, queue, layout);

// 左上角单行文本
font.draw_label(r2d, "Hello World", Color::WHITE, 14.0, 18.0, Vec2::new(10.0, 10.0), "SimHei", Align::Left, 0.0);

// 屏幕居中 Game Over
let size = font.draw_label_ex(r2d, "GAME OVER\n按 R 重开", Color::RED, 22.0, 28.0, cam.position, "SimHei", Align::Center, 1e7, Vec2::new(0.5, 0.5));

10. 其他常用小类型速查

类型 / 函数	位置	用途
`KeyState::pressed()/released()`	`rjw_keystate`	按住/松开
`KeyState::down_edge()/up_edge()`	`rjw_keystate`	按下/松开那一帧
`KeyState::true_edge()/down_true_edge()`	`rjw_keystate`	系统级真实边沿
`KeyCode::KeyW/...`	`rjw_main` 重导出 winit	键盘常量
`MouseButton::Left/...`	winit	鼠标按钮
`ctx.timer.dt().get_f32()`	`rjw_time`	帧间隔秒
`ctx.timer.get_fps()`	`rjw_time`	FPS
`ArcTextureWrapped.uid`	`rjw_render`	纹理唯一 ID
`Sprite2DBuilder<'a>`	`rjw_2d_render`	add_sprite2d* 返回
`MeshBuilder<'a>`	`rjw_2d_render`	add_mesh / add_polygon_* 返回
`CustomDraw`	`rjw_2d_render`	外部绘制 trait（闭包 blanket impl）
`CustomBuilder<'a>`	`rjw_2d_render`	add_custom 返回，可链式 RStates

还想看更多？源码在 crates/rjw_*/src/，目录与本文一一对应。

FilesExpand file tree

API_REFERENCE.md

Latest commit

History