docs: 逐模块细化中文逻辑注释并覆盖测试与示例
This commit is contained in:
@@ -13,13 +13,14 @@ use endor_core::{
|
||||
/// 验证 hitTest 返回的是 Bool,避免把任意真值隐式当成命中。
|
||||
struct Boolean;
|
||||
impl NativeCallable for Boolean {
|
||||
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
|
||||
/// 接收 hitTest 返回的唯一值,交给 invoke 严格检查 Bool。
|
||||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||||
Some(endor_core::CallArity::exact(1))
|
||||
}
|
||||
|
||||
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
|
||||
/// 只接受真正的 Bool 并原样返回;数字或对象不能以宿主真值规则替代源协议契约。
|
||||
fn invoke(&self, _: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
|
||||
// 协议要求明确 Bool;拒绝数字、对象等“真值”,使用户实现错误立即暴露。
|
||||
let [Value::Bool(value)] = args else {
|
||||
return Err(VmError::InvalidArgument("hitTest must return Bool"));
|
||||
};
|
||||
@@ -30,13 +31,14 @@ impl NativeCallable for Boolean {
|
||||
/// 比较按下与释放的选择结果,只有同一目标才能继续点击分发。
|
||||
struct SameTarget;
|
||||
impl NativeCallable for SameTarget {
|
||||
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
|
||||
/// 接收按下与释放两次命中选择的结果。
|
||||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||||
Some(endor_core::CallArity::exact(2))
|
||||
}
|
||||
|
||||
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
|
||||
/// 仅当两结果为同一 Mount 对象才返回目标,否则返回 Nil;共享 Block 的不同出现位置也不能合成点击。
|
||||
fn invoke(&self, _: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
|
||||
// 比较的是实际出现 Mount 的身份;即使共享同一个 Block,不同出现之间拖动也不构成点击。
|
||||
let value = match args {
|
||||
[Value::Object(first), Value::Object(second)] if first == second => {
|
||||
Value::Object(*first)
|
||||
@@ -53,6 +55,7 @@ fn code(
|
||||
constants: Vec<Value>,
|
||||
layout: CodeLayout,
|
||||
) -> Result<ObjectRef, VmError> {
|
||||
// 校验并编码指令,同时设置诊断位置;独立空 globals 避免驱动依赖业务全局命名空间。
|
||||
let code = EndorCode::from_instructions(&instructions, constants, layout)?.with_location(
|
||||
"<pointer hitTest>",
|
||||
"<tessera>",
|
||||
@@ -76,11 +79,13 @@ fn selector(
|
||||
))?;
|
||||
let mut instructions = Vec::new();
|
||||
let mut constants = vec![Value::Object(validate)];
|
||||
// 候选按绘制顺序提供,逆序使最上层先参与测试;弱引用失效视为过期输入错误。
|
||||
for weak in candidates.iter().rev() {
|
||||
let mount = cx
|
||||
.upgrade(*weak)?
|
||||
.ok_or(VmError::InvalidArgument("pointer Mount expired"))?;
|
||||
let target = cx.store().payload::<Mount>(mount, "Mount")?.clone();
|
||||
// 先排除已卸载、非交互和几何不命中的出现,避免为明显无效候选构造源调用。
|
||||
if !target.mounted
|
||||
|| !target.geometry.interactive
|
||||
|| !target
|
||||
@@ -91,14 +96,17 @@ fn selector(
|
||||
}
|
||||
let geometry = &target.geometry;
|
||||
let point = crate::geometry::Point::new(point[0], point[1]);
|
||||
// 把投影坐标反算到节点逻辑空间;不可逆/无效投影没有可用于 hitTest 的局部坐标。
|
||||
let Some(point) = geometry.logical_point(point) else {
|
||||
continue;
|
||||
};
|
||||
// 源 Point 以节点左上为原点;这里再次验证范围,避免变换后的点落到节点盒子之外。
|
||||
let x = point.x - geometry.x;
|
||||
let y = point.y - geometry.y;
|
||||
if x < 0.0 || y < 0.0 || x > geometry.width || y > geometry.height {
|
||||
continue;
|
||||
}
|
||||
// 依据真实 Block 的名义类型解析 hitTest,不用原生矩形命中替代源协议。
|
||||
let definition = cx
|
||||
.store()
|
||||
.type_of(target.block)?
|
||||
@@ -111,6 +119,7 @@ fn selector(
|
||||
attach_desktop_type(cx, local, "Point", desktop)?;
|
||||
cx.set_attr(local, "x", Value::Number((x as f64).into()))?;
|
||||
cx.set_attr(local, "y", Value::Number((y as f64).into()))?;
|
||||
// 每个候选占四个常量:协议函数、Block、Mount、局部 Point;索引供下面字节码复用。
|
||||
let start = constants.len() as u32;
|
||||
constants.extend([
|
||||
Value::Object(function),
|
||||
@@ -118,12 +127,16 @@ fn selector(
|
||||
Value::Object(mount),
|
||||
Value::Object(local),
|
||||
]);
|
||||
// false 分支只跳过“加载本 Mount 并返回”两条指令。按编码宽度计算,
|
||||
// 常量索引大到需要扩展操作数时仍能跳到下一候选。
|
||||
let skip = (Instruction::encode_all(&[
|
||||
Instruction::new(Opcode::LoadConst, start + 2),
|
||||
Instruction::simple(Opcode::ReturnValue),
|
||||
])?
|
||||
.len()
|
||||
/ 2) as u32;
|
||||
// 先调用 hitTest(block, mount, local),再把结果传给 validate。
|
||||
// true 立即返回本 Mount;false 继续下一个候选,实现透明区域向下穿透。
|
||||
instructions.extend([
|
||||
Instruction::new(Opcode::LoadConst, 0),
|
||||
Instruction::simple(Opcode::PushNull),
|
||||
@@ -139,6 +152,7 @@ fn selector(
|
||||
Instruction::simple(Opcode::ReturnValue),
|
||||
]);
|
||||
}
|
||||
// 所有候选均未命中时显式返回 Nil;不会把最后一个 false 当作选择结果。
|
||||
let end = constants.len() as u32;
|
||||
constants.push(Value::Nil);
|
||||
instructions.extend([
|
||||
@@ -156,13 +170,14 @@ struct Prepare {
|
||||
desktop: ObjectRef,
|
||||
}
|
||||
impl NativeCallable for Prepare {
|
||||
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
|
||||
/// 候选、按下点和释放点已保存于适配器,无需外部实参。
|
||||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||||
Some(endor_core::CallArity::exact(0))
|
||||
}
|
||||
|
||||
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
|
||||
/// 为按下/释放各建立只读选择器,把两次结果放入同一 VM 调用序列,再交 SameTarget 比较实际出现身份。
|
||||
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
|
||||
// 按下和释放分别构造选择器,但都在本次只读执行内调用,使用同一预算域。
|
||||
let down = selector(cx, &self.candidates, self.press, self.desktop)?;
|
||||
let up = selector(cx, &self.candidates, self.release, self.desktop)?;
|
||||
let compare = cx.allocate(ContextNativeFunction::new(
|
||||
@@ -170,6 +185,7 @@ impl NativeCallable for Prepare {
|
||||
SameTarget,
|
||||
vec![],
|
||||
))?;
|
||||
// 两次选择结果先存入局部槽,再作为两个实参交给 SameTarget;局部槽也保留中间结果生命周期。
|
||||
let instructions = vec![
|
||||
Instruction::new(Opcode::LoadConst, 0),
|
||||
Instruction::simple(Opcode::PushNull),
|
||||
@@ -199,6 +215,7 @@ impl NativeCallable for Prepare {
|
||||
..CodeLayout::default()
|
||||
},
|
||||
)?;
|
||||
// 把执行权交回 VM 运行驱动,不在宿主里递归开启另一次 VM 调用。
|
||||
Ok(NativeResult::Invoke {
|
||||
function: driver,
|
||||
arguments: vec![],
|
||||
@@ -206,7 +223,7 @@ impl NativeCallable for Prepare {
|
||||
}
|
||||
}
|
||||
/// Returned Mount owns one root. No-hit and mismatched targets return None.
|
||||
/// 解析输入所指向的实际目标,避免把包装身份与底层数据混淆。
|
||||
/// 在一次有界只读调用中分别选择按下与释放目标;仅二者为同一 Mount 时返回其拥有根。
|
||||
pub fn resolve(
|
||||
vm: &mut Vm,
|
||||
desktop: ObjectRef,
|
||||
@@ -214,6 +231,7 @@ pub fn resolve(
|
||||
press: [f32; 2],
|
||||
release: [f32; 2],
|
||||
) -> anyhow::Result<Option<ObjectRef>> {
|
||||
// 显式 captures 保活 desktop;候选列表仍是弱引用,不因等待选择而保活全部旧 Mount。
|
||||
let prepare = vm.allocate(ContextNativeFunction::new(
|
||||
"prepare pointer hitTest",
|
||||
Prepare {
|
||||
@@ -232,9 +250,11 @@ pub fn resolve(
|
||||
max_instructions: 1_000_000,
|
||||
},
|
||||
);
|
||||
// 先保存调用结果再释放入口根,因此 VM 返回错误时也能完成入口清理。
|
||||
vm.release(prepare)?;
|
||||
let (value, _) = result.map_err(|error| crate::endor_host::runtime_error(vm, error))?;
|
||||
match value {
|
||||
// 成功返回的 Mount 仍拥有一次根引用,交由调用方使用并释放;None 不转移任何对象根。
|
||||
Value::Object(mount) => Ok(Some(mount)),
|
||||
Value::Nil => Ok(None),
|
||||
value => {
|
||||
|
||||
Reference in New Issue
Block a user