diff --git a/src/runtime/endor_host/tests.rs b/src/runtime/endor_host/tests.rs index d80989b..9e10a88 100644 --- a/src/runtime/endor_host/tests.rs +++ b/src/runtime/endor_host/tests.rs @@ -4921,6 +4921,7 @@ fn cross_alignment_is_live_and_specific_to_each_parent_occurrence() { /// 源 arrange 主动把第一个子项 y 改为 7,后续原生 crossAlign 不能覆盖源给定位置。 /// 另一子项比父交叉轴更宽时按起点溢出,center 不应产生负起点。 fn cross_alignment_preserves_source_placements_and_starts_overflow() { + // 一个源 Row.arrange 显式指定 y=7,另一个源 Column.measure 只分配宽 10;分别覆盖源位置优先及自然子项溢出。 let (mut session, initial) = ReplSession::load(r#" class Placed: Row { function arrange(self: Placed, mount: Mount, geometry: Bounds): Arrangement { @@ -4941,7 +4942,9 @@ fn cross_alignment_preserves_source_placements_and_starts_overflow() { page = Page() page.render(Column(0, 0, placed, small)) "#, "app.main", 295, 1).unwrap(); + // 通过正常加载收敛并验证文档,以下检查读取最终 Mount 坐标而非临时 Arrangement。 initial.validate().unwrap(); + // 即使父 crossAlign=end,源 arrange 已给定的 y=7 也不能被后续原生对齐覆盖。 assert_eq!( session .execute("first.mounts().at(0).bounds().y", "app.main") @@ -4949,6 +4952,7 @@ fn cross_alignment_preserves_source_placements_and_starts_overflow() { .value, "7" ); + // 子宽 40 大于父宽 10,center 应从起点溢出,不能用负剩余空间计算出负偏移。 assert_eq!( session .execute("second.mounts().at(0).bounds().x", "app.main") @@ -4962,6 +4966,7 @@ fn cross_alignment_preserves_source_placements_and_starts_overflow() { /// 带不对称 margin 的共享子项分别参与有限 flex Row 和自然尺寸 Row。 /// 检查定位、交叉轴居中、剩余宽度与容器固有尺寸;增加右 margin 同时挤窄 flex 兄弟并扩大自然父宽度。 fn margins_participate_in_intrinsic_size_alignment_and_flex_allocation() { + // 同一 first 带左右 3/7、上下 5/15 的 margin,分别参与有限分配与自然尺寸两种父布局。 let (mut session, initial) = ReplSession::load(r#" class Wide: Row { function measure(self: Wide, mount: Mount, constraints: Constraints): MeasureResult { return MeasureResult(200, 100) } @@ -4979,7 +4984,10 @@ fn margins_participate_in_intrinsic_size_alignment_and_flex_allocation() { page = Page() page.render(Column(0, 0, row, intrinsic)) "#, "app.main", 296, 1).unwrap(); + // 先验证文档,随后比较位置、兄弟分配和自然父尺寸,覆盖 margin 进入盒模型的各处。 initial.validate().unwrap(); + // 有限 Row 的首项 x=10+3,后项 x=10+3+20+7+10;剩余宽 140 给 flex 项。 + // 自然 Row 宽为 20 padding+30 首项外宽+10 gap+30 后项,高为 20 padding+40 最大外高。 for (expression, expected) in [ ("first.mounts().at(0).bounds().x", "13"), ("first.mounts().at(0).bounds().y", "35"), @@ -4988,15 +4996,18 @@ fn margins_participate_in_intrinsic_size_alignment_and_flex_allocation() { ("intrinsic.mounts().at(0).bounds().width", "90"), ("intrinsic.mounts().at(0).bounds().height", "60"), ] { + // 逐表达式核对真实几何,错误信息保留表达式以区分定位与尺寸求解问题。 assert_eq!( session.execute(expression, "app.main").unwrap().value, expected, "{expression}" ); } + // 将共享 first 的右 margin 增加 10,两个出现位置都需刷新,但有限父和自然父的变化方向不同。 session .execute("first.marginRight = 17", "app.main") .unwrap(); + // 有限 Row 总宽不变,flex 兄弟让出 10;自然 Row 则增加 10,证明 margin 不是只影响绘制偏移。 assert_eq!( session .execute("second.mounts().at(0).bounds().width", "app.main") @@ -5017,6 +5028,7 @@ fn margins_participate_in_intrinsic_size_alignment_and_flex_allocation() { /// 在固定尺寸 Overlay 内嵌带边框/不对称 padding 的 Column,子项还有 margin。 /// 比较三层绝对坐标与边框绘制命令,再动态改变 min/max,验证对齐与内容偏移使用同一盒模型。 fn nested_overlay_uses_border_boxes_and_asymmetric_content_insets() { + // 固定 Overlay 中放置固定 Column,Column 有非对称 padding/border,子项另有 margin,构造三层偏移。 let (mut session, initial) = ReplSession::load( r##" child = RectBlock(20, 10) @@ -5043,7 +5055,9 @@ fn nested_overlay_uses_border_boxes_and_asymmetric_content_insets() { 1, ) .unwrap(); + // 完成布局后逐层查几何,让容器对齐、内容内缩和子项 margin 使用同一坐标基准。 initial.validate().unwrap(); + // Column 的外框在 (50,70),子项 x=50+3+11+5=69、y=70+2+7+4=83。 for (expression, expected) in [ ("overlay.mounts().at(0).bounds().width", "300"), ("column.mounts().at(0).bounds().x", "50"), @@ -5052,13 +5066,16 @@ fn nested_overlay_uses_border_boxes_and_asymmetric_content_insets() { ("child.mounts().at(0).bounds().x", "69"), ("child.mounts().at(0).bounds().y", "83"), ] { + // 核对边框盒尺寸和绝对坐标,避免只看像素颜色而遗漏布局数值偏差。 assert_eq!( session.execute(expression, "app.main").unwrap().value, expected, "{expression}" ); } + // 红色左边框必须在 Column 外框左缘生成宽 3、高 120 的命令,不能画到内容起点。 assert!(initial.frame.commands.iter().any(|command| matches!(command, RenderCommand::RoundedRect { x, y, width, height, color, .. } if *x == 50.0 && *y == 70.0 && *width == 3.0 && *height == 120.0 && color == "#FF0000"))); + // 同一 Column 的显式尺寸还要受 maxWidth/minHeight 夹取,字段更新后应变成 160×140。 session .execute("column.maxWidth = 160\ncolumn.minHeight = 140", "app.main") .unwrap(); @@ -5082,6 +5099,7 @@ fn nested_overlay_uses_border_boxes_and_asymmetric_content_insets() { /// 文字 boxWidth=fill 在有限父宽中获得整个边框盒,真正换行宽度再扣左右 padding。 /// 另构造无界 Column 主轴上的 fill 高度,应明确拒绝无法定义的有限分配。 fn fill_wraps_text_inside_finite_column_and_rejects_unbounded_axis() { + // 有限宽 160 的 Column 为 fill 文字分配边框盒,文字自身 padding 再减少实际排字宽度。 let (mut session, initial) = ReplSession::load(r#" text = TextBlock("Text wrapping follows the finite border box rather than the original unbounded column width.") text.boxWidth = "fill" @@ -5092,6 +5110,7 @@ fn fill_wraps_text_inside_finite_column_and_rejects_unbounded_axis() { page = Page() page.render(column) "#, "app.main", 298, 1).unwrap(); + // 确认文档有效,并通过 Mount 查询核对 fill 后的外框宽度恰为 160。 initial.validate().unwrap(); assert_eq!( session @@ -5100,7 +5119,9 @@ fn fill_wraps_text_inside_finite_column_and_rejects_unbounded_axis() { .value, "160" ); + // 排字起点右移 8,wrap 宽为 160−8−12=140;不能把外框宽直接当作文字可用宽。 assert!(initial.frame.commands.iter().any(|command| matches!(command, RenderCommand::Text { x, wrap_bounds: Some([width, _]), .. } if *x == 8.0 && *width == 140.0))); + // 另一程序让自然高度 Column 中的子项 boxHeight=fill;主轴无有限分配,无法定义填满目标。 let error = ReplSession::load( r#" rect = RectBlock(10, 10) @@ -5114,6 +5135,7 @@ fn fill_wraps_text_inside_finite_column_and_rejects_unbounded_axis() { ) .err() .expect("unbounded fill must fail"); + // 错误应明确说明 fill 缺少有限父分配,不能以任意其他加载失败替代该检查。 assert!( format!("{error:#}").contains("fill requires a finite parent allocation"), "{error:#}" @@ -5124,6 +5146,7 @@ fn fill_wraps_text_inside_finite_column_and_rejects_unbounded_axis() { /// 让子按钮超出带左边框且 overflow=clip 的固定 Row。 /// 子 Mount 保留原几何,但 clip 仅覆盖父内容区域;命中在原按钮矩形内也应因裁剪而失败。 fn clipping_a_box_limits_descendant_paint_and_hit_geometry() { + // 固定 Row 宽 60 且左边框宽 2,前项先占宽 100,后按钮保留位于父内容区之外的原几何。 let (_, initial) = ReplSession::load(r#" class Overflow: RectBlock { function measure(self: Overflow, mount: Mount, constraints: Constraints): MeasureResult { return MeasureResult(100, 20) } @@ -5138,15 +5161,19 @@ fn clipping_a_box_limits_descendant_paint_and_hit_geometry() { page = Page() page.render(row) "#, "app.main", 300, 1).unwrap(); + // 确认发布结构合法,随后从完整帧定位唯一可交互按钮。 initial.validate().unwrap(); + // 按 interactive 找后按钮;裁剪不能通过删除 Mount 或篡改其原位置来实现。 let child = initial .frame .mounts .iter() .find(|mount| mount.interactive) .unwrap(); + // 有效裁剪只覆盖扣去边框的父内容区 [2,0,58,40],子项 x 仍应在 100 之外。 assert_eq!(child.clip, Some([2.0, 0.0, 58.0, 40.0])); assert!(child.x >= 100.0); + // 选择子矩形内部点调用整帧命中测试,仍必须因父裁剪而找不到目标。 assert!( initial .frame @@ -5159,6 +5186,8 @@ fn clipping_a_box_limits_descendant_paint_and_hit_geometry() { /// 两个 fill 子项分享扣去 margin/gap/固定项后的主轴空间,其中一项触及 maxWidth 后重新分配。 /// 交叉轴 stretch 仍受 maxHeight 和 alignSelf 限制;增大父宽后首项吸收新增空间。 fn main_axis_fill_shares_remaining_space_and_stretch_respects_box_limits() { + // 父宽 240 扣 padding 20、gap 10、首项 margin 5 和固定项 40,留给两项 fill 的总宽为 165。 + // 第二项 maxWidth=50 后首项吸收剩余 115;交叉轴 stretch 另受 maxHeight/alignSelf 限制。 let (mut session, initial) = ReplSession::load( r#" first = RectBlock(10, 10) @@ -5182,7 +5211,9 @@ fn main_axis_fill_shares_remaining_space_and_stretch_respects_box_limits() { 1, ) .unwrap(); + // 先验证整体文档,再独立检查主轴分配、交叉轴限制和固定项居中位置。 initial.validate().unwrap(); + // 首项高度被 maxHeight 夹为 30,第二项填满内容高 60;固定项显式 center 得到 y=30。 for (expression, expected) in [ ("first.mounts().at(0).bounds().width", "115"), ("second.mounts().at(0).bounds().width", "50"), @@ -5190,12 +5221,14 @@ fn main_axis_fill_shares_remaining_space_and_stretch_respects_box_limits() { ("second.mounts().at(0).bounds().height", "60"), ("fixed.mounts().at(0).bounds().y", "30"), ] { + // 从各自 Mount 读取最终分配,不能把业务自然尺寸当作 fill/stretch 的结果。 assert_eq!( session.execute(expression, "app.main").unwrap().value, expected, "{expression}" ); } + // 父宽增加 40,第二项仍卡在最大宽 50,新增空间应全部给首项,得到 155。 session.execute("row.boxWidth = 280", "app.main").unwrap(); assert_eq!( session @@ -5210,6 +5243,7 @@ fn main_axis_fill_shares_remaining_space_and_stretch_respects_box_limits() { /// 通过真实 VM 加载盒布局示例并验证完整文档。 /// 共享文字有两个 Mount,父盒宽度不同产生不同分配,防止示例只在说明文档中成立。 fn box_layout_example_runs_through_the_real_source_pipeline() { + // 直接加载仓库中的盒布局示例,以真实 VM、桥接布局和文档发布检验示例可执行性。 let (mut session, initial) = ReplSession::load( include_str!("../../../examples/box-layout.endor"), "app.main", @@ -5217,6 +5251,7 @@ fn box_layout_example_runs_through_the_real_source_pipeline() { 1, ) .unwrap(); + // 共享文字必须有两个 Mount,才能比较不同父盒约束下的独立分配。 initial.validate().unwrap(); assert_eq!( session @@ -5225,12 +5260,14 @@ fn box_layout_example_runs_through_the_real_source_pipeline() { .value, "2" ); + // 取得第一个出现的最终宽度并转为数值,避免字符串字典序比较。 let left = session .execute("shared.mounts().at(0).bounds().width", "app.main") .unwrap() .value .parse::() .unwrap(); + // 第二个出现单独读宽,较窄父盒应得到更小分配,不能共享第一次测量结果。 let right = session .execute("shared.mounts().at(1).bounds().width", "app.main") .unwrap() @@ -5244,6 +5281,7 @@ fn box_layout_example_runs_through_the_real_source_pipeline() { /// 固定 Overlay 按内容高度拉伸子项,再受 margin/maxHeight 限制得到 50。 /// 改为显式 boxHeight 后使用 15,证明显式尺寸优先于 stretch,覆盖层不按线性子项重排。 fn overlay_stretch_allocates_each_occurrence_without_reflowing_its_siblings() { + // Overlay 高 80 扣上下 padding 10 和 child 顶 margin 3,stretch 原可分配 67,再受 maxHeight=50 限制。 let (mut session, initial) = ReplSession::load( r#" child = RectBlock(20, 10) @@ -5261,6 +5299,7 @@ fn overlay_stretch_allocates_each_occurrence_without_reflowing_its_siblings() { 1, ) .unwrap(); + // 文档有效后核对 child 高 50 且 y=5+3=8,验证 margin 在拉伸与定位中一致使用。 initial.validate().unwrap(); assert_eq!( session @@ -5276,6 +5315,7 @@ fn overlay_stretch_allocates_each_occurrence_without_reflowing_its_siblings() { .value, "8" ); + // 改为显式高度 15 后应优先采用该值,父 stretch 不得再次覆盖它。 session.execute("child.boxHeight = 15", "app.main").unwrap(); assert_eq!( session @@ -5290,6 +5330,7 @@ fn overlay_stretch_allocates_each_occurrence_without_reflowing_its_siblings() { /// 两个有限视口共享同一 Scene2D,默认相机独立,出现位置各有变换和裁剪。 /// 点击先经变换命中;只改首个相机不测量业务对象,显式共享 camera 后两边才同步缩放。 fn two_canvas_viewports_share_a_scene_with_independent_explicit_cameras() { + // 两个有限 CanvasViewport 共享同一 Scene2D/button,初始只修改 first 的默认相机。 let (mut session, initial) = ReplSession::load( r#" hits = ui.state(0) @@ -5310,6 +5351,7 @@ fn two_canvas_viewports_share_a_scene_with_independent_explicit_cameras() { 1, ) .unwrap(); + // 共享业务按钮应拥有两个 Mount;相机和裁剪属于各出现上下文,而非按钮自身。 initial.validate().unwrap(); assert_eq!( session @@ -5318,19 +5360,24 @@ fn two_canvas_viewports_share_a_scene_with_independent_explicit_cameras() { .value, "2" ); + // 按文档顺序收集两处交互 Mount,分别核对缩放变换与左右面板裁剪。 let buttons: Vec<_> = initial .frame .mounts .iter() .filter(|mount| mount.interactive) .collect(); + // 首面板 zoom=2,第二面板默认相机无额外变换;两者 clip 分别位于 x=0 和 x=220。 assert_eq!(buttons.len(), 2); assert_eq!(buttons[0].view.unwrap().zoom, 2.0); assert!(buttons[1].view.is_none()); assert_eq!(buttons[0].clip, Some([0.0, 0.0, 200.0, 100.0])); assert_eq!(buttons[1].clip, Some([220.0, 0.0, 200.0, 100.0])); + // 保存首个出现身份,后续改相机应保留该 ID。 let first_id = buttons[0].id; + // 选取经首相机投影后位于按钮内的屏幕坐标,命中必须先还原场景位置。 let point = [45.0, 45.0]; + // 先核对整帧命中选择,再沿原生派发路径发送同一坐标,确保几何与事件路由一致。 assert_eq!( initial .frame @@ -5339,6 +5386,7 @@ fn two_canvas_viewports_share_a_scene_with_independent_explicit_cameras() { .id, first_id ); + // 有效文档版本下点击首个出现,只有共享业务计数递增一次。 session .dispatch(&crate::events::Input { window: crate::window::MAIN_WINDOW, @@ -5357,22 +5405,27 @@ fn two_canvas_viewports_share_a_scene_with_independent_explicit_cameras() { session.execute("hits.value", "app.main").unwrap().value, "1" ); + // 只修改 first.camera 平移/缩放,第二面板不能被共享场景对象带着改变。 let changed = session .execute("first.camera.x = -40\nfirst.camera.zoom = 1", "app.main") .unwrap() .document .unwrap(); + // 重新发布后的交互 Mount 仍按各面板独立投影,几何结构应有效。 changed.validate().unwrap(); + // 从新文档重新取出现位置,不能借用旧帧中的 view 判断更新是否生效。 let buttons: Vec<_> = changed .frame .mounts .iter() .filter(|mount| mount.interactive) .collect(); + // 首个 Mount 身份保持、平移变为 40;第二个仍无额外变换,业务测量数为零。 assert_eq!(buttons[0].id, first_id); assert_eq!(buttons[0].view.unwrap().x, 40.0); assert!(buttons[1].view.is_none()); assert_eq!(source_measure_stat(&mut session, "measured"), 0); + // 显式把 second.camera 指向 first.camera 后再缩放,此时两个面板才应共享相机状态。 let shared = session .execute( "second.camera = first.camera\nfirst.camera.zoom = 2", @@ -5381,6 +5434,7 @@ fn two_canvas_viewports_share_a_scene_with_independent_explicit_cameras() { .unwrap() .document .unwrap(); + // 验证新帧并检查所有交互出现都采用 zoom=2,区分显式共享和初始默认独立。 shared.validate().unwrap(); assert!( shared @@ -5396,6 +5450,7 @@ fn two_canvas_viewports_share_a_scene_with_independent_explicit_cameras() { /// 嵌套二维相机的缩放相乘、平移复合,检查最终变换和相交裁剪。 /// 手势只驱动内层相机,外层不动;最后软件绘制采样确认固定 HUD 与变换后内容均位于预期像素。 fn nested_canvas_projects_pixels_and_hits_while_overlay_ui_stays_fixed() { + // 内相机缩放 0.5、外相机缩放 2,嵌套面板位置参与复合变换;HUD 是外部 Overlay 的独立兄弟。 let (mut session, initial) = ReplSession::load( r##" button = Button("nested") @@ -5418,13 +5473,16 @@ fn nested_canvas_projects_pixels_and_hits_while_overlay_ui_stays_fixed() { 1, ) .unwrap(); + // 先确认发布结构,再定位嵌套按钮,检查复合投影及可见区域。 initial.validate().unwrap(); + // 唯一可交互节点来自最内 Scene2D,携带两层相机叠加后的有效变换。 let button = initial .frame .mounts .iter() .find(|mount| mount.interactive) .unwrap(); + // 最终 zoom=1,Transform 按 point×zoom+(x,y) 投影,平移为 (20,20);clip 在视图坐标中比较。 assert_eq!( button.view.unwrap(), crate::viewport::Transform { @@ -5434,9 +5492,12 @@ fn nested_canvas_projects_pixels_and_hits_while_overlay_ui_stays_fixed() { } ); assert_eq!(button.clip, Some([40.0, 40.0, 160.0, 120.0])); + // 屏幕点 (55,55) 同时用于交互命中和选取最内层可控相机。 let point = crate::geometry::Point::new(55.0, 55.0); assert_eq!(initial.frame.hit_test(point).unwrap().id, button.id); + // camera_at 应优先命中内层视口,平移手势不能误控制外层相机。 let inner_id = initial.frame.camera_at(point).unwrap().id; + // 构造针对内层视口的 viewport-pan,delta 通过宿主相机手势入口消费。 let input = crate::events::Input { window: 1, session: initial.frame.session, @@ -5449,6 +5510,7 @@ fn nested_canvas_projects_pixels_and_hits_while_overlay_ui_stays_fixed() { tab_drop: None, screen_position: None, }; + // 派发后内相机 x 应变为 10,外相机 x 仍为零,验证手势目标选择。 session.dispatch(&input).unwrap(); assert_eq!( session.execute("inner.camera.x", "app.main").unwrap().value, @@ -5458,12 +5520,15 @@ fn nested_canvas_projects_pixels_and_hits_while_overlay_ui_stays_fixed() { session.execute("outer.camera.x", "app.main").unwrap().value, "0" ); + // 显式使 HUD paint 失效以取得最新完整文档,再检验真实像素而非仅投影字段。 let document = session .execute("hud.invalidate(\"paint\")", "app.main") .unwrap() .document .unwrap(); + // 分配 200×200 软件输出缓冲,1x DPI 下采样点与逻辑坐标一致。 let mut pixels = vec![0; 200 * 200]; + // 执行真实光栅化以核对叠加层与变换后内容,补足仅检查投影字段无法覆盖的绘制路径。 crate::software_renderer::SoftwareRenderer::render( &document.display_list(1.0).unwrap(), &mut pixels, @@ -5471,6 +5536,7 @@ fn nested_canvas_projects_pixels_and_hits_while_overlay_ui_stays_fixed() { 200, ) .unwrap(); + // HUD 原点蓝色保持固定;场景采样与远处背景不同,证明平移后的内容确实被绘出。 assert_eq!(pixels[5 * 200 + 5], 0x0000FF); assert_ne!(pixels[55 * 200 + 45], pixels[190 * 200 + 190]); } @@ -5479,6 +5545,7 @@ fn nested_canvas_projects_pixels_and_hits_while_overlay_ui_stays_fixed() { /// 在负世界 x 处放红矩形,经相机平移和二倍缩放映射到有限视口。 /// 实际像素需显示固定蓝色覆盖层、可见红块和视口外背景,检验命令投影与裁剪最终进入光栅化。 fn canvas_world_paint_is_zoomed_and_clipped_in_the_software_renderer() { + // 红矩形位于负世界 x,经相机平移与二倍缩放进入 50×50 视口;蓝色 HUD 不随相机变化。 let (_, initial) = ReplSession::load( r##" rect = RectBlock(20, 20, 0, "#FF0000") @@ -5495,8 +5562,11 @@ fn canvas_world_paint_is_zoomed_and_clipped_in_the_software_renderer() { 1, ) .unwrap(); + // 文档通过结构验证后再做像素测试,区分投影数据有效与实际绘制正确。 initial.validate().unwrap(); + // 输出 80×80,大于有限视口,留出明确的视口外背景采样点。 let mut pixels = vec![0; 80 * 80]; + // 用 1x 显示列表运行软件绘制,包含世界投影、面板裁剪和 Overlay 绘制顺序。 crate::software_renderer::SoftwareRenderer::render( &initial.display_list(1.0).unwrap(), &mut pixels, @@ -5504,6 +5574,7 @@ fn canvas_world_paint_is_zoomed_and_clipped_in_the_software_renderer() { 80, ) .unwrap(); + // 依次核对固定蓝层、可见红块、视口外背景以及矩形右侧背景,捕获缩放或裁剪遗漏。 assert_eq!(pixels[5 * 80 + 5], 0x0000FF); assert_eq!(pixels[25 * 80 + 5], 0xFF0000); assert_eq!(pixels[55 * 80 + 5], pixels[79 * 80 + 79]); @@ -5514,6 +5585,7 @@ fn canvas_world_paint_is_zoomed_and_clipped_in_the_software_renderer() { /// 加载场景视口示例并确认共享按钮出现两次。 /// 再实际构造 ScrollView,检查它保持 ScrollBlock 名义类型兼容,而非只在文本说明中存在的别名。 fn scene_viewport_example_and_scroll_view_alias_run_as_real_source() { + // 直接执行场景视口示例,确认共享 increment 按钮在两个视口中各有一个出现。 let (mut session, initial) = ReplSession::load( include_str!("../../../examples/scene-viewports.endor"), "app.main", @@ -5521,6 +5593,7 @@ fn scene_viewport_example_and_scroll_view_alias_run_as_real_source() { 1, ) .unwrap(); + // 先检查示例文档和出现数量,再单独验证 ScrollView 的实际构造与名义类型兼容。 initial.validate().unwrap(); assert_eq!( session @@ -5529,12 +5602,14 @@ fn scene_viewport_example_and_scroll_view_alias_run_as_real_source() { .value, "2" ); + // 源码构造 ScrollView 实例并保存在全局,不只是检查名字可查询或文档宣称存在别名。 session .execute( "testScroll = ScrollView(100, 60, Row(0, 0, TextBlock(\"scroll\")))", "app.main", ) .unwrap(); + // 新实例仍应满足 ScrollBlock 名义类型,保证兼容原有滚动 API。 assert_eq!( session .execute("ui.isInstance(testScroll, ScrollBlock)", "app.main") @@ -5548,6 +5623,7 @@ fn scene_viewport_example_and_scroll_view_alias_run_as_real_source() { /// 场景内容在负坐标,按当前 Mount 的有限尺寸 fitView。 /// 比较相机 zoom/pan 与矩形投影后的 48px 留白,验证适配的是场景边界而非业务对象原始正坐标假设。 fn fit_view_uses_finite_scene_bounds_and_this_mounts_size() { + // 场景矩形跨负坐标,视口固定为 296×196,测试 fitView 不假设世界内容从原点向正方向展开。 let (mut session, initial) = ReplSession::load( r#" rect = RectBlock(100, 50) @@ -5562,29 +5638,36 @@ fn fit_view_uses_finite_scene_bounds_and_this_mounts_size() { 1, ) .unwrap(); + // 基线文档有效后,针对视口的具体 Mount 调用 fitView,使用该出现位置的有限尺寸。 initial.validate().unwrap(); + // fitView 更新相机并发布新文档,后续投影必须从新帧取值。 let document = session .execute("view.mounts().at(0).fitView()", "app.main") .unwrap() .document .unwrap(); + // 验证适配后的完整文档,再比较相机缩放和平移结果。 document.validate().unwrap(); + // 扣两边各 48 的留白后,宽约束允许 zoom=2;x/y 还需补偿负世界边界以居中放置内容。 for (expression, expected) in [ ("view.camera.zoom", "2"), ("view.camera.x", "-124"), ("view.camera.y", "-49"), ] { + // 直接读取源相机状态,排除只在绘制命令上临时移动而未更新业务相机的实现。 assert_eq!( session.execute(expression, "app.main").unwrap().value, expected ); } + // 从适配后的帧找场景矩形,其逻辑几何保持 100×50,仅视图变换改变。 let rect = document .frame .mounts .iter() .find(|mount| mount.width == 100.0 && mount.height == 50.0) .unwrap(); + // 用出现位置附带的 view 投影矩形左上角,应落在 (48,48),与相机字段断言互相核对。 let screen = rect .view .unwrap() @@ -5596,6 +5679,7 @@ fn fit_view_uses_finite_scene_bounds_and_this_mounts_size() { /// 同一场景用透视和正交相机各显示一次,前景蓝盒应遮住后景红盒。 /// 比较拾取距离、交点和实际中心像素;移动前景并只修改透视相机后,两视图露出后景且相机 z 保持独立。 fn real_scene3d_renders_depth_with_independent_perspective_and_orthographic_cameras() { + // 透视与正交视口共享前蓝后红两个盒子,ambient=1 便于用准确材质色比较遮挡像素。 let (mut session, initial) = ReplSession::load( r##" back = Box3D(2, 2, 2, "#FF0000") @@ -5615,28 +5699,36 @@ fn real_scene3d_renders_depth_with_independent_perspective_and_orthographic_came 1, ) .unwrap(); + // 确认首帧合法,再从文档命令中取两套实际三维视图,不重新构造近似渲染数据。 initial.validate().unwrap(); + // 只保留 Scene3D 命令里的 view,按左右视口顺序用于相机和射线断言。 let commands: Vec<_> = initial .frame .commands .iter() .filter_map(|command| { + // 三维命令携带渲染/拾取使用的同一场景快照,其他 UI 命令不参与本组比较。 if let RenderCommand::Scene3D { view, .. } = command { Some(view) } else { + // 跳过容器等非三维命令,避免把显示列表全部命令数误当作视口数量。 None } }) .collect(); assert_eq!(commands.len(), 2); + // 透视视口中心射线应先击中前盒 z=2 的正面,距离相机 3,不能依场景子项次序选择后盒。 let hit = commands[0].pick(0.5, 0.5, 1.2).unwrap(); assert!((hit.distance - 3.0).abs() < 1e-5); assert_eq!(hit.point, crate::scene3d::math::Vec3::new(0., 0., 2.)); + // 第二个视图必须保留显式正交投影 height=4,不能因共享 scene 误用透视相机。 assert!(matches!( commands[1].camera.projection, crate::scene3d::math::Projection::Orthographic { height: 4.0 } )); + // 输出 250×100,覆盖两个宽 120、间距 10 的视口,左右中心点分别位于 x=60/190。 let mut pixels = vec![0; 250 * 100]; + // 首帧实际光栅化验证深度遮挡,两视口中心均应显示前盒蓝色。 crate::software_renderer::SoftwareRenderer::render( &initial.display_list(1.).unwrap(), &mut pixels, @@ -5646,25 +5738,31 @@ fn real_scene3d_renders_depth_with_independent_perspective_and_orthographic_came .unwrap(); assert_eq!(pixels[50 * 250 + 60], 0x0000FF); assert_eq!(pixels[50 * 250 + 190], 0x0000FF); + // 把前盒移出中心,同时只把透视相机 z 改为 8;正交相机应保持初始 z=5。 let updated = session .execute("front.x=10\nperspective.camera.z=8", "app.main") .unwrap() .document .unwrap(); + // 新文档必须有效,再检查命令快照里的两台相机位置。 updated.validate().unwrap(); + // 从更新后的 Scene3D 命令收集 z,验证共享的是场景而非两个默认相机对象。 let cameras: Vec<_> = updated .frame .commands .iter() .filter_map(|command| { + // 仅三维视图提供 camera.position,仍按发布顺序比较左右相机。 if let RenderCommand::Scene3D { view, .. } = command { Some(view.camera.position.z) } else { + // 非场景命令不提供相机数据,不参与预期的 [8,5] 列表。 None } }) .collect(); assert_eq!(cameras, vec![8., 5.]); + // 复用像素缓冲绘制新帧;两个中心都应露出后盒红色,不能保留上一帧深度或颜色。 crate::software_renderer::SoftwareRenderer::render( &updated.display_list(1.).unwrap(), &mut pixels, @@ -5680,6 +5778,7 @@ fn real_scene3d_renders_depth_with_independent_perspective_and_orthographic_came /// 先通过 Mount.pick3D 查询中心交点与真实 mesh 材质,再从原生输入派发同位置 click。 /// 回调写 event.hit.mesh.color 后业务对象及最终像素都变绿,证明拾取结果保留正确托管业务身份。 fn ray_pick_returns_managed_mesh_and_native_pointer_event_updates_its_material() { + // 源 Actions 回调通过 event.hit.mesh 改色,验证拾取结果能映射回原托管业务 Mesh。 let (mut session, initial) = ReplSession::load( r##" class Actions { @@ -5699,6 +5798,7 @@ fn ray_pick_returns_managed_mesh_and_native_pointer_event_updates_its_material() 1, ) .unwrap(); + // 先在源 API 查询中心拾取:交点 z=1 且材质为红,建立原生输入前的拾取基线。 initial.validate().unwrap(); assert_eq!( session @@ -5714,17 +5814,20 @@ fn ray_pick_returns_managed_mesh_and_native_pointer_event_updates_its_material() .value, "\"#FF0000\"" ); + // 显式请求重绘取得最新帧,确保随后原生事件携带当前布局版本。 let frame = session .execute("view.invalidate(\"paint\")", "app.main") .unwrap() .document .unwrap() .frame; + // 以 scene3d_viewport 标记选实际三维视口 Mount,而非场景内部网格或普通按钮。 let mount = frame .mounts .iter() .find(|mount| mount.scene3d_viewport) .unwrap(); + // 原生 click 的按下/释放均在视口中心;宿主应附带对应 Hit3D 交给源回调。 let updated = session .dispatch(&crate::events::Input { window: 1, @@ -5741,11 +5844,14 @@ fn ray_pick_returns_managed_mesh_and_native_pointer_event_updates_its_material() .unwrap() .document .unwrap(); + // 从原全局 mesh 读到绿色,证明 event.hit.mesh 没有指向脱离业务对象的临时副本。 assert_eq!( session.execute("mesh.color", "app.main").unwrap().value, "\"#00FF00\"" ); + // 再准备 100×100 软件像素缓冲,检验业务材质改动确实进入绘制依赖与最终渲染。 let mut pixels = vec![0; 100 * 100]; + // 绘制派发返回的新文档,中心像素必须为绿色,与源字段查询结果一致。 crate::software_renderer::SoftwareRenderer::render( &updated.display_list(1.).unwrap(), &mut pixels, @@ -5760,6 +5866,7 @@ fn ray_pick_returns_managed_mesh_and_native_pointer_event_updates_its_material() /// 运行内置三维示例及其旋转动作,再替换为源构造的自定义三角网格。 /// 另检查 Group3D 自循环和越界三角索引的明确错误,非法场景不能进入发布。 fn scene3d_example_custom_geometry_and_cycle_diagnostics_use_real_source() { + // 执行仓库的三维示例,用源 Actions.rotate 验证实际交互业务可更新场景。 let (mut session, document) = ReplSession::load( include_str!("../../../examples/scene3d.endor"), "app.main", @@ -5767,17 +5874,20 @@ fn scene3d_example_custom_geometry_and_cycle_diagnostics_use_real_source() { 1, ) .unwrap(); + // 首帧结构必须有效,动作执行后 cube.rotationY 应更新为 40。 document.validate().unwrap(); session.execute("actions.rotate()", "app.main").unwrap(); assert_eq!( session.execute("cube.rotationY", "app.main").unwrap().value, "40" ); + // 在原会话替换为三个顶点、一个三角面的自定义 Geometry3D,要求产生有效新文档。 session.execute(r##" geometry=Geometry3D(ObjectList(Vec3(-1,-1,0),Vec3(1,-1,0),Vec3(0,1,0)),ObjectList(Triangle3D(0,1,2))) custom=Mesh3D(geometry,"#112233") scene.children=ObjectList(custom) "##,"app.main").unwrap().document.unwrap().validate().unwrap(); + // 独立程序令 Group3D.children 包含自己,必须明确拒绝场景图循环而非无限遍历。 let error = ReplSession::load( r##" group=Group3D() @@ -5792,10 +5902,12 @@ fn scene3d_example_custom_geometry_and_cycle_diagnostics_use_real_source() { ) .err() .unwrap(); + // 检查完整错误链指向三维图循环,避免任意解析错误也通过。 assert!( format!("{error:#}").contains("cyclic 3D scene graph"), "{error:#}" ); + // 另一个程序仅给一个顶点却引用索引 0/1/2,应在 Geometry3D 缓冲验证时拒绝。 let error = ReplSession::load( r##" geometry=Geometry3D(ObjectList(Vec3(0,0,0)),ObjectList(Triangle3D(0,1,2))) @@ -5806,6 +5918,7 @@ fn scene3d_example_custom_geometry_and_cycle_diagnostics_use_real_source() { ) .err() .unwrap(); + // 区分非法几何缓冲与前一场景循环诊断,确保两条边界都有覆盖。 assert!( format!("{error:#}").contains("invalid Geometry3D buffers"), "{error:#}"