docs: explain Tessera modules and execution flows in Chinese
This commit is contained in:
@@ -1,3 +1,7 @@
|
||||
//! 将 Endor 托管场景对象转换成可供渲染线程读取的 3D 数据。
|
||||
//! 构造器和字段仍属于 VM;快照复制必要的数值、不可变网格和依赖,渲染器不读取托管堆。
|
||||
//! 场景遍历组合局部变换、检查环和资源限制,并为 Panel3D 提取独立 UI 根。控制器更新相机;拾取结果再映射回托管节点。
|
||||
//!
|
||||
//! Traced 3D objects and checked immutable snapshots. No managed handle enters
|
||||
//! the renderer; cameras and node transforms remain editable Endor attributes.
|
||||
use crate::{
|
||||
@@ -11,6 +15,7 @@ use endor_core::{NativeContext, ObjectPayload, ObjectRef, ObjectStore, Value, Vm
|
||||
use std::{collections::HashSet, sync::Arc};
|
||||
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
/// 源 3D 类型的构造元数据入口,统一管理名称、参数、数量和可变子项。
|
||||
pub enum Constructor {
|
||||
Vec3,
|
||||
Triangle,
|
||||
@@ -26,6 +31,7 @@ pub enum Constructor {
|
||||
Panel,
|
||||
}
|
||||
impl Constructor {
|
||||
/// 返回内部枚举或对象对应的稳定源名称。
|
||||
pub fn name(self) -> &'static str {
|
||||
match self {
|
||||
Self::Vec3 => "Vec3",
|
||||
@@ -42,6 +48,7 @@ impl Constructor {
|
||||
Self::Panel => "Panel3D",
|
||||
}
|
||||
}
|
||||
/// 取得本构造器对应的源工厂函数名称。
|
||||
pub fn function(self) -> &'static str {
|
||||
match self {
|
||||
Self::Vec3 => "vec3",
|
||||
@@ -58,6 +65,7 @@ impl Constructor {
|
||||
Self::Panel => "panel3D",
|
||||
}
|
||||
}
|
||||
/// 反查源构造器名称对应的原生 3D 种类,不认识的名称返回空值。
|
||||
pub fn from_function(name: &str) -> Option<Self> {
|
||||
[
|
||||
Self::Vec3,
|
||||
@@ -76,6 +84,7 @@ impl Constructor {
|
||||
.into_iter()
|
||||
.find(|kind| kind.function() == name)
|
||||
}
|
||||
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
|
||||
pub fn arity(self) -> (usize, usize) {
|
||||
match self {
|
||||
Self::Vec3 | Self::Triangle => (3, 3),
|
||||
@@ -87,6 +96,7 @@ impl Constructor {
|
||||
_ => (0, 0),
|
||||
}
|
||||
}
|
||||
/// 列出本构造器的参数类型名称,供签名安装与源调用检查使用。
|
||||
pub fn parameters(self) -> &'static [&'static str] {
|
||||
match self {
|
||||
Self::Vec3 | Self::Triangle => &["Number", "Number", "Number"],
|
||||
@@ -98,12 +108,14 @@ impl Constructor {
|
||||
_ => &[],
|
||||
}
|
||||
}
|
||||
/// 标记构造器是否接收数量可变的子对象。
|
||||
pub fn variadic(self) -> bool {
|
||||
matches!(self, Self::Group | Self::Scene)
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
/// 托管 3D 节点的名义种类,防止仅有同名字段的任意对象冒充场景节点。
|
||||
pub enum NodeKind {
|
||||
Vector,
|
||||
Triangle,
|
||||
@@ -117,40 +129,52 @@ pub enum NodeKind {
|
||||
Panel,
|
||||
}
|
||||
#[derive(Debug)]
|
||||
/// 允许普通属性的 3D 标记 payload;数值字段仍由托管属性系统拥有。
|
||||
pub struct Node(pub NodeKind);
|
||||
impl ObjectPayload for Node {
|
||||
/// 提供受检查的 Any 下转型入口,让宿主按具体 payload 类型读取数据。
|
||||
fn as_any(&self) -> &dyn std::any::Any {
|
||||
self
|
||||
}
|
||||
/// 返回运行时诊断/类型检查使用的稳定 payload 名称。
|
||||
fn kind_name(&self) -> &'static str {
|
||||
"scene-3d-object"
|
||||
}
|
||||
/// 声明此 payload 的赋值遵循引用身份语义,避免把内部宿主状态当作可复制值。
|
||||
fn reference_assignment_only(&self) -> bool {
|
||||
true
|
||||
}
|
||||
/// 声明此 payload 是否允许使用托管属性存储,具体字段仍由类型与调用检查约束。
|
||||
fn allows_attributes(&self) -> bool {
|
||||
true
|
||||
}
|
||||
}
|
||||
#[derive(Debug)]
|
||||
/// 托管不可变网格包装,顶点和三角形数值已经复制为原生 Arc 数据。
|
||||
pub struct Geometry(pub Arc<scene3d::Geometry>);
|
||||
impl ObjectPayload for Geometry {
|
||||
/// 提供受检查的 Any 下转型入口,让宿主按具体 payload 类型读取数据。
|
||||
fn as_any(&self) -> &dyn std::any::Any {
|
||||
self
|
||||
}
|
||||
/// 返回运行时诊断/类型检查使用的稳定 payload 名称。
|
||||
fn kind_name(&self) -> &'static str {
|
||||
"geometry-3d"
|
||||
}
|
||||
/// 声明此 payload 的赋值遵循引用身份语义,避免把内部宿主状态当作可复制值。
|
||||
fn reference_assignment_only(&self) -> bool {
|
||||
true
|
||||
}
|
||||
/// 声明此 payload 是否允许使用托管属性存储,具体字段仍由类型与调用检查约束。
|
||||
fn allows_attributes(&self) -> bool {
|
||||
true
|
||||
}
|
||||
}
|
||||
/// 统一构造本模块的参数错误,让调用方停止处理无效输入。
|
||||
fn invalid(message: &'static str) -> VmError {
|
||||
VmError::InvalidArgument(message)
|
||||
}
|
||||
/// 把源 Value 转换为受检查的托管对象引用,拒绝非对象输入。
|
||||
fn object_ref(value: &Value) -> Result<ObjectRef, VmError> {
|
||||
if let Value::Object(object) = value {
|
||||
Ok(*object)
|
||||
@@ -158,9 +182,11 @@ fn object_ref(value: &Value) -> Result<ObjectRef, VmError> {
|
||||
Err(invalid("3D field requires an object"))
|
||||
}
|
||||
}
|
||||
/// 在源 Value 与所需数值表示之间转换,并沿用本调用的有限值/范围检查。
|
||||
fn number(value: &Value) -> Result<f32, VmError> {
|
||||
crate::scroll::coordinate(value)
|
||||
}
|
||||
/// 把当前源值或文本选择解码成此调用需要的文本表示。
|
||||
fn text(value: &Value) -> Result<String, VmError> {
|
||||
if let Value::Text(text) = value {
|
||||
Ok(text.clone())
|
||||
@@ -168,6 +194,7 @@ fn text(value: &Value) -> Result<String, VmError> {
|
||||
Err(invalid("3D field requires text"))
|
||||
}
|
||||
}
|
||||
/// 把经过转换的数值写回指定托管字段,仍通过 VM/NativeContext 的检查入口。
|
||||
fn set_number(
|
||||
cx: &mut NativeContext<'_>,
|
||||
object: ObjectRef,
|
||||
@@ -176,6 +203,7 @@ fn set_number(
|
||||
) -> Result<(), VmError> {
|
||||
cx.set_attr(object, name, crate::native_visual::value(value))
|
||||
}
|
||||
/// 解析颜色值并检查其满足当前原生绘制约定。
|
||||
fn color(value: &str) -> Result<[f32; 3], VmError> {
|
||||
let color = crate::document::parse_color(value).map_err(|_| invalid("invalid 3D color"))?;
|
||||
if color.alpha != 255 {
|
||||
@@ -188,6 +216,7 @@ fn color(value: &str) -> Result<[f32; 3], VmError> {
|
||||
])
|
||||
}
|
||||
|
||||
/// 按构造器建立对应托管 3D 类型,检查几何输入并安装默认属性。
|
||||
pub fn allocate(
|
||||
cx: &mut NativeContext<'_>,
|
||||
desktop: ObjectRef,
|
||||
@@ -368,18 +397,22 @@ pub fn allocate(
|
||||
Ok(instance)
|
||||
}
|
||||
|
||||
/// 快照字段读取器,同时记录实际观察到的对象/属性依赖。
|
||||
struct Reader<'a> {
|
||||
store: &'a ObjectStore,
|
||||
reads: HashSet<(ObjectRef, String)>,
|
||||
}
|
||||
impl Reader<'_> {
|
||||
/// 读取字段并登记依赖,使后续字段变更能够使 3D 快照失效。
|
||||
fn value(&mut self, object: ObjectRef, name: &str) -> Result<Value, VmError> {
|
||||
self.reads.insert((object, name.into()));
|
||||
self.store.get_attr(object, name)
|
||||
}
|
||||
/// 在源 Value 与所需数值表示之间转换,并沿用本调用的有限值/范围检查。
|
||||
fn number(&mut self, object: ObjectRef, name: &str) -> Result<f32, VmError> {
|
||||
number(&self.value(object, name)?)
|
||||
}
|
||||
/// 连续读取三个数值字段,组成位置、旋转或缩放向量。
|
||||
fn vector(&mut self, object: ObjectRef, names: [&str; 3]) -> Result<Vec3, VmError> {
|
||||
Ok(Vec3::new(
|
||||
self.number(object, names[0])?,
|
||||
@@ -387,6 +420,7 @@ impl Reader<'_> {
|
||||
self.number(object, names[2])?,
|
||||
))
|
||||
}
|
||||
/// 读取并校验透视或正交摄像机字段,生成不持有 VM 引用的投影描述。
|
||||
fn camera(&mut self, object: ObjectRef) -> Result<Camera, VmError> {
|
||||
let projection = match self.store.payload::<Node>(object, "3D camera")?.0 {
|
||||
NodeKind::Perspective => Projection::Perspective {
|
||||
@@ -416,6 +450,7 @@ impl Reader<'_> {
|
||||
}
|
||||
}
|
||||
|
||||
/// 从场景中提取的有限 UI 根,携带稳定面板 key 和逻辑排版尺寸。
|
||||
pub struct PanelMount {
|
||||
pub key: u64,
|
||||
pub content: ObjectRef,
|
||||
@@ -426,6 +461,7 @@ pub type Snapshot = (
|
||||
Vec<(ObjectRef, String)>,
|
||||
Vec<PanelMount>,
|
||||
);
|
||||
/// 将当前托管或可变状态提取为后续阶段使用的派生表示。
|
||||
pub fn snapshot(
|
||||
store: &ObjectStore,
|
||||
scene: ObjectRef,
|
||||
@@ -433,6 +469,7 @@ pub fn snapshot(
|
||||
) -> Result<Snapshot, VmError> {
|
||||
snapshot_reusing(store, scene, camera, None)
|
||||
}
|
||||
/// 遍历场景并记录字段依赖;如果世界数据未变则复用不可变场景和 BVH,只替换摄像机视图。
|
||||
pub fn snapshot_reusing(
|
||||
store: &ObjectStore,
|
||||
scene: ObjectRef,
|
||||
@@ -615,6 +652,7 @@ pub fn snapshot_reusing(
|
||||
Ok((view, reader.reads.into_iter().collect(), panels))
|
||||
}
|
||||
|
||||
/// 把视口中的指针射线结果转换成 RayHit3D,关联实际托管网格和交点数据。
|
||||
pub fn pick(
|
||||
cx: &mut NativeContext<'_>,
|
||||
desktop: ObjectRef,
|
||||
@@ -706,6 +744,7 @@ pub fn pick(
|
||||
}
|
||||
|
||||
#[derive(Debug)]
|
||||
/// 指针拾取的中间结果,保留交点与所属实例信息供 Event/RayHit3D 使用。
|
||||
pub struct PointerPick {
|
||||
pub mount: ObjectRef,
|
||||
pub desktop: ObjectRef,
|
||||
@@ -713,6 +752,7 @@ pub struct PointerPick {
|
||||
}
|
||||
|
||||
/// The default controller is replaceable; camera data has no dependency on it.
|
||||
/// 为指定出现解码相机手势并调用控制器;嵌套面板输入先转换到所属视口坐标。
|
||||
pub fn control(
|
||||
cx: &mut NativeContext<'_>,
|
||||
controller: ObjectRef,
|
||||
@@ -809,6 +849,7 @@ pub fn control(
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// 执行托管 3D 节点的原生平移/旋转操作,供尚不支持普通数值算术表达式的源程序调用。
|
||||
pub fn transform(
|
||||
cx: &mut NativeContext<'_>,
|
||||
owner: ObjectRef,
|
||||
@@ -863,9 +904,11 @@ pub fn transform(
|
||||
Ok(())
|
||||
}
|
||||
impl endor_core::NativeCallable for PointerPick {
|
||||
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
|
||||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||||
Some(endor_core::CallArity::exact(0))
|
||||
}
|
||||
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
|
||||
fn invoke(
|
||||
&self,
|
||||
cx: &mut NativeContext<'_>,
|
||||
|
||||
Reference in New Issue
Block a user