docs: clarify graphics resource and Block validation call paths

This commit is contained in:
2026-11-12 20:24:05 +08:00
parent 1f26349436
commit b44d7833ea
2 changed files with 16 additions and 2 deletions
+6
View File
@@ -3,6 +3,8 @@
//! Endor 源程序调用这些函数创建模型资源/绘图命令;source_paint 解码图片命令时调用 decode_image。
//! PointerDispatch 由 UiBridge::dispatch 包装成临时 callable,用同一 VM 分发原始指针事件。
//! 这里不定义应用剧情或按钮业务。像素资源经 Arc 共享,托管资源身份与引用边仍由 Aster 管理。
//! graphics.readText 是初始化用的同步 UTF-8 小文件读取(16 KiB);ui.readText 的后台任务接口另由 io_tasks 实现。
//! 图片命令经托管 image 属性拥有资源;source_paint 解码后只把 Arc 像素带入渲染命令,绘制线程无需访问 VM。
use crate::{
document::{RenderCommand, parse_color},
geometry::{Point, Rect},
@@ -299,6 +301,7 @@ impl NativeCallable for Function {
Value::Object(resource)
}
LoadFont => {
// 不仅文件读取有副作用,register_font 还会修改字体注册表,因此布局/绘制只读回调也不能加载字体。
if cx.store().is_read_only() {
return Err(invalid("load resources outside paint/layout"));
}
@@ -584,7 +587,9 @@ impl NativeCallable for Function {
fn ranges(left: f32, right: f32, y: f32, line: f32, exclusions: &[&Exclusion]) -> Vec<(f32, f32)> {
// 每个形状先贡献一个阻塞区间;最后统一排序/扫线,支持多个重叠障碍。
let mut blocked = Vec::new();
// 按资源分别求本行投影;不修改 Exclusion,使同一障碍可被多个 Flow 调用和不同文本列共享。
for e in exclusions {
// 圆直接求解析弦宽;矩形/图片轮廓的 circle 为 None,继续交给下面的多边形边遍历。
if let Some((p, r)) = e.circle {
// 行带包含圆心时 gap=0,否则为圆心到最近水平边的垂直距离。
let gap = (y - p.y).max(p.y - y - line).max(0.);
@@ -607,6 +612,7 @@ fn ranges(left: f32, right: f32, y: f32, line: f32, exclusions: &[&Exclusion]) -
// 行带覆盖的顶点直接参与水平包围,避免水平边/角点没有穿越交点时被漏掉。
xs.push(a.x);
}
// 同一条斜边可能跨越行带的上下两边,两个交点都要计入横向包围,不能找到一个就停止。
for edge in [top, bottom] {
if (a.y < edge && b.y > edge) || (b.y < edge && a.y > edge) {
// 只有真正跨过水平边界才插值,分母 b.y-a.y 在此条件下非零。
+10 -2
View File
@@ -427,6 +427,9 @@ pub fn resolve_tracked(
/// Validate the entire finite expansion before establishing a new composition
/// edge. The node count is an explicit rejected resource quota, not truncated UI.
/// 完整展开 Block/Cell/孩子图,拒绝环、禁止目标回边及超过 10000 次展开的组成。
/// allocate/Scene3D 面板构造传 None,只检查已有图;共享赋值传目标 Cell,
/// Children 的 append/insert/replace 和 Page 的 render/navigate 则传目标 Data。
/// 因此 forbidden_state 虽沿用 state 名称,实际可以是 Cell 或 Data 身份;二者都不能在新子图中出现。
pub fn validate(
store: &ObjectStore,
root: ObjectRef,
@@ -472,7 +475,8 @@ pub fn validate(
let Value::Object(value) = store.cell_get(state)? else {
return Err(VmError::InvalidArgument("invalid Block state"));
};
// Cell 当前值若直接指向将被修改的禁用目标,同样形成回边,不能只比较当前 Cell。
// Children/Page 编辑传入的是 Data 身份,要在此比较 Cell 的值;共享赋值传入的 Cell 已在上方比较。
// 例如给容器追加它自己的别名时,包装身份可能不同,最终 Data 相同仍须拒绝。
if forbidden_state == Some(value) {
return Err(VmError::InvalidArgument(
"Block composition would create a cycle",
@@ -502,6 +506,8 @@ pub fn snapshot(store: &ObjectStore, root: ObjectRef) -> Result<Arc<UiNode>, VmE
/// Native visual parameters are ordinary managed attributes too. Composition,
/// histories and connections remain structural payload edges.
/// 列出本类型可投影到托管属性的原生字段及默认值。
/// allocate 用返回值初始化 properties;visual_data 用字段名重读当前值;RenderCache 用同一集合登记精确失效依赖。
/// 新增原生视觉字段时需同时补这里与 apply_visual_property,否则可能出现可解码但不进入快照/缓存观察的字段。
pub fn native_properties(data: &Data) -> Vec<(&'static str, Value)> {
/// 把已有 f32 默认字段编码为源 Number;这里不做范围校验,读取解码由 apply_visual_property 处理。
fn number(value: f32) -> Value {
@@ -643,7 +649,7 @@ pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
let properties = data
.properties
.ok_or(VmError::InvalidArgument("missing Block properties"))?;
// 字段集合由原生种类确定,每项从当前存储读取,保留业务属性依赖以驱动后续失效。
// 字段集合由原生种类确定,每项从当前存储读取;RenderCache 调用方另用同一字段集合登记精确缓存依赖。
for (name, _) in native_properties(&data) {
// 借用读取的源值先解码到副本,错误不会反写已存在的业务描述。
let value = store.get_attr(properties, name)?;
@@ -707,6 +713,8 @@ pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
}
/// 按属性名检查和解码源值,再更新对应视觉字段;非法尺寸、枚举或颜色被拒绝。
/// binding::refresh 在写入托管属性前用副本试解码;visual_data 在全量覆盖后另查 min/max 和视口协议。
/// 本函数只验证本次值并更新传入 Data,不自行写 properties,也不保证多个相关字段组合起来一定合法。
pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Result<(), VmError> {
// 绑定刷新在写回前、visual_data 在读取时调用本解码器;通用类型/范围失败统一为视觉属性错误。
let bad = || VmError::InvalidArgument("invalid native visual property");