docs: explain UI bridge callers, control flow and VM ownership
This commit is contained in:
@@ -1,11 +1,13 @@
|
||||
//! 把页面、2D 视口和 3D 视口的相机输入转换成托管对象更新。
|
||||
//! 输入携带具体出现的 Mount;嵌套世界 UI 先做逆投影,避免把屏幕位移直接当成场景坐标。
|
||||
//!
|
||||
//! Camera mutations run on the owning VM worker, just like other page input.
|
||||
//! UiBridge::dispatch 按输入 kind 分流到下面三个方法:整页、局部二维视口和局部三维场景分别处理。
|
||||
//! 它们只在所属 VM worker 上修改托管相机属性或调用 controller.update,不直接改 GUI 已发布帧。
|
||||
//! 姿态变化随后由正常依赖/快照刷新观察;任何新帧仍需走 layout/paint/commit 的完整发布路径。
|
||||
use super::*;
|
||||
|
||||
impl UiBridge {
|
||||
/// 解码指定 3D 视口的旋转/平移/缩放输入,再调用其托管相机控制器。
|
||||
/// dispatch 的 scene-pan/orbit/zoom 分支调用,把命中出现位置的输入包装成 CameraGesture 交给控制器。
|
||||
pub(super) fn dispatch_scene_view(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
@@ -13,6 +15,7 @@ impl UiBridge {
|
||||
) -> Result<()> {
|
||||
// 锁内只读取当前发布版本与弱 Mount 身份,离开锁后才进入 VM 操作,避免持 session 锁调用用户代码。
|
||||
let (weak, desktop) = {
|
||||
// 当前窗口已由外层选定;本锁内同时读版本和 Mount,避免把旧几何与新弱身份混用。
|
||||
let state = self
|
||||
.session
|
||||
.lock()
|
||||
@@ -30,9 +33,11 @@ impl UiBridge {
|
||||
state.desktop,
|
||||
)
|
||||
};
|
||||
// upgrade 返回临时拥有根,下方即使任一步失败也通过闭包外的 release 清理。
|
||||
let mount = vm
|
||||
.upgrade(weak)?
|
||||
.ok_or_else(|| anyhow::anyhow!("3D viewport Mount expired"))?;
|
||||
// 不能直接 ? 返回整个方法,否则错误时跳过 Mount 根释放;用闭包暂存处理结果。
|
||||
let result = (|| {
|
||||
// 除 session 发布版本外,再检查目标自身仍挂接、版本匹配且确为 3D 视口,拒绝旧出现操作。
|
||||
let occurrence = vm.payload::<crate::mount::Mount>(mount, "Mount")?.clone();
|
||||
@@ -42,8 +47,11 @@ impl UiBridge {
|
||||
&& occurrence.geometry.scene3d_viewport,
|
||||
"obsolete 3D viewport"
|
||||
);
|
||||
// resolve 跟随 Block 的共享替换关系,再读取实际视觉状态,不能只信任旧 payload。
|
||||
let (_, data) = block::resolve(vm.object_store(), occurrence.block)?;
|
||||
// visual_data 合并当前可见属性,后面的相机/控制器来自模型而非原生画面的旧快照。
|
||||
let data = block::visual_data(vm.object_store(), data)?;
|
||||
// 没有显式相机就无法解释手势,拒绝更新而不是猜一个默认相机改变场景语义。
|
||||
let camera = data
|
||||
.camera
|
||||
.ok_or_else(|| anyhow::anyhow!("missing 3D camera"))?;
|
||||
@@ -51,18 +59,25 @@ impl UiBridge {
|
||||
let controller = data
|
||||
.controller
|
||||
.ok_or_else(|| anyhow::anyhow!("3D controller disabled"))?;
|
||||
// 同一视觉对象的边框/内边距由快照解析,手势锚点与可用尺寸都应扣除这部分。
|
||||
let node = block::snapshot(vm.object_store(), occurrence.block)?;
|
||||
// inset 将外框换算成视口内容盒,避免控制器把边框尺寸算成场景宽高。
|
||||
let inset = crate::layout::insets(&node);
|
||||
// 几何来自具体 Mount,两个窗口中共享同一场景仍可能有不同视图投影。
|
||||
let geometry = &occurrence.geometry;
|
||||
// 外层二维视图逆变换用于锚点定位;没有视图变换时使用恒等变换。
|
||||
let outer = geometry.view.unwrap_or_default();
|
||||
// delta 的第一分量还会用作缩放倍率;缺失说明输入信封不满足相机事件要求。
|
||||
let delta = input
|
||||
.delta
|
||||
.ok_or_else(|| anyhow::anyhow!("3D camera delta required"))?;
|
||||
// 缩放使用倍率而非二维位移;旋转/平移通过 logical_delta 处理嵌套二维/面板投影。
|
||||
// 不可逆映射时忽略本次连续增量,不在无效坐标上继续更新相机。
|
||||
let local_delta = if input.kind == "scene-zoom" {
|
||||
// 缩放不产生平移 dx/dy,只把原第一分量写到 gesture.factor。
|
||||
[0., 0.]
|
||||
} else {
|
||||
// 平移/旋转先撤销外层投影;映射失败表示本帧增量无法可靠应用。
|
||||
let Some(delta) = geometry.logical_delta(input.point, delta) else {
|
||||
return Ok(());
|
||||
};
|
||||
@@ -79,6 +94,7 @@ impl UiBridge {
|
||||
));
|
||||
// 将输入封装为名义 CameraGesture 临时对象;不把原生 Input 或窗口指针直接交给源控制器。
|
||||
let gesture = vm.new_object()?;
|
||||
// 临时手势也有独立拥有根;把附类型/写字段/控制器错误暂存,外层始终 release(gesture)。
|
||||
let result = (|| {
|
||||
vm.attach_type(
|
||||
gesture,
|
||||
@@ -95,10 +111,12 @@ impl UiBridge {
|
||||
("pointX", point.x - geometry.x - inset.left),
|
||||
("pointY", point.y - geometry.y - inset.top),
|
||||
] {
|
||||
// 全部数值通过统一语言数值编码写属性,控制器读取的是普通托管字段。
|
||||
vm.set_attr(gesture, name, crate::native_visual::value(value))?;
|
||||
}
|
||||
// 绑定 controller.update 保留接收者语义,再带 camera/gesture 两个显式参数进行有界调用。
|
||||
let function = vm.bind_attr(controller, "update")?;
|
||||
// callable 校验在 VM 执行边界继续完成,非对象方法值直接作为契约错误返回。
|
||||
let result = match function {
|
||||
Value::Object(function) => vm.call_with_limits(
|
||||
function,
|
||||
@@ -124,7 +142,7 @@ impl UiBridge {
|
||||
result
|
||||
}
|
||||
|
||||
/// 把具体 CanvasViewport 的位移或缩放锚点映射到其显式 Camera2D。
|
||||
/// dispatch 的 viewport-pan/zoom 分支调用,逆投影具体 CanvasViewport 输入并改写其 Camera2D 属性。
|
||||
pub(super) fn dispatch_viewport_view(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
@@ -132,6 +150,7 @@ impl UiBridge {
|
||||
) -> Result<()> {
|
||||
// 二维视口同样先校验发布版本,再从活动表捕获原 Mount,不能因目标消失自动换成另一个视口。
|
||||
let weak = {
|
||||
// 锁内只检查发布版本并复制弱身份;下面读取相机和写 VM 属性时不持有会话锁。
|
||||
let state = self
|
||||
.session
|
||||
.lock()
|
||||
@@ -146,10 +165,13 @@ impl UiBridge {
|
||||
.get(&input.mount)
|
||||
.ok_or_else(|| anyhow::anyhow!("viewport is no longer active"))?
|
||||
};
|
||||
// 临时根保证输入处理期间 Mount 仍可读取,方法尾部无论成功失败都释放。
|
||||
let mount = vm
|
||||
.upgrade(weak)?
|
||||
.ok_or_else(|| anyhow::anyhow!("viewport Mount expired"))?;
|
||||
// 闭包集中实际处理,使所有 ? 都先回到统一释放路径。
|
||||
let result = (|| {
|
||||
// 弱身份能升级不代表仍挂载/版本有效,先验证具体出现上下文。
|
||||
let occurrence = vm.payload::<crate::mount::Mount>(mount, "Mount")?;
|
||||
anyhow::ensure!(
|
||||
occurrence.mounted
|
||||
@@ -157,32 +179,44 @@ impl UiBridge {
|
||||
&& occurrence.geometry.canvas_viewport,
|
||||
"obsolete viewport occurrence"
|
||||
);
|
||||
// 复制几何和 Block 身份,结束 occurrence 对 VM 的借用后才能改写相机。
|
||||
let geometry = occurrence.geometry.clone();
|
||||
// Block 只用于找相机/边距,输入定位仍来自 Mount 的几何。
|
||||
let block = occurrence.block;
|
||||
// 共享替换后的实际视觉状态才包含当前相机引用。
|
||||
let (_, data) = block::resolve(vm.object_store(), block)?;
|
||||
// 托管属性覆盖 payload 缺省值,保持与布局/绘制同一视觉读取约定。
|
||||
let data = block::visual_data(vm.object_store(), data)?;
|
||||
// 局部视口必须有 Camera2D,不把整页 Surface 当作相机替代。
|
||||
let camera = data
|
||||
.camera
|
||||
.ok_or_else(|| anyhow::anyhow!("viewport has no camera"))?;
|
||||
// 读取已校验的相机快照作为本次基准;共享相机用户会通过普通属性变更观察到相同更新。
|
||||
let old = crate::viewport::camera(vm.object_store(), camera)?;
|
||||
// 该分量在 zoom 时表示倍率,在 pan 时表示外部逻辑位移,随后分支分别解释。
|
||||
let delta = input
|
||||
.delta
|
||||
.ok_or_else(|| anyhow::anyhow!("viewport input has no delta"))?;
|
||||
// 基于旧快照计算三个新值,完成验证后才依次回写托管属性。
|
||||
let (mut x, mut y, mut zoom) = (old.x, old.y, old.zoom);
|
||||
if input.kind == "viewport-zoom" {
|
||||
// 缩放必须有锚点,不能让缺失指针导致隐式绕视口原点缩放。
|
||||
let pointer = input
|
||||
.point
|
||||
.ok_or_else(|| anyhow::anyhow!("zoom requires anchor"))?;
|
||||
// 先用屏幕/视图坐标做外框检查,再逆投影到布局逻辑坐标。
|
||||
let pointer = crate::geometry::Point::new(pointer[0], pointer[1]);
|
||||
anyhow::ensure!(
|
||||
geometry.contains(pointer),
|
||||
"zoom anchor is outside viewport"
|
||||
);
|
||||
// 外框命中不保证投影可逆;None 作为错误返回,不能继续使用原屏幕数值。
|
||||
let pointer = geometry
|
||||
.logical_point(pointer)
|
||||
.ok_or_else(|| anyhow::anyhow!("zoom anchor cannot be projected"))?;
|
||||
// 当前 Block 快照给出布局边距,用它取得正确内容盒的缩放锚点。
|
||||
let node = block::snapshot(vm.object_store(), block)?;
|
||||
// inset 与布局模块共用同一规则,避免相机手势与绘制对内容原点理解不同。
|
||||
let inset = crate::layout::insets(&node);
|
||||
// 已验证指针落在出现外框还不够;扣除 inset 后必须落入实际内容盒,禁止用边框作为缩放锚点。
|
||||
let local = [
|
||||
@@ -201,6 +235,7 @@ impl UiBridge {
|
||||
x += local[0] / old.zoom - local[0] / zoom;
|
||||
y += local[1] / old.zoom - local[1] / zoom;
|
||||
} else {
|
||||
// 平移没有锚点保持公式,只需逆投影增量再除相机自身缩放。
|
||||
let Some(delta) = geometry.logical_delta(input.point, delta) else {
|
||||
return Ok(());
|
||||
};
|
||||
@@ -216,11 +251,12 @@ impl UiBridge {
|
||||
vm.set_attr(camera, "zoom", crate::native_visual::value(zoom))?;
|
||||
Ok(())
|
||||
})();
|
||||
// release 发生在 result? 之前,保证投影/属性写入错误不会泄漏升级得到的 Mount。
|
||||
vm.release(mount)?;
|
||||
result
|
||||
}
|
||||
|
||||
/// 处理旧 Page 模式的兼容相机事件;独立视口使用各自的输入路径。
|
||||
/// dispatch 的 page-pan/zoom 分支调用,兼容旧 Page 表面相机;独立 CanvasViewport 不走此方法。
|
||||
pub(super) fn dispatch_page_view(
|
||||
&self,
|
||||
vm: &mut Vm,
|
||||
@@ -228,6 +264,7 @@ impl UiBridge {
|
||||
) -> Result<()> {
|
||||
// 兼容 Page 相机不通过 Mount 定位,而是读取当前活动页面及其 Surface 副本;发布版本仍必须一致。
|
||||
let (page, mut surface, viewport) = {
|
||||
// 只复制当前已发布页的相机与真实视口,不持锁执行下面的坐标计算或 VM 属性写入。
|
||||
let state = self
|
||||
.session
|
||||
.lock()
|
||||
@@ -244,17 +281,21 @@ impl UiBridge {
|
||||
state.layout.viewport,
|
||||
)
|
||||
};
|
||||
// 外层信封校验之后仍要求本路径必需的增量字段,防止不完整调用静默改变相机。
|
||||
let delta = input
|
||||
.delta
|
||||
.ok_or_else(|| anyhow::anyhow!("page view requires delta"))?;
|
||||
if input.kind == "page-zoom" {
|
||||
// 旧 Page 模式只允许 Canvas 缩放,有限文档或 Window 页面保持各自尺寸语义。
|
||||
anyhow::ensure!(
|
||||
surface.mode == crate::page::Mode::Canvas,
|
||||
"zoom requires canvas mode"
|
||||
);
|
||||
// 以光标为缩放锚点,先要求它存在,再检查可用视口范围。
|
||||
let pointer = input
|
||||
.point
|
||||
.ok_or_else(|| anyhow::anyhow!("zoom requires anchor"))?;
|
||||
// 转为页面几何共用的 Point,便于调用 Surface::to_world 做缩放前逆变换。
|
||||
let pointer = crate::geometry::Point::new(pointer[0], pointer[1]);
|
||||
anyhow::ensure!(
|
||||
pointer.x >= 0.0
|
||||
@@ -270,6 +311,7 @@ impl UiBridge {
|
||||
world.y - pointer.y / surface.zoom,
|
||||
);
|
||||
} else {
|
||||
// 平移按当前 zoom 换成世界距离,不直接把屏幕像素累加进世界 pan。
|
||||
surface.pan.x += delta[0] / surface.zoom;
|
||||
surface.pan.y += delta[1] / surface.zoom;
|
||||
}
|
||||
@@ -277,6 +319,7 @@ impl UiBridge {
|
||||
if let Some(viewport) = viewport {
|
||||
surface.clamp(viewport);
|
||||
}
|
||||
// 内容模式 clamp 之外再加通用坐标预算;Canvas 可自由漫游,但也不能无限增长偏移。
|
||||
let limit = MAX_DIMENSION as f32;
|
||||
surface.pan.x = surface.pan.x.clamp(-limit, limit);
|
||||
surface.pan.y = surface.pan.y.clamp(-limit, limit);
|
||||
|
||||
Reference in New Issue
Block a user