docs: clarify protocol and document publication contracts
This commit is contained in:
+15
-4
@@ -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<crate::layout::Size>,
|
||||
pub window_viewports: std::collections::BTreeMap<u64, crate::layout::Size>,
|
||||
// 原生命令与运行时世代一起发布,防止窗口 ID 在跨 VM 时被误用。
|
||||
pub runtime_session: u64,
|
||||
// 待窗口壳消费的世代化原生命令,按动作合并并保留全局请求顺序。
|
||||
// 待窗口壳消费的世代化原生命令,按同窗动作合并;sequence 只在各窗口内单调,不承诺跨窗口的全局发生顺序。
|
||||
pub window_commands: Vec<crate::window::Envelope>,
|
||||
}
|
||||
|
||||
@@ -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<Option<u64>> {
|
||||
// 先核对归属,再计算新版本;失败或过时的结果不会替换已显示文档。
|
||||
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<Color>,
|
||||
// 原生像素由 Arc 独立保活;GUI 绘制无需用源对象 ID 查 VM 堆。
|
||||
image: Arc<crate::render::image::Image>,
|
||||
},
|
||||
// 屏幕矩形中的三维 View 快照,世界几何和相机数据由原生 Arc 独立拥有。
|
||||
|
||||
Reference in New Issue
Block a user