From 7849dd9c1983295590b52317cbafe38dc3d483f5 Mon Sep 17 00:00:00 2001 From: wyc <1104749580@qq.com> Date: Thu, 20 Aug 2026 17:12:44 +0800 Subject: [PATCH] =?UTF-8?q?=E6=A0=B8=E5=BF=83=E7=AC=AC=E4=B8=80=E7=89=88?= =?UTF-8?q?=E4=BF=AE=E8=AE=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 3 +- Project_naming_conventions.md | 25 +++++++++++++++- kernel/src/kernel/renderable.hpp | 49 +++----------------------------- kernel/src/kernel/renderable.ipp | 45 +++++++++++++++++++++++++++++ kernel/src/kernel/scene.hpp | 23 +++------------ kernel/src/kernel/scene.ipp | 28 ++++++++++++++---- 6 files changed, 102 insertions(+), 71 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9d6b0a2..7cca283 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ \ae\proj\Aethera\cmake-build-vs2022_debug --target Aethera_Kernel_check -j 30 默认每次运行程序都通过CDB运行 D: \ae\ewdk\EWDK_22621_230929-1800\Program Files\Windows Kits\10\Debuggers\x64\cdb.exe -编译器环境脚本 C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\Tools\vsdevcmd\ext\VsDevCmd.bat +编译器环境脚本 C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\Tools\VsDevCmd.bat -host_arch=x64 -arch=x64 D:\ae\tools 可能会有有用的工具 @@ -16,6 +16,7 @@ D:\ae\tools 可能会有有用的工具 写函数 和模块使用下面的约定 [错误处理规范](./Error_handling_specification.md) [命名约定](./Project_naming_conventions.md) +[项目细节规范](./Project_detail_specification.md) 0. 跟你审计报告 就要大刀阔斧的改 一次性先把问题一次改完 在批量检查 要大步前进 1. 每个状态只能有一个权威来源，禁止在不同对象中重复保存并手工同步。 diff --git a/Project_naming_conventions.md b/Project_naming_conventions.md index 986b068..242a639 100644 --- a/Project_naming_conventions.md +++ b/Project_naming_conventions.md @@ -55,4 +55,27 @@ Low_Latency_Strategy.inl * 内部实现统一使用 `detail` 命名空间。 -**总规则：类型大写下划线，值和函数，成员变量小写下划线，字段注释保持行尾注释并且保持对齐** +## 普通字段注释 + +* 普通数据字段必须在声明同行使用 `/* ... */` 注释；不要为每个普通字段单独占用前一行。 +* 同一个结构体、类或连续字段分组内，行尾注释的起始列必须对齐。以该分组中最长的声明为基准，并至少保留一个空格。 +* 注释应说明字段的业务含义；存在单位、有效条件、触发时机、零值语义、所有权或生命周期约束时，必须一并写明。 +* 禁止只把字段名或类型换成中文重复一遍，也不要把与字段无关的实现流程写进字段注释。 +* 复杂不变量可在字段分组前增加块注释，但字段本身仍应保留简短、对齐的行尾摘要，避免为了塞入全部说明制造超长单行。 +* 函数、类型别名、嵌套类型和 CRTP 定制点不属于普通字段，应使用声明前注释说明契约。 + +```cpp +bool rebuilt{}; /* 本次提交是否重新构建任务图。 */ +std::uint64_t execution_time_ns{}; /* 本次执行耗时，单位为纳秒；未执行时为 0。 */ +``` + +## Private 实现放置 + +* 对外 `.hpp` 中只前置声明嵌套的 `struct Private;`，不得展开其字段、内部派发表、线程状态、缓冲角色或实现函数。 +* `Owner::Private` 的完整声明放在对应 `.ipp` 中；模板实现继续放在 `.ipp`，非模板实现可放在 `.cpp`。 +* 派生方可覆盖的 CRTP 函数和能力契约，必须在 `.ipp` 的 `Private` 完整声明处逐项注释；派生 `Private` 必须继承 `Prev_Private`。 +* 禁止在 `.hpp` 与 `.ipp` 各保留一份 `Private` 定义，也禁止为旧布局保留兼容转发层。 + +更完整的代码组织和设计约束见 [项目细节规范](./Project_detail_specification.md)。 + +**总规则：类型使用大写下划线；值、函数和成员变量使用小写下划线；普通字段使用对齐的同行注释；Private 的完整实现声明放在对应 `.ipp`。** diff --git a/kernel/src/kernel/renderable.hpp b/kernel/src/kernel/renderable.hpp index c218293..4cccd38 100644 --- a/kernel/src/kernel/renderable.hpp +++ b/kernel/src/kernel/renderable.hpp @@ -70,52 +70,11 @@ struct Renderable : Def, Tagg std::size_t paint_task_count{}; /* Paint 子图的任务数；数据模式固定为 1。 */ std::uint64_t prepare_execution_time_ns{}; /* 本次 Prepare 阶段实际执行耗时，单位为纳秒；未执行时为 0。 */ std::uint64_t paint_execution_time_ns{}; /* 本次 Paint 阶段实际执行耗时，单位为纳秒；未执行时为 0。 */ - bool operator==(const State&) const = default; /* 支持测试、快照比较和变更检测的逐字段相等比较。 */ - }; - struct Private : Prev_Private { - /* - * 派生 Renderable 的 Private 必须继承 Prev_Private，并为 Prepare/Paint 各提供一种能力： - * void prepare_data(T* object) 或 tf::Taskflow build_prepare_graph(T* object, const T::State& state)； - * void paint(T* object) 或 tf::Taskflow build_paint_graph(T* object, const T::State& state)。 - */ - using Run_Predicate = bool (*)(Root*, bool); - using Rebuild_Predicate = bool (*)(Root*); - using Stage_Run = void (*)(Root*); - using Graph_Builder = tf::Taskflow (*)(Root*); - using State_Get = State* (*)(Root*); - using State_Notify = void (*)(Root*); - struct Stage_Dispatch { - Run_Predicate predicate; /* 判断该阶段本次是否执行。 */ - Rebuild_Predicate rebuild_predicate; /* 判断已有阶段子图是否重建。 */ - Stage_Run run; /* 数据模式执行入口；子图模式为空。 */ - Graph_Builder builder; /* 子图模式构建入口；数据模式为空。 */ - }; - struct State_Dispatch { - State_Get get; /* 获取最终对象的 Renderable 状态层。 */ - State_Notify notify; /* 发布最终对象的 Renderable 状态。 */ - }; - struct Dispatch { - Stage_Dispatch prepare; /* Prepare 阶段分派。 */ - Stage_Dispatch paint; /* Paint 阶段分派。 */ - State_Dispatch state; /* Renderable 状态访问与发布分派。 */ - }; - const Dispatch* dispatch{}; /* 绑定最终对象类型后指向其静态分派表。 */ - std::unique_ptr prepare_graph; /* Prepare 子图模式的当前构建产物。 */ - std::unique_ptr paint_graph; /* Paint 子图模式的当前构建产物。 */ - bool prepare_graph_built{}; /* Prepare 子图是否至少成功构建过一次。 */ - bool paint_graph_built{}; /* Paint 子图是否至少成功构建过一次。 */ - /* CRTP 可覆盖：决定已构建的 Prepare 子图是否重建；默认返回 false。 */ - bool should_rebuild_prepare_graph(Attached auto* object, const State& state); - /* CRTP 可覆盖：决定已构建的 Paint 子图是否重建；默认返回 false。 */ - bool should_rebuild_paint_graph(Attached auto* object, const State& state); - /* CRTP 可覆盖：决定本次是否执行 Prepare；默认返回 dirty。 */ - bool should_prepare(Attached auto* object, const State& state, bool dirty); - /* CRTP 可覆盖：决定本次是否执行 Paint；默认返回 dirty。 */ - bool should_paint(Attached auto* object, const State& state, bool dirty); - /* CRTP 可覆盖：prepare_data(...) 完成后按派生类到基类顺序调用；默认不处理。 */ - void after_prepare_data(Attached auto* object); - /* Def::Private 的四个 State 生命周期 hook 同样可在派生 Private 中覆盖，并通过 State_Access::get() 访问状态层。 */ + /* 支持测试、快照比较和变更检测的逐字段相等比较。 */ + bool operator==(const State&) const = default; }; + /* 完整声明、内部派发以及 Prepare/Paint CRTP 能力契约见 renderable.ipp 中的 Renderable::Private。 */ + struct Private; private: /* 数据模式的内部调度入口：执行最终对象 prepare_data(...)，再触发各 CRTP 层 after_prepare_data(...)。 */ template diff --git a/kernel/src/kernel/renderable.ipp b/kernel/src/kernel/renderable.ipp index a6b0e8e..8960a73 100644 --- a/kernel/src/kernel/renderable.ipp +++ b/kernel/src/kernel/renderable.ipp @@ -1,6 +1,51 @@ #pragma once #include namespace aethera { +struct Renderable::Private : Prev_Private { + /* + * 派生 Renderable 的 Private 必须继承 Prev_Private，并为 Prepare/Paint 各提供一种执行能力。 + * Prepare 在编译期按能力选择：存在 build_prepare_graph(...) 时使用子图模式，否则使用 prepare_data(...)；两者同时存在时子图优先。 + * Paint 在编译期按能力选择：存在 build_paint_graph(...) 时使用子图模式，否则使用 paint(...)；两者同时存在时子图优先。 + * should_rebuild_prepare_graph(...) 和 should_rebuild_paint_graph(...) 只决定已选中子图模式后的重建时机，不负责选择模式。 + */ + using Run_Predicate = bool (*)(Root*, bool); + using Rebuild_Predicate = bool (*)(Root*); + using Stage_Run = void (*)(Root*); + using Graph_Builder = tf::Taskflow (*)(Root*); + using State_Get = State* (*)(Root*); + using State_Notify = void (*)(Root*); + struct Stage_Dispatch { + Run_Predicate predicate; /* 判断该阶段本次是否执行。 */ + Rebuild_Predicate rebuild_predicate; /* 判断已有阶段子图是否重建。 */ + Stage_Run run; /* 数据模式执行入口；子图模式为空。 */ + Graph_Builder builder; /* 子图模式构建入口；数据模式为空。 */ + }; + struct State_Dispatch { + State_Get get; /* 获取最终对象的 Renderable 状态层。 */ + State_Notify notify; /* 发布最终对象的 Renderable 状态。 */ + }; + struct Dispatch { + Stage_Dispatch prepare; /* Prepare 阶段分派。 */ + Stage_Dispatch paint; /* Paint 阶段分派。 */ + State_Dispatch state; /* Renderable 状态访问与发布分派。 */ + }; + const Dispatch* dispatch{}; /* 绑定最终对象类型后指向其静态分派表。 */ + std::unique_ptr prepare_graph; /* Prepare 子图模式的当前构建产物。 */ + std::unique_ptr paint_graph; /* Paint 子图模式的当前构建产物。 */ + bool prepare_graph_built{}; /* Prepare 子图是否至少成功构建过一次。 */ + bool paint_graph_built{}; /* Paint 子图是否至少成功构建过一次。 */ + /* CRTP 可覆盖：决定已选中子图模式的 Prepare 子图是否重建；object 为最终对象，state 为当前发布状态；默认返回 false。 */ + bool should_rebuild_prepare_graph(Attached auto* object, const State& state); + /* CRTP 可覆盖：决定已选中子图模式的 Paint 子图是否重建；object 为最终对象，state 为当前发布状态；默认返回 false。 */ + bool should_rebuild_paint_graph(Attached auto* object, const State& state); + /* CRTP 可覆盖：决定本次是否执行 Prepare；object 为最终对象，state 为当前发布状态，dirty 为 Prepare dirty；默认返回 dirty。 */ + bool should_prepare(Attached auto* object, const State& state, bool dirty); + /* CRTP 可覆盖：决定本次是否执行 Paint；object 为最终对象，state 为当前发布状态，dirty 为 Paint dirty；默认返回 dirty。 */ + bool should_paint(Attached auto* object, const State& state, bool dirty); + /* CRTP 可覆盖：prepare_data(...) 完成后按派生类到基类顺序调用；object 为最终对象；默认不处理。 */ + void after_prepare_data(Attached auto* object); + /* Def::Private 的四个 State 生命周期 hook 同样可在派生 Private 中覆盖，并通过 State_Access::get() 访问状态层。 */ +}; template void Renderable::run_prepare_data(Object* object) { auto& private_data = static_cast(object->d); diff --git a/kernel/src/kernel/scene.hpp b/kernel/src/kernel/scene.hpp index 81b28f7..5425b54 100644 --- a/kernel/src/kernel/scene.hpp +++ b/kernel/src/kernel/scene.hpp @@ -19,26 +19,11 @@ struct Scene : Def, Dependency_Graph_Ty std::size_t taskflow_max_predecessors{}; /* 当前总 Taskflow 中单个任务的最大直接前驱数量。 */ std::size_t taskflow_max_successors{}; /* 当前总 Taskflow 中单个任务的最大直接后继数量。 */ std::uint64_t taskflow_execution_time_ns{}; /* 本次 process(...) 执行总 Taskflow 的耗时，单位为纳秒；没有任务时为 0。 */ - bool operator==(const State&) const = default; /* 支持测试、快照比较和变更检测的逐字段相等比较。 */ - }; - struct Private : Prev_Private { - struct Result {}; /* process(...) 完成回调的结果类型；当前仅表示完成。 */ - struct Runtime; /* Scene 的 Taskflow 构建产物，定义保留在实现文件。 */ - std::unique_ptr runtime; /* Scene 唯一运行时构建产物的所有权。 */ - Private(); - ~Private(); - /* Def CRTP hook：所有缓冲推进后重建必要的总 Taskflow，并更新 Scene_State_Tag 状态层。 */ - template - void after_advance(Object* object, - Prop* pending_prop, - State_Access pending_states, - const Prop* current_prop, - State_Access current_states); - /* Impl CRTP 入口：同步执行当前总 Taskflow；派生 Private 只有在替换完整 Scene 处理语义时才应覆盖。 */ - template - void process(Object* object, Callback&& callback) requires std::invocable; - /* 派生 Scene 的 Private 还可覆盖 Def::Private 的四个 State 生命周期 hook，并通过 State_Access::get() 访问状态层。 */ + /* 支持测试、快照比较和变更检测的逐字段相等比较。 */ + bool operator==(const State&) const = default; }; + /* 完整声明、字段及可覆盖 CRTP hook 见 scene.ipp 中的 Scene::Private。 */ + struct Private; }; } #include "scene.ipp" diff --git a/kernel/src/kernel/scene.ipp b/kernel/src/kernel/scene.ipp index d7a03c7..24fa983 100644 --- a/kernel/src/kernel/scene.ipp +++ b/kernel/src/kernel/scene.ipp @@ -4,8 +4,26 @@ #include #include namespace aethera { +struct Scene::Private : Prev_Private { + struct Result {}; /* process(...) 完成回调的结果类型；当前仅表示完成。 */ + struct Runtime; /* Scene 的 Taskflow 构建产物；完整定义位于本文件下方。 */ + std::unique_ptr runtime; /* Scene 唯一运行时构建产物的所有权。 */ + Private(); + ~Private(); + /* Def CRTP hook：所有缓冲推进后重建必要的总 Taskflow，并更新 Scene_State_Tag 状态层。 */ + template + void after_advance(Object* object, + Prop* pending_prop, + State_Access pending_states, + const Prop* current_prop, + State_Access current_states); + /* Impl CRTP 入口：同步执行当前总 Taskflow；派生 Private 只有在替换完整 Scene 处理语义时才应覆盖。 */ + template + void process(Object* object, Callback&& callback) requires std::invocable; + /* 派生 Scene 的 Private 还可覆盖 Def::Private 的四个 State 生命周期 hook，并通过 State_Access::get() 访问状态层。 */ +}; struct Scene::Private::Runtime { - std::unique_ptr taskflow; + std::unique_ptr taskflow; /* 当前已构建的总 Taskflow；为空表示尚未构建。 */ }; template void Scene::Private::process(Object* object, Callback&& callback) requires std::invocable { @@ -62,10 +80,10 @@ void Scene::Private::after_advance(Object* object, detail::clear_stage_observers(&taskflow); taskflow.clear(); struct Stage_Tasks { - tf::Task prepare_entry; - tf::Task prepare_exit; - tf::Task paint_entry; - tf::Task paint_exit; + tf::Task prepare_entry; /* Prepare 条件任务，作为该阶段依赖入口。 */ + tf::Task prepare_exit; /* Prepare 完成任务，作为该阶段依赖出口。 */ + tf::Task paint_entry; /* Paint 条件任务，作为该阶段依赖入口。 */ + tf::Task paint_exit; /* Paint 完成任务，作为该阶段依赖出口。 */ }; std::pmr::unordered_map stage_tasks{resource}; for (auto* renderable : renderables) {