merge: resolve manuscript conflicts with latest main comments

This commit is contained in:
2026-11-12 11:11:00 +08:00
123 changed files with 2699 additions and 253 deletions
+6 -1
View File
@@ -75,8 +75,10 @@ impl Default for Sizing {
impl Sizing {
/// Constrain descendants using the actual finite box before wrapping text.
/// 根据固定/auto/fill 与 min/max 规则细化父级提供的可用约束。
/// 将 [最小宽, 最小高, 最大宽, 最大高] 收窄,供子内容测量和文本换行使用。
/// 固定尺寸限制最大可用空间;最后缩小最小约束以保持 min <= max。这里不直接计算最终盒子。
pub fn available(self, mut constraints: [f32; 4]) -> [f32; 4] {
// 先套自身 max,再应用 Fixed;Auto/Fill 在测量阶段保留父级允许的空间。
constraints[2] = constraints[2].min(self.max_width);
constraints[3] = constraints[3].min(self.max_height);
if let Dimension::Fixed(width) = self.width {
@@ -100,10 +102,12 @@ impl Sizing {
max: f32,
available: f32,
) -> Result<f32> {
// 先按策略选候选值:Auto 用内容测量值,Fixed 用指定值,Fill 用父级分配上限。
let value = match policy {
Dimension::Auto => intrinsic,
Dimension::Fixed(value) => value,
Dimension::Fill => {
// MAX_DIMENSION 充当无界哨兵;无界空间没有可填满的有限尺寸,必须拒绝。
if available >= MAX_DIMENSION as f32 {
return Err(VmError::InvalidArgument(
"fill requires a finite parent allocation on this axis",
@@ -113,6 +117,7 @@ impl Sizing {
available
}
};
// 先满足自身 min/max,再服从父级上限;父级空间比 min 小时,父级上限优先。
Ok(value.clamp(min, max).min(available))
}
Ok(Size {
+14
View File
@@ -47,30 +47,38 @@ pub enum DrawCommand {
opacity: f32,
tint: Option<Color>,
},
// 在 rect 内绘制不可变 3D 视图;平移/缩放改变视口矩形,不改写共享场景或相机。
Scene3D {
rect: Rect,
view: std::sync::Arc<crate::scene3d::View>,
},
// 清除整个目标缓冲;不携带几何,因此列表平移和缩放不会改变它。
Clear(Color),
// 将矩形压入裁剪栈;后续命令受裁剪约束,必须由对应 PopClip 恢复。
PushClip(Rect),
// 恢复上层裁剪。合并列表保持原顺序,调用方需保证裁剪栈配对。
PopClip,
// 填充圆角矩形;半径与矩形尺寸在设备缩放时使用同一比例。
FillRoundedRect {
rect: Rect,
radius: f32,
color: Color,
},
// 描边圆角矩形;描边宽度也是长度,必须随几何一起缩放。
StrokeRoundedRect {
rect: Rect,
radius: f32,
width: f32,
color: Color,
},
// 在有限矩形内进行文本布局;缩放同时作用于矩形和文字样式,保持换行比例。
WrappedText {
rect: Rect,
value: String,
style: TextStyle,
color: Color,
},
// 以原点定位文本,文本布局使用 TextStyle;与 WrappedText 不同,不额外携带有限文本框。
Text {
origin: Point,
value: String,
@@ -82,6 +90,7 @@ pub enum DrawCommand {
impl DrawCommand {
/// 返回平移后的绘制命令,并同步移动命令中的相关几何。
pub fn translated(mut self, delta: Point) -> Self {
// 平移只改变位置,保留尺寸、圆角、文字样式和颜色;消费 self 后返回修改后的命令。
match &mut self {
Self::WrappedText { rect, .. }
| Self::Scene3D { rect, .. }
@@ -110,7 +119,9 @@ pub struct DisplayList {
impl DisplayList {
/// 按设备比例缩放命令,文字、边框和矩形不能分别使用不一致比例。
pub fn scale(&mut self, scale: f32) {
// 原地累计缩放:重复调用会相乘,并非设置绝对缩放值。调用方负责提供有效设备比例。
for command in &mut self.commands {
// 先处理各变体独有的长度(字体、圆角、描边),再把公共矩形交给下方统一缩放。
let rect = match command {
DrawCommand::WrappedText { rect, style, .. } => {
*style = style.scaled(scale);
@@ -149,6 +160,7 @@ impl DisplayList {
}
_ => None,
};
// 矩形的原点和宽高一起缩放,保证裁剪范围、文本框与实际绘制内容对齐。
if let Some(rect) = rect {
rect.x *= scale;
rect.y *= scale;
@@ -163,6 +175,7 @@ impl DisplayList {
}
/// 平移当前显示列表中的命令,供整块页面或管理面板放入窗口坐标。
// 与单条 translated 相同,但直接修改整个列表;Clear/PopClip 没有位置需要移动。
pub fn translate(&mut self, delta: Point) {
for command in &mut self.commands {
match command {
@@ -189,6 +202,7 @@ impl DisplayList {
}
/// 按原顺序合并另一组绘制命令,不在这里重排层次。
// 消费另一个列表并移动其命令,不复制字符串或场景数据,也不在连接处补裁剪指令。
pub fn extend(&mut self, other: DisplayList) {
self.commands.extend(other.commands);
}
+5 -3
View File
@@ -8,7 +8,7 @@ pub struct Point {
}
impl Point {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 直接保存二维坐标;不缩放、不舍入,也不检查有限性,调用方负责坐标空间和输入校验。
pub const fn new(x: f32, y: f32) -> Self {
Self { x, y }
}
@@ -24,7 +24,7 @@ pub struct Rect {
}
impl Rect {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 直接保存左上角和宽高;不归一化负尺寸,布局调用方需先产生合法边界。
pub const fn new(x: f32, y: f32, width: f32, height: f32) -> Self {
Self {
x,
@@ -34,7 +34,7 @@ impl Rect {
}
}
/// 判断给定点是否位于目标范围;需要相机转换的类型会先转换再判断。
/// 用闭区间比较判断点是否命中,左右上下边缘都计入;调用前需将点转换到矩形所在空间。
pub fn contains(self, point: Point) -> bool {
point.x >= self.x
&& point.x <= self.x + self.width
@@ -48,7 +48,9 @@ mod tests {
use super::*;
#[test]
/// 矩形左上/右下边界均包含,刚越过左边界的点排除,固定基础命中边界策略。
fn rectangle_contains_edges_but_not_outside_points() {
// 同时验证左上和右下边界被包含,以及仅越过左边界的小偏差也会被排除。
let rect = Rect::new(10.0, 20.0, 30.0, 40.0);
assert!(rect.contains(Point::new(10.0, 20.0)));
assert!(rect.contains(Point::new(40.0, 60.0)));
+48
View File
@@ -79,6 +79,7 @@ impl CrossAlign {
/// 根据交叉轴对齐方式计算有限剩余空间中的偏移。
fn offset(self, available: f32, occupied: f32) -> f32 {
// 溢出时剩余空间归零,Center/End 都退化为起点对齐,避免把内容前缘移出可达滚动范围。
let spare = (available - occupied).max(0.0);
match self {
Self::Start | Self::Stretch => 0.0,
@@ -125,9 +126,11 @@ impl MainAlign {
#[derive(Debug, Clone, Copy, PartialEq)]
/// 主轴伸缩策略与限值,不能用一个宽度常量替代完整分配规则。
pub struct FlexPolicy {
// Some 指定主轴首选基准,None 使用首次内容测量;grow/fill 的缺省基准在 flex_sizes 中解释为零。
pub basis: Option<f32>,
pub min: f32,
pub max: f32,
// 收缩权重还会乘 basis;默认零表示空间不足时不主动压缩该项。
pub shrink: f32,
}
impl Default for FlexPolicy {
@@ -170,7 +173,9 @@ struct Key {
#[derive(Debug, Clone, Default)]
/// 布局缓存、稳定出现身份与统计。构建在临时副本上完成,成功后才写回。
pub struct LayoutRuntime {
// 按 Block 身份只保留最后一份 Shape/Size;共享 Block 不同约束可交替覆盖,但每次复用前仍比较完整 Shape。
sizes: HashMap<String, (Shape, Size)>,
// 出现身份取父 Mount、稳定 slot 和 Block 身份三元组,区别于仅按业务组件分配一个全局 ID。
ids: HashMap<Key, u64>,
next_id: u64,
pub version: u64,
@@ -209,6 +214,7 @@ fn coordinate(value: f32) -> Result<f32> {
/// 从页面模式和当前视口生成根节点约束;无视口时使用明确的无界轴哨兵。
pub fn root_constraints(viewport: Option<Size>) -> [f32; 4] {
// 无视口时以 MAX_DIMENSION 作为无界哨兵;它是有限数值预算,但 Fill 必须另行要求真正有限分配。
let size = viewport.unwrap_or(Size {
width: MAX_DIMENSION as f32,
height: MAX_DIMENSION as f32,
@@ -218,6 +224,7 @@ pub fn root_constraints(viewport: Option<Size>) -> [f32; 4] {
/// 从父级上限扣除内边距;无界哨兵保持无界,不因减法被误认为有限。
fn content_limit(available: f32, inset: f32) -> f32 {
// 不能直接从哨兵减 padding,否则略小于 MAX_DIMENSION 会被误认为有限空间,从而错误允许 Fill。
if available >= MAX_DIMENSION as f32 {
available
} else {
@@ -227,6 +234,7 @@ fn content_limit(available: f32, inset: f32) -> f32 {
/// 把父盒子的可用尺寸传递给子项,扣除容器内边距并考虑主轴是否可延伸。
pub fn child_constraints(node: &UiNode, parent: [f32; 4]) -> [f32; 4] {
let parent = node.sizing.available(parent);
// Overlay 双轴都受内容盒上限约束;不像 Row/Column 在主轴自然展开。
if let UiKind::Overlay { .. } = node.kind {
let padding = insets(node);
return [
@@ -240,6 +248,7 @@ pub fn child_constraints(node: &UiNode, parent: [f32; 4]) -> [f32; 4] {
node.kind,
UiKind::Canvas { .. } | UiKind::Scene2D { .. } | UiKind::CanvasViewport { .. }
) {
// 世界 Canvas/Scene2D 与其观察视口不把屏幕尺寸传入世界布局,场景孩子用无界轴约束。
return root_constraints(None);
}
if let UiKind::Scroll { width, height, .. } = node.kind {
@@ -249,6 +258,7 @@ pub fn child_constraints(node: &UiNode, parent: [f32; 4]) -> [f32; 4] {
constrained(Size { width, height }, parent),
);
}
// Row 主轴 x 无界、交叉轴 y 有限;Column/Button/Scroll 的普通方向相反,具体滚动另有上方分支。
match container(node) {
Some((true, padding, _)) => [
0.0,
@@ -272,6 +282,7 @@ pub fn margin_constraints(child: &UiNode, mut constraints: [f32; 4]) -> [f32; 4]
.into_iter()
.enumerate()
{
// 仅对真正有限轴扣 margin,保持无界哨兵;最小约束同时收窄以维持 min<=max。
if constraints[axis + 2] < MAX_DIMENSION as f32 {
constraints[axis + 2] = (constraints[axis + 2] - margin).max(0.0);
constraints[axis] = constraints[axis].min(constraints[axis + 2]);
@@ -290,6 +301,7 @@ pub fn occurrence_constraints(
offer: Size,
child_index: usize,
) -> [f32; 4] {
// 世界面板 UI 根必须精确按纹理分辨率布局,最小与最大相同,不让外层视口世界尺寸泄入纹理空间。
if let UiKind::Viewport3D { panels, .. } = &parent.kind {
let size = panels[child_index];
return [size.width, size.height, size.width, size.height];
@@ -299,6 +311,7 @@ pub fn occurrence_constraints(
(0, child.sizing.width, offer.width, inset.horizontal()),
(1, child.sizing.height, offer.height, inset.vertical()),
] {
// Fill 若从父容器主轴得到无界 base,但父本轮 offer 有限,则用内容可用长度测量,后面再参与权重分配。
if dimension == crate::box_model::Dimension::Fill
&& base[axis + 2] >= MAX_DIMENSION as f32
&& available < MAX_DIMENSION as f32
@@ -333,6 +346,7 @@ pub fn initial_child_constraints(
/// including a source parent's allocation rather than only constructor size.
/// 根据已分配父尺寸重新细化子项约束,使实际安排能够反向影响换行等测量。
pub fn arranged_child_constraints(node: &UiNode, available: [f32; 4], bounds: Size) -> [f32; 4] {
// 滚动允许轴无界以容纳内容,禁用轴使用实际已安排的视口尺寸,文字才能按最终交叉轴宽度换行。
if let UiKind::Scroll { axis, .. } = node.kind {
let padding = insets(node);
return [
@@ -364,6 +378,7 @@ pub fn constrained(size: Size, constraints: [f32; 4]) -> Size {
/// Effective content inset, including borders, in border-box coordinates.
/// 计算布局使用的有效内边距和边框占用,兼容旧的统一 padding。
pub fn insets(node: &UiNode) -> Insets {
// 单边 padding 优先,其次兼容容器的统一 padding,最后再加 border;其他叶节点无统一 padding 默认值。
let fallback = match node.kind {
UiKind::Row { padding, .. }
| UiKind::Column { padding, .. }
@@ -406,6 +421,7 @@ fn measure_shape(shape: &Shape) -> Result<Size> {
Shape::Padded(shape, padding) => padding.outer(measure_shape(shape)?),
Shape::Text(value, size, width) => {
let style = TextStyle::ui(*size);
// 自然文字宽度与受限换行高度分别测量;布局宽度不超过可用宽度,高度反映完整段落行数。
let intrinsic = text::measure(value, style);
let wrapped = text::measure_wrapped(value, style, *width);
Size {
@@ -418,6 +434,7 @@ fn measure_shape(shape: &Shape) -> Result<Size> {
height: *height,
},
Shape::Container(row, padding, gap, children) => {
// 主轴相加、交叉轴取最大,再加对应 inset 与 n-1 个 gap;saturating_sub 保证零孩子不出现负间距。
let along = children
.iter()
.map(|s| if *row { s.width } else { s.height })
@@ -461,6 +478,7 @@ fn shape(node: &UiNode, children: Vec<Size>, constraints: [f32; 4]) -> Result<Sh
let shape = match &node.kind {
UiKind::Overlay { .. } => {
let padding = insets(node);
// Overlay 取含各自 margin 的子盒最大宽高,不把重叠项逐个相加。
let size = children.into_iter().zip(node.children()).fold(
Size::default(),
|size, (child, node)| {
@@ -476,11 +494,13 @@ fn shape(node: &UiNode, children: Vec<Size>, constraints: [f32; 4]) -> Result<Sh
size.height + padding.vertical(),
)
}
// 独立场景视口按自己的有限盒测量,不因远方世界几何或面板内容大小扩展其布局分配。
UiKind::CanvasViewport { width, height, .. } | UiKind::Viewport3D { width, height, .. } => {
Shape::Rect(*width, *height)
}
UiKind::Canvas { positions, .. } | UiKind::Scene2D { positions, .. } => {
let mut size = Size::default();
// 场景尺寸仅累计孩子右下端最大值;负方向内容不向左上平移整体,导航仍由相机负责。
for (position, child) in positions.iter().zip(children) {
size.width = size.width.max(position[0] + child.width);
size.height = size.height.max(position[1] + child.height);
@@ -511,6 +531,7 @@ fn shape(node: &UiNode, children: Vec<Size>, constraints: [f32; 4]) -> Result<Sh
Shape::Container(row, padding, gap, children)
}
};
// 只有非默认盒尺寸策略才包 Sized 并把约束加入键;文字等自身 Shape 已包含其实际影响测量的参数。
Ok(if node.sizing == crate::box_model::Sizing::default() {
shape
} else {
@@ -530,12 +551,14 @@ pub fn measure_native(node: &UiNode, children: Vec<Size>, constraints: [f32; 4])
pub struct Context {
pub node: Option<std::sync::Arc<UiNode>>,
pub children: Vec<Size>,
// 本轮首次测量的首选尺寸,不应被上轮 flex 实际分配覆盖,否则反复测量会改变伸缩基准。
pub preferred: Vec<Size>,
pub bounds: Option<[f32; 4]>,
}
/// 为单个原生节点按已分配几何生成内容命令;容器背景/边框与整树遍历由外层组织。
pub fn paint_native(node: &UiNode, x: f32, y: f32, size: Size) -> Option<RenderCommand> {
// 文字内容盒需要减 inset 并带 wrap_bounds;Rect/Button 背景则画完整 border-box。
let size_for_text = size;
let inset = insets(node);
match &node.kind {
@@ -580,6 +603,7 @@ pub fn paint_native(node: &UiNode, x: f32, y: f32, size: Size) -> Option<RenderC
/// 从一个节点及其分配几何生成原生绘制命令,包括背景、边框与内容。
pub fn paint_commands(node: &UiNode, x: f32, y: f32, size: Size) -> Vec<RenderCommand> {
let mut commands: Vec<_> = paint_native(node, x, y, size).into_iter().collect();
// 边框按四个零圆角条分别追加,宽厚各自钳到盒大小;不使用单一 stroke_width 混淆不等厚四边。
let border = node.border;
for [x, y, width, height] in [
[x, y, size.width, border.top.min(size.height)],
@@ -639,6 +663,7 @@ fn main_limits(child: &UiNode, row: bool) -> (f32, f32) {
/// 按权重分配主轴剩余空间,尊重每项 min/max;达到上限的项退出后重新分配剩余量。
pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[Size]) -> Vec<Size> {
// Overlay 各孩子独立填内容盒,不共享主轴剩余量;普通线性容器才做下方加权增长/收缩。
if matches!(node.kind, UiKind::Overlay { .. }) {
let inset = insets(node);
return children
@@ -668,6 +693,7 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
};
let nodes = node.children();
let mut output = children.to_vec();
// 先处理交叉轴 Stretch,仅 Auto 维度可拉伸;明确 Fixed 不因父对齐策略被改写。
for (child, size) in nodes.iter().zip(&mut output) {
if child.align_self.unwrap_or(node.cross_align) == CrossAlign::Stretch {
let sizing = child.sizing;
@@ -682,9 +708,11 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
}
}
}
// 无主轴伸缩需求时也可能已完成交叉轴拉伸,直接返回这份 output,不丢弃上面调整。
if !nodes.iter().any(|child| child.has_flex()) {
return output;
}
// 可分配主轴空间先扣父 inset、每个孩子两侧 margin 和固定 gap;使用 f64 累计减小权重分配误差。
let space = ((if row { bounds.width } else { bounds.height }) as f64
- if row {
padding.horizontal()
@@ -703,6 +731,7 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
.sum::<f32>() as f64
- gap as f64 * children.len().saturating_sub(1) as f64)
.max(0.0);
// 显式 basis 优先;grow/fill 默认从零参与分配,其余用 preferred,不拿已经压缩后的 children 充当自然基准。
let bases: Vec<f64> = nodes
.iter()
.zip(preferred)
@@ -726,8 +755,10 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
basis.clamp(min as f64, max as f64)
})
.collect();
// 初始 basis 先钳 min/max,剩余正数为增长,负数为收缩;非参与项仍占据其合法基准尺寸。
let free = space - sizes.iter().sum::<f64>();
let growing = free > 0.0;
// 增长按 flex,主轴 Fill 且 flex=0 用权重1;收缩按 shrink×原 basis,保持大内容承担较多缩减。
let weights: Vec<f64> = nodes
.iter()
.zip(&bases)
@@ -750,6 +781,7 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
if growing { max as f64 } else { min as f64 }
})
.collect();
// 只让有正权重且未到 min/max 的项参与,每轮触顶/到底的项退出,剩余空间继续分给未饱和者。
let mut active: Vec<usize> = (0..nodes.len())
.filter(|&i| {
weights[i] > 0.0
@@ -767,6 +799,7 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
let mut saturated = false;
for &i in &active {
let capacity = (limits[i] - sizes[i]).abs();
// 本轮按同一 remaining 比例计算,再限制到该项剩余容量;不能为单项超配后再粗暴钳制丢掉剩余量。
let amount = (remaining * weights[i] / total).min(capacity);
sizes[i] += if growing { amount } else { -amount };
spent += amount;
@@ -775,6 +808,7 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
remaining = (remaining - spent).max(0.0);
// Without saturation this round distributed all available space. Do not
// spin on floating point residue; a saturated round freezes a child.
// 没有项饱和说明比例分配已完成,微小浮点残差不能导致无进展死循环。
if !saturated {
break;
}
@@ -804,6 +838,7 @@ pub fn arrange_native(
bounds: Size,
children: &[Size],
) -> Result<Vec<(f32, f32)>> {
// 3D 面板根在各自纹理空间均从 (0,0) 开始,世界摆放交由 Panel world 矩阵,不把世界坐标写入普通 UI 布局。
if matches!(node.kind, UiKind::Viewport3D { .. }) {
return Ok(node.children().iter().map(|_| (0., 0.)).collect());
}
@@ -881,6 +916,7 @@ pub fn arrange_native(
MainAlign::End => spare,
_ => 0.0,
};
// space-between 只在至少两个孩子间分配额外剩余量,原固定 gap 仍保留;单项保持 start。
let distributed_gap = if node.main_align == MainAlign::SpaceBetween && children.len() > 1 {
spare / (children.len() - 1) as f32
} else {
@@ -920,6 +956,7 @@ pub fn arrange_native(
coordinate(point.0 + child.width)?;
coordinate(point.1 + child.height)?;
points.push(point);
// 主轴游标推进当前盒尺寸、两侧 margin、固定及额外 gap;交叉轴对齐不改变主轴顺序。
cursor += if row { child.width } else { child.height };
cursor += if row {
margin.horizontal()
@@ -954,6 +991,7 @@ impl LayoutRuntime {
/// 清空结构出现身份表;业务对象和源状态不因此被复制。
pub fn clear_occurrences(&mut self) {
// 清出现映射不重置 next_id,高水位继续增加,避免旧事件与新出现数值身份意外重合。
self.ids.clear();
}
/// 在临时 LayoutRuntime 中生成完整几何,成功后才替换现有缓存和身份状态。
@@ -982,6 +1020,7 @@ impl LayoutRuntime {
children: Vec<Size>,
constraints: [f32; 4],
) -> Result<Size> {
// 缓存只有完整 Shape 相等才复用,纯颜色变化不在测量 Shape 中,因此无需重做尺寸求解。
let shape = shape(node, children, constraints)?;
if let Some((_, size)) = self
.sizes
@@ -1003,12 +1042,14 @@ impl LayoutRuntime {
self.settle_passes = usize::from(!structural);
self.slices = usize::from(!structural);
let mut items = Vec::<Item<'_>>::new();
// 用显式栈构建父先子后 items,根采用 slot0/无父;孩子逆序入栈保持原始布局顺序。
let mut work = vec![(root, None::<usize>, 0, self.root_constraints())];
let mut used = HashSet::new();
while let Some((node, parent, slot, constraints)) = work.pop() {
if items.len() >= MAX_LAYOUT_VISITS {
bail!("expanded UI layout exceeds 10000 nodes");
}
// slot 与孩子必须一一对应,否则稳定出现身份不可信,不能用 zip 静默丢掉多余项。
if node.slots.len() != node.children().len() {
bail!("invalid child slot table");
}
@@ -1017,6 +1058,7 @@ impl LayoutRuntime {
slot,
block: node.block_id.clone(),
};
// 结构三元组未变则复用 ID,新出现 checked_add 分配;只在成功构建副本后才提交整表。
let id = if let Some(id) = self.ids.get(&key) {
*id
} else {
@@ -1027,6 +1069,7 @@ impl LayoutRuntime {
self.ids.insert(key.clone(), self.next_id);
self.next_id
};
// 同一展示出现键不得重复;共享组件在不同父或不同 slot 下使用不同 key,仍允许多次出现。
if !used.insert(key) {
bail!("duplicate child slot in one presentation");
}
@@ -1054,6 +1097,7 @@ impl LayoutRuntime {
}
let mut sizes = vec![Size::default(); items.len()];
if !structural {
// 反向 items 自底向上测量,孩子尺寸已经求出;structural=true 完全跳过此步骤,零几何仅用于挂载准备。
for (index, item) in items.iter().enumerate().rev() {
sizes[index] = constrained(
self.measure_node(
@@ -1069,6 +1113,7 @@ impl LayoutRuntime {
let mut mounts = Vec::with_capacity(items.len());
let mut commands = Vec::new();
let mut siblings = vec![None; items.len()];
// 先按每个父的孩子顺序建立 next_sibling,最后一个默认 None;这与业务孩子列表身份不同。
for item in &items {
for pair in item.children.windows(2) {
siblings[pair[0]] = Some(items[pair[1]].id);
@@ -1113,6 +1158,7 @@ impl LayoutRuntime {
continue;
}
let child_sizes: Vec<_> = item.children.iter().map(|child| sizes[*child]).collect();
// 自顶向下用父实际尺寸更新孩子分配后再求原点;更复杂的源协议反复求解由 source_layout 驱动。
let child_sizes = flex_sizes(item.node, size, &child_sizes, &child_sizes);
for (child, allocated) in item.children.iter().zip(&child_sizes) {
sizes[*child] = *allocated;
@@ -1126,6 +1172,7 @@ impl LayoutRuntime {
points[*child] = point;
}
}
// 成功求解后丢弃已消失出现和不在本树的测量缓存,避免历史页面不断积累派生条目。
self.ids.retain(|key, _| used.contains(key));
let blocks: HashSet<_> = items
.iter()
@@ -1133,6 +1180,7 @@ impl LayoutRuntime {
.collect();
self.sizes
.retain(|block, _| blocks.contains(block.as_str()));
// 每次结构/完整构建成功都推进版本,禁止溢出复用;该版本用于后续 Mount/输入归属校验。
self.version = self
.version
.checked_add(1)
+16 -1
View File
@@ -1,20 +1,35 @@
//! 渲染模块入口。排版、源视觉协议、相机投影和最终光栅化各自独立,通过不可变帧衔接。
//!
// Module ownership follows the directory; crate-root aliases keep internal call sites stable.
// 目录确定模块归属;main 中的 crate 根别名保持内部调用路径稳定。
/// 计算边框、内外边距和内容区域,并应用容器主轴/交叉轴分配规则。
pub(crate) mod box_model;
/// 表达与转换绘图命令,集中处理显示列表裁剪和坐标变换。
pub(crate) mod display_list;
/// 提供点、矩形等基础几何运算,供布局、命中和绘制共享。
pub(crate) mod geometry;
/// 实现原生布局求解、约束分配及可重用的尺寸/几何数据结构。
pub(crate) mod layout;
/// 适配原生视觉方法的测量、排列与绘制行为,供语言桥接和纯布局流程使用。
pub(crate) mod native_visual;
/// 描述整页表面模式、平移缩放和视口到世界坐标转换。
pub(crate) mod page;
/// 组合页面、侧栏和开发工具的整窗显示列表,并返回宿主输入所需布局。
pub(crate) mod scene;
/// 完成三维投影、射线拾取、裁剪与软件深度光栅化;子模块拆分数学、空间索引和世界 UI 面板。
pub(crate) mod scene3d;
/// 计算每个出现位置的滚动范围、裁剪和滚轮目标,嵌套滚动按可消费方向选择。
pub(crate) mod scroll;
/// 将完整显示列表写入像素缓冲;处理二维命令以及嵌套场景表面的最终合成。
pub(crate) mod software_renderer;
/// 在受控只读上下文调用源 hitTest,结合出现位置与可见性判断输入目标。
pub(crate) mod source_hit;
/// 用可恢复 VM 调用执行源 measure/arrange,追踪读依赖并迭代到几何稳定后产出草稿。
pub(crate) mod source_layout;
/// 分片执行源 paint 并验证/解码返回命令;未完成的绘制不能当作完整帧发布。
pub(crate) mod source_paint;
/// 使用系统字体塑形、换行和字形缓存,统一测量与像素绘制的文字尺寸。
pub(crate) mod text;
/// 处理二维场景相机、局部视口投影和空间查询,供绘制与命中使用相同变换。
pub(crate) mod viewport;
pub mod image;
+35 -5
View File
@@ -41,6 +41,7 @@ pub(crate) fn number(
.to_string()
.parse::<f32>()
.map_err(|_| invalid("invalid visual number"))?;
// 所有协议数值须有限且位于世界尺寸预算内;signed 区分坐标(可负)与长度/约束(非负)。
if !value.is_finite() || value.abs() > MAX_DIMENSION as f32 || (!signed && value < 0.0) {
return Err(invalid("visual number exceeds bounds"));
}
@@ -48,6 +49,7 @@ pub(crate) fn number(
}
/// 将原生布局计算结果封装为协议需要的托管 Value。
pub(crate) fn value(value: f32) -> Value {
// 原生 f32 提升到 f64 包装为 Endor Number;本函数不单独校验,调用路径必须已保证输入合法。
Value::Number((value as f64).into())
}
/// 新建指定名义类型的托管记录,并逐项设置字段,作为视觉协议的结果返回。
@@ -57,6 +59,7 @@ pub(crate) fn record(
kind: &str,
fields: Vec<(&str, Value)>,
) -> Result<ObjectRef, VmError> {
// 先赋精确名义类型,再初始化字段;只读协议可创建结果对象,但不能借机写入旧业务图。
let object = cx.new_object()?;
attach_desktop_type(cx, object, kind, desktop)?;
for (key, value) in fields {
@@ -64,8 +67,9 @@ pub(crate) fn record(
}
Ok(object)
}
/// 在约束提供的视口内执行原生布局,从根出现提取宽高,再按协议约束限制结果。
/// 以最大宽高作视口执行原生布局并提取根尺寸;最小/最大最终钳制由 Measure 分支负责。
fn size(node: &crate::ui_bridge::UiNode, constraints: [f32; 4]) -> Result<Size, VmError> {
// 无 staged 子测量结果时,使用有限最大约束运行原生布局取得根尺寸;最终 min/max 钳制在调用方 Measure 分支。
let frame = layout::frame_with_viewport(
node,
Size {
@@ -106,6 +110,7 @@ pub(crate) fn is_intrinsic(
name: &str,
desktop: ObjectRef,
) -> Result<bool, VmError> {
// 快速路径仅认可实际 ContextNativeFunction 的 Method 实现,函数名相同或签名相似的源函数不能冒充。
let Some(function) = store
.object(function)?
.payload()
@@ -118,6 +123,7 @@ pub(crate) fn is_intrinsic(
return Ok(false);
};
// Per-window desktops share the same nominal registry and intrinsic bodies.
// 同一 VM 不同窗口 desktop 可共享 types 字典,所以以注册表身份允许复用原生方法体。
let same_registry = method.desktop == desktop
|| matches!(
(store.get_attr(method.desktop, "types")?, store.get_attr(desktop, "types")?),
@@ -138,24 +144,27 @@ impl NativeCallable for Method {
fn signature(&self) -> Option<CallSignature> {
Some(self.signature.clone())
}
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 接收三项底层参数:Block 接收者、具体 Mount、Constraints/Bounds/Point 协议输入。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(3))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 检查 Block/Mount 归属与有效性,再按 measure/arrange/paint/hitTest 执行原生视觉协议并返回受检查的托管值。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
// 三个实际参数含接收者 Block、具体 Mount 和协议输入;几何属于 Mount,不能仅凭 Block 身份查询。
let [owner, context, input] = args else {
return Err(invalid("visual method expects a Mount and an input value"));
};
let owner = object(owner)?;
let mount = cx.store().payload::<Mount>(object(context)?, "Mount")?;
// 默认协议也校验上下文归属,防止调用者把另一个出现的几何套到当前组件。
if !mount.mounted || mount.block != owner {
return Err(invalid(
"visual context is detached or belongs to another Block",
));
}
let geometry = mount.geometry.clone();
// 布局阶段从临时 Context 取当前节点、孩子实测尺寸与首选尺寸;克隆派生数据后释放锁再进行计算。
let staged = mount
.layout
.as_ref()
@@ -171,6 +180,7 @@ impl NativeCallable for Method {
})
.transpose()?;
let input = object(input)?;
// 默认 hitTest 检查局部点在已提交盒内,采用左上包含、右下排除;布局阶段几何不稳定,禁止调用。
if matches!(self.query, Query::HitTest) {
if staged.is_some() {
return Err(invalid("hitTest is unavailable during layout"));
@@ -181,11 +191,13 @@ impl NativeCallable for Method {
x >= 0.0 && y >= 0.0 && x < geometry.width && y < geometry.height,
)));
}
// 存在布局 Context 但尚无当前节点,说明准备顺序不完整,不能回退读取旧快照伪装成当前数据。
if matches!(&staged, Some((None, _, _))) {
return Err(invalid(
"layout context is not prepared for this occurrence",
));
}
// 准备好则复用本轮不可变节点,非 staged 调用才从托管 Block 提取视觉快照。
let node = if let Some((Some(node), _, _)) = &staged {
node.clone()
} else {
@@ -197,9 +209,11 @@ impl NativeCallable for Method {
let min_h = number(cx, input, "minHeight", false)?;
let max_w = number(cx, input, "maxWidth", false)?;
let max_h = number(cx, input, "maxHeight", false)?;
// 最小值不可超过最大值,否则后面的 clamp 会无意义甚至失败;各数值已通过非负有限检查。
if min_w > max_w || min_h > max_h {
return Err(invalid("minimum exceeds maximum constraint"));
}
// 混合源/原生布局使用已经测好的子尺寸,避免重复执行子树;独立调用则走完整原生测量。
let size = if let Some((_, children, _)) = &staged {
layout::measure_native(&node, children.clone(), [min_w, min_h, max_w, max_h])
.map_err(|_| invalid("native measurement exceeds layout limits"))?
@@ -211,6 +225,7 @@ impl NativeCallable for Method {
self.desktop,
"MeasureResult",
vec![
// MeasureResult 最终明确落在传入 min/max 内,原生内容自然大小不能突破源协议约束。
("width", value(size.width.clamp(min_w, max_w))),
("height", value(size.height.clamp(min_h, max_h))),
],
@@ -224,6 +239,7 @@ impl NativeCallable for Method {
if x + width > MAX_DIMENSION as f32 || y + height > MAX_DIMENSION as f32 {
return Err(invalid("visual bounds exceed limits"));
}
// Arrange 优先使用本轮子测量;没有 staged 时按孩子的实际分配约束逐个测量后再安排。
let children = if let Some((_, children, _)) = &staged {
children.clone()
} else {
@@ -248,16 +264,19 @@ impl NativeCallable for Method {
})
.collect::<Result<Vec<_>, _>>()?
};
// preferred 保留弹性分配所需首选大小,与已受约束的实测 children 区分;无 staged 时两者相同。
let preferred = staged
.as_ref()
.map_or(children.as_slice(), |(_, _, preferred)| {
preferred.as_slice()
});
// 先依据父盒分配 flex 尺寸,再由 arrange_native 求位置,避免先定位再改变孩子大小导致重叠。
let children =
layout::flex_sizes(&node, Size { width, height }, &children, preferred);
let points = layout::arrange_native(&node, x, y, Size { width, height }, &children)
.map_err(|_| invalid("native arrangement exceeds limits"))?;
let mut result = Vec::new();
// 每个返回 Bounds 附稳定 slot,与 children 当前顺序分开;调用方可按 slot 校验组成身份。
for ((slot, size), (x, y)) in node.slots.iter().zip(children).zip(points) {
let bounds = record(
cx,
@@ -273,6 +292,7 @@ impl NativeCallable for Method {
cx.set_attr(bounds, "slot", Value::Number((*slot as i64).into()))?;
result.push(bounds);
}
// Arrangement 返回受控 ObjectList,不返回宿主 Vec 或任意形状的源对象集合。
let result = crate::object_list::collection(cx, result, self.desktop)?;
Value::Object(record(
cx,
@@ -290,6 +310,7 @@ impl NativeCallable for Method {
return Err(invalid("visual bounds exceed limits"));
}
let mut commands = Vec::new();
// 将 Rust 默认绘制命令反向编码成源 PaintCommand,允许源覆盖方法调用基类 paint 后继续组合。
for command in layout::paint_commands(&node, x, y, Size { width, height }) {
let fields = match command {
RenderCommand::Scene3D {
@@ -299,6 +320,7 @@ impl NativeCallable for Method {
height,
view,
} => {
// 3D 通过不可变 PaintView payload 暴露场景快照,不把运行中 VM 的场景对象交给后续绘制线程。
let snapshot = cx.allocate(crate::scene3d::PaintView(view))?;
vec![
("kind", Value::Text("scene3d".into())),
@@ -325,6 +347,7 @@ impl NativeCallable for Method {
("size", Value::Number((size as i64).into())),
("color", Value::Text(color)),
];
// 可选文本换行边界成对写入;缺省时两个字段都不创建,与源 paint 解码契约保持一致。
if let Some([width, height]) = wrap_bounds {
fields.push(("wrapWidth", value(width)));
fields.push(("wrapHeight", value(height)));
@@ -347,6 +370,7 @@ impl NativeCallable for Method {
("radius", value(radius)),
("color", Value::Text(color)),
],
// 当前反向编码支持明确列出的命令;新增 RenderCommand 变体时须同步此转换,不能静默丢弃。
_ => return Err(invalid("unsupported native paint command")),
};
let command = record(cx, self.desktop, "PaintCommand", fields)?;
@@ -378,7 +402,7 @@ impl NativeCallable for PointMethod {
fn signature(&self) -> Option<CallSignature> {
Some(self.signature.clone())
}
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 圆形测试接收 Point 加圆心/半径共四项;矩形测试接收 Point 和 Bounds 共两项。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(if self.circle {
4
@@ -387,11 +411,12 @@ impl NativeCallable for PointMethod {
}))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 先验证 Point 名义类型与有限坐标,再分别计算圆内距离或 Bounds 包含关系,返回 Bool。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
let Some(Value::Object(point)) = args.first() else {
return Err(invalid("Point method requires a Point"));
};
// Point 辅助方法验证名义接收者,不能只要有 x/y 字段就接受普通对象。
if !cx.store().is_instance(*point, self.expected)? {
return Err(invalid("Point method requires a Point"));
}
@@ -407,6 +432,7 @@ impl NativeCallable for PointMethod {
else {
return Err(invalid("inCircle requires center x/y and radius"));
};
// 圆心和半径按 f64 解析及求平方距离,在有界数值内避免不必要的 f32 精度损失。
let parse = |value: &endor_core::EndorNumber| -> Result<f64, VmError> {
let value = value
.to_string()
@@ -420,6 +446,7 @@ impl NativeCallable for PointMethod {
let dx = x as f64 - parse(cx_value)?;
let dy = y as f64 - parse(cy_value)?;
let radius = parse(radius)?;
// 半径不能负;零半径只包含圆心,边界使用 <= 因此圆周也命中。
if radius < 0.0 {
return Err(invalid("circle radius must be nonnegative"));
}
@@ -432,6 +459,7 @@ impl NativeCallable for PointMethod {
let top = number(cx, *bounds, "y", true)?;
let width = number(cx, *bounds, "width", false)?;
let height = number(cx, *bounds, "height", false)?;
// 矩形辅助同样使用半开右/下边界;这与 geometry::Rect 的闭区间 contains 不同,调用方应留意语义。
x >= left && y >= top && x < left + width && y < top + height
};
Ok(NativeResult::Return(Value::Bool(inside)))
@@ -457,6 +485,7 @@ pub fn install(
let measure = nominal("MeasureResult")?;
let arrangement = nominal("Arrangement")?;
let display = nominal("DisplayList")?;
// 把四个默认方法安装到 Block,源子类可覆盖;所有视觉协议声明 ReadOnly,允许派生结果分配而不修改模型。
for (name, query, input, returns) in [
("measure", Query::Measure, constraints, measure),
("arrange", Query::Arrange, bounds, arrangement),
@@ -485,6 +514,7 @@ pub fn install(
&vm.dict_get(registry, &Value::Text("Point".into()))?
.ok_or(invalid("missing Point type"))?,
)?;
// Point.inside 接收 Bounds,inCircle 接收圆心 x/y 和半径;签名都包含隐式 Point receiver。
for (name, circle) in [("inside", false), ("inCircle", true)] {
let function = vm.allocate(ContextNativeFunction::new(
name,
+20 -1
View File
@@ -12,9 +12,13 @@ use serde::{Deserialize, Serialize};
/// 旧 Page 的有限或自由空间模式,新场景视口不依赖它表达布局方向。
pub enum Mode {
#[default]
// 双轴被原生视口限制;兼容相机固定在原点且比例为 1。
Window,
// 宽度固定,高度允许展开到布局上限,只沿 y 方向导航。
Vertical,
// 高度固定,宽度允许展开到布局上限,只沿 x 方向导航。
Horizontal,
// 双轴自由布局并允许平移缩放;相机不按内容边缘钳制。
Canvas,
}
@@ -44,10 +48,12 @@ impl Mode {
/// 为旧页面模式生成有限轴和可延伸轴的根约束。
pub fn constraints(self, viewport: Option<Size>) -> [f32; 4] {
// 未收到原生视口尺寸时采用布局默认根约束;不能凭空建立固定宽高。
let Some(size) = viewport else {
return crate::layout::root_constraints(None);
};
let limit = crate::ui_bridge::MAX_DIMENSION as f32;
// 数组采用 [最小宽, 最小高, 最大宽, 最大高];竖/横页面仍至少占满当前视口。
match self {
Self::Window => [size.width, size.height, size.width, size.height],
Self::Vertical => [size.width, size.height, size.width, limit],
@@ -61,10 +67,13 @@ impl Mode {
/// 页面级兼容相机状态和有限内容范围,支持绘制与命中正逆变换。
pub struct Surface {
pub mode: Mode,
// 发布给原生侧的页面身份文本,不是托管强引用。
pub page: String,
// 视图左上角对应的世界坐标;绘制时先减 pan 再乘 zoom。
pub pan: Point,
#[serde(default = "unit")]
pub zoom: f32,
// 布局产出的内容宽高,用于有限模式钳制;不决定 Canvas 的导航边界。
pub extent: Size,
}
@@ -87,7 +96,7 @@ impl Default for Surface {
}
impl Surface {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 指定页面模式并显式使用单位缩放,其他字段采用空页面默认值;无需分配 VM 或原生窗口资源。
pub fn new(mode: Mode) -> Self {
Self {
mode,
@@ -97,6 +106,7 @@ impl Surface {
}
/// 把页面视图坐标反算为旧 Page 相机下的世界坐标。
// 输入在视图空间,先除缩放再加世界偏移;调用方需保证 zoom 有限且大于零。
pub fn to_world(&self, point: Point) -> Point {
Point::new(
point.x / self.zoom + self.pan.x,
@@ -105,6 +115,7 @@ impl Surface {
}
/// 把旧页面世界坐标变换到可见视图坐标。
// 输入在世界空间,先减相机偏移再缩放,恰与 to_world 互逆。
pub fn to_view(&self, point: Point) -> Point {
Point::new(
(point.x - self.pan.x) * self.zoom,
@@ -114,6 +125,8 @@ impl Surface {
/// 判断给定点是否位于目标范围;需要相机转换的类型会先转换再判断。
pub fn contains(&self, point: [f32; 2], viewport: Option<Size>) -> bool {
// 传入的数组是世界坐标。转换后使用左/上包含、右/下排除的视口边界;
// 未知视口时仍排除负坐标,但不限制右/下界。
let point = self.to_view(Point::new(point[0], point[1]));
point.x >= 0.0
&& point.y >= 0.0
@@ -122,6 +135,8 @@ impl Surface {
/// 只对有限页面按实际内容范围钳制偏移;自由画布不按内容边缘停止导航。
pub fn clamp(&mut self, viewport: Size) {
// Window 重置所有导航;单轴模式清除另一轴并恢复单位缩放。
// 内容小于视口时 max(0) 令可滚动范围归零,避免 clamp 出现反向上下限。
match self.mode {
Mode::Window => {
self.pan = Point::default();
@@ -153,7 +168,9 @@ mod tests {
use super::*;
#[test]
/// 检查页面相机的往返变换,缩放时反求 pan 使指针下世界点固定,并按视口验证世界点可见性。
fn camera_inverse_and_cursor_anchored_zoom_preserve_world_position() {
// 先验证相机正逆变换,再改变 zoom 并反求 pan,保证指针下的世界点不发生漂移。
let mut view = Surface::new(Mode::Canvas);
view.pan = Point::new(-240.0, 120.0);
view.zoom = 0.75;
@@ -183,7 +200,9 @@ mod tests {
}
#[test]
/// 纵向页面将过大偏移夹到内容减视口范围;内容缩短到视口以内后偏移必须归零,横向偏移也禁用。
fn finite_pages_clamp_after_content_shrinks() {
// 先将 900 的旧偏移钳到 800-600=200,再缩短内容至视口以内,确认偏移回零。
let mut view = Surface::new(Mode::Vertical);
view.pan = Point::new(25.0, 900.0);
view.extent = Size {
+8
View File
@@ -25,6 +25,7 @@ pub fn build_scene(
activity: &Activity,
sidebar: &mut crate::sidebar::State,
) -> DisplayScene {
// 活动标签的 developer_tool 标记决定管理页类型,不靠当前窗口标题猜测;同步工具状态后再合成。
let tool = document
.frame
.tabs
@@ -35,23 +36,28 @@ pub fn build_scene(
developer_tools_state.document_updated(document);
let left = sidebar.left();
let surface = &document.frame.surface;
// width/height 为设备像素,sidebar.left 为逻辑单位,先乘 scale 得到页面可用裁剪区域。
let content = Rect::new(
left * scale,
0.0,
(width as f32 - left * scale).max(0.0),
height as f32,
);
// 管理页使用单位页面缩放,避免业务 Page 相机改变宿主工具字号;普通页叠加旧 Surface zoom。
let zoom = if tool.is_some() { 1.0 } else { surface.zoom };
// 显示列表转换失败时降级为空默认文档;这只保护原生绘制,不把无效命令伪装成成功执行。
let mut page = document.display_list(scale * zoom).unwrap_or_else(|_| {
RenderDocument::default()
.display_list(scale)
.expect("default document is valid")
});
// 页面显示列表先已乘设备比例/zoom,再加入侧栏偏移和世界 pan 的设备像素平移,保持缩放顺序一致。
page.translate(Point::new(
(left - surface.pan.x * zoom) * scale,
-surface.pan.y * zoom * scale,
));
let mut display_list = DisplayList::default();
// 全窗只做一次 Clear,后续跳过页面列表自身 Clear,防止其覆盖侧栏或突破页面裁剪。
display_list.push(DrawCommand::Clear(
crate::document::parse_color(&document.frame.background)
.unwrap_or(crate::system_ui::theme::BG),
@@ -71,9 +77,11 @@ pub fn build_scene(
developer_tools_state,
activity,
);
// 工具命令在设备空间平移,交互布局在逻辑空间平移,两者比例不同但实际对齐同一页面起点。
developer_list.translate(Point::new(left * scale, 0.0));
developer_layout.translate(left, 0.0);
display_list.extend(developer_list);
// 侧栏最后覆盖合成,内部按逻辑尺寸绘制后统一设备缩放,不受页面相机影响。
let mut chrome = sidebar.draw(
&document.frame.tabs,
height as f32 / scale,
+43 -3
View File
@@ -23,8 +23,10 @@ pub struct Geometry {
pub uv: Vec<[f32; 2]>,
}
impl Geometry {
/// 检查数值、几何和资源条件是否满足本类型约束,供上层拒绝非法输入。
/// 检查顶点与三角数量、索引范围、坐标有效性及逐顶点 UV;允许缺省 UV,不在此限制 UV 到单位区间。
pub fn valid(&self) -> bool {
// 检查顶点/三角形资源量和所有索引范围;UV 可省略,否则必须逐顶点对应且每个分量有限。
// 不在这里强制 UV 位于 [0,1],纹理采样阶段再钳制。
self.vertices.len() <= MAX_VERTICES
&& (self.uv.is_empty()
|| self.uv.len() == self.vertices.len()
@@ -39,6 +41,7 @@ impl Geometry {
}
/// 生成以原点为中心的盒体顶点和三角形索引;位置和旋转由网格世界矩阵另行描述。
pub fn cuboid(width: f32, height: f32, depth: f32) -> Self {
// 八个角点共享位置,每个面拆两个三角形;尺寸有效性由构造调用边界检查,cuboid 本身只生成数值。
let (x, y, z) = (width / 2., height / 2., depth / 2.);
Self {
uv: vec![],
@@ -72,6 +75,7 @@ impl Geometry {
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
/// 一次场景实例:几何、世界矩阵、颜色与可选 UI 面板,身份用于拾取回关联。
pub struct Mesh {
// 纯文本业务关联身份,用于拾取返回;不作为渲染线程可操作的托管引用。
pub identity: String,
pub geometry: Arc<Geometry>,
pub world: Matrix,
@@ -110,6 +114,7 @@ pub struct Scene {
pub ambient: f32,
pub background: [f32; 3],
#[serde(skip)]
// 序列化忽略的世界 BVH,反序列化后可按场景网格重建;相机改变不要求重建世界空间索引。
pub acceleration: Arc<spatial::Index>,
}
impl PartialEq for Scene {
@@ -153,13 +158,13 @@ pub struct Hit {
}
impl View {
/// 检查数值、几何和资源条件是否满足本类型约束,供上层拒绝非法输入。
/// 递归验证相机、材质、灯光、网格/面板表面及全场景资源预算;世界 UI 嵌套最多八层。
pub fn valid(&self) -> bool {
thread_local! { static DEPTH:std::cell::Cell<usize>=const { std::cell::Cell::new(0) }; }
// 验证可能递归进入面板内的 3D;作用域结束时归还深度,错误返回也不泄漏计数。
struct Guard;
impl Drop for Guard {
/// 在 Rust 所有者离开作用域时执行本类型的配套清理;不能用它代替需要报告错误的显式关闭。
/// 退出当前嵌套校验层时递减线程局部深度;短路失败与正常返回都恢复同一计数。
fn drop(&mut self) {
DEPTH.with(|depth| depth.set(depth.get() - 1));
}
@@ -174,12 +179,14 @@ impl View {
}) {
return false;
}
// 深度检查通过才建立 Guard,之后任一短路校验失败都会恢复计数;上限覆盖嵌套面板中的 3D 命令。
let _guard = Guard;
let color_valid = |color: [f32; 3]| {
color
.iter()
.all(|value| value.is_finite() && (0.0..=1.0).contains(value))
};
// 同时限制实例数、灯光数、累计顶点数和三角形数,单个 Geometry 合法不代表整个 Scene 未超预算。
self.camera.valid()
&& self.scene.ambient.is_finite()
&& (0.0..=1.0).contains(&self.scene.ambient)
@@ -201,6 +208,7 @@ impl View {
.sum::<usize>()
<= MAX_TRIANGLES
&& self.scene.meshes.iter().all(|mesh| {
// 矩阵系数有限之外还验证每个变换后顶点范围,避免局部几何合法但累计世界变换产生无限坐标。
mesh.geometry.valid()
&& mesh.world.0.iter().all(|v| v.is_finite())
&& color_valid(mesh.color)
@@ -209,6 +217,7 @@ impl View {
.vertices
.iter()
.all(|point| mesh.world.point(*point).valid())
// 面板纹理限制在 1..2048 每轴,内部命令/视图/裁剪表等长并递归校验绘制;多一个命令额度留给装配焦点框。
&& mesh.panel.as_ref().is_none_or(|panel| {
panel.width > 0
&& panel.height > 0
@@ -235,6 +244,7 @@ impl View {
&& self.scene.lights.iter().all(|light| {
color_valid(light.color)
&& light.direction.valid()
// 方向光必须近似单位向量,确保点积仅反映夹角而非把方向模长重复乘入光照强度。
&& (light.direction.length() - 1.).abs() < 0.0001
&& light.intensity.is_finite()
&& (0.0..=32.0).contains(&light.intensity)
@@ -242,6 +252,7 @@ impl View {
}
/// 按包围盒候选发射射线,再检查三角形;距离相同时保留与绘制顺序一致的实例。
pub fn pick(&self, u: f32, v: f32, aspect: f32) -> Option<Hit> {
// 拾取只接受有效相机、视口内归一化点及正有限宽高比;不在此完整重验几何,调用方应先验证 View。
if !self.camera.valid()
|| !(0.0..=1.0).contains(&u)
|| !(0.0..=1.0).contains(&v)
@@ -254,6 +265,7 @@ impl View {
let basis = self.camera.basis()?;
let mut hit: Option<Hit> = None;
let temporary;
// 无缓存或网格数失配时本次临时重建;数量相同的内容变更须由快照层生成新索引,不靠 matches 检测。
let index = if self.scene.acceleration.matches(self.scene.meshes.len()) {
&*self.scene.acceleration
} else {
@@ -261,6 +273,7 @@ impl View {
&temporary
};
for (entry, instance) in index.ray(ray) {
// BVH 候选按包围盒进入距离排序;后续盒子起点已比最近真实交点远时,可安全停止查询。
if hit.as_ref().is_some_and(|hit| entry > hit.distance) {
break;
}
@@ -272,6 +285,7 @@ impl View {
continue;
};
let point = ray.origin + ray.direction * distance;
// near/far 限制相机前向深度,而不是到相机的欧氏距离;离轴射线同样按视锥范围筛选。
let depth = self.camera.view(basis, point).z;
if depth < self.camera.near
|| depth > self.camera.far
@@ -282,9 +296,11 @@ impl View {
{
continue;
}
// 使用变换后的世界顶点计算面法线,支持非均匀缩放;退化三角形没有可靠法线,不作为命中。
let Some(normal) = (b - a).cross(c - a).normalized() else {
continue;
};
// 同距离时保留较早实例,与绘制严格小于深度比较一致;同实例后续同距三角形也不会覆盖前者。
hit = Some(Hit {
instance,
identity: mesh.identity.clone(),
@@ -331,6 +347,7 @@ pub fn surface(
height: u32,
aspect: f32,
) -> Result<Arc<[u32]>, &'static str> {
// 全局缓存以 View Arc 身份+输出尺寸+aspect 为键;值相等但不同 Arc 的视图不会自动命中。
static CACHE: std::sync::OnceLock<std::sync::Mutex<SurfaceCache>> = std::sync::OnceLock::new();
let cache = CACHE.get_or_init(Default::default);
{
@@ -348,6 +365,7 @@ pub fn surface(
// 3D viewport and recurse through the compositor.
let pixels: Arc<[u32]> = render_aspect(view, width, height, aspect)?.into();
let mut cache = cache.lock().map_err(|_| "3D surface cache poisoned")?;
// 按插入顺序从队首淘汰,不在命中时搬到队尾;最多 8 项、累计 8388608 像素,渲染单表面另有限额。
while cache.entries.len() >= 8 || cache.pixels + pixels.len() > 8_388_608 {
let Some(entry) = cache.entries.pop_front() else {
break;
@@ -387,6 +405,7 @@ impl Vertex {
}
/// 生成相机空间六个视锥平面,供三角形裁剪与 BVH 可见性查询共用。
fn frustum_planes(camera: Camera, aspect: f32) -> [[f32; 4]; 6] {
// 平面内侧满足 ax+by+cz+d>=0。透视侧平面随 z 展开,正交侧平面是固定 x/y 边界。
let (x, y, slope) = match camera.projection {
Projection::Perspective { fov } => {
let y = (fov.to_radians() / 2.).tan();
@@ -414,10 +433,12 @@ fn clip(mut polygon: Vec<Vertex>, camera: Camera, aspect: f32) -> Vec<Vertex> {
a * p.x + b * p.y + c * p.z + d
};
let mut output = Vec::new();
// 从闭多边形最后一点连到第一点开始,逐边做 Sutherland–Hodgman 裁剪,不遗漏首尾边。
let mut previous = *polygon.last().unwrap();
let mut before = distance(previous);
for current in polygon {
let after = distance(current);
// 边跨平面时按带符号距离求交点比例,同步插值相机位置和 UV;内侧端点另行保留。
if (before >= 0.) != (after >= 0.) {
output.push(previous.lerp(current, before / (before - after)));
}
@@ -445,6 +466,7 @@ fn render_aspect(
aspect: f32,
) -> Result<Vec<u32>, &'static str> {
let _scope = crate::software_renderer::RenderScope::enter()?;
// 颜色与深度各占一份面积,既有每表面硬上限,也在下方计入递归累计像素预算。
let area = width as usize * height as usize;
// Offscreen targets have a hard per-surface resource bound.
if area > 4_194_304
@@ -456,12 +478,14 @@ fn render_aspect(
{
return Err("invalid 3D surface or resource budget exceeded");
}
// 先申请两份工作量再分配缓冲,深度初始化正无穷,首个有效面可写入。
crate::software_renderer::reserve_pixels(area.saturating_mul(2))?;
let mut pixels = vec![rgb(view.scene.background); area];
let mut depths = vec![f32::INFINITY; area];
let camera = view.camera;
let basis = camera.basis().unwrap();
let perspective = matches!(camera.projection, Projection::Perspective { .. });
// 点已经经过视锥裁剪,才做透视除法;屏幕 y 向下,保留相机 z 用于后续深度/UV 校正。
let project = |point: Vec3| {
let half = match camera.projection {
Projection::Perspective { fov } => point.z * (fov.to_radians() / 2.).tan(),
@@ -484,12 +508,14 @@ fn render_aspect(
// 宽阶段只筛选候选:离屏网格不进入后续纹理分配和逐三角形处理。
for instance in index.visible(camera, aspect) {
let mesh = &view.scene.meshes[instance];
// 只为宽阶段可见的面板生成普通 UI 纹理;同一 mesh 的所有三角形复用本次纹理。
let texture = mesh.panel.as_ref().map(panel::texture).transpose()?;
for indices in &mesh.geometry.triangles {
let [a, b, c] = indices.map(|i| mesh.world.point(mesh.geometry.vertices[i as usize]));
let Some(normal) = (b - a).cross(c - a).normalized() else {
continue;
};
// 每三角形使用平面法线做 Lambert 漫反射,环境光为基础,方向光逐 RGB 累加;背光点积钳零。
let mut light = [view.scene.ambient; 3];
for source in &view.scene.lights {
let intensity = normal.dot(source.direction * -1.).max(0.) * source.intensity;
@@ -497,6 +523,7 @@ fn render_aspect(
*channel += intensity * color;
}
}
// 材质色乘累计光照后转 RGB,通道最终钳制;UI 面板纹理分支直接采纹理,不再乘这份网格光照。
let color = rgb(std::array::from_fn(|i| mesh.color[i] * light[i]));
// 在透视除法之前裁剪,并插入具有正确 UV 的交点;不能先投影再裁剪近面。
let polygon = clip(
@@ -506,6 +533,7 @@ fn render_aspect(
basis,
mesh.world.point(mesh.geometry.vertices[index as usize]),
),
// 没有 UV 的顶点用 [0,0];普通无纹理网格不依赖它,带纹理面板由构造器提供四角 UV。
uv: mesh
.geometry
.uv
@@ -528,6 +556,7 @@ fn render_aspect(
let max_x = a.x.max(b.x).max(c.x).ceil().min(width as f32) as u32;
let min_y = a.y.min(b.y).min(c.y).floor().max(0.) as u32;
let max_y = a.y.max(b.y).max(c.y).ceil().min(height as f32) as u32;
// 按屏幕包围矩形面积计工作,而非仅成功写像素数;大量重叠/细长三角形也不能绕过循环预算。
work += max_x.saturating_sub(min_x) as usize * max_y.saturating_sub(min_y) as usize;
if work > 32_000_000 {
return Err("3D raster work budget exceeded");
@@ -535,6 +564,7 @@ fn render_aspect(
let edge = |a: Vec3, b: Vec3, x: f32, y: f32| {
(x - a.x) * (b.y - a.y) - (y - a.y) * (b.x - a.x)
};
// 有向面积允许任意顶点绕序,除相同 area 得到一致重心权重;近零面积跳过,不做背面剔除。
let area = edge(a, b, c.x, c.y);
if area.abs() < 1e-6 {
continue;
@@ -543,6 +573,7 @@ fn render_aspect(
for x in min_x..max_x {
let px = x as f32 + 0.5;
let py = y as f32 + 0.5;
// 在像素中心求三个屏幕重心权重,负值容忍 1e-5 舍入误差,明显在外则不做深度和纹理计算。
let weights = [
edge(b, c, px, py) / area,
edge(c, a, px, py) / area,
@@ -576,6 +607,7 @@ fn render_aspect(
+ weights[2] * vertices[2].uv[axis]
}
};
// 透视校正 UV 后做最近邻采样,钳到 [0,1] 并限制到最后一个像素,避免 UV=1 恰好越界。
let u = (interpolated(0).clamp(0., 1.) * panel.width as f32)
.min((panel.width - 1) as f32)
as usize;
@@ -599,6 +631,7 @@ fn render_aspect(
mod tests {
use super::*;
#[test]
/// 构造99个远离视锥的网格,宽阶段只保留正中实例;有/无预存BVH的精确拾取身份与距离必须一致。
fn spatial_index_culls_offscreen_meshes_and_preserves_ray_pick() {
let mut view = view(Geometry::cuboid(1., 1., 1.));
let scene = Arc::make_mut(&mut view.scene);
@@ -614,6 +647,7 @@ mod tests {
scene.meshes.push(far);
}
scene.acceleration = Arc::new(spatial::Index::build(&scene.meshes));
// 远处实例应被宽阶段剔除;随后比较带缓存与临时重建索引的精确拾取身份/距离,防止加速改变结果。
assert_eq!(scene.acceleration.visible(view.camera, 1.), vec![0]);
let ray = view.camera.ray(0.5, 0.5, 1.).unwrap();
assert_eq!(scene.acceleration.ray(ray).len(), 1);
@@ -624,6 +658,7 @@ mod tests {
assert_eq!(indexed.identity, fallback.identity);
assert_eq!(indexed.distance, fallback.distance);
}
/// 构造测试最小视图:默认相机、原点红网格、纯环境光与白背景,不依赖业务VM或外部光源。
fn view(geometry: Geometry) -> View {
View {
camera: Camera::default(),
@@ -643,6 +678,7 @@ mod tests {
}
}
#[test]
/// 跨越近裁剪面的三角形仍应产生像素,射线命中受同一 near/far 约束;缩短远面后命中消失。
fn triangles_crossing_near_plane_are_clipped_and_pick_uses_the_same_range() {
let mut view = view(Geometry {
uv: vec![],
@@ -658,6 +694,7 @@ mod tests {
view.camera.near = 1.;
view.camera.far = 10.;
view.camera.projection = Projection::Perspective { fov: 90. };
// 三角形跨近面仍应产生可见红像素,拾取也必须尊重相同 near/far;缩短 far 后命中消失。
let pixels = render(&view, 64, 64).unwrap();
assert!(pixels.contains(&0xFF0000));
let hit = view.pick(0.5, 0.5, 1.).unwrap();
@@ -666,6 +703,7 @@ mod tests {
assert!(view.pick(0.5, 0.5, 1.).is_none());
}
#[test]
/// 验证局部TRS先于父变换作用于点;正交投影不同水平采样的射线方向相同但原点按可见宽度平移。
fn group_transform_order_and_orthographic_rays_are_consistent() {
let local = Matrix::trs(
Vec3::new(1., 0., 0.),
@@ -689,10 +727,12 @@ mod tests {
assert_eq!(right.origin.x - left.origin.x, 2.);
}
#[test]
/// 同一不可变视图/尺寸/aspect复用像素Arc;改变aspect重绘,超像素预算或退化相机必须拒绝。
fn surface_cache_reuses_immutable_frames_and_rejects_invalid_resources() {
let view = Arc::new(view(Geometry::cuboid(1., 1., 1.)));
let first = surface(&view, 64, 64, 1.).unwrap();
let second = surface(&view, 64, 64, 1.).unwrap();
// 同一不可变视图/尺寸/aspect 返回同像素 Arc;仅改变 aspect 即使像素尺寸不变也必须重绘。
assert!(Arc::ptr_eq(&first, &second));
let wide = surface(&view, 64, 64, 2.).unwrap();
assert!(!Arc::ptr_eq(&first, &wide));
+26 -4
View File
@@ -5,14 +5,14 @@ use serde::{Deserialize, Serialize};
use std::ops::{Add, Mul, Sub};
#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
/// 三个有限浮点分量的数学向量,不是托管 Vec3 对象。
/// 三维数学向量;构造不校验分量,需在输入边界显式调用 valid,不是托管 Vec3 对象。
pub struct Vec3 {
pub x: f32,
pub y: f32,
pub z: f32,
}
impl Vec3 {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 直接保存三个分量,不隐式归一化或拒绝非有限值。
pub const fn new(x: f32, y: f32, z: f32) -> Self {
Self { x, y, z }
}
@@ -34,11 +34,13 @@ impl Vec3 {
}
/// 仅在长度有效且不退化时返回单位向量,避免除零产生非有限结果。
pub fn normalized(self) -> Option<Self> {
// 先求模长,拒绝非有限值和长度不大于 1e-6 的向量;返回 None 让相机/法线调用方停止退化计算。
let length = self.length();
(length.is_finite() && length > 1e-6).then(|| self * (1.0 / length))
}
/// 检查数值、几何和资源条件是否满足本类型约束,供上层拒绝非法输入。
/// 要求三维向量各分量有限、绝对值不超过一百万;构造和算术运算不会自动调用此检查。
pub fn valid(self) -> bool {
// 构造函数与算术运算不会自动验证;此入口显式要求每个分量有限且绝对值至多一百万。
[self.x, self.y, self.z]
.iter()
.all(|v| v.is_finite() && v.abs() <= 1_000_000.0)
@@ -80,12 +82,15 @@ impl Default for Matrix {
impl Matrix {
/// 求仿射世界矩阵的逆;退化或不可逆时返回空值。
pub fn inverse(self) -> Option<Self> {
// 这里按仿射矩阵处理:最后一行假设为 [0,0,0,1],只逆左上 3×3,不实现一般透视矩阵求逆。
let m = self.0;
let determinant = m[0] * (m[5] * m[10] - m[6] * m[9]) - m[1] * (m[4] * m[10] - m[6] * m[8])
+ m[2] * (m[4] * m[9] - m[5] * m[8]);
// 接近零行列式意味着某方向被压扁或数值不稳定;不能继续除以 determinant。
if !determinant.is_finite() || determinant.abs() < 1e-9 {
return None;
}
// 用伴随矩阵除行列式得到线性部分逆矩阵;先把逆平移留为零。
let d = 1. / determinant;
let mut out = Self([
(m[5] * m[10] - m[6] * m[9]) * d,
@@ -105,6 +110,7 @@ impl Matrix {
0.,
1.,
]);
// 仿射逆平移为 -A⁻¹t。此时 out 平移为零,所以 point 只应用刚求得的线性逆变换。
let translation = out.point(Vec3::new(m[3], m[7], m[11])) * -1.;
out.0[3] = translation.x;
out.0[7] = translation.y;
@@ -113,6 +119,7 @@ impl Matrix {
}
/// 组合父子仿射变换,调用顺序决定局部坐标最终落在哪个世界位置。
pub fn compose(self, local: Self) -> Self {
// 行主序存储,点视作列向量;self.compose(local) = self × local,即先应用 local 再应用 self。
let mut out = [0.; 16];
for row in 0..4 {
for col in 0..4 {
@@ -133,6 +140,7 @@ impl Matrix {
}
/// 由平移、角度旋转和缩放构造局部仿射矩阵。
pub fn trs(position: Vec3, rotation: Vec3, scale: Vec3) -> Self {
// 输入欧拉角单位为度,先转换为弧度。组合为 T × Rz × Ry × Rx × S,列分别乘对应缩放轴。
let (sx, cx) = rotation.x.to_radians().sin_cos();
let (sy, cy) = rotation.y.to_radians().sin_cos();
let (sz, cz) = rotation.z.to_radians().sin_cos();
@@ -161,7 +169,9 @@ impl Matrix {
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
/// 投影策略:透视视场角或正交可见高度。
pub enum Projection {
// fov 表示垂直视场角(度),水平范围再乘视口宽高比。
Perspective { fov: f32 },
// height 是相机空间可见总高度,与深度无关;宽度为 height × aspect。
Orthographic { height: f32 },
}
@@ -198,13 +208,16 @@ pub struct Basis {
impl Camera {
/// 从观察位置、目标和上方向建立正交相机基;方向退化时拒绝。
pub fn basis(self) -> Option<Basis> {
// forward 指向观察目标;up 输入只提供大致上方向,叉积后重新正交化。
// 位置等于目标、up 为零或与前向平行时,normalized 返回 None。
let forward = (self.target - self.position).normalized()?;
let right = forward.cross(self.up).normalized()?;
let up = right.cross(forward).normalized()?;
Some(Basis { right, up, forward })
}
/// 检查数值、几何和资源条件是否满足本类型约束,供上层拒绝非法输入。
/// 验证相机向量/观察基、裁剪面次序和投影参数;退化方向、非法视场角或正交高度均返回 false。
pub fn valid(self) -> bool {
// 除了向量范围,还要求有效观察基、0 < near < far,以及合法视场角或正交高度。
self.position.valid()
&& self.target.valid()
&& self.up.valid()
@@ -223,15 +236,19 @@ impl Camera {
}
/// 把世界点投影到相机的右/上/前基向量坐标。
pub fn view(self, basis: Basis, p: Vec3) -> Vec3 {
// 先把世界点相对化,再点乘正交基;这里前方 z 为正,与某些图形 API 的负 z 约定不同。
let p = p - self.position;
Vec3::new(p.dot(basis.right), p.dot(basis.up), p.dot(basis.forward))
}
/// 从视口归一化坐标生成透视或正交射线;宽高比由具体视口提供。
pub fn ray(self, u: f32, v: f32, aspect: f32) -> Option<Ray> {
let basis = self.basis()?;
// u/v 通常是视口内 [0,1],映射到 [-1,1] 并翻转屏幕 y。
// 此函数不钳制输入,捕获拖动可以从视口外继续生成射线;aspect 由调用方保证有效。
let (x, y) = (u * 2. - 1., 1. - v * 2.);
match self.projection {
Projection::Perspective { fov } => {
// 透视射线共用相机原点,方向沿前向加上视平面偏移,最后归一化。
let half = (fov.to_radians() / 2.).tan();
Some(Ray {
origin: self.position,
@@ -241,6 +258,7 @@ impl Camera {
.normalized()?,
})
}
// 正交射线方向都为 forward,只改变起点在相机右/上平面中的位置。
Projection::Orthographic { height } => Some(Ray {
origin: self.position
+ basis.right * (x * height * aspect / 2.)
@@ -259,15 +277,18 @@ pub struct Ray {
impl Ray {
/// 求射线与三角形相交距离和重心坐标,拒绝退化三角形及射线起点后方的交点。
pub fn triangle(self, a: Vec3, b: Vec3, c: Vec3) -> Option<(f32, [f32; 3])> {
// Möller–Trumbore 求交:使用两条三角形边与叉积解重心系数,不先构造平面方程。
let ab = b - a;
let ac = c - a;
let p = self.direction.cross(ac);
let determinant = ab.dot(p);
// 近零表示射线与面平行或三角形退化;保留正负行列式,因此不做背面剔除。
if determinant.abs() < 1e-7 {
return None;
}
let inverse = 1.0 / determinant;
let t = self.origin - a;
// u 是顶点 b 的重心权重,必须位于 [0,1];v 是 c 的权重,a 的权重由 1-u-v 得到。
let u = t.dot(p) * inverse;
if !(0.0..=1.0).contains(&u) {
return None;
@@ -277,6 +298,7 @@ impl Ray {
if v < 0. || u + v > 1. {
return None;
}
// 返回的是射线参数 t,方向为单位向量时才等于世界距离;负值在射线起点后方,被拒绝。
let distance = ac.dot(q) * inverse;
(distance >= 0.).then_some((distance, [1. - u - v, u, v]))
}
+22
View File
@@ -17,17 +17,22 @@ use std::sync::Arc;
#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
/// 一次面板出现的正逆投影信息,可以链接父面板形成嵌套映射。
pub struct Mapping {
// 包含本面板的 3D 视口 Mount ID,与 key 一起区分同一业务场景的多次出现。
pub owner: u64,
// 面板在场景中的稳定标识,不能仅凭 Block 身份选择某个具体面板出现。
pub key: u64,
pub view: Arc<View>,
pub rect: [f32; 4],
// 外层二维相机变换;逆映射先处理它,再进入 3D 摄像机射线计算。
pub outer: Transform,
pub clip: Option<[f32; 4]>,
// 嵌套面板的外层链;反投影从父到子,正投影从子到父。
pub parent: Option<Arc<Mapping>>,
}
impl Mapping {
/// 沿父面板逆投影到当前平面的 UI 像素;要求可见时使用最近射线命中拒绝被遮挡的目标。
pub fn texture_point(&self, point: Point, clipped: bool) -> Option<Point> {
// 先把最外层窗口坐标逐层反投影为父面板像素,再检查当前面板所属空间的裁剪。
let point = if let Some(parent) = &self.parent {
parent.texture_point(point, clipped)?
} else {
@@ -45,6 +50,7 @@ impl Mapping {
if width <= 0. || height <= 0. {
return None;
}
// rect 是 3D 视口在当前二维空间的位置,归一化坐标传给该视口相机;不是面板纹理坐标。
let (u, v) = ((point.x - x) / width, (point.y - y) / height);
let mesh = self.view.scene.meshes.iter().find(|mesh| {
mesh.panel
@@ -68,18 +74,22 @@ impl Mapping {
let center = mesh.world.point(Vec3::default());
let normal = (mesh.world.point(Vec3::new(1., 0., 0.)) - center)
.cross(mesh.world.point(Vec3::new(0., 1., 0.)) - center);
// 用世界变换后的局部 x/y 轴叉积求平面法线,支持旋转和非均匀缩放;平行射线无交点。
let denominator = normal.dot(ray.direction);
if denominator.abs() < 1e-7 {
return None;
}
// 解射线与无限平面交点,拒绝非有限及相机后方结果;clipped=false 时允许点落在面板边界外。
let distance = (center - ray.origin).dot(normal) / denominator;
if !distance.is_finite() || distance <= 0. {
return None;
}
// 把世界交点乘逆 world 回到面板局部坐标,逆矩阵退化时拒绝。
let local = mesh
.world
.inverse()?
.point(ray.origin + ray.direction * distance);
// 面板网格约定以局部原点为中心;x 向右、y 向上,转换为纹理左上原点、y 向下。
let world_width = mesh.geometry.vertices[1].x - mesh.geometry.vertices[0].x;
let world_height = mesh.geometry.vertices[0].y - mesh.geometry.vertices[2].y;
let point = Point::new(
@@ -99,6 +109,7 @@ impl Mapping {
let panel = mesh.panel.as_ref()?;
let width = mesh.geometry.vertices[1].x - mesh.geometry.vertices[0].x;
let height = mesh.geometry.vertices[0].y - mesh.geometry.vertices[2].y;
// 正向路径与 texture_point 对称:纹理像素先转局部平面点,再进入世界空间。
let world = mesh.world.point(Vec3::new(
(point.x / panel.width as f32 - 0.5) * width,
(0.5 - point.y / panel.height as f32) * height,
@@ -106,10 +117,12 @@ impl Mapping {
));
let camera = self.view.camera;
let local = camera.view(camera.basis()?, world);
// 点在近远面之外时无可用投影;此方法仅算位置,不检查前方遮挡或二维 clip。
if local.z <= camera.near || local.z >= camera.far {
return None;
}
let [x, y, w, h] = self.rect;
// 透视半高随相机深度增长,正交半高恒定;横向除数还包含视口宽高比。
let half = match camera.projection {
Projection::Perspective { fov } => local.z * (fov.to_radians() / 2.).tan(),
Projection::Orthographic { height } => height / 2.,
@@ -118,6 +131,7 @@ impl Mapping {
x + (local.x / (half * w / h) + 1.) * w / 2.,
y + (1. - local.y / half) * h / 2.,
));
// 当前投影得到的是父面板纹理空间;继续向外层正投影,直到窗口页面坐标。
if let Some(parent) = &self.parent {
parent.project_point(point)
} else {
@@ -142,6 +156,7 @@ pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
use crate::document::RenderCommand;
use std::collections::{HashMap, HashSet};
let mounts: HashMap<_, _> = frame.mounts.iter().map(|mount| (mount.id, mount)).collect();
// 分组键包含视口 owner 和面板 key,防止同一场景在两个视口出现时互相混入绘制命令。
let mut groups = HashMap::<(u64, u64), Vec<Entry>>::new();
let mut roots = Vec::new();
// 每条命令都有出现归属;据此分流为窗口根命令或某个世界面板的内部命令。
@@ -163,6 +178,7 @@ pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
roots.push(entry);
}
}
// 面板内焦点框也必须作为纹理内容绘制,不能留在窗口根层,否则会脱离世界面板位置。
if let Some(mount) = frame.focus.and_then(|id| mounts.get(&id))
&& let Some(panel) = &mount.panel
{
@@ -195,6 +211,7 @@ pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
if let RenderCommand::Scene3D { view, .. } = &mut entry.command
&& view.scene.meshes.iter().any(|mesh| mesh.panel.is_some())
{
// 只有含面板的 Scene3D 命令才递归装配;path 跟踪当前祖先出现,限制深度小于 8 并拒绝环。
anyhow::ensure!(
depth < 8 && path.insert(entry.owner),
"3D UI paint nesting cycle or depth budget exceeded"
@@ -208,6 +225,7 @@ pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
clips: Vec::new(),
views: Vec::new(),
};
// 按照原命令顺序递归装配面板内容;嵌套 3D 子命令先完成,父面板才取得完整表面。
for child in groups.get(&(entry.owner, panel.key)).into_iter().flatten() {
let child = assemble(child.clone(), groups, path, depth + 1)?;
surface.commands.push(child.command);
@@ -221,11 +239,13 @@ pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
scene: Arc::new(scene),
camera: view.camera,
});
// 退出当前分支时撤销祖先标记,允许同一身份在其他独立分支中出现而不误判成环。
path.remove(&entry.owner);
}
Ok(entry)
}
let mut path = HashSet::new();
// 面板内部命令已经移入 UiSurface,根帧只保留外层命令;四张平行元数据表同步重建。
frame.commands.clear();
frame.command_clips.clear();
frame.command_views.clear();
@@ -242,10 +262,12 @@ pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
/// 为一个面板分配有限像素表面,并调用普通 UI 软件渲染;当前实现不会按面板内容独立缓存纹理。
pub fn texture(panel: &super::Panel) -> Result<Vec<u32>, &'static str> {
// 先向统一像素预算申请有限纹理面积,再分配背景缓冲;嵌套面板同样受该预算约束。
crate::software_renderer::reserve_pixels(panel.width as usize * panel.height as usize)?;
let mut pixels =
vec![super::rgb(panel.background); panel.width as usize * panel.height as usize];
if let Some(surface) = &panel.surface {
// 将普通 UI 表面包装为临时文档复用现有显示列表和软件渲染路径;比例 1 对应纹理像素。
let document = crate::document::RenderDocument {
frame: crate::document::Frame {
background: format!("#{:06X}", super::rgb(panel.background)),
+17 -2
View File
@@ -21,6 +21,7 @@ impl Bounds {
.vertices
.iter()
.map(|point| mesh.world.point(*point));
// 空网格没有包围盒,返回 None 后不会进入树;首顶点初始化上下界,避免把原点误算进边界。
let first = points.next()?;
Some(points.fold(
Self {
@@ -64,6 +65,7 @@ impl Bounds {
}
/// 用包围盒筛出射线候选;索引查询按进入距离排序,精确三角形求交在调用方完成。
fn ray(self, ray: Ray) -> Option<f32> {
// slab 算法逐轴交区间;near 从零开始,只保留射线前方,起点在盒内时返回零。
let mut near = 0f32;
let mut far = f32::INFINITY;
for (origin, direction, min, max) in [
@@ -71,6 +73,7 @@ impl Bounds {
(ray.origin.y, ray.direction.y, self.min.y, self.max.y),
(ray.origin.z, ray.direction.z, self.min.z, self.max.z),
] {
// 近乎平行该轴时不做除法;起点在 slab 外即可拒绝,在 slab 内则该轴不收窄距离。
if direction.abs() < 1e-12 {
if origin < min || origin > max {
return None;
@@ -79,6 +82,7 @@ impl Bounds {
}
let a = (min - origin) / direction;
let b = (max - origin) / direction;
// 方向可为负,先排序该轴进入/退出距离,再与之前各轴区间求交。
near = near.max(a.min(b));
far = far.min(a.max(b));
if far < near {
@@ -87,8 +91,9 @@ impl Bounds {
}
Some(near)
}
/// 用相机六平面保守判断包围盒可见性,返回保持原场景顺序的候选。
/// 检查八角是否全落在任一视锥平面外侧;返回保守可见性,不代表真实三角形可见。
fn visible(self, camera: Camera, basis: Basis, planes: &[[f32; 4]; 6]) -> bool {
// 用三位索引枚举 AABB 八角,再转到相机空间,使角点与视锥平面处于同一坐标系。
let corners: [Vec3; 8] = std::array::from_fn(|index| {
camera.view(
basis,
@@ -111,6 +116,7 @@ impl Bounds {
),
)
});
// 只有某个平面外侧包含全部八角时才剔除;盒与视锥可能无真实相交也会保守保留。
!planes.iter().any(|[a, b, c, d]| {
corners
.iter()
@@ -148,8 +154,9 @@ pub struct Index {
root: Option<usize>,
}
impl Index {
/// 根据当前输入构造本模块的派生结果,具体的验证与资源边界见函数内步骤。
/// 用变换后的网格顶点建立世界 AABB 与 BVH;忽略空网格,树内仅保存原生几何下标。
pub fn build(meshes: &[Mesh]) -> Self {
// 保留与原网格下标等长的包围盒数组;items 仅收集非空网格,最终候选仍指向原场景下标。
let bounds: Vec<_> = meshes.iter().map(Bounds::mesh).collect();
let mut items: Vec<_> = bounds
.iter()
@@ -173,11 +180,13 @@ impl Index {
.map(|&index| self.bounds[index].unwrap())
.reduce(Bounds::union)
.unwrap();
// 先占位父节点,递归子树会扩展 nodes;返回后按稳定下标替换父占位,不保留可失效的引用。
let index = self.nodes.len();
self.nodes.push(Node::Leaf {
bounds,
items: Vec::new(),
});
// 至多四项成为叶;更大集合沿包围盒最长轴排序后二等分,控制树深而非按三角形拆分。
if items.len() <= 4 {
self.nodes[index] = Node::Leaf {
bounds,
@@ -198,6 +207,7 @@ impl Index {
.center(axis)
.total_cmp(&self.bounds[b].unwrap().center(axis))
});
// 两半均非空,即使所有中心重合也能递减集合规模,保证递归终止。
let mid = items.len() / 2;
let (left, right) = items.split_at_mut(mid);
let left = self.split(left);
@@ -211,11 +221,13 @@ impl Index {
index
}
/// 检查索引覆盖的网格数量是否与场景相符;缺失缓存时允许重建。
// 这里只校验数量,不验证顶点或 world 变换;调用方必须在几何改变后重建索引。
pub fn matches(&self, meshes: usize) -> bool {
self.bounds.len() == meshes
}
/// 用包围盒筛出射线候选;索引查询按进入距离排序,精确三角形求交在调用方完成。
pub fn ray(&self, ray: Ray) -> Vec<(f32, usize)> {
// 空树的栈为空;显式栈避免查询递归,先测分支包围盒,未命中时整棵子树跳过。
let mut stack: Vec<_> = self.root.into_iter().collect();
let mut output = Vec::new();
while let Some(index) = stack.pop() {
@@ -236,11 +248,13 @@ impl Index {
}
}
}
// 距离是盒进入距离而非三角形命中距离;同距按场景下标排序,精确拾取仍由调用方完成。
output.sort_unstable_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1)));
output
}
/// 用相机六平面保守判断包围盒可见性,返回保持原场景顺序的候选。
pub fn visible(&self, camera: Camera, aspect: f32) -> Vec<usize> {
// 相机无法建立有效正交基时没有可靠视锥,返回空候选,不继续使用无效投影。
let Some(basis) = camera.basis() else {
return Vec::new();
};
@@ -264,6 +278,7 @@ impl Index {
}
}
}
// BVH 遍历顺序与场景顺序不同;恢复原下标顺序以保持后续绘制及同深度处理稳定。
output.sort_unstable();
output
}
+29 -1
View File
@@ -54,6 +54,8 @@ impl Axis {
/// 求两个裁剪矩形的交集,空区域仍保持合法非负尺寸。
fn intersection(a: [f32; 4], b: [f32; 4]) -> [f32; 4] {
// 输入采用 [左, 上, 宽, 高]。交集左上取较大值,右下取较小值;
// 右/下边界再钳到左/上边界,保证完全错开时输出零面积而非负尺寸。
let x = a[0].max(b[0]);
let y = a[1].max(b[1]);
[
@@ -65,6 +67,8 @@ fn intersection(a: [f32; 4], b: [f32; 4]) -> [f32; 4] {
}
/// 沿出现树累计滚动偏移和裁剪;遇到独立场景视口时按其有限边界重新建立投影范围。
pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame) -> Result<()> {
// 第一阶段只建立查找表,不改坐标:Block ID 查语义节点,Mount ID 查帧中的出现。
// 同一个 Block 可以多次出现;滚动偏移后面按 Mount 读取,不能存入这个 Block 表。
let mut nodes = HashMap::new();
let mut work = vec![root];
while let Some(node) = work.pop() {
@@ -82,6 +86,8 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
.iter()
.map(|m| matches!(nodes[m.block_id.as_str()].kind, UiKind::Scroll { .. }))
.collect();
// extent 保存尚未滚动的内容右下边界。滚动容器先扣除自身右/下 inset,
// 后续传播子内容后再加回 padding,避免把空容器的内边距算成可滚动溢出。
let mut extent: Vec<_> = frame
.mounts
.iter()
@@ -95,6 +101,7 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
(m.x + m.width - inset.right, m.y + m.height - inset.bottom)
})
.collect();
// Mount 按父先子后排列,反向扫描才能先汇总子树,再将边界向父级传播。
for i in (0..frame.mounts.len()).rev() {
let m = &frame.mounts[i];
if let Some(parent) = m.parent {
@@ -103,8 +110,10 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
nodes[frame.mounts[parent].block_id.as_str()].kind,
UiKind::CanvasViewport { .. } | UiKind::Viewport3D { .. }
) {
// 场景世界内部的坐标范围不扩大外部有限布局盒子的滚动范围。
continue;
}
// 子滚动容器向外只贡献自己的视口;它内部的溢出由自己的偏移处理。
let e = if scrolling[i] {
(m.x + m.width, m.y + m.height)
} else {
@@ -114,6 +123,8 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
extent[parent].1 = extent[parent].1.max(e.1);
}
}
// 第二阶段从父到子投影。上下文保存祖先累计位移和裁剪,而非当前节点本身的偏移。
// 重建绘制命令及其平行元数据,保证显示、命中与裁剪使用同一套投影坐标。
let mut contexts = HashMap::<u64, (f32, f32, Option<[f32; 4]>)>::new();
frame.commands.clear();
frame.command_clips.clear();
@@ -130,6 +141,7 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
UiKind::Scroll { axis, .. } => axis,
_ => Axis::Both,
};
// limits 在未改写的布局坐标里计算;禁用轴直接设零,内容比视口小时也为零。
let limits = [
if axis.horizontal() {
(extent[i].0 + padding.right - m.x - m.width).max(0.0)
@@ -142,10 +154,12 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
0.0
},
];
// 当前容器跟随祖先滚动;它自己的 scroll_offset 只影响子节点,容器边框保持原位。
m.x -= dx;
m.y -= dy;
m.clip = clip;
let mut child = (dx, dy, clip);
// 普通裁剪使用边框内侧矩形,并与祖先裁剪求交,不能扩大祖先允许的区域。
if node.clip_children {
let border = node.border;
let viewport = [
@@ -167,11 +181,14 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
let owner = vm
.upgrade(*weak)?
.ok_or_else(|| anyhow::anyhow!("expired scroll Mount"))?;
// weak upgrade 临时保活 Mount。先保存 payload 读取结果再 release,
// 这样读取失败也会先释放强引用,然后由下方 offset? 传播错误。
let offset = vm
.payload::<Mount>(owner, "Mount")
.map(|mount| mount.scroll_offset);
vm.release(owner)?;
let offset = offset?;
// 内容缩短时旧偏移可能超界;此处只钳制帧投影,不改写托管 Mount 的原偏移。
let x = offset[0].clamp(0.0, limits[0]);
let y = offset[1].clamp(0.0, limits[1]);
m.scroll = Some([x, y, limits[0], limits[1]]);
@@ -187,6 +204,7 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
),
);
}
// 3D 子场景有独立投影空间,不能继续叠加外层二维滚动坐标和裁剪。
if matches!(node.kind, UiKind::Viewport3D { .. }) {
child = (0., 0., None);
}
@@ -218,6 +236,7 @@ pub fn coordinate(value: &Value) -> Result<f32, VmError> {
"scroll coordinates must be numbers",
));
};
// 通过 Number 文本表示转为 f32,再检查有限性及绝对值上限;允许负数以表达相对滚动。
let n = value
.to_string()
.parse::<f32>()
@@ -235,6 +254,7 @@ pub fn set(
point: [f32; 2],
relative: bool,
) -> Result<(), VmError> {
// 只允许已提交且仍挂接的出现接受滚动;布局过程中的临时 Mount 不具备稳定滚动边界。
let mut mount = cx.store().payload::<Mount>(owner, "Mount")?.clone();
if !mount.mounted || mount.layout.is_some() {
return Err(VmError::InvalidArgument(
@@ -257,7 +277,8 @@ pub fn set(
let desktop = cx
.upgrade(desktop)?
.ok_or(VmError::InvalidArgument("Mount window expired"))?;
// Check the normal mutation barrier even when the clamped result is equal.
// 即使钳制后数值未变,也走正常写屏障,使只读调用不能借助无效滚动绕过变更限制。
// scrollRequested 通知后续刷新重做投影,而不是在这里直接重建布局或绘制。
cx.replace_payload(owner, mount)?;
cx.set_attr(desktop, "scrollRequested", Value::Bool(true))
}
@@ -273,6 +294,7 @@ pub fn into_view(
"scrollIntoView requires committed attached Mount",
));
}
// rect 随祖先滚动调整,表示目标在当前投影中的可见需求;从最近父容器逐层向外处理。
let mut rect = [
mount.geometry.x,
mount.geometry.y,
@@ -286,6 +308,7 @@ pub fn into_view(
};
let mount = cx.store().payload::<Mount>(owner, "Mount")?.clone();
parent = mount.parent;
// 跨越独立场景边界时,外层只能滚动整个场景视口,不能使用内部世界坐标定位目标。
if mount.geometry.canvas_viewport || mount.geometry.scene3d_viewport {
rect = [
mount.geometry.x,
@@ -295,6 +318,7 @@ pub fn into_view(
];
}
if let Some(offset) = mount.geometry.scroll {
// 目标起点在视口前则向前对齐;否则只补足末端溢出,已完全可见时返回零。
let delta = |start: f32, length: f32, viewport: f32, size: f32| {
if start < viewport {
start - viewport
@@ -306,6 +330,7 @@ pub fn into_view(
let dy = delta(rect[1], rect[3], mount.geometry.y, mount.geometry.height);
let x = (offset[0] + dx).clamp(0.0, offset[2]);
let y = (offset[1] + dy).clamp(0.0, offset[3]);
// 下一层祖先看到的目标位置必须扣掉本层实际移动量,不能扣未钳制的请求量。
rect[0] -= x - offset[0];
rect[1] -= y - offset[1];
if x != offset[0] || y != offset[1] {
@@ -318,12 +343,15 @@ pub fn into_view(
/// 按逆出现顺序选择指针处可处理当前滚动方向的最内层容器。
pub fn wheel_target(frame: &Frame, point: Point, delta: [f32; 2]) -> Option<u64> {
let indices: HashMap<_, _> = frame.mounts.iter().map(|mount| (mount.id, mount)).collect();
// 逆序先取最上层命中的出现,再沿其祖先寻找能消费位移的滚动容器。
// 不搜索被覆盖的兄弟容器,内层到边界后才交给外层滚动。
let mut current = frame
.mounts
.iter()
.rev()
.find(|mount| mount.contains(point));
while let Some(mount) = current {
// 只有至少一轴钳制后真正改变偏移才接收此次输入;没有任何容器可移动则返回 None。
if mount.scroll.is_some_and(|s| {
(s[0] + delta[0]).clamp(0.0, s[2]) != s[0] || (s[1] + delta[1]).clamp(0.0, s[3]) != s[1]
}) {
+32 -3
View File
@@ -10,6 +10,7 @@ use crate::{
/// 显示列表的 CPU 执行入口,错误在原生 present 前向上传递。
pub struct SoftwareRenderer;
// 预算按渲染线程维护,递归 3D/面板渲染共用同一组计数;不同线程之间不共享额度。
thread_local! {
static RENDER_DEPTH:std::cell::Cell<usize>=const { std::cell::Cell::new(0) };
static PIXEL_UNITS:std::cell::Cell<usize>=const { std::cell::Cell::new(0) };
@@ -21,9 +22,11 @@ impl RenderScope {
pub fn enter() -> Result<Self, &'static str> {
RENDER_DEPTH.with(|depth| {
let current = depth.get();
// 拒绝第 19 层进入,不先增加深度;成功返回的 RenderScope 析构时才对应减一。
if current >= 18 {
return Err("render nesting budget exceeded");
}
// 只有最外层渲染开始才清累计像素数;递归进入不能借此重置预算。
if current == 0 {
PIXEL_UNITS.with(|pixels| pixels.set(0));
}
@@ -33,7 +36,7 @@ impl RenderScope {
}
}
impl Drop for RenderScope {
/// 在 Rust 所有者离开作用域时执行本类型的配套清理;不能用它代替需要报告错误的显式关闭。
/// 退出一次像素渲染作用域时归还嵌套深度;像素工作量仍按本帧累计,不因退出内层而返还。
fn drop(&mut self) {
RENDER_DEPTH.with(|depth| depth.set(depth.get() - 1));
}
@@ -41,6 +44,7 @@ impl Drop for RenderScope {
/// 累加本帧中间表面工作量,超过预算立即返回错误。
pub(crate) fn reserve_pixels(units: usize) -> Result<(), &'static str> {
PIXEL_UNITS.with(|pixels| {
// 累计申请工作量而非当前存活像素;释放一个中间表面不会返还额度,饱和加法避免溢出绕过限制。
let next = pixels.get().saturating_add(units);
if next > 16_777_216 {
return Err("nested render pixel budget exceeded");
@@ -58,6 +62,7 @@ impl SoftwareRenderer {
width: u32,
height: u32,
) -> Result<(), &'static str> {
// RAII 保护让成功、提前返回和错误传播都恢复深度;target 长度须由调用方保证至少 width×height。
let _scope = RenderScope::enter()?;
let mut canvas = Canvas {
pixels: target,
@@ -80,6 +85,7 @@ impl SoftwareRenderer {
canvas.draw_image(image, *origin, *rect, *angle, *opacity, *tint);
}
DrawCommand::Scene3D { rect, view } => {
// 先将 3D 矩形与当前裁剪和目标尺寸相交;完全不可见时连中间表面都不生成。
let left = rect.x.max(canvas.clip.x).max(0.).floor() as u32;
let top = rect.y.max(canvas.clip.y).max(0.).floor() as u32;
let right = (rect.x + rect.width)
@@ -95,24 +101,28 @@ impl SoftwareRenderer {
if left >= right || top >= bottom || rect.width <= 0. || rect.height <= 0. {
continue;
}
// 3D 中间表面的最长边限制到约 2048 像素,再采样到请求尺寸;相机宽高比仍用原 rect,避免改变透视比例。
let lod = (2048. / rect.width.max(rect.height)).min(1.);
let w = (rect.width * lod).ceil().max(1.) as u32;
let h = (rect.height * lod).ceil().max(1.) as u32;
let surface = crate::scene3d::surface(view, w, h, rect.width / rect.height)?;
for y in top..bottom {
for x in left..right {
// 按目标像素中心反算纹理坐标并钳到有效表面边界;只复制可见区域,不循环整个放大矩形。
let u = (((x as f32 + 0.5 - rect.x) / rect.width) * w as f32)
.clamp(0., (w - 1) as f32)
as u32;
let v = (((y as f32 + 0.5 - rect.y) / rect.height) * h as f32)
.clamp(0., (h - 1) as f32)
as u32;
// 3D 表面是最终 RGB 像素,直接覆盖目标;不走二维 source alpha 混合。
canvas.pixels[y as usize * width as usize + x as usize] =
surface[v as usize * w as usize + u as usize];
}
}
}
DrawCommand::PushClip(rect) => {
// 先保存旧裁剪,再求交;嵌套 PushClip 只能收窄,矩形分离时宽高归零。
clips.push(canvas.clip);
let x = canvas.clip.x.max(rect.x);
let y = canvas.clip.y.max(rect.y);
@@ -130,6 +140,7 @@ impl SoftwareRenderer {
);
}
DrawCommand::PopClip => {
// 多余 PopClip 在当前实现中被忽略;合法列表仍应由生成层保证配对。
if let Some(clip) = clips.pop() {
canvas.clip = clip;
}
@@ -164,7 +175,7 @@ impl SoftwareRenderer {
}
}
/// 借用目标像素切片并维护当前裁剪,所有像素写入都受该上下文限制。
/// 借用目标像素切片并维护当前裁剪;图形/文字受裁剪,Clear 明确填满整个目标。
struct Canvas<'a> {
pixels: &'a mut [u32],
width: u32,
@@ -225,14 +236,16 @@ impl Canvas<'_> {
}
}
/// 清空本对象维护的当前内容或缓存,后续状态由调用方重新建立。
/// 用不透明 RGB 填满目标切片;此命令忽略当前裁剪和输入颜色 alpha。
fn clear(&mut self, color: Color) {
// Clear 填整个提供的目标切片,不受当前 clip 约束;pack 忽略 alpha,清屏色作为不透明 RGB。
self.pixels.fill(pack(color));
}
/// 只遍历裁剪后的矩形像素,按圆角覆盖决定填充区域。
fn fill_rounded_rect(&mut self, rect: Rect, radius: f32, color: Color) {
let bounds = self.clamped_bounds(rect);
// 半径钳到非负且不超过半宽/半高;后续用像素中心判定圆角内外,不做边缘面积覆盖积分。
let radius = radius.max(0.0).min(rect.width / 2.0).min(rect.height / 2.0);
for y in bounds.1..bounds.3 {
for x in bounds.0..bounds.2 {
@@ -246,6 +259,7 @@ impl Canvas<'_> {
/// 用外轮廓与内轮廓的差绘制边框,避免把边框当成整个矩形填充。
fn stroke_rounded_rect(&mut self, rect: Rect, radius: f32, width: f32, color: Color) {
let bounds = self.clamped_bounds(rect);
// 描边请求先至少一单位再限制为半宽/半高;inner 从四边缩入,最终绘制外轮廓减内轮廓。
let width = width.max(1.0).min(rect.width / 2.0).min(rect.height / 2.0);
let outer_radius = radius.max(0.0).min(rect.width / 2.0).min(rect.height / 2.0);
let inner = Rect::new(
@@ -271,6 +285,7 @@ impl Canvas<'_> {
/// 把文字原点转换为局部裁剪区域,交给有界字形绘制,再混合到目标缓冲。
fn draw_text(&mut self, origin: Point, value: &str, style: TextStyle, color: Color) {
// 将文字原点对齐整数像素;转换 clip 到字形局部空间,回调再加原点写回目标。
let x = origin.x.round() as i32;
let y = origin.y.round() as i32;
let clip = Rect::new(
@@ -289,6 +304,7 @@ impl Canvas<'_> {
if rect.width <= 0.0 || rect.height <= 0.0 {
return;
}
// 段落文本临时收窄 clip 到文本框;下方调用完成后恢复 old,后续命令不能继承段落私有裁剪。
let old = self.clip;
let x = old.x.max(rect.x);
let y = old.y.max(rect.y);
@@ -310,6 +326,7 @@ impl Canvas<'_> {
value,
style,
color,
// 换行按完整段落宽度排版,而不是按被祖先裁剪后剩余的可见宽度重新排版。
Some(rect.width),
clip,
|dx, dy, pixel| self.blend_pixel(left + dx, top + dy, pixel),
@@ -319,6 +336,7 @@ impl Canvas<'_> {
/// 把连续矩形转换成目标缓冲内的整数像素范围,避免在不可见区域进行光栅循环。
fn clamped_bounds(&self, rect: Rect) -> (i32, i32, i32, i32) {
// 左/上 floor,右/下 ceil 形成保守循环范围;blend_pixel 还会按当前 clip 检查实际整数像素。
(
rect.x.max(self.clip.x).max(0.0).floor() as i32,
rect.y.max(self.clip.y).max(0.0).floor() as i32,
@@ -335,6 +353,7 @@ impl Canvas<'_> {
/// 在画布与当前裁剪范围内进行透明度混合,防止文字/图形写出目标缓冲。
fn blend_pixel(&mut self, x: i32, y: i32, source: Color) {
// 拒绝画布外、裁剪外与全透明像素;只有通过后才计算线性下标,避免负坐标转 usize。
if x < 0
|| y < 0
|| x >= self.width as i32
@@ -349,6 +368,7 @@ impl Canvas<'_> {
}
let index = y as usize * self.width as usize + x as usize;
// 全不透明像素可直接打包覆盖,省去目的通道解码与乘除法。
if source.alpha == 255 {
self.pixels[index] = pack(source);
return;
@@ -358,6 +378,7 @@ impl Canvas<'_> {
let dst_red = (destination >> 16) & 0xff;
let dst_green = (destination >> 8) & 0xff;
let dst_blue = destination & 0xff;
// 非预乘源颜色按 source*alpha + destination*(1-alpha) 合成,目标不存 alpha,逐通道整除 255。
let alpha = source.alpha as u32;
let inverse = 255 - alpha;
let red = (source.red as u32 * alpha + dst_red * inverse) / 255;
@@ -379,6 +400,8 @@ fn rounded_rect_contains(rect: Rect, radius: f32, x: f32, y: f32) -> bool {
// Clamp in local coordinates: adding a large origin to a shrinking tab's
// half-width can otherwise round the lower bound above the upper bound.
let radius = radius.min(rect.width / 2.0).min(rect.height / 2.0);
// 在局部坐标钳到圆角中心可达矩形,距离向量对应最近角圆心;中心带距离为零。
// 先减大原点可降低浮点舍入导致 clamp 上下界反转的风险。
let local_x = x - rect.x;
let local_y = y - rect.y;
let dx = local_x - local_x.clamp(radius, rect.width - radius);
@@ -388,6 +411,7 @@ fn rounded_rect_contains(rect: Rect, radius: f32, x: f32, y: f32) -> bool {
/// 将颜色通道打包成目标缓冲的整数像素表示。
fn pack(color: Color) -> u32 {
// 像素格式为 0x00RRGGBB,高字节不存透明度;透明度已在混合阶段折算进 RGB。
(color.red as u32) << 16 | (color.green as u32) << 8 | color.blue as u32
}
@@ -396,6 +420,7 @@ mod tests {
use super::*;
#[test]
/// 画长文字进入嵌套裁剪,逐像素检查多行与裁剪交集;PopClip后的蓝矩形验证后续命令不沿用旧clip。
fn wrapped_text_uses_multiple_lines_respects_nested_clips_and_restores_the_clip() {
let mut list = DisplayList::default();
list.push(DrawCommand::Clear(Color::rgb(255, 255, 255)));
@@ -420,6 +445,7 @@ mod tests {
});
let mut pixels = vec![0; 80 * 60];
SoftwareRenderer::render(&list, &mut pixels, 80, 60).unwrap();
// 确认文字确实换成多行且每个非背景文字像素都落在嵌套裁剪交集内,蓝色矩形验证裁剪已恢复。
let mut second_line = false;
for y in 0..60 {
for x in 0..80 {
@@ -435,6 +461,7 @@ mod tests {
}
#[test]
/// 在黑底4x4缓冲画2x2红矩形,核对内部像素变红、外部仍黑,覆盖最小坐标/打包路径。
fn renderer_changes_pixels_inside_a_rectangle() {
let mut list = DisplayList::default();
list.push(DrawCommand::Clear(Color::rgb(0, 0, 0)));
@@ -450,6 +477,7 @@ mod tests {
}
#[test]
/// 半透明白字叠黑底必须含中间抗锯齿值且通道不超128;alpha=0的文字完全不改像素。
fn text_edges_are_antialiased_and_respect_opacity() {
let mut list = DisplayList::default();
list.push(DrawCommand::Clear(Color::rgb(0, 0, 0)));
@@ -462,6 +490,7 @@ mod tests {
let mut pixels = vec![0; 256 * 48];
SoftwareRenderer::render(&list, &mut pixels, 256, 48).unwrap();
assert!(pixels.iter().any(|pixel| *pixel > 0));
// 白字 alpha=128 叠黑底,任何通道都不应超过 128;中间覆盖值证明字形边缘仍有抗锯齿。
assert!(pixels.iter().all(|pixel| (pixel & 255) <= 128));
assert!(pixels.iter().any(|pixel| (1..128).contains(&(pixel & 255))));
+27 -7
View File
@@ -13,13 +13,14 @@ use endor_core::{
/// 验证 hitTest 返回的是 Bool,避免把任意真值隐式当成命中。
struct Boolean;
impl NativeCallable for Boolean {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 接收 hitTest 返回的唯一值,交给 invoke 严格检查 Bool。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(1))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 只接受真正的 Bool 并原样返回;数字或对象不能以宿主真值规则替代源协议契约。
fn invoke(&self, _: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
// 协议要求明确 Bool;拒绝数字、对象等“真值”,使用户实现错误立即暴露。
let [Value::Bool(value)] = args else {
return Err(VmError::InvalidArgument("hitTest must return Bool"));
};
@@ -30,13 +31,14 @@ impl NativeCallable for Boolean {
/// 比较按下与释放的选择结果,只有同一目标才能继续点击分发。
struct SameTarget;
impl NativeCallable for SameTarget {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 接收按下与释放两次命中选择的结果。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(2))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 仅当两结果为同一 Mount 对象才返回目标,否则返回 Nil;共享 Block 的不同出现位置也不能合成点击。
fn invoke(&self, _: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
// 比较的是实际出现 Mount 的身份;即使共享同一个 Block,不同出现之间拖动也不构成点击。
let value = match args {
[Value::Object(first), Value::Object(second)] if first == second => {
Value::Object(*first)
@@ -53,6 +55,7 @@ fn code(
constants: Vec<Value>,
layout: CodeLayout,
) -> Result<ObjectRef, VmError> {
// 校验并编码指令,同时设置诊断位置;独立空 globals 避免驱动依赖业务全局命名空间。
let code = EndorCode::from_instructions(&instructions, constants, layout)?.with_location(
"<pointer hitTest>",
"<tessera>",
@@ -76,11 +79,13 @@ fn selector(
))?;
let mut instructions = Vec::new();
let mut constants = vec![Value::Object(validate)];
// 候选按绘制顺序提供,逆序使最上层先参与测试;弱引用失效视为过期输入错误。
for weak in candidates.iter().rev() {
let mount = cx
.upgrade(*weak)?
.ok_or(VmError::InvalidArgument("pointer Mount expired"))?;
let target = cx.store().payload::<Mount>(mount, "Mount")?.clone();
// 先排除已卸载、非交互和几何不命中的出现,避免为明显无效候选构造源调用。
if !target.mounted
|| !target.geometry.interactive
|| !target
@@ -91,14 +96,17 @@ fn selector(
}
let geometry = &target.geometry;
let point = crate::geometry::Point::new(point[0], point[1]);
// 把投影坐标反算到节点逻辑空间;不可逆/无效投影没有可用于 hitTest 的局部坐标。
let Some(point) = geometry.logical_point(point) else {
continue;
};
// 源 Point 以节点左上为原点;这里再次验证范围,避免变换后的点落到节点盒子之外。
let x = point.x - geometry.x;
let y = point.y - geometry.y;
if x < 0.0 || y < 0.0 || x > geometry.width || y > geometry.height {
continue;
}
// 依据真实 Block 的名义类型解析 hitTest,不用原生矩形命中替代源协议。
let definition = cx
.store()
.type_of(target.block)?
@@ -111,6 +119,7 @@ fn selector(
attach_desktop_type(cx, local, "Point", desktop)?;
cx.set_attr(local, "x", Value::Number((x as f64).into()))?;
cx.set_attr(local, "y", Value::Number((y as f64).into()))?;
// 每个候选占四个常量:协议函数、Block、Mount、局部 Point;索引供下面字节码复用。
let start = constants.len() as u32;
constants.extend([
Value::Object(function),
@@ -118,12 +127,16 @@ fn selector(
Value::Object(mount),
Value::Object(local),
]);
// false 分支只跳过“加载本 Mount 并返回”两条指令。按编码宽度计算,
// 常量索引大到需要扩展操作数时仍能跳到下一候选。
let skip = (Instruction::encode_all(&[
Instruction::new(Opcode::LoadConst, start + 2),
Instruction::simple(Opcode::ReturnValue),
])?
.len()
/ 2) as u32;
// 先调用 hitTest(block, mount, local),再把结果传给 validate。
// true 立即返回本 Mount;false 继续下一个候选,实现透明区域向下穿透。
instructions.extend([
Instruction::new(Opcode::LoadConst, 0),
Instruction::simple(Opcode::PushNull),
@@ -139,6 +152,7 @@ fn selector(
Instruction::simple(Opcode::ReturnValue),
]);
}
// 所有候选均未命中时显式返回 Nil;不会把最后一个 false 当作选择结果。
let end = constants.len() as u32;
constants.push(Value::Nil);
instructions.extend([
@@ -156,13 +170,14 @@ struct Prepare {
desktop: ObjectRef,
}
impl NativeCallable for Prepare {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 候选、按下点和释放点已保存于适配器,无需外部实参。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 为按下/释放各建立只读选择器,把两次结果放入同一 VM 调用序列,再交 SameTarget 比较实际出现身份。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
// 按下和释放分别构造选择器,但都在本次只读执行内调用,使用同一预算域。
let down = selector(cx, &self.candidates, self.press, self.desktop)?;
let up = selector(cx, &self.candidates, self.release, self.desktop)?;
let compare = cx.allocate(ContextNativeFunction::new(
@@ -170,6 +185,7 @@ impl NativeCallable for Prepare {
SameTarget,
vec![],
))?;
// 两次选择结果先存入局部槽,再作为两个实参交给 SameTarget;局部槽也保留中间结果生命周期。
let instructions = vec![
Instruction::new(Opcode::LoadConst, 0),
Instruction::simple(Opcode::PushNull),
@@ -199,6 +215,7 @@ impl NativeCallable for Prepare {
..CodeLayout::default()
},
)?;
// 把执行权交回 VM 运行驱动,不在宿主里递归开启另一次 VM 调用。
Ok(NativeResult::Invoke {
function: driver,
arguments: vec![],
@@ -206,7 +223,7 @@ impl NativeCallable for Prepare {
}
}
/// Returned Mount owns one root. No-hit and mismatched targets return None.
/// 解析输入所指向的实际目标,避免把包装身份与底层数据混淆。
/// 在一次有界只读调用中分别选择按下与释放目标;仅二者为同一 Mount 时返回其拥有根。
pub fn resolve(
vm: &mut Vm,
desktop: ObjectRef,
@@ -214,6 +231,7 @@ pub fn resolve(
press: [f32; 2],
release: [f32; 2],
) -> anyhow::Result<Option<ObjectRef>> {
// 显式 captures 保活 desktop;候选列表仍是弱引用,不因等待选择而保活全部旧 Mount。
let prepare = vm.allocate(ContextNativeFunction::new(
"prepare pointer hitTest",
Prepare {
@@ -232,9 +250,11 @@ pub fn resolve(
max_instructions: 1_000_000,
},
);
// 先保存调用结果再释放入口根,因此 VM 返回错误时也能完成入口清理。
vm.release(prepare)?;
let (value, _) = result.map_err(|error| crate::endor_host::runtime_error(vm, error))?;
match value {
// 成功返回的 Mount 仍拥有一次根引用,交由调用方使用并释放;None 不转移任何对象根。
Value::Object(mount) => Ok(Some(mount)),
Value::Nil => Ok(None),
value => {
+54 -10
View File
@@ -40,6 +40,7 @@ fn desktop_type_registry(cx: &NativeContext<'_>, desktop: ObjectRef) -> Result<O
#[derive(Debug, Clone)]
/// 一次源测量的缓存输入、输出和真实读取依赖;不同约束或依赖版本不能复用。
struct Measurement {
// 缓存记录借用的业务身份及方法身份,与子测量、约束和依赖版本共同决定复用资格,不增加托管根。
owner: ObjectRef,
method: ObjectRef,
children: Vec<Size>,
@@ -79,6 +80,7 @@ impl Cache {
#[derive(Debug)]
/// 一个等待源测量返回的收集项,记录本次方法、约束和子项输入。
struct Pending {
// 只读子调用的精确读取跟踪区间 token,由 Step 开始、Collect 在结果解码后结束。
token: usize,
owner: ObjectRef,
method: ObjectRef,
@@ -102,6 +104,7 @@ struct Plan {
pending: Vec<Option<Pending>>,
constraints: Vec<[f32; 4]>,
// Source-arranged dimensions remain exact for this solve, not business state.
// 每个出现两个轴的显式分配,Some 形成精确 min=max 约束;不是可写业务尺寸属性。
allocations: Vec<[Option<f32>; 2]>,
custom_arrange: Vec<bool>,
native_arrange: Vec<bool>,
@@ -137,12 +140,12 @@ struct Step {
desktop: ObjectRef,
}
impl NativeCallable for Step {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 单个布局步骤所需 Mount、阶段和计划已保存,实际调用无参。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 解析当前实际 measure/arrange 实现,决定原生快速路径或源调用,准备本节点输入及依赖收集,避免跳过源覆盖。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
let mount = cx.store().payload::<Mount>(self.mount, "Mount")?.clone();
let definition = cx
@@ -153,6 +156,7 @@ impl NativeCallable for Step {
.store()
.lookup_method(definition, self.phase.method())?
.ok_or(invalid("missing layout method"))?;
// 判断真实宿主实现而非方法名;源覆盖即使调用基类也不能整体绕过其用户逻辑。
let intrinsic = crate::native_visual::is_intrinsic(
cx.store(),
method,
@@ -169,6 +173,7 @@ impl NativeCallable for Step {
.iter()
.map(|child| plan.sizes[*child])
.collect::<Vec<_>>();
// preferred 优先取本轮最初测量值,不能将上一轮 flex 分配当作新的自然基准,造成累计漂移。
let preferred = plan.children[self.index]
.iter()
.map(|child| plan.preferred[*child].unwrap_or(plan.sizes[*child]))
@@ -181,6 +186,7 @@ impl NativeCallable for Step {
if matches!(self.phase, Phase::Measure) {
plan.custom_measure[self.index] = !intrinsic;
}
// 原生 measure 直接计算避免源 VM 调用;源 measure 尝试按 Mount、owner、方法、子尺寸、约束和读取版本复用。
let native_size = if matches!(self.phase, Phase::Measure) && intrinsic {
let constraints = plan.constraints[self.index];
Some(
@@ -213,6 +219,7 @@ impl NativeCallable for Step {
})
})
.map(|entry| entry.size);
// 命中无需再打开读取跟踪;未命中保存 Pending 元信息,等待真正源调用结果返回才建立缓存。
if let Some(size) = cached {
plan.cache.hits += 1;
Some(size)
@@ -236,10 +243,12 @@ impl NativeCallable for Step {
if matches!(self.phase, Phase::Arrange) {
plan.runtime.arranged += 1;
plan.native_arrange[self.index] = intrinsic;
// 原生 arrange 若需要分配 flex/stretch 也视作需显式记录子分配,参与后面的约束收敛。
plan.custom_arrange[self.index] = !intrinsic || node.allocates_children();
}
(node, children, preferred, bounds, native_size)
};
// 先安装本轮节点、子测量和临时 bounds,让源代码调用基类或 Mount.bounds 时观察当前阶段数据。
let context = mount.layout.ok_or(invalid("missing pre-layout context"))?;
{
let mut context = context
@@ -250,6 +259,7 @@ impl NativeCallable for Step {
context.preferred = preferred;
context.bounds = bounds;
}
// 原生结果或缓存命中都包装为同一名义 MeasureResult,后续 Collect 无需区分来源。
if let Some(size) = native_size {
return Ok(NativeResult::Return(Value::Object(record(
cx,
@@ -294,6 +304,7 @@ impl NativeCallable for Step {
}
};
if matches!(self.phase, Phase::Measure) {
// 输入记录初始化完成后再开始子调用跟踪;Collect 解码返回值也在区间内,覆盖复用旧结果对象的字段读取。
let token = cx.store().begin_read_tracking()?;
self.plan
.lock()
@@ -322,13 +333,14 @@ struct Collect {
desktop: ObjectRef,
}
impl NativeCallable for Collect {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 接收一次 measure/arrange 返回的托管结果,按当前 phase 解码。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(1))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 结束当前测量读跟踪并解码结果,验证尺寸或完整子槽安排,再更新计划与可复用测量依赖。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
// 取走本节点待收集状态,确保每个跟踪区间只结束一次;arrange 不建立测量缓存项。
let pending = if matches!(self.phase, Phase::Measure) {
self.plan
.lock()
@@ -345,6 +357,7 @@ impl NativeCallable for Collect {
Phase::Measure => "MeasureResult",
Phase::Arrange => "Arrangement",
};
// 先验证 MeasureResult/Arrangement 名义类型,再解码字段,拒绝只有同名字段的普通对象。
if !cx
.store()
.is_instance(*result, desktop_type(cx.store(), expected, self.desktop)?)?
@@ -357,6 +370,7 @@ impl NativeCallable for Collect {
.map_err(|_| invalid("layout plan poisoned"))?;
match self.phase {
Phase::Measure => {
// 源返回宽高先检查非负有限,再钳制到本出现约束,不允许结果绕过父级分配。
let size = layout::constrained(
Size {
width: number(cx, *result, "width", false)?,
@@ -367,6 +381,7 @@ impl NativeCallable for Collect {
// Native shrink-to-content containers keep their existing input
// policy. Only a source measurement that differs from the native
// result supplies an additional content constraint.
// 源容器测量若不同于默认原生结果,将相应轴记成额外内容上限;后续碰巧相等也不撤销本轮已选限制。
if plan.custom_measure[self.index] && !plan.children[self.index].is_empty() {
let children = plan.children[self.index]
.iter()
@@ -398,6 +413,7 @@ impl NativeCallable for Collect {
})
.transpose()?;
if let Some((pending, reads)) = tracked {
// 若观察了 Mount 内容/几何等不稳定宿主状态,无法证明跨轮可复用,保守地删除该测量缓存。
let mut volatile = false;
let registry = desktop_type_registry(cx, self.desktop)?;
for read in &reads.accesses {
@@ -429,6 +445,7 @@ impl NativeCallable for Collect {
.into_iter()
.filter(|dependency| {
let object = dependency.object();
// 缓存只保留仍存在的业务依赖,去除 desktop、注册表与 Mount;避免宿主提交几何自己反过来使缓存失效。
object != self.desktop
&& object != registry
&& cx.store().object(object).is_ok_and(|value| {
@@ -440,6 +457,7 @@ impl NativeCallable for Collect {
);
}
}
// 仅首次填写 preferred;sizes 每轮更新,根测量直接给本轮根 bounds,安排才能从根向下展开。
plan.preferred[self.index].get_or_insert(size);
plan.sizes[self.index] = size;
if self.index == 0 {
@@ -452,11 +470,13 @@ impl NativeCallable for Collect {
};
let items = object_list::items(cx.store(), list)?;
let children = plan.children[self.index].clone();
// 安排结果必须覆盖全部孩子,不能省略零尺寸项;结合下面 slot 唯一检查保证逐一对应。
if items.len() != children.len() {
return Err(invalid(
"Arrangement must assign every child slot exactly once",
));
}
// 按稳定 slot 找实际孩子下标,不要求源返回列表与孩子原顺序一致;外来或重复 slot 都拒绝。
let slots: HashMap<_, _> = plan.nodes[self.index]
.slots
.iter()
@@ -496,6 +516,7 @@ impl NativeCallable for Collect {
return Err(invalid("arrangement bounds exceed limits"));
}
let child = children[position];
// 源安排或原生弹性分配的差异保留为显式轴分配,下一轮测量使用精确尺寸,确保文字按实际宽度重排。
if plan.custom_arrange[self.index] {
if plan.native_arrange[self.index]
&& let Some(main) = layout::main_axis(&plan.nodes[self.index])
@@ -526,11 +547,11 @@ struct Settle {
mounts: Arc<[WeakObjectRef]>,
}
impl NativeCallable for Settle {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 一轮测量/排列完成后无参进入收敛检查。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 由新 bounds 推导下一轮约束与自然尺寸,比较完整布局状态;稳定则结束,循环状态报错,否则继续同帧求解。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
let repeat = {
let mut plan = self
@@ -538,6 +559,7 @@ impl NativeCallable for Settle {
.lock()
.map_err(|_| invalid("layout plan poisoned"))?;
plan.runtime.settle_passes += 1;
// 安排完成后按最终 bounds 从父到子推导下一轮约束,测量限制和源分配可反向影响换行高度。
let mut next = plan.constraints.clone();
for index in 0..plan.nodes.len() {
let children = plan.children[index].clone();
@@ -570,6 +592,7 @@ impl NativeCallable for Settle {
child_index,
);
let mut constraints = natural;
// 显式轴分配同时设置最小与最大,区别于仅给孩子一个可自由缩小的最大可用宽度。
if let Some(width) = plan.allocations[child][0] {
constraints[0] = width;
constraints[2] = width;
@@ -580,6 +603,7 @@ impl NativeCallable for Settle {
}
if let Some(main) = layout::main_axis(&plan.nodes[index]) {
let cross = 1 - main;
// 交叉轴变化可能改变换行及主轴自然高度,清 preferred 让其重新测量;原生派生主轴分配也需暂时撤销。
if constraints[cross] != plan.constraints[child][cross]
|| constraints[cross + 2] != plan.constraints[child][cross + 2]
{
@@ -600,6 +624,7 @@ impl NativeCallable for Settle {
}
}
let mut state = Vec::with_capacity(plan.nodes.len() * 14);
// 把约束、实测、bounds、分配和首选值编码成几何状态,统一 +0/-0,避免仅符号位差异造成假不收敛。
let bits = |value: f32| if value == 0.0 { 0 } else { value.to_bits() };
for (index, constraints) in next.iter().enumerate() {
state.extend(constraints.iter().copied().map(bits));
@@ -624,6 +649,7 @@ impl NativeCallable for Settle {
state.extend([0, 0]);
}
}
// 相邻两轮状态和约束均相同才停止;非相邻重复则是振荡环,不能把循环误当作稳定布局。
if plan.previous.as_ref() == Some(&state) && plan.constraints == next {
false
} else {
@@ -632,6 +658,7 @@ impl NativeCallable for Settle {
}
plan.previous = Some(state);
plan.constraints = next;
// 需要重算时清全部 bounds;下一轮测量不能访问上轮安排产生的陈旧几何。
plan.bounds.fill(None);
true
}
@@ -660,11 +687,11 @@ struct Prepare {
desktop: ObjectRef,
}
impl NativeCallable for Prepare {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 布局驱动的零参入口,Mount 列表/desktop/计划已由调用方捕获。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 建立按出现位置推进的 Advance 和固定字节码循环,保持同一 VM 预算,避免首次让出前创建整树临时调用对象。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
let advance = cx.allocate(ContextNativeFunction::new(
"next layout occurrence",
@@ -693,13 +720,14 @@ struct Advance {
next: Mutex<usize>,
}
impl NativeCallable for Advance {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 由共享布局循环无参调用,游标表示本轮测量/排列的位置。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 按游标安排自底向上 measure 与自顶向下 arrange,短锁结束后才创建/执行当前节点调用,末尾进入收敛检查。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
let count = self.mounts.len();
// 游标取值/递增只在短锁内完成,不能持锁执行源协议,否则源调用基类会再次访问同一 Plan。
let position = {
let mut next = self
.next
@@ -711,6 +739,7 @@ impl NativeCallable for Advance {
}
position
};
// 每轮恰有 N 个逆序 measure 和 N 个正序 arrange,之后调用 Settle;需要重算时游标归零。
if position == count * 2 {
let settled = Settle {
plan: self.plan.clone(),
@@ -728,6 +757,7 @@ impl NativeCallable for Advance {
}
return Ok(NativeResult::Return(Value::Bool(repeat)));
}
// nodes 是先序,逆序测量保证孩子先完成,正序安排保证父 bounds 已经分配到孩子。
let (phase, index) = if position < count {
(Phase::Measure, count - position - 1)
} else {
@@ -736,6 +766,7 @@ impl NativeCallable for Advance {
let mount = cx
.upgrade(self.mounts[index])?
.ok_or(invalid("layout Mount expired"))?;
// 只为当前出现建立 Step 与 collector,显式 captures 保活本次 Mount/desktop,避免一次分配整棵调用树。
let step = cx.allocate(ContextNativeFunction::new(
"layout step",
Step {
@@ -757,6 +788,7 @@ impl NativeCallable for Advance {
},
vec![self.desktop],
))?;
// 执行一步并立即收集,再给外层 repeat_call 返回 true;各轮迭代共享原 VM 帧和预算。
let function = crate::vm_sequence::collect_and_continue(
cx,
collector,
@@ -810,6 +842,7 @@ impl Work {
/// 显式结束布局续体和只读域,释放本次尚未提交的临时根。
pub fn cancel(self, vm: &mut Vm) -> Result<()> {
// 取消与释放入口根均先尝试,再依次传播错误;普通 Rust drop 无法替代 VM 只读域清理。
let cancelled = vm.cancel_read_only_call();
let released = vm.release(self.prepare);
cancelled?;
@@ -864,9 +897,11 @@ pub fn start(
cache.hits = 0;
cache.misses = 0;
let live: HashSet<_> = mounts.iter().copied().collect();
// 先删除不再出现在此结构中的测量项,防止已移除的弱 Mount 身份无限积累。
cache.entries.retain(|mount, _| live.contains(mount));
// Preserve the existing native measurement cache and avoid VM/result
// allocation for small trees without custom layout methods. Contexts already exist.
// 扫描每个出现的实际 measure/arrange,实现全部为原生还不够,下面 flex/拉伸也会要求收敛驱动。
let mut custom = false;
for weak in &mounts {
let mount = vm
@@ -900,16 +935,19 @@ pub fn start(
}
// Flex allocation can change text wrapping and ancestor measurements even
// when every protocol method is native. Use the same settling driver.
// 仅小于等于64节点且无自定义/弹性分配的树走直接路径;大原生树仍经同一驱动以便分片让出。
if !custom && nodes.len() <= NATIVE_FAST_PATH_MAX_NODES {
cache.clear();
let mut native = runtime.frame(&root)?;
// Only the structural pass consumes a published version.
// 结构准备已经分配本次发布版本,快速完整测量不能再多消耗一个可见布局版本。
native.layout_version = frame.layout_version;
runtime.version = frame.layout_version;
*frame = native;
state.reads.clear();
return Ok(Progress::Complete(state));
}
// 帧结构、弱 Mount 和视觉节点必须同序同数量,否则按出现下标执行协议会把上下文接错。
anyhow::ensure!(
nodes.len() == mounts.len() && nodes.len() == frame.mounts.len(),
"layout structure does not match Mount contexts"
@@ -926,6 +964,7 @@ pub fn start(
children[indices[&parent]].push(index);
}
}
// 从根向下初始化约束,之后每轮由 Settle 结合真实父分配细化;初始值不是最终精确几何。
let mut constraints = vec![runtime.root_constraints(); nodes.len()];
for index in 0..nodes.len() {
for (child_index, child) in children[index].iter().enumerate() {
@@ -938,6 +977,7 @@ pub fn start(
}
}
let count = nodes.len();
// 把运行时/缓存克隆进未发布 Plan,失败或取消时上层可以丢弃派生求解结果而不提交半帧。
let plan = Arc::new(Mutex::new(Plan {
sizes: vec![Size::default(); nodes.len()],
preferred: vec![None; nodes.len()],
@@ -973,6 +1013,7 @@ pub fn start(
desktop,
slices: 1,
};
// 一次有界只读调用跨所有节点与收敛轮次;slice 只控制让出量,总指令预算仍共享一百万。
let progress = vm.start_read_only_call(
prepare,
&[],
@@ -992,6 +1033,7 @@ fn finish(
value: Value,
reads: Vec<endor_core::ReadDependency>,
) -> Result<Progress> {
// 驱动返回值仅为控制流结果,先释放;真正结果保存在原生 Plan,而非返回值中的第二份业务图。
vm.release_value(value)?;
let mut plan = work
.plan
@@ -999,6 +1041,7 @@ fn finish(
.map_err(|_| anyhow::anyhow!("layout plan poisoned"))?;
plan.runtime.slices = work.slices;
let frame = &mut work.state.frame;
// 用最终收敛 bounds 更新 frame 的各出现;这里只生成默认内容命令,后续投影/源 paint 还会重建完整绘制表。
frame.commands.clear();
for (index, mount) in frame.mounts.iter_mut().enumerate() {
let [x, y, width, height] =
@@ -1016,6 +1059,7 @@ fn finish(
}
work.state.runtime = plan.runtime.clone();
work.state.cache = plan.cache.clone();
// 大原生树可能使用分片驱动但没有真正源读取,因此无需把宿主驱动读取当业务布局依赖发布。
if !plan.custom {
work.state.reads.clear();
return Ok(Progress::Complete(work.state));
+44 -7
View File
@@ -33,7 +33,7 @@ fn object(value: Value) -> Result<ObjectRef, VmError> {
Err(invalid("paint must return managed objects"))
}
}
/// 把当前源值或文本选择解码成此调用需要的文本表示。
/// 读取指定命令字段并要求其值为 Text;不隐式字符串化其他类型。
fn text(store: &ObjectStore, object: ObjectRef, name: &str) -> Result<String, VmError> {
if let Value::Text(value) = store.get_attr(object, name)? {
Ok(value)
@@ -46,6 +46,7 @@ fn number(store: &ObjectStore, object: ObjectRef, name: &str) -> Result<f32, VmE
let Value::Number(value) = store.get_attr(object, name)? else {
return Err(invalid("paint field must be a Number"));
};
// x/y 允许负数以表达相对原点的绘制;其余长度必须非负。所有数值都必须有限且在尺寸预算内。
let value = value
.to_string()
.parse::<f32>()
@@ -73,12 +74,14 @@ fn decode(
command: ObjectRef,
expected: ObjectRef,
) -> Result<RenderCommand, VmError> {
// 使用当前 desktop 注册的 PaintCommand 名义类型;字段形状相似的普通对象也不能冒充命令。
if !store.is_instance(command, expected)? {
return Err(invalid("paint commands must be PaintCommand instances"));
}
let x = number(store, command, "x")?;
let y = number(store, command, "y")?;
let kind = text(store, command, "kind")?;
// 场景和图片命令持有独立资源,无需读取通用颜色字段。
let color = if matches!(kind.as_str(), "scene3d" | "image") {
String::new()
} else {
@@ -87,6 +90,7 @@ fn decode(
let result = match kind.as_str() {
"image" => crate::bridge::graphics::decode_image(store, command)?,
"scene3d" => {
// 这里仅接受宿主生成的 PaintView payload,克隆原生 Arc,不把活动的 VM 场景图传到绘制线程。
let snapshot = object(store.get_attr(command, "scene")?)?;
RenderCommand::Scene3D {
x,
@@ -103,6 +107,7 @@ fn decode(
let width = number(store, command, "width")?;
let height = number(store, command, "height")?;
let radius = number(store, command, "radius")?;
// 单项数值合法还不足以保证右/下边界合法;额外检查原点与尺寸相加后的范围。
if x + width > MAX_DIMENSION as f32 || y + height > MAX_DIMENSION as f32 {
return Err(invalid("paint rectangle exceeds bounds"));
}
@@ -129,9 +134,11 @@ fn decode(
}
"text" => {
let size = number(store, command, "size")?;
// size 是离散文字等级而非任意像素字号,只接受 1 到 8 的整数。
if size.fract() != 0.0 || !(1.0..=8.0).contains(&size) {
return Err(invalid("paint text size must be an integer from 1 to 8"));
}
// 两个换行边界必须同时出现或同时缺失;只缺一个时传播属性错误,防止半定义文本框。
let wrap_bounds = match (
store.get_attr(command, "wrapWidth"),
store.get_attr(command, "wrapHeight"),
@@ -154,6 +161,7 @@ fn decode(
}
_ => return Err(invalid("unsupported paint command kind")),
};
// 变体字段解码后仍走统一命令校验,覆盖颜色格式、文本以及组合几何合法性。
result
.validate()
.map_err(|_| invalid("invalid paint command geometry, text or color"))?;
@@ -163,7 +171,9 @@ fn decode(
#[derive(Debug, Default)]
/// 按出现 ID 收集已检查的源绘制覆盖,随后与原生默认命令合并。
struct PaintOutput {
// 按出现 ID 收集覆盖;同一个业务 Block 在多个 Mount 中可产生不同绘制结果。
commands: BTreeMap<u64, Vec<RenderCommand>>,
// 全轮源命令累计数,不能靠拆分多个源 DisplayList 绕过 10000 条总预算。
count: usize,
}
type Output = Arc<Mutex<PaintOutput>>;
@@ -175,12 +185,12 @@ struct Collect {
output: Output,
}
impl NativeCallable for Collect {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 接收当前出现位置 paint 的唯一 DisplayList 结果。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(1))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 验证返回名义类型并完整解码所有 PaintCommand,检查全轮命令预算后才把该出现位置结果写入输出表。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
let [Value::Object(result)] = args else {
return Err(invalid("paint must return a DisplayList"));
@@ -191,12 +201,14 @@ impl NativeCallable for Collect {
)? {
return Err(invalid("paint must return a DisplayList"));
}
// 先验证外层 DisplayList,再取其受控 ObjectList;所有成员解码成功后才写入 output。
let commands = object(cx.store().get_attr(*result, "commands")?)?;
let expected = named_type(cx.store(), self.desktop, "PaintCommand")?;
let commands = object_list::items(cx.store(), commands)?
.iter()
.map(|command| decode(cx.store(), *command, expected))
.collect::<Result<Vec<_>, _>>()?;
// 仅收集结果时持锁,不在调用源 paint 期间持有结果锁;失败不会插入半个命令列表。
let mut output = self
.output
.lock()
@@ -217,13 +229,14 @@ struct Prepare {
output: Output,
}
impl NativeCallable for Prepare {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 零参数驱动入口,待绘制 Mount 和输出容器已保存在适配器。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 建立共享游标与固定外层字节码循环,让 VM 每轮只准备一个出现位置的 paint 调用。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
// 构造一个共享游标驱动;每轮只准备当前出现,避免一次保留所有出现的临时实参。
let advance = cx.allocate(ContextNativeFunction::new(
"next paint occurrence",
Advance {
@@ -251,12 +264,13 @@ struct Advance {
output: Output,
}
impl NativeCallable for Advance {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 由外层循环无参调用,下一出现位置由内部游标决定。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 短锁内取并推进游标,随后验证/准备当前 Mount 的方法与几何;用临时调用链收集结果,完成后才进入下一位置。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
// 锁只保护取游标与递增;离开此块后释放锁,再做 VM 分配和源调用。
let occurrence = {
let mut next = self
.next
@@ -266,6 +280,7 @@ impl NativeCallable for Advance {
*next += usize::from(occurrence.is_some());
occurrence
};
// false 是 repeat_call 的停止信号;有出现时即使跳过原生方法也返回 true 继续遍历。
let Some((id, weak)) = occurrence else {
return Ok(NativeResult::Return(Value::Bool(false)));
};
@@ -284,9 +299,11 @@ impl NativeCallable for Advance {
.store()
.lookup_method(definition, "paint")?
.ok_or(invalid("missing paint method"))?;
// 原生默认 paint 留给 finish 生成;仅执行实际覆盖的源方法,避免重复绘制同一出现。
if crate::native_visual::is_intrinsic(cx.store(), function, "paint", self.desktop)? {
return Ok(NativeResult::Return(Value::Bool(true)));
}
// 把已提交 Mount 几何封装为本轮临时 Bounds;新分配参数可初始化,业务模型仍处于只读域。
let bounds = cx.new_object()?;
attach_desktop_type(cx, bounds, "Bounds", self.desktop)?;
for (name, value) in [
@@ -297,6 +314,7 @@ impl NativeCallable for Advance {
] {
cx.set_attr(bounds, name, Value::Number((value as f64).into()))?;
}
// 收集器只捕获桌面根和当前出现 ID;输出是原生共享容器,不增加业务图的强引用。
let collector = cx.allocate(ContextNativeFunction::new(
"collect source paint",
Collect {
@@ -306,6 +324,7 @@ impl NativeCallable for Advance {
},
vec![self.desktop],
))?;
// 辅助帧先执行 paint(block, mount, bounds),收集其结果,再返回 true 推进外层游标。
let function = crate::vm_sequence::collect_and_continue(
cx,
collector,
@@ -327,7 +346,9 @@ impl NativeCallable for Advance {
/// 已经完成本阶段、但尚未由桥接层发布的派生结果,包含帧/缓存或真实读取依赖。
pub struct Draft {
// 已经合并命令的原生帧;Draft 仍需桥接层提交,完成计算不等于发布成功。
pub frame: Frame,
// 保留源绘制的业务读取依赖,供下次写入后判定是否必须重绘。
pub reads: Vec<endor_core::ReadDependency>,
pub slices: usize,
}
@@ -343,6 +364,7 @@ pub enum Progress {
/// 拥有未完成源调用及临时根的工作句柄;丢弃 Rust 值不能替代 VM 内的取消。
pub struct Work {
desktop: ObjectRef,
// 跨切片保留的入口根;完成或取消都必须在所属 VM 中显式释放。
prepare: ObjectRef,
output: Output,
root: Option<Arc<UiNode>>,
@@ -353,6 +375,7 @@ pub struct Work {
impl Work {
/// 继续当前绘制续体,保留其先前收集的命令和所属窗口上下文。
pub fn resume(mut self, vm: &mut Vm, slice: usize) -> Result<Progress> {
// 恢复保留原执行预算,slice 只决定本次让出的指令配额,不能重置整个绘制上限。
self.slices += 1;
let progress = vm.resume_read_only_call(slice);
self.accept(vm, progress)
@@ -360,6 +383,7 @@ impl Work {
/// 关闭未完成绘制续体并释放其临时根,不发布半完成命令列表。
pub fn cancel(self, vm: &mut Vm) -> Result<()> {
// 先执行取消和 release 两个操作,再依次传播错误;取消失败也仍尝试释放入口根。
let cancelled = vm.cancel_read_only_call();
let released = vm.release(self.prepare);
cancelled?;
@@ -374,6 +398,7 @@ impl Work {
progress: Result<endor_core::ExecutionProgress, VmError>,
) -> Result<Progress> {
match progress {
// 挂起时工作句柄继续持有 frame/output/prepare,不能发布部分输出。
Ok(endor_core::ExecutionProgress::Pending { .. }) => {
Ok(Progress::Pending(Box::new(self)))
}
@@ -382,11 +407,13 @@ impl Work {
dependencies,
..
}) => {
// VM 完成后先释放入口与驱动返回值,再读取纯原生收集结果;返回值本身不作为绘制命令。
vm.release(self.prepare)?;
vm.release_value(value)?;
finish(vm, self, dependencies)
}
Err(error) => {
// 趁 VM 诊断信息仍可用先生成错误,再取消只读执行并清理临时根。
let diagnostic = crate::endor_host::runtime_error(vm, error);
self.cancel(vm)?;
Err(diagnostic)
@@ -404,6 +431,7 @@ pub fn start(
frame: Frame,
slice: usize,
) -> Result<Progress> {
// 禁止零切片和嵌套只读/挂起调用;同一 VM 同时只能由一个续体驱动。
anyhow::ensure!(slice > 0, "paint slice must be positive");
anyhow::ensure!(
!vm.has_suspended_call() && !vm.object_store().is_read_only(),
@@ -445,7 +473,9 @@ fn finish(vm: &mut Vm, mut work: Work, reads: Vec<endor_core::ReadDependency>) -
.output
.lock()
.map_err(|_| anyhow::anyhow!("paint output poisoned"))?;
// 是否有源覆盖以 map 是否为空判断;源方法返回空命令列表也算覆盖,会抑制该出现的默认绘制。
let native_only = output.commands.is_empty();
// 没有根时没有节点投影可合并,直接交回已有帧并清空绘制读取,不展开默认命令。
if work.root.is_none() {
return Ok(Progress::Complete(Box::new(Draft {
frame: work.frame,
@@ -456,6 +486,7 @@ fn finish(vm: &mut Vm, mut work: Work, reads: Vec<endor_core::ReadDependency>) -
let root = work.root.as_deref();
let desktop = work.desktop;
let frame = &mut work.frame;
// 建立 Block ID 到不可变节点的索引;最终合并顺序仍以 frame.mounts 为准,不能按 map 排序。
let mut nodes = HashMap::new();
let mut pending: Vec<_> = root.into_iter().collect();
while let Some(node) = pending.pop() {
@@ -467,7 +498,9 @@ fn finish(vm: &mut Vm, mut work: Work, reads: Vec<endor_core::ReadDependency>) -
let mut views = Vec::new();
let mut owners = Vec::new();
for mount in &frame.mounts {
// 记录本出现追加前的长度,用差值为新增命令同步扩展 clip/view/owner 三张平行表。
let before = commands.len();
// 有源覆盖则使用其整个结果(包括空列表);否则用节点和 Mount 几何生成原生默认命令。
if let Some(custom) = output.commands.get(&mount.id) {
commands.extend(custom.iter().cloned());
} else {
@@ -487,6 +520,7 @@ fn finish(vm: &mut Vm, mut work: Work, reads: Vec<endor_core::ReadDependency>) -
clips.extend(std::iter::repeat_n(mount.clip, commands.len() - before));
views.extend(std::iter::repeat_n(mount.view, commands.len() - before));
owners.extend(std::iter::repeat_n(mount.id, commands.len() - before));
// 混合原生与源命令后再检查总预算,前面的源输出预算不能覆盖这里新增的默认命令。
if commands.len() > 10_000 {
bail!("paint command budget exceeded");
}
@@ -495,8 +529,11 @@ fn finish(vm: &mut Vm, mut work: Work, reads: Vec<endor_core::ReadDependency>) -
frame.command_clips = clips;
frame.command_views = views;
frame.command_mounts = owners;
// 统一命令和投影元数据就绪后,再把世界 UI 面板装配进对应 3D 场景。
crate::scene3d::panel::compose(frame)?;
let registry = object(vm.get_attr(desktop, "types")?)?;
// 排除宿主桌面、类型注册表、Mount 以及已经死亡的临时身份,只保留业务读取。
// 纯原生帧不需要保留这次驱动的读取记录。
let reads = reads
.into_iter()
.filter(|dependency| {
+44 -1
View File
@@ -69,9 +69,11 @@ pub struct TextSize {
/// 文字整形缓存键,包含文本、样式和可选换行宽度。
struct TextKey {
value: String,
// 用浮点原始位模式做键,精确区分整形参数;不是把字号取整为 u32。
font_size: u32,
line_height: u32,
family: TextFamily,
// None 表示不换行,Some 保存宽度的浮点位模式;同一文本不同宽度必须分开缓存。
wrap_width: Option<u32>,
}
@@ -88,15 +90,17 @@ struct TextEngine {
code_family: Option<String>,
swash: SwashCache,
buffers: HashMap<TextKey, PreparedText>,
// 累计缓存文本的 UTF-8 字节数,只衡量源文本预算,并非 Buffer/字形的总内存。
source_bytes: usize,
}
impl TextEngine {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 扫描系统字体,选择可用的界面/等宽字体偏好,并建立空整形和栅格缓存。
fn new() -> Self {
let mut fonts = FontSystem::new();
// Select installed, readable families rather than assuming an OS font
// name exists. COSMIC Text handles per-glyph fallback (including CJK).
// 按偏好顺序查询实际安装字体,找到第一个匹配名;找不到则由字体系统默认族处理。
let choose = |choices: &[&str]| {
choices.iter().find_map(|choice| {
fonts
@@ -139,6 +143,7 @@ impl TextEngine {
/// 为文本、字体样式和可选换行宽度建立整形缓存,超过缓存预算先清理旧结果。
fn prepare_width(&mut self, value: &str, style: TextStyle, wrap_width: Option<f32>) -> TextKey {
// 键包含全部排版输入;命中后测量与绘制都复用同一 Buffer,避免两套排版产生偏差。
let key = TextKey {
value: value.to_owned(),
font_size: style.font_size.to_bits(),
@@ -150,6 +155,8 @@ impl TextEngine {
return key;
}
// Cache recent shaped strings, without retaining every submitted source.
// 采用整批清空而非 LRU;新增前达到条数或文本字节阈值时释放旧整形结果。
// 单个超大文本仍会被整形,source_bytes 不是对单次输入长度的硬拒绝。
if self.buffers.len() >= 256 || self.source_bytes + value.len() > 524_288 {
self.buffers.clear();
self.source_bytes = 0;
@@ -168,11 +175,13 @@ impl TextEngine {
&mut self.fonts,
Metrics::new(style.font_size, style.line_height),
);
// 有限宽度使用按词优先、字形兜底的换行策略,兼容中文和无空格长标识符;无宽度则不换行。
buffer.set_wrap(if wrap_width.is_some() {
Wrap::WordOrGlyph
} else {
Wrap::None
});
// 高度不设上限,让测量能得到所有换行后的完整内容高度,而非当前裁剪区域高度。
buffer.set_size(wrap_width, None);
buffer.set_text(
value,
@@ -180,7 +189,9 @@ impl TextEngine {
Shaping::Advanced,
Some(Align::Left),
);
// 整形采用高级脚本处理和左对齐;实际字形及回退由同一 FontSystem 决定。
buffer.shape_until_scroll(&mut self.fonts, false);
// 即使空文本没有布局 run 也保留一行高度;宽度取各行最大值,高度取最下方行底。
let mut size = TextSize {
width: 0.0,
height: style.line_height,
@@ -198,6 +209,7 @@ impl TextEngine {
/// 取得全局受锁保护的字体/整形引擎;共享缓存不等于可以并行修改字体状态。
fn engine() -> &'static Mutex<TextEngine> {
// 惰性创建全进程引擎;Mutex 同时保护字体库、整形缓存与栅格缓存,测量和绘制不能并发修改它。
static ENGINE: OnceLock<Mutex<TextEngine>> = OnceLock::new();
ENGINE.get_or_init(|| Mutex::new(TextEngine::new()))
}
@@ -211,6 +223,7 @@ pub fn measure(value: &str, style: TextStyle) -> TextSize {
/// 按可用宽度整形并测量多行高度,供布局与实际段落绘制共用。
pub fn measure_wrapped(value: &str, style: TextStyle, width: f32) -> TextSize {
// 零或负可用宽度直接返回零宽与一行高,避免给整形器无效换行宽度。
if width <= 0.0 {
return TextSize {
width: 0.0,
@@ -241,9 +254,12 @@ pub fn draw_clipped(
{
return;
}
// 超大字号按比例降到最高 512 再栅格化;普通字号保持 1。
// 字体、行高和换行宽度一起缩小,后续用 1/lod 恢复目标几何比例。
let lod = (512. / style.font_size).min(1.);
let mut engine = engine().lock().expect("text engine lock");
let key = engine.prepare_width(value, style.scaled(lod), width.map(|width| width * lod));
// 拆借可变字段以便在保留 Buffer 借用时访问字体和 Swash 缓存,不复制整形结果。
let TextEngine {
fonts,
swash,
@@ -251,6 +267,7 @@ pub fn draw_clipped(
..
} = &mut *engine;
let buffer = &buffers[&key].buffer;
// 从已有 image_cache 统计位图字节;不包含整形 Buffer,也不含字体数据库本身。
let mut cache_bytes: usize = swash
.image_cache
.values()
@@ -262,6 +279,7 @@ pub fn draw_clipped(
let physical = glyph.physical((0., run.line_y), 1.);
// Conservative font-sized guard includes bearings/overhangs. The
// exact bitmap bounds below determine the actual visible pixels.
// 先用保守包围范围排除完全不可见字形,尽量避免生成裁剪区外的位图;精确边界由实际位图决定。
let guard = glyph.font_size * 4. / lod;
let gx = physical.x as f32 / lod;
let gy = physical.y as f32 / lod;
@@ -272,10 +290,12 @@ pub fn draw_clipped(
{
continue;
}
// 达到条数或约 32 MiB 时替换整个 SwashCache,再生成当前可见字形;预算不因缩放无限增长。
if swash.image_cache.len() >= 4096 || cache_bytes >= 33_554_432 {
*swash = SwashCache::new();
cache_bytes = 0;
}
// 只对新生成的图像增加字节统计;缓存中的生成失败项由 None 跳过,不参与绘制。
let cached = swash.image_cache.contains_key(&physical.cache_key);
let Some(image) = swash.get_image(fonts, physical.cache_key) else {
continue;
@@ -283,22 +303,28 @@ pub fn draw_clipped(
if !cached {
cache_bytes += image.data.len();
}
// 位图 placement 包含字形 bearing。顶部使用基线减 top,再除 lod 转回目标绘制空间。
let left = (physical.x + image.placement.left) as f32 / lod;
let top = (physical.y - image.placement.top) as f32 / lod;
let right = left + image.placement.width as f32 / lod;
let bottom = top + image.placement.height as f32 / lod;
// 可选字形颜色覆盖 RGB,但透明度始终采用调用方的整体 alpha。彩色位图分支会使用位图自己的 RGB。
let base = glyph.color_opt.map_or(color, |value| {
Color::rgba(value.r(), value.g(), value.b(), color.alpha)
});
// 循环范围取位图与 clip 交集,只遍历最终可见像素;ceil 与半像素采样共同决定整数像素覆盖。
for y in top.max(clip.y).ceil() as i32..bottom.min(clip.y + clip.height).ceil() as i32 {
for x in
left.max(clip.x).ceil() as i32..right.min(clip.x + clip.width).ceil() as i32
{
// 把目标像素中心反映射到低分辨率位图,再钳制到最后一个有效像素,避免边缘采样越界。
let u = (((x as f32 + 0.5 - left) * lod) as u32)
.min(image.placement.width.saturating_sub(1));
let v = (((y as f32 + 0.5 - top) * lod) as u32)
.min(image.placement.height.saturating_sub(1));
let index = (v * image.placement.width + u) as usize;
// 灰度 Mask 把覆盖率乘整体 alpha;Color 保留位图 RGB 并乘其 alpha。
// SubpixelMask 不适用此软件合成路径,直接跳过。
let sample = match image.content {
cosmic_text::SwashContent::Mask => Color::rgba(
base.red,
@@ -317,6 +343,7 @@ pub fn draw_clipped(
}
cosmic_text::SwashContent::SubpixelMask => continue,
};
// 只输出采样颜色,最终混合由调用方 pixel 完成;回调在引擎锁持有期间执行,不应重入文字引擎。
pixel(x, y, sample);
}
}
@@ -331,6 +358,7 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
// A source line may include a very large comment. Only shape a bounded
// preview for the sidebar; the stored source and its AST spans stay intact.
// 仅预览截断至约 8 KiB 字素边界,不改保存的源码。单个超长字素也不能被拆开。
let truncated = value.len() > 8192;
let value = if truncated {
let end = value
@@ -343,6 +371,7 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
} else {
value
};
// 原文本未受预览截断且已能放下时原样返回;受截断文本即使较短也要追加省略号提示。
if !truncated && measure(value, style).width <= width {
return value.to_owned();
}
@@ -350,15 +379,18 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
if width <= 0.0 || measure(ellipsis, style).width > width {
return String::new();
}
// 保存每个完整字素簇的结束字节位置,后续切片不会拆开组合音标或连字 emoji。
let ends: Vec<_> = value
.grapheme_indices(true)
.map(|(start, part)| start + part.len())
.collect();
let mut low = 0;
let mut high = ends.len();
// 二分搜索可容纳的最长字素前缀;取上中位数使成功分支能推进 low,避免相邻边界时死循环。
while low < high {
let count = (low + high).div_ceil(2);
let end = ends[count - 1];
// 省略号也参与真实整形测量,不能简单从总宽度减去字符数估算。
let candidate = format!("{}{ellipsis}", &value[..end]);
if measure(&candidate, style).width <= width {
low = count;
@@ -366,6 +398,7 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
high = count - 1;
}
}
// 没有任何字素能放下时只返回省略号;更早已经检查省略号本身可容纳。
let end = low.checked_sub(1).map_or(0, |index| ends[index]);
format!("{}{ellipsis}", &value[..end])
}
@@ -407,7 +440,9 @@ mod tests {
use unicode_segmentation::UnicodeSegmentation;
#[test]
/// 用一万倍缩放检验绘制回调被限制在32x32裁剪内,同时检查字形缓存字号不超过512以控制中间资源。
fn extreme_zoom_rasterizes_only_the_clip_with_bounded_glyph_sizes() {
// 极端缩放测试限制实际回调在 32×32 裁剪区,同时检查缓存字号不超过 512。
let mut count = 0;
draw_clipped(
"M",
@@ -433,8 +468,10 @@ mod tests {
}
#[test]
/// 混合中文、单词、长标识符、组合字符和emoji,检查窄宽约束分别换行/缓存,且不污染无约束自然测量。
fn width_sensitive_shaping_wraps_words_and_clusters_without_changing_intrinsic_metrics() {
let style = TextStyle::ui(1);
// 混合中文、长英文词、组合字符和 emoji,验证窄/宽换行缓存隔离且不改变无换行测量结果。
let text = "中文段落 with words and long_unbroken_identifier é 👩‍💻 中文段落";
let intrinsic = measure(text, style);
let narrow = measure_wrapped(text, style, 70.0);
@@ -452,7 +489,9 @@ mod tests {
}
#[test]
/// 比较比例字体宽窄字母、等宽字体、多行高度与缩放比例,证明尺寸来自字体整形而非按字符数估计。
fn proportional_metrics_monospace_and_multiline_height_come_from_the_fonts() {
// 用宽窄拉丁字母验证比例字体差异、等宽字体一致性、多行行高和同比例缩放。
let ui = TextStyle::ui(1);
assert!(measure("WWWW", ui).width > measure("iiii", ui).width * 2.0);
let mono = TextStyle::code();
@@ -463,8 +502,10 @@ mod tests {
}
#[test]
/// 普通和代码字体都需为四个中文字符产生非零glyph_id;依赖测试环境安装可用CJK回退字体。
fn system_fallback_shapes_chinese_without_missing_glyphs() {
let mut engine = engine().lock().unwrap();
// 两种字体风格都要求四个中文字符生成非零 glyph_id,确保系统回退实际找到了字形。
for style in [TextStyle::ui(1), TextStyle::code()] {
let key = engine.prepare("中文字体", style);
let glyphs: Vec<_> = engine.buffers[&key]
@@ -479,6 +520,7 @@ mod tests {
}
#[test]
/// 按实际测量宽度截断带组合字符的文本,结果需是原文字素边界前缀加省略号,且整体不超宽。
fn ellipsis_fits_actual_width_and_preserves_graphemes() {
let style = TextStyle::code();
let short_source = "let s = ui.text(\"中文字体\")";
@@ -486,6 +528,7 @@ mod tests {
let value = "e\u{301}e\u{301}中文字体e\u{301}e\u{301}";
let width = measure("e\u{301}e\u{301}中…", style).width + 0.01;
let fitted = fit(value, width, style);
// 检查结果前缀确实来自原文且结束于字素边界,而不仅是合法 UTF-8 字节边界。
let prefix = fitted.strip_suffix('…').unwrap();
assert!(value.starts_with(prefix));
assert!(
+30 -3
View File
@@ -39,10 +39,12 @@ pub struct CameraView {
/// 读取并校验托管 Camera2D 的位置和缩放,生成原生投影描述。
pub fn camera(store: &ObjectStore, object: ObjectRef) -> Result<CameraView, VmError> {
// 先验证实际宿主 payload,避免只有 x/y/zoom 同名字段的普通对象冒充相机。
store.payload::<Camera2D>(object, "Camera2D")?;
let x = crate::scroll::coordinate(&store.get_attr(object, "x")?)?;
let y = crate::scroll::coordinate(&store.get_attr(object, "y")?)?;
let zoom = crate::scroll::coordinate(&store.get_attr(object, "zoom")?)?;
// coordinate 已检查有限性与绝对范围;zoom 还要严格为正并位于专门相机范围,保证可逆变换。
if !(0.01..=100.0).contains(&zoom) {
return Err(VmError::InvalidArgument(
"Camera2D.zoom expects 0.01 through 100",
@@ -63,6 +65,7 @@ pub fn fit(
cx: &mut endor_core::NativeContext<'_>,
mount: &crate::mount::Mount,
) -> Result<(), VmError> {
// 只接受已提交的 CanvasViewport,布局期间的临时几何不能作为 fitView 分配尺寸依据。
if !mount.geometry.canvas_viewport || mount.layout.is_some() {
return Err(VmError::InvalidArgument(
"fitView requires a committed CanvasViewport Mount",
@@ -83,6 +86,7 @@ pub fn fit(
.store()
.payload::<crate::mount::Mount>(root, "Mount")?
.clone();
// 只汇总场景直接子出现的有限边界,沿 sibling 链扫描;不把无限世界或整棵后代图作为布局盒。
let mut next = scene.first_child;
let mut bounds: Option<[f32; 4]> = None;
let mut count = 0;
@@ -95,12 +99,14 @@ pub fn fit(
.upgrade(weak)?
.ok_or(VmError::InvalidArgument("expired scene child"))?;
let child = cx.store().payload::<crate::mount::Mount>(object, "Mount")?;
// 先扣 scene 原点,把孩子绝对布局坐标转为场景相对坐标;此数组存左上/右下,而非宽高。
let rect = [
child.geometry.x - scene.geometry.x,
child.geometry.y - scene.geometry.y,
child.geometry.x - scene.geometry.x + child.geometry.width,
child.geometry.y - scene.geometry.y + child.geometry.height,
];
// 逐个扩展共同包围框,空场景保持 None 并在后面回到单位相机。
bounds = Some(bounds.map_or(rect, |b| {
[
b[0].min(rect[0]),
@@ -113,13 +119,16 @@ pub fn fit(
}
let node = crate::block::snapshot(cx.store(), mount.block)?;
let inset = crate::layout::insets(&node);
// 扣除布局 inset 后才是相机可用的内容区域;负值归零,避免用边框占用部分计算缩放。
let width = (mount.geometry.width - inset.horizontal()).max(0.0);
let height = (mount.geometry.height - inset.vertical()).max(0.0);
let (x, y, zoom) = if let Some(bounds) = bounds {
// 两个轴分别计算可容纳倍率再取较小者;内容跨度增加 48 世界单位形成留白,最终钳到相机范围。
let zoom = (width / (bounds[2] - bounds[0] + 48.0))
.min(height / (bounds[3] - bounds[1] + 48.0))
.clamp(0.01, 100.0);
(
// 让内容中心落在视口中心:相机位置 = 内容中心 - 半个视口的世界尺寸。
(bounds[0] + bounds[2]) / 2.0 - width / (2.0 * zoom),
(bounds[1] + bounds[3]) / 2.0 - height / (2.0 * zoom),
zoom,
@@ -127,6 +136,7 @@ pub fn fit(
} else {
(0.0, 0.0, 1.0)
};
// 最终通过普通属性写入走 VM 变更追踪/绑定机制;共享该相机的其他视口也会观察到更新。
for (name, value) in [("x", x), ("y", y), ("zoom", zoom)] {
cx.set_attr(
camera,
@@ -160,6 +170,7 @@ impl Transform {
Point::new(point.x * self.zoom + self.x, point.y * self.zoom + self.y)
}
/// 将视图点反算回逻辑坐标,供命中和手势锚点计算使用。
// 不在这里额外校验 zoom,调用方必须先保证 valid;零缩放无法反算。
pub fn inverse(self, point: Point) -> Point {
Point::new(
(point.x - self.x) / self.zoom,
@@ -177,6 +188,7 @@ impl Transform {
)
}
/// 将当前变换再放入外层变换,保持绘制与逆向命中的组合顺序一致。
// 组合为 outer(self(point)):内层平移也要乘外层缩放,不能只把两次平移相加。
pub fn then(self, outer: Self) -> Self {
Self {
zoom: self.zoom * outer.zoom,
@@ -184,8 +196,9 @@ impl Transform {
y: self.y * outer.zoom + outer.y,
}
}
/// 检查数值、几何和资源条件是否满足本类型约束,供上层拒绝非法输入。
/// 验证累计二维变换:zoom 有限且在 (0,1000000],平移有限且绝对值不超过一万亿。
pub fn valid(self) -> bool {
// 允许累计平移远大于单个世界坐标范围,因为相机偏移还会乘缩放;同时限制嵌套累计放大。
self.zoom.is_finite()
&& self.zoom > 0.0
&& self.zoom <= 1_000_000.0
@@ -198,6 +211,7 @@ impl Transform {
/// 计算视口与祖先裁剪的共同可见矩形。
fn intersect(a: [f32; 4], b: [f32; 4]) -> [f32; 4] {
// clip 用 [x,y,width,height],分离的矩形返回零面积,不产生负宽高。
let x = a[0].max(b[0]);
let y = a[1].max(b[1]);
[
@@ -222,12 +236,14 @@ pub fn project(
nodes.insert(node.block_id.as_str(), node);
work.extend(node.children().iter().map(|node| node.as_ref()));
}
// 每个出现向孩子传递累计二维变换、当前空间的裁剪和嵌套面板映射;业务布局坐标不被改写。
type Scope = (
Transform,
Option<[f32; 4]>,
Option<Arc<crate::scene3d::panel::Mapping>>,
);
let mut contexts = HashMap::<u64, Scope>::new();
// 保留 next_sibling 查找表,遍历可变 Mount 时仍可按稳定子出现顺序为面板根建立映射。
let next: HashMap<_, _> = frame
.mounts
.iter()
@@ -237,6 +253,7 @@ pub fn project(
HashMap::<u64, (Arc<crate::scene3d::panel::Mapping>, crate::layout::Size)>::new();
for mount in &mut frame.mounts {
let node = nodes[mount.block_id.as_str()];
// 面板根进入独立纹理像素空间,二维变换重置为单位,裁剪重置为面板尺寸;普通节点沿用父上下文。
let (view, clip, panel) = if let Some((panel, size)) = panels.get(&mount.id) {
(
Transform::default(),
@@ -253,6 +270,7 @@ pub fn project(
view.valid(),
"nested viewport transform exceeds numeric budget"
);
// 单位变换省略存储,其余保持为显式 Transform;每轮先清理旧 viewport_clip,避免残留上帧状态。
mount.view = (view != Transform::default()).then_some(view);
mount.panel = panel.clone();
mount.clip = clip;
@@ -263,6 +281,7 @@ pub fn project(
let viewport = if let UiKind::CanvasViewport { camera, .. } = &node.kind {
let x = mount.x + inset.left;
let y = mount.y + inset.top;
// 围绕视口内容原点建立相机变换:原点保持锚定,世界内容先减相机位置再缩放,最后套父变换。
child_view = Transform {
zoom: camera.zoom,
x: x * (1.0 - camera.zoom) - camera.x * camera.zoom,
@@ -282,6 +301,7 @@ pub fn project(
(mount.width - inset.horizontal()).max(0.),
(mount.height - inset.vertical()).max(0.),
))
// 普通节点的 clip_children 裁到边框内侧,独立视口裁内容盒,Scroll 默认裁整个滚动盒。
} else if node.clip_children {
let border = node.border;
Some(Rect::new(
@@ -296,6 +316,7 @@ pub fn project(
None
};
if let Some(rect) = viewport {
// 本视口边界按父变换投影,不能套当前相机的 child_view,否则相机会连自己的视口框一起移动。
let rect = view.rect(rect);
let rect = [rect.x, rect.y, rect.width, rect.height];
child_clip = Some(clip.map_or(rect, |clip| intersect(clip, rect)));
@@ -309,6 +330,7 @@ pub fn project(
..
} = &node.kind
{
// 沿面板映射链限制嵌套深度,防止递归纹理装配和输入逆投影无限展开。
let mut depth = 0;
let mut ancestor = panel.clone();
while let Some(mapping) = ancestor {
@@ -317,6 +339,7 @@ pub fn project(
}
anyhow::ensure!(depth < 8, "3D UI viewport nesting exceeds 8 surfaces");
let mut child = mount.first_child;
// slots、面板尺寸和直接子出现按同序配对;缺少预期子出现时立即报错,不能把内容映射到错误面板。
for (key, size) in node.slots.iter().zip(sizes) {
let id = child.ok_or_else(|| anyhow::anyhow!("missing 3D UI root occurrence"))?;
let mapping = Arc::new(crate::scene3d::panel::Mapping {
@@ -333,6 +356,7 @@ pub fn project(
clip: mount.viewport_clip,
parent: panel.clone(),
});
// 记录待遍历面板根的新上下文;之后走到该孩子时切换纹理空间,不把外层 clip 误当纹理像素。
panels.insert(id, (mapping, *size));
child = next[&id];
}
@@ -340,6 +364,7 @@ pub fn project(
contexts.insert(mount.id, (child_view, child_clip, panel));
}
let mounts: HashMap<_, _> = frame.mounts.iter().map(|mount| (mount.id, mount)).collect();
// 按每条命令的 Mount 归属重建 view/clip,确保源绘制、默认绘制和输入都使用这一轮最终投影。
frame.command_views.clear();
frame.command_clips.clear();
anyhow::ensure!(
@@ -353,6 +378,7 @@ pub fn project(
frame.command_views.push(mount.view);
frame.command_clips.push(mount.clip);
}
// 几何、裁剪和视图信息全部就绪后才建立屏幕宽阶段索引,避免查询旧投影候选。
frame.hit_index = std::sync::Arc::new(spatial::Index::build(&frame.mounts));
Ok(())
}
@@ -360,9 +386,9 @@ pub fn project(
mod tests {
use super::*;
#[test]
/// 以实际两次点变换核对嵌套组合顺序、逆变换和矩形尺寸,并允许大相机投影平移而非套用较小世界坐标限额。
fn nested_views_compose_and_invert_without_changing_layout_coordinates() {
// Camera coordinates may be +/-1e6 at zoom 100. Their projected
// translation must not inherit the smaller world-coordinate limit.
// 相机坐标可达正负一百万,缩放100后投影平移可达一亿;不能继续使用较小的世界坐标限制。
assert!(
Transform {
zoom: 100.,
@@ -382,6 +408,7 @@ mod tests {
y: 20.0,
};
let point = Point::new(-5.0, 100.0);
// 以两次实际点变换验证组合顺序,再检查逆变换和矩形尺寸,避免只验证某一种公式写法。
let composed = inner.then(outer);
assert_eq!(composed.point(point), outer.point(inner.point(point)));
assert_eq!(composed.inverse(composed.point(point)), point);
+16 -1
View File
@@ -9,12 +9,15 @@ use std::collections::HashMap;
#[derive(Debug, Default)]
/// 有限屏幕格子和后备集合。候选筛选允许保守多取,但不能因索引预算漏掉有效命中。
pub struct Index {
// 建立索引时的 Mount 总数,用来发现明显过期的索引;数量相同不代表几何未改变。
count: usize,
// 格子坐标映射到原 mounts 切片下标,保留原始绘制顺序信息,不持有托管对象。
cells: HashMap<(i32, i32), Vec<usize>>,
// 不能安全装入网格的候选,每次查询都参与;由后续精确 contains 排除误命中。
fallback: Vec<usize>,
}
impl Index {
/// 根据当前输入构造本模块的派生结果,具体的验证与资源边界见函数内步骤。
/// 从帧几何构建 128 单位屏幕网格;大对象、投影面板和超预算项进入保守后备集合。
pub fn build(mounts: &[MountGeometry]) -> Self {
let mut result = Self {
count: mounts.len(),
@@ -22,6 +25,7 @@ impl Index {
};
let mut entries = 0;
for (index, mount) in mounts.iter().enumerate() {
// 只有可交互项、场景视口或滚动容器需要参与输入目标宽阶段,其余外观节点跳过。
if !mount.interactive
&& !mount.canvas_viewport
&& !mount.scene3d_viewport
@@ -29,16 +33,19 @@ impl Index {
{
continue;
}
// 3D 面板使用射线投影,不能把局部矩形当成屏幕 AABB 安全近似,统一交给精确阶段。
if mount.panel.is_some() {
result.fallback.push(index);
continue;
}
// 普通二维节点取两对角点并应用视图变换,再排序上下界,兼容坐标方向变化。
let a = Point::new(mount.x, mount.y);
let b = Point::new(mount.x + mount.width, mount.y + mount.height);
let a = mount.view.map_or(a, |view| view.point(a));
let b = mount.view.map_or(b, |view| view.point(b));
let (mut x0, mut y0, mut x1, mut y1) =
(a.x.min(b.x), a.y.min(b.y), a.x.max(b.x), a.y.max(b.y));
// 先与有效裁剪求交,缩小入网范围;完全不可见的矩形不需要成为候选。
if let Some([x, y, w, h]) = mount.clip {
x0 = x0.max(x);
y0 = y0.max(y);
@@ -48,6 +55,7 @@ impl Index {
if x1 < x0 || y1 < y0 {
continue;
}
// 极端或非有限坐标不做网格展开,转后备集合;不能因转换溢出而漏掉待精确检查的目标。
if ![x0, y0, x1, y1]
.iter()
.all(|value| value.is_finite() && value.abs() < 1e12)
@@ -56,8 +64,10 @@ impl Index {
continue;
}
let (left, top, right, bottom) = (cell(x0), cell(y0), cell(x1), cell(y1));
// 用 i64 计算格子跨度和饱和乘积,避免极大矩形在预算检查前发生算术溢出。
let cells = (i64::from(right) - i64::from(left) + 1)
.saturating_mul(i64::from(bottom) - i64::from(top) + 1);
// 单项最多展开 256 格,全索引最多 65536 项格子引用;超预算只降级,不丢弃目标。
if cells > 256 || entries + cells > 65_536 {
result.fallback.push(index);
continue;
@@ -73,6 +83,7 @@ impl Index {
}
/// 返回当前网格格子与后备集合中的候选,去重并恢复逆绘制顺序。
pub fn candidates(&self, point: Point, count: usize) -> Vec<usize> {
// 索引总数与当前帧不一致时,下标集合不再可靠;直接返回整帧逆序候选。
if self.count != count {
return (0..count).rev().collect();
}
@@ -80,6 +91,7 @@ impl Index {
if let Some(items) = self.cells.get(&(cell(point.x), cell(point.y))) {
output.extend(items);
}
// 按下标降序还原从前景到背景的绘制顺序;去重确保同一出现不会重复执行 hitTest。
output.sort_unstable_by(|a, b| b.cmp(a));
output.dedup();
output
@@ -87,6 +99,7 @@ impl Index {
}
/// 把屏幕坐标映射到有界整数网格坐标,处理负方向与极端数值。
fn cell(value: f32) -> i32 {
// 每格 128 个屏幕单位;floor 让 -1 属于负格而不是零格,再限制到整数表示范围。
(value / 128.)
.floor()
.clamp(i32::MIN as f32, i32::MAX as f32) as i32
@@ -96,6 +109,7 @@ fn cell(value: f32) -> i32 {
mod tests {
use super::*;
#[test]
/// 200个分散节点只返回局部网格候选;覆盖海量格的巨大前景节点进入后备集合后仍按前景顺序参与精确命中。
fn screen_grid_limits_candidates_and_keeps_huge_rectangles_hittable() {
let (_, document) = crate::endor_host::ReplSession::load(
"page=Page()\npage.render(Button(\"hit\"))",
@@ -123,6 +137,7 @@ mod tests {
}
let index = Index::build(&mounts);
assert_eq!(index.candidates(Point::new(5., 5.), mounts.len()), vec![0]);
// 把最前景节点扩大到覆盖海量格子,验证其进入后备集合后仍排在普通候选之前且可精确命中。
mounts[199].x = -1_000_000.;
mounts[199].width = 2_000_000.;
let index = Index::build(&mounts);