diff --git a/src/model/document.rs b/src/model/document.rs index e366e44..277d571 100644 --- a/src/model/document.rs +++ b/src/model/document.rs @@ -29,14 +29,14 @@ pub struct NamespaceState { pub revision: u64, // 较新完整 PUT/DELETE 会改变提交身份;旧输入即使晚完成也不得覆盖新结果。 pub submission: u64, - // 最近成功的完整文档;编译/执行失败或过期候选不替换它。 + // 最近完整发布的文档;失败候选不替换其几何,但 worker 可在旧完整画面上追加 fault 诊断后重新提交。 pub document: RenderDocument, // viewport 是主窗口逻辑页面区域;window_viewports 同时记录仍存活的副窗口。 pub viewport: Option, pub window_viewports: std::collections::BTreeMap, // 原生命令与运行时世代一起发布,防止窗口 ID 在跨 VM 时被误用。 pub runtime_session: u64, - // 待窗口壳消费的世代化原生命令,按动作合并并保留全局请求顺序。 + // 待窗口壳消费的世代化原生命令,按同窗动作合并;sequence 只在各窗口内单调,不承诺跨窗口的全局发生顺序。 pub window_commands: Vec, } @@ -81,7 +81,7 @@ impl NamespaceState { self.window_commands .push(crate::window::Envelope { session, command }); } - // 合并后按 VM 原始 sequence 恢复执行顺序,避免 retain/push 使不同资源动作乱序。 + // 按各命令原 sequence 排序,恢复同窗保留动作的先后;不同窗口的序号可以相同,不能由此推导跨窗时间顺序。 self.window_commands .sort_by_key(|command| command.command.sequence); } @@ -94,6 +94,7 @@ impl NamespaceState { } /// 仅当提交身份仍是最新时替换完整文档并递增版本;已被取代的结果不发布。 + /// 发布调用方须先完成文档验证与适用的世代检查;这里不自动 validate,也不设置 runtime_session 或发布窗口命令。 pub fn commit(&mut self, submission: u64, document: RenderDocument) -> Result> { // 先核对归属,再计算新版本;失败或过时的结果不会替换已显示文档。 if submission != self.submission { @@ -469,7 +470,8 @@ impl CodeNode { } #[derive(Clone, Debug, Serialize, Deserialize)] -/// 一个窗口的一次完整视觉发布:有序命令及其裁剪/变换、出现几何、焦点和版本。平行索引表必须和命令数量一致。 +/// 一个窗口的视觉帧数据:有序命令及其裁剪/变换、出现几何、焦点和版本。布局/绘制也用此结构保存未发布草稿。 +/// 是否完整可见由运行时的验证与稳定发布边界决定;仅持有 Frame 或 layout_version 不能证明它已发布。 pub struct Frame { // 命中索引是可重建的本地优化,不作为序列化协议的一部分保存。 #[serde(skip)] @@ -605,6 +607,7 @@ impl MountGeometry { } /// 把视图位移换算成目标出现的局部位移,处理缩放与世界 UI 投影差异。 pub fn logical_delta(&self, point: Option<[f32; 2]>, delta: [f32; 2]) -> Option<[f32; 2]> { + // page_input 的相机手势和 UiBridge 的 scroll 输入共用;返回的是本出现布局单位,视口相机自身的 zoom 由各调用方再解释。 // 累计二维缩放用于把最终视图差值还原到布局位移;透视面板还需先投影两个端点。 let zoom = self.view.unwrap_or_default().zoom; // 普通二维映射为线性,只除累计 zoom 即可;世界面板透视非线性,必须映射两个点求差。 @@ -641,6 +644,7 @@ impl MountGeometry { impl Frame { /// 从顶层绘制顺序向后查找可控制的视口,命中与裁剪均成立才接收相机手势。 pub fn camera_at(&self, point: Point) -> Option<&MountGeometry> { + // 本方法不检查 frame.fault 或 session;shell 接纳输入的外层流程仍须验证运行域和发布身份。 // 窗口手势目标选择使用空间索引候选次序,但仍须逐个通过视口种类、外框和内容裁剪。 self.hit_index .candidates(point, self.mounts.len()) @@ -689,15 +693,22 @@ pub enum RenderCommand { #[serde(skip_deserializing)] // 仅本机可构造的不可变图像资源命令,禁止从外部 JSON 反序列化任意图像资源。 Image { + // 旋转/缩放围绕的逻辑原点;与下面局部图像矩形偏移分开保存。 x: f32, y: f32, + // 显示矩形的逻辑尺寸,可与原始像素宽高不同;设备比例在 to_draw_command 中应用。 width: f32, height: f32, + // 相对 origin 的局部矩形起点,Sprite 锚点通过负偏移表示,不移动资源本身的像素。 offset_x: f32, offset_y: f32, + // 弧度旋转角,设备同比缩放不改变角度。 angle: f32, + // 整体混合透明度,发布验证要求位于 [0,1]。 opacity: f32, + // 可选颜色调制;None 使用图像本来的颜色,区别于全透明调制色。 tint: Option, + // 原生像素由 Arc 独立保活;GUI 绘制无需用源对象 ID 查 VM 堆。 image: Arc, }, // 屏幕矩形中的三维 View 快照,世界几何和相机数据由原生 Arc 独立拥有。 diff --git a/src/model/protocols.rs b/src/model/protocols.rs index 97f1873..b62406f 100644 --- a/src/model/protocols.rs +++ b/src/model/protocols.rs @@ -94,6 +94,8 @@ pub fn install( CallEffect::External, ) }; + // Aster typed trait 要求固定的规范调用形状;例如 on 以 receiver+事件名+回调+阶段四参描述。 + // 这只修改 trait 的签名副本,不收紧原生 on/dispatch 方法本身允许省略尾参的 arity。 signature.arity = CallArity::exact(parameters + 1); // 接收者类型改为 Any,使能力可由其他符合方法契约的名义类型实现,不把契约绑定死在 Block。 signature.parameters[0] = AnnotationType::Any.into(); @@ -103,6 +105,7 @@ pub fn install( }); } // VM 创建受类型约束的 trait;后面保活、附 Trait 名义类型并公开两个查询入口。 + // EndorTraitObject.trace 会追踪签名中的名义类型,requirements 不是只供显示的无拥有关系文本。 let capability = vm.new_typed_trait(name, requirements)?; // 新能力放入宿主 roots 管理生命周期,再同时暴露于 ui 属性与 desktop 类型注册表。 roots.push(capability); diff --git a/src/model/scene3d.rs b/src/model/scene3d.rs index 06e75cb..ac97614 100644 --- a/src/model/scene3d.rs +++ b/src/model/scene3d.rs @@ -546,6 +546,7 @@ pub fn snapshot( snapshot_reusing(store, scene, camera, None) } /// 遍历场景并记录字段依赖;如果世界数据未变则复用不可变场景和 BVH,只替换摄像机视图。 +/// RenderCache 传入同一 Scene3D 的旧场景;仍完整读取当前场景并比较数值,复用并不意味着跳过遍历或沿用旧依赖。 pub fn snapshot_reusing( store: &ObjectStore, scene: ObjectRef, @@ -625,6 +626,7 @@ pub fn snapshot_reusing( match kind { NodeKind::Scene | NodeKind::Group => { // 通过 Reader 记录 children 属性引用,items 再验证它确为 ObjectList。 + // 此处记录的是 owner.children 属性键;items 借用列表 payload,不会给 reader.reads 自动添加列表内容依赖。 let list = object_ref(&reader.value(object, "children")?)?; // 逆序压栈保留列表原始遍历次序,每个子出现都继承当前 world。 for (index, child) in object_list::items(store, list)?.iter().enumerate().rev() { @@ -891,7 +893,7 @@ pub fn pick( } #[derive(Debug)] -/// 指针拾取的中间结果,保留交点与所属实例信息供 Event/RayHit3D 使用。 +/// UiBridge 为三维点击分配的零参原生适配器;invoke 才执行拾取并将 RayHit3D/Nil 放进 Event.hit。 pub struct PointerPick { // 原生指针目标的托管 Mount,由调用方包装的 captures 保活。 pub mount: ObjectRef, @@ -1023,6 +1025,7 @@ pub fn control( return Err(invalid("camera movement exceeds world budget")); } // 位置与 target 逐轴经 NativeContext 写回,变化日志让下一视觉快照观察到更新。 + // 正交 zoom 分支还会单独写 height;这些是普通属性写入,不构成多字段事务回滚,失败处理由外层 VM 调用路径负责。 for (name, value) in [ ("x", position.x), ("y", position.y),