248 lines
11 KiB
Rust
248 lines
11 KiB
Rust
//! 旧 Page.mode 的兼容空间策略，以及页面级的正逆相机变换。
|
|
//! 新组合应优先使用普通布局、ScrollView 和独立场景视口；保留这里是为了兼容已有 window/vertical/horizontal/canvas 页面。
|
|
//!
|
|
//! 调用路径：Block.mode 属性解码用 Mode.parse；根布局按 Mode.constraints 选择有限/可延伸轴。
|
|
//! scene/输入导航使用 Surface 的正逆变换和可见性判断，内容变化后用 clamp 收敛兼容页面偏移。
|
|
//! 本模块不创建窗口、不修改 VM；Page 表面导航与独立 CanvasViewport/ScrollBlock 是不同状态。
|
|
//!
|
|
//! Page space is independent of the native window. The camera is applied once
|
|
//! for painting and inverted once for input; layout and Mounts stay in world units.
|
|
use crate::{geometry::Point, layout::Size};
|
|
use endor_core::VmError;
|
|
use serde::{Deserialize, Serialize};
|
|
|
|
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(rename_all = "lowercase")]
|
|
/// 旧 Page 的有限或自由空间模式，新场景视口不依赖它表达布局方向。
|
|
pub enum Mode {
|
|
#[default]
|
|
// 双轴被原生视口限制；兼容相机固定在原点且比例为 1。
|
|
Window,
|
|
// 宽度固定，高度允许展开到布局上限，只沿 y 方向导航。
|
|
Vertical,
|
|
// 高度固定，宽度允许展开到布局上限，只沿 x 方向导航。
|
|
Horizontal,
|
|
// 双轴自由布局并允许平移缩放；相机不按内容边缘钳制。
|
|
Canvas,
|
|
}
|
|
|
|
impl Mode {
|
|
/// 返回内部枚举或对象对应的稳定源名称。
|
|
pub fn name(self) -> &'static str {
|
|
// 源字段编码与序列化采用同一组小写策略名，布局方向不由显示标题推断。
|
|
match self {
|
|
Self::Window => "window",
|
|
Self::Vertical => "vertical",
|
|
Self::Horizontal => "horizontal",
|
|
Self::Canvas => "canvas",
|
|
}
|
|
}
|
|
|
|
/// 把外部源码或属性表示转换为内部枚举/结构，并反馈不支持的输入。
|
|
pub fn parse(name: &str) -> Result<Self, VmError> {
|
|
// 仅接受四个兼容模式，未知值明确拒绝，不能默认为 window。
|
|
match name {
|
|
"window" => Ok(Self::Window),
|
|
"vertical" => Ok(Self::Vertical),
|
|
"horizontal" => Ok(Self::Horizontal),
|
|
"canvas" => Ok(Self::Canvas),
|
|
_ => Err(VmError::InvalidArgument(
|
|
"Page.mode expects window, vertical, horizontal or canvas",
|
|
)),
|
|
}
|
|
}
|
|
|
|
/// 为旧页面模式生成有限轴和可延伸轴的根约束。
|
|
pub fn constraints(self, viewport: Option<Size>) -> [f32; 4] {
|
|
// LayoutRuntime::root_constraints 用于页面根测量；这里的可延伸轴仍有数值上限，不会向布局传 f32::INFINITY。
|
|
// 未收到原生视口尺寸时采用布局默认根约束；不能凭空建立固定宽高。
|
|
let Some(size) = viewport else {
|
|
return crate::layout::root_constraints(None);
|
|
};
|
|
// MAX_DIMENSION 在根约束中充当可延伸轴上限，不把它当作真实窗口尺寸。
|
|
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],
|
|
Self::Horizontal => [size.width, size.height, limit, size.height],
|
|
Self::Canvas => [0.0, 0.0, limit, limit],
|
|
}
|
|
}
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
/// 页面级兼容相机状态和有限内容范围，支持绘制与命中正逆变换。
|
|
pub struct Surface {
|
|
// 兼容 Page 空间策略，决定根约束及偏移夹取规则。
|
|
pub mode: Mode,
|
|
// 发布给原生侧的页面身份文本，不是托管强引用。
|
|
pub page: String,
|
|
// 视图左上角对应的世界坐标；绘制时先减 pan 再乘 zoom。
|
|
pub pan: Point,
|
|
#[serde(default = "unit")]
|
|
// 世界到视图的均匀比例，反变换要求非零有限；模型/文档入口负责合法范围。
|
|
pub zoom: f32,
|
|
// 布局产出的内容宽高，用于有限模式钳制；不决定 Canvas 的导航边界。
|
|
pub extent: Size,
|
|
}
|
|
|
|
/// 生成页面相机计算所需的单位比例或边界默认值。
|
|
fn unit() -> f32 {
|
|
1.0
|
|
}
|
|
|
|
impl Default for Surface {
|
|
/// 建立类型约定的初始值，供尚未发布或尚未交互的状态使用。
|
|
fn default() -> Self {
|
|
// 初始 Window 表面无页面身份、零偏移且单位缩放，可作为合法空发布值。
|
|
Self {
|
|
mode: Mode::Window,
|
|
page: String::new(),
|
|
pan: Point::default(),
|
|
zoom: 1.0,
|
|
extent: Size::default(),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl Surface {
|
|
/// 指定页面模式并显式使用单位缩放，其他字段采用空页面默认值；无需分配 VM 或原生窗口资源。
|
|
pub fn new(mode: Mode) -> Self {
|
|
Self {
|
|
mode,
|
|
zoom: 1.0,
|
|
..Self::default()
|
|
}
|
|
}
|
|
|
|
/// 把页面视图坐标反算为旧 Page 相机下的世界坐标。
|
|
// 输入在视图空间，先除缩放再加世界偏移；调用方需保证 zoom 有限且大于零。
|
|
pub fn to_world(&self, point: Point) -> Point {
|
|
// shell 先去除侧栏/设备比例等宿主偏移，再调用本逆变换；不在这里处理 Mount.view 或三维面板的第二层映射。
|
|
Point::new(
|
|
point.x / self.zoom + self.pan.x,
|
|
point.y / self.zoom + self.pan.y,
|
|
)
|
|
}
|
|
|
|
/// 把旧页面世界坐标变换到可见视图坐标。
|
|
// 输入在世界空间，先减相机偏移再缩放，恰与 to_world 互逆。
|
|
pub fn to_view(&self, point: Point) -> Point {
|
|
Point::new(
|
|
(point.x - self.pan.x) * self.zoom,
|
|
(point.y - self.pan.y) * self.zoom,
|
|
)
|
|
}
|
|
|
|
/// 判断给定点是否位于目标范围；需要相机转换的类型会先转换再判断。
|
|
pub fn contains(&self, point: [f32; 2], viewport: Option<Size>) -> bool {
|
|
// UiBridge 在点击/滚动前用它排除页面外输入；point 必须已经是页面世界点，不能把原始设备像素传进来。
|
|
// 传入的数组是世界坐标。转换后使用左/上包含、右/下排除的视口边界；
|
|
// 未知视口时仍排除负坐标，但不限制右/下界。
|
|
// 传入世界坐标先投影到视图空间，再按视口半开边界检查，不能与 Rect.contains 的闭边界混淆。
|
|
let point = self.to_view(Point::new(point[0], point[1]));
|
|
point.x >= 0.0
|
|
&& point.y >= 0.0
|
|
&& viewport.is_none_or(|size| point.x < size.width && point.y < size.height)
|
|
}
|
|
|
|
/// 只对有限页面按实际内容范围钳制偏移；自由画布不按内容边缘停止导航。
|
|
pub fn clamp(&mut self, viewport: Size) {
|
|
// UiBridge 布局完成后和 page_input 导航后调用；只修改这个 Surface 数值副本，写回 Page 属性或发布 Frame 由调用方完成。
|
|
// Window 重置所有导航；单轴模式清除另一轴并恢复单位缩放。
|
|
// 内容小于视口时 max(0) 令可滚动范围归零，避免 clamp 出现反向上下限。
|
|
match self.mode {
|
|
// 普通窗口页面关闭导航能力，每次夹取恢复零 pan 与 zoom=1。
|
|
Mode::Window => {
|
|
self.pan = Point::default();
|
|
self.zoom = 1.0;
|
|
}
|
|
// 纵向模式仅允许 y 在内容高−视口高内移动，清横向偏移并禁用缩放。
|
|
Mode::Vertical => {
|
|
self.zoom = 1.0;
|
|
self.pan.x = 0.0;
|
|
self.pan.y = self
|
|
.pan
|
|
.y
|
|
.clamp(0.0, (self.extent.height - viewport.height).max(0.0));
|
|
}
|
|
// 横向模式同理仅允许 x 移动，内容缩短后最大偏移随之减少。
|
|
Mode::Horizontal => {
|
|
self.zoom = 1.0;
|
|
self.pan.y = 0.0;
|
|
self.pan.x = self
|
|
.pan
|
|
.x
|
|
.clamp(0.0, (self.extent.width - viewport.width).max(0.0));
|
|
}
|
|
// 自由画布不按内容边缘夹取，保留可查看负世界坐标与空白区域的导航。
|
|
Mode::Canvas => {}
|
|
}
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
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;
|
|
// 固定视图指针位置作为缩放锚点，计算缩放前它对应的世界点。
|
|
let pointer = Point::new(300.0, 180.0);
|
|
// 保存锚点世界位置，改变 zoom 后反求 pan，保证 to_view(world) 仍等于 pointer。
|
|
let world = view.to_world(pointer);
|
|
assert_eq!(view.to_view(world), pointer);
|
|
// 模拟指针锚定缩放而不是绕世界原点缩放，随后检查可见与不可见点。
|
|
view.zoom = 2.0;
|
|
view.pan = Point::new(
|
|
world.x - pointer.x / view.zoom,
|
|
world.y - pointer.y / view.zoom,
|
|
);
|
|
assert_eq!(view.to_view(world), pointer);
|
|
assert!(view.contains(
|
|
[world.x, world.y],
|
|
Some(Size {
|
|
width: 500.0,
|
|
height: 400.0
|
|
})
|
|
));
|
|
assert!(!view.contains(
|
|
[-1000.0, -1000.0],
|
|
Some(Size {
|
|
width: 500.0,
|
|
height: 400.0
|
|
})
|
|
));
|
|
}
|
|
|
|
#[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 {
|
|
width: 400.0,
|
|
height: 800.0,
|
|
};
|
|
view.clamp(Size {
|
|
width: 400.0,
|
|
height: 600.0,
|
|
});
|
|
assert_eq!(view.pan, Point::new(0.0, 200.0));
|
|
// 内容缩到视口之内后重新夹取，旧 y=200 必须回零，不能继续显示内容外空白。
|
|
view.extent.height = 100.0;
|
|
view.clamp(Size {
|
|
width: 400.0,
|
|
height: 600.0,
|
|
});
|
|
assert_eq!(view.pan.y, 0.0);
|
|
}
|
|
}
|