docs: explain box sizing, device drawing and image preparation

This commit is contained in:
2026-11-12 18:32:01 +08:00
parent 7a3eea3958
commit 13a8b1b4b5
4 changed files with 129 additions and 0 deletions
+27
View File
@@ -1,5 +1,7 @@
//! 面向设备像素的绘制指令集合。它承载矩形、文字、裁剪与 3D 表面等原语,不直接操作 VM。
//! 平移和缩放统一作用于命令几何;文字样式和裁剪也要使用一致的设备比例。
//! 调用路径:RenderDocument.display_list 将已验证逻辑命令转为这些设备原语;shell/system_ui 也可直接组装。
//! SoftwareRenderer 顺序消费 commands;合成页面/工具面板时用 translate/extend,不能把共享场景数据本身平移。
//!
use crate::geometry::{Point, Rect};
use crate::text::TextStyle;
@@ -7,9 +9,13 @@ use crate::text::TextStyle;
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
/// 设备绘制使用的 RGBA 字节通道,区别于源代码的颜色文本。
pub struct Color {
// 红通道字节;源十六进制颜色由 document.parse_color 解码。
pub red: u8,
// 绿通道字节,颜色本身不带坐标或设备比例。
pub green: u8,
// 蓝通道字节,与输出软件像素通道组合。
pub blue: u8,
// 透明度 0..255,混合方式由具体原语渲染器解释。
pub alpha: u8,
}
@@ -40,11 +46,17 @@ impl Color {
pub enum DrawCommand {
/// Immutable RGBA image mapped from its local rectangle by rotation.
Image {
// 不可变 RGBA 资源 Arc,窗口渲染无需访问源对象或重新解码 PNG。
image: std::sync::Arc<crate::render::image::Image>,
// 设备坐标旋转原点,平移只移动它,不改局部 rect 的偏移。
origin: Point,
// 相对 origin 的局部采样矩形,旋转时绕 origin 映射。
rect: Rect,
// 旋转角参数,平移/同比缩放不改变它。
angle: f32,
// 整体不透明度系数,与资源像素 alpha 在采样时组合。
opacity: f32,
// 可选染色通道值,不属于位置/尺寸变换。
tint: Option<Color>,
},
// 在 rect 内绘制不可变 3D 视图;平移/缩放改变视口矩形,不改写共享场景或相机。
@@ -92,6 +104,7 @@ impl DrawCommand {
pub fn translated(mut self, delta: Point) -> Self {
// 平移只改变位置,保留尺寸、圆角、文字样式和颜色;消费 self 后返回修改后的命令。
match &mut self {
// 这些原语的定位直接在 rect 上,移动矩形原点即可,尺寸保持不变。
Self::WrappedText { rect, .. }
| Self::Scene3D { rect, .. }
| Self::PushClip(rect)
@@ -100,10 +113,12 @@ impl DrawCommand {
rect.x += delta.x;
rect.y += delta.y;
}
// 文字与图片使用 origin 定位;图片 rect 是局部偏移,不能在此跟着重复平移。
Self::Text { origin, .. } | Self::Image { origin, .. } => {
origin.x += delta.x;
origin.y += delta.y;
}
// Clear/PopClip 无定位几何,平移不产生任何变化。
_ => {}
}
self
@@ -113,6 +128,7 @@ impl DrawCommand {
#[derive(Clone, Debug, Default)]
/// 有序绘制原语容器;命令顺序同时约束叠放和裁剪栈行为。
pub struct DisplayList {
// 拥有按执行顺序排列的原语、字符串与原生资源 Arc,列表本身不引用 VM。
commands: Vec<DrawCommand>,
}
@@ -123,16 +139,21 @@ impl DisplayList {
for command in &mut self.commands {
// 先处理各变体独有的长度(字体、圆角、描边),再把公共矩形交给下方统一缩放。
let rect = match command {
// 有限文字框交给公共矩形缩放,样式先同步乘比例,避免换行框与字形不一致。
DrawCommand::WrappedText { rect, style, .. } => {
*style = style.scaled(scale);
Some(rect)
}
// 裁剪属于设备几何,和所裁内容使用相同比例。
DrawCommand::PushClip(rect) => Some(rect),
// 只改三维显示区域,不缩放共享世界网格和相机数值。
DrawCommand::Scene3D { rect, .. } => Some(rect),
// 圆角作为长度先缩放,再返回矩形供统一处理。
DrawCommand::FillRoundedRect { rect, radius, .. } => {
*radius *= scale;
Some(rect)
}
// 半径与描边宽也要缩放,不能只改外框而保留旧粗细。
DrawCommand::StrokeRoundedRect {
rect,
radius,
@@ -143,6 +164,7 @@ impl DisplayList {
*width *= scale;
Some(rect)
}
// 图片 origin 和局部 rect 均在设备单位,分别缩放后返回 None,防止公共分支再缩放一次。
DrawCommand::Image { origin, rect, .. } => {
origin.x *= scale;
origin.y *= scale;
@@ -152,12 +174,14 @@ impl DisplayList {
rect.height *= scale;
None
}
// 无框文字单独缩放原点和样式,没有矩形需要返回公共路径。
DrawCommand::Text { origin, style, .. } => {
origin.x *= scale;
origin.y *= scale;
*style = style.scaled(scale);
None
}
// Clear/PopClip 不含长度数据,保持原样。
_ => None,
};
// 矩形的原点和宽高一起缩放,保证裁剪范围、文本框与实际绘制内容对齐。
@@ -177,7 +201,9 @@ impl DisplayList {
/// 平移当前显示列表中的命令,供整块页面或管理面板放入窗口坐标。
// 与单条 translated 相同,但直接修改整个列表;Clear/PopClip 没有位置需要移动。
pub fn translate(&mut self, delta: Point) {
// 保持原语顺序逐项移动,不能按种类分组而打乱覆盖关系和裁剪栈。
for command in &mut self.commands {
// 与单条 translated 保持同一空间规则:rect 型移原点,图片只移旋转 origin。
match command {
DrawCommand::WrappedText { rect, .. }
| DrawCommand::Scene3D { rect, .. }
@@ -191,6 +217,7 @@ impl DisplayList {
origin.x += delta.x;
origin.y += delta.y;
}
// 无几何的状态原语保留顺序但不做坐标更新。
DrawCommand::Clear(_) | DrawCommand::PopClip => {}
}
}