diff --git a/.planning/documentation/guide.md b/.planning/documentation/guide.md new file mode 100644 index 0000000..5dc7a5f --- /dev/null +++ b/.planning/documentation/guide.md @@ -0,0 +1,142 @@ +# 指南文档编写规范 + +## 适用范围 + +本规范适用于 `docs/` 下面向使用者的指南文档,包括教程、渲染指南、系统说明和扩展说明。API 自动生成页、计划文档、流程记录不直接适用本规范。 + +阶段 CONTEXT 中的局部决策优先于本规范;本规范负责沉淀所有指南文档通用的写作要求。`guide.md` 与 `workflow.md` 是文档工作的统一入口。 + +## 文档目标 + +文档的目标是让读者能完成任务,而不是展示作者知道多少。 + +- 读者读完应知道怎么用、怎么改、怎么写能运行,以及常见错误怎么处理。 +- 原理只讲到“足够正确使用”为止;读者不需要的实现细节不写。 +- 文档不是源码导读,不逐段解释源码,也不按代码目录或接口清单组织。 +- 内容重心由内容性质决定:现成能力重点讲怎么用,扩展机制重点讲怎么自定义。 + +## 读者与取舍 + +- 先判断目标读者是谁、读者已经读过什么、这篇文档要解决什么问题。 +- 只写读者真正需要知道的内容。能删就删,不追求面面俱到。 +- 不写罕见边界、极低概率异常、需要刻意构造的情况。 +- 不写“我之前改好了”“文档站没有环境”“不要现场 new Texture”这类修复过程、问题复盘或元叙述。 +- 不把用户提出的问题、审阅意见或“为了解决问题所以这样写”抄进正文。 +- 不写“源码怎么怎么样”。除非某段行为模型是理解用法所必需的,否则不要讲实现。 +- 必须讲的行为模型要讲清,例如状态机如何读取状态、曲线如何把时间进度映射为数值变化。 +- 可以写应用场景,但必须能从接口语义、限制或代价推导出原因;不得凭空写“常用于”“只用于”。 +- 不假设某个曲线、模式或接口适合什么场景;只客观描述形状、速度和端点行为。 + +## 结构顺序 + +按读者的理解顺序组织,不按代码目录或 API 清单组织: + +`问题或场景 → 系统模型 → 机制与原因 → 接口与用法 → 示例 → 少量边界 → 总结` + +- 讲一个系统时,先讲模型是什么(概念、组成、角色、数据流),再讲接口。 +- 每个章节只回答一个问题;不同消费者、不同阶段分开讲。 +- 只在认知跳跃大的地方用一两句话承接,不硬加“接下来我们……”式过渡。 +- 复杂接口必须按使用顺序拆开:为什么需要 → 先获取什么 → 最小示例 → 示例做了什么 → 下一步做什么 → 再给下一个示例 → 最后才是完整用法。 +- 简单接口可以短,但不能只列签名。 +- 模板不要放在开头。先讲概念和扩展点,再给引导语、模板代码、模板说明。 +- 只有读者需要自己实现接口或注册内容时才给模板;纯接口使用只给示例。 +- 纯内部实现章节要靠后,并明确本章讲的是内部实现;文档前半部分先讲怎么用。 +- 高级教程按库文档方式写,可用示例加解释;中级教程的“复制什么 / 改什么”六步法不要套到高级教程。 + +## 标题 + +- H2/H3 一律使用短名词短语。 +- 不用句子、祈使句、问句,也不用“标题:一句解释”这种冒号扩展。 +- 标题只说明“这一段讲什么”,不承担章节摘要的作用。 +- 不写“第一步”“用 set 让它动起来”“拿到控制器”这种步骤式或口语化标题;步骤放在正文列表里。 +- 文件名与目录名使用连字符英文命名。 + +## 接口讲解 + +每个接口、成员或类型第一次出现时,按以下顺序说明: + +1. 为什么当前场景需要它;不用它会缺什么。 +2. 它的名称、类型或形态。 +3. 它的用途和关键限制。 +4. 最小示例或参数说明。 + +不得上来就贴签名、参数表和“它能做什么”。不得只列接口名并假设读者已经知道。 + +- 只写用户会使用的接口;引擎内部接口、内部成员不写进用户文档。 +- 常用接口放主要位置,不要塞进“其他接口”。 +- 状态驱动的系统必须讲清:哪些操作改变状态,哪些读取操作默认读取哪一个状态。 +- 源码注释与实现不一致时,以方法注释为准,并在对话中报告;不把不一致写进正文。 +- 编辑器、`.jsonc` 等尚未完全就位的内容,按“编辑器已经完成”写;不要写过渡做法。 + +## 示例与 live + +### 代码示例 + +- 示例必须完整、结构正确,能与上下文一起运行;不要给脱离上下文的成员片段。 +- 类、函数、文件级片段要保留完整结构;必要时用注释省略无关部分。 +- UI 示例遵循项目标准模板;完整示例包含 imports、props、组件和 `FULL_LOC`,简化示例使用 `// setup` + `// 组件内容`。 +- `value` 双向绑定统一写 `v-model:value`;其他 prop 写 `v-model:prop`。 +- 教程中的实操按“目标 → 改哪里 → 复制什么 → 改什么 → 怎么验证 → 注意”组织;示例取最短可行路径。 +- 内容较杂的功能按功能拆分示例,一个功能一段,不合并成一大块。 +- 每个示例前说明它是什么、要演示什么;不要突然丢代码。 +- 完整代码放在最后;前面用最小示例逐步建立。 + +### 注释 + +- 注释解释当前状态、意图、结果或关键行为,不逐行翻译语法。 +- 复杂流程的链式代码可在行尾注释当前对象、索引、锚点和本行作用。 +- 注释服务于理解;不要为了“注释多”堆无信息量的句子。 + +### live 与图 + +- live 放在对应知识点旁边,不能只在文末放一个综合 live。 +- 需要看效果的接口、属性、状态变化各自配 live;复杂时序优先拆成“时间轴”和“播放效果”两个视角。 +- 动画、交互、状态变化不要用 CSS 定时器伪造;使用真实执行器。 +- 渲染树、事件流、数据流、状态机、组件拆分、完整示例步骤等结构或流程,用 mermaid 图表达;图放在机制小节开头或示例前,配一两句说明。 +- 视觉变化、布局、材质、几何关系适合用效果图或白板图;数字堆砌不能代替可视解释。 +- 不要把多个互不相同的示例塞进一个 live;一个示例至少有一个独立 live。 + +## 语言与术语 + +- 用普通开发者能直接理解的中文;优先短句和具体动作。 +- 专用名词首次出现必须解释它是什么、在这篇文档里指什么;能不用术语就不用。 +- 不引入“插值”“句柄”“上游/下游”等未解释术语;必须使用时要给出普通解释。 +- 可读性优先于形式上的绝对准确;不为了准确堆复杂公式、限定条件或底层计算。 +- 不写“适合位移/淡入淡出/蓄力/脉冲”这样的用途假设;只写客观形状和效果。 +- 加粗内容不要以标点开头或结尾,避免 CommonMark 边界导致不渲染。 + +## 边界与注意事项 + +- 边界与特殊情况集中放在文末,不混入主干。 +- 只写真正会影响使用、容易触发或容易误解的问题。 +- 不重复正文已经讲过的流程,不写“必须先选择对象”这种显而易见的提醒。 +- 不写没有依据的约束,例如“计划定义完要尽快 planEnd”。 +- 如果没有值得写的边界,就不开这一节,不要为了章节完整而凑内容。 + +## 正确性与验证 + +- 写文档前先理解完整设计、调用链和生命周期,不只读被讲到的一段代码。 +- 每次修改前按站点阅读顺序读完目标之外的全部现有文档;目的是理解分工和写作风格,不是只读目标页。 +- 写之前核对源码、接口、默认值、可空性和实际行为;构建通过不等于语义正确。 +- 写完后跑 prettier,再跑文档构建,检查死链。 +- 修订循环不逐轮提交;用户明确确认后再统一提交。 + +## 审阅流程 + +1. 骨架检查:第二个子代理只检查内容合理性和规范符合性;最多修订三次,仍不通过则停止汇报。 +2. 用户审阅:骨架和最终文档都由用户审阅;用户按自己的阅读体验提出意见,AI 只改用户点名内容。 +3. 审阅只分骨架检查和用户审阅两层;用户确认前不宣称完成。 + +## 参考文档 + +`.planning/references/feishu-teaching-docs/` 中的教学文档只用于观察行文思路、信息密度、示例和图示的放置方式,不是内容模板,也不是当前项目文档的正确性来源。 + +参考时重点看: + +- 开头先给目标和效果,再进入步骤。 +- 概念之后马上给最小示例,示例之后说明发生了什么。 +- 视觉变化用效果图或图解释,不靠文字堆。 +- 暂时不需要的底层内容明确后置,不为了完整而展开。 +- 结尾有总结和下一篇的衔接。 + +不要照搬参考文档的编号、标题风格或具体结构;当前项目仍按本规范和阶段 CONTEXT 执行。 diff --git a/.planning/documentation/pending-issues.md b/.planning/documentation/pending-issues.md new file mode 100644 index 0000000..99300af --- /dev/null +++ b/.planning/documentation/pending-issues.md @@ -0,0 +1,19 @@ +# 文档待处理问题 + +## 2026-11-19 22:10 + +状态:仅记录,未执行(按 22:00 停止规则)。 + +### 动画激励页面的执行器内容 + +- 目标文档:`docs/render-guide/internals/animation-excitation.md` +- 问题:动画激励页面讲了 `useAnimater` 与 `useTransition`,这两个接口与动画激励本身关系不大。 +- 处理:已删除 `useAnimater` / `useTransition` 相关章节及引用,激励页只保留激励内容。 +- 状态:已处理(2026-11-20)。 + +### `onExcited` 与 `onExcitedFunc` 的章节合并 + +- 目标文档:`docs/render-guide/internals/animation-excitation.md` +- 问题:`onExcited` 与 `onExcitedFunc` 被合并在同一个章节;一个章节应只讲一个内容,除非两者概念几乎重叠且内容极少。 +- 处理:已拆为 `登记受激励对象 onExcited` 与 `包装函数 onExcitedFunc` 两个独立小节。 +- 状态:已处理(2026-11-20)。 diff --git a/.planning/documentation/workflow.md b/.planning/documentation/workflow.md new file mode 100644 index 0000000..51ab511 --- /dev/null +++ b/.planning/documentation/workflow.md @@ -0,0 +1,249 @@ +# 指南文档编写流程 + +## 总则 + +指南文档按三个阶段推进,不得跳阶段: + +1. 讨论阶段:确定要写什么、分成几篇。 +2. 文档骨架:每篇先写人类可读的骨架,检查并修订,交由用户审阅。 +3. 文档编写:骨架获用户明确确认后,才开始写正文,并进入用户审阅循环。 + +文档正文必须由子代理编写或修改,主代理不得内联落盘(阶段 CONTEXT 的豁免条款除外)。任何阶段都不得提前写正文。 + +## 阶段一:讨论 + +### 输入 + +用户给出需要写成文档的内容、目标读者和大致范围。 + +### 讨论内容 + +- 这批内容要解决什么问题。 +- 应该拆成几篇文档,每篇的边界是什么。 +- 每篇的目标读者、前置知识和阅读顺序。 +- 哪些内容写进文档,哪些留给其他篇目或后续阶段。 +- 哪些内容适合代码示例、mermaid、效果图、live。 +- 哪些术语需要专门解释。 + +### 输出 + +一份文档清单,包含: + +- 每篇文档的暂定标题和文件路径。 +- 每篇的职责与不负责的内容。 +- 与其他文档的衔接关系。 +- 尚未决定、需要用户裁决的问题。 + +### 约束 + +- 讨论阶段由用户主导。主代理先听用户说明,不抢先用子代理探索需求或自行拆分。 +- 讨论没有确认文档拆分前,不进入骨架阶段。 +- 不写标题以外的正文,不写示例,不写 live。 + +## 阶段二:文档骨架 + +### 骨架目标 + +骨架是写给用户审阅的文档设计图,不是正文草稿。它要让人一眼看出这篇文档准备怎么教、每一节讲什么、示例和 live 放在哪里、哪些内容明确不写。 + +骨架必须人类可读,避免把提示词、长篇分析或源码摘录塞进去。 + +### 骨架文件位置 + +默认放在当前阶段的 `skeletons/` 下: + +```text +.planning/phases//skeletons/.md +``` + +如果当前任务不属于某个阶段,放在 `.planning/documentation/skeletons/.md`。 + +### 骨架格式 + +每篇骨架使用以下结构。标题层级最深到三级,骨架本身不展开正文。 + +```markdown +# <文档标题> 骨架 + +## 文档信息 + +| 项目 | 内容 | +| ------------ | ----------------------------------------------- | +| 文件路径 | `docs/.../xxx.md` | +| 目标读者 | ... | +| 前置知识 | ... | +| 前后衔接 | 上一篇讲什么;本篇接什么;下一篇讲什么 | +| 本篇目标 | 读者读完后能做什么 | +| 不负责的内容 | ... | +| 状态 | 骨架待审 / 骨架已确认 / 正文编写中 / 待用户审阅 | + +## 读者问题 + +- 读者读这篇之前通常会问什么。 +- 读完后应该能回答什么。 +- 哪些问题明确不在本篇回答。 + +## 章节结构 + +### 1. <章节标题> + +- **目的**:这一节要让读者明白什么。 +- **内容**:要讲的概念、机制、接口和步骤。 +- **衔接**:上一节留下什么问题,这一节如何接上。 +- **重点**:读者最需要记住的内容。 +- **不写**:这一节明确不展开的内容。 + +#### 1.1 <三级标题> + +- **目的**:... +- **内容**:... +- **示例**:几个;每个示例是什么;是完整示例还是最小示例。 +- **live / 图**:是否需要;展示时间轴、播放效果、结构还是流程。 +- **术语**:需要解释哪些词。 +- **衔接**:讲完后如何进入下一节。 + +### 2. <章节标题> + +... + +## 示例计划 + +| 编号 | 所在章节 | 示例是什么 | 示例目的 | 代码范围 | live / 图 | 放在哪里 | +| ---- | -------- | ---------- | -------- | --------------------------- | --------- | -------- | +| E1 | ... | ... | ... | 完整类 / 最小片段 / 完整 UI | ... | ... | + +## live 计划 + +| 编号 | 所在章节 | 展示内容 | 类型 | 与正文的关系 | +| ---- | -------- | -------- | ---------------------------- | ------------ | +| L1 | ... | ... | 时间轴 / 播放效果 / 结构交互 | ... | + +## 图表计划 + +| 编号 | 所在章节 | 图类型 | 要说明的结构或流程 | +| ---- | -------- | ------------------------- | ------------------ | +| D1 | ... | mermaid / 效果图 / 白板图 | ... | + +## 术语表 + +| 术语 | 首次出现位置 | 普通解释 | 是否必须使用 | +| ---- | ------------ | -------- | ------------------------- | +| ... | ... | ... | 是 / 否,能否换成普通说法 | + +## 内容边界 + +- **必须写**:读者完成任务必需的内容。 +- **可以简写**:只需一句带过的内容。 +- **明确不写**:内部实现、罕见边界、其他文档已讲清的内容。 +- **留给其他文档**:哪些内容转到哪一篇。 + +## 验收标准 + +- 读者读完后能完成什么操作。 +- 读者应该能复述哪些模型或状态关系。 +- 哪些示例必须能独立运行。 +- 哪些 live 必须真实反映行为。 + +## 未决问题 + +- 需要用户裁决的拆分、命名、范围或示例选择。 +``` + +### 骨架检查 + +骨架完成后,派第二个子代理检查。检查者只做两件事: + +1. **内容合理性**:该讲的有没有讲,不该讲的有没有写;章节顺序、示例数量、live 和图表是否服务目标;有没有明显的内容缺口或越界。 +2. **规范符合性**:是否违反 `guide.md`、本流程和当前阶段 CONTEXT 中的文档要求,包括标题、读者取舍、接口引入、示例完整性、术语解释、live 放置和边界处理。 + +检查结果写回骨架末尾或独立检查记录,至少包含: + +- 阻断问题。 +- 非阻断建议。 +- 是否符合规范。 +- 需要用户裁决的问题。 + +### 修订循环 + +- 根据检查结果修订骨架。 +- 修订后再次检查。 +- 最多循环三次。 +- 三次后仍有阻断问题,停止并汇报具体问题,不再自行循环。 + +### 用户审阅 + +骨架通过内部检查后交给用户审阅。用户确认前不得开始写正文。 + +用户审阅的重点是: + +- 文档拆分是否合理。 +- 章节是否覆盖目标,是否有明显多余内容。 +- 示例、live 和图表是否足够且位置正确。 +- 读者关心与不关心的内容划分是否正确。 +- 标题和术语是否符合预期。 + +## 阶段三:文档编写 + +### 开始条件 + +必须同时满足: + +- 骨架已通过内部检查。 +- 用户已明确确认骨架。 + +未满足时不得编写正文,也不得派发正文编写子代理。 + +### 编写要求 + +- 按骨架写,不擅自增删章节或改变文档拆分。 +- 先读 `guide.md`、当前阶段 CONTEXT、目标文档之外的全部现有文档,再读目标文档和相关源码。 +- 复杂接口按“为什么 → 获取什么 → 最小示例 → 说明 → 下一步”的顺序写,不能写成 API 参考。 +- 每个示例前说明它是什么;示例后说明发生了什么。 +- live 就近放置;复杂时序优先拆时间轴和播放效果两个视角。 +- 只写对使用有帮助的行为模型,不写内部实现和罕见边界。 +- 标题使用短名词短语,不写步骤式或口语化标题。 +- 写完跑 prettier、文档构建和死链检查。 + +### 用户审阅循环 + +- 骨架阶段由用户审阅骨架;正文阶段由用户审阅最终文档。 +- 用户提出意见后,由子代理逐条修改;不擅自扩大修改范围。 +- 循环直到用户明确表示满意。 +- 用户确认前不宣称完成,不写 SUMMARY,不更新 ROADMAP 或 STATE,不提交。 + +## 角色分工 + +| 角色 | 职责 | +| ---------- | -------------------------------------------------------- | +| 用户 | 主导讨论、确认文档拆分、审阅骨架、审阅最终文档、裁决争议 | +| 主代理 | 组织阶段、派发子代理、汇总检查结果、保证流程不跳阶段 | +| 骨架编写者 | 按模板写人类可读的骨架 | +| 骨架检查者 | 只检查内容合理性与规范符合性,不改正文 | +| 文档编写者 | 按已确认骨架写正文,按用户意见修订 | + +## 子代理上下文包 + +每个新任务必须新开子代理,不得复用已完成任务的子代理会话,避免上下文污染。唯一例外:子代理因规则冲突或安全限制在读取、修改前提前返回,可以续用该未执行会话。 + +每次派发文档子代理前,任务提示必须包含以下上下文;缺任何一项都不得派发: + +- 必读 `.planning/documentation/guide.md`。 +- 必读 `.planning/documentation/workflow.md`。 +- 必读当前阶段 CONTEXT,例如 `.planning/phases/10-docs-restructure/10-CONTEXT.md`。 +- 涉及正文修改时,按 D-115 读完全部现有文档,并说明阅读目的;任务中写明阅读范围,子代理回报实际读过的文档与结构判断。 +- 目标文件的完整路径,以及明确禁止修改的文件范围。 +- 需要核对的源码路径;内容写作任务必须核对源码,不能只读旧文档。 +- 本次要解决的问题、验收标准、需要运行的格式化与构建命令。 +- 明确禁止 commit,除非用户当次明确要求。 +- 明确要求子代理先完成阅读,再开始修改;未读或未说明阅读范围即视为不合格。 + +骨架检查子代理的上下文包额外包含: + +- 目标骨架文件路径。 +- 本次骨架对应的文档拆分与用户已确认的边界。 +- 检查只做内容合理性与规范符合性两件事,不直接改正文。 +- 输出阻断问题、非阻断建议、规范结论和需要用户裁决的问题。 + +## 参考材料 + +`.planning/references/feishu-teaching-docs/` 是写作风格参考,只用于观察如何安排目标、示例、图示和章节过渡,不作为当前项目文档的事实来源,也不要求照搬其结构或标题。 diff --git a/.planning/phases/10-docs-restructure/10-CONTEXT.md b/.planning/phases/10-docs-restructure/10-CONTEXT.md index c104a69..befa7c1 100644 --- a/.planning/phases/10-docs-restructure/10-CONTEXT.md +++ b/.planning/phases/10-docs-restructure/10-CONTEXT.md @@ -281,6 +281,21 @@ - **D-113(接口必须先说明是什么):** 文档里出现任何接口、成员或类型时,必须先说明它的名称、类型/形态和用途,再讲它能做什么;不能只列接口名并假设读者已经知道。不要把引擎内部接口、内部成员写进用户文档;用户常用接口按使用频率放在主要位置,不要塞进“其他接口”。 - **D-114(excitation 执行顺序与 transition 端点判断):** excitation 执行不同激励对象的顺序不保证;在 `onExcitedFunc` 中用“当前值是否等于 min/max 端点”来决定下一目标,可能在起始帧设置目标后、Transition 尚未推进时,下一帧又因当前值仍在端点而重复设置同一目标,导致动画永远停在起点。`Selection` 的 alpha 来回切换就是典型案例。这是系统“设置当帧不改变值”的既定行为,不是系统 bug,只能在实现层规避:不要用当前值等于端点作为切换条件,改用独立状态、方向变量或事件驱动;后续文档涉及 `Selection`、`Transition`、`onExcitedFunc` 动画时需专门提醒。 - **D-115(文档修改前的全量阅读,强制,不得再遗漏):** **任何文档修改子代理在动手前,必须先按文档站阅读顺序完整读完目标文档之外的全部现有文档**:中级 → 高级 I → 高级 II 现有数据端/其他已存在篇目 → 高级 III → 其他非目标文档;读完后才能读目标文档和相关源码。**未完成全量阅读不得修改,不得以“只读了相关源码/目标页”代替。** 每次派发任务必须把本要求原文写入任务,并**明确说明阅读目的**:一是了解项目整体结构、已讲概念与文档分工,避免写出与现有内容脱节的说明;二是对齐文档的写作风格、详略、示例、标题、术语与表格形式,避免只读目标页造成风格偏差。**不得只列阅读清单而不说明目的,也不得把“读文档”本身当成任务。** 要求子代理在回报中列出已读文档范围及对结构与风格的实际判断;未列出、未读全或未说明目的的改动一律视为不合格,必须重做。此条与 D-94 的读者全量阅读要求并列,适用于所有文档修改子代理,**不得以时间、并行、上下文限制或任务简单为由跳过**。 +- **D-116(文档编写豁免 GSD,用户主导的子代理循环):** 文档编写/修改不再要求 GSD 的 Plan → Execute → Verify,不为此创建计划,也不派 `gsd-planner` / `gsd-plan-checker` / `gsd-executor`。但**文档仍必须由主代理派发子代理编写/修改**,不能由主代理内联落盘。流程改为「主代理派发子代理写/改 → 用户审阅 → 主代理按意见再派子代理修订」的循环;可随时中断和继续,不写 SUMMARY / ROADMAP / STATE,除非用户明确要求收尾或记账。**每次派发文档编写/修改子代理时,任务里必须明确要求它先读 `.planning/phases/10-docs-restructure/10-CONTEXT.md`(至少 D-115、D-116 和相关写作规则),再按 D-115 原文完成“现有文档全量阅读 + 明确阅读目的”,并在回报中列出已读范围与对结构/风格的实际判断;不得只把目标文档和源码给它。** D-115 的强制全量阅读适用于文档内容写作子代理;纯结构迁移/路径调整不强制全量阅读。内容准确性、源码核对(D-104)、写作风格、示例标准、标题/参数表等文档内容规则仍然适用。 +- **D-117(可读性优先于绝对准确性):** 文档解释概念、接口与行为时,优先使用读者能直接理解的语言和例子;**不得为了追求形式上的绝对准确而引入复杂公式、术语、冗长限定或底层计算过程**。能一句话说清就不展开“进度怎么算、当前值怎么插值、曲线终值如何代入”等读者不关心的细节;必要的技术说明放在不会增加理解负担的位置。贯穿所有文档、示例和“边界与注意”章节,不只是动画文档。 +- **D-118(讲接口前必须先讲“为什么需要它”):** **不得上来就介绍接口签名、参数和用法。** 每个接口(包括 `animate`、`to`、`curve`、`after`、`when`、`planEnd`、`bindExcitation`、`useAnimater`、`useTransition` 等)在正式说明前,必须先有一句上下文:当前场景要解决什么问题、为什么非它不可、不用它会怎样。没有这句引入就直接开始讲接口,视为不合格,必须补充。该要求与 D-117 一起适用所有文档。 +- **D-119(“获取执行器/绑定”与“选择动画对象”分开):** “获取执行器与绑定”指自己 `new Animater`、`bindExcitation`,或在组件里使用 `useAnimater`;这部分应放在计划模型之前,让读者先知道执行器从哪里来。`animate(content: IAnimatable)` 是“选择动画对象”,必须在计划模型之后再讲,并使用类似“为了让动画系统知道把当前值写进哪个对象,需要先绑定动画对象”的引入;不得把 `animate` 混入“获取执行器”小节。 +- **D-120(指南文档必须一步步教,不能写成 API 参考):** 复杂接口的指南文档**不允许**采用“先讲接口能干什么,再给一个完整大示例”的 API 参考写法。必须拆成使用顺序:为什么需要 → 先拿到什么对象 → 最小可运行示例 → 示例刚刚做了什么 → 下一步做什么 → 再给下一个示例 → 最后才是完整用法。简单接口可以短,但复杂接口(如 `transitioned`、`transitionedColor`、`cycledTransition`、Animater 编排)必须按步骤展开。所有指南文档都要按此自查。 +- **D-121(术语首次出现必须解释):** 任何专用名词(如“上游/下游”“激励源”“变速器”“插值”等)首次出现时,必须用普通开发者能理解的中文说明它是什么、在这篇文档里指什么;能不用术语就不用。不得假设读者已经知道术语含义。此条与 D-117 并列,适用于所有文档。 +- **D-122(曲线模式只描述形状,不假设用途):** `CurveMode` 和各曲线的说明只客观描述形状、速度分布、端点行为,**不得写“适合位移/淡入淡出/蓄力/脉冲”等使用场景假设**。读者自己决定用在哪里。 +- **D-123(执行器状态机必须讲清):** Animater 是状态驱动的执行器,文档必须说明哪些接口会改变内部状态(选择对象、设置曲线、写步骤、设置触发点、提交计划组等),以及 `to`、`query`、`wait` 等读取接口默认读取的是“当前计划组”“当前选中对象”“当前执行组”中的哪一种状态。不能只列接口而不讲状态依赖。 +- **D-124(D-117 不删除必要的行为模型):** D-117 反对的是读者不需要的底层实现细节,不是反对所有原理。读者理解用法所必需的行为模型必须讲清,例如曲线如何把时间进度映射为数值进度、执行器如何根据状态决定写哪个对象;用简单语言讲,不堆公式和实现细节。 +- **D-125(通用文档规范独立成文):** 通用指南文档规则统一整理到 `.planning/documentation/guide.md`;后续编写或修改指南文档先读该文件。本 CONTEXT 中仍然保留通用规则的历史决策,但 `guide.md` 是通用规则的统一入口,阶段局部决策优先。 +- **D-126(文档编写三阶段):** 指南文档编写固定为「讨论 → 文档骨架 → 文档编写」三个阶段,详细流程与骨架格式见 `.planning/documentation/workflow.md`。骨架必须包含章节结构、示例计划、live/图计划、术语、内容边界和验收标准;骨架经第二个子代理检查并最多修订三次,仍不通过则停止汇报;骨架必须经用户明确确认后才能开始写正文。 +- **D-127(教学参考材料位置):** 用户提供的飞书教学文档已移动到 `.planning/references/feishu-teaching-docs/`。这些文档只作为行文思路、信息密度、示例与图示安排的参考,不作为当前项目文档的事实来源,也不要求照搬其结构、编号或标题。 +- **D-128(标题只说明主题):** H2/H3 标题使用短名词短语,只说明这一节讲什么;不得写成摘要长句、步骤式标题、口语化标题或“标题:解释”的冒号扩展。标题不是章节内容的核心,不承担概括整节的任务。 +- **D-129(废止独立读者审阅):** 独立读者审阅流程不再存在,流程以 `.planning/documentation/workflow.md` 的三阶段为准。D-46、D-78、D-91、D-92、D-94 不再遵循;D-89 只保留“文档正确性由写作者与用户负责”,其中独立读者部分废止;D-116 中关于文档审阅流程的细节由 D-126 / `workflow.md` 取代,GSD 豁免、子代理落盘与全量阅读要求保留。D-115 的“修改前全量阅读”仍然保留,但它约束的是文档修改子代理,不是独立读者。 +- **D-130(子代理不得复用):** 每个新任务必须新开子代理,禁止复用已完成任务的子代理会话,避免前一个任务的上下文污染本次判断。唯一例外:子代理因规则冲突、安全限制等原因在读取或修改前提前返回,可以续用该未执行会话。任务提示、检查、修订循环都按此执行。 diff --git a/.planning/references/feishu-teaching-docs/01.md b/.planning/references/feishu-teaching-docs/01.md new file mode 100644 index 0000000..28cdbb1 --- /dev/null +++ b/.planning/references/feishu-teaching-docs/01.md @@ -0,0 +1,660 @@ +6.2 画布的高级操作 + +**多图预告!!注意流量使用!!** + +# 6.2.1 全局不透明度 + +全局不透明度描述了绘制在画布上时,颜色的不透明度通道会乘以的值。也就是说,所有的内容在画到画布上之前,其不透明度都会乘以全局不透明度,再画到画布上。设置全局不透明度使用 `globalAlpha` 属性: + +```TypeScript +ctx.globalAlpha = 0.8; // 全局不透明度为 0.8 +``` + +如果绘制的颜色本身就是透明的,那么会再乘以全局不透明度。举例来说,如果 `fillStyle` 设为了 `rgba(255,255,255,0.6)`,`globalAlpha` 设为了 `0.8`,那么最后绘制到画布上的颜色就会是 `rgba(255,255,255,0.48)`。 + +注意 `globalAlpha` 的范围是 `0-1`,也就是说,不能通过将 `globalAlpha` 设置为大于 1 的值来让本身透明的东西变得不那么透明。 + +# 6.2.2 二维线性变换的数学基础 + +在 `Canvas2d` 中,我们经常会用到这些行为:缩放、平移、旋转,虽说平移和缩放可以通过调整坐标等参数来实现,但是我们还需要手动计算坐标,而如果是旋转后再缩放、平移,我们就更难手动计算坐标了,因此我们需要一个通用的方式来实现这三个基本操作。在数学上,这三个行为都叫做线性变换,我们可以使用矩阵乘法来描述这一行为,而且借助于矩阵乘法不满足交换律的特性,我们还可以描述出每个行为的执行顺序。 + +我们可以使用如下三个矩阵来分别描述缩放(Scale)、平移(Translate)、旋转(Rotate)行为: + +$\bold{S}=\begin{bmatrix} x & 0 & 0 \\ 0 & y & 0 \\ 0 & 0 & 1 \end{bmatrix}$ $\bold{T}=\begin{bmatrix} 1 & 0 & x \\ 0 & 1 & y \\ 0 & 0 & 1 \end{bmatrix}$ $\bold{R}=\begin{bmatrix} \cos\theta & -\sin\theta & 0 \\ \sin\theta & \cos\theta & 0 \\ 0 & 0 & 1 \end{bmatrix}$ + +矩阵乘法不满足交换律,即 $\bold{A}\bold{B}\neq\bold{B}\bold{A}$。 + +三者倒序相乘,即可得出最终的变换矩阵,例如我们需要先旋转,再平移,只需要计算 $\bold{TR}$ 即可。同样,如果要先平移,再旋转,只需要计算 $\bold{RT}$ 即可。 + +不过实际上,在 `Canvas2d` 中,我们不需要完全理解上述数学内容,只留下一个大概的印象即可,浏览器提供了相当丰富的接口来让你实现这些线性变换操作,而不需要进行复杂的数学计算。 + +# 6.2.3 在画布中执行线性变换 + +我们可以使用 `ctx.scale` `ctx.translate` `ctx.rotate` 来实现上述三种矩阵变换操作。例如我们要在坐标 (100,100) 的位置画一个旋转了 30° 的矩形,我们需要先对矩形执行旋转操作,再执行平移操作。变换操作需要倒序执行,因此用代码可以这么写: + +```TypeScript +ctx.translate(100, 100); // 平移操作 +ctx.rotate(Math.PI / 6); // 旋转使用弧度制 +ctx.fillRect(0, 0, 100, 100); // 平移操作已经修改了位置,因此直接在 (0,0) 画 +``` + +而如果先平移再旋转,旋转时沿着左上角的原点旋转,于是平移坐标就不对了: + +```TypeScript +ctx.rotate(Math.PI / 6); // 先旋转 30° +ctx.translate(100, 0); // 再横向平移 100 像素 +// 这时候的原点就变成了 (50sqrt(3),50),其中 sqrt 代表平方根 +ctx.fillRect(0, 0, 100, 100); +``` + +这些操作可以随意组合,实现复杂的变换操作: + +```TypeScript +ctx.rotate(Math.PI / 4); +ctx.scale(2, 1.5); +ctx.translate(100, 200); +ctx.rotate(Math.PI / 2); +ctx.scale(0.75, 0.8); +``` + +注意所有的变换都只影响之后绘制的内容,对已有内容没有任何影响。 + +如果我们自己算出来了矩阵,还可以使用 `ctx.setTransform` 来直接设置变换矩阵: + +```TypeScript +function setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void; +``` + +可以使用变换矩阵描述接口的每个参数: + +$$\bold{T}=\begin{bmatrix} a & b & e \\ c & d & f \\ 0 & 0 & 1 \end{bmatrix}$$ + +一般情况下我们并不会用到这个接口,它的最大用处是重置变换矩阵: + +```TypeScript +ctx.setTransform(1, 0, 0, 1, 0, 0); // 重置变换矩阵,此时相当于没有执行任何变换操作 +``` + +# 6.2.4 画布状态机 + +画布本质上是一个状态机,即它会根据当前的状态形成不同的输出(绘制内容)。例如当 `fillStyle` 为 `red` 时,画出的图形就是红色的,`fillStyle` 为 `yellow` 时,画出的图像就是黄色的。除了颜色,还有很多其他状态,包括字体、描边样式、线参数、变换矩阵等。 + +现在考虑这些场景:我需要绘制一个 UI,UI 的中间有一个需要旋转 90° 的地方,这时候我们需要在绘制这个地方之前旋转 90°,绘制之后再旋转 -90°;UI 的中间有一部分使用红色绘制,其余地方使用白色绘制,我需要在红色之前将 `fillStyle` 或 `strokeStyle` 设为 `red`,绘制完之后再切换为白色。 + +我们会发现,如果状态数量少的话,直接设置倒也不复杂,那么加入状态多呢?例如字体、变换矩阵、样式等都需要改变,绘制完之后再改回去,一个个修改就会非常麻烦了。因此浏览器提供了接口来处理这种情况: + +```TypeScript +function save(): void; +function restore(): void; +``` + +其中 `save` 表示保存当前画布的状态,包括样式、字体、变换矩阵等多数设置,注意不包括绘制内容;`restore` 表示回退到上一次保存的状态,如果没有保存状态,那么什么事都不会做。 + +注意这些状态与操作都只会影响之后将要绘制的内容,而不会影响画布上的已有内容。后面的小节讲的内容也是如此。 + +示例如下: + +```TypeScript +ctx.font = '16px Verdana'; +ctx.fillStyle = 'white'; +ctx.strokeStyle = 'blue'; +ctx.textBaseline = 'top'; +// 以上述设置绘制一段文字的填充和描边,白色填充,蓝色描边,16px 字体 +ctx.fillText('lhjnb', 0, 0); +ctx.strokeText('lhjnb', 0, 0); + +ctx.save(); // 保存当前状态 +ctx.fillStyle = 'red'; +ctx.strokeStyle = 'white'; +ctx.font = '24px Verdana'; +// 再以这些设置绘制文字的填充和描边,红色填充,白色描边,24px 字体 +ctx.fillText('lhjnb', 0, 100); +ctx.strokeText('lhjnb', 0, 100); + +ctx.restore(); // 回退成原来的状态 +// 再以原来的设置绘制文字的填充和描边,白色填充,蓝色描边,16px 字体 +ctx.fillText('lhjnb', 0, 200); +ctx.strokeText('lhjnb', 0, 200); +``` + +# 6.2.5 颜色渐变 + +画布提供了渐变的接口,允许我们创建线性渐变、环形渐变和锥形渐变,图示如下: + + + +不同的渐变使用方法基本一致,遵循 `创建渐变->设置颜色->使用渐变` 的流程,不同的地方仅位于创建渐变的步骤。创建渐变时,三者使用不同的方法,我们一个个来讲。 + +## 创建渐变 + +对于线性渐变,使用如下方法: + +```TypeScript +function createLinearGradient(x0: number, y0: number, x1: number, y1: number): CanvasGradient; +``` + +其中 `x0` `y0` 描述了渐变的起始点,`x1` `y1` 描述了渐变的终止点。换句话说,`x0` `y0` 描述了渐变开始的位置,在此处渐变程度为 0,`x1` `y1` 描述了渐变结束的位置,在此处渐变程度为 1。使用图解如下: + +![](https://feishu.cn/file/WY0Zb0zysoeVx0xEridcD74Fned) + +接下来是环形渐变,使用如下方法: + +```TypeScript +function createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): CanvasGradient; +``` + +其中 `x0` `y0` 描述了起始点圆形的位置,`r0` 描述了起始点渐变的半径,`x1` `y1` 描述了终止圆形的位置,`r1` 描述了终止点的半径。使用图解如下: + + + +最后是锥形渐变,使用如下方法: + +```TypeScript +function createConicGradient(startAngle: number, x: number, y: number): CanvasGradient; +``` + +其中 `startAngle` 描述了渐变起始点的角度,水平向右为正,顺时针旋转。`x` `y` 描述了锥形的中心。使用图解如下: + + + +## 设置颜色 + +不同渐变设置颜色的方式完全一样,都使用 `addColorStop` 方法: + +```TypeScript +function addColorStop(offset: number, color: string): void; +``` + +其中 `offset` 表示渐变程度,0 表示渐变的起始位置,1 表示渐变的终止位置,`color` 表示这一点对应的颜色。以线性渐变为例,如果我需要做出一个从绿色到黄色再到蓝色的渐变,那么应该这么写: + +```TypeScript +const gradient = ctx.createLinearGradient(0, 0, 100, 0); // 从 (0,0) 到 (100,0) 的渐变,即水平向右 +gradient.addColorStop(0, 'green'); +gradient.addColorStop(0.5, 'yellow'); +gradient.addColorStop(1, 'blue'); +``` + +不同的渐变的起始终止位置是不同的,注意区分。 + +## 使用渐变 + +最后,我们只需要将渐变赋值给 `fillStyle` 或 `strokeStyle` 即可: + +```TypeScript +const gradient = ctx.createLinearGradient(0, 0, 100, 0); // 从 (0,0) 到 (100,0) 的渐变,即水平向右 +gradient.addColorStop(0, 'green'); +gradient.addColorStop(1, 'yellow'); +ctx.fillStyle = gradient; +ctx.fillRect(0, 0, 100, 100); // 会显示出从左到右的渐变,颜色从绿色变为黄色 +``` + +值得注意的是,渐变的坐标是相对于全局的,与图形的位置并没有任何关系。以上面的例子中的渐变为例,渐变从 (0,0) 渐变至 (100,0),如果你在 (200,0) 的位置画了一个矩形,那么这个矩形会全是黄色,因为它的位置超出了渐变的范围。 + +不过,你可以通过矩阵变换来修改渐变的位置或旋转缩放等。如果你想再用同样的渐变画整个矩形,那么就可以这么写: + +```TypeScript +ctx.fillStyle = gradient; +ctx.translate(200, 0); // 先平移至目标位置 +ctx.fillRect(0, 0, 100, 100); // 再在原点绘制矩形 +``` + +渐变也可以传入半透明的颜色,例如从完全透明转为黑色: + +```TypeScript +const gradient = ctx.createLinearGradient(0, 0, 100, 0); // 从 (0,0) 到 (100,0) 的渐变,即水平向右 +gradient.addColorStop(0, 'rgba(0,0,0,0)'); +gradient.addColorStop(1, 'black'); +``` + +使用这种方式,就可以做出类似百叶窗的效果,不过我们目前只会静态的内容,还无法做出动态的效果。 + +## 注意事项 + +跨上下文使用渐变似乎是一个未定义行为,例如: + +```TypeScript +const gradient = ctx1.createLinearGradient(...); // 使用第一个画布创建渐变 +ctx2.fillStyle = gradient; // 然后将渐变赋值给第二个画布 +``` + +此行为在浏览器标准文档中并没有提及,也就是说它是未定义行为,不同浏览器中行为可能不同,有的浏览器可能报错,有的浏览器可能正常运行。因此需要注意避免这种使用方式。 + +# 6.2.6 滤镜 + +## 滤镜基本使用 + +滤镜允许我们使用简单的代码实现比较常见的效果,包括亮度改变、高斯模糊等。它包含这些内容: + +- `blur(kernal)`:高斯模糊,`kernal` 指高斯模糊的程度(卷积核大小),越大越模糊,但是值过大的话可能会产生严重的性能问题。 +- `brightness(percent)`:调整亮度,`percent` 表示亮度的百分比,`100%` 表示亮度不变,`200%` 可以使亮度变为二倍,`50%` 可以使亮度减为一半。 +- `contrast(percent)`:调整对比度,`percent` 表示对比度百分比,`100%` 保持不变,`0%` 将会变为纯黑,`200%` 会提高对比度。 +- `grayscale(percent)`:调整灰度值,`percent` 表示灰度百分比,`100%` 变为纯灰度图,`0%` 保持不变。 +- `hue-rotate(angle)`:色相旋转,`angle` 表示旋转角度,`0deg` 表示不变,`180deg` 表示色相旋转 180°。 +- `invert(percent)`:反色,`percent` 表示反色程度,`0%` 保持不变,`50%` 生成灰色图像,`100%` 完全反色。 +- `saturate(percent)`:调整饱和度,`percent` 表示饱和度百分比,`100%` 保持不变,`0%` 生成灰度图,`200%` 生成高饱和度图像。 +- `sepia(percent)`:调整为深褐色,`percent` 表示深褐色程度,`0%` 保持不变,`100%` 完全深褐色。可以用于生成老旧照片效果。 + +这些滤镜可以自由组合,之后赋值给 `ctx.filter`,然后绘制即可生效。注意效果是按顺序施加的,顺序可能对效果有一定的影响。示例如下: + +```TypeScript +ctx.filter = 'brightness(120%)contrast(120%)'; // 亮度和对比度调整为 120% +ctx.filter = 'invert(100%)hue-rotate(90deg)blur(4px)'; // 反色 100%,色相旋转 90°,模糊 4px +``` + +如果不想要滤镜,直接设为 `none` 即可: + +```TypeScript +ctx.filter = 'none'; +``` + +注意,直到现在,`Safari` 浏览器依然不支持此特性,也就是说所有的滤镜效果将不会在 `Safari` 浏览器上显示,即 `iOS` 和使用 `Safari` 浏览器的 `Mac` 设备将无法正确显示滤镜。 + +## 关于 `XML` 滤镜 + +这一段的内容并不重要,仅做了解,知道有这个功能即可。 + +最后简单说明一下 `XML` 滤镜,`XML` 滤镜允许你用一段 `XML` 代码实现复杂的滤镜操作,自由度远比字符串更高,但是学习难度也更大,复杂度更高,并不常用。 + +我们需要先在 `HTML` 中声明一段 `svg` 代码,或是在 `ts` 中写成字符串,然后定义为 `URL`,再使用 `url()` 传递给 `filter` 参数。例如下面是一个复杂的 3D 光源滤镜,我们将它写到 `html` 中:(代码来自 [Filter Effects Module Level 1](https://drafts.fxtf.org/filter-effects/#typedef-filter-value-list)) + +```HTML + + Produces a 3D lighting effect. + + + + + + + + + + + + +``` + +然后我们将它赋值给 `filter`: + +```TypeScript +ctx.filter = 'url(#my-filter)'; +``` + +这样就可以实现 `XML` 滤镜效果了。此行为只做了解,知道有这个功能即可,完全不需要掌握,需要的时候再去查资料即可。(似乎连现在的大模型都不知道画布的滤镜还能这么用,足以见得这个功能使用场景非常少) + +# 6.2.7 混合模式 + +混合模式描述了将要画到画布上的内容与画布上已有内容混合的方式。混合模式使用 `ctx.globalCompositeOperation` 来设置,例如: + +```TypeScript +ctx.globalCompositeOperation = 'source-in'; // 设为 source-in 混合模式 +``` + +浏览器一共提供了 26 种混合模式,具体可以查看[此 MDN 文档](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation)了解具体的每一种混合模式。下面我们讲一些常用的混合模式。 + +## `source-` 系列和 `destination-` 系列 + +这两个系列共包含八个混合模式,也是最常用的混合模式,它们的命名都有规律,规律如下: + +- `source` 代表将要画到画布上的内容,`destination` 表示画布上的已有内容 +- 在 `source-` 和 `destination-` 后面跟着的内容描述了将内容画到哪 + +我们可以列个表: + +
系列混合模式描述效果图
source-source-over将 destination 画到 source 的上面,这个是默认设置,也是用的最多的设置。
source-in将 destination 画到与 source 内容重叠的地方,仅显示新内容。
source-out将 destination 画到不与 source 内容重叠的地方,仅显示新内容。
source-atop将 destination 画到与 source 内容重叠的区域上面,显示新内容与原有内容。
destination-destination-over将 destination 画到 source 后面,与 source-over 相反。
destination-in将 source 保留在仅与 destination 重叠的地方,即擦除 destination 之外的内容。
destination-out将 source 中与 destination 重叠的区域全部擦除,相当于升级版的 clearRect。
destination-atop仅保留 source 中与 destination 重叠的部分,并将 destination 画到原有内容后面,与 source-atop 相反。
+ +在这些混合模式中,我们最常用的是 `source-over` 和 `destination-out`,前者是默认设置,大部分绘制都会使用它,后者可以用于自定义形状的擦除行为,例如制作蒙版效果。注意这里的 `destination-out` 是包含透明度的,如果你使用一个半透明的图像去 `destination-out`,会留下一个半透明的 `source`,并不会完全擦除。这些模式组合可以实现大部分我们想要的效果,不过对于一些复杂效果,我们还需要其他的混合模式。 + +## 其他常用混合模式 + +### `lighter` 混合模式 + +在造塔群里面我们经常会看到关于黑底动画应该如何绘制的问题,现在我们就可以回答一部分了,答案是使用加算叠加。对于黑色部分,它的 `RGB` 值是 `0,0,0`,与 `destination` 加算后保持不变,还是 `destintaion` 原有的颜色,而对于其他部分,使用加算叠加后,可以直接显示在画面上。因此我们并不需要进行复杂的抠图操作,很可能还扣不干净,这时候我们直接使用 `lighter` 混合模式执行加算叠加,就可以有效果了。假如我们有一个这种素材 `animate`,那么只需要这么写: + +```TypeScript +ctx.globalCompositeOperation = 'lighter'; // 加算叠加 +ctx.drawImage(animate, 0, 0, 416, 416); // 画到画面上 +``` + +### `multiply` 混合模式 + +我们有时候还会碰到颜色是黑底+白色的动画图片,这种图片直接使用加算叠加时效果不佳,是因为用法不对。这种图片的本意是让你先使用乘算叠加来上色,再使用加算叠加画到画面上。例如有一个纯白的爆炸素材,我们想要橙色的爆炸,就可以先乘以橙色,这样的话白色部分就会上色为橙色(因为白色的 `RGB` 值归一化后是 `1,1,1`,乘以橙色就等于橙色),而黑色部分保持为黑色,我们就得到了橙色的爆炸图,最后再用加算叠加即可画到画面上。假如我们有一个这种素材 `explosion`,那么可以这么写: + +```TypeScript +const ctx = explosionCanvas.getContext('2d'); // 爆炸素材画布 +const ctx2 = gameCanvas.getContext('2d'); // 游戏画面的画布 +ctx.globalCompositeOperation = 'source-over'; // 先使用默认混合模式 +ctx.fillStyle = 'orange'; // 橙色填充 +ctx.fillRect(0, 0, 416, 416); // 全部填充为橙色 +ctx.globalCompositeOperation = 'multiply'; // 调整为乘算叠加 +ctx.drawImage(explosion, 0, 0, 416, 416); // 将素材与背景的橙色乘算,得到橙色的爆炸素材 +ctx2.globalCompositeOperation = 'lighter'; // 将游戏画面调整为加算叠加 +ctx2.drawImage(explosionCanvas, 0, 0, 416, 416); // 将爆炸素材加算叠加至游戏画面 +``` + +这样,我们就对这种黑底素材提交了一个完美的答卷。 + +除了这种用法,乘算叠加还可以用来制作蒙版,将需要显示的地方画为白色,不需要显示的地方画为黑色,然后使用乘算叠加,就会只显示白色的部分了。当然还可以与渐变结合,例如人类塔的封面就使用了这种方式(示例为简化版本): + +```TypeScript +const gradient = ctx.createLinearGradient(0, 0, 100, 0); // 创建渐变 +gradient.addColorStop(0, 'rgba(255,255,255,1)'); +gradient.addColorStop(1, 'rgba(0,0,0,1)'); +ctx.globalCompositeOperation = 'multiply'; // 调整为乘算叠加 +ctx.fillStyle = gradient; +ctx.fillRect(0, 0, 416, 416); // 与游戏画面乘算叠加 +``` + +![](https://feishu.cn/file/ThYObwlU5o1lJVxVmyRcSBuPnlg) + +# 6.2.8 阴影效果 + +画布可以用几行代码实现阴影效果,使用如下四个接口: + +- `ctx.shadowOffsetX`:阴影横向偏移量,单位像素。 +- `ctx.shadowOffsetY`:阴影纵向偏移量,单位像素。 +- `ctx.shadowColor`:阴影的颜色。 +- `ctx.shadowBlur`:阴影的模糊程度,会给阴影添加高斯模糊,单位像素。 + +我们只要设置了这四个属性,画到画面上的内容就会有阴影效果。如下例所示: + +```TypeScript +ctx.shadowColor = "red"; // 阴影颜色 +ctx.shadowOffsetX = 25; // 阴影横向偏移 +ctx.shadowOffsetY = 0; // 阴影纵向偏移 +ctx.shadowBlur = 10; // 阴影模糊 +ctx.fillStyle = "blue"; // 填充颜色 +ctx.fillRect(20, 20, 150, 100); // 以蓝色绘制一个矩形,将会有红色阴影效果 +``` + +效果如图: + +![](https://feishu.cn/file/Vv5IbT7oZo6awvxXp6QcMS7Knuc) + +阴影会受到 `globalAlpha` 的影响以及所画内容不透明度的影响,例如如果 `globalAlpha=0.5`,绘制一个 `rgba(255,255,255,0.5)` 的矩形,那么阴影的不透明度将会是 `阴影颜色的不透明度 * 0.5 * 0.5`。因此,你不能通过绘制一个透明的内容来只获得阴影。 + +如果你需要只获得阴影,可以考虑与 `globalCompositeOperation` 结合使用,先做一个阴影颜色的画布,再使用 `destination-in` 获取到将要画到画布上的内容区域,这样你就获取到了阴影内容,再将此画布画到最终画布上,并添加高斯模糊的滤镜以及需要的偏移量,就可以仅将阴影画到目标画布上。假如我们需要获取一个图片的阴影,那么可以这么写: + +```TypeScript +const ctx1 = shadowCanvas.getContext('2d'); +const ctx2 = canvas.getContext('2d'); + +ctx1.fillStyle = 'red'; // 使用红色阴影 +ctx1.fillRect(0, 0, shadowCanvas.width, shadowCanvas.height); +ctx1.globalCompositeOperation = 'destination-in'; +ctx1.drawImage(image, 0, 0, image.width, image.height); // 将图片画上去,这样就会只保留图片的红色阴影 + +ctx2.filter = 'blur(4px)'; // 目标画布添加高斯模糊滤镜 +ctx2.drawImage(shadowCanvas, 25, 0); // 将阴影画布偏移 (25,0) 画到目标画布上 +``` + +# 6.2.9 区域裁剪 + +区域裁剪使用场景较少,但是在部分场景下会有一些意想不到的效果。区域裁剪允许你将之后的绘制内容限定在指定区域内,在区域之外的内容将不会绘制。它使用如下接口,共有四种用法: + +```TypeScript +function clip(): void; +function clip(path: Path2D): void; +function clip(fillRule: CanvasFillRule): void; +function clip(path: Path2D, fillRule: CanvasFillRule): void; +``` + +当传入 `path` 时,会将区域限定在传入的路径中,否则将会限定在画布现有路径中,即从上一次 `beginPath` 到现在所声明的路径。`fillRule` 即为环绕原则,参考上一节课的内容。 + +下面我们展示一个示例,此示例使用 `clip()` 方法根据圆弧的形状创建一个裁剪区域。然后绘制了两个矩形;只有在裁剪区域内的部分才会被渲染。 + +```TypeScript +ctx.beginPath(); +ctx.arc(100, 75, 50, 0, Math.PI * 2); // 圆形形状 +ctx.clip(); // 使用圆形裁剪 + +ctx.fillStyle = "blue"; +ctx.fillRect(0, 0, canvas.width, canvas.height); // 绘制内容 +ctx.fillStyle = "orange"; +ctx.fillRect(0, 0, 100, 100); // 绘制内容 +``` + +其效果如下,所有绘制内容都被限定到了圆形区域内: + +![](https://feishu.cn/file/U9xnbmo4UowHCZxTbyYcy7l4npv) + +如果需要取消裁剪区域,可以使用 `ctx.save` 和 `ctx.restore`,在裁剪之前使用 `ctx.save` 保存画布状态,在之后使用 `ctx.restore` 回退画布状态,即可取消裁剪区域。 + +# 6.2.10 抗锯齿 + +画布默认会有抗锯齿行为,但是这对于像素游戏来说有时候并不合适,如果我们需要调整抗锯齿设置,可以使用 `ctx.imageSmoothingEnabled` 和 `ctx.imageSmoothingQuality` 来调整,前者控制是否开启抗锯齿,后者控制抗锯齿效果。不过后者并不常用,我们一般只会使用到前者。我们可以看一下开启抗锯齿与否的区别: + +```TypeScript +ctx.drawImage(img, 0, 24, w, h); // 原始图片 +ctx.imageSmoothingEnabled = true; +ctx.drawImage(img, w, 24, w * 3, h * 3); // 开启抗锯齿绘制 +ctx.imageSmoothingEnabled = false; +ctx.drawImage(img, w * 4, 24, w * 3, h * 3); // 关闭抗锯齿绘制 +``` + +其效果如下: + +![](https://feishu.cn/file/NTlrb0vjHo9byExhwjCcYy6Ln3c) + +# 6.2.11 位置判断 + +如果你需要判断一个点是否处在一个路径内,可以使用如下方法: + +```TypeScript +function isPointInPath(x: number, y: number, fillRule?: CanvasFillRule): boolean; +function isPointInPath(path: Path2D, x: number, y: number, fillRule?: CanvasFillRule): boolean; +``` + +如果你需要处理交互的话,那么此方法会很实用,虽然其性能并不一定有手动判断更好,但是其准确度会更高,而且考虑到交互频率一般不会很高,使用此方法完全合适。示例如下: + +```TypeScript +ctx.beginPath(); +ctx.rect(0, 0, 100, 100); // 矩形路径 +ctx.fill(); + +ctx.isPointInPath(10, 10); // 在路径内,返回 true +ctx.isPointInPath(110, 10); // 在路径外,返回 false +``` + +除了这个方法,还可以使用 `ctx.isPointInStroke` 来判断一个点是否在描边内: + +```TypeScript +function isPointInStroke(x: number, y: number): void; +function isPointInStroke(path: Path2D, x: number, y: number): void; +``` + +其中 `lineWidth` 需要通过 `ctx.lineWidth` 设置。例如: + +```TypeScript +ctx.beginPath(); +ctx.rect(0, 0, 100, 100); // 矩形路径 +ctx.lineWidth = 10; // 10 的宽度 +ctx.stroke(); + +ctx.isPointInStroke(1, 1); // 在描边内,返回 true +ctx.isPointInStroke(106, 106); // 在描边外,返回 false +``` + +# 6.2.12 Pattern 样式 + +## 基础使用 + +样板中可以为每个地图设置一个背景图块,这样的话这一层如果什么内容都没有,就会显示成只有背景图块的样子。我们来考虑它是如何实现的。 + +首先想到的当然是写一个循环,在循环内调用 `drawImage`,如下所示: + +```TypeScript +for (let x = 0; x < width; x++) { + for (let y = 0; y < height; y++) { + ctx.drawImage(block, x * 32, y * 32, 32, 32); + } +} +``` + +但是这样未免太过麻烦,而且由于绘制调用次数多,可能会有额外的绘制开销。因此,我们可以使用浏览器提供的 `CanvasPattern` 接口,这个接口对于这种场景来说非常方便。我们需要使用 `createPattern` 来创建平铺样式,其接口定义如下: + +```TypeScript +function createPattern(image: CanvasImageSource, repetition?: string): CanvasPattern; +``` + +其中第一个参数代表要平铺的图像,可以是图片、画布等内容,第二个参数表示重复方式,即平铺类型,它可以填: + +- `repeat`:水平竖直都会平铺,这是默认设置,不填第二个参数的时候就使用此设置。 +- `repeat-x`:仅在水平方向上平铺。 +- `repeat-y`:仅在竖直方向上平铺。 +- `no-repeat`:两个方向都不平铺。 + +那么我们就可以使用平铺样式来简化上述背景绘制: + +```TypeScript +const pattern = ctx.createPattern(block, 'repeat'); // 创建平铺样式 +ctx.fillStyle = pattern; // 将平铺样式赋值给 fillStyle +ctx.fillRect(0, 0, 416, 416); // 使用 fillRect 绘制 +``` + +与渐变类似,平铺样式坐标也是基于全局的,不会受到绘制位置的影响。如果需要位移、旋转、放缩等,需要使用线性变换接口: + +```TypeScript +ctx.fillStyle = pattern; +ctx.translate(16, 16); +ctx.scale(2, 2); +ctx.fillRect(0, 0, 32, 32); +``` + +## 注意事项 + +在创建平铺样式后修改创建样式的图像源是没有效果的,例如将一个画布创建为平铺样式,然后修改画布内容,这时平铺样式绘制的内容不会改变: + +```TypeScript +const pattern = ctx.createPattern(patternCanvas, 'repeat'); // 用画布创建一个平铺样式 +ctx.fillStyle = pattern; +ctx.fillRect(0, 0, 208, 208); // 使用平铺样式绘制 + +patternCtx.fillRect(0, 0, 32, 32); // 修改创建样式的画布 +ctx.fillRect(0, 0, 208, 208); // 再次使用平铺样式绘制,这时候结果不变 +``` + +与渐变类似,跨上下文使用平铺样式也是未定义行为,不同浏览器行为可能不同,需要避免这种使用方式: + +```TypeScript +const pattern = ctx.createPattern(image, 'repeat'); // 使用第一个画布创建样式 +ctx2.fillStyle = pattern; // 将样式赋值给第二个画布 +``` + +有一点需要澄清的是,如果你查阅 MDN 文档,它会如此描述 `CanvasPattern`:描述图案的不透明对象。这里的不透明并不是说平铺样式没有不透明度通道,而是说这个对象并不会暴露给用户,即我们不知道对象内部是什么,对象的接口对于我们来说是不透明的,平铺样式自然可以使用透明的图片,并不会使内容变得不透明。 + +# 6.2.13 文字测量 + +## 基本概念 + +我们很难知道一段文字画出来之后其占多大的地方,如果我们需要获取一段文字的宽度、高度等信息,可以使用浏览器提供的 `measureText` 接口: + +```TypeScript +function measureText(text: string): TextMetrics; +``` + +其中 `text` 表示要测量的文字,测量时使用 `ctx.font` 作为字体。 + +`TextMetrics` 包含很多内容,包括文字的宽度、高度等,我们一个个来看。 + +- `metrics.width`:描述了这段文字的宽度,单位像素。 +- `metrics.actualBoundingBoxAscent` 和 `metrics.actualBoundingBoxDescent`:描述了从文本基线(`ctx.textBaseline` 所描述的位置)到文本最高的顶部及最低的底部的距离。最高的顶部指所有文字中最靠上的位置,最低的底部同理。单位像素,可能是负值。使用图示说明: + + + +- `metrics.actualBoundingBoxLeft` 和 `metrics.actualBoundingBoxRight`:与 `Ascent` 和 `Descent` 类似,描述的是 `ctx.textAlign` 所描述的位置距离文本最左侧和最右侧的距离。单位像素,可能是负值,不再提供图示说明。 +- `metrics.fontBoundingBoxAscent` 和 `metrics.fontBoundingBoxDescent`:与 `actual` 类似,但是描述的位置不同,它描述的是字体中包含的所有文字的顶端或底端。这可能不好理解,举例来说,对于 `字` 这个字,它的体积是比字母 `a` 更大的,如果这个字体只包含这两个字,那么 `font` 就会返回 `字` 所对应的距离,而非 `a` 所对应的距离。 + +我们最常用的也就是这七个属性,其余属性并不常用,这里也不再描述。下面来看一些示例。 + +## 使用示例 + +获取文本宽度: + +```TypeScript +ctx.font = '16px Verdana'; // 设置测量使用的字体 +const metrics = ctx.measureText('这是一段文字'); // 测量文字 +metrics.width; // 获取文字宽度 +``` + +获取文本高度,使用 `Ascent` 加上 `Descent`: + +```TypeScript +ctx.font = '16px Verdana'; // 设置测量使用的字体 +const metrics = ctx.measureText('这是一段文字'); // 测量文字 +const height = metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent; // 计算高度 +``` + +## 注意事项 + +除了 `metrics.width` 外,其余属性都对浏览器版本有一定的要求,兼容性较差,不建议使用,只建议使用 `metrics.width` 这一个属性。如果需要高度,可以直接使用字体大小代替,结果并不会差很多。 + +# 6.2.14 画布数据 + +## 基本使用 + +我们可以通过 `getImageData` 和 `putImageData` 来对画布内容进行像素级的操作。接口声明如下: + +```TypeScript +interface ImageData { + readonly width: number; + readonly height: number; + readonly data: Uint8ClampedArray; +} + +function getImageData(sx: number, sy: number, sw: number, sh: number, settings?: ImageDataSettings): ImageData; + +function putImageData(data: ImageData, dx: number, dy: number): void; +function putImageData(data: ImageData, dx: number, dy: number, sx: number, sy: number, sw: number, sh: number): void; +``` + +我们需要先使用 `getImageData` 获取数据对象,它的前四个参数表示需要获取的区域,`settings` 参数一般用不到,如果需要可以自行查询: + +```TypeScript +const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height); +``` + +然后我们来看 `imageData` 对象。它的 `width` 和 `height` 属性分别代表裁剪内容的宽度和高度,`data` 是一个一维数字数组,长度为 `width * height * 4`。类型声明中的 `Uint8ClampedArray` 之前没见过,它是一个数字数组,每一项的范围为 `0-255`,至于其他的内容在之后的课程中,参考 。数组以 `R G B A` 的顺序,从左到右,从上到下的顺序排列。例如 `imageData.data[22]` 就表示第 6 个像素的 `B` 通道,即蓝色通道,因为第 6 个像素对应到 `5*4 ~ 6*4` 索引,即 `20~24`,包括 20,不包括 24。 + +我们可以使用循环来修改每个像素的内容,例如把红色通道去掉: + +```TypeScript +const length = imageData.width * imageData.height; +for (let i = 0; i < length; i++) { // 使用一个循环 + imageData.data[i * 4] = 0; // 把每个像素对应的第一个通道设为 0 +} +``` + +之后再使用 `putImageData` 放回画布上,其中 `putImageData` 的第一个参数是数据对象,`dx` `dy` 描述了放到画布的哪个位置,后面的 `sx` 四个参数可选,表示对数据对象裁剪后放到画布上: + +```TypeScript +ctx.putImageData(imageData, 0, 0); +``` + +这样的话画布上的所有内容的红色通道都会变成 0 了。 + +## 注意事项 + +使用这个接口相当于使用 CPU 干显卡的事,即 CPU 渲染,因此性能极差,如果不是需要进行图像分析或是极其特殊的场景,非常不建议使用。使用 `drawImage` 绘图性能要显著好于此接口。而如果需要像素级操作,推荐使用后续教程中将会详细讲解的 `WebGL`,而非使用此接口。 + +# 6.2.15 杂项 + +## 字体 + +画布的字体可以设置多个,如果第一个不包含要绘制的文字,那么会自动使用第二个。例如: + +```TypeScript +ctx.font = '24px myFont, 16px Arial, 16px Verdana'; +``` + +这样的话,如果 `24px myFont` 字体中不包含要绘制的文字,那么会自动使用 `16px Arial` 作为字体,如果还没有,再尝试使用 `16px Verdana`,如果依然没有,则会使用系统默认字体。 + +使用 `ctx.measureText` 测量文字时,`metrics.fontBoundingBoxAscent` 及 `metrics.fongBoundingBoxDescent` 只会使用字体列表中的第一个字体,即 `24px myFont`,并不会使用 `16px Arial`,即使要测量的文字包含了 `myFont` 中不包含的文字。 + +## 其他接口 + +画布中还有一些接口我们没有讲到,这是因为它们不常用,或者兼容性不好。如果你需要这些接口,可以自行查阅 MDN 文档。 + +# 6.2.16 总结 + +至此,我们将 `Canvas2D` 的内容讲解完毕了,现在我们可以使用画布进行简单的绘制了。你可以自己在样板里面或自己创建一个 `HTML` 页面尝试一下。下一节我们将会讲解如何做出动态效果。 \ No newline at end of file diff --git a/.planning/references/feishu-teaching-docs/02.md b/.planning/references/feishu-teaching-docs/02.md new file mode 100644 index 0000000..414a07e --- /dev/null +++ b/.planning/references/feishu-teaching-docs/02.md @@ -0,0 +1,337 @@ +6.4 WebGL2 数学基础 + +从本课开始,我们将会接触一个复杂庞大的系统,它叫做 `WebGL2`。它是一个允许你直接使用 GPU 进行渲染的工具,因此其性能要远比 `Canvas2D` 更好,但是其难度也更大,涉及到的概念很多且复杂。 + +`WebGL2` 部分很可能是整个教程的难度顶点,但是由于新样板将会大量使用,我们不得不在这个时期就开始讲解,因此请做好足够的心理准备。 + +本节课将会讲解 `WebGL2` 涉及到的核心数学基础,纯理论,不包含任何实操内容。注意本节课所讲的所有内容都是理解基本原理即可,不需要自己会算,更不需要死记硬背。 + +# 6.4.1 是否应该学习 `WebGL2`? + +你可以先通过本小节来判断自己是否真的需要学习 `WebGL2`。 + +## 需要学习的场景 + +`WebGL2` 通过显卡渲染,因此其性能表现远好于 `Canvas2D`,如果你需要高性能渲染,学习 `WebGL2` 是必要的。 + +`WebGL2` 可以实现像素级的渲染操作,你可以单独处理某些像素,如果你需要这种行为,学习 `WebGL2` 是必要的。 + +`WebGL2` 可以实现三维渲染,如果你想画三维内容,或是在你的塔里面添加一些三维效果,学习 `WebGL2` 是必要的。 + +如果你想看懂新样板的渲染系统,以及新样板的一些内置效果,学习 `WebGL2` 是必要的。 + +如果你想深入了解计算机的渲染流程,学习 `WebGL2` 是必要的。 + +## 不需要学习的场景 + +如果你只是想造出魔塔,不制作复杂的渲染效果,是不需要学习 `WebGL2` 的。 + +如果你认为自己的思维能力不够强,可以考虑不学习 `WebGL2`。如果你可以理解前面课程中的 `TypeScript`,那么思维能力就是过关的,可以学习 `WebGL2`,如果有些内容无法理解,可以考虑暂缓 `WebGL2` 的学习。 + +如果你的数学能力没有达到初中水平和部分高中水平,是不需要学习 `WebGL2` 的。这里的部分高中知识主要是三角函数。 + +如果你只是想学习使用样板,或是学习 `js`,那么是不需要学习 `WebGL2` 的。 + +# 6.4.2 笛卡尔坐标系 + +笛卡尔坐标系是众多坐标系的一种,也是最常用的一种,我们在初中学到的 “平面直角坐标系” 指的就是笛卡尔坐标系。`WebGL2` 使用三维右手笛卡尔坐标系,即 `x` 轴水平向右,`y` 轴竖直向上,`z` 轴垂直屏幕指向使用设备的人(之后称为观察者)。使用图示如下: + + + +而名称中的右手坐标系,是指你可以使用右手,大拇指指向 `x` 轴正方向,食指指向 `y` 轴正方向,中指指向 `z` 轴正方向,如下图所示: + +![](https://feishu.cn/file/CHZ3b4Z4qoreKFxzLDfcPPRcnCd) + +`WebGL2` 的坐标是与 `Canvas2D` 不同的,注意区分。在 `WebGL2` 中,坐标原点是画布的正中心,并非 `Canvas2D` 的左上角或是数学中常用的左下角。每个坐标的范围都是 `-1 ~ 1`,即画布最左侧的横坐标是 -1,最右侧的横坐标是 1,画布最下侧的纵坐标是 -1,最上侧的纵坐标是 1,最远离观察者的 `z` 坐标是 -1,最靠近观察者的 `z` 坐标是 1。而对于超出这些范围的物体,将不会做任何渲染行为。 + +# 6.4.3 必要术语 + +## 归一化 + +指将一个坐标进行缩放,使得其距离原点的长度为 1。例如对于坐标 `(3,4)`,其长度为 5(使用勾股定理计算),归一化后为 $(\frac{3}{5},\frac{4}{5})$,其长度为 1。 + +# 6.4.4 向量 + +向量指的是一个有方向的量,对于 $n$ 维向量,使用 $n$ 个坐标表示。例如向量 $\vec{a}=(1,2,3)$,它表示了一个向量,指向了 $(1,2,3)$ 这个方向。假设将向量作用于点 $(1,1,1)$,那么结果就是 $(2,3,4)$。 + +## 向量的模 + +向量的模描述了向量的长度,例如对于上例 $\vec{a}=(1,2,3)$,这个向量的长度就是 $\sqrt{14}$(使用勾股定理计算)。符号表示为 $\lvert \vec{a} \rvert=\sqrt{14}$。 + +向量可以归一化,归一化后向量的长度为 1,因此直接将每个坐标除以向量的模即可,可以表示为 $\vec{a_n}=\frac{\vec{a}}{\lvert \vec{a} \rvert}$。 + +## 向量加减法 + +向量的加减法可以表示为每个对应坐标相加,例如 $\vec{a}=(1,2,3)$,$\vec{b}=(2,3,4)$,则 $\vec{a}+\vec{b}=(3,5,7)$。在坐标系下,它遵循平行四边形法则,使用图示表示: + + + +## 向量点积 + +向量的点积表示为 $r=\vec{a}\cdot \vec{b}$,注意点号不可省略。计算其结果时,首先计算两个向量夹角的余弦值,再计算两个向量的模,最后将余弦值与模三者相乘,即可得到结果,结果是一个数字。数学表示为 $\vec{a}\cdot \vec{b}=\lvert \vec{a} \rvert \lvert \vec{b} \rvert\cos(\vec{a},\vec{b})$。 + +使用坐标计算时,直接计算对应坐标相乘的和即可,例如对于 $\vec{a}=(1,2,3)$,$\vec{b}=(2,3,4)$,其点积为 $\vec{a}\cdot\vec{b}=1\times 2+2\times 3+3\times 4=20$。 + +## 向量叉乘 + +向量叉乘表示为 $\vec{v}=\vec{a}\times\vec{b}$,注意乘号不能省略,注意与点积区分。其结果是一个向量,计算分为计算方向与计算模长。方向遵循右手定则,即食指、中指、无名指、小拇指并在一起,指向向量 $\vec{a}$ 的方向,然后弯曲四个手指并调整手腕,使得手指指向向量 $\vec{b}$的方向,将手缩成拳头,大拇指竖起,大拇指方向就是叉乘结果的方向。计算模长时使用公式 $r=\lvert \vec{a} \rvert \lvert \vec{b} \rvert\sin(\vec{a},\vec{b})$。将模长与方向结合即可得到计算结果。 + +使用坐标计算时,使用公式:$\vec{a}\times\vec{b}=(a_yb_z-a_zb_y,a_zb_x-a_xb_z,a_xb_y+a_yb_z)$,其中 $a_x,a_y,a_z$ 分别表示向量 $\vec{a}$ 的 `x` `y` `z` 坐标。 + +使用行列式表示如下,看一看即可,不需掌握,只了解上述坐标计算公式即可: + +$\vec{a}\times\vec{b}=\begin{vmatrix} \vec{i} & \vec{j} & \vec{k} \\ a_x & a_y & a_z \\ b_x & b_y & b_z\end{vmatrix}$,其中 $\vec{i}=(1,0,0)$,$\vec{j}=(0,1,0)$,$\vec{k}=(0,0,1)$ + +# 6.4.5 矩阵 + +矩阵可以用于描述线性变换。具体来说,给定一个点和一个矩阵,可以通过矩阵乘以点的形式计算出这个点经过矩阵变换后的位置。我们本节先来看矩阵的定义与基本运算。 + +## 矩阵基本定义 + +矩阵为一个 $m\times n$ 的数字列表,一般使用圆括号或方括号包裹。在图形学中,我们一般习惯使用方括号。例如这就是一个矩阵:$\bold{A}=\begin{bmatrix} 1 & 2 \\ 3 & 4 \end{bmatrix}$,它包含 `1 2 3 4` 这四个数,并有位置关系。 + +定义单位矩阵:$\bold{I}_n=\begin{bmatrix} 1 & 0 & \cdots & 0 \\ 0 & 1 & \cdots & 0 \\ \vdots & \vdots & \ddots & \vdots \\ 0 & 0 & \cdots & 1 \end{bmatrix}$,其中 $n$ 表示矩阵的维度,比如 $\bold{I}_2=\begin{bmatrix} 1 & 0 \\ 0 & 1 \end{bmatrix}$,$\bold{I}_3=\begin{bmatrix} 1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1 \end{bmatrix}$。单位矩阵的英文为 `identity`。 + +## 矩阵乘法 + +矩阵乘法符号为 $\bold{R}=\bold{A}\bold{B}$,定义为:对于位于 `(m,n)` 位置的数,其计算结果为 $\bold{A}$ 矩阵的 `m` 行与 $\bold{B}$ 矩阵的 `n` 列依次相乘并相加的结果。这句话不太好理解,如果使用数学表达式的话,就是这么表示的:$\bold{R}_{mn}=\sum_{i=1}^{n}\sum_{j=1}^{m}\left(\bold{A}_{mi}\times \bold{B}_{jn}\right)$。举例来说,对于两个矩阵 $\bold{A}=\begin{bmatrix} 1 & 2 \\ 3 & 4 \end{bmatrix}$,$\bold{B}=\begin{bmatrix} 2 & 3 \\ 4 & 5 \end{bmatrix}$,其相乘的结果为:$\bold{AB}=\begin{bmatrix} 1\times2+2\times4 & 1\times3+2\times5 \\ 3\times2+4\times4 & 3\times3+4\times5\end{bmatrix}=\begin{bmatrix} 10 & 13 \\ 14 & 29 \end{bmatrix}$。我们以第一行第一列的计算结果 10 为例,简单解释一下计算过程。 + +对于第一行第一列,其结果就是 $\bold{A}$ 的第一行与 $\bold{B}$ 的第一列依次相乘并相加。由于两个矩阵都是 $2\times 2$ 矩阵,因此,其结果应该是两项乘积相加,第一项是 $\bold{A}$ 的第一行第一列乘以 $\bold{B}$ 的第一行第一列,第二项是 $\bold{A}$ 的第一行第二列乘以 $\bold{B}$ 的第二行第一列,因此第一项是 $1\times 2$,第二项是 $2\times 4$,最终结果就是 10。 + +我们不要求需要自己手动计算,只需要知道计算原理即可。对于两个 $4\times 4$ 的方阵来说,我们可以用代码写出其计算过程,代码中 `m1` 表示第一个矩阵,`m2` 表示第二个矩阵,都是二维数组: + +```TypeScript +function multiplyMatrix(m1: number[][], m2: number[][]) { + // 初始化结果矩阵,4x4 方阵的计算结果依然是 4x4 方阵 + const res: number[][] = [ + [0, 0, 0, 0], + [0, 0, 0, 0], + [0, 0, 0, 0], + [0, 0, 0, 0] + ]; + // 遍历每一行每一列 + for (let x = 0; x < 4; x++) { + for (let y = 0; y < 4; y++) { + let ans = 0; + // 对于某个元素,计算对应行与列的乘积并相加 + for (let n = 0; n < 4; n++) { + ans += m1[y][n] * m2[n][x]; + } + res[y][x] = ans; + } + } + return res; +} +``` + +可以看出,矩阵乘法的计算量很大,即使是 $4\times 4$ 方阵,就需要 $4^3=64$次乘法运算及加法运算。因此使用 CPU 大量计算矩阵并不是一个好选择,而专门针对矩阵运算优化过的显卡就可以完美胜任矩阵运算。 + +矩阵乘法具有如下性质: + +- 不满足交换律,即 $\bold{AB}\neq\bold{BA}$,这一点非常重要,在之后的矩阵变换中将会经常用到。 +- 单位矩阵乘以任何矩阵都等于矩阵本身:$\bold{I}_n\bold{A}=\bold{A}$。 +- 满足结合律。即 $\bold{A}(\bold{BC})=(\bold{AB})\bold{C}=\bold{ABC}$。 + +## 矩阵转置 + +矩阵转置表示矩阵沿从左上到右下的对角线进行对称翻转,数学符号为 $\bold{A^T}$。例如对于一个 $3\times 3$ 矩阵 $\bold{A}=\begin{bmatrix} 1 & 2 & 3 \\ 4 & 5 & 6 \\ 7 & 8 & 9 \end{bmatrix}$,其转置为:$\bold{A^T}=\begin{bmatrix} 1 & 2 & 3 \\ 4 & 5 & 6 \\ 7 & 8 & 9 \end{bmatrix}^{\bold{T}}=\begin{bmatrix} 1 & 4 & 7 \\ 2 & 5 & 8 \\ 3 & 6 & 9 \end{bmatrix}$。 + +# 6.4.6 线性变换 + +注意到矩阵乘法要求矩阵 $\bold{A}$ 的列数与矩阵 $\bold{B}$ 的行数相等,因此参与矩阵乘法的并不一定是方阵。我们考虑将一个二维坐标写成矩阵的形式:$\bold{P}=\begin{bmatrix} x & y & 1 \end{bmatrix}^{\bold{T}}=\begin{bmatrix} x \\ y \\ 1 \end{bmatrix}$,其中最后一位 1 我们暂时不管。这样的话,我们可以用一个 $3\times 3$ 方阵乘以坐标,得到另一个坐标。假设这个 $3\times 3$ 方阵为 $\bold{T}$,那么我们可以这么表示:$\bold{R}=\bold{TP}=\begin{bmatrix} m_{11} & m_{12} & m_{13} \\ m_{21} & m_{22} & m_{23} \\ m_{31} & m_{32} & m_{33} \end{bmatrix}\begin{bmatrix} x \\ y \\ 1 \end{bmatrix}$。此操作就是对点进行线性变换,而前面的 $3\times 3$ 方阵就叫做变换矩阵。如果变换矩阵是一个单位矩阵 $\bold{I}_3$,那么计算结果将与原坐标相同,即 $\bold{I}_3\bold{P}=\bold{P}$。 + +如果对整个坐标系乘以一个矩阵,那么就是对坐标系的线性变换。 + +下图是线性变换的动画,摘自 b 站 up 主漫士沉思录的视频。 + +![](https://feishu.cn/file/Nlyhbkf76odm28xcJwKcvcOLnJd) + +与二维类似,如果需要三维的变换,那么只需要再增加一维即可:$\bold{R}=\bold{TP}=\begin{bmatrix} m_{11} & m_{12} & m_{13} & m_{14} \\ m_{21} & m_{22} & m_{23} & m_{24} \\ m_{31} & m_{32} & m_{33} & m_{34} \\ m_{41} & m_{42} & m_{43} & m_{44} \end{bmatrix}\begin{bmatrix} x \\ y \\ z \\ 1 \end{bmatrix}$ + +对于坐标 $\begin{bmatrix} x & y & z & 1 \end{bmatrix}^{\bold{T}}$,它也可以叫做向量,这里坐标包含四个元素,因此称为四维向量。 + +以上是关于线性代数与线性变换的基本概念,它们将会在 `WebGL2` 的学习中频繁接触到,因此这些东西不说会手动计算,至少也要理解其原理。如果没有搞明白或者想要深化一下,推荐观看 b 站 up 主漫士沉思录的“无痛线代”系列视频:[线性代数很难学?因为没有深刻理解这个概念【无痛线代】](https://www.bilibili.com/video/BV1wu411T7dj/?share_source=copy_web&vd_source=734ccb7e83f97b45497b8e968b286ded),合集共六集,观看时长约两小时。 + +# 6.4.7 变换矩阵 + +## 二维变换矩阵 + +先前我们已经讲过了三种二维变换矩阵,缩放、平移、旋转变换矩阵分别是: + +$\bold{S}=\begin{bmatrix} x & 0 & 0 \\ 0 & y & 0 \\ 0 & 0 & 1 \end{bmatrix}$ $\bold{T}=\begin{bmatrix} 1 & 0 & x \\ 0 & 1 & y \\ 0 & 0 & 1 \end{bmatrix}$ $\bold{R}=\begin{bmatrix} \cos\theta & -\sin\theta & 0 \\ \sin\theta & \cos\theta & 0 \\ 0 & 0 & 1 \end{bmatrix}$ + +按照变换顺序的倒序相乘,最后乘以坐标即可。 + +## 三维变换矩阵 + +三维的变换矩阵比二维的更复杂一些。对于放缩,使用:$\bold{S}=\begin{bmatrix} x & 0 & 0 & 0 \\ 0 & y & 0 & 0 \\ 0 & 0 & z & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}$。 + +对于平移,使用:$\bold{T}=\begin{bmatrix} 1 & 0 & 0 & x \\ 0 & 1 & 0 & y \\ 0 & 0 & 1 & z \\ 0 & 0 & 0 & 1 \end{bmatrix}$。 + +而旋转包含三个方向,每个方向使用不同的变换矩阵。围绕 `x` 轴、`y` 轴、`z` 轴旋转分别使用: + +$\bold{R}_x=\begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & \cos\theta & -\sin\theta & 0 \\ 0 & \sin\theta & \cos\theta & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}$$\bold{R}_y=\begin{bmatrix} \cos\theta & 0 & \sin\theta & 0 \\ 0 & 1 & 0 & 0 \\ -\sin\theta & 0 & \cos\theta & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}$$\bold{R}_z=\begin{bmatrix} \cos\theta & -\sin\theta & 0 & 0 \\ \sin\theta & \cos\theta & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}$ + +这些变换矩阵留下一个印象即可,不需要死记硬背,等到需要的时候再查询即可。 + +同样,按照变换顺序的倒序相乘,最后乘以坐标,即可得到变换后的坐标。 + +## 倒序相乘 + +我们提到变换矩阵需要倒序相乘,这是为什么呢?我们考虑如下变换,先平移,再缩放,再旋转,那么经过平移后的坐标应该是 $\bold{TP}$,再经过缩放,那么就是 $\bold{S}(\bold{TP})$,再经过旋转,就是 $\bold{R}(\bold{S}(\bold{TP}))$,根据矩阵乘法的结合律,去掉括号就得到了 $\bold{RSTP}$。因此矩阵变换需要是倒序相乘。 + +## 列主序与行主序 + +以上我们所讲的内容都是行主序的,它与 `WebGL2` 中所使用的列主序不同。使用行主序教学是因为我们习惯使用行主序推导,且网络上能搜到的教程都是行主序的。为了切换成列主序,我们只需要给上面的所有的矩阵执行一次转置即可,包括坐标。全部转置之后,乘法计算方式依然遵循原来的计算方式,因此最终结果也是列主序的,将结果转置即可获得行主序的结果。 + +不过需要注意的是,不是所有的 `WebGL2` 矩阵都是列主序的,它也可能是行主序,我们将在后面详细讲解何时为列主序,何时为行主序。 + +# 6.4.8 坐标系 + +在图形学中有很多种坐标系,包含世界坐标系、摄像机坐标系、裁剪坐标系等。 + +## 世界坐标系 + +世界坐标系指的是空间中的绝对坐标系。例如,我声明原点为 $\rm{A}$ 点,再确定三个坐标轴的方向,那么每个物体都将会有一个固定的绝对坐标,比如一个点可能在 $(3,2,1)$,另一个点可能在 $(5,9,7)$ 等等。这些坐标都是固定的,除非物体移动或者原点移动。 + +## 摄像机坐标系 + +在图形学中,我们称观察者为摄像机,显示的画面就是摄像机看到的画面。以摄像机为原点,摄像机朝向方向为 `z` 轴负方向,摄像机水平向右为 `x` 轴正方向,摄像机竖直向上为 `y` 轴正方向建立坐标系,此坐标系就称为摄像机坐标系。使用图例表示: + + + +## 裁剪坐标系 + +裁剪坐标系指的就是 5.4.2 中讲到的画布坐标系,以画布中心为原点,水平向右为 `x` 轴正方向,竖直向上为 `y` 轴正方向,垂直屏幕指向观察者为 `z` 轴正方向。每个坐标的范围都是 `-1 ~ 1`,超出范围的部分不会被渲染。 + +# 6.4.9 MVP 变换 + +MVP 变换是指 Model View Projection 变换,翻译为模型、视图、投影变换。 + +## 模型变换 + +模型变换指的就是对一个物体进行平移、缩放、旋转操作,使用上面讲过的变换矩阵。它操作的是世界坐标系下的坐标。例如我们对正方体进行模型变换,先平移,再旋转,最后缩放,使用矩阵表示为:$\bold{P_R}=\bold{S}\cdot\bold{R}\cdot\bold{T}\cdot\bold{P}$,其中 $\bold{P_R}$ 表示变换结果,$\bold{T}$ 表示平移变换矩阵,$\bold{R}$ 表示旋转变换矩阵,$\bold{S}$ 表示缩放变换矩阵,$\bold{P}$ 表示物体的原始坐标。变换时注意要倒序相乘,而非顺序相乘。使用二维图形表示如下: + + + +有了物体,画面才能显示出来东西,通过模型变换,我们就可以在世界坐标系下任意移动物体了,可以把一个物体以任何形式放到世界中。 + +由于旋转和缩放也会影响平移,因此一般使用缩放->旋转->平移的顺序变换,这样可以准确控制物体的位置坐标、旋转及缩放。 + +## 视图变换 + +视图变换作用是把坐标系从世界坐标系转换至摄像机坐标系。在进行视图变换前,我们需要确定摄像机的朝向与位置。一般来说,我们通过三个坐标或向量来确定摄像机的位置与朝向: + +1. 摄像机坐标(Eye):摄像机所处的位置 +2. 目标朝向向量(Target):摄像机看向的方向 +3. 头顶朝向向量(Up):摄像机的正上方朝向 + +图示如下: + +![](https://feishu.cn/file/LBtcblRWOoppuPxj8DOcdIPWnKe) + +视图变换矩阵较为复杂,看一下就行,不需要记住,而且一般用不到,这里直接给出计算公式: + +$$\bold{M}_{Camera}=\begin{bmatrix} \vec{u_x} & \vec{u_y} & \vec{u_z} & -\vec{u}\cdot \vec{e} \\ \vec{v_x} & \vec{v_y} & \vec{v_z} & -\vec{v}\cdot \vec{e} \\ \vec{w_x} & \vec{w_y} & \vec{w_z} & -\vec{w}\cdot \vec{e} \\ 0 & 0 & 0 & 1 \end{bmatrix}$$ + +其中 $\vec{u}, \vec{v}, \vec{w}, \vec{e}$ 是三维向量,$\vec{u_x}, \vec{u_y}, \vec{u_z}$ 表示向量的 `x` `y` `z` 坐标。$\vec{e}$ 表示摄像机坐标,剩下的三个向量可以使用公式计算: + +$\vec{w}=-\frac{\vec{g}}{\lvert \vec{g} \rvert}$,$\vec{u}=\frac{\vec{t}\times\vec{w}}{\lvert \vec{t}\times\vec{w} \rvert}$,$\vec{v}=\vec{w}\times\vec{u}$ + +其中 $\vec{g}$表示观察方向向量,通过 Target 减去 Eye 并归一化得到,$\vec{t}$ 表示摄像机上方向向量,通过 Up 归一化得到。 + +## 投影变换 + +投影变换描述了将摄像机坐标系下的内容投影至摄像机平面的方式,常见的有透视投影和正交投影。投影变换会把三维空间降维至二维空间,因此经过变换的坐标可以直接在屏幕上渲染。在降维的同时,还保留了 `z` 坐标,仅用来描述深度,即距离观察者多远,不用来描述位置关系。 + +两个投影使用图示表示如下,左边是透视投影,右边是正交投影: + +![](https://feishu.cn/file/GXF9boIxroGqpRxs6Ucc3cxEnzW) + +### 透视投影 + +透视投影是人眼的投影方式,也是最常用的投影方式。使用透视投影时,摄像机能看到的区域是一个四棱锥,因此也被称为视锥体。 + +描述透视投影时,需要用到如下几个参数: + +- 近平面(near):能看到的距离摄像机最近的距离,比这更近的东西将会被裁剪 +- 远平面(far):能看到的距离摄像机最远的距离,比这更远的东西将会被裁剪 +- 视角(fovy):描述了摄像机在竖直方向的视角,需要小于 180°,值越大看到的内容越多越近,相当于广角镜头,值越小看到的内容越少越远,相当于长焦镜头。 +- 横纵比(aspect):画面横向宽度与纵向高度的比值。 + +在近平面以内的内容,经过投影后 `z` 坐标会大于 1,在远平面以外的内容,经过投影后 `z` 坐标会小于 -1,因此在二者之外的内容将会自动被 `WebGL2` 裁剪,不会显示,只有在这个范围内的会被显示。同样,`x` `y` 坐标也会自动归一化到 `-1 ~ 1` 的范围。 + +透视投影使用矩阵如下,也是看一眼就行,不需要记忆: + +$$\bold{M}_p=\begin{bmatrix} \frac{1}{a\cdot \tan\frac{F}{2}} & 0 & 0 & 0 \\ 0 & \frac{1}{\tan\frac{F}{2}} & 0 & 0 \\ 0 & 0 & \frac{n+f}{n-f} & -\frac{2nf}{n-f} \\ 0 & 0 & -1 & 0\end{bmatrix}$$ + +其中 $a$ 表示横纵比,$F$ 表示视角,$n$ 表示近平面,$f$ 表示远平面。 + +### 正交投影 + +正交投影常出现在三视图及工程设计图中,它的特征是没有近大远小,不论距离远近其大小都一致。不过它并不是只会用于三视图和工程设计图中,在图形学中有很多其他的用处。 + +描述透视投影我们会用到这些参数: + +- 左平面(left):能看到的内容中最靠左的位置 +- 右平面(right):能看到的内容中最靠右的位置 +- 上平面(top):能看到的内容中最靠上的位置 +- 下平面(bottom):能看到的内容中最靠下的位置 +- 近平面(near):能看到的距离摄像机最近的距离 +- 远平面(far):能看到的距离摄像机最远的距离 + +正交投影使用矩阵如下,也是看一眼就行: + +$$\bold{M}_o=\begin{bmatrix} \frac{2}{r-l} & 0 & 0 & -\frac{r+l}{r-l} \\ 0 & \frac{2}{t-b} & 0 & -\frac{t+b}{t-b} \\ 0 & 0 & \frac{2}{n-f} & -\frac{n+f}{n-f} \\ 0 & 0 & 0 & 1 \end{bmatrix}$$ + +其中 $l$ 表示左平面,$r$ 表示右平面,$t$ 表示上平面,$b$ 表示下平面,$n$ 表示近平面,$f$ 表示远平面。 + +## MVP 变换组合 + +最后,我们将三种变换组合起来,先进行模型变换,再进行视图变换,最后投影变换,即可计算出一个物体在画布上一个显示的位置。使用倒序的顺序相乘,可以表示为 $\bold{R}=\bold{M}_p\cdot\bold{M}_v\cdot\bold{M}_m\cdot\bold{P}$,其中 $\bold{M}_p$ 表示投影变换,$\bold{M}_v$ 表示视图变换,$\bold{M}_m$ 表示模型变换。 + +以上内容我们一般使用 `gl-matrix` 库实现,不会手动实现,也不要求会手动计算,知道计算原理即可。 + +# 6.4.10 屏幕空间 + +经过上述流程,我们得到了一个物体在裁剪坐标系(裁剪空间)下的位置,每个轴的坐标都在 `-1 ~ 1` 的范围内。不过,我们的设备显示屏实际上还是以左上角为原点,水平向右为 `x` 轴正方向,竖直向下为 `y` 轴正方向,我们还需要进行最后一次变换,将裁剪空间坐标映射到设备的屏幕空间。 + +这次映射我们需要四个参数: + +- 左上角横纵坐标:描述了 $x=-1,y=1$ 的坐标应该渲染至屏幕的哪个位置,单位像素 +- 视图宽高:描述了整个裁剪空间应该渲染至屏幕的宽度与高度,单位像素 + +使用图示表示: + + + +假设左上角坐标和屏幕的宽高分别为 $x,y,w,h$,那么裁剪空间有如下映射: + +| 裁剪空间坐标 | 屏幕空间坐标 | +|-|-| +| $(-1,1)$ | $(x,y)$ | +| $(1,1)$ | $(x+w,y)$ | +| $(-1,-1)$ | $(x,y+h)$ | +| $(1,-1)$ | $(x+w,y+h)$ | + +这一步将会最终确定内容应该渲染至屏幕的哪个地方。使用矩阵表示如下,依然是看一眼就行: + +$$\bold{M}_D=\begin{bmatrix} \frac{w}{2} & 0 & x+\frac{w}{2} \\ 0 & -\frac{h}{2} & y+\frac{h}{2} \\ 0 & 0 & 1 \end{bmatrix}$$ + +除了 `x` `y` 坐标,`z` 坐标也会映射,它会将 `-1` 映射至 `1`,将 `1` 映射至 `0`,即从 `-1 ~ 1` 的范围映射至了 `0 ~ 1` 的范围并反向。 + +# 6.4.11 工作流程总结 + +最后,我们来总结一下变换矩阵的工作流程。 + +给定一个物体,我们要将它显示在屏幕上,我们首先需要对其进行模型变换,得到它在世界坐标系的位置,即 $\bold{M}_m\bold{P}$。其中模型变换包含三部分,平移旋转和缩放,一般按照缩放->旋转->平移的顺序执行,倒序相乘,表示为 $\bold{M}_m=\bold{T}\cdot\bold{R}\cdot\bold{S}$。 + +接下来,需要进行视图变换,将世界坐标系转换为摄像机坐标系。在模型变换的基础上进行变换,表示为 $\bold{M}_v\cdot\bold{M}_m\cdot\bold{P}$。 + +然后执行投影变换,将摄像机坐标系转换为裁剪坐标系,表示为 $\bold{M}_p\cdot\bold{M}_v\cdot\bold{M}_m\cdot\bold{P}$。 + +最后执行屏幕空间变换,将裁剪空间映射到屏幕空间,确定应该渲染到屏幕的哪个地方,表示为 $\bold{M}_D\cdot\bold{M}_p\cdot\bold{M}_v\cdot\bold{M}_m\cdot\bold{P}$。 + +如果将模型变换展开,那么最终可以表示为这些矩阵的相乘:$\bold{M}_D\cdot\bold{M}_p\cdot\bold{M}_v\cdot\bold{T}\cdot\bold{R}\cdot\bold{S}\cdot\bold{P}$。 + +至此,我们终于讲完了如何确定一个物体应该画在屏幕上的哪个位置,从下节课开始,我们将开始讲解 `WebGL2` 的基本概念,并开始实操。 \ No newline at end of file diff --git a/.planning/references/feishu-teaching-docs/03.md b/.planning/references/feishu-teaching-docs/03.md new file mode 100644 index 0000000..ef945dc --- /dev/null +++ b/.planning/references/feishu-teaching-docs/03.md @@ -0,0 +1,247 @@ +6.5 类型化数组 + +在讲解 `WebGL2` 基本概念之前,我们必须先来讲解一下类型化数组这一概念。 + +与上节课相比,本节课的强度没那么高,会更好理解一些。 + +# 6.5.1 基本概念 + +类型化数组是一类纯数字数组,拥有固定的数据类型,它会在内存中连续存储,因此性能会比传统的数组更好(根据 benchmark,类型化数组的性能约为普通数组的两倍),但是它也有较大局限性,一般只会在性能敏感条件下或是二进制数据处理时使用。 + +类型化数组包含多个类型,其用法完全一致,区别只在于数据类型。常用的包括: + +- `Int8Array`:每个数据都是一个 8 位有符号整数,范围 `-128 ~ 127`。 +- `Uint8Array`:每个数据都是一个 8 位无符号整数,范围 `0 ~ 255`,是最常用的类型化数组之一。 +- `Uint8ClampedArray`:每个数据都是一个 8 位无符号整数,范围 `0 ~255`,与 `Uint8Array` 有一定的区别,不常用。区别会在后面讲解到。 +- `Int16Array`:每个数据都是一个 16 位有符号整数,范围 `-32768 ~ 32767`。 +- `Uint16Array`:每个数据都是一个 16 位无符号整数,范围 `0 ~ 65535`。 +- `Int32Array`:每个数据都是一个 32 位有符号整数,范围 `-2147483647 ~ 2147483648`。 +- `Uint32Array`:每个数据都是一个 32 位无符号整数,范围 `0 ~ 4294967295`。 +- `Float32Array`:每个数据都是一个 32 位浮点数,7 位有效数字,范围 `-3.4E38` 到 `3.4E38`,最小的正数是`1.2E-38`。是最常用的类型化数组之一。 +- `Float64Array`:每个数据都是一个 64 位浮点数,16 位有效数字,范围 `-1.8E308` 到 `1.8E308`,最小的正数是 `5E-324`。 + +这些类型化数组都有规律,记住一个就可以类比出其他的。必须掌握的是 `Float32Array` 和 `Uint8Array`,它们将会在后续大量使用到。 + +## 约定 + +后续内容中,将会大量使用十六进制的数据,因为两个十六进制数据刚刚好对应 `Uint8` 类型,`0x00` 为 0,`0xFF` 为 255。 + +# 6.5.2 长度 + +类型化数组包含两个长度,一个是数组长度,另一个是字节长度。其中数组长度很好理解,就是数组包含多少个数字。 + +对于字节长度,要看数组的数据类型。每 8 位是一个字节,因此容易推断出每一种数据类型的字节长度如下: + +| 数据类型 | 字节长度 | 数组字节长度 | +|-|-|-| +| `Int8` `Uint8` | 1 | `1 * length` | +| `Int16` `Uint16` | 2 | `2 * length` | +| `Int32` `Uint32` `Float32` | 4 | `4 * length` | +| `Float64` | 8 | `8 * length` | + +需要注意的是,类型化数组的长度是不可变的,其长度会在数组定义时确定,之后不可变。 + +# 6.5.3 创建类型化数组的基础方法 + +创建类型化数组的方法很多,但是我们目前只能讲解三种方法。 + +## 使用 `new` 直接创建 + +使用 `new` 创建类型化数组,并指定长度: + +```TypeScript +function TypedArray(length: number): TypedArray; +``` + +示例如下: + +```TypeScript +const array1 = new Uint8Array(16); // 创建一个 16 长度的 Uint8 类型化数组 +array1[2] = 16; // 给第三项赋值为 16 +array1[4] = 0x5C; // 给第五项赋值为 0x5C +const array2 = new Float32Array(32); // 创建一个 32 长度的 Float32 类型化数组 +array2[31] = 1.23456; // 给最后一项赋值为 1.23456 +``` + +如果不填写 `length` 参数,那么会创建一个长度为 0 的类型化数组。 + +## 通过数组创建 + +除了直接指定长度,还可以通过传入一个传统数组来创建类型化数组。例如: + +```TypeScript +const array1 = new Float32Array([1.1, 2.2, 3.3, 4.4]); // 创建一个长度为 4 的类型化数组 +const array2 = new Uint8Array([1, 2, 3, 4]); // 创建一个长度为 4 的类型化数组 +``` + +## 通过类型化数组创建 + +我们还可以直接指定一个类型化数组来创建,此操作会将类型化数组复制一份,并对数据类型进行数值转换。数值转换遵循数值相同原则,如果是浮点数向整数的转换,那么会向下取整。示例如下: + +```TypeScript +const array1 = new Uint8Array([1, 2, 3, 4]); // 创建一个长度为 4 的类型化数组 +const array2 = new Uint8Array(array1); // 复制一份 +const array3 = new Uint16Array(array2); // 复制为 Uint16Array +``` + +# 6.5.4 数据截断 + +如果你给整数类型化数组赋值了一个超出数据类型范围的值,那么将对数据截断。具体来说: + +对于 `Uint8ClampedArray`,将会钳制在 `0-255` 范围内,即小于 0 的数转换为 0,大于 255 的数转换为 255。 + +对于其他整数数组,将会直接截断高位,例如在 `Uint8Array` 中,赋值为 `256 = 0x100`,那么将会截断成 `0x00 = 0`,赋值为 `1234 = 0x4D2`,那么会截断成 `0xD2 = 210`,赋值为 `-20 = 0xF...EC`,那么将会截断成 `0xEC = 236`。 + +对于 `Float32Array`,超出范围的浮点数会存储为 `Infinity`,对于不超出范围的浮点数,将会通过算法将 `js` 使用的 64 位浮点数转换至最接近的 32 位浮点数。 + +# 6.5.5 字节序 + +字节序描述了计算机存储数据类型的方式,分为大字端与小字端。小字端表明数据是按照字节从低到高的顺序存储的,也是大部分设备与平台使用的存储方式;大字端表明数据是按照字节从高到低的顺序存储的,不那么常用。 + +举例来说,对于一个 32 位数据,例如 `0x12345678`,按照小字端存储时,每个字节将会存储为 `0x78 0x56 0x34 0x12`,按照大字端存储时,将会存储为 `0x12 0x34 0x56 0x78`。 + +小字端常用是因为使用这种存储方式时,如果数据较小,例如使用 32 位存储了 8 位,那么高位会全是 0,此时就可以省略高位,从而减小存储体积。 + +# 6.5.6 缓冲区 + +缓冲区描述了一个类型化数组的实际存储的内容的部分,内部是二进制数据,不能直接读取,需要使用类型化数组接收并读取。 + +缓冲区使用接口 `ArrayBuffer`,它仅包含字节长度,不包含数组长度,因为它实际上并不是一个数组,而是存储在内存的一系列连续数据。 + +## 获取缓冲区 + +我们可以获取类型化数组的缓冲区: + +```TypeScript +const array1 = new Uint8Array(8); // 定义类型化数组 +const buffer = array1.buffer; // 获取缓冲区 +``` + +## 从缓冲区创建类型化数组 + +我们可以通过缓冲区来创建类型化数组。例如: + +```TypeScript +const array1 = new Uint8Array(8); // 定义类型化数组 +const buffer = array1.buffer; // 获取缓冲区 +const array2 = new Uint8Array(buffer); // 从缓冲区创建类型化数组 +``` + +使用这种方式时,可以在不同数据类型之间转换,其转换规则遵循 5.5.5 小节中讲到的字节序,一般是小字端。举例来说,对于一串二进制数据 `0x12 0x34 0x56 0x78`,使用 `Uint8Array` 获取时,类型化数组将会是 `[0x12, 0x34, 0x56, 0x78]`,如果使用 `Uint16Array` 获取,类型化数组将会是 `[0x3412, 0x7856]`。如果使用浮点数创建,那么遵循 `IEEE 754` 浮点数规则。示例如下: + +```TypeScript +const array1 = new Uint8Array([0x12, 0x34, 0x56, 0x78]); +const buffer = array1.buffer; +const array2 = new Uint32Array(buffer); // 使用 32 位整数 +array2[0]; // 0x78563412 +``` + +## 内存共享 + +对于引用了同一个 `ArrayBuffer` 的类型化数组,其使用同一个缓冲区,因此内存也是共享的,当一个类型化数组变化时,其他的也会同步改变: + +```TypeScript +const array1 = new Uint8Array([0x12, 0x34, 0x56, 0x78]); +const buffer = array1.buffer; +const array2 = new Uint32Array(buffer); // 使用 32 位整数 +array1[2] = 0x00; +array2[0]; // 0x78560012; +array2[0] = 0x12345678; +array1; // [0x78, 0x56, 0x34, 0x12] +``` + +## 字节偏移与长度 + +在使用 `ArrayBuffer` 创建类型化数组时,可以指定字节偏移与长度。具体来说,类型化数组会从指定的偏移位置开始读取,然后读取指定长度的字节,并构建为类型化数组。举例来说: + +```TypeScript +const array1 = new Uint8Array([0x12, 0x34, 0x56, 0x78]); +const array2 = new Uint8Array(array1.buffer, 1, 2); // 偏移为 1,长度为 2 +array2; // [0x34, 0x56],从偏移一个字节的位置开始读取,读取两个字节 +``` + +注意,这里的偏移与长度都是字节偏移与长度,并非数组的偏移与长度,例如使用 `Uint16Array` 创建时: + +```TypeScript +const array1 = new Uint16Array([0x1234, 0x3456, 0x5678, 0x789A]); +const array2 = new Uint8Array(array1.buffer, 1, 4); // 偏移为 1,长度为 2 +array2; // [0x12, 0x56, 0x34, 0x78],从偏移一个字节的位置开始读取,读取四个字节 +``` + +## 关于修改长度 + +在新标准中,可以通过 `ArrayBuffer.resize` 来调整缓冲区的字节长度,但是由于其对浏览器版本要求高,兼容性差,并不推荐使用。 + +# 6.5.7 类型化数组方法 + +类型化数组包含大部分数组也包含的方法,正好复习一遍之前的内容: + +- `at`:获取数组某一项的值,可以填入负数表示从末尾获取。 +- `copyWithin`:这个之前没讲过,马上讲,普通数组也有这个方法,但是相对不常用。 +- `every`:判断是否每一项都满足条件。 +- `fill`:将数组全部填充为某个值。 +- `filter`:对数组每一项判断是否满足条件,将满足条件的数据单独组成一个新的类型化数组。 +- `find` `findIndex` `findLast` `findLastIndex`:根据条件获取符合条件的项。 +- `forEach`:遍历数组。 +- `includes`:判断数组是否包含某个数据。 +- `indexOf` `lastIndexOf`:获取指定数据的索引位置。 +- `join`:在每个数据之间插入字符串并将整体合并为一个字符串。 +- `map`:对数组进行遍历,并将每一项映射为一个新的值,新值组成一个新的类型化数组。 +- `reduce` `reduceRight`:数组求和。 +- `reverse`:翻转类型化数组,并非简单的指针反向,缓冲区的数据也会同时反向。 +- `slice`:裁剪数组,将结果组成一个新的类型化数组。 +- `some`:判断数组中是否至少有一项满足条件。 +- `sort`:数组排序。 + +## `set` 方法 + +`set` 方法提供了一种高效的设置类型化数组的值的方法,它要求传入一个数组或类型化数组,并指定偏移量,方法将会把传入数组拷贝至目标数组指定偏移量的位置。这里的偏移量并非字节偏移量,而是下标偏移量。方法的类型声明如下: + +```TypeScript +function set(array: Array | TypedArray, targetOffset?: number): void; +``` + +示例如下: + +```TypeScript +const array = new Uint8Array([0x00, 0x12, 0x11, 0x22, 0x33]); +array.set([0x40, 0x50], 2); // array 会变成 [0x00, 0x40, 0x50, 0x22, 0x33] +``` + +这种方式的性能远比手动循环赋值更快,因此多数情况下更推荐使用这种方式。 + +如果传入的类型化数组与目标数组使用同一 `ArrayBuffer`,那么将会直接进行拷贝,速度更快。 + +## `copyWithin` 方法 + +`copyWithin` 方法提供了一种高效的在数组内拷贝数据的方法。其类型声明如下: + +```TypeScript +function copyWithin(target: number, start: number, end?: number): void; +``` + +`target` 表示要将数据拷贝至那个地方,`start` 表示数据开始拷贝的下标,`end` 表示数据结束拷贝的下标。方法会将从 `start` 下标至 `end` 下标(不填时表示结尾)区间的内容拷贝至 `target` 开始的区域。拷贝的区域允许重合。举例来说: + +```TypeScript +const array = new Uint8Array([0x00, 0x12, 0x11, 0x22, 0x33]); +array.copyWithin(3, 0, 2); // [0x00, 0x12, 0x11, 0x00, 0x12] 将前两项拷贝至下标 3 开头的地方 +array.copyWithin(1, 0, 4); // [0x00, 0x00, 0x12, 0x11, 0x00] 将前四项拷贝至下标 1 开头的地方 +``` + +## `subarray` 方法 + +`subarray` 方法用于提取类型化数组的子数组,同时与原数组共用同一 `ArrayBuffer`,共用同一内存。 + +```TypeScript +function subarray(start: number, end?: number): TypedArray +``` + +其中 `start` 表示裁剪起始索引,`end` 表示裁剪结尾索引,裁剪结果不包含此索引,不填表示裁剪至末尾。由于此方法不会创建新的内存缓冲区,因此速度极快,可以方便地将一个长数组分割为多个短数组,便于维护和操作。例如我们将一个 64 长度的数组分割为四个 16 长度的数组: + +```TypeScript +const array = new Float32Array(64); +const array1 = array.subarray(0, 16); +const array2 = array.subarray(16, 32); +const array3 = array.subarray(32, 48); +const array4 = array.subarray(48, 64); +``` \ No newline at end of file diff --git a/.planning/references/feishu-teaching-docs/04.md b/.planning/references/feishu-teaching-docs/04.md new file mode 100644 index 0000000..a1e7a3c --- /dev/null +++ b/.planning/references/feishu-teaching-docs/04.md @@ -0,0 +1,520 @@ +6.6 WebGL2 基本概念 + +经过了前两节课的铺垫,我们终于可以开始真正接触 `WebGL2` 了。本节课将会先讲解一些 `WebGL2` 中的必要概念。 + +# 6.6.1 创建 `WebGL2` 画布 + +与 `Canvas2D` 类似,我们需要先创建一个 `canvas` 标签,然后调用 `getContext` 方法,不过这里的参数我们需要填写 `webgl2`: + +```TypeScript +const canvas = document.createElement('canvas'); +const gl = canvas.getContext('webgl2')!; // 获取画布上下文 +``` + +如果浏览器不支持 `WebGL2`,或是之前已经创建了其他的上下文,那么 `getContext` 会返回 `null`,因此这里最后添加了非空断言,从而避免后续类型演算出问题。 + +获取 `webgl2` 上下文时,可以指定一些配置,常用的包括: + +- `alpha`:是否开启透明度通道,默认开启。 +- `antialias`:是否开启抗锯齿,默认开启。 +- `depth`:开启后,`WebGL2` 将会提供至少 16 位的深度缓冲区,默认开启。深度缓冲区的概念将会在后续讲解。 + +一般情况下遵循默认设置即可,如果你需要修改设置,可以给 `getContext` 传入第二个参数: + +```TypeScript +const gl = canvas.getContext('webgl2', { alpha: false }); // 关闭 alpha 通道 +``` + +# 6.6.2 术语与约定 + +## 术语 + +- 源内容:指将要画到画布上的内容。 +- 目标内容:指画布上的已有内容。 +- NDC 坐标:经过 MVP 变换后的坐标,未经过屏幕坐标变换。 + +## 约定 + +- 每个 `RGBA` 通道的值都在 `0 ~ 1` 之间,对于八位色深(大部分显示器的色深),0 对应到 0,1 对应到 255。注意与 `Canvas2D` 区分。 + +# 6.6.3 混合模式 + +默认情况下,`WebGL2` 在渲染时会将渲染区域的内容全部覆盖,并且 `alpha` 通道无效。默认设置很可能不符合我们的预期,因此我们在创建画布后设置画布的混合模式。 + +设置混合模式使用 `gl.enable` 和 `gl.blendFunc` 接口。我们需要先使用 `gl.enable` 开启 `gl.BLEND`,然后使用 `gl.blendFunc` 设置混合模式。一般我们会使用简单 alpha 混合,使用如下代码设置: + +```TypeScript +gl.enable(gl.BLEND); +gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA); +``` + +## 混合模式公式 + +混合模式有一个通用的公式: + +$$c=(s\times f_s)+(d\times f_d)$$ + +这里的 $c$ 描述了最终呈现的颜色,$s$ 指源内容的颜色,$d$ 指目标内容的颜色,$f_s,f_d$ 指混合因子,$f_s$ 由 `blendFunc` 的第一个参数指定,$f_d$ 由 `blendFunc` 的第二个参数指定。 + +`blendFunc` 需要传入两个 `WebGL2` 混合模式常量,下面列一个表来描述常见常量。每个常量对应一个混合因子($f_s$ 或 $f_d$),因子分为 `R G B A` 四个通道,使用 $R_s,G_s,B_s,A_s$ 描述源内容的 `RGBA` 通道,$R_d,G_d,B_d,A_d$ 描述目标内容的 `RGBA` 通道。列表如下: + +| 常量 | `R` 通道 | `G` 通道 | `B` 通道 | `A` 通道 | 文字描述 | +|-|-|-|-|-|-| +| `gl.ZERO` | $0$ | $0$ | $0$ | $0$ | 颜色乘以 0 | +| `gl.ONE` | $1$ | $1$ | $1$ | $1$ | 颜色乘以 1 | +| `gl.SRC_COLOR` | $R_s$ | $G_s$ | $B_s$ | $A_s$ | 颜色乘以源颜色 | +| `gl.ONE_MINUS_SRC_COLOR` | $1-R_s$ | $1-G_s$ | $1-B_s$ | $1-A_s$ | 颜色乘以 1 减源颜色 | +| `gl.DST_COLOR` | $R_d$ | $G_d$ | $B_d$ | $A_d$ | 颜色乘以目标颜色 | +| `gl.ONE_MINUS_DST_COLOR` | $1-R_s$ | $1-G_s$ | $1-B_s$ | $1-A_s$ | 颜色乘以 1 减目标颜色 | +| `gl.SRC_ALPHA` | $A_s$ | $A_s$ | $A_s$ | $A_s$ | 颜色乘以源不透明度 | +| `gl.ONE_MINUS_SRC_ALPHA` | $1-A_s$ | $1-A_s$ | $1-A_s$ | $1-A_s$ | 颜色乘以 1 减源不透明度 | +| `gl.DST_ALPHA` | $A_d$ | $A_d$ | $A_d$ | $A_d$ | 颜色乘以目标不透明度 | +| `gl.ONE_MINUS_DST_ALPHA` | $1-A_d$ | $1-A_d$ | $1-A_d$ | $1-A_d$ | 颜色乘以 1 减目标不透明度 | + +以上是常用的混合因子。由此我们可以推断出简单 alpha 混合的混合公式: + +$$c=s\times A_s+d\times (1-A_s)$$ + +这也是 `Canvas2D` 中 `source-over` 混合模式所使用的混合因子。 + +上面这些混合因子可以自由混合,例如: + +```TypeScript +gl.enable(gl.BLEND); +gl.blendFunc(gl.SRC_COLOR, gl.SRC_ALPHA); +``` + +就会将混合公式设为: + +$$c=s\times (R_s,G_s,B_s,A_s)+d\times A_s$$ + +# 6.6.4 数据缓冲区 + +`WebGL2` 使用显卡渲染,因此我们不能使用传统的方法来给它传递参数,因为显卡有独立的内存区域,与 CPU 并不共享,因此我们需要将数据通过缓冲区传递给显卡,之后再进行渲染操作。 + +`WebGL2` 是一个巨大的状态机,使用缓冲区传递数据时需要先设定我要传输什么内容,确定好传输状态,然后再进行传输。 + +## 创建缓冲 + +创建缓冲使用 `createBuffer` 接口: + +```TypeScript +function createBuffer(): WebGLBuffer; +``` + +直接调用创建即可: + +```TypeScript +const buffer = gl.createBuffer(); +``` + +返回值的 `WebGLBuffer` 不包含任何接口,因此 `ts` 会将它识别为与空对象相同,从而导致潜在的类型错误,需要注意。 + +## 绑定缓冲区 + +接下来我们需要把创建的缓冲区绑定至 `WebGL2`,使用 `bindBuffer` 接口: + +```TypeScript +function bindBuffer(target: GLenum, buffer: WebGLBindBuffer): void; +``` + +这里的 `target` 指要绑定至哪个缓冲区,`buffer` 指的是刚刚用 `createBuffer` 创建的缓冲。这个方法的重点是第一个参数 `target`,在不同场景下要填入不同的值。`WebGL2` 一共给我们提供了八个缓冲区,我们可以在这八个缓冲区中操作修改缓冲数据。不过由于我们压根还没有学各种场景,因此我们这里只介绍一种用法,绑定至 `gl.ARRAY_BUFFER` 缓冲区: + +```TypeScript +const buffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, buffer); +``` + +这样,我们刚刚创建的缓冲就被绑定在了 `gl.ARRAY_BUFFER` 上,之后再去操作 `gl.ARRAY_BUFFER`,我们操作的就是刚刚创建的 `buffer` 缓冲。至于其他的七种缓冲区,我们之后再去说,现在还讲不了。 + +## 缓冲区操作 + +绑定缓冲区之后,我们需要用 `bufferData` 或 `bufferSubData` 为缓冲区赋值。 + +### `bufferData` + +`bufferData` 一般用于重新给缓冲区赋值,它会为缓冲区重新分配内存并赋值,因此速度相对较慢,一般只会在内容长度修改或者第一次赋值时使用。它的用法如下: + +```TypeScript +function bufferData(target: GLenum, size: number, usage: GLenum): void; +function bufferData(target: GLenum, src: ArrayBuffer | TypedArray, usage: GLenum): void; +function bufferData(target: GLenum, src: ArrayBuffer | TypedArray, usage: GLenum, srcOffset: number, length: number): void; +``` + +三种用法分别描述如下: + +1. 给缓冲区设置长度为 `size`(字节长度),并全部填充为 0。 +2. 给缓冲区赋值为 `src`,字节长度也设为 `src` 对应的字节长度。 +3. 给缓冲区赋值为 `src`,从 `src` 的第 `srcOffset` 索引位置开始读取(非字节长度),读取 `length` 个数据(非字节长度),字节长度设为 `length * byte`,即 `length` 乘以单个数据的字节数。 + +使用时,第一个参数 `target` 填写上述绑定缓冲区的 `target`,例如我们刚刚绑定了 `gl.ARRAY_BUFFER` 缓冲区,这里的 `target` 也要填写 `gl.ARRAY_BUFFER`。 + +`usage` 描述了缓冲区数据的使用场景,`WebGL2` 会根据使用场景进行优化。常用的 `usage` 包括下面这些: + +- `gl.STATIC_DRAW`:缓冲区的内容可能经常使用,而基本不会被更改。此操作用于给缓冲区赋值。 +- `gl.DYNAMIC_DRAW`: 缓冲区的内容可能经常被使用,并且经常更改。此操作用于给缓冲区赋值。 +- `gl.STREAM_DRAW`:缓冲区的内容可能不被经常使用,而且基本不会被更改。此操作用于给缓冲区赋值。 + +例如,我们需要传入一个不被经常修改而可能被经常使用的缓冲,可以这么写: + +```TypeScript +const src = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); +const buffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, buffer); +gl.bufferData(gl.ARRAY_BUFFER, src, gl.STATIC_DRAW); +``` + +### `bufferSubData` + +`bufferSubData` 用于更新缓冲区的内容,它不会重新分配内存,因此性能也会比 `bufferData` 更好。它的用法如下: + +```TypeScript +function bufferSubData(target: GLenum, offset: number, srcData: ArrayBuffer | TypedArray): void; +function bufferSubData(target: GLenum, offset: number, srcData: ArrayBuffer | TypedArray, srcOffset: number, srcLength?: number): void; +``` + +它的用法与 `bufferData` 类似,`target` 描述要赋值的缓冲区,两种用法说明如下: + +1. 从缓冲区的 `offset` 字节开始赋值,赋值为 `srcData`。 +2. 从缓冲区的 `offset` 字节开始赋值,赋值为 `srcData`,读取 `srcData` 时从 `srcOffset` 索引开始(非字节长度),读取 `srcLength` 长度(非字节长度)。 + +示例如下: + +```TypeScript +const src = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); +const buffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, buffer); +gl.bufferData(gl.ARRAY_BUFFER, src, gl.DYNAMIC_DRAW); // usage 改为 DYNAMIC_DRAW +// 此时缓冲区为 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 +const src2 = new Uint16Array([0xABCD, 0x7890]); +gl.bufferSubData(gl.ARRAY_BUFFER, 2, src2); +// 此时缓冲区为 0x01 0x02 0xCD 0xAB 0x90 0x78 0x07 0x08 +``` + +### 常见问题 + +1. 既然 `target` 最多只有八个,那我是不是只能绑定八个缓冲区? + +答:是的。我们一般只会使用两三个,如果一个 `target` 有多个缓冲区,我们会一个个 `bindBuffer` 再 `bufferData`。 + +1. 为什么缓冲区赋值要这么复杂? + +答:因为这是在操作显卡,我们需要在 CPU 代码里面操作显卡,告诉显卡数据是什么,因此操作起来与 CPU 变量的赋值读取完全不同。这些操作都是必要的。 + +## 删除缓冲区 + +如果一个缓冲区数据不再会被使用,那么需要删除它,使用 `gl.deleteBuffer` 接口: + +```TypeScript +function deleteBuffer(buffer: WebGLBuffer): void; +``` + +示例如下: + +```TypeScript +const buffer = gl.createBuffer(); +gl.deleteBuffer(buffer); // 删除缓冲区数据 +``` + +# 6.6.5 顶点 + +为了让 `WebGL2` 能画出来东西,我们必须告诉他要在哪些地方画东西,这一操作是通过顶点完成的。 + +我们会有这些绘制方法:画点、画线、画平面。我们最常用的是画平面,画点和画线很少用到,因为它们都可以通过画平面实现,我们也不再讲解画点和画线。 + +## 顶点数组 + +由于物体有多个顶点,因此我们使用数组来描述。一般来说,一个顶点可能会有两个、三个坐标,分别对应二维和三维。 + +定义顶点数组时,我们直接把坐标按照 `x` `y` `z` 的顺序排列在 `Float32Array` 类型化数组中即可。如果顶点是二维的,只需填写 `x` `y`,两个一组,如果是三维的,则需要三个一组。例如: + +```TypeScript +const vertex1 = new Float32Array([1, 1, 1, 2, 2, 2, 3, 3, 3]); // 三个点分别是 (1,1,1) (2,2,2) (3,3,3) +const vertex2 = new Float32Array([1, 1, 2, 2, 3, 3, 4, 4]); // 四个点分别是 (1,1) (2,2) (3,3) (4,4) +``` + +我们会发现一个问题,我们如何区分顶点是二维的还是三维的呢?这个问题暂时无法解答,需要留到后面的课程。 + +## 赋值到缓冲区 + +接下来,我们就可以按照 5.6.4 中的方式给缓冲区赋值了,代码如下: + +```TypeScript +const vertex = new Float32Array([1, 1, 1, 2, 2, 2, 3, 3, 3]); +const buffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, buffer); +gl.bufferData(gl.ARRAY_BUFFER, vertex, gl.STATIC_DRAW); +``` + +## 连接方式 + +我们会以三角形作为平面的基本单位,三个点组成一个三角形。而组成三角形时也有不同的方式,列表如下,图示中的数字代表是第几个顶点: + +
连线方式文字说明图解说明
gl2.TRIANGLES每三个坐标代表一个三角形
gl2.TRIANGLE_STRIP前三个坐标代表一个三角形,后面每个坐标都会与前两个坐标相连形成三角形
gl2.TRIANGLE_FANS第一个坐标代表中心点,之后的两个坐标与第一个坐标形成三角形,之后的每个坐标与前一个坐标以及中心点形成三角形
+ +这三种连线方式都非常常用,务必理解并掌握。 + +## 三角形方向 + +顶点组成三角形会分为顺时针和逆时针,例如 `(0,0) (2,0) (1,1)` 三个点就以逆时针形成三角形。图示如下: + + + +我们定义逆时针三角形为顺向三角形,顺时针三角形为逆向三角形。 + +我们考虑一个正方体,它一共有六个面,共十二个三角形(正方形面由两个三角形组成),此时当我们看向正方体时,最多只能看到三个面六个三角形,剩余的三角形看不见。这时如果还对它们进行渲染,就会额外产生不必要的开销,因此我们需要面剔除的功能。 + +在 `WebGL2` 中,使用 `cullFace` 接口设置面剔除模式,使用 `enable` 开启面剔除: + +```TypeScript +gl.enable(gl.CULL_FACE); +gl.cullFace(gl.BACK); +``` + +此时,`WebGL2` 就会开启面剔除的功能,并自动剔除逆向三角形(顺时针三角形)。如果想要剔除顺向三角形,可以使用 `gl.cullFace(gl.FRONT)`。 + +# 6.6.6 深度检测 + +我们之前提到过 `z` 坐标超出 `-1 ~ 1` 范围的内容会被裁剪掉,这说明 `z` 坐标会有裁剪功能。但是除了裁剪,`z` 坐标还可以描述深度,即距离观察者有多远。 + +经过投影变换后,靠近观察者的物体 `z` 坐标更大,远离观察者的物体 `z` 坐标更小,因此我们可以通过 `z` 坐标来描述物体之间的遮挡关系,`z` 坐标大的会遮挡 `z` 坐标小的。通过判断 `z` 坐标,我们可以判断一个物体是否被遮挡,从而决定它是否应该被渲染,被遮挡就不渲染,不被遮挡就渲染,从而提高渲染性能。这一行为称为深度检测。 + +我们一般会使用 NDC 坐标进行推理,而在实际渲染时,深度检测是在屏幕坐标上进行的。因此在设定深度检测模式时,判断方式会与我们的推理刚好相反。参考 5.4.10 最后对屏幕变换的描述。 + +在深度检测中,如果判断一个物体需要被渲染,它会被叫做通过深度测试。 + +在 `WebGL2` 中,使用 `gl.enable` 开启深度检测: + +```TypeScript +gl.enable(gl.DEPTH_TEST); +``` + +使用 `gl.depthFunc` 调整深度检测模式,常见的有这些模式: + +- `gl.NEVER`:从不通过,即从不渲染 +- `gl.LESS`:深度值小于当前深度值的通过,`z` 坐标小的覆盖大的。在 NDC 坐标下,就是 `z` 坐标大的覆盖小的。这是默认设置,也是常用设置。 +- `gl.LEQUAL`:深度值小于等于当前深度值的通过,`z` 坐标小的覆盖大的,但是还包含相同的场景。在 NDC 坐标下,就是 `z` 坐标大的覆盖小的。 + +设置示例如下: + +```TypeScript +gl.enable(gl.DEPTH_TEST); +gl.depthFunc(gl.LEQUAL); +``` + +# 6.6.7 着色器概念 + +着色器是显卡能够直接执行的代码,分为顶点着色器和片段着色器两种。顶点着色器用于确定绘制顶点,片段着色器用于确定每个像素的颜色。 + +由于着色器内容比较复杂,本节课暂且不讲着色器代码如何编写以及其含义,只讲解着色器的基本概念以及如何编译链接着色器。 + +## 顶点着色器 + +顶点着色器英文是 `vertex shader`,用来确定绘制顶点。具体来说,它用于将世界坐标下的顶点位置映射至 NDC 坐标。 + +例如,给定一个立方体,它一共包含 12 个三角形,使用 `gl.TRIANGLES` 连接方式时需要 36 个顶点,那么 `WebGL2` 会依次将这 36 个顶点传入,经过着色器计算后,得到对应的 36 个 NDC 坐标。这样,再根据连接方式,`WebGL2` 就可以确定需要在哪些地方渲染了。 + +## 片段着色器 + +片段着色器英文是 `fragment shader`,用来确定每个像素的颜色。有时还称为片元着色器或像素着色器。 + +当确定了顶点之后,`WebGL2` 会对顶点范围内的所有像素遍历,并调用片段着色器得到这一像素的颜色。 + +## 创建着色器 + +着色器代码使用字符串定义,并通过 `createShader` 与 `shaderSource` 传递。二者的类型声明如下: + +```TypeScript +function createShader(type: GLenum): WebGLShader; +function shaderSource(shader: WebGLShader, source: string): void; +``` + +首先定义一个着色器代码(暂时不用管代码是干什么的): + +```TypeScript +// 顶点着色器 +const vs = /* glsl */ `#version 300 es +precision highp float; + +in vec4 a_position; +uniform mat4 u_matrix; + +void main() { + gl_Position = u_matrix * a_position; +} +`; +// 片段着色器 +const fs = /* glsl */ `#version 300 es +precision highp float; + +out vec4 outColor; + +void main() { + outColor = vec4(1.0, 1.0, 1.0, 1.0); +} +`; +``` + +然后分别创建顶点着色器与片段着色器对象: + +```TypeScript +const vsShader = gl.createShader(gl.VERTEX_SHADER); // 创建顶点着色器 +const fsShader = gl.createShader(gl.FRAGMENT_SHADER); // 创建片段着色器 +``` + +然后将着色器代码传递给着色器对象: + +```TypeScript +gl.shaderSource(vsShader, vs); // 顶点着色器 +gl.shaderSource(fsShader, fs); // 片段着色器 +``` + +# 6.6.8 `WebGL2` 程序 + +`WebGL2` 程序存储了顶点着色器与片段着色器代码,包含了程序的状态信息,可以被显卡执行。 + +## 创建程序 + +创建程序使用 `gl.createProgram`,类型声明如下: + +```TypeScript +function createProgram(): WebGL2Program; +``` + +示例如下: + +```TypeScript +const program = gl.createProgram(); +``` + +## 编译着色器 + +程序创建完成之后不能直接运行,因为我们还没有给它添加着色器,添加之前我们需要先编译着色器,使用 `gl.compileShader` 接口,类型声明如下: + +```TypeScript +function compileShader(shader: WebGLShader): void; +``` + +示例如下: + +```TypeScript +const vsShader = gl.createShader(gl.VERTEX_SHADER); // 创建顶点着色器 +const fsShader = gl.createShader(gl.FRAGMENT_SHADER); // 创建片段着色器 +gl.shaderSource(vsShader, vs); // 顶点着色器代码 +gl.shaderSource(fsShader, fs); // 片段着色器代码 +gl.compileShader(vsShader); // 编译顶点着色器 +gl.compileShader(fsShader); // 编译片段着色器 +``` + +## 添加着色器 + +着色器编译完成后,我们还需要给程序添加着色器,使用 `attachShader` 接口: + +```TypeScript +function attachShader(program: WebGLProgram, shader: WebGLShader); +``` + +示例如下: + +```TypeScript +gl.attachShader(program, vsShader); // 顶点着色器 +gl.attachShader(program, fsShader); // 片段着色器 +``` + +着色器与程序是分开的两个概念,因此多个程序可以共用一个着色器,例如共用一个顶点着色器,这在一些场景下非常方便。 + +## 链接着色器程序 + +最后我们需要链接着色器程序,让程序能够在显卡上运行,使用 `linkProgram` 即可: + +```TypeScript +function linkProgram(program: WebGLProgram): void; +``` + +下面的例子将创建着色器、编译着色器、创建程序等放在一起: + +```TypeScript +const vsShader = gl.createShader(gl.VERTEX_SHADER); // 创建顶点着色器 +const fsShader = gl.createShader(gl.FRAGMENT_SHADER); // 创建片段着色器 +gl.shaderSource(vsShader, vs); // 顶点着色器代码 +gl.shaderSource(fsShader, fs); // 片段着色器代码 +gl.compileShader(vsShader); // 编译顶点着色器 +gl.compileShader(fsShader); // 编译片段着色器 + +const program = gl.createProgram(); // 创建着色器程序 +gl.attachShader(program, vsShader); // 添加顶点着色器 +gl.attachShader(program, fsShader); // 添加片段着色器 +gl.linkProgram(program); // 链接着色器程序 +``` + +## 删除程序与着色器 + +如果一个程序和着色器不会再被使用到,需要使用 `gl.deleteProgram` 和 `gl.deleteShader` 删除。它们的定义如下: + +```TypeScript +function deleteProgram(program: WebGLProgram): void; +function deleteShader(shader: WebGLShader): void; +``` + +示例如下: + +```TypeScript +gl.deleteProgram(program); // 删除程序 +gl.deleteShader(vsShader); // 删除顶点着色器 +gl.deleteShader(fsShader); // 删除片段着色器 +``` + +# 6.6.9 内置缓冲区 + +注意,本节与 5.6.4 的数据缓冲区不同。 + +这里的缓冲区是指 `WebGL2` 内置的一些缓冲区,包括颜色缓冲区、深度缓冲区等。 + +## 颜色缓冲区 + +渲染时,`WebGL2` 会先把内容绘制到颜色缓冲区,然后设备的显示器读取颜色缓冲区的内容并显示出来。一般来讲,颜色缓冲区至少是双缓冲,内容会渲染至第一层缓冲,然后再推送给第二层缓冲,最后由显示器读取第二层缓冲。这么做是为了保证渲染完成前不会被显示器读取并显示出来,避免出现画面撕裂或是只渲染了一部分的情况。 + +一般来说,我们在渲染内容前,需要先清空颜色缓冲区。我们需要使用 `gl.clearColor` 设置清空为什么颜色,再调用 `gl.clear` 清空缓冲区。二者的类型声明如下: + +```TypeScript +function clearColor(r: number, g: number, b: number, a: number): void; +function clear(bit: GLbitfield): void; +``` + +示例如下: + +```TypeScript +gl.clearColor(0, 0, 0, 0); // 清空为透明色 +gl.clear(gl.COLOR_BUFFER_BIT); // 清空颜色缓冲区 +``` + +## 深度缓冲区 + +深度缓冲区是在深度检测时用到的。在渲染时,一个像素的深度值会与深度缓冲区的值进行比较,如果满足条件(比如 `gl.LESS`),那么会更新深度缓冲区,并渲染这个像素,否则就不会做渲染。而在比较时,我们需要为深度缓冲区设定一个初始值,否则像素就不知道跟谁比较了。 + +由于深度值越大越远离观察者,因此我们一般将深度缓冲区设为 1。使用 `clearDepth` 设置: + +```TypeScript +function clearDepth(depth: number): void; +``` + +示例如下: + +```TypeScript +gl.clearDepth(1); // 深度缓冲区设为 1,这一步仅是配置项,不会进行清理 +gl.clear(gl.DEPTH_BUFFER_BIT); // 清空深度缓冲区并设为 1 +``` + +而在渲染前,我们一般是需要同时清空深度缓冲区和颜色缓冲区的,我们可以这么写: + +```TypeScript +gl.clearColor(0, 0, 0, 0); +gl.clearDepth(1); +gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); // 将两个清空项用按位或连接,就可以同时清理 +``` + +# 6.6.10 总结 + +那么到现在,我们终于讲完了必要的前置知识,从下节课开始,我们将真正开始实操学习如何使用 `WebGL2` 进行渲染!下节课,我们将会学会如何渲染一个三角形出来! + +相信你看到现在还有很多不懂的地方,不过没关系,有很多知识是相互关联的,我们无法一次性讲完,只能先讲一部分。等到后面,我们还有机会对一些复杂的地方进行复盘,从而了解其更底层的原理。 \ No newline at end of file diff --git a/.planning/references/feishu-teaching-docs/05.md b/.planning/references/feishu-teaching-docs/05.md new file mode 100644 index 0000000..842411d --- /dev/null +++ b/.planning/references/feishu-teaching-docs/05.md @@ -0,0 +1,697 @@ +6.7 学会用 WebGL2 画三角形 + +本节将会教你画出一个三角形,效果如图所示: + +![](https://feishu.cn/file/HT6Ebg0IaoEzxjxh5XCcBIIkn6o) + +你可以打开 https://codepen.io/unanmed/pen/myVdXJj 来查看源代码,或者 Fork 后自行修改一部分内容。 + +下面我们将会讲解如何画出来这个三角形。 + +具体来说,我们的目标是传入三个顶点,按照这三个顶点画出三角形,填充为白色。 + +# 6.7.1 创建画布 + +我们使用 300\*300 大小的画布,先编写 `HTML` 内容: + +```HTML + +``` + +然后编写 `CSS` 设定画布的尺寸: + +```CSS +/* 使用 # 选中指定 id 的元素 */ +#webgl { + width: 300px; + height: 300px; +} +``` + +在 `ts` 中使用 `querySelector` 获取元素并获取 `WebGL2` 上下文: + +```TypeScript +const canvas = document.querySelector("#webgl"); +const gl = canvas.getContext("webgl2")!; +``` + +设置画布的像素宽高: + +```TypeScript +canvas.width = 300 * devicePixelRatio; +canvas.height = 300 * devicePixelRatio; +``` + +# 6.7.2 着色器 + +着色器是一个复杂庞大的概念,我们没办法一次性讲完,我们会在之后的课程中一步步讲解。本节课先来讲解画出三角形所必须的语法与接口。 + +`WebGL2` 着色器使用 `OpenGL ES 3.0` 标准,使用 `GLSL` 着色器语言。我们不再讲解旧版着色器的内容,直接讲解 `ES 3.0` 着色器。 + +在 `vscode` 中,我们可以通过 `es6-string-html` 插件来让模板字符串有代码高亮功能,因此我们一般会在着色器代码之前添加一个 `/* glsl */` 的内联注释。 + +## 声明着色器版本 + +为了让 `WebGL2` 知道你使用的是 `ES 3.0` 标准,需要在第一行加上 `#version 300 es`,注意是第一行,不能是第二行,也不能是第一行空一格空格开始写。正确与错误示例如下: + +```TypeScript +// 正确示例 +const source = /* glsl */ `#version 300 es +// 着色器代码 +`; + +// 错误示例-1 不在第一行 +const source = /* glsl */ ` +#version 300 es +`; + +// 错误示例-2 有空格 +const source = /* glsl */ ` #version 300 es +`; + +// 错误示例-3 有空格 +const source = /* glsl */ `# version 300 es +`; + +// 错误示例-4 有分号 +const source = /* glsl */ `#versoin 300 es; +`; +``` + +## 定义数值精度 + +接下来我们需要定义浮点数的数值精度,它分为 `lowp` `mediump` `highp` 三个精度,分别对应低精度、中精度、高精度,具体区别如下: + +| 精度 | 浮点数范围 | 浮点数绝对精度 | 浮点数相对精度 | +|-|-|-|-| +| `lowp` | $(-2,2)$ | $2^{-8}$ | $2^{-8}$ | +| `mediump` | $(-2^{14},2^{14})$ | $2^{-14}$ | $2^{-10}$ | +| `highp` | $(-2^{62},2^{62})$ | $2^{-62}$ | $2^{-16}$ | + +一般我们会使用 `mediump` 或 `highp`。 + +定义精度时使用固定语法 `precision highp float;` 分号不能少,示例如下: + +```OpenGL Shading Language +#version 300 es +precision highp float; +``` + +## 基本语法 + +`GLSL` 语法与 `C` 语言类似。需要注意的点如下: + +1. 每一条语句后面都必须添加分号。 +2. 变量等必须声明类型。 + +### 整数与浮点数 + +定义整数直接写数字,例如 `1` `2`。 + +定义浮点数必须包含小数点,例如 `1.0` `2.` `.3`,`2.` 就是 `2.0`,`.3` 就是 `0.3`。一般我们不会使用后两种写法,只会使用第一种写法,因为它更直观。 + +浮点数使用 `float` 定义,整数使用 `int` 定义。示例在后面给出。 + +注意,在着色器中,我们很少使用整数,多数情况下使用浮点数,这是因为显卡计算浮点数更快。除了循环、枚举等场景,一般都使用浮点数作为变量。 + +### 定义变量 + +定义变量时使用 `类型+变量名` 的格式: + +```OpenGL Shading Language +float color; // 仅声明 +float color = 1.0; // 声明并赋值初始值 +int i = 0; // 定义整数 +``` + +### 布尔值 + +布尔值使用 `bool` 定义: + +```OpenGL Shading Language +bool isXxx = false; +bool greater = 1.0 > 0.5; +``` + +### 定义函数 + +定义函数使用 `返回值类型+函数名+参数` 的形式。例如: + +```OpenGL Shading Language +void func1(); // 声明一个没有参数没有返回值的函数 +void func2(float num, int i); // 有两个参数,没有返回值的函数 +float func3(); // 有返回值,没有参数的函数 +int func4(float num, int i); // 有返回值,有两个参数的函数 +``` + +### 函数实现 + +直接在函数声明后面跟上花括号即可实现函数定义: + +```OpenGL Shading Language +float func1() { + return 1.0; // 返回浮点数 +} + +float func2(float num1, float num2) { + return num1 * num2; // 返回两个参数的乘积 +} +``` + +### 函数调用 + +与 `js` 类似,使用圆括号调用: + +```OpenGL Shading Language +float num = func2(1.0, 2.0); +``` + +函数必须先声明再调用,例如下面这样会引起报错: + +```OpenGL Shading Language +float num = func2(1.0, 2.0); + +float func2(float num1, float num2) { + return num1 * num2; // 返回两个参数的乘积 +} +``` + +我们可以在前面提前写一个声明而不实现: + +```OpenGL Shading Language +float func2(float num1, float num2); // 提前写一个声明 + +float num = func2(1.0, 2.0); + +float func2(float num1, float num2) { + return num1 * num2; // 返回两个参数的乘积 +} +``` + +或者干脆把实现提到前面: + +```OpenGL Shading Language +float func2(float num1, float num2) { + return num1 * num2; // 返回两个参数的乘积 +} + +float num = func2(1.0, 2.0); +``` + +### 强制类型转换 + +浮点数与整数相乘结果会是浮点数,如果我们需要获取整数,就需要强制类型转换。强制类型转换使用 `(类型)值` 的形式,例如: + +```OpenGL Shading Language +int num = (int)(3.0 * 2.0); // 强制转换结果为整数,这会向下取整,可能需要注意浮点误差 +float n = (float)num; // 强制转换为浮点数 +``` + +### 输入变量 + +片段着色器与顶点着色器都有输入变量,直接使用 `in` 关键字定义即可,注意不能赋初始值,因为它是由外部传入的,并非着色器代码本身的变量。 + +定义顶点着色器的输入变量时,一般使用 `a_变量名` 的格式,定义片段着色器的输入变量时,一般使用 `v_变量名` 的格式。原因在之后可能会讲到。 + +示例如下,注意不要忘记分号: + +```OpenGL Shading Language +in float a_vertexFloat; // 顶点着色器输入变量 +in float v_fragFloat; // 片段着色器的输入变量 +``` + +### 输出变量 + +片段着色器与顶点着色器都有输出变量,使用 `out` 关键字定义,可以赋初始值,因为它是着色器内部定义的,输出到外部。 + +定义顶点着色器的输出变量时,一般使用 `v_变量名` 的格式,定义片段着色器的输出变量时,没有命名格式要求,但一般以 `out` 开头。 + +示例如下: + +```OpenGL Shading Language +out float v_vertexOut; // 顶点着色器输出变量 +out vec4 outColor; // 片段着色器输出变量 +``` + +### 向量数据类型 + +向量数据类型包括 `vec2` `vec3` `vec4`,它们分别描述了二维、三维、四维向量,分别包含两个、三个、四个浮点数。示例如下: + +```OpenGL Shading Language +vec2 v1 = vec2(1.0, 0.2); // 二维向量 +vec3 v2 = vec3(1.0, 0.3, 0.8); // 三维向量 +vec4 v3 = vec4(1.0, 2.0, 3.3, 1.1); // 四维向量 +``` + +还可以使用向量声明向量,比如在三维向量的基础上加一位变成四维向量: + +```OpenGL Shading Language +vec3 v1 = vec3(1.0, 2.2, 0.5); +vec4 v2 = vec4(v1, 1.0); // 在后面添加一个 1.0 +vec4 v3 = vec4(1.0. v1); // 在前面添加一个 1.0 +``` + +这类似于 `js` 中的扩散语法。但是注意最大只有四维向量,没有五维或更高的向量。 + +我们可以通过 `.rgba` 或 `.xyzw` 获取向量的第一、二、三、四个数值。 + +例如获取 `vec4` 的第三项,就有两种写法: + +```OpenGL Shading Language +vec4 v = vec4(1.0, 2.0, 3.3, 1.1); // 四维向量 +float f1 = v.b; // 获取第三项 +float f2 = v.z; // 获取第三项 +``` + +`.rgba` 和 `.xyzw` 可以自由组合,顺序也可以颠倒,程序会根据其顺序依次取出并组成一个新的向量。但是两个获取方式是不能混用的。示例如下: + +```OpenGL Shading Language +vec4 v = vec4(1.0, 2.0, 3.0, 4.0); +vec2 v1 = v.ra; // 获取第一项和最后一项,结果为 vec2(1.0, 4.0) +vec3 v2 = v.zyx; // 倒序获取前三项,结果为 vec3(3.0, 2.0, 1.0) +``` + +### 顶点输出 + +这里的顶点输出是指顶点着色器输出的顶点坐标,并非 `out` 变量,注意区分。 + +我们计算出顶点位置后,需要让 `WebGL2` 知道位置是什么,此时我们需要将运算结果赋值给 `gl_Position` 内置变量。例如: + +```OpenGL Shading Language +vec4 pos = vec4(0.0, 1.0, 0.5, 1.0); +gl_Position = pos; // 将顶点输出赋值给 gl_Position +``` + +### 片段输出 + +这里的片段输出是指片段着色器输出的颜色。 + +我们直接将颜色赋值给使用 `out` 定义的变量即可: + +```OpenGL Shading Language +out vec4 outColor; +outColor = vec4(0.0, 0.0, 0.0, 1.0); // 赋值给 out 变量 +``` + +### 主程序 + +顶点着色器和片段着色器都有一个主程序,它是 `main` 函数,显卡会从这里开始执行着色器,他就是着色器的入口。因此 `main` 函数是必不可少的。示例如下: + +```OpenGL Shading Language +void main() { + gl_Position = pos; // 顶点着色器输出顶点 +} +``` + +### 其他语法 + +其他语法包括基本数学运算、逻辑运算、循环、条件判断等基本与 `js` 语法一致,这里不再细讲,后面直接给出一个示例。 + +需要注意的是 `glsl` 的数学运算符很少,只包含加减乘除等,不包含取余、位运算等运算符。 + +```OpenGL Shading Language +float num = (1.0 + 2.0) * 3.0 / 4.0; +bool logic = (false && true) || false; +float n = 1.0 > 2.0 ? 1.0 : 2.0; + +if (logic && 2.0 > 1.0) { +} + +while (logic) { + break; +} + +for (int i = 0; i < 10; i++) { +} +``` + +# 6.7.3 编写着色器 + +讲解完着色器的语法后,我们就可以开始编写着色器了。 + +## 顶点着色器 + +首先来看顶点着色器。 + +顶点着色器的目标是确定顶点。我们画三角形时会传入三角形的顶点,因此直接将传入的顶点作为输出即可。 + +我们需要先定义一个输入变量 `a_position`,它就是三角形的顶点坐标,然后直接赋值给 `gl_Position`。代码如下: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec4 a_position; + +void main() { + gl_Position = a_position; +} +``` + +## 片段着色器 + +我们需要将三角形填充成白色,因此直接将输出颜色设为白色即可: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +out vec4 outColor; + +void main() { + outColor = vec4(1.0, 1.0, 1.0, 1.0); // 分别代表 rgba +} +``` + +# 6.7.4 编译着色器与链接程序 + +我们编写完了着色器,接下来我们就需要编译并链接程序了。 + +## 编译着色器 + +编译某个着色器使用如下代码: + +```TypeScript +const shader = gl.createShader(gl.VERTEX_SHADER); +gl.shaderSource(shader, vs); +gl.compileShader(shader); +``` + +有时候着色器代码有问题,会编译失败,这时候 `WebGL2` 并不会报错,而是会继续往下执行。我们需要判断是否编译完成,使用这段代码: + +```TypeScript +if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) { + const info = gl.getShaderInfoLog(shader); + throw new Error(`无法编译着色器。\n\n${info}`); +} +``` + +我们有顶点着色器和片段着色器两个着色器,因此需要写两遍,为了不这么麻烦,我们可以把上述过程封装成一个函数: + +```TypeScript +/** + * 编译着色器 + * @param type 着色器类型 + * @param source 着色器代码 + */ +function compileShader(type: GLenum, source: string): WebGLShader { + const shader = gl.createShader(type); + gl.shaderSource(shader, source); + gl.compileShader(shader); + + // 如果编译失败 + if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) { + const info = gl.getShaderInfoLog(shader); + throw new Error(`无法编译着色器。\n\n${info}`); + } + + return shader; +} +``` + +于是我们直接调用就可以了: + +```TypeScript +const vsShader = compileShader(gl.VERTEX_SHADER, vs); +const fsShader = compileShader(gl.FRAGMENT_SHADER, fs); +``` + +## 链接程序 + +根据上一节课讲过的过程创建并链接程序即可: + +```TypeScript +const program = gl.createProgram(); +gl.attachShader(program, vsShader); +gl.attachShader(program, fsShader); +gl.linkProgram(program); +``` + +链接程序后,我们还需要判断程序是否链接成功,就像判断着色器是否编译成功一样,使用如下代码: + +```TypeScript +if (!gl.getProgramParameter(program, gl.LINK_STATUS)) { + const info = gl.getProgramInfoLog(program); + throw new Error(`无法编译 WebGL 程序。\n\n${info}`); +} +``` + +# 6.7.5 顶点数组 + +我们需要使用顶点数组指定三角形画到哪。 + +## 定义顶点数组 + +我们以 $(-0.5,-0.5)$ $(0.5,-0.5)$ $(0,0.5)$ 三个点组成三角形。定义顶点数组: + +```TypeScript +const vertex = new Float32Array([-0.5, -0.5, 0.5, -0.5, 0, 0.5]); +``` + +绑定并赋值到缓冲区: + +```TypeScript +const buffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, buffer); +gl.bufferData(gl.ARRAY_BUFFER, vertex, gl.STATIC_DRAW); +``` + +## 获取输入变量位置 + +我们需要将上述顶点数组传递给着色器的 `a_position` 输入变量。我们需要先通过 `gl.getAttribLocation` 方法来获取输入变量的位置: + +```TypeScript +function getAttribLocation(program: WebGLProgram, attrib: string): number; +``` + +第一个参数代表要获取哪个程序的输入变量,第二个参数代表输入变量的名称,会返回一个数字,代表输入变量的位置。示例如下: + +```TypeScript +const location = gl.getAttribLocation(program, 'a_position'); +``` + +## 传递顶点数组 + +接下来我们需要使用 `gl.vertexAttribPointer` 来传递顶点数组。它的类型声明如下: + +```TypeScript +function vertexAttribPointer( + index: number, + size: number, + type: GLenum, + normalized: boolean, + stride: number, + offset: number +): void; +``` + +它的功能是将当前绑定在 `gl.ARRAY_BUFFER` 缓冲区的内容传递给指定位置的顶点输入变量。我们刚刚将顶点数组绑定至了 `gl.ARRAY_BUFFER` 缓冲区,那么我们需要将刚刚获取的输入变量位置传入,这样顶点数组就会传递给顶点变量了。 + +它的每个参数解释如下: + +- `index`:顶点输入变量的位置,即刚刚用 `getAttribLocation` 获取到的值。 +- `size`:每个数据的大小,填 1 代表浮点数,填 2 代表二维向量,以此类推。 +- `type`:数据类型,可以填 `gl.BYTE` `gl.SHORT` `gl.FLOAT` 等,分别代表八位整数、十六位整数、三十二位浮点数等。 +- `normalized`:是否对数据归一化,对整数类型有效,浮点数无效。对于有符号整数,会归一化至 `[-1,1]` 的区间,对于无符号整数,会归一化至 `[0,1]` 的区间。 +- `stride`:连续的两个顶点属性的间距,以字节为单位。以浮点数来说,如果此值是 16,`size` 是 3,那么会依次读取 `0,1,2,4,5,6,8,9,10` 索引的数据。此参数最大值是 255。如果填 0,那么相当于 `size*byte`,即填 0 的时候每个数据之间是挨着的。 +- `offset`:数据从哪个字节开始读取,注意是字节偏移量,而非索引偏移量。 + +图示如下: + + + +那么在我们现在的场景下,应该如下填写参数: + +```TypeScript +gl.vertexAttribPointer( + location, // 传入刚刚获取的输入变量位置 + 2, // 每个点两个坐标,因此传入 2 + gl.FLOAT, // 每个坐标都是浮点数 + false, // 浮点数不需要归一化 + 0, // 顶点属性间连续,因此填 0 + 0 // 不需要偏移 +); +``` + +这里也解释了上一节课中的疑问,`WebGL2` 如何知道顶点数组是几个一组的呢?答案是在传入顶点数组的时候指定,而不是定义顶点数组的时候指定,这样的话顶点数组就可以复用了。 + +## 启用顶点数组 + +最后,我们需要使用 `gl.enableVertexAttribArray` 来启用刚刚传入的顶点数组: + +```TypeScript +function enableVertexAttribArray(index: number): void; +``` + +参数就是输入变量的位置,我们直接传入即可: + +```TypeScript +gl.enableVertexAttribArray(location); +``` + +# 6.7.6 使用着色器程序 + +我们需要使用 `gl.useProgram` 告诉 `WebGL2` 要使用什么着色器程序渲染。其类型声明如下: + +```TypeScript +function useProgram(program: WebGLProgram): void; +``` + +我们刚刚创建并设定完毕了需要使用的程序,直接传入即可: + +```TypeScript +gl.useProgram(program); +``` + +# 6.7.7 执行渲染 + +我们总算是来到了最后一步,终于可以开始渲染内容了! + +## 设定视口 + +我们首先按照上一节课的内容设定视口: + +```TypeScript +gl.viewport(0, 0, canvas.width, canvas.height); +``` + +## 清空画布 + +接下来按照上一节课的内容清空画布: + +```TypeScript +gl.clearColor(0, 0, 0, 1); +gl.clearDepth(1); +gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); +``` + +## 执行渲染 + +最后,我们调用 `gl.drawArrays`,它的类型声明如下: + +```TypeScript +function drawArrays(mode: GLenum, first: number, count: number): void; +``` + +其中第一个参数表示线的连接方式,就是上一节课中讲到的 `gl.TRIANGLES` `gl.TRIANGLE_STRIP` `gl.TRIANGLE_FANS`。 + +第二个参数是指从哪个点开始渲染,第三个参数代表要渲染多少个点。 + +我们的场景中只有一个三角形,因此三种连接方式都没有区别,我们选用 `gl.TRIANGLES`。三个顶点需要全部花完,因此 `first` 和 `count` 分别传入 0 和 3。 + +最后代码如下: + +```TypeScript +gl.drawArrays(gl.TRIANGLES, 0, 3); +``` + +# 6.7.8 渲染流程解释 + +## 执行顶点着色器 + +当我们执行了 `drawArrays` 后,`WebGL2` 会检查所有启用的顶点数组,并将它们按照指定的方式组成浮点数或向量,逐个传入顶点着色器的输入变量,并执行顶点着色器的主程序。 + +对于我们的顶点数组 `[-0.5, -0.5, 0.5, -0.5, 0, 0.5]`,会被分割为三个 `vec2`,即 `vec2(-0.5, -0.5)` `vec2(0.5, -0.5)` `vec2(0, 0.5)`,于是着色器中的输入变量 `a_position` 就会依次被赋值为它,并执行主程序。我们将 `a_position` 直接赋值给了 `gl_Position`,因此最后三角形的顶点也就是这三个坐标。 + +我们定义的 `a_position` 是 `vec4`,但是传入了 `vec2`,此时 `a_position` 将会是 `vec4(vec2, 0, 1)`,即 `z w` 坐标分别被填充为 0 和 1。 + +## 光栅化 + +当确定了顶点之后,`WebGL2` 会遍历顶点构成区域内的所有像素。由于顶点等坐标都是浮点数,需要对应到屏幕像素,因此需要分割成一个个的像素,这一行为被称为光栅化。 + +## 执行片段着色器 + +最后确定了所有要渲染的像素后,会对每个像素执行片段着色器,将其输出的颜色推送到颜色缓冲区,并在屏幕上显示。 + +# 6.7.9 完整代码 + +```TypeScript +// 创建画布 +const canvas = document.querySelector("#webgl"); +const gl = canvas.getContext("webgl2")!; + +//设置画布宽高 +canvas.width = 300 * devicePixelRatio; +canvas.height = 300 * devicePixelRatio; + +// 顶点着色器 +const vs = /* glsl */ `#version 300 es +precision highp float; + +in vec4 a_position; + +void main() { + gl_Position = a_position; +} +`; + +// 片段着色器 +const fs = /*glsl */ `#version 300 es +precision highp float; + +out vec4 outColor; + +void main() { + outColor = vec4(1.0, 1.0, 1.0, 1.0); +} +`; + +// 编译着色器 +const vsShader = compileShader(gl.VERTEX_SHADER, vs) +const fsShader = compileShader(gl.FRAGMENT_SHADER, fs); + +// 创建程序并编译链接 +const program = gl.createProgram(); +gl.attachShader(program, vsShader); +gl.attachShader(program, fsShader); +gl.linkProgram(program); + +// 如果程序链接失败 +if (!gl.getProgramParameter(program, gl.LINK_STATUS)) { + const info = gl.getProgramInfoLog(program); + throw new Error(`无法编译 WebGL 程序。\n\n${info}`); +} + +// 定义顶点数组,并赋值给缓冲区 +const vertex = new Float32Array([-0.5, -0.5, 0.5, -0.5, 0, 0.5]); +const buffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, buffer); +gl.bufferData(gl.ARRAY_BUFFER, vertex, gl.STATIC_DRAW); + +// 获取顶点属性地址 +const attrib = gl.getAttribLocation(program, "a_position"); +// 指定顶点数组并启用 +gl.vertexAttribPointer(attrib, 2, gl.FLOAT, false, 0, 0); +gl.enableVertexAttribArray(attrib); + +// 使用着色器程序 +gl.useProgram(program); + +// 设置视口并清空画布 +gl.viewport(0, 0, canvas.width, canvas.height); +gl.clearColor(0, 0, 0, 1); +gl.clearDepth(1); +gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); + +// 执行渲染 +gl.drawArrays(gl.TRIANGLES, 0, 3); + +/** + * 编译着色器 + * @param type 着色器类型 + * @param source 着色器代码 + */ +function compileShader(type: GLenum, source: string): WebGLShader { + const shader = gl.createShader(type); + gl.shaderSource(shader, source); + gl.compileShader(shader); + + // 如果编译失败 + if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) { + const info = gl.getShaderInfoLog(shader); + throw new Error(`无法编译着色器。\n\n${info}`); + } + + return shader; +} +``` \ No newline at end of file diff --git a/.planning/references/feishu-teaching-docs/06.md b/.planning/references/feishu-teaching-docs/06.md new file mode 100644 index 0000000..738e099 --- /dev/null +++ b/.planning/references/feishu-teaching-docs/06.md @@ -0,0 +1,174 @@ +6.8 颜色渐变与插值 + +本节课将会教你如何实现颜色渐变,并解释渐变的底层逻辑——插值。本节课实现效果如图所示: + +![](https://feishu.cn/file/TvK4bJm9poWrM3xhqYWcNEFVn2i) + +代码链接:https://codepen.io/unanmed/pen/jEWELKQ + +# 6.8.1 顶点输出变量与片段输入变量 + +我们之前讲过顶点输出变量和片段输入变量的概念,但是没有提到其用法,以及其运行方式。我们先来讲解其编写方式。 + +我们以颜色为例,展示输出变量及输入变量在颜色上的表现。 + +我们需要先在顶点着色器中编写一个 `out` 变量: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec4 a_position; +out vec4 v_color; +``` + +然后在片段着色器中编写一个同名的 `in` 变量: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec4 v_color; +out vec4 outColor; +``` + +最后,在顶点着色器给输出变量赋值: + +```OpenGL Shading Language +void main() { + v_color = vec4(1.0, 1.0, 1.0, 1.0); + gl_Position = a_position; +} +``` + +# 6.8.2 设定颜色 + +我们当然会有一个疑问,顶点着色器只会对顶点执行,片段着色器只会对像素执行,这个过程中二者行为没有重合,甚至执行次数都不一样,根本没办法一一对应,那么片段着色器是如何处理输入变量的?这个问题我们暂且不解释,先做出来效果看看。 + +我们需要为每个顶点设定一个颜色,因此可以考虑使用传入顶点坐标的方式,使用相同的方式传入顶点颜色。 + +## 顶点着色器 + +首先修改顶点着色器,新增一个输入变量,接收顶点颜色: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec4 a_position; +in vec4 a_color; +``` + +然后我们新增一个顶点输出,叫做 `v_color`: + +```OpenGL Shading Language +out vec4 v_color; +``` + +在主程序里面直接将 `v_color` 赋值为 `a_color`: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec4 a_position; +in vec4 a_color; +out vec4 v_color; // 顶点输出变量 + +void main() { + v_color = a_color; + gl_Position = a_position; +} +``` + +## 片段着色器 + +我们在片段着色器接收顶点着色器中的顶点输出变量,然后将它作为输出颜色: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec4 v_color; // 片段输入变量,与顶点输出变量同名 +out vec4 outColor; // 输出颜色 + +void main() { + outColor = v_color; +} +``` + +## 传入顶点输入 + +与传入顶点坐标类似,我们再执行一遍创建缓冲区->缓冲区赋值->传递顶点变量的流程即可,完整代码如下: + +```TypeScript +// 定义顶点数组和颜色数组 +const vertex = new Float32Array([-0.5, -0.5, 0.5, -0.5, 0, 0.5]); +const colorArray = new Float32Array([1, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1, 1]); + +// 顶点赋值给缓冲区 +const positionBuffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, positionBuffer); +gl.bufferData(gl.ARRAY_BUFFER, vertex, gl.STATIC_DRAW); + +// 传递并启用顶点数组 +const position = gl.getAttribLocation(program, 'a_position'); +gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0); +gl.enableVertexAttribArray(position); + +// 颜色赋值给缓冲区 +const colorBuffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, colorBuffer); +gl.bufferData(gl.ARRAY_BUFFER, colorArray, gl.STATIC_DRAW); + +// 传递并启用颜色数组 +const color = gl.getAttribLocation(program, 'a_color'); +gl.vertexAttribPointer(color, 4, gl.FLOAT, false, 0, 0); +gl.enableVertexAttribArray(color); +``` + +这里三个顶点分别被设为了红色 `rgba(1,0,0,1)` 绿色 `rgba(0,1,0,1)` 和蓝色 `rgba(0,0,1,1)`。 + +# 6.8.3 代码效果 + +我们将代码修改完毕后,就得到了如下效果: + +![](https://feishu.cn/file/MzuKbt7tko7vbPx2ScEcRJGonXf) + +非常 Amazing 啊,我们得到了一个渐变颜色的三角形。观察后可以发现,每个顶点确实符合我们设置的颜色,而顶点中间则产生了颜色渐变。 + +产生渐变的根本原因是插值,我们马上开始讲解。 + +# 6.8.4 插值 + +当顶点着色器的输出变量输出至片段着色器时,变量会经过插值操作。 + +## 线性插值 + +对于两个点 $(x_1,y_1)$$(x_2,y_2)$,我们需要知道这两个点之间的点 $x_3$ 对应的值,我们可以使用两点式直线方程创建一条直线:$\frac{x-x_1}{x_2-x_1}=\frac{y-y_1}{y_2-y_1}$,这时将 $x_3$ 带入,就可以求出 $y_3$ 的值,这一操作就叫做线性插值。 + +如果使用代码编写线性插值,可以先求出斜率,然后计算: + +```TypeScript +// 两个点 +const x1 = 10; +const y1 = 20; +const x2 = 30; +const y2 = 40; +const x3 = 15; // 要计算的点 + +const k = (y2 - y1) / (x2 - x1); // 求斜率 +const y3 = k * (x3 - x1) + y1; // 求出点的纵坐标,斜率乘以横坐标差值加上纵坐标 +``` + +## 着色器的插值 + +在着色器上,已知的点就是每个顶点,它的值由顶点输出变量确定。例如对于本节课的三角形,每个点对应的值就是 `vec4(1,0,0,1)` `vec4(0,1,0,1)` `vec4(0,0,1,1)`。 + +当顶点数据输出到片段着色器时,显卡就会自动对这些值进行线性插值操作,从而得到每个像素的值,也就产生了颜色变化。 + +着色器的插值是二维的插值,运作机理相对来说会比较复杂,我们一般不需要知道具体的插值方式,只需要知道大致是如何插值的,并了解插值相关的接口,我们这里也不再讲解其运行机理。 + +# 6.8.5 总结 + +本节课讲解了颜色渐变和插值的概念。从下节课开始,我们将会步入三维渲染,讲解三维渲染中的一些基本概念。 \ No newline at end of file diff --git a/.planning/references/feishu-teaching-docs/07.md b/.planning/references/feishu-teaching-docs/07.md new file mode 100644 index 0000000..8a9a0a8 --- /dev/null +++ b/.planning/references/feishu-teaching-docs/07.md @@ -0,0 +1,343 @@ +6.9 uniform 变量 + +本节课讲解 `uniform` 变量,它在 `WebGL2` 中相当重要。本节课实现效果如图所示: + +![](https://feishu.cn/file/D26ebvCtXo15o6x7arkcZjrPnPg) + +代码链接:https://codepen.io/unanmed/pen/GgomeEL + +# 6.9.1 `uniform` 概念 + +`uniform` 变量可以控制着色器渲染,它可以被外部赋值,可以用于顶点着色器和片段着色器,且其值在两个着色器及整个渲染流程中保持一致,因此也称为一致变量。这种变量在着色器中是只读的,不能在着色器内被修改,只能在外部修改。 + +我们只需要在全局变量声明之前添加一个 `uniform` 关键字,即可将它标记为 `uniform` 变量。注意 `uniform` 变量只能是 `float` `vec2` `vec3` `vec4` `int` 等类型中的一种,不可以是布尔值等类型。 + +```OpenGL Shading Language +#version 300 es +precision highp float; + +// uniform 变量命名一般以 u_ 开头 +uniform float u_var; +``` + +# 6.9.2 操作 `uniform` 变量 + +我们可以在着色器外部操作 `uniform` 变量,其流程与顶点数组类似。 + +## 获取变量位置 + +首先使用 `getUniformLocation` 获取变量位置: + +```TypeScript +function getUniformLocation(program: WebGLProgram, uniform: string): WebGLUniformLocation; +``` + +对于上述例子中的 `u_var`,我们可以这么获取: + +```TypeScript +// program 为编译链接好的程序 +const location = gl.getUniformLocation(program, 'u_var'); +``` + +## 给变量赋值 + +给 `uniform` 变量赋值非常复杂,不同的数据类型要用不同的方法,而且每种数据类型基本都有不止一种方法,我们很难用简洁的语言描述清楚。因此我们从方法名的命名讲起。 + +一个标准的给 `uniform` 赋值的方法名为 `uniform3fv`,我们拆开来看: + + + +- 这里 `uniform` 为固定内容,所有的赋值方法都以它起头。 +- 后面跟上一个数字,表明赋值的数据长度,它可以是 `1` `2` `3` `4`,分别对应浮点数或整数、二维向量、三维向量、四维向量。 +- 后面的一个或两个字符表明数据类型,填写 `i` 表示有符号整数(`int`),填写 `ui` 表示无符号整数(`unsigned int`),填写 `f` 表示浮点数(`float`) +- 最后一个可以填写 `v`,表示向量模式(`vector`),也可以不填。 + +向量模式只影响传递的参数,不影响赋值结果。 + +### 非向量模式 + +在非向量模式下,我们需要传入对应数量的数值,例如 `uniform3f` 就要传递三个参数,`uniform4i` 就要传递四个参数,以此类推。示例如下: + +```TypeScript +// location 是变量位置 +gl.uniform1f(location, 1); +gl.uniform3f(location, 1, 2, 3); +gl.uniform2ui(location, 2, 2); +gl.uniform4i(location, 1, 2, 3, 4); +``` + +### 向量模式 + +向量模式下,参数如下所示: + +```TypeScript +function uniform[1234][uif][v]( + location: WebGLUniformLocation, + data: TypedArray, + srcOffset?: number, + srcLength?: number +): void; +``` + +这与 `bufferData` 方法基本一致,每个参数的含义也大致相同。 + +- `location`:表示要操作的变量位置。 +- `data`:传递给变量的类型化数组。 +- `srcOffset`:从类型化数组的哪个索引开始读取。注意是索引,而非字节长度。 +- `srcLength`:从类型化数组读取多长的数据。注意是索引,而非字节长度。 + +示例如下: + +```TypeScript +gl.uniform3fv(location, new Float32Array([1, 2, 3])); +gl.uniform4uiv(location, new Uint32Array([2, 4, 6, 8])); +gl.uniform2fv(location, new Float32Array([1, 2, 3, 4]), 1, 2); // 指定偏移和长度 +``` + +如果不想使用 `uniform` 方法的 `srcOffset` 和 `srcLength`,我们还可以通过创建一个新的类型化数组实现: + +```TypeScript +const arr = new Float32Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 0]); +// 直接从 ArrayBuffer 创建,基本不消耗性能 +gl.uniform3fv(location, new Float32Array(arr.buffer, 0, 12)); +``` + +如果我们有很多 `uniform`,使用向量模式和类型化数组可以大幅提高运行速度。 + +# 6.9.3 动画效果 + +既然 `uniform` 变量可以在外部操作,那么如果我们每帧修改一次变量,并重绘,就可以实现动画效果了。下面我们以让上节课的三角形转起来为例,展示如何制作一个动画效果。 + +## 顶点着色器 + +让三角形转起来实际上是在操作顶点,因此我们只需要修改顶点着色器即可,不需要修改片段着色器。首先我们当然要先定义一个 `uniform` 变量: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +uniform float u_rad; +``` + +接下来我们需要创建一个二维旋转矩阵,使用 `mat2` 数据类型,此数据类型我们将在下节课详细讲解,这里我们只需要知道它是一个 `2x2` 方阵即可。旋转矩阵不包含平移分量,因此只需要 `2x2`,不需要第三维。我们需要计算三角函数,在 `glsl` 里面,我们直接使用 `sin` `cos` 函数即可。代码如下: + +```OpenGL Shading Language +mat2 rot = mat2( + cos(u_rad), -sin(u_rad), + sin(u_rad), cos(u_rad) +); +``` + +然后让矩阵乘以坐标,算出来旋转后的坐标: + +```OpenGL Shading Language +vec2 pos = a_position.xy; +pos = rot * pos; +``` + +最后把坐标赋值给 `gl_Position`: + +```OpenGL Shading Language +gl_Position = vec4(pos, 0.0, 1.0); +``` + +这样,最终的顶点坐标就是经过了旋转操作的坐标,我们只需要修改 `u_rad`,就可以控制三角形的旋转。 + +## 每帧重绘 + +接下来,我们只需要每帧修改 `uniform` 变量并重绘即可。首先我们需要获取 `uniform` 的位置: + +```TypeScript +const rad = gl.getUniformLocation(program, 'u_rad'); +``` + +然后我们开一个 `raf`: + +```TypeScript +const drawScene = () => { + requestAnimationFrame(drawScene); +} +requestAnimationFrame(drawScene); +``` + +在 `raf` 里面,我们修改 `u_rad` 的值,让它每帧增加 3 度: + +```TypeScript +let nowAngle = 0; +const drawScene = () => { + // 每帧增加 3 度 + nowAngle += Math.PI / 60; + if (nowAngle > Math.PI) { + nowAngle -= Math.PI * 2; + } + // 赋值操作 + gl.uniform1f(rad, nowAngle); + + requestAnimationFrame(drawScene); +} +requestAnimationFrame(drawScene); +``` + +最后每帧清空并重绘即可,注意不需要设置视口,也不需要编译链接程序,清空并重绘即可: + +```TypeScript +gl.clearColor(0, 0, 0, 1); +gl.clearDepth(1); +gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); + +// 执行渲染 +gl.drawArrays(gl.TRIANGLES, 0, 3); +``` + +这样,我们就做出了三角形旋转的效果。 + +# 6.9.4 完整代码 + +## 顶点着色器 + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec4 a_position; +in vec4 a_color; + +uniform float u_rad; + +out vec4 v_color; + +void main() { + vec2 pos = a_position.xy; + mat2 rot = mat2( + cos(u_rad), -sin(u_rad), + sin(u_rad), cos(u_rad) + ); + pos = rot * pos; + v_color = a_color; + gl_Position = vec4(pos, 0.0, 1.0); +} +``` + +## 片段着色器 + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec4 v_color; +out vec4 outColor; + +void main() { + outColor = v_color; +} +``` + +## TypeScript + +```TypeScript +// 创建画布 +const canvas = document.querySelector("#webgl"); +const gl = canvas.getContext("webgl2")!; + +//设置画布宽高 +canvas.width = 300 * devicePixelRatio; +canvas.height = 300 * devicePixelRatio; + +// 顶点着色器见上面的代码块 +const vs = /* glsl */ ` +`; + +// 片段着色器见上面的代码块 +const fs = /*glsl */ ` +`; + +// 编译着色器 +const vsShader = compileShader(gl.VERTEX_SHADER, vs) +const fsShader = compileShader(gl.FRAGMENT_SHADER, fs); + +// 创建程序并编译链接 +const program = gl.createProgram(); +gl.attachShader(program, vsShader); +gl.attachShader(program, fsShader); +gl.linkProgram(program); + +// 如果程序链接失败 +if (!gl.getProgramParameter(program, gl.LINK_STATUS)) { + const info = gl.getProgramInfoLog(program); + throw new Error(`无法编译 WebGL 程序。\n\n${info}`); +} + +// 定义顶点数组和颜色数组 +const vertex = new Float32Array([-0.5, -0.5, 0.5, -0.5, 0, 0.5]); +const colorArray = new Float32Array([1, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1, 1]); + +// 顶点赋值给缓冲区 +const positionBuffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, positionBuffer); +gl.bufferData(gl.ARRAY_BUFFER, vertex, gl.STATIC_DRAW); + +// 传递并启用顶点数组 +const position = gl.getAttribLocation(program, 'a_position'); +gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0); +gl.enableVertexAttribArray(position); + +// 颜色赋值给缓冲区 +const colorBuffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, colorBuffer); +gl.bufferData(gl.ARRAY_BUFFER, colorArray, gl.STATIC_DRAW); + +// 传递并启用颜色数组 +const color = gl.getAttribLocation(program, 'a_color'); +gl.vertexAttribPointer(color, 4, gl.FLOAT, false, 0, 0); +gl.enableVertexAttribArray(color); + +// uniform 变量地址 +const rad = gl.getUniformLocation(program, 'u_rad'); + +// 使用着色器程序 +gl.useProgram(program); + +// 设置视口 +gl.viewport(0, 0, canvas.width, canvas.height); + +let nowAngle = 0; + +// 每帧重绘 +const drawScene = () => { + // 每帧使角度增加 3 度 + nowAngle += Math.PI / 60; + if (nowAngle > Math.PI) { + nowAngle -= Math.PI * 2; + } + gl.uniform1f(rad, nowAngle); + + gl.clearColor(0, 0, 0, 1); + gl.clearDepth(1); + gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); + + // 执行渲染 + gl.drawArrays(gl.TRIANGLES, 0, 3); + + requestAnimationFrame(drawScene); +} +requestAnimationFrame(drawScene); + +/** + * 编译着色器 + * @param type 着色器类型 + * @param source 着色器代码 + */ +function compileShader(type: GLenum, source: string): WebGLShader { + const shader = gl.createShader(type); + gl.shaderSource(shader, source); + gl.compileShader(shader); + + // 如果编译失败 + if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) { + const info = gl.getShaderInfoLog(shader); + throw new Error(`无法编译着色器。\n\n${info}`); + } + + return shader; +} +``` \ No newline at end of file diff --git a/.planning/references/feishu-teaching-docs/08.md b/.planning/references/feishu-teaching-docs/08.md new file mode 100644 index 0000000..bb0a992 --- /dev/null +++ b/.planning/references/feishu-teaching-docs/08.md @@ -0,0 +1,718 @@ +6.10 三维物体渲染 + +本节课主要讲解如何使用 `WebGL2` 渲染三维物体。本节课实现效果如图所示: + +![](https://feishu.cn/file/UStbb7VLBokYSixrCt7cxICUnBc) + +代码链接:https://codepen.io/unanmed/pen/wBMedxY + +# 6.10.1 `gl-matrix` 库的基本使用 + +进行三维渲染时我们需要 MVP 变换,我们一般使用 `gl-matrix` 库,人类塔中包含了这个库,如果你通过人类塔学习,可以直接使用。如果想要自己尝试,可以自己通过 `pnpm create vite` 创建一个 `vite` 项目,并 `pnpm add gl-matrix` 安装后尝试。 + +或者使用 `CodePen` 网站,可以直接引入,上面的代码链接就使用了 `CodePen`。 + +`gl-matrix` 包含二维、三维变换矩阵,我们着重讲解三维变换矩阵。 + +## 创建矩阵 + +首先需要使用 `mat4.create` 创建矩阵: + +```TypeScript +function create(): mat4; +``` + +它会创建一个单位矩阵,返回值 `mat4` 是一个 `Float32Array`,官方文档全部使用了 `mat4` 作为类型,这里我们也使用它。我们画三维物体需要四个矩阵,一个用于存储最终计算结果,另外三个分别是 mvp 矩阵。示例如下: + +```TypeScript +import { mat4 } from 'gl-matrix'; + +const trans = mat4.create(); +const model = mat4.create(); +const view = mat4.create(); +const proj = mat4.create(); +``` + +## 操作矩阵的基本模式 + +`gl-matrix` 操作矩阵时,都会要求传入一个输出目标,运算结果将会存储到传入的矩阵中,与传统的接口设计并不相同。举例来说,将一个矩阵设为单位矩阵的方法如下: + +```TypeScript +function identity(out: mat4): mat4; +``` + +这里的 `out` 就是要设为单位矩阵的矩阵,返回值就是传入的 `out`。例如我们需要每帧将 `trans` 设为单位矩阵,可以这么写: + +```TypeScript +mat4.identity(trans); +``` + +## 矩阵相乘 + +使用 `multiply` 做乘法: + +```TypeScript +function multiply(out: mat4, a: mat4, b: mat4): mat4; +``` + +这里的 `out` 是运算结果,`a` 是乘号左侧的矩阵(左操作数),`b` 是右操作数。 + +例如: + +```TypeScript +// 先模型变换,再视角变换,最后投影变换 +mat4.multiply(trans, trans, proj); +mat4.multiply(trans, trans, view); +mat4.multiply(trans, trans, model); +``` + +## 模型变换 + +### 基础用法 + +`gl-matrix` 有 `translate` `rotate` `scale` 方法用来执行模型变换,它们的类型声明如下: + +```TypeScript +function translate(out: mat4, a: mat4, v: vec3): mat4; +function rotate(out: mat4, a: mat4, rad: number, axis: vec3): mat4; +function rotateX(out: mat4, a: mat4, rad: number): mat4; +function rotateY(out: mat4, a: mat4, rad: number): mat4; +function rotateZ(out: mat4, a: mat4, rad: number): mat4; +function scale(out: mat4, a: mat4, v: vec3): mat4; +``` + +这里的 `out` 都代表输出矩阵,`a` 代表输入矩阵,即要进行操作的矩阵。 + +- 平移变换 `translate`:`v` 代表在 `x y z` 三个方向上的平移量。 +- 旋转变换 `rotate` `rotateX` `rotateY` `rotateZ`:第一个方法代表沿某个轴旋转 `rad` 弧度,其中旋转轴用一个三维向量描述,例如沿 `[1, 1, 1]` 轴旋转。后面三个方法代表沿 `x y z` 轴旋转 `rad` 弧度。 +- 缩放变换 `scale`:`v` 代表在 `x y z` 三个方向上的缩放量。 + +例如,我们想先缩放,再旋转,再平移,可以这么写: + +```TypeScript +mat4.translate(model, model, [1, 1, 1]); // 三个方向各平移一个单位 +mat4.rotate(model, model, Math.PI / 2, [1, 1, 1]); // 沿斜 45 度方向旋转 90 度 +mat4.scale(model, model, [1, 2, 1]); // 在 y 方向缩放为 2 倍 +``` + +### `from` 系列方法 + +除了这些方法,如果我们不需要非常复杂的组合变换,可以通过一系列 `from` 方法来实现,它的运算速度要比上述方法快得多。 + +通过平移、旋转、缩放创建使用这些接口: + +```TypeScript +function fromTranslation(out: mat4, v: vec3): mat4; +function fromRotation(out: mat4, rad: number, axis: vec3): mat4; +function fromXRotation(out: mat4, rad: number): mat4; +function fromYRotation(out: mat4, rad: number): mat4; +function fromZRotation(out: mat4, rad: number): mat4; +function fromScaling(out: mat4, v: vec3): mat4; +``` + +这些接口与前面讲的那些接口类似,只不过会重置矩阵并只进行一次变换操作。以 `fromTranslation` 为例,它与如下代码一致: + +```TypeScript +mat4.identity(model); +mat4.translate(model, v); +``` + +但是要更快,因此更推荐用这种方法。示例如下: + +```TypeScript +mat4.fromTranslation(model, [1, 1, 1]); // 将矩阵设为平移矩阵 +mat4.fromScaling(model, [1, 2, 1]); // 将矩阵设为缩放矩阵,前一步平移将不会生效 +``` + +## 四元数 + +我们可以用一个四元组描述旋转 `[qx, qy, qz, qw]`,其中 `qx, qy, qz` 表示旋转轴,`qw` 是旋转角度一半的余弦值,即 $\cos\frac{\theta}{2}$。 + +我们可以用 `quat.create` 创建: + +```TypeScript +function create(): quat; +``` + +旋转使用的方法与 `mat4` 类似,但没有 `rotate` 方法: + +```TypeScript +function rotateX(out: quat, a: quat, rad: number): quat; +function rotateY(out: quat, a: quat, rad: number): quat; +function rotateZ(out: quat, a: quat, rad: number): quat; +``` + +我们可以通过一个四元数直接生成 `mat4` 矩阵: + +```TypeScript +function fromQuat(out: mat4, q: quat): mat4; +``` + +例如: + +```TypeScript +import { mat4, quat } from 'gl-matrix'; +const model = mat4.create(); +const q = quat.create(); +quat.rotateX(q, q, Math.PI / 2); +mat4.fromQuat(model, q); +``` + +## 复杂模型变换 + +除了使用基本的 `from` 方法,还有一些用于复杂变换的 `from` 系列方法。这些方法仅说明一下它们相当于什么代码,不再提供例子。 + +第一个方法: + +```TypeScript +function fromRotationTranslation(out: mat4, q: quat, v: vec3): mat4; +``` + +它以指定四元数和平移生成矩阵,先旋转再平移,相当于: + +```TypeScript +mat4.identity(model); +mat4.translate(model, model, v); +const quatMat = mat4.create(); +mat4.fromQuat(quatMat, quat); +mat4.multiply(model, model, quatMat); +``` + +但是这个方法将这些方法整合成了一步,速度要快很多,而且写起来也更方便了。 + +第二个方法: + +```TypeScript +function fromRotationTranslationScale(out: mat4, q: quat, v: vec3, s: vec3): mat4; +``` + +先缩放,再旋转,最后平移,相当于: + +```TypeScript +mat4.identity(model); +mat4.translate(model, model, vec); +const quatMat = mat4.create(); +mat4.fromQuat(quatMat, quat); +mat4.multiply(model, model, quatMat); +mat4.scale(model, model, scale) +``` + +第三个方法: + +```TypeScript +function fromRotationTranslationScaleOrigin(out: mat4, q: quat, v: vec3, s: vec3, o: vec3): mat4; +``` + +先缩放,再旋转,最后平移,不过缩放与旋转不再相对于原点,而是相对于 `o` 参数指定的点。相当于: + +```TypeScript +mat4.identity(model); +mat4.translate(model, model, vec); +mat4.translate(model, model, origin); +const quatMat = mat4.create(); +mat4.fromQuat(quatMat, quat); +mat4.multiply(model, model, quatMat); +mat4.scale(model, model, scale); +mat4.translate(model, model, negativeOrigin); +``` + +## 视角变换 + +视角变换使用 `mat4.lookAt` 方法: + +```TypeScript +function lookAt(out: mat4, eye: vec3, center: vec3, up: vec3): mat4; +``` + +这里的 `eye` 表示摄像机的位置,`center` 表示看向的点,`up` 表示摄像机上朝向。 + +例如我们想要正面看向屏幕内,`up` 方向朝上,可以这么写: + +```TypeScript +mat4.lookAt(view, [0, 0, 1], [0, 0, 0], [0, 1, 0]); +``` + +## 投影变换 + +投影变换使用 `mat4.ortho` 和 `mat4.perspective`,前者是正交投影,后者是透视投影: + +```TypeScript +function ortho(out: mat4, left: number, right: number, bottom: number, top: number, near: number, far: number): mat4; +function perspective(out: mat4, fovy: number, aspect: number, near: number, far: number): mat4; +``` + +这些参数在 5.4 的课程中都已经讲解到了,这里不再讲解。示例如下: + +```TypeScript +mat4.ortho(proj, -1, 1, -1, 1, 0.1, 100); +mat4.perspective(proj, Math.PI / 4, 1, 0.1, 100); +``` + +# 6.10.2 着色器 + +我们需要画出一个旋转的正方体,而且六个面有不同的颜色。 + +## 矩阵类型 + +在编写着色器之前,我们需要了解一下 `GLSL` 的矩阵类型,它用来描述一个矩阵。矩阵类型包括:`mat2` `mat2x3` `mat2x4` `mat3` `mat3x4` `mat4`,分别代表 `2*2` `2*3` `2*4` `3*3` `3*4` `4*4` 大小的矩阵。前一个数字代表列数,后一个数字代表行数,例如 `mat2x3` 表示一个二列三行的矩阵。例如我们想创建一个 `2*2` 矩阵,就像上节课那样,可以这么写: + +```OpenGL Shading Language +mat2 mat = mat2( + 1, 0, + 0, 1 +); +``` + +这里换行是为了代码更清晰,实际上不换行也行,但是代码会变得难以阅读: + +```OpenGL Shading Language +mat2 mat = mat2(1, 0, 0, 1); +``` + +当然,矩阵还可以作为 `uniform` 变量: + +```OpenGL Shading Language +uniform mat4 u_transform; +``` + +## 顶点着色器 + +我们需要给顶点着色器添加变换矩阵,同时保留顶点位置与颜色的顶点输入,因此着色器内容为: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +// 位置与颜色信息 +in vec4 a_position; +in vec4 a_color; + +// 变换矩阵 +uniform mat4 u_transform; + +out vec4 v_color; + +void main() { + v_color = a_color; + gl_Position = u_transform * a_position; +} +``` + +## 片段着色器 + +片段着色器维持不变: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec4 v_color; +out vec4 outColor; + +void main() { + outColor = v_color; +} +``` + +# 6.10.3 顶点数组 + +## 定义正方体 + +我们需要定义正方体顶点数组。为了更加清晰,我们可以把顶点坐标与颜色写在一起,然后使用 `stride` 参数控制顶点数组的读取。 + +为了避免插值问题,让每个面的颜色是单一的,我们需要使用 `gl.TRIANGLES` 连接方式,因为其他的连接方式都与前面的点有关系,必然会产生插值。 + +除此之外还要注意剔除问题,逆向三角形会被剔除(顺时针三角形),这需要一定的空间想象力。一个面旋转到正面之后应该是正向三角形(逆时针三角形),因此在我们的视角下,背面的三角形应该是逆向的,只有这样旋转到正面之后才会变成顺向。其他面也是类似。 + +正方体一个面有四个顶点,需要两个三角形。四个顶点编号为 `1 2 3 4`,假设在正面时它们逆时针旋转,那么三角形的顶点依次是 `1 2 3 2 3 4`,即按顺序编写并重复中间两个顶点。 + +因此顶点数组编写如下,前三项代表坐标,后四项代表颜色: + +```TypeScript +const array = new Float32Array([ + 0.5, 0.5, 0.5, 1, 0, 0, 1, + -0.5, 0.5, 0.5, 1, 0, 0, 1, + 0.5, -0.5, 0.5, 1, 0, 0, 1, // 前面右上角三角形 + 0.5, -0.5, 0.5, 1, 0, 0, 1, + -0.5, 0.5, 0.5, 1, 0, 0, 1, + -0.5, -0.5, 0.5, 1, 0, 0, 1, // 前面左下角三角形 + + 0.5, 0.5, 0.5, 0, 1, 0, 1, + 0.5, 0.5, -0.5, 0, 1, 0, 1, + -0.5, 0.5, -0.5, 0, 1, 0, 1, // 上面右后方三角形 + -0.5, 0.5, -0.5, 0, 1, 0, 1, + -0.5, 0.5, 0.5, 0, 1, 0, 1, + 0.5, 0.5, 0.5, 0, 1, 0, 1, // 上面左前方三角形 + + -0.5, 0.5, 0.5, 0, 0, 1, 1, + -0.5, 0.5, -0.5, 0, 0, 1, 1, + -0.5, -0.5, 0.5, 0, 0, 1, 1, // 左面上前方三角形 + -0.5, -0.5, 0.5, 0, 0, 1, 1, + -0.5, 0.5, -0.5, 0, 0, 1, 1, + -0.5, -0.5, -0.5, 0, 0, 1, 1, // 左面下后方三角形 + + 0.5, 0.5, 0.5, 1, 1, 0, 1, + 0.5, -0.5, 0.5, 1, 1, 0, 1, + 0.5, 0.5, -0.5, 1, 1, 0, 1, // 右面上前方三角形 + 0.5, 0.5, -0.5, 1, 1, 0, 1, + 0.5, -0.5, 0.5, 1, 1, 0, 1, + 0.5, -0.5, -0.5, 1, 1, 0, 1, // 右面下后方三角形 + + 0.5, -0.5, -0.5, 1, 0, 1, 1, + 0.5, -0.5, 0.5, 1, 0, 1, 1, + -0.5, -0.5, -0.5, 1, 0, 1, 1, // 下面右后方三角形 + -0.5, -0.5, -0.5, 1, 0, 1, 1, + 0.5, -0.5, 0.5, 1, 0, 1, 1, + -0.5, -0.5, 0.5, 1, 0, 1, 1, // 下面左前方三角形 + + 0.5, 0.5, -0.5, 0, 1, 1, 1, + 0.5, -0.5, -0.5, 0, 1, 1, 1, + -0.5, 0.5, -0.5, 0, 1, 1, 1, // 后面右上方三角形 + -0.5, 0.5, -0.5, 0, 1, 1, 1, + 0.5, -0.5, -0.5, 0, 1, 1, 1, + -0.5, -0.5, -0.5, 0, 1, 1, 1, // 后面左下方三角形 +]); +``` + +## 传递顶点数组 + +这次我们只需要绑定一个缓冲区,然后使用 `stride` 和 `offset` 参数调整顶点数组的读取方式。 + +数据类型是 `Float32`,占用四字节,每组数据包含七个数据,因此 `stride` 应该填 `7*4`。 + +颜色从第四项开始读取,因此偏移量 `offset` 应该填写 `3*4`。 + +因此完整代码如下: + +```TypeScript +// 顶点赋值给缓冲区 +const buffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, buffer); +gl.bufferData(gl.ARRAY_BUFFER, array, gl.STATIC_DRAW); + +// 传递并启用顶点数组 +const position = gl.getAttribLocation(program, 'a_position'); +gl.vertexAttribPointer(position, 3, gl.FLOAT, false, 7 * 4, 0); +gl.enableVertexAttribArray(position); + +// 传递并启用颜色数组 +const color = gl.getAttribLocation(program, 'a_color'); +gl.vertexAttribPointer(color, 4, gl.FLOAT, false, 7 * 4, 3 * 4); +gl.enableVertexAttribArray(color); + +``` + +使用这种方式,我们只需要创建一个类型化数组,更加直观,而且只需要绑定一个缓冲区,运行速度也会提升。 + +# 6.10.4 变换矩阵 + +## 视角变换与投影变换 + +我们需要先创建四个矩阵分别存储 model view projection 变换以及运算结果: + +```TypeScript +// 创建变换矩阵 +const trans = mat4.create(); +const model = mat4.create(); +const view = mat4.create(); +const proj = mat4.create(); +``` + +视角变换和投影变换不会变化,因此直接写,摄像机在 `[0, 3, 4]` 的位置看向原点,相当于向前下方看;视角选用 45°,这个视角下的透视关系与人眼相似(等效焦距约 50mm): + +```TypeScript +mat4.lookAt(view, [0, 3, 4], [0, 0, 0], [0, 1, 0]); +mat4.perspective(proj, Math.PI / 4, 1, 0.1, 10); +``` + +## 模型变换 + +正方体在旋转,因此我们需要每帧设定它的模型变换。 + +这里我们不再使用每帧加上角度的方式,因为帧率会影响结果,我们换为使用时间计算角度的方式。我们只需要设定一个常数,让它乘以时间作为旋转角度即可,为了避免数据溢出,我们还需要将角度范围限定在 `[0, 2*pi]` 范围内: + +```TypeScript +// 使用 time 计算角度,与帧率不绑定 +let angle = time / 500; +if (time > Math.PI * 2) { + // 确保范围在 [0, 2*pi] 之间 + const n = Math.floor(time / Math.PI / 2); + angle -= Math.PI * 2 * n; +} +``` + +然后使用 `fromYRotation` 方法生成矩阵: + +```TypeScript +mat4.fromYRotation(model, angle); +``` + +## 计算变换矩阵 + +接下来,我们只需要将三个矩阵倒序相乘即可,注意计算前需要先把结果重置为单位矩阵: + +```TypeScript +// 重置并计算变换矩阵 +mat4.identity(trans); +mat4.multiply(trans, trans, proj); +mat4.multiply(trans, trans, view); +mat4.multiply(trans, trans, model); +``` + +## 传递变换矩阵 + +传递变换矩阵不再使用上一节课讲的 `uniform[1234][uif][v]` 方法,它使用 `uniformMatrix[234]x[234]fv` 方法。一个典型的名称是 `uniformMatrix2x3fv`,表示传递一个 `mat2x3`,即一个二列三行的矩阵。而对于 `mat2` `mat3` `mat4`,则不使用 `uniformMatrix2x2fv` 这种命名方式,而是简写成 `uniformMatrix2fv` 这种形式。 + +这个系列方法的命名方式较为直观简单,不再画图说明。 + +每种方法的用法都一致,类型声明如下: + +```TypeScript +function uniformMatrix[234]x[234]fv( + location: WebGLUniformLocation, + transpose: boolean, + data: Float32Array, + srcOffset?: number, + srcLength?: number +): void; +``` + +每个参数含义如下: + +- `location`:`uniform` 变量位置,使用 `getUniformLocation` 获取。 +- `transpose`:是否对矩阵转置,`GLSL` 使用列主序矩阵,如果运算时使用了行主序,那么需要转置。我们使用 `gl-matrix` 库,并不需要转置。 +- `data`:矩阵内容。 +- `srcOffset` `srcLength`:读取时使用的索引偏移量与长度。 + +我们需要传递一个变换矩阵,因此使用 `uniformMatrix4fv` 方法: + +```TypeScript +// uniform 变量地址,不需要每帧执行 +const transform = gl.getUniformLocation(program, 'u_transform'); +// 每帧执行 +gl.uniformMatrix4fv(transform, false, trans); +``` + +# 6.10.5 执行渲染 + +我们需要开启面剔除功能: + +```TypeScript +gl.enable(gl.CULL_FACE); +gl.cullFace(gl.BACK); +``` + +你可以通过调整摄像机的位置检查面剔除是否生效,把摄像机位置设到正方体内(例如 `[0, 0.2, 0.2]`),理应不会显示任何内容。 + +每帧执行渲染,注意绘制点数不再是 3,而是 `array.length / 7`: + +```TypeScript + gl.clearColor(0, 0, 0, 1); + gl.clearDepth(1); + gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); + + // 执行渲染 + gl.drawArrays(gl.TRIANGLES, 0, array.length / 7); +``` + +# 6.10.6 完整代码 + +## 顶点着色器 + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec4 a_position; +in vec4 a_color; + +uniform mat4 u_transform; + +out vec4 v_color; + +void main() { + v_color = a_color; + gl_Position = u_transform * a_position; +} +``` + +## 片段着色器 + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec4 v_color; +out vec4 outColor; + +void main() { + outColor = v_color; +} +``` + +## TypeScript + +```TypeScript +import { mat4 } from "gl-matrix"; +// 创建画布 +const canvas = document.querySelector("#webgl"); +const gl = canvas.getContext("webgl2")!; + +//设置画布宽高 +canvas.width = 300 * devicePixelRatio; +canvas.height = 300 * devicePixelRatio; + +// 顶点着色器见上面的代码块 +const vs = /* glsl */ ` +`; + +// 片段着色器见上面的代码块 +const fs = /*glsl */ ` +`; + +// 编译着色器 +const vsShader = compileShader(gl.VERTEX_SHADER, vs) +const fsShader = compileShader(gl.FRAGMENT_SHADER, fs); + +// 创建程序并编译链接 +const program = gl.createProgram(); +gl.attachShader(program, vsShader); +gl.attachShader(program, fsShader); +gl.linkProgram(program); + +// 如果程序链接失败 +if (!gl.getProgramParameter(program, gl.LINK_STATUS)) { + const info = gl.getProgramInfoLog(program); + throw new Error(`无法编译 WebGL 程序。\n\n${info}`); +} + +// 定义顶点数组和颜色数组 +const array = new Float32Array([ + 0.5, 0.5, 0.5, 1, 0, 0, 1, + -0.5, 0.5, 0.5, 1, 0, 0, 1, + 0.5, -0.5, 0.5, 1, 0, 0, 1, // 前面右上角三角形 + 0.5, -0.5, 0.5, 1, 0, 0, 1, + -0.5, 0.5, 0.5, 1, 0, 0, 1, + -0.5, -0.5, 0.5, 1, 0, 0, 1, // 前面左下角三角形 + + 0.5, 0.5, 0.5, 0, 1, 0, 1, + 0.5, 0.5, -0.5, 0, 1, 0, 1, + -0.5, 0.5, -0.5, 0, 1, 0, 1, // 上面右后方三角形 + -0.5, 0.5, -0.5, 0, 1, 0, 1, + -0.5, 0.5, 0.5, 0, 1, 0, 1, + 0.5, 0.5, 0.5, 0, 1, 0, 1, // 上面左前方三角形 + + -0.5, 0.5, 0.5, 0, 0, 1, 1, + -0.5, 0.5, -0.5, 0, 0, 1, 1, + -0.5, -0.5, 0.5, 0, 0, 1, 1, // 左面上前方三角形 + -0.5, -0.5, 0.5, 0, 0, 1, 1, + -0.5, 0.5, -0.5, 0, 0, 1, 1, + -0.5, -0.5, -0.5, 0, 0, 1, 1, // 左面下后方三角形 + + 0.5, 0.5, 0.5, 1, 1, 0, 1, + 0.5, -0.5, 0.5, 1, 1, 0, 1, + 0.5, 0.5, -0.5, 1, 1, 0, 1, // 右面上前方三角形 + 0.5, 0.5, -0.5, 1, 1, 0, 1, + 0.5, -0.5, 0.5, 1, 1, 0, 1, + 0.5, -0.5, -0.5, 1, 1, 0, 1, // 右面下后方三角形 + + 0.5, -0.5, -0.5, 1, 0, 1, 1, + 0.5, -0.5, 0.5, 1, 0, 1, 1, + -0.5, -0.5, -0.5, 1, 0, 1, 1, // 下面右后方三角形 + -0.5, -0.5, -0.5, 1, 0, 1, 1, + 0.5, -0.5, 0.5, 1, 0, 1, 1, + -0.5, -0.5, 0.5, 1, 0, 1, 1, // 下面左前方三角形 + + 0.5, 0.5, -0.5, 0, 1, 1, 1, + 0.5, -0.5, -0.5, 0, 1, 1, 1, + -0.5, 0.5, -0.5, 0, 1, 1, 1, // 后面右上方三角形 + -0.5, 0.5, -0.5, 0, 1, 1, 1, + 0.5, -0.5, -0.5, 0, 1, 1, 1, + -0.5, -0.5, -0.5, 0, 1, 1, 1, // 后面左下方三角形 +]); + +// 顶点赋值给缓冲区 +const buffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, buffer); +gl.bufferData(gl.ARRAY_BUFFER, array, gl.STATIC_DRAW); + +// 传递并启用顶点数组 +const position = gl.getAttribLocation(program, 'a_position'); +gl.vertexAttribPointer(position, 3, gl.FLOAT, false, 7 * 4, 0); +gl.enableVertexAttribArray(position); + +// 传递并启用颜色数组 +const color = gl.getAttribLocation(program, 'a_color'); +gl.vertexAttribPointer(color, 4, gl.FLOAT, false, 7 * 4, 3 * 4); +gl.enableVertexAttribArray(color); + +// uniform 变量地址 +const transform = gl.getUniformLocation(program, 'u_transform'); + +// 使用着色器程序 +gl.useProgram(program); + +// 设置视口 +gl.viewport(0, 0, canvas.width, canvas.height); +gl.enable(gl.CULL_FACE); +gl.cullFace(gl.BACK); + +// 创建变换矩阵 +const trans = mat4.create(); +const model = mat4.create(); +const view = mat4.create(); +const proj = mat4.create(); + +mat4.lookAt(view, [0, 3, 4], [0, 0, 0], [0, 1, 0]); +mat4.perspective(proj, Math.PI / 4, 1, 0.1, 10); + +// 每帧重绘 +const drawScene = (time: number) => { + // 使用 time 计算角度,与帧率不绑定 + let angle = time / 500; + if (time > Math.PI * 2) { + // 确保范围在 [0, 2*pi] 之间 + const n = Math.floor(time / Math.PI / 2); + angle -= Math.PI * 2 * n; + } + + mat4.fromYRotation(model, angle); + + // 重置并计算变换矩阵 + mat4.identity(trans); + mat4.multiply(trans, trans, proj); + mat4.multiply(trans, trans, view); + mat4.multiply(trans, trans, model); + + gl.uniformMatrix4fv(transform, false, trans); + + gl.clearColor(0, 0, 0, 1); + gl.clearDepth(1); + gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); + + // 执行渲染 + gl.drawArrays(gl.TRIANGLES, 0, array.length / 7); + + requestAnimationFrame(drawScene); +} +requestAnimationFrame(drawScene); + +/** + * 编译着色器 + * @param type 着色器类型 + * @param source 着色器代码 + */ +function compileShader(type: GLenum, source: string): WebGLShader { + const shader = gl.createShader(type); + gl.shaderSource(shader, source); + gl.compileShader(shader); + + // 如果编译失败 + if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) { + const info = gl.getShaderInfoLog(shader); + throw new Error(`无法编译着色器。\n\n${info}`); + } + + return shader; +} +``` \ No newline at end of file diff --git a/.planning/references/feishu-teaching-docs/09.md b/.planning/references/feishu-teaching-docs/09.md new file mode 100644 index 0000000..6398655 --- /dev/null +++ b/.planning/references/feishu-teaching-docs/09.md @@ -0,0 +1,450 @@ +6.11 纹理贴图 + +本节课讲解如何在 `WebGL2` 中渲染一张图片,以下面这张音理的图为例,你可以右键另存为来下载它: + +![](https://feishu.cn/file/VfN4bfFxjocILUxHtN8cJOr5nLh) + +代码地址:https://codepen.io/unanmed/pen/gbPXNXX + +# 6.11.1 图片加载 + +资源加载我们在后面的课程中还会学习到,而且三言两语讲不清楚,因此这里直接给出从一个允许跨域(Cross Origin)的链接加载图片的模板: + +```TypeScript +const imgSrc = '图片链接'; +const img = new Image(); +img.src = imgSrc; +img.crossOrigin = ''; +``` + +如果图片服务器不允许跨域,那么之后在进行渲染的时候会报错(跨域问题在加载相关课程中还会讲解到)。 + +我们从 `JSDelivr` 上加载图片,这是一个全球通用的 `cdn` 服务器,允许跨域访问。该网站会自动从 `GitHub` 上同步资源。 + +```TypeScript +const imgSrc = 'https://cdn.jsdelivr.net/gh/unanmed/h5-programming-training/img/5.11.webp'; +const img = new Image(); +img.src = imgSrc; +img.crossOrigin = ''; +``` + +# 6.11.2 纹理操作 + +## 创建纹理 + +我们使用 `gl.createTexture` 创建纹理: + +```TypeScript +function createTexture(): WebGLTexture; +``` + +例如: + +```TypeScript +const texture = gl.createTexture(); +``` + +## 激活与绑定纹理 + +接下来,我们需要告诉 `WebGL2` 我们需要操作哪个纹理,以及纹理存放在哪个地方。 + +首先我们需要调用 `gl.activeTexture` 来激活一个纹理: + +```TypeScript +function activeTexture(texture: number): void; +``` + +我们使用 0 号纹理,传入 `gl.TEXTURE0`: + +```TypeScript +gl.activeTexture(gl.TEXTURE0); +``` + +然后我们需要调用 `gl.bindTexture` 让 `WebGL2` 知道我们需要操作的是哪个纹理对象: + +```TypeScript +function bindTexture(target: GLenum, texture: WebGLTexture): void; +``` + +我们使用二维纹理,因此传入 `gl.TEXTURE_2D`,其他类型的纹理我们在后面的课程中讲解。 + +```TypeScript +gl.bindTexture(gl.TEXTURE_2D, texture); +``` + +这样,我们就会操作我们刚刚定义的 `texture` 纹理对象,它被绑定到了二维纹理,同时我们激活了 0 号纹理,因此我们对它的操作会自动传入 0 号纹理。最终的结果就是,我们定义了一个二维纹理,并把它绑定到了 0 号纹理。 + +这里的逻辑比较绕,相比于缓冲区它还多了一层绑定,相当于绑定了两次。 + +## 传输纹理 + +接下来我们需要把图片传递给纹理对象,使用 `texImage2D`,我们最常用的是这个用法: + +```TypeScript +function texImage2D( + target: GLenum, + level: number, + internalFormat: GLenum, + format: GLenum, + type: GLenum, + pixels: TexImageSource +): void; +``` + +- `target`:要把图片传递给绑定的纹理对象。 +- `level`:图片的金字塔简化级别。这个我们之后的课程中讨论,本节不讨论。 +- `internalFormat`:图片的内部存储格式,常使用 `gl.RGBA`,其他值在部分情况下也可能会使用。 +- `format`:图像源的读取方式,常使用 `gl.RGBA`,它会读取四个通道,如果填写 `gl.RGB`,那么会抛弃不透明度通道,只保留颜色通道。其他格式使用较少。一般与 `internalFormat` 保持一致。 +- `type`:数据类型,常使用 `gl.UNSIGNED_BYTE` 表示八位色深的图片。 +- `pixels`:图像源,可以是 `TypedArray` `HTMLCanvasElement` `HTMLImageElement` 等。 + +我们的示例中使用 `HTMLImageElement` 作为图像源,格式为 `gl.RGBA`,数据类型为 `gl.UNSIGNED_BYTE`,因此: + +```TypeScript +gl.activeTexture(gl.TEXTURE0); +gl.bindTexture(gl.TEXTURE_2D, texture); +gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img); +``` + +一般我们会使用宽高为2的幂次的图像,例如 `1024*1024` `512*256` 等,这种图像会帮助 `WebGL2` 内部优化,性能表现会更好。不是这些大小的纹理依然可以使用(`WebGL` 不行,只有 `WebGL2` 可以)。 + +## 性能问题 + +使用 `WebGL2` 画图片确实很快,但是如果去尝试的话会发现耗时远比 `Canvas2D` 更长,这不是因为 `WebGL2` 画图片的速度更慢,而是因为时间都花费在了图片的传递上,也就是说把图片传递给 GPU 是个很慢的操作。关于这个问题,我们在之后将会有几节课专门讲解。 + +# 6.11.3 纹理参数 + +我们会使用 `gl.texParameteri` 来控制部分纹理参数: + +```TypeScript +function texParameteri(texture: GLenum, param: GLenum, value: GLenum): void; +``` + +## 缩放参数 + +缩放参数包含两个 `gl.TEXTURE_MAG_FILTER` 和 `gl.TEXTURE_MIN_FILTER`,分别代表放大参数与缩小参数。它们都可以填这两个参数: + +- `gl.NEAREST`:取最近的采样点,即当前点距离纹理的哪个像素最近取哪个。 +- `gl.LINEAR`:取周围的采样点,并执行线性插值操作,相当于有简易的抗锯齿。 + +其他值我们本节课接触不到,暂时不讲解。 + +我们的图片不是像素风图片,这时候一般建议使用 `gl.LINEAR`: + +```TypeScript +gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR); +gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR); +``` + +## 边缘参数 + +边缘参数指的是如果读取了在纹理范围之外的坐标,会有什么行为。如图所示: + + + +![](https://feishu.cn/file/Lpj2bCvPCo4Aztx5CpYcJEkBn2M) + + +![](https://feishu.cn/file/HLRgbR1mCoaEbJxbJ0ncPZHpnYf) + + +![](https://feishu.cn/file/B7rUbkKmloVBHKx2LB0cwVT4nzh) + + + +这三种情况就代表了三种不同的边缘参数: + +- `gl.REPEAT`:超出部分重复纹理。 +- `gl.MIRRORED_REPEAT`:超出部分重复,但是镜像。 +- `gl.CLAMP_TO_EDGE`:超出部分读取边缘像素。 + +这三种参数都有不同的使用场景。 + +我们可以分别设置横坐标上的边缘参数与纵坐标上的边缘参数: + +```TypeScript +gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE); +gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE); +``` + +# 6.11.4 着色器 + +## `sampler2D` 数据类型 + +贴图需要使用 `sampler2D` 数据类型,我们需要在片段着色器里面定义一个 `uniform` 变量: + +```OpenGL Shading Language +uniform sampler2D u_sampler; +``` + +这个数据类型描述了贴图的采样器,即用来读取贴图。它本质上是一个数字,存储了要读取的纹理编号。我们先前提到的纹理编号,对应到着色器就是这个数据类型。 + +我们使用的是 0 号纹理,因此我们需要给它赋值为 0: + +```TypeScript +const location = gl.getUniformLocation('u_sampler'); +gl.uniform1i(location, 0); +``` + +## 纹理读取 + +纹理的坐标与 `WebGL2` 的世界坐标并不一样。对于纹理,左上角坐标是 `(0,0)`,右上角坐标是 `(1,0)`,左下角坐标是 `(0,1)`,右下角坐标是 `(1,1)`,也就是与 `Canvas2D` 的坐标模式一致。 + +读取纹理使用 `texture` 接口,它会返回一个 `vec4` 四维向量,包含了 `RGBA` 通道: + +```OpenGL Shading Language +outColor = texture(u_sampler, coord); +``` + +那么我们需要考虑一个问题,这里的第二个参数 `coord` 坐标该怎么填? + +还记得之前讲过的插值吗,我们可以利用插值来填写坐标。我们可以在顶点着色器内定义一个纹理坐标输入和输出: + +```OpenGL Shading Language +in vec2 a_texCoord; +out vec2 v_texCoord; +``` + +然后传递给片段着色器: + +```OpenGL Shading Language +v_texCoord = a_texCoord; +``` + +这样的话,传递给片段着色器的坐标就是经过插值的。我们只需要控制纹理坐标输入,让它在左上角的顶点值为 `(0,0)`,右上角的顶点值为 `(1,0)`... 就可以让贴图画出来了。 + +这样的话,片段着色器中的读取贴图就是: + +```OpenGL Shading Language +outColor = texture(u_sampler, v_texCoord); +``` + +## 顶点着色器 + +我们编写顶点着色器如下: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec4 a_position; +in vec2 a_texCoord; + +out vec2 v_texCoord; + +void main() { + v_texCoord = a_texCoord; + gl_Position = a_position; +} +``` + +## 片段着色器 + +我们编写片段着色器如下: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec2 v_texCoord; +out vec4 outColor; + +uniform sampler2D u_sampler; + +void main() { + outColor = texture(u_sampler, v_texCoord); +} +``` + +# 6.11.5 顶点坐标 + +根据上面的讨论,我们可以编写顶点坐标如下,使用 `gl.TRIANGLE_STRIP` 连接方式: + +```TypeScript +const array = new Float32Array([ + 1.0, 1.0, 1.0, 0.0, // 右上角 + -1.0, 1.0, 0.0, 0.0, // 左上角 + 1.0, -1.0, 1.0, 1.0, // 右下角 + -1.0, -1.0, 0.0, 1.0, // 左下角 +]); +``` + +每一行的前两个数代表顶点坐标,后两个数代表纹理坐标。 + +因此传递顶点数组如下: + +```TypeScript +// 顶点赋值给缓冲区 +const buffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, buffer); +gl.bufferData(gl.ARRAY_BUFFER, array, gl.STATIC_DRAW); + +// 传递并启用顶点数组 +const position = gl.getAttribLocation(program, 'a_position'); +gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 4 * 4, 0); +gl.enableVertexAttribArray(position); + +// 传递并启用颜色数组 +const tex = gl.getAttribLocation(program, 'a_texCoord'); +gl.vertexAttribPointer(tex, 2, gl.FLOAT, false, 4 * 4, 2 * 4); +gl.enableVertexAttribArray(tex); +``` + +# 6.11.6 执行渲染 + +我们在图片加载完毕后执行渲染,编写 `drawScene` 函数: + +```TypeScript +const drawScene = () => { + gl.activeTexture(gl.TEXTURE0); + gl.bindTexture(gl.TEXTURE_2D, texture); + gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img); + + // 设置纹理参数 + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR); + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR); + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE); + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE); + + gl.uniform1i(sampler, 0); + + gl.clearColor(0, 0, 0, 1); + gl.clearDepth(1); + gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); + + // 执行渲染 + gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4); +} +``` + +在图片加载完成后调用: + +```TypeScript +img.addEventListener('load', () => { + drawScene(); +}); +``` + +# 6.11.7 完整代码 + +顶点着色器与片段着色器已经在前面给出。以下是 `TypeScript` 内容: + +```TypeScript +const imgSrc = 'https://cdn.jsdelivr.net/gh/unanmed/h5-programming-training/img/5.11.webp'; +const img = new Image(); +img.src = imgSrc; +img.crossOrigin = ''; + +// 创建画布 +const canvas = document.querySelector("#webgl"); +const gl = canvas.getContext("webgl2")!; + +//设置画布宽高 +canvas.width = 300 * devicePixelRatio; +canvas.height = 300 * devicePixelRatio; + +// 顶点着色器已经在上面给出 +const vs = /* glsl */ ` +`; + +// 片段着色器已经在上面给出 +const fs = /*glsl */ ` +`; + +// 编译着色器 +const vsShader = compileShader(gl.VERTEX_SHADER, vs) +const fsShader = compileShader(gl.FRAGMENT_SHADER, fs); + +// 创建程序并编译链接 +const program = gl.createProgram(); +gl.attachShader(program, vsShader); +gl.attachShader(program, fsShader); +gl.linkProgram(program); + +// 如果程序链接失败 +if (!gl.getProgramParameter(program, gl.LINK_STATUS)) { + const info = gl.getProgramInfoLog(program); + throw new Error(`无法编译 WebGL 程序。\n\n${info}`); +} + +// 定义顶点数组和颜色数组 +const array = new Float32Array([ + 1.0, 1.0, 1.0, 0.0, // 右上角 + -1.0, 1.0, 0.0, 0.0, // 左上角 + 1.0, -1.0, 1.0, 1.0, // 右下角 + -1.0, -1.0, 0.0, 1.0, // 左下角 +]); + +// 顶点赋值给缓冲区 +const buffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, buffer); +gl.bufferData(gl.ARRAY_BUFFER, array, gl.STATIC_DRAW); + +// 传递并启用顶点数组 +const position = gl.getAttribLocation(program, 'a_position'); +gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 4 * 4, 0); +gl.enableVertexAttribArray(position); + +// 传递并启用颜色数组 +const tex = gl.getAttribLocation(program, 'a_texCoord'); +gl.vertexAttribPointer(tex, 2, gl.FLOAT, false, 4 * 4, 2 * 4); +gl.enableVertexAttribArray(tex); + +// 创建纹理对象 +const texture = gl.createTexture(); + +// uniform 变量地址 +const sampler = gl.getUniformLocation(program, 'u_sampler'); + +// 使用着色器程序 +gl.useProgram(program); + +// 设置视口 +gl.viewport(0, 0, canvas.width, canvas.height); +gl.disable(gl.CULL_FACE); + +// 传递纹理并绘制 +const drawScene = () => { + gl.activeTexture(gl.TEXTURE0); + gl.bindTexture(gl.TEXTURE_2D, texture); + gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img); + + // 设置纹理参数 + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR); + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR); + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE); + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE); + + gl.uniform1i(sampler, 0); + + gl.clearColor(0, 0, 0, 1); + gl.clearDepth(1); + gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); + + // 执行渲染 + gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4); +} + +img.addEventListener('load', () => { + drawScene(); +}); + +/** + * 编译着色器 + * @param type 着色器类型 + * @param source 着色器代码 + */ +function compileShader(type: GLenum, source: string): WebGLShader { + const shader = gl.createShader(type); + gl.shaderSource(shader, source); + gl.compileShader(shader); + + // 如果编译失败 + if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) { + const info = gl.getShaderInfoLog(shader); + throw new Error(`无法编译着色器。\n\n${info}`); + } + + return shader; +} +``` \ No newline at end of file diff --git a/.planning/references/feishu-teaching-docs/10.md b/.planning/references/feishu-teaching-docs/10.md new file mode 100644 index 0000000..4e358cd --- /dev/null +++ b/.planning/references/feishu-teaching-docs/10.md @@ -0,0 +1,546 @@ +6.12 帧缓冲 + +本节课讲解帧缓冲对象(Frame Buffer Object, FBO)相关的内容,目标是使用帧缓冲实现三维画中画效果。本节课实现效果如图: + +![](https://feishu.cn/file/DXXfbRSpWooVBtx1CfQcs8c2nfe) + +代码链接:https://codepen.io/unanmed/pen/EaPREOp + +# 6.12.1 帧缓冲对象概念 + +之前我们讲到,当 `WebGL2` 渲染时,需要先渲染到帧缓冲上,然后把帧缓冲交给屏幕显示。那如果我们把帧缓冲截获,不让它渲染到屏幕上,而是渲染到一个纹理上呢? + +我们将 `WebGL2` 渲染到纹理上,这一步是通过帧缓冲对象 Frame Buffer Object(简称 FBO)实现的。 + +## 创建 FBO + +我们使用 `gl.createFramebuffer` 创建帧缓冲对象,注意这里的 `createFramebuffer` 中 `Framebuffer` 的 `b` 不大写。 + +```TypeScript +function createFramebuffer(): WebGLFramebuffer; +``` + +示例如下: + +```TypeScript +const fb = gl.createFramebuffer(); +``` + +## 绑定 FBO + +操作 `FBO` 的方式与缓冲区类似,都遵循先绑定再操作的模式。 + +首先我们需要使用 `gl.bindFramebuffer` 将 `FBO` 绑定: + +```TypeScript +function bindFramebuffer(target: GLenum, framebuffer: WebGLFramebuffer | null): void +``` + +其中第一项是要绑定至哪个缓冲区,一般我们填写 `gl.FRAMEBUFFER`。 + +第二个参数是要绑定的 `FBO`,填写 `null` 时表示取消绑定。 + +我们需要将刚刚创建的缓冲区绑定: + +```TypeScript +gl.bindFramebuffer(gl.FRAMEBUFFER, fb); +``` + +这是我们操作的就是我们绑定的缓冲区了,而且渲染时也是渲染至此 `FBO`,而不是画布本身。因此这时候你去渲染的话将什么都得不到。 + +## 配置 FBO 渲染至纹理 + +操作 `FBO`,并配置为渲染至纹理使用 `gl.framebufferTexture2D` 方法: + +```TypeScript +function framebufferTexture2D( + target: GLenum, + attachment: GLenum, + texTarget: GLenum, + texture: WebGLTexture, + level: number +): void; +``` + +- `target`:要操作的 `FBO` 缓冲区,一般填写 `gl.FRAMEBUFFER`。 +- `attachment`:要将什么内容渲染到 `FBO`,可以填写 `gl.COLOR_ATTACHMENT0` 表示颜色内容,也可以填写 `gl.DEPTH_ATTACHMENT` 表示深度内容等。 +- `texTarget`:表示将内容渲染至哪个纹理,如果使用二维纹理,填写 `gl.TEXTURE_2D`。 +- `texture`:表示渲染至的纹理对象。 +- `level`:这一项只能填 0。 + +我们需要将颜色渲染至纹理,渲染至 `gl.TEXTURE_2D` 纹理。因此: + +```TypeScript +// 创建纹理 +const frameTexture = gl.createTexture(); +gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, frameTexture, 0); +``` + +# 6.12.2 初始化纹理 + +此时我们并不能直接开始渲染,因为现在纹理没有任何内容,此时它的大小为 0,将一个大小不一致的东西渲染到纹理当然会有问题。因此我们需要预先给纹理分配内存。 + +这一操作使用 `gl.texImage2D` 的这个重载: + +```TypeScript +function texImage2D( + target: GLenum, + level: number, + internalFormat: GLenum, + width: number, + height: number, + border: number, + format: GLenum, + type: GLenum, + pixels: TypedArray +): void; +``` + +- `target` `level` `internalFormat` `format` `type`:这些前面讲过,不再讲了。 +- `width` `height`:给纹理指定大小。因为我们需要使用一维的 `TypedArray`,不指定宽高的话 `WebGL2` 没办法知道纹理应该多大。 +- `border`:这一项必须填 0。 +- `pixels`:`TypedArray` 组成的颜色信息。 + +我们初始化的时候不需要提供颜色信息,初始化纹理大小为 `512*512`,因此: + +```TypeScript +gl.bindTexture(gl.TEXTURE_2D, frameTexture); // 记得绑定纹理 +gl.texImage2D( + gl.TEXTURE_2D, 0, gl.RGBA, 512, 512, 0, gl.RGBA, gl.UNSIGNED_SHORT, + // 使用 Uint8Array 类型化数组,长度为面积*4,因为有 RGBA 四个通道 + new Uint8Array(512 * 512 * 4) +); +// 配置纹理信息 +gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR); +gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR); +gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE); +gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE); +``` + +# 6.12.3 着色器 + +我们需要画一个正方体,同时把贴图贴上去,因此我们对 6.10 节的着色器稍加修改即可。 + +## 顶点着色器 + +需要编写 `u_transform` 变量,同时接收 `a_texCoord`,输出 `v_texCoord`: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec4 a_position; +in vec2 a_texCoord; + +uniform mat4 u_transform; + +out vec2 v_texCoord; + +void main() { + v_texCoord = a_texCoord; + gl_Position = u_transform * a_position; +} +``` + +## 片段着色器 + +接收 `v_texCoord` 并读取纹理: + +```OpenGL Shading Language +#version 300 es +precision highp float; + +in vec2 v_texCoord; +out vec4 outColor; + +uniform sampler2D u_sampler; + +void main() { + outColor = texture(u_sampler, v_texCoord); +} +``` + +# 6.12.4 顶点数组 + +我们需要对顶点数组做一些改变,不再传入颜色,而是传入纹理坐标: + +```TypeScript +const array = new Float32Array([ + 0.5, 0.5, 0.5, 1, 0, + -0.5, 0.5, 0.5, 0, 0, + 0.5, -0.5, 0.5, 1, 1, // 前面右上角三角形 + 0.5, -0.5, 0.5, 1, 1, + -0.5, 0.5, 0.5, 0, 0, + -0.5, -0.5, 0.5, 0, 1, // 前面左下角三角形 + + 0.5, 0.5, 0.5, 1, 1, + 0.5, 0.5, -0.5, 1, 0, + -0.5, 0.5, -0.5, 0, 0, // 上面右后方三角形 + -0.5, 0.5, -0.5, 0, 0, + -0.5, 0.5, 0.5, 0, 1, + 0.5, 0.5, 0.5, 1, 1, // 上面左前方三角形 + + -0.5, 0.5, 0.5, 1, 0, + -0.5, 0.5, -0.5, 0, 0, + -0.5, -0.5, 0.5, 1, 1, // 左面上前方三角形 + -0.5, -0.5, 0.5, 1, 1, + -0.5, 0.5, -0.5, 0, 0, + -0.5, -0.5, -0.5, 0, 1, // 左面下后方三角形 + + 0.5, 0.5, 0.5, 0, 0, + 0.5, -0.5, 0.5, 0, 1, + 0.5, 0.5, -0.5, 1, 0, // 右面上前方三角形 + 0.5, 0.5, -0.5, 1, 0, + 0.5, -0.5, 0.5, 0, 1, + 0.5, -0.5, -0.5, 1, 1, // 右面下后方三角形 + + 0.5, -0.5, -0.5, 1, 1, + 0.5, -0.5, 0.5, 1, 0, + -0.5, -0.5, -0.5, 0, 1, // 下面右后方三角形 + -0.5, -0.5, -0.5, 0, 1, + 0.5, -0.5, 0.5, 1, 0, + -0.5, -0.5, 0.5, 0, 0, // 下面左前方三角形 + + 0.5, 0.5, -0.5, 0, 0, + 0.5, -0.5, -0.5, 0, 1, + -0.5, 0.5, -0.5, 1, 0, // 后面右上方三角形 + -0.5, 0.5, -0.5, 1, 0, + 0.5, -0.5, -0.5, 0, 1, + -0.5, -0.5, -0.5, 1, 1, // 后面左下方三角形 +]); +``` + +对 `vertexAttribPointer` 稍作修改: + +```TypeScript +// 传递并启用顶点数组 +const position = gl.getAttribLocation(program, 'a_position'); +gl.vertexAttribPointer(position, 3, gl.FLOAT, false, 5 * 4, 0); +gl.enableVertexAttribArray(position); + +// 传递并启用纹理数组 +const tex = gl.getAttribLocation(program, 'a_texCoord'); +gl.vertexAttribPointer(tex, 2, gl.FLOAT, false, 5 * 4, 3 * 4); +gl.enableVertexAttribArray(tex); +``` + +# 6.12.5 图片加载 + +我们不再在 `drawScene` 里面传递纹理,因为这样的话会每帧传递一次,性能会显著下降。我们只需要在图片加载完毕的时候传递纹理就可以了: + +```TypeScript +const imgSrc = 'https://cdn.jsdelivr.net/gh/unanmed/h5-programming-training/img/5.11.webp'; +const img = new Image(); +img.src = imgSrc; +img.crossOrigin = ''; + +const texture = gl.createTexture(); + +img.addEventListener('load', () => { + gl.activeTexture(gl.TEXTURE0); + gl.bindTexture(gl.TEXTURE_2D, texture); + gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img); + + // 设置纹理参数 + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR); + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR); + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE); + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE); + + gl.uniform1i(sampler, 0); + + // 调用 drawScene + requestAnimationFrame(drawScene); +}); +``` + +# 6.12.6 渲染行为 + +为了之后叙述方便,并消除歧义,我们会使用一个单独的名词 draw call,它表示调用一次渲染函数 `gl.drawArrays` 等。 + +为了实现目标效果,我们需要两次 draw call,首先将一个贴满图片的正方体渲染到 `FBO`,然后再把 `FBO` 作为纹理渲染到正方形上,作为最终渲染结果。 + +## 第一次渲染 + +我们需要先设定视口,将视口大小与纹理大小匹配,视口大小可以比画布本身更大: + +```TypeScript +gl.viewport(0, 0, 512, 512); +``` + +然后我们清空缓冲区: + +```TypeScript +gl.clearColor(0.4, 1, 1, 1); +gl.clearDepth(1); +gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); +``` + +接下来我们需要绑定 `FBO`,将要渲染至的 `FBO` 绑定到 `gl.FRAMEBUFFER`,并把要渲染至的纹理绑定至 `gl.TEXTURE_2D`: + +```TypeScript +gl.bindTexture(gl.TEXTURE_2D, texture); +gl.bindFramebuffer(gl.FRAMEBUFFER, frameBuffer); +``` + + 最后执行 draw call: + +```TypeScript +gl.drawArrays(gl.TRIANGLES, 0, array.length / 5); +``` + +## 第二次渲染 + +我们需要设置视口为画布大小: + +```TypeScript +gl.viewport(0, 0, canvas.width, canvas.height); +``` + +取消 `FBO` 绑定并绑定纹理为刚刚 `FBO` 渲染至的纹理: + +```TypeScript +gl.bindTexture(gl.TEXTURE_2D, frameTexture); +gl.bindFramebuffer(gl.FRAMEBUFFER, null); +``` + +记得清空缓冲区: + +```TypeScript +gl.clearColor(0, 0, 0, 1); +gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); +``` + +最后渲染至画面: + +```TypeScript +gl.drawArrays(gl.TRIANGLES, 0, array.length / 5); +``` + +# 6.12.7 完整代码 + +着色器代码已在上面给出,此处不再给出。 + +```TypeScript +import { mat4 } from "https://esm.sh/gl-matrix"; + +const imgSrc = 'https://cdn.jsdelivr.net/gh/unanmed/h5-programming-training/img/5.11.webp'; +const img = new Image(); +img.src = imgSrc; +img.crossOrigin = ''; + +// 创建画布 +const canvas = document.querySelector("#webgl"); +const gl = canvas.getContext("webgl2")!; + +//设置画布宽高 +canvas.width = 300 * devicePixelRatio; +canvas.height = 300 * devicePixelRatio; + +const frameBufferSize = 512; + +// 顶点着色器 +const vs = /* glsl */ ` +`; + +// 片段着色器 +const fs = /*glsl */ ` +`; + +// 编译着色器 +const vsShader = compileShader(gl.VERTEX_SHADER, vs) +const fsShader = compileShader(gl.FRAGMENT_SHADER, fs); + +// 创建程序并编译链接 +const program = gl.createProgram(); +gl.attachShader(program, vsShader); +gl.attachShader(program, fsShader); +gl.linkProgram(program); + +// 如果程序链接失败 +if (!gl.getProgramParameter(program, gl.LINK_STATUS)) { + const info = gl.getProgramInfoLog(program); + throw new Error(`无法编译 WebGL 程序。\n\n${info}`); +} + +// 定义顶点数组和颜色数组 +const array = new Float32Array([ + 0.5, 0.5, 0.5, 1, 0, + -0.5, 0.5, 0.5, 0, 0, + 0.5, -0.5, 0.5, 1, 1, // 前面右上角三角形 + 0.5, -0.5, 0.5, 1, 1, + -0.5, 0.5, 0.5, 0, 0, + -0.5, -0.5, 0.5, 0, 1, // 前面左下角三角形 + + 0.5, 0.5, 0.5, 1, 1, + 0.5, 0.5, -0.5, 1, 0, + -0.5, 0.5, -0.5, 0, 0, // 上面右后方三角形 + -0.5, 0.5, -0.5, 0, 0, + -0.5, 0.5, 0.5, 0, 1, + 0.5, 0.5, 0.5, 1, 1, // 上面左前方三角形 + + -0.5, 0.5, 0.5, 1, 0, + -0.5, 0.5, -0.5, 0, 0, + -0.5, -0.5, 0.5, 1, 1, // 左面上前方三角形 + -0.5, -0.5, 0.5, 1, 1, + -0.5, 0.5, -0.5, 0, 0, + -0.5, -0.5, -0.5, 0, 1, // 左面下后方三角形 + + 0.5, 0.5, 0.5, 0, 0, + 0.5, -0.5, 0.5, 0, 1, + 0.5, 0.5, -0.5, 1, 0, // 右面上前方三角形 + 0.5, 0.5, -0.5, 1, 0, + 0.5, -0.5, 0.5, 0, 1, + 0.5, -0.5, -0.5, 1, 1, // 右面下后方三角形 + + 0.5, -0.5, -0.5, 1, 1, + 0.5, -0.5, 0.5, 1, 0, + -0.5, -0.5, -0.5, 0, 1, // 下面右后方三角形 + -0.5, -0.5, -0.5, 0, 1, + 0.5, -0.5, 0.5, 1, 0, + -0.5, -0.5, 0.5, 0, 0, // 下面左前方三角形 + + 0.5, 0.5, -0.5, 0, 0, + 0.5, -0.5, -0.5, 0, 1, + -0.5, 0.5, -0.5, 1, 0, // 后面右上方三角形 + -0.5, 0.5, -0.5, 1, 0, + 0.5, -0.5, -0.5, 0, 1, + -0.5, -0.5, -0.5, 1, 1, // 后面左下方三角形 +]); + +// 顶点赋值给缓冲区 +const buffer = gl.createBuffer(); +gl.bindBuffer(gl.ARRAY_BUFFER, buffer); +gl.bufferData(gl.ARRAY_BUFFER, array, gl.STATIC_DRAW); + +// 传递并启用顶点数组 +const position = gl.getAttribLocation(program, 'a_position'); +gl.vertexAttribPointer(position, 3, gl.FLOAT, false, 5 * 4, 0); +gl.enableVertexAttribArray(position); + +// 传递并启用纹理数组 +const tex = gl.getAttribLocation(program, 'a_texCoord'); +gl.vertexAttribPointer(tex, 2, gl.FLOAT, false, 5 * 4, 3 * 4); +gl.enableVertexAttribArray(tex); + +// 创建纹理对象 +const texture = gl.createTexture(); + +// uniform 变量地址 +const sampler = gl.getUniformLocation(program, 'u_sampler'); +const transform = gl.getUniformLocation(program, 'u_transform'); + +// framebuffer +const frameBuffer = gl.createFramebuffer(); +const frameTexture = gl.createTexture(); +gl.bindTexture(gl.TEXTURE_2D, frameTexture); +gl.bindFramebuffer(gl.FRAMEBUFFER, frameBuffer); +gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, frameTexture, 0); +// 初始化 fbo 纹理 +gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, frameBufferSize, frameBufferSize, 0, gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array(frameBufferSize * frameBufferSize * 4)); +gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR); +gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR); +gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE); +gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE); + +// 使用着色器程序 +gl.useProgram(program); + +// 配置 +gl.enable(gl.CULL_FACE); +gl.cullFace(gl.BACK); +gl.enable(gl.DEPTH_TEST); +gl.depthFunc(gl.LESS); + +// 创建变换矩阵 +const trans = mat4.create(); +const model = mat4.create(); +const view = mat4.create(); +const proj = mat4.create(); + +mat4.lookAt(view, [0, 3, 4], [0, 0, 0], [0, 1, 0]); +mat4.perspective(proj, Math.PI / 9, 1, 0.1, 10); + +// 传递纹理并绘制 +const drawScene = (time: number) => { + // 使用 time 计算角度,与帧率不绑定 + let angle = time / 1000; + if (time > Math.PI * 2) { + // 确保范围在 [0, 2*pi] 之间 + const n = Math.floor(time / Math.PI / 2); + angle -= Math.PI * 2 * n; + } + + mat4.fromYRotation(model, angle); + + // 重置并计算变换矩阵 + mat4.identity(trans); + mat4.multiply(trans, trans, proj); + mat4.multiply(trans, trans, view); + mat4.multiply(trans, trans, model); + + gl.uniformMatrix4fv(transform, false, trans); + + gl.viewport(0, 0, frameBufferSize, frameBufferSize); + + // 使用原图作为纹理 + gl.bindTexture(gl.TEXTURE_2D, texture); + gl.bindFramebuffer(gl.FRAMEBUFFER, frameBuffer); + + gl.clearColor(0.4, 1, 1, 1); + gl.clearDepth(1); + gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); + + // 渲染至纹理 + gl.drawArrays(gl.TRIANGLES, 0, array.length / 5); + + // 取消 fbo 绑定,使用 fbo 作为纹理 + gl.bindTexture(gl.TEXTURE_2D, frameTexture); + gl.bindFramebuffer(gl.FRAMEBUFFER, null); + + gl.viewport(0, 0, canvas.width, canvas.height); + + gl.clearColor(0, 0, 0, 1); + gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); + + // 渲染至画面 + gl.drawArrays(gl.TRIANGLES, 0, array.length / 5); + + requestAnimationFrame(drawScene); +} + +img.addEventListener('load', () => { + gl.activeTexture(gl.TEXTURE0); + gl.bindTexture(gl.TEXTURE_2D, texture); + gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img); + + // 设置纹理参数 + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR); + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR); + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE); + gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE); + + gl.uniform1i(sampler, 0); + + requestAnimationFrame(drawScene); +}); + +/** + * 编译着色器 + * @param type 着色器类型 + * @param source 着色器代码 + */ +function compileShader(type: GLenum, source: string): WebGLShader { + const shader = gl.createShader(type); + gl.shaderSource(shader, source); + gl.compileShader(shader); + + // 如果编译失败 + if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) { + const info = gl.getShaderInfoLog(shader); + throw new Error(`无法编译着色器。\n\n${info}`); + } + + return shader; +} +``` \ No newline at end of file diff --git a/.planning/references/feishu-teaching-docs/11.md b/.planning/references/feishu-teaching-docs/11.md new file mode 100644 index 0000000..9111125 --- /dev/null +++ b/.planning/references/feishu-teaching-docs/11.md @@ -0,0 +1,603 @@ +5.1 number 补充 + +本节课将对数字类型 `number` 相关知识做补充。 + +# 5.1.1 数字字面量 + +我们再重新复习一下数字字面量的声明,并对之前可能遗漏的知识点做一些补充。 + +## 普通数字 + +整数和浮点数使用正常的声明方式: + +```TypeScript +1; // 数字字面量 1 +2.2; // 数字字面量 2.2 +``` + +对于小数,还可以省略小数点前后的数字,省略前面表示 `0.x`,省略后面表示 `x.0`: + +```TypeScript +.2; // 数字字面量 0.2 +2.; // 数字字面量 2.0,与 2 完全相同 +``` + +这两种方式一般不常用,容易引起误解,可读性也差。 + +还可以使用指数形式声明,使用 `xxxxEn` 的形式: + +```TypeScript +1e10; // 10 ** 10 +1.2E5; // 1.2 * (10 ** 5) +2.5E+4; // 2.5 * (10 ** 4) +5e-12; // 5 * (10 ** -12) +3.e3; // 3 * (10 ** 3) +``` + +还有 `0x` `0b` `0o` 分别表示十六进制、二进制、八进制: + +```TypeScript +0xffee; // 十六进制 FFEE +0xAbCd; // 十六进制 ABCD +0b1010; // 二进制 1010 +0b1111; // 二进制 1111 +0o1234; // 八进制 1234 +0o7777; // 八进制 7777 +``` + +十六进制、二进制、八进制无法声明浮点数。 + +非严格模式下,以 `0` 开头的数字也是八进制,但我们的教程遵循严格模式,因此这里不需要记住。 + +使用下划线可以分割数字使数字可读性更高: + +```TypeScript +123_456; // 等价于 123456 +12.34_666_7; // 等价于 12.346667 +0b1001_0011; // 等价于 0b10010011 +0xffff_ee_ee; // 等价于 0xffffeeee +``` + +## 特殊数字 + +除了一般的整数和浮点数,还有两个特殊的数字 `Infinity` `NaN`,分别表示无穷大和不是数字: + +```TypeScript +NaN; // 表示不是数字(Not a Number) +Infinity; // 表示无穷大 +``` + +这两个特殊数字中,`Infinity` 可以直接判等,而 `NaN` 无法直接判等,判等结果一定是 `false`: + +```TypeScript +NaN === NaN; // false +Infinity === Infinity; // true +``` + +`NaN` 判等需要使用 `Object.is`: + +```TypeScript +Object.is(NaN, NaN); // true +Object.is(Infinity, Infinity); // true +``` + +# 5.1.2 数值运算补充 + +## 浮点数存储 + +`IEEE 754` 标准定义了 8 位、 16 位、32 位、64 位浮点数的存储方式,每种浮点数的格式是相同的,都包含符号位、底数位、指数位三部分。拿 64 位浮点数举例,它包含一个符号位、52 个底数位、11 个指数位,图示如下: + + + +最终其值将会是 $s\times n\times 2^e$,其中 $s$ 表示符号位,$n$ 表示底数位,$e$ 表示指数位,注意指数位自身还包含一个符号位,因此指数的有效位数是 10。底数位全部描述小数,即如果指数位是 0,那么浮点数的值不大于 1。 + +因此,64 位浮点数最大可以表示 52 位整数(全部使用底数位),这也是为什么 `Number.MAX_SAFE_INTEGER` 是 $2^{53}-1$。 + +我们也可以推断出它最大可以存储的数据是 $2^{1024}$,即指数位全部占满。 + +## 浮点误差 + +计算浮点数时,有可能产生误差,这是计算机的结构及 `IEEE 754` 规范所决定的,无法解决。如果我们尝试在控制台输入 `0.1 + 0.2`,会得到 `0.30000000000000004` 的结果,而不是 `0.3`。 + +具体来说,由于计算机使用二进制,必然会有一些在十进制下是有限小数的数无法表示为二进制的有限小数。举例来说,对于 $\frac{1}{3}$,它在三进制下可以表示为 `0.1`,但是在十进制下就无法精确表示,因为它是一个无限小数,在运算时只能取后面的几位小数去运算,这样就会产生误差了。 + +在浮点数计算时也是这样,十进制的 `0.1` 和 `0.2` 在二进制下是无限小数,无法精确表示,最后结果也就产生了误差。 + +我们基本上不会对浮点数进行判等,因此我们不必过于在意浮点误差。如果需要浮点数判等,基本可以说明你的代码设计有些问题。虽说有些不得不执行浮点判等的场景,但是极其少见,在学习阶段完全避免浮点判等就可以了。 + +我们有一些办法可以在一定程度上避免浮点误差,但是场景很少见,我们也先不讲解了。 + +## 特殊数值的运算 + +对于 `NaN` 来说,几乎所有的数字与 `NaN` 执行任何运算的结果都是 `NaN`: + +```TypeScript +NaN * 0; // NaN +NaN / 12; // NaN +NaN ** 3; // NaN +NaN - 3; // NaN +NaN + 1; // NaN +``` + +除了 `NaN ** 0`: + +```TypeScript +NaN ** 0; // 结果是 1,是唯一一种可以把 NaN 仅通过数学运算变为非 NaN 的方法 +``` + +这些运算可能产生 `NaN`: + +```TypeScript +0 / 0; // NaN +0 * Infinity; // NaN +Infinity / Infinity; // NaN +Infinity - Infinity; // NaN +``` + +在运算时与非数字类型运算,如果非数字类型无法转换为数字类型,结果也可能会是 `NaN`: + +```TypeScript +12 - 'abc'; // NaN +2.4 * 'ccc'; // NaN +72 * {}; // NaN +``` + +这些东西大致了解就行,没必要全记住,基本上用不到。 + +# 5.1.3 特殊数值判断 + +## 大小判断 + +`NaN` 与任何数字判断关系的结果都是 `false`: + +```TypeScript +12 < NaN; // false +12 > NaN; // false +12 <= NaN; // false +12 >= NaN; // false +``` + +`Infinity` 判断关系如下代码所示: + +```TypeScript +12 < Infinity; // true +Infinity < Infinity; // false +Infinity > Infinity; // false +Infinity >= Infinity; // true +Infinity <= Infinity; // true +-Infinity < Infinity; // true +``` + +这些东西大致了解就行,没必要全记住,基本上用不到。 + +## `NaN` 判断 + +判断一个数是否是 `NaN` 使用 `Number.isNaN` 或 `isNaN`,二者的类型声明一致: + +```TypeScript +function isNaN(num: any): boolean; +``` + +对于 `Number.isNaN`,如果输入的参数不是数字类型,则返回 `false`,如果是数字类型,再判断其是否是 `NaN`,返回判断结果。 + +对于 `isNaN`,如果输入的参数不是数字类型,会先使用 5.1.5 节(本节后续内容)中的 `Number` 方法转换为数字后,再判断是否是 `NaN`,返回判断结果。 + +不过我们并不需要过于关注这两个方法的差距,在使用 ts 写代码时,并不会出现类型错误的情况,一般使用 `isNaN` 就可以了。 + +示例如下: + +```TypeScript +isNaN(100); // false +isNaN('100'); // false +isNaN('abc'); // true +isNaN(NaN); // true; +Number.isNaN('100'); // false +Number.isNaN(NaN); // true +Number.isNaN('abc'); // false +``` + +除了这两种方法,还可以用 `Object.is` 判断,我们在 5.1.1 也已经讲了,这种方法相对少见: + +```TypeScript +Object.is(NaN, NaN); // true +``` + +## `Infinity` 判断 + +判断数字是否是 `Infinity` 或 `-Infinity` 使用 `isFinite` 或 `Number.isFinite` 方法: + +```TypeScript +function isFinite(num: number): boolean; +``` + +如果 `num` 是 `Infinity` `-Infinity` 或 `NaN`,函数将会返回 `false`,其他情况返回 `true`。这两者的区别与 `isNaN` 和 `Number.isNaN` 的区别一致,不再过多讲解。示例如下: + +```TypeScript +isFinite(100); // true +isFinite(Infinity); // false +isFinite('100'); // true +isFinite('abc'); // false +Number.isFinite(100); // true +Number.isFinite(Infinity); // false +Number.isFinite('100'); // false +Number.isFinite('abc'); // false +``` + +# 5.1.4 数字转字符串 + +数字转字符串一般会使用 `String` `toString` `toExponential` `toPrecision` `toFixed` 接口。 + +## `String` + +`String` 是一个将指定数据转换为字符串的接口。而自然,它可以把数字转为字符串: + +```TypeScript +const str1 = String(1.1); // 字符串 '1.1' +const str2 = String(2); // 字符串 '2' +``` + +这个方法不仅可以转换数字,任何数据类型都可以转换,我们在之后将会详细说明。 + +注意这种转换方法只会看数字的值,并不会因为你写好几个 0 而导致最终字符串也有好几个 0: + +```TypeScript +const str = String(1.0000000); // 结果依然是 '1' +``` + +## `toString` + +这是字符串转数字最常用的方法之一,类型声明如下: + +```TypeScript +function toString(radix?: number): string; +``` + +这里的 `radix` 可选,表示输出进制,可以是 2-36 进制。填写除此之外的进制会报错。默认使用十进制。 + +例如: + +```TypeScript +const num1 = 12; +const num2 = 12.25; +const str1 = num1.toString(); // '12' +const str2 = num2.toString(); // '12.25' +const str3 = num1.toString(13); // 'c',对于大于 10 的进制结果一定是小写 +const str4 = num2.toString(4); // '30.1' +``` + +需要注意的是,数字字面量的第一个 `.` 一定会被识别为小数点,因此如下写法是错误的: + +```TypeScript +2.toString(); +12.toString(); +``` + +如果想对整数字面量执行 `toString`,那么可以加括号,或者再加个点,浮点数可以直接调用: + +```TypeScript +2..toString(); // '2' +(3).toString(); // '3' +3.2.toString(); // '3.2' +``` + +如果是负数的话,就必须加括号了,因为一元减的优先级高于成员运算符: + +```TypeScript +-2.3.toString(); // -2.3 数字 +(-2.3).toString(); // '-2.3' 字符串 +``` + +`toString` 方法与 `String` 在 0 的表现上一致,并不会因为你写好几个 0 而导致最终结果也有好几个 0。 + +## `toExponential` + +这个方法允许你把数字转为字符串,同时使用指数形式: + +```TypeScript +function toExponential(digits?: number): string; +``` + +其中 `digits` 参数表示保留几位小数,不填时表示有多少位保留多少位。 + +```TypeScript +3.2.toExponential(); // '3.2e+0' +0.0002345.toExponential(); // '2.345e-4' +123456789.toExponential(3); // '1.235e+8',保留三位小数 +``` + +## `toFixed` + +这个方法允许你将数字转为字符串,同时保留指定位数的小数: + +```TypeScript +function toFixed(digits?: number): string; +``` + +参数 `digits` 表示保留几位小数,不填时表示不保留,范围需要在 `0 ~ 100` 之间。 + +```TypeScript +3.2.toFixed(3); // '3.200' +12.3456.toFixed(2); // '12.35' +``` + +不建议保留过高的位数,因为可能会因为浮点误差导致结果出错: + +```TypeScript +0.3.toFixed(50); // '0.29999999999999998889776975374843459576368331909180' +``` + +## `toPrecision` + +该方法会把数字四舍五入到指定有效数字,与 `toFixed` 类似: + +```TypeScript +function toPrecision(precision?: number): string; +``` + +参数 `precision` 表示有效数字位数。示例如下: + +```TypeScript +12.34567.toPrecision(4); // '12.35' +2345.34.toPrecision(2); // '2.3e+3' 有可能返回指数形式 +0.0004.toPrecision(3); // '0.000400' +``` + +## 其他方法 + +除了这些方法,还有一些其他的方法可以将数字转为字符串,但它们大多语义不清晰,或是性能较差,不建议使用。 + +```TypeScript +123 + ''; // 与空字符串相加转为字符串 +'' + 123; // 与空字符串相加转为字符串 +123 + []; // 与空数组相加转为字符串 +[] + 123; // 与空数组相加转为字符串 +`${123}`; // 直接使用模板字符串转为字符串 +``` + +模板字符串虽然比较常用,但是仅用于把数字转为字符串并不是一个好选择。 + +# 5.1.5 字符串转数字 + +字符串转数字一般会使用 `parseInt` `parseFloat` `Number` 等方法。 + +## `+` 运算符 + +我们可以简单地在字符串前面加一个一元加运算符来把字符串转换为数字。这种方法语义虽然不那么清晰,但是性能最佳,在高性能需求的场景下一般使用此方法: + +```TypeScript ++'234'; // 数字 234 ++'3e12'; // 数字 3e+12 +32 + +'16'; // 数字 48 ++'0x12'; // 数字 18 ++'-123'; // 数字 -123 +``` + +如果不能转换,结果会是 `NaN`: + +```TypeScript ++'abc'; // NaN +``` + +需要注意的是,此方法不能转换那些包含分隔符的数字: + +```TypeScript ++'123_456'; // NaN +``` + +空字符串会转换为 `0`: + +```TypeScript ++''; // 0 +``` + +## `Number` + +此方法的行为与 `+` 运算符一致,但是语义更清晰: + +```TypeScript +Number('123'); // 数字 123 +Number('abc'); // NaN +Number('0x12'); // 数字 18 +``` + +## `parseInt` + +此方法可以用于把一个整数字符串转换为数字: + +```TypeScript +function parseInt(string: string, radix?: number): number; +``` + +### 基本功能 + +可以将非指数形式的字符串转换为整数: + +```TypeScript +parseInt('100'); // 数字 100 +parseInt('-12345'); // 数字 -12345 +``` + +填写 `radix` 参数表示指定字符串的进制,范围 `2 ~ 36`,例如: + +```TypeScript +parseInt('10', 2); // 2 +parseInt('32', 8); // 26 +parseInt('0xF', 16); // 15 +``` + +如果不填 `radix`,且字符串以 `0x` 开头,依然会被认为是十六进制: + +```TypeScript +parseInt('0xFF'); // 255 +``` + +对于以 `0` 开头的字符串,有可能被识别为八进制,也可能被识别为十进制,虽然 `ES5` 规范要求需要被识别为十进制,但是由于历史原因,依然有浏览器可能识别为八进制。 + +注意,`parseInt` 只能识别 `0x` 或 `0X` 作为十六进制,但是无法识别二进制、八进制等前缀。 + +### 空格表现 + +如果字符串前后包含空格,那么可以正常转换: + +```TypeScript +parseInt(' 123'); // 123 +parseInt('123 '); // 123 +parseInt(' 123 '); // 123 +``` + +### 非数字表现 + +在移除空格后,如果第一个字符不能被识别为指定进制的数字,那么将会返回 `NaN`: + +```TypeScript +parseInt('a'); // NaN +parseInt('23', 2); // NaN,因为二进制不包含数字 2 +parseInt('GF', 16); // NaN,因为十六进制不包含数字 G +``` + +如果第一个字符可以被识别为指定进制的数字,那么会依次向后解析,直到遇到了一个不能被识别的字符,将前面的内容转换为数字并返回: + +```TypeScript +parseInt('123abc'); // 123,十进制不包含 a,因此解析到 123 就结束了 +parseInt('640px'); // 640 +parseInt('123e12'); // 123,不能解析指数形式 +parseInt('1.23'); // 1,仅解析整数 +``` + +### 其他行为 + +如果传入的参数不是数字类型,会先将它转换为字符串类型,再执行解析操作。因此,如果你传入了一个数字类型的参数,那么结果可能就会比较奇怪: + +```TypeScript +parseInt(0.000004); // 0 +parseInt(0.0000004); // 4,数字被转换为字符串的 '4e-7' +``` + +但不能解析指数形式并不意味着遇到 `e` 就会停,如果使用 15 进制以上的进制转换,依然会被识别: + +```TypeScript +parseInt('0e0', 16); // 224 +parseInt('1e+3', 16); // 30,解析 '1e' 为十六进制 +``` + +## `parseFloat` + +`parseFloat` 用于将浮点数字符串转换为数字: + +```TypeScript +function parseFloat(string: string): number; +``` + +它的表现与 `parseInt` 基本一致,不过可以识别指数和小数,但是无法指定进制。 + +它的空格表现及非数字表现与 `parseFloat` 一致。 + +```TypeScript +parseFloat('123'); // 123 +parseFloat('1.23'); // 1.23 +parseFloat('1.23e4'); // 12340 +parseFloat(' 123 '); // 123 +parseFloat('123px'); // 123 +``` + +# 5.1.6 二进制存储布尔值 + +在 js 中,位运算符可以操作 32 位整数,我们可以把 32 位整数的每一位作为一个布尔值使用,使用 `1` 代表 `true`,使用 `0` 代表 `false`。例如 `0b0101` 表示第一位是 `true`,第二位是 `false` ...,这要比使用数组 `[true, false, true, false]` 快得多。 + +## 状态判断 + +例如,在我们常用的自动元件中,每个自动元件可能会与周围一圈建立连接,也就有八个不同的连接状态,我们就可以使用一个八位二进制数来表示。假如设左上方为最高位,顺时针旋转位次依次降低,那么我们可以使用位运算判断: + +```TypeScript +const connection = 0b0101_0101; // 连接情况 +if (connection & 0b0000_0001) {} // 如果最低位是 1,即如果与左侧连接 +if (connection & 0b0000_0011) {} // 如果最低位或次低位是 1,即如果与左侧或左下侧连接 +if (connection & 0b0000_0011 === 0b0000_0011) {} // 如果最低位和次低位都是 1,即如果与左侧和左下侧都连接 +// 其他判断... +``` + +在判断状态时,此方式要远比使用数组或是对象存储更快,因为它是直接的硬件底层运算。在后续的学习中我们会时不时地遇见数字的这种使用方式。 + +## 状态修改 + +可以使用 `|` 及 `& ~` 设置状态: + +```TypeScript +let connection = 0b0000_0000; +connection |= 0b0010_0000; // connection 会变为 0b0010_0000 +connection |= 0b1101_0100; // connection 会变为 0b1111_0100 +connection &= ~0b0100_0000; // connection 会变为 0b1011_0100 +``` + +## 位移操作 + +可以使用位移操作来执行状态修改等操作: + +```TypeScript +let connection = 0b0000_0000; +connection |= 1 << 2; // connection 会变为 0b0000_0100 +connection |= (1 << 3) | (1 << 4); // connection 会变为 0b0001_1100 +connection &= ~(1 << 3); // connection 会变为 0b0001_0100 +``` + +# 5.1.7 布尔值转数字 + +我们可以将 `true` 转换为 `1`,把 `false` 转换为 `0`,这在使用数字存储布尔值时非常有用。我们可以通过一元加运算符或 `Number` 进行转换: + +```TypeScript ++true; // 1 ++false; // 0 +Number(true); // 1 +Number(false); // 0 +``` + +或者使用三元运算符: + +```TypeScript +const bool = true; +bool ? 1 : 0; // 1 +``` + +三种方法中,使用 `+` 一元加运算符是最快的,但是语义可能不清晰。如果不需要最好的性能,建议使用 `Number` 方法转换。 + +# 5.1.8 `0` 与 `-0` + +在 js 中,0 与 -0 是不一样的,虽然他们在数学运算与比较中完全一致,但是他俩确确实实是两个不同的数!判断 0 与 -0 只能通过 `Object.is` 判断: + +```TypeScript +Object.is(0, -0); // false +Object.is(-0, -0); // true +Object.is(0, 0); // true +0 === -0; // true +0 === 0; // true +-0 === -0; // true +``` + +想要构造出 -0,一般只能通过直接写出来,或是使用一元减运算符: + +```TypeScript +-0; // -0 ++'-0'; // -0 +-'0'; // -0 +-''; // -0 +-(1 - 1); // -0 +``` + +这个东西完全没有任何用处!也不需要记! + +# 5.1.9 课后习题 + +给出下列表达式的值: + +```TypeScript +parseInt(true); +Number.isNaN(false); +parseInt('123 45'); +Number('0b1011'); +'123' + +'123'; +123..toExponential(); +parseFloat('0xfff'); +parseInt('0b1011'); +NaN === NaN; +isFinite(Infinity); +``` \ No newline at end of file diff --git a/.planning/references/feishu-teaching-docs/12.md b/.planning/references/feishu-teaching-docs/12.md new file mode 100644 index 0000000..61cc5e3 --- /dev/null +++ b/.planning/references/feishu-teaching-docs/12.md @@ -0,0 +1,751 @@ +5.2 string 补充 + +本节课对字符串类型 `string` 做复习以及补充。 + +# 5.2.1 字符串字面量 + +本小节对字符串字面量的声明做复习,并对之前课程可能遗漏的内容做补充。 + +## 普通字符串 + +普通字符串使用单引号或双引号声明,二者没有任何区别,我们建议使用单引号,因为输入的时候不需要按 Shift 键: + +```TypeScript +'abc'; // 单引号 +"abc"; // 双引号,与单引号没有任何区别 +``` + +单引号声明的字符串内不允许出现单引号,双引号同理: + +```TypeScript +'I'm happy' +"He says "..."" +``` + +这样的话引号会就近匹配,于是就会引起错误。 + +不过单引号内可以出现双引号,双引号内也可以出现单引号: + +```TypeScript +"I'm happy"; // 没有问题 +'He says "..."'; // 没有问题 +``` + +如果你真的要在单引号内写单引号,双引号内写双引号,可以使用转义字符: + +```TypeScript +'I\'m happy'; +"He says \"...\""; +``` + +## 模板字符串 + +模板字符串使用反引号 \` 声明,反引号内可以换行: + +```TypeScript +`第一行 +第二行 +第三行`; +``` + +模板字符串在换行时会保留缩进: + +```TypeScript +`第一行 + 第二行,前面空四格 +`; +``` + +模板字符串内可以使用 `${}` 嵌入表达式,内容会自动转为字符串。 + +```TypeScript +`数字:${123},字符串:${'abc'},布尔值:${true}`; +``` + +## ASCII 解析 + +字符串内允许使用 `\x` 来声明 ASCII 码。例如字母 `a` 对应的 ASCII 码为 61,其十六进制为 ,那么可以这么写: + +```TypeScript +'\x61'; // 字母 a +"\x61"; // 字母 a +`\x61`; // 字母 a +``` + +但是注意不能动态拼接: + +```TypeScript +'\x' + '97'; // 会报错! +`\x${97}`; // 会报错! +``` + +# 5.2.2 Unicode 码 + +> 这一节相对不那么重要,但是如果想要深入理解字符串的话,这一节是必看的。如果只是做一些非常简单的工作,这一节不看也行。 + +Unicode 码是全球通用的字符码,包含了目前世界上的几乎所有文字和字符。它包含基础平面与若干额外平面,基础平面中多是常见的字符,例如英文字符、中日韩字符(CJK字符)、部分常用的 `emoji` 等。而额外平面则会包含一些不那么常用的字符,例如一些罕见的古文字、部分 `emoji` 等。 + +对于基础平面的字符,会使用四个十六进制数表示,对于额外平面的字符,会使用五个十六进制数表示。我们称基础平面和额外平面的单个字符叫做码元。 + +Unicode 码兼容 ASCII 码,因此 ASCII 可以直接转换为 Unicode。 + +下面讲一下如何在 js 中使用 Unicode 码。 + +## Unicode 解析 + +在字符串中以 `\u` 开头,并紧跟着四个十六进制数,或是跟上花括号,花括号内写上一至五个十六进制数即可,注意 `\u` 后面不加花括号的话必须跟四个,否则会报错: + +```TypeScript +'\u0061'; // 字母 a +"\u0061"; // 字母 a +`\u0061`; // 字母 a +'\u{0061}'; // 字母 a +"\u{61}"; // 字母 a +``` + +来看一个中文的例子,以汉字 `魔` 为例,它的 unicode 码为 `9b54`,因此可以这么写: + +```TypeScript +'\u9b54'; // 汉字 魔 +"\u9B54"; // 汉字 魔 +'\u{9B54}'; // 汉字 魔 +``` + +额外屏幕的 unicode 比较少见,一般是 emoji 或者特殊符号。例如对于一个神秘的表意文字 `𐂣`,其 Unicode 码为 `100a3`,如果我们如果使用 Unicode 声明它,那么需要使用 `\u{xxxxx}` 的形式,不能用 `\uxxxxx` 的形式: + +```TypeScript +'\u{100a3}'; // 𐂣 +'\u100a3'; // ည3,\u100a 被视为了 ည,后面的 3 单独就是一个字符 +``` + +与 ASCII 同样,Unicode 也不能动态组合: + +```TypeScript +'\u' + '0061'; // 会报错! +``` + +## 在代码中使用 Unicode + +除了字符串内,代码中也可以使用 Unicode,例如: + +```TypeScript +const \u{61} = 10; // 将 10 赋给常量 a +``` + +这个东西不太可能见得到,没必要记住,知道能这么干就行。 + +## 特殊 Unicode + +除了基础平面和额外平面,Unicode 中还包含一些特殊行为的字符,它们要求多个码元组合到一起。这种字符多是 `emoji`,例如对于 emoji 😄,它由两个码元 `\uD83D\uDE04` 组成。 + +要判断是否要组合,需要看第一个码元是什么,如果第一个码元是处在 `\uD800` 和 `\uDBFF` 之间的话,就会和后续码元一起解析组合。例如 `\uD842\uDFB7` 会解析出 `𠮷` 字,`\uD83D\uDE04` 会解析出 😄 等。 + +实际上 `emoji` 可以使用一系列连续的 Unicode 码组合到一起形成不同的颜色,甚至是直接组合。有时候我们看到有机器人可以把几个 `emoji` 组合成一个新的 `emoji`,实际上内部可能就是 Unicode 自身组合做到的。 + +除了上述组合方式,一些普通字符也可以与其他 Unicode 组合,例如数字和星号井号加上 `\ufe0f\u20e3` 就可以把它变成数字键帽 `emoji`: + +```TypeScript +[0, 1, 2, 3, 4, 5].map(num => num + '\ufe0f\u20e3'); +// ["0️⃣", "1️⃣", "2️⃣", "3️⃣", "4️⃣", "5️⃣"] +``` + +这些内容做了解即可,如果想深入了解可以看看这篇知乎文章:https://zhuanlan.zhihu.com/p/407013219 + +# 5.2.3 字符串拼接 + +字符串拼接有两种常用方法,第一种方法是使用 `concat` 接口,第二种方法是使用 + 运算符。 + +## `+` 运算符 + +多个字符串直接使用 + 连接就可以拼接在一起: + +```TypeScript +'abc' + 'def'; // 'abcdef' +'123' + '456' + '789'; // '123456789' +``` + +## `concat` 接口 + +`concat` 是字符串的一个方法,允许将多个字符串与一个字符串拼接到一起。其类型声明如下: + +```TypeScript +function concat(...strs: string[]): string; +``` + +例如: + +```TypeScript +'abc'.concat('def'); // 'abcdef' +'abc'.concat('def', 'ghi'); // 'abcdefghi' +'123'.concat('456', '789', '123'); // '123456789123' +``` + +这种方法由于写起来会比较麻烦,所以使用场景较少。多数情况下我们会使用 + 运算符连接字符串。 + +## `join` 接口 + +`join` 是数组的一个方法,可以把数组的每一项转换成字符串并且使用指定字符串连接在一起。这一接口已经在数组这一节中讲过,这里仅做回忆。 + +```TypeScript +[1, 2, 3].join('+'); // 1+2+3 +[1, 2, 3].join(); // 123 +``` + +`join` 方法多在不定长内容字符串拼接以及内容较多时使用,其使用场景较少,不过还是需要了解这一接口的。 + +关于 `join` 方法的更多其他特性,我们会在数组补充中再做讲解。 + +# 5.2.4 字符串性能与规范问题 + +虽然字符串的性能很好,但是相比于数字类型和布尔值,它就相当慢了,因为字符串实际上相当于一个字符数组,数组操作并不快。因此我们建议非必要时不使用字符串,尤其是在 `Map` 映射中。 + +我们有时还会使用正则表达式匹配字符串,这写起来非常方便,但是正则表达式的速度其实很慢,在一些简单场合当然可以使用,而在对性能要求较高的场合就会严重拖慢速度了。 + +例如,在魔塔中,我们可能会建立一个映射,以图块 `id` 为键,其他内容为值,其实这么做并不好,更好的做法是以图块数字为键,其他内容为值,数字做映射要远比更快。 + +而如果要罗列一系列数据,更建议用枚举,例如对于朝向,使用 `left` `right` 等字符串就是不好的写法,而使用枚举就是更好的写法: + +```TypeScript +const enum FaceDirection { + Unknown, + Left, + Up, + Right, + Down, + LeftUp, + RightUp, + LeftDown, + RightDown +} +``` + +一般我们使用字符串只有如下场景: + +- 要给用户展示文字 +- 必须使用字符串存储的数据,如用户名、助记符等 +- 浏览器内部接口要求必须使用字符串 + +其他场景下很少会有使用字符串的需求。 + +# 5.2.5 字符串长度 + +可以通过字符串的 `length` 属性获取字符串的长度: + +```TypeScript +'abcde'.length; // 5 +'123'.length; // 5 +``` + +字符串的 `length` 属性是只读属性,不可修改,如果强行赋值,那么会报错。 + +需要注意的是,字符串的长度并不一定等于字符数量,例如使用 5.2.2 中讲到的组合 Unicode 时,这些文字可能会包含多个码元,那么 `length` 属性就会计数多次: + +```TypeScript +'😄'.length; // 2 +``` + +# 5.2.6 字符串索引 + +## 使用索引运算符 + +与数组类似,字符串可以直接使用方括号索引: + +```TypeScript +'abcde'[3]; // 'd' +'12345'[2]; // '3' +``` + +需要注意的是,字符串的索引是只读的,不可以修改,如果使用等号赋值,那么会赋值失败,同时不会报任何错误: + +```TypeScript +let a = 'abcde'; +a[1] = 'f'; // 这句赋值会返回 'f',是赋值运算符的返回值 +a; // 但是这里还是 'abcde' +``` + +这是因为字符串并不是引用类型,它是一个字面量类型,当创建完毕后就无法修改了,除非创建一个新的字符串。如果需要修改字符串的某一项,可以使用 `slice` 方法(在后文讲解): + +```TypeScript +const a = 'abcde'; +a.slice(0, 1) + 'f' + a.slice(2); // 'afcde' +``` + +但是这种行为非常少见,应该不会遇到这种需求。 + +## 使用 `at` 接口 + +与数组类似,字符串也有 `at` 方法,它的功能与数组也类似,在直接索引的基础上允许填入负数从结尾开始索引: + +```TypeScript +'abcde'.at(-1); // 'e' +'abcde'.at(4); // 'e' +``` + +## 使用 `charAt` 接口 + +`charAt` 接口与直接使用索引运算符索引基本一致,直接填入索引: + +```TypeScript +'abcde'.charAt(0); // 'a' +'abcde'.charAt(4); // 'e' +``` + +如果超出了字符串的范围,那么会返回一个空字符串: + +```TypeScript +'abcde'.charAt(-1); // '' +'abcde'.charAt(5); // '' +``` + +如果不填写参数,会获取索引为 0 的字符: + +```TypeScript +'abcde'.charAt(); // 'a' +``` + +## 特殊行为 + +> 这一节简单了解即可,基本上一辈子碰不到 + +对于 5.2.4 中讲到的占据多个码元的字符,使用如上三个方式都不会获取到完整字符,而是会获取到对应字符的两个码元: + +```TypeScript +'😄'[0]; // '\uD83D' +'😄'[1]; // '\uDE04' +'1️⃣'.charAt(0); // '1' +'1️⃣'.charAt(1); // '\uFE0F' +'1️⃣'.at(2); // '\u20E3' +``` + +要获取码元数量是 2 的字符,可以使用迭代器: + +```TypeScript +const arr = [...'😄123'] +arr[0]; // '😄' +arr[1]; // '1' +``` + +但是对于码元数量超过 2 的字符,依然不能正确识别: + +```TypeScript +[...'1️⃣']; // ['1', '️', '⃣'] +``` + +对于这种码元数量超过 2 的字符并没有简单的方式获取到,但是这种场景极其少见,需要使用相应的第三方库实现,我们也不再讲解了。 + +# 5.2.7 字符串遍历 + +一般使用 `for` 循环遍历: + +```TypeScript +const str = 'abcde'; +for (let i = 0; i < str.length; i++) { + console.log(str[i]); // 依次输出 'a' 'b' 'c' 'd' 'e' +} + +for (const char of str) { + console.log(char); // 依次输出 'a' 'b' 'c' 'd' 'e' +} +``` + +# 5.2.8 字符串处理接口 + +下面讲解一下字符串中常用的处理接口。 + +## 去除空格 + +去除空格使用 `trim` 系列接口,`trim` 系列包含 `trim` `trimStart` `trimEnd` 三个接口,作用分别是去除字符串前后的空格,去除字符串前的空格,去除字符串后的空格: + +```TypeScript +' abcde '.trim(); // 'abcde' +' abcde '.trimStart(); // 'abcde ' +' abcde '.trimEnd(); // ' abcde' +``` + +## 大小写转换 + +大小写转换会使用 `toLowerCase` 和 `toUpperCase` 接口: + +```TypeScript +'abcde'.toUpperCase(); // 'ABCDE' +'ABCde'.toLowerCase(); // 'abcde' +``` + +## 字符串裁剪 + +字符串裁剪常用 `slice` 和 `substring`,二者几乎没有区别,我们建议使用 `slice` 而不是 `substring`。`slice` 的定义如下: + +```TypeScript +function slice(start?: number, end?: number): string; +``` + +- `start`: 裁剪起始索引,裁剪结果包含此索引。 +- `end`:裁剪终止索引,裁剪结果不包含此索引。 + +这两个参数都可以填负数,如果填负数的话会从结尾开始索引。如果起始索引大于终止索引,那么会返回一个空字符串。示例如下: + +```TypeScript +'abcde'.slice(); // 'abcde' +'abcde'.slice(1); // 'bcde' +'abcde'.slice(1, 3); // 'bc' +'abcde'.slice(-2, -1); // 'e' +'abcde'.slice(4, 1); // '' +``` + +而对于 `substring`,如果起始索引大于终止索引,那么会交换两者,并不会返回空字符串,且负数参数视为 0: + +```TypeScript +'abcde'.substring(4, 1); // 'bcd' +'abcde'.substring(-2, -1); // '',负数参数视为 0,所以相当于 substring(0, 0) +``` + +## 前后填充 + +可以使用 `padStart` 和 `padEnd` 在字符串前后填充内容,它们的类型声明一样: + +```TypeScript +function padStart(targetLength: number, padString?: string): string; +``` + +当字符串长度大于等于 `targetLength` 时,会将字符串原样返回。如果字符串长度小于 `targetLength`,那么会在前方(`padStart`)或后方(`padEnd`)填充 `padString` 字符直到字符串长度等于 `targetLength`,然后将填充后的字符串返回。如果不填 `padString`,则视为空格。 + +示例如下: + +```TypeScript +'abc'.padStart(5, 'a'); // 'aaabc' +'abc'.padEnd(5, 'a'); // 'abcaa' +``` + +## 字符串重复 + +使用 `repeat` 接口重复一个字符串若干次: + +```TypeScript +function repeat(count: number): string; +``` + +`count` 表示重复次数。例如: + +```TypeScript +'abc'.repeat(3); // 'abcabcabc' +``` + +## 字符串分割 + +使用 `split` 将字符串按照指定内容将字符串分割成一个数组。其类型声明如下: + +```TypeScript +function split(pattern: string | RegExp, limit?: number): string[]; +``` + +- `pattern`:指字符串应该在哪里分割,可以填字符串,说明按照这个字符串分割;也可以填正则表达式,会按照匹配到的正则分割。 +- `limit`:最多分割几次,在分割这么多次之后忽略后面的内容。 + +文字描述可能不那么直观,看例子: + +```TypeScript +'abc|bcd|def'.split('|'); // ['abc', 'bcd', 'def'] +'abc|bcd|def'.split('|', 2); // ['abc', 'bcd'],第二个 '|' 后面的内容被忽略 +'abc,bcd|def/efg\fgh'.split(/[,|/\\]/); // ['abc', 'bcd', 'efg', 'fgh],使用正则表达式分割 +``` + +# 5.2.9 字符串判断 + +字符串判断分为相等、大于、小于、包含、开头、结尾几种类型。 + +## 字符串判等 + +字符串判等使用等于运算符 `===`: + +```TypeScript +'abc' === 'abc'; // true +'abc' === 'bcd'; // false +``` + +当然使用弱等于 `==` 也行,但是弱等于在几乎所有情况下都不推荐使用。 + +## 大小比较 + +字符串之间可以使用 `>` `<` `>=` `<=` 比较大小,比较时会比较第一位字符的 Unicode 值,如果相等再比较后续的字符。例如: + +```TypeScript +'cde' > 'b'; // true,第一个字符 c 的 Unicode 大于 b +'bbb' > 'bab'; // true,第二个字符 b 的 Unicode 大于 a +``` + +## 包含判断 + +包含判断可以使用 `includes` `indexOf` `lastIndexOf` 三个方法,与数组的用法基本一致。 + +`includes` 用于判断是否包含一个字符串: + +```TypeScript +function includes(search: string, position?: number): boolean; +``` + +- `search`:要判断是否包含的字符串。不能填正则表达式。 +- `position`:从指定索引开始搜索,不填表示从头开始搜索。 + +`indexOf` 和 `lastIndexOf` 用于搜索指定字符串在当前字符串中的索引,它们的类型声明一致: + +```TypeScript +function indexOf(search: string, position?: number): number; +``` + +- `search`:要判断包含的字符串。不能填正则表达式。 +- `position`:对于 `indexOf`,表示从指定索引开始向后搜索;对于 `lastIndexOf`,表示从指定索引开始向前搜索。不论 `indexOf` 还是 `lastIndexOf`,这里的从指定索引开始搜索表示 `search` 的第一个字符从被搜索字符串的指定索引开始搜索,也就是: + + + +对于这两个接口,如果搜索到了,那么会返回对应的索引,否则返回 `-1`。 + +三个接口的示例如下: + +```TypeScript +'abcdefg'.includes('abc'); // true +'abcdefg'.includes('abc', 1); // false,从索引 1 开始搜索,搜索不到 +'abcdefg'.indexOf('cde'); // 2 +'abcdefg'.indexOf('cde', 3); // -1,搜索不到 +'abcdefg'.lastIndexOf('cde'); // 2,依然是从前往后数的索引,而不是从后往前数的索引 +'abcdefg'.lastIndexOf('cde', 2); // 2,从索引 2 开始向前搜索 +``` + +## 开头结尾判断 + +开头结尾判断使用 `startsWith` 和 `endsWith`,它们会判断字符串是否以指定字符串开头或结尾: + +```TypeScript +function startsWith(search: string, position?: number): boolean; +``` + +- `search`:要判断的字符串。不能填正则表达式。 +- `position`:字符串判断位置。对于 `startsWith`,表示第一个字符所在位置索引,对于 `endsWith`,表示最后一个字符所在位置索引+1,注意与 `indexOf` 和 `lastIndexOf` 的 `position` 参数区分。 + +示例如下: + +```TypeScript +'abcdefg'.startsWith('abc'); // true +'abcdefg'.startsWith('bcd'); // false +'abcdefg'.endsWith('efg'); // true +'abcdefg'.endsWith('cde', 5); // true,这里索引 5 对应 f,因此会判断索引 2,3,4 是否正好等于 'cde' +``` + +# 5.2.10 Unicode 接口 + +我们不仅可以使用 Unicode 直接编写字符串,还可以使用相应的接口来处理 Unicode 相关的内容。 + +## Unicode 获取 + +可以使用 `charCodeAt` 或 `codePointAt` 来获取指定索引的码元对应的 Unicode,它们的类型标注一致: + +```TypeScript +function charCodeAt(index?: number): number; +``` + +`index` 对应的是码元索引,方法会它会返回对应索引码元的 Unicode 值。 + +示例如下: + +```TypeScript +'a'.charCodeAt(0); // 97 +'a'.codePointAt(0); // 97 +``` + +这两个方法对于码元数不为 1 的字符处理不同,但是由于极其不常见,所以这里也不再讲解了。 + +## 根据 Unicode 生成字符 + +在前面我们讲到可以直接写 `\uxxxx` 或 `\u{}` 来生成对应 Unicode 的字符,但是这种写法不允许传入变量。如果我们需要传入变量,则需要用到 `String.fromCharCode` 或 `String.fromCodePoint` 接口,它们的类型标注一致: + +```TypeScript +function fromCharCode(...code: number[]): string; +``` + +示例如下: + +```TypeScript +String.fromCharCode(97, 98, 99); // 'abc' +String.fromCodePoint(97, 98, 99); // 'abc' +``` + +它们的区别与 `charCodeAt` 和 `codePointAt` 的区别类似,这里也不再讲解。 + +# 5.2.11 字符串匹配 + +字符串匹配包括 `match` `matchAll` `search` 三个字符串方法,以及 `RegExp.test` 和 `ResExp.exec` 两个正则表达式方法。 + +> 学习下面的内容之前必须先学习正则表达式,正则表达式在之前的课程中讲解过:https://h5mota.com/bbs/thread/?tid=1018&p=5#p58,务必看完再来看这一节。 + +## `RegExpExecArray` 接口 + +这个接口描述了正则匹配结果数组,它在字符串数组的基础上新增了一些属性。这个接口在后面的讲解中会用到,其部分类型声明如下,先看一眼就行: + +```TypeScript +interface RegExpMatchArray extends Array { + /** + * 描述了这一匹配项所在的索引 + */ + index?: number; + /** + * 被匹配的字符串字面量 + */ + input?: string; + /** + * 第一个匹配项,由于没匹配到的时候会返回 null,因此第 0 索引必定是存在的 + */ + 0: string; +} +``` + +## `match` 方法 + +`match` 方法用于直接匹配正则表达式,其类型声明如下: + +```TypeScript +function match(regexp: RegExp): RegExpExecArray | null; +``` + +当正则表达式不包含 `g` 修饰符时,如果没有搜索到,则会返回 `null`。如果搜索到了,那么返回结果的第 0 索引会是匹配到的字符串内容,后续内容是每一个捕获组(也就是正则表达式圆括号括起来的内容)对应的匹配内容。例如: + +```TypeScript +'abc'.match(/\d/); // null,字符串没有数字,匹配不到 +'abcdefg,hijklmn'.match(/^(\w+),\w*$/); // ['abcdefg,hijklmn', 'abcdefg'],索引 2 对应捕获组 (\w+) +``` + +同时这个数组还会包含上面讲到的属性: + +```TypeScript +'abcdefg,hijklmn'.match(/^(\w+),\w*$/); +// 数组内容 ['abcdefg,hijklmn', 'abcdefg'] +// 对象内容 { index: 0, input: 'abcdefg,hijklmn' },由于开头就匹配到了,所以 index 是 0。input 就是被匹配的原始字符串 +``` + +当正则表达式包含 `g` 修饰符时,如果没有搜索到,则会返回 `null`。如果搜索到了,那么会返回一个数组,包含每一个匹配项,不会包含捕获组,也不会包含 `index` `input` 这些属性,是一个纯净的数组: + +```TypeScript +'abcdefg'.match(/\w/g); // ['a', 'b', 'c', 'd', 'e', 'f', 'g'],纯净的数组,不包含额外属性 +``` + +## `matchAll` 方法 + +`matchAll` 方法的类型声明如下: + +```TypeScript +function matchAll(regexp: RegExp): Iterable; +``` + +这个方法要求正则表达式必须包含 `g` 修饰符,如果不包含,则会报错。 + +匹配结果是一个可迭代对象,这表明你可以通过 `for ... of` 循环或 `[...]` 扩散语法来遍历或转换为数组。匹配结果的每一项都是一个 `RegExpExecArray` 数组,这个数组的第 0 索引表示匹配到的完整字符串,后面的每一项表示每一个捕获组的内容,这与 `match` 不加 `g` 修饰符类似。 + +举例来说: + +```TypeScript +[...'abc,def,ghi,jkl'.matchAll(/(.{2})\w,/g)]; +// [ +// ['abc,', 'ab'], { index: 0, input: 'abc,def,ghi,jkl' } +// ['def,', 'de'], { index: 4, input: 'abc,def,ghi,jkl' } +// ['ghi,', 'gh'], { index: 8, input: 'abc,def,ghi,jkl' } +// ] +``` + +这里的结果可能不那么直观,可以好好想一想。 + +## `search` 方法 + +`search` 用于搜索第一个在字符串中匹配指定正则表达式的索引,类型声明如下: + +```TypeScript +function search(regexp: RegExp): number; +``` + +对于这个方法来说,正则表达式包含 `g` 修饰符与否不影响结果。返回结果是字符串中第一个匹配成功的索引,举例来说: + +```TypeScript +'abc,def'.search(/,.*/); // 4 +'abc,def,ghi'.search(/,.*/g); // 4,g 修饰符没有影响 +``` + +## `RegExp.test` 方法 + +用于判断一个字符串是否符合指定正则表达式的规则,这个是正则表达式对象上的方法,其类型声明如下: + +```TypeScript +function test(str: string): boolean; +``` + +举例来说: + +```TypeScript +;/\w+/.test('abcde'); // true,匹配成功,代码前面那个分号是为了让高亮正确,不用管 +/\d+/.test('abcde'); // false,匹配失败 +``` + +## `RegExp.exec` 方法 + +这个方法与 `match` 方法基本一致,但是由于正则表达式的内部状态等原因,并不推荐使用此方法。如果你想判断字符串是否匹配正则表达式,那么应该使用 `test` 方法,如果想匹配字符串内容,应该使用 `String.match` 方法,如果想获取索引,应该使用 `search` 方法。 + +由于其表现与 `match` 基本一致,这里也不再讲解了。 + +# 5.2.12 字符串替换 + +字符串替换会使用到 `replace` 和 `replaceAll` 方法。 + +## `replace` 方法 + +类型声明如下: + +```TypeScript +function replace(pattern: string | RegExp, replacement: string): string; +function replace(pattern: string | RegExp, replacement: (match: string, ...pn: string[], offset: number, string: number, groups?: { [key: string]: string }) => string): string; +``` + +这里我们着重讲解第一个方法,第二个方法比较复杂而且使用场景较少,之前简单讲过,这里也不再讲了,如果需要就自己查 mdn 吧。 + +- `pattern`:表示匹配方式,填字符串的时候表示把原始字符串的第一个 `pattern` 替换,填正则表达式时表示把匹配到的内容替换。如果正则表达式包含 `g` 修饰符,那么会把所有的匹配项都替换。 +- `replacement`:替换为的字符串。 + +`pattern` 填字符串时: + +```TypeScript +'Apples are round, and apples are juicy.'.replace('apples', 'oranges'); +// Apples are round, and oranges are juicy. +``` + +`pattern` 填正则表达式时,其基础用法为: + +```TypeScript +'Apples are round, and apples are juicy.'.replace(/apples/i, 'oranges'); // i 是大小写不敏感修饰符 +// oranges are round, and apples are juicy. +'Apples are round, and apples are juicy.'.replace(/apples/gi, 'oranges'); +// oranges are round, and oranges are juicy. +``` + +替换字符串还可以填写 `$1` 等表示捕获组,填写 `$&` 表示匹配内容等等: + +```TypeScript +'Apples are round, and apples are juicy.'.replace(/apples/i, '"$&"'); +// "Apples" are round, and apples are juicy. +'Apples are round, and apples are juicy.'.replace(/(apples)/i, '"$1"'); // $1 表示第一个捕获组 +// "Apples" are round, and oranges are juicy. +``` + +`replace` 还有很多用法,具体可以参考这篇 mdn 文档:[String.prototype.replace() - JavaScript | MDN](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/String/replace) + +## `replaceAll` 方法 + +`replaceAll` 方法一般用于字符串匹配的替换,很少使用正则表达式,因为正则表达式使用 `replace` 也可以实现。`replaceAll` 方法的类型声明与 `replace` 一致,这里也不再列出了。 + +`pattern` 填字符串时,它会把所有匹配项全部替换,而不是只替换第一个: + +```TypeScript +'apples are round, and apples are juicy.'.replaceAll('apples', 'oranges'); +// oranges are round, and oranges are juicy. +``` + +填正则表达式时,要求必须包含 `g` 修饰符,表现与 `replace` 完全一致: + +```TypeScript +'Apples are round, and apples are juicy.'.replaceAll(/apples/gi, 'oranges'); +// oranges are round, and oranges are juicy. +``` \ No newline at end of file diff --git a/.planning/references/feishu-teaching-docs/13.md b/.planning/references/feishu-teaching-docs/13.md new file mode 100644 index 0000000..b15fbfc --- /dev/null +++ b/.planning/references/feishu-teaching-docs/13.md @@ -0,0 +1,247 @@ +5.3 function 补充 + +本节课对 `function` 函数类型做复习以及补充。 + +# 5.3.1 函数声明复习 + +## 函数声明 + +我们依然先复习一下函数的声明方式。第一种方法是使用 `function` 关键字: + +```TypeScript +function myFunc(param1: type, param2: type, ...params: type[]): ReturnType { + // 这里写函数内容 +} +``` + +这里的 `param1` `param2` `...params` 就是函数参数,`ReturnType` 就是函数的返回值类型。 + +函数本身也是一个值,可以被变量、常量或对象的属性接收: + +```TypeScript +const myFunc = function() { + // 这里写函数内容 +} +``` + +在使用变量或常量接收时,我们更习惯使用箭头函数: + +```TypeScript +const myFunc = () => { + // 这里写函数内容 +}; +``` + +对于箭头函数,只有一个参数时可以省略括号,也可以省略花括号表示直接将表达式返回: + +```TypeScript +const myFunc = x => {}; // 只有一个参数时省略括号 +const myFunc = () => 1 + 2 + 3; // 省略花括号直接返回表达式 +const myFunc = x => x + 5; // 两个简化写法同时使用 +``` + +## 普通函数与箭头函数的区别 + +箭头函数与使用 `function` 关键字有两个关键区别: + +1. 箭头函数本身没有 `this` 指向,它会继承父作用域的 `this` 指向。这在传递回调函数的场景非常有用: + +```TypeScript +class MyClass { + count: number = 0; + myMethod() { + this.count = 0; + [1, 2, 3, 4].forEach(v => { + // 箭头函数里面直接写 this 就行 + this.count += v; + }); + [1, 2, 3, 4].forEach(function (v) { + // 但是 function 关键字声明的就不行,它有自己的 this 指向,在这个场景下会指向 undefined,于是会报错 + this.count += v; + }); + } +} +``` + +1. 箭头函数没有 `arguments`,想获取剩余参数只能通过 `...params` 声明参数。 + +# 5.3.2 声明规范 + +我们建议在编写函数时使用一定的规范,常见的有这几种规范: + +1. 所有函数都使用箭头函数。 +2. 在模块顶层的函数使用 `function` 关键字声明函数,其他函数使用箭头函数。 +3. 临时函数使用箭头函数,其他函数使用 `function` 关键字声明函数。 + +在新样板中,我们遵循了第二个规范,也就是说所有在模块顶层的函数都会使用 `function` 声明,包括导出的函数,而其他的函数全部使用箭头函数,包括函数内的函数、回调函数等。 + +# 5.3.3 返回值泄漏 + +使用箭头函数时,可能会出现返回值泄漏的情况。例如我们需要一个函数给一个变量赋值: + +```TypeScript +let a = 100; +const myFunc = x => a = x; +``` + +我们调用 `myFunc` 时会给变量 `a` 赋值,这个行为没什么问题。但是我们省略了花括号,所以这个函数会把 `a = x` 的返回值作为函数的返回值,这就引起了返回值泄漏。返回值泄漏大部分情况下没什么问题,但是在一些特定情况可能会造成一定的安全问题,因此建议这种纯副作用函数使用 `void` 关键字把返回值包裹: + +```TypeScript +let a = 100; +const myFunc = x => void(a = x); +``` + +`void` 关键字的作用在前面的课程中已经讲解到,作用是把紧跟着的表达式的返回值变为 `undefined`。这个圆括号并不是一定需要的,`void` 并不是一个函数,而是一个关键字,在优先级正确的前提下可以删除圆括号。 + +或者干脆直接加上花括号: + +```TypeScript +let a = 100; +const myFunc = x => { a = x; }; +``` + +# 5.3.4 函数方法 + +函数也是一个对象,其有一些方法允许我们实现一些更高级的行为。 + +## `call` 方法 + +函数的 `call` 方法允许你调用函数,并修改本次调用时函数内的 `this` 指向。其类型声明如下: + +```TypeScript +// 这里的 Func 泛型表示原函数本身的类型 +function call(thisArg: any, ...params: Parameters): ReturnType +``` + +其中 `thisArg` 表示本次调用的 `this` 指向,`...params` 表示传递给原函数的参数,用代码简单表示的话如下: + +```TypeScript +function myFunc(...params: any[]): any; + +myFunc.call(thisArg, ...params); +// 相当于: +this = thisArg; +myFunc(...params); +``` + +例如: + +```TypeScript +interface Addable { + y: number; +} + +function myFunc(this: T, x: number): number { + this.y += x; + return this.y; +} + +// 第一个对象 +const a = { y: 100 }; +// 第二个对象 +const b = { + y: 10, + someMethod() { ... } +} + +myFunc.call(a, 10); // a.y 变成 110,这句话返回 110 +myFunc.call(b, 10); // b.y 变成 20,这句话返回 20 +``` + +注意在使用 ts 时,函数声明的参数中写 `this` 并不表示参数,而表示函数的 `this` 指向,也就是说 `myFunc` 只有一个参数 `x`,而不是两个参数,因此后面的 `myFunc.call` 的参数列表只需要填一个。 + +需要注意的是,箭头函数不包含 `this` 指向,这也意味着它不能使用 `call` 方法。 + +## `apply` 方法 + +`apply` 方法与 `call` 方法的功能完全一样,唯一的区别是二者的参数不一致: + +```TypeScript +function apply(thisArg: any, params: Parameters): ReturnType; +``` + +其中 `thisArg` 表示本次调用的 `this` 指向,`params` 表示传递给原函数的参数,注意这里与 `call` 不同,`call` 是剩余参数,而 `apply` 是数组。 + +依然使用上面的 `myFunc` 作为示例: + +```TypeScript +myFunc.apply(a, [10]); // 等同于 myFunc.call(a, 10),参数要使用数组 +myFunc.apply(b, [10]); // 等同于 myFunc.call(b, 10) +``` + +## `bind` 方法 + +`bind` 方法用于创建一个新函数,调用时会以指定 `this` 调用原函数。其类型声明如下: + +```TypeScript +function bind(thisArg: T): (this: T, ...params: Parameters) => ReturnType; +``` + +其中 `thisArg` 表示新函数的 `this` 指向。 + +还是以 `myFunc` 作为示例: + +```TypeScript +const newFuncA = myFunc.bind(a); // newFuncA 内容还是 myFunc,但是 this 指向变为了 a +newFuncA(10); // a.y 变成 110,返回 110 +const newFuncB = myFunc.bind(b); // newFuncB 内容还是 myFunc,但是 this 指向变为了 b +newFuncB(10); // b.y 变成 20,返回 20 +``` + +## 其他内容 + +`call` `apply` `bind` 本身也是函数,因此他们也有 `call` `apply` `bind` 方法。以 `call` 为例,你可以使用 `func.call.call()` 来修改 `func.call` 的 `this` 指向。`call` 的 `this` 指向默认为原函数(可以想想为什么),当对 `call` 执行 `call` 时,就会修改原函数,相当于直接调用了另外一个函数了。例如: + +```TypeScript +function funcA() { + console.log('Called funcA'); +} +function funcB() { + console.log('Called funcB'); +} +// 第一个参数 funcB 表示 funcA.call 的 this 指向, +// 第二个参数 void 0 表示传递给 funcA.call 的第一个参数, +// 也就是传递给 funcB(本来应该是 funcA,但是 this 绑定为了 funcB)的 this 指向 +funcA.call.call(funcB, void 0); // 输出 Called funB +``` + +当然这没有什么实际用途,只能用于加深对 js 的理解。 + +# 5.3.5 函数转字符串 + +可以使用 `toString` 将函数转换为字符串。此行为可以用于代码调试,在实际项目中很少出现: + +```TypeScript +function sum(a, b) { + return a + b; +} + +console.log(sum.toString()); +// Expected output: "function sum(a, b) { +// return a + b; +// }" +``` + +# 5.3.6 函数属性 + +函数上还包括一些属性,这些属性多用于调试和日志输出,很少用于代码逻辑。 + +## `length` 属性 + +函数的 `length` 属性表示函数预期接收的参数数量,剩余参数不算在内,不计算第一个默认参数及之后的参数。例如: + +```TypeScript +console.log((() => {}).length); // 0 +console.log(((a) => {}).length); // 1 +console.log(((a, b) => {}).length); // 2,依此类推 + +console.log(((...args) => {}).length); +// 0,剩余参数不计算在内 + +console.log(((a, b = 1, c) => {}).length); +// 1,只计算第一个具有默认值的参数之前的参数 +``` + +## `name` 属性 + +函数的 `name` 属性表示了函数的名称,如果函数是匿名函数则会返回空字符串或者 `anonymous`。此属性的具体行为比较复杂,如果想要了解的话可以参考 [Function.name - JavaScript | MDN](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Function/name)。 \ No newline at end of file diff --git a/docs/.vitepress/components/demos/ui/animater-delayed-playback.tsx b/docs/.vitepress/components/demos/ui/animater-delayed-playback.tsx new file mode 100644 index 0000000..341ca50 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-delayed-playback.tsx @@ -0,0 +1,3 @@ +import { DelayedPlayback } from './animater-examples'; + +export default DelayedPlayback; diff --git a/docs/.vitepress/components/demos/ui/animater-delayed-timeline.tsx b/docs/.vitepress/components/demos/ui/animater-delayed-timeline.tsx new file mode 100644 index 0000000..bc45132 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-delayed-timeline.tsx @@ -0,0 +1,3 @@ +import { DelayedTimeline } from './animater-examples'; + +export default DelayedTimeline; diff --git a/docs/.vitepress/components/demos/ui/animater-examples.tsx b/docs/.vitepress/components/demos/ui/animater-examples.tsx new file mode 100644 index 0000000..1c3c2b6 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-examples.tsx @@ -0,0 +1,503 @@ +import { EndRelation, linear } from '@motajs/animate'; +import { Font } from '@motajs/render'; +import { useAnimater } from '@motajs/render-vue'; +import { defineComponent, nextTick, onMounted, ref } from 'vue'; + +const LABEL_FONT = new Font('Verdana', 12); + +const TRACK_X = 110; +const TRACK_WIDTH = 330; +const TIMELINE_TOP = 112; +const ROW_GAP = 36; +const BUTTON_TOP = 276; + +const BLUE = '#58c4dd'; +const ORANGE = '#f2b84b'; + +type ScenarioKind = + | 'sequential' + | 'parallel' + | 'delayed' + | 'relay' + | 'query' + | 'retarget'; + +type DemoView = 'timeline' | 'playback'; + +type Animater = NonNullable>; + +interface ISegment { + label: string; + start: number; + end: number; + row: number; + color: string; +} + +interface IScenario { + title: string; + hint: string; + total: number; + segments: ISegment[]; +} + +const SCENARIOS: Record = { + sequential: { + title: 'Animater:顺序执行', + hint: 'x 走完,y 才开始', + total: 1150, + segments: [ + { label: 'x1', start: 0, end: 700, row: 0, color: BLUE }, + { label: 'y1', start: 700, end: 1150, row: 1, color: ORANGE } + ] + }, + parallel: { + title: 'Animater:并行执行', + hint: 'x 与 y 同时开始', + total: 900, + segments: [ + { label: 'x1', start: 0, end: 900, row: 0, color: BLUE }, + { label: 'y1', start: 0, end: 900, row: 1, color: ORANGE } + ] + }, + delayed: { + title: 'Animater:延迟与重叠', + hint: 'y 在 x 开始 300ms 后启动', + total: 1000, + segments: [ + { label: 'x1', start: 0, end: 1000, row: 0, color: BLUE }, + { label: 'y1', start: 300, end: 900, row: 1, color: ORANGE } + ] + }, + relay: { + title: 'Animater:组接力', + hint: '组 2 等组 1 全部结束才开始', + total: 1200, + segments: [ + { label: 'x1', start: 0, end: 600, row: 0, color: BLUE }, + { label: 'y1', start: 600, end: 1200, row: 1, color: ORANGE } + ] + }, + query: { + title: 'Animater:查询与等待', + hint: '读出 y 的步骤,只等待这一条', + total: 300, + segments: [ + { label: 'x1', start: 0, end: 300, row: 0, color: BLUE }, + { label: 'y1', start: 100, end: 300, row: 1, color: ORANGE } + ] + }, + retarget: { + title: 'Animater:中途改道', + hint: 'x 第 2 段在 700ms 接管第 1 段', + total: 1500, + segments: [ + { label: 'x1', start: 0, end: 700, row: 0, color: BLUE }, + { label: 'x2', start: 700, end: 1200, row: 0, color: BLUE }, + { label: 'y1', start: 0, end: 1500, row: 1, color: ORANGE } + ] + } +}; + +const VIEW_HINTS: Record = { + sequential: 'x 结束后,y 才开始。', + parallel: 'x 与 y 在同一组里同时推进。', + delayed: 'y 在 x 开始 300ms 后启动。', + relay: '组 2 等组 1 全部结束才开始。', + query: '读出 y 第 1 段,并只等待它。', + retarget: 'x 第 2 段在 700ms 接管第 1 段。' +}; + +async function runScenario( + animater: Animater, + kind: ScenarioKind, + x: { value: number }, + y: { value: number }, + setStatus: (text: string) => void +): Promise { + switch (kind) { + case 'sequential': { + const group = animater + .animate(x) + .curve(linear()) + .to(1, 700) + .animate(y) + .after() + .to(1, 450) + .planEnd(); + + setStatus('x 执行中'); + await animater.wait(x, 1, group); + setStatus('x 完成,y 开始'); + await animater.wait(y, 1, group); + setStatus('全部完成'); + break; + } + case 'parallel': { + const group = animater + .animate(x) + .curve(linear()) + .to(1, 900) + .animate(y) + .curve(linear()) + .to(1, 900) + .planEnd(); + + setStatus('x 与 y 同时执行'); + await animater.wait(y, 1, group); + setStatus('全部完成'); + break; + } + case 'delayed': { + const group = animater + .animate(x) + .curve(linear()) + .to(1, 1000) + .when(300) + .animate(y) + .curve(linear()) + .to(1, 600) + .planEnd(); + + setStatus('x 先走,y 延迟 300ms 启动'); + await animater.wait(y, 1, group); + setStatus('y 完成,x 仍在走'); + await animater.wait(x, 1, group); + setStatus('全部完成'); + break; + } + case 'relay': { + const first = animater + .animate(x) + .curve(linear()) + .to(1, 600) + .planEnd(); + const second = animater + .animate(y) + .curve(linear()) + .to(1, 600) + .planEnd(); + + setStatus('组 1:x 执行中'); + await animater.wait(x, 1, first); + setStatus('组 1 完成,组 2 开始'); + await animater.wait(y, 1, second); + setStatus('全部完成'); + break; + } + case 'query': { + const group = animater + .animate(x) + .curve(linear()) + .to(1, 300) + .when(100) + .animate(y) + .curve(linear()) + .to(1, 200) + .planEnd(); + const yStep = animater.query(y, 1, group); + + setStatus( + yStep + ? `y 第 1 段:目标 ${yStep.targetValue},时长 ${yStep.time}ms` + : '未查询到 y 第 1 段' + ); + await animater.wait(x, 1, group); + setStatus('x 完成'); + await animater.wait(y, 1, group); + setStatus('y 完成,只等了指定步骤'); + break; + } + case 'retarget': { + const group = animater + .animate(x) + .curve(linear()) + .to(1, 1200, EndRelation.Self) + .animate(y) + .curve(linear()) + .to(1, 1500) + .whenPlan(x, 1, 700) + .animate(x) + .curve(linear()) + .to(0, 500) + .planEnd(); + const second = animater.query(x, 2, group); + + setStatus( + second + ? `x 第 2 段:目标 ${second.targetValue},时长 ${second.time}ms` + : '未查询到 x 第 2 段' + ); + await animater.wait(x, 1, group); + setStatus('x 第 1 段在改道时结束'); + await animater.wait(x, 2, group); + setStatus('x 第 2 段完成,y 仍在走'); + await animater.wait(y, 1, group); + setStatus('全部完成'); + break; + } + } +} + +function createDemo(kind: ScenarioKind, view: DemoView) { + const scenario = SCENARIOS[kind]; + + return defineComponent(() => { + const animater = useAnimater()!; + const clock = useAnimater()!; + const x = ref(0); + const y = ref(0); + const phase = ref(0); + const running = ref(false); + const status = ref('等待开始'); + + const play = async () => { + if (running.value) return; + running.value = true; + x.value = 0; + y.value = 0; + phase.value = 0; + status.value = '准备开始'; + + clock + .animate(phase) + .curve(linear()) + .to(1, scenario.total) + .planEnd(); + + await runScenario(animater, kind, x, y, text => { + status.value = text; + }); + running.value = false; + }; + + onMounted(() => { + nextTick(() => { + void play(); + }); + }); + + const renderTimeline = () => { + const playhead = TRACK_X + phase.value * TRACK_WIDTH; + const elapsed = Math.round(phase.value * scenario.total); + + return ( + <> + + + {[0, 1].map(row => ( + + ))} + {scenario.segments.map(segment => { + const left = + TRACK_X + + (segment.start / scenario.total) * TRACK_WIDTH; + const width = + ((segment.end - segment.start) / scenario.total) * + TRACK_WIDTH; + const top = TIMELINE_TOP + segment.row * ROW_GAP; + + return ( + + + + + ); + })} + + + + + + + + ); + }; + + const renderPlayback = () => { + const retargetX = TRACK_X + (700 / scenario.total) * TRACK_WIDTH; + + return ( + <> + + + + + + + + + + + {kind === 'retarget' && ( + <> + + + + )} + + + + + ); + }; + + return () => ( + + + + + + + {view === 'timeline' ? renderTimeline() : renderPlayback()} + + { + void play(); + }} + > + + + + + + ); + }); +} + +export const SequentialTimeline = createDemo('sequential', 'timeline'); +export const SequentialPlayback = createDemo('sequential', 'playback'); +export const ParallelTimeline = createDemo('parallel', 'timeline'); +export const ParallelPlayback = createDemo('parallel', 'playback'); +export const DelayedTimeline = createDemo('delayed', 'timeline'); +export const DelayedPlayback = createDemo('delayed', 'playback'); +export const RelayTimeline = createDemo('relay', 'timeline'); +export const RelayPlayback = createDemo('relay', 'playback'); +export const QueryTimeline = createDemo('query', 'timeline'); +export const QueryPlayback = createDemo('query', 'playback'); +export const RetargetTimeline = createDemo('retarget', 'timeline'); +export const RetargetPlayback = createDemo('retarget', 'playback'); diff --git a/docs/.vitepress/components/demos/ui/animater-parallel-playback.tsx b/docs/.vitepress/components/demos/ui/animater-parallel-playback.tsx new file mode 100644 index 0000000..d86d707 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-parallel-playback.tsx @@ -0,0 +1,3 @@ +import { ParallelPlayback } from './animater-examples'; + +export default ParallelPlayback; diff --git a/docs/.vitepress/components/demos/ui/animater-parallel-timeline.tsx b/docs/.vitepress/components/demos/ui/animater-parallel-timeline.tsx new file mode 100644 index 0000000..ad20778 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-parallel-timeline.tsx @@ -0,0 +1,3 @@ +import { ParallelTimeline } from './animater-examples'; + +export default ParallelTimeline; diff --git a/docs/.vitepress/components/demos/ui/animater-query-playback.tsx b/docs/.vitepress/components/demos/ui/animater-query-playback.tsx new file mode 100644 index 0000000..a470633 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-query-playback.tsx @@ -0,0 +1,3 @@ +import { QueryPlayback } from './animater-examples'; + +export default QueryPlayback; diff --git a/docs/.vitepress/components/demos/ui/animater-query-timeline.tsx b/docs/.vitepress/components/demos/ui/animater-query-timeline.tsx new file mode 100644 index 0000000..acb95a3 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-query-timeline.tsx @@ -0,0 +1,3 @@ +import { QueryTimeline } from './animater-examples'; + +export default QueryTimeline; diff --git a/docs/.vitepress/components/demos/ui/animater-relay-playback.tsx b/docs/.vitepress/components/demos/ui/animater-relay-playback.tsx new file mode 100644 index 0000000..2699cee --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-relay-playback.tsx @@ -0,0 +1,3 @@ +import { RelayPlayback } from './animater-examples'; + +export default RelayPlayback; diff --git a/docs/.vitepress/components/demos/ui/animater-relay-timeline.tsx b/docs/.vitepress/components/demos/ui/animater-relay-timeline.tsx new file mode 100644 index 0000000..d8e15b0 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-relay-timeline.tsx @@ -0,0 +1,3 @@ +import { RelayTimeline } from './animater-examples'; + +export default RelayTimeline; diff --git a/docs/.vitepress/components/demos/ui/animater-retarget-playback.tsx b/docs/.vitepress/components/demos/ui/animater-retarget-playback.tsx new file mode 100644 index 0000000..f8f3d4d --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-retarget-playback.tsx @@ -0,0 +1,3 @@ +import { RetargetPlayback } from './animater-examples'; + +export default RetargetPlayback; diff --git a/docs/.vitepress/components/demos/ui/animater-retarget-timeline.tsx b/docs/.vitepress/components/demos/ui/animater-retarget-timeline.tsx new file mode 100644 index 0000000..b17090f --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-retarget-timeline.tsx @@ -0,0 +1,3 @@ +import { RetargetTimeline } from './animater-examples'; + +export default RetargetTimeline; diff --git a/docs/.vitepress/components/demos/ui/animater-sequential-playback.tsx b/docs/.vitepress/components/demos/ui/animater-sequential-playback.tsx new file mode 100644 index 0000000..b673bc6 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-sequential-playback.tsx @@ -0,0 +1,3 @@ +import { SequentialPlayback } from './animater-examples'; + +export default SequentialPlayback; diff --git a/docs/.vitepress/components/demos/ui/animater-sequential-timeline.tsx b/docs/.vitepress/components/demos/ui/animater-sequential-timeline.tsx new file mode 100644 index 0000000..ec61085 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-sequential-timeline.tsx @@ -0,0 +1,3 @@ +import { SequentialTimeline } from './animater-examples'; + +export default SequentialTimeline; diff --git a/docs/.vitepress/components/demos/ui/animater-timeline.tsx b/docs/.vitepress/components/demos/ui/animater-timeline.tsx new file mode 100644 index 0000000..a54bc80 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animater-timeline.tsx @@ -0,0 +1,241 @@ +import { linear } from '@motajs/animate'; +import { Font } from '@motajs/render'; +import { useAnimater } from '@motajs/render-vue'; +import { defineComponent, nextTick, onMounted, ref } from 'vue'; + +const LABEL_FONT = new Font('Verdana', 12); + +const TOTAL = 1400; +const A1_TIME = 800; +const A2_DELAY = 200; +const A2_TIME = 400; +const B1_DELAY = 200; +const B1_TIME = 500; +const B2_DELAY = 150; +const B2_TIME = 300; + +const TRACK_X = 70; +const TRACK_WIDTH = 350; +const TIMELINE_TOP = 164; + +interface ITimelineSegment { + label: string; + start: number; + end: number; + row: number; + color: string; +} + +const SEGMENTS: ITimelineSegment[] = [ + { label: 'A1', start: 0, end: A1_TIME, row: 0, color: '#58c4dd' }, + { + label: 'A2', + start: A1_TIME + A2_DELAY, + end: A1_TIME + A2_DELAY + A2_TIME, + row: 0, + color: '#58c4dd' + }, + { + label: 'B1', + start: B1_DELAY, + end: B1_DELAY + B1_TIME, + row: 1, + color: '#f2b84b' + }, + { + label: 'B2', + start: B1_DELAY + B1_TIME + B2_DELAY, + end: B1_DELAY + B1_TIME + B2_DELAY + B2_TIME, + row: 1, + color: '#f2b84b' + } +]; + +// 时间线演示:两个动画对象由同一个 Animater 推进,播放头本身也是一条计划 +export default defineComponent(() => { + const animater = useAnimater()!; + const left = ref(0); + const right = ref(0); + const phase = ref(0); + const running = ref(false); + + const play = async () => { + if (running.value) return; + running.value = true; + left.value = 0; + right.value = 0; + phase.value = 0; + + const group = animater + .animate(phase) + .curve(linear()) + .to(1, TOTAL) + .animate(left) + .when(0) + .to(1, A1_TIME) + .animate(right) + .when(B1_DELAY) + .to(1, B1_TIME) + .animate(right) + .after(B2_DELAY) + .to(0, B2_TIME) + .animate(left) + .afterPlan(left, 1, A2_DELAY) + .to(0, A2_TIME) + .planEnd(); + + await animater.wait(phase, 1, group); + running.value = false; + }; + + onMounted(() => { + nextTick(() => { + void play(); + }); + }); + + return () => { + const playhead = TRACK_X + phase.value * TRACK_WIDTH; + const elapsed = Math.round(phase.value * TOTAL); + + return ( + + + + + + + + + + + + + + + + + + + + + + + + {SEGMENTS.map(segment => { + const x = TRACK_X + (segment.start / TOTAL) * TRACK_WIDTH; + const width = + ((segment.end - segment.start) / TOTAL) * TRACK_WIDTH; + const y = TIMELINE_TOP + segment.row * 26; + + return ( + + + + + ); + })} + + + + + + + + { + void play(); + }} + > + + + + + + ); + }; +}); diff --git a/docs/.vitepress/components/demos/ui/animation-alpha.tsx b/docs/.vitepress/components/demos/ui/animation-alpha.tsx new file mode 100644 index 0000000..ed371fc --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-alpha.tsx @@ -0,0 +1,123 @@ +import { CurveMode, linear, sin } from '@motajs/animate'; +import { transitioned } from '@motajs/render-vue'; +import { defineComponent, ref } from 'vue'; + +// 数值渐变:alpha、位置与进度条 +export default defineComponent(() => { + const alpha = transitioned(0.25, 600, sin(CurveMode.EaseOut))!; + const slide = transitioned(0, 600, sin(CurveMode.EaseOut))!; + const bar = transitioned(0.3, 600, sin(CurveMode.EaseOut))!; + const high = ref(false); + const smooth = ref(true); + const slow = ref(false); + + const toggle = () => { + high.value = !high.value; + alpha.set(high.value ? 1 : 0.25); + slide.set(high.value ? 1 : 0); + bar.set(high.value ? 1 : 0.3); + }; + + const toggleCurve = () => { + smooth.value = !smooth.value; + const curve = smooth.value ? sin() : linear(); + alpha.mode(curve); + slide.mode(curve); + bar.mode(curve); + toggle(); + }; + + const toggleTime = () => { + slow.value = !slow.value; + const time = slow.value ? 1200 : 600; + alpha.setTime(time); + slide.setTime(time); + bar.setTime(time); + toggle(); + }; + + return () => ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-color.tsx b/docs/.vitepress/components/demos/ui/animation-color.tsx new file mode 100644 index 0000000..816f794 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-color.tsx @@ -0,0 +1,61 @@ +import { CurveMode, sin } from '@motajs/animate'; +import { transitionedColor } from '@motajs/render-vue'; +import { defineComponent, ref } from 'vue'; + +// 颜色渐变:填充色与描边色 +export default defineComponent(() => { + const fill = transitionedColor('#2f6fed', 600, sin(CurveMode.EaseOut))!; + const stroke = transitionedColor( + 'rgba(242, 184, 75, 0.9)', + 600, + sin(CurveMode.EaseOut) + )!; + const warm = ref(true); + + const toggle = () => { + warm.value = !warm.value; + fill.set(warm.value ? '#2f6fed' : '#f2b84b'); + stroke.set(warm.value ? 'rgba(242, 184, 75, 0.9)' : '#7ee787'); + }; + + return () => ( + + + + + + + + + + + + + + + + + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-calc-add.tsx b/docs/.vitepress/components/demos/ui/animation-curve-calc-add.tsx new file mode 100644 index 0000000..e7f360d --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-calc-add.tsx @@ -0,0 +1,22 @@ +import { addCurve, constant, sin } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveCalcLab from './animation-curve-calc'; + +const SOURCE_1 = sin(); +const SOURCE_2 = constant(0.2); +const RESULT = addCurve(SOURCE_1, SOURCE_2); + +// 相加:两条来源曲线的逐点和 +export default defineComponent(() => { + return () => ( + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-calc-composite.tsx b/docs/.vitepress/components/demos/ui/animation-curve-calc-composite.tsx new file mode 100644 index 0000000..774dd1a --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-calc-composite.tsx @@ -0,0 +1,22 @@ +import { compositeCurve, pow, sin } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveCalcLab from './animation-curve-calc'; + +const OUTER = sin(); +const INNER = pow(2); +const RESULT = compositeCurve(OUTER, INNER); + +// 复合:外层曲线接收内层曲线的输出 +export default defineComponent(() => { + return () => ( + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-calc-div.tsx b/docs/.vitepress/components/demos/ui/animation-curve-calc-div.tsx new file mode 100644 index 0000000..d129693 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-calc-div.tsx @@ -0,0 +1,22 @@ +import { constant, divCurve, linear } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveCalcLab from './animation-curve-calc'; + +const SOURCE_1 = linear(); +const SOURCE_2 = constant(0.5); +const RESULT = divCurve(SOURCE_1, SOURCE_2); + +// 相除:两条来源曲线的逐点商,分母取常数避免过零 +export default defineComponent(() => { + return () => ( + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-calc-move.tsx b/docs/.vitepress/components/demos/ui/animation-curve-calc-move.tsx new file mode 100644 index 0000000..7b504b3 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-calc-move.tsx @@ -0,0 +1,20 @@ +import { moveCurve, sin } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveCalcLab from './animation-curve-calc'; + +const SOURCE = sin(); +const RESULT = moveCurve(SOURCE, 0.2); + +// 平移:在来源曲线上加一个纵向偏移 +export default defineComponent(() => { + return () => ( + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-calc-mul.tsx b/docs/.vitepress/components/demos/ui/animation-curve-calc-mul.tsx new file mode 100644 index 0000000..46d7a7d --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-calc-mul.tsx @@ -0,0 +1,22 @@ +import { linear, mulCurve, sin } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveCalcLab from './animation-curve-calc'; + +const SOURCE_1 = sin(); +const SOURCE_2 = linear(); +const RESULT = mulCurve(SOURCE_1, SOURCE_2); + +// 相乘:两条来源曲线的逐点积 +export default defineComponent(() => { + return () => ( + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-calc-normalize.tsx b/docs/.vitepress/components/demos/ui/animation-curve-calc-normalize.tsx new file mode 100644 index 0000000..7c7ed42 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-calc-normalize.tsx @@ -0,0 +1,20 @@ +import { moveCurve, normalize, scaleCurve, sin } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveCalcLab from './animation-curve-calc'; + +const SOURCE = moveCurve(scaleCurve(sin(), 0.6), 0.2); +const RESULT = normalize(SOURCE); + +// 归一化:把来源曲线的两端对齐到 0 与 1 +export default defineComponent(() => { + return () => ( + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-calc-opposite.tsx b/docs/.vitepress/components/demos/ui/animation-curve-calc-opposite.tsx new file mode 100644 index 0000000..ed1f47a --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-calc-opposite.tsx @@ -0,0 +1,20 @@ +import { oppositeCurve, sin } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveCalcLab from './animation-curve-calc'; + +const SOURCE = sin(); +const RESULT = oppositeCurve(SOURCE, 1); + +// 取反:以 move 为基准翻转来源曲线 +export default defineComponent(() => { + return () => ( + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-calc-pow.tsx b/docs/.vitepress/components/demos/ui/animation-curve-calc-pow.tsx new file mode 100644 index 0000000..87b6b42 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-calc-pow.tsx @@ -0,0 +1,22 @@ +import { constant, linear, powCurve } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveCalcLab from './animation-curve-calc'; + +const SOURCE_1 = linear(); +const SOURCE_2 = constant(2); +const RESULT = powCurve(SOURCE_1, SOURCE_2); + +// 取幂:第一条曲线为底,第二条曲线为指数 +export default defineComponent(() => { + return () => ( + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-calc-reciprocal.tsx b/docs/.vitepress/components/demos/ui/animation-curve-calc-reciprocal.tsx new file mode 100644 index 0000000..f234921 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-calc-reciprocal.tsx @@ -0,0 +1,25 @@ +import { + linear, + moveCurve, + reciprocalCurve, + scaleCurve +} from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveCalcLab from './animation-curve-calc'; + +const SOURCE = moveCurve(scaleCurve(linear(), 0.5), 0.5); +const RESULT = reciprocalCurve(SOURCE, 0.5); + +// 倒数:来源曲线取值在 0.5 到 1,避免分母过零 +export default defineComponent(() => { + return () => ( + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-calc-scale.tsx b/docs/.vitepress/components/demos/ui/animation-curve-calc-scale.tsx new file mode 100644 index 0000000..4dff597 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-calc-scale.tsx @@ -0,0 +1,20 @@ +import { scaleCurve, sin } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveCalcLab from './animation-curve-calc'; + +const SOURCE = sin(); +const RESULT = scaleCurve(SOURCE, 0.5); + +// 缩放:纵向缩小来源曲线 +export default defineComponent(() => { + return () => ( + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-calc-sequence.tsx b/docs/.vitepress/components/demos/ui/animation-curve-calc-sequence.tsx new file mode 100644 index 0000000..0dca45f --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-calc-sequence.tsx @@ -0,0 +1,27 @@ +import { linear, sequenceCurve, sin } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveCalcLab from './animation-curve-calc'; + +const SEGMENT_1 = linear(); +const SEGMENT_2 = sin(); +const RESULT = sequenceCurve( + [SEGMENT_1, SEGMENT_2], + [0.5, 0.5], + [1, 1], + [0, 0] +); + +// 拼接:两条来源段按各占一半时长合成一条曲线 +export default defineComponent(() => { + return () => ( + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-calc-sub.tsx b/docs/.vitepress/components/demos/ui/animation-curve-calc-sub.tsx new file mode 100644 index 0000000..ba938f7 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-calc-sub.tsx @@ -0,0 +1,22 @@ +import { constant, linear, subCurve } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveCalcLab from './animation-curve-calc'; + +const SOURCE_1 = constant(0.8); +const SOURCE_2 = linear(); +const RESULT = subCurve(SOURCE_1, SOURCE_2); + +// 相减:两条来源曲线的逐点差 +export default defineComponent(() => { + return () => ( + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-calc.tsx b/docs/.vitepress/components/demos/ui/animation-curve-calc.tsx new file mode 100644 index 0000000..a330bb8 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-calc.tsx @@ -0,0 +1,99 @@ +import { Font } from '@motajs/render'; +import { SetupComponentOptions } from '@motajs/system'; +import { defineComponent } from 'vue'; +import { createCurveRender, type CurveEntry } from './animation-curve-plot'; + +const LABEL_FONT = new Font('Verdana', 12); + +export interface ICurveCalcLabProps { + /** 计算函数名称,显示在标题位置 */ + title: string; + /** 来源与结果的简短说明 */ + subtitle: string; + /** 来源曲线与结果曲线;通常前两项是来源,最后一项是结果 */ + curves: CurveEntry[]; +} + +const curveCalcLabProps = { + props: ['title', 'subtitle', 'curves'] +} satisfies SetupComponentOptions; + +const RANGE_SAMPLES = 120; + +// 按来源与结果曲线的实际采样计算显示范围,避免把越界输出截断 +function getDisplayRange(curves: CurveEntry[]): { + min: number; + max: number; +} { + let min = Infinity; + let max = -Infinity; + + for (const entry of curves) { + for (let i = 0; i <= RANGE_SAMPLES; i++) { + const value = entry.curve(i / RANGE_SAMPLES); + if (!Number.isFinite(value)) continue; + min = Math.min(min, value); + max = Math.max(max, value); + } + } + + if (!Number.isFinite(min) || !Number.isFinite(max)) { + return { min: 0, max: 1 }; + } + + // 0 是进度映射的基准,显示范围需要包含它 + min = Math.min(min, 0); + max = Math.max(max, 0); + + const span = max - min; + const padding = span > 0 ? span * 0.1 : 0.1; + + return { min: min - padding, max: max + padding }; +} + +// 曲线计算实验台:标题、说明、来源与结果曲线图 +const CurveCalcLab = defineComponent((props, { slots }) => { + return () => { + const render = createCurveRender( + props.curves, + getDisplayRange(props.curves) + ); + + return ( + + + + + + + + {props.curves.map((entry, index) => ( + + + + + ))} + + {slots.default?.()} + + ); + }; +}, curveCalcLabProps); + +export default CurveCalcLab; diff --git a/docs/.vitepress/components/demos/ui/animation-curve-constant.tsx b/docs/.vitepress/components/demos/ui/animation-curve-constant.tsx new file mode 100644 index 0000000..e404abb --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-constant.tsx @@ -0,0 +1,30 @@ +import { constant } from '@motajs/animate'; +import { defineComponent, ref } from 'vue'; +import { Slider } from '../../../../../packages-user/client-base/src/components/slider'; +import CurveLab from './animation-curve-lab'; + +const VALUE_MIN = 0; +const VALUE_MAX = 1; + +// 常数曲线:输出始终等于 k +export default defineComponent(() => { + const k = ref(0.5); + + return () => ( + constant(k.value)} + bindings={[k.value]} + > + + + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-cosh.tsx b/docs/.vitepress/components/demos/ui/animation-curve-cosh.tsx new file mode 100644 index 0000000..9bc13c3 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-cosh.tsx @@ -0,0 +1,31 @@ +import { cosh } from '@motajs/animate'; +import { defineComponent, ref } from 'vue'; +import { Slider } from '../../../../../packages-user/client-base/src/components/slider'; +import CurveLab from './animation-curve-lab'; + +const K_MIN = 0.5; +const K_MAX = 4; + +// 双曲余弦曲线:调整比例参数 k,切换四种 CurveMode +export default defineComponent(() => { + const k = ref(2); + + return () => ( + cosh(k.value, mode)} + bindings={[k.value]} + supportsMode + > + + + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-lab.tsx b/docs/.vitepress/components/demos/ui/animation-curve-lab.tsx new file mode 100644 index 0000000..e404097 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-lab.tsx @@ -0,0 +1,131 @@ +import { CurveMode, type ExcitationCurve } from '@motajs/animate'; +import { Font } from '@motajs/render'; +import { SetupComponentOptions } from '@motajs/system'; +import { defineComponent, ref } from 'vue'; +import { createCurveRender } from './animation-curve-plot'; + +const LABEL_FONT = new Font('Verdana', 12); + +const MODE_ITEMS: { mode: CurveMode; label: string; hint: string }[] = [ + { mode: CurveMode.EaseIn, label: 'EaseIn', hint: '缓进快出' }, + { mode: CurveMode.EaseOut, label: 'EaseOut', hint: '快进缓出' }, + { mode: CurveMode.EaseInOut, label: 'EaseInOut', hint: '缓进缓出,中间快' }, + { + mode: CurveMode.EaseCenter, + label: 'EaseCenter', + hint: '快进快出,中间缓' + } +]; + +export interface ICurveLabProps { + /** 曲线名称,显示在标题位置 */ + title: string; + /** 曲线说明,显示在标题下方 */ + subtitle: string; + /** 按当前模式生成要绘制的曲线 */ + curve: (mode: CurveMode) => ExcitationCurve; + /** 曲线依赖的响应式值;变化时重绘 */ + bindings: unknown[]; + /** 是否显示四种曲线模式的按钮 */ + supportsMode?: boolean; + /** 没有控件时显示的说明 */ + note?: string; +} + +const curveLabProps = { + props: ['title', 'subtitle', 'curve', 'bindings', 'supportsMode', 'note'] +} satisfies SetupComponentOptions; + +// 曲线实验台:标题、说明、曲线图,以及可选的模式按钮与参数控件 +const CurveLab = defineComponent((props, { slots }) => { + const mode = ref(CurveMode.EaseIn); + + return () => { + const supportsMode = props.supportsMode ?? false; + const currentMode = + MODE_ITEMS.find(item => item.mode === mode.value) ?? MODE_ITEMS[0]; + const hasBody = Boolean(slots.default) || Boolean(props.note); + const modeTop = hasBody ? 258 : 272; + const bodyTop = supportsMode ? 292 : 268; + const render = createCurveRender([ + { + label: props.title, + color: '#7ee787', + curve: props.curve(mode.value) + } + ]); + + return ( + + + + + + {supportsMode && ( + + )} + + + + {supportsMode && + MODE_ITEMS.map((item, index) => { + const active = item.mode === mode.value; + + return ( + { + mode.value = item.mode; + }} + > + + + + ); + })} + + {hasBody && ( + + {slots.default?.()} + {!slots.default && props.note && ( + + )} + + )} + + ); + }; +}, curveLabProps); + +export default CurveLab; diff --git a/docs/.vitepress/components/demos/ui/animation-curve-linear.tsx b/docs/.vitepress/components/demos/ui/animation-curve-linear.tsx new file mode 100644 index 0000000..042e32b --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-linear.tsx @@ -0,0 +1,16 @@ +import { linear } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveLab from './animation-curve-lab'; + +// 线性曲线:没有参数,输出始终等于 x +export default defineComponent(() => { + return () => ( + linear()} + bindings={[]} + note="无参数" + /> + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-modes.tsx b/docs/.vitepress/components/demos/ui/animation-curve-modes.tsx new file mode 100644 index 0000000..1883d3d --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-modes.tsx @@ -0,0 +1,16 @@ +import { sin } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveLab from './animation-curve-lab'; + +// 曲线模式:同一条正弦曲线在四种 CurveMode 之间切换 +export default defineComponent(() => { + return () => ( + sin(mode)} + bindings={[]} + supportsMode + /> + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-plot.tsx b/docs/.vitepress/components/demos/ui/animation-curve-plot.tsx new file mode 100644 index 0000000..fd0a9cc --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-plot.tsx @@ -0,0 +1,113 @@ +import type { ExcitationCurve } from '@motajs/animate'; +import type { CustomRenderFunction } from '@motajs/render'; + +// 一条曲线的名称、颜色与函数 +export interface CurveEntry { + label: string; + color: string; + curve: ExcitationCurve; +} + +const WIDTH = 408; +const HEIGHT = 190; +const LEFT = 46; +const TOP = 12; +const RIGHT = 12; +const BOTTOM = 36; + +// 刻度文字:整数不带小数点,其余最多保留两位 +function formatTick(value: number): string { + if (Number.isInteger(value)) return String(value); + return value.toFixed(2).replace(/0+$/, '').replace(/\.$/, ''); +} + +// 生成绘制坐标轴与多条曲线的 render 函数;纵轴默认 0 到 1,可指定显示范围 +export function createCurveRender( + curves: CurveEntry[], + options: { min?: number; max?: number } = {} +): CustomRenderFunction { + const min = options.min ?? 0; + const max = options.max ?? 1; + + return canvas => { + const ctx = canvas.ctx; + const plotWidth = WIDTH - LEFT - RIGHT; + const plotHeight = HEIGHT - TOP - BOTTOM; + const bottom = TOP + plotHeight; + const toY = (value: number) => + TOP + ((max - value) / (max - min)) * plotHeight; + + // 背景 + ctx.fillStyle = '#101820'; + ctx.fillRect(0, 0, WIDTH, HEIGHT); + + // 网格 + ctx.strokeStyle = '#22304a'; + ctx.lineWidth = 1; + for (let i = 0; i <= 4; i++) { + const y = TOP + (plotHeight * i) / 4; + ctx.beginPath(); + ctx.moveTo(LEFT, y); + ctx.lineTo(LEFT + plotWidth, y); + ctx.stroke(); + + const x = LEFT + (plotWidth * i) / 4; + ctx.beginPath(); + ctx.moveTo(x, TOP); + ctx.lineTo(x, bottom); + ctx.stroke(); + } + + // 坐标轴 + ctx.strokeStyle = '#7d8ea6'; + ctx.lineWidth = 1.5; + ctx.beginPath(); + ctx.moveTo(LEFT, TOP); + ctx.lineTo(LEFT, bottom); + ctx.lineTo(LEFT + plotWidth, bottom); + ctx.stroke(); + + // 刻度 + ctx.fillStyle = '#8b98a8'; + ctx.font = '11px Verdana'; + ctx.textAlign = 'right'; + ctx.textBaseline = 'middle'; + for (let i = 0; i <= 4; i++) { + const value = max - ((max - min) * i) / 4; + const y = TOP + (plotHeight * i) / 4; + ctx.fillText(formatTick(value), LEFT - 8, y); + } + + ctx.textAlign = 'center'; + ctx.textBaseline = 'top'; + ctx.fillText('0', LEFT, bottom + 6); + ctx.fillText('0.5', LEFT + plotWidth / 2, bottom + 6); + ctx.fillText('1', LEFT + plotWidth, bottom + 6); + + // 轴名 + ctx.fillText('x', LEFT + plotWidth / 2, bottom + 22); + + ctx.save(); + ctx.translate(12, TOP + plotHeight / 2); + ctx.rotate(-Math.PI / 2); + ctx.textBaseline = 'middle'; + ctx.fillText('输出', 0, 0); + ctx.restore(); + + // 曲线 + ctx.lineWidth = 2.5; + for (const entry of curves) { + ctx.beginPath(); + ctx.strokeStyle = entry.color; + for (let i = 0; i <= 120; i++) { + const p = i / 120; + const value = entry.curve(p); + const x = LEFT + p * plotWidth; + const y = toY(value); + if (i === 0) ctx.moveTo(x, y); + else ctx.lineTo(x, y); + } + ctx.stroke(); + } + }; +} diff --git a/docs/.vitepress/components/demos/ui/animation-curve-pow.tsx b/docs/.vitepress/components/demos/ui/animation-curve-pow.tsx new file mode 100644 index 0000000..011ea23 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-pow.tsx @@ -0,0 +1,31 @@ +import { pow } from '@motajs/animate'; +import { defineComponent, ref } from 'vue'; +import { Slider } from '../../../../../packages-user/client-base/src/components/slider'; +import CurveLab from './animation-curve-lab'; + +const EXP_MIN = 0.5; +const EXP_MAX = 4; + +// 幂曲线:调整指数,切换四种 CurveMode +export default defineComponent(() => { + const exp = ref(2); + + return () => ( + pow(exp.value, mode)} + bindings={[exp.value]} + supportsMode + > + + + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-sec.tsx b/docs/.vitepress/components/demos/ui/animation-curve-sec.tsx new file mode 100644 index 0000000..0c7acaf --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-sec.tsx @@ -0,0 +1,16 @@ +import { sec } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveLab from './animation-curve-lab'; + +// 正割曲线:切换四种 CurveMode,观察快慢分布 +export default defineComponent(() => { + return () => ( + sec(mode)} + bindings={[]} + supportsMode + /> + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-sech.tsx b/docs/.vitepress/components/demos/ui/animation-curve-sech.tsx new file mode 100644 index 0000000..55e6518 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-sech.tsx @@ -0,0 +1,31 @@ +import { sech } from '@motajs/animate'; +import { defineComponent, ref } from 'vue'; +import { Slider } from '../../../../../packages-user/client-base/src/components/slider'; +import CurveLab from './animation-curve-lab'; + +const K_MIN = 0.5; +const K_MAX = 4; + +// 双曲正割曲线:调整比例参数 k,切换四种 CurveMode +export default defineComponent(() => { + const k = ref(1); + + return () => ( + sech(k.value, mode)} + bindings={[k.value]} + supportsMode + > + + + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-sin.tsx b/docs/.vitepress/components/demos/ui/animation-curve-sin.tsx new file mode 100644 index 0000000..91f1da6 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-sin.tsx @@ -0,0 +1,16 @@ +import { sin } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveLab from './animation-curve-lab'; + +// 正弦曲线:切换四种 CurveMode,观察快慢分布 +export default defineComponent(() => { + return () => ( + sin(mode)} + bindings={[]} + supportsMode + /> + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-step.tsx b/docs/.vitepress/components/demos/ui/animation-curve-step.tsx new file mode 100644 index 0000000..5d71efd --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-step.tsx @@ -0,0 +1,30 @@ +import { step } from '@motajs/animate'; +import { defineComponent, ref } from 'vue'; +import { Slider } from '../../../../../packages-user/client-base/src/components/slider'; +import CurveLab from './animation-curve-lab'; + +const STEP_MIN = 2; +const STEP_MAX = 12; + +// 阶梯曲线:进度每走 1/k,输出跳变一次 +export default defineComponent(() => { + const k = ref(5); + + return () => ( + step(k.value)} + bindings={[k.value]} + > + + + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-tan.tsx b/docs/.vitepress/components/demos/ui/animation-curve-tan.tsx new file mode 100644 index 0000000..a0874f4 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-tan.tsx @@ -0,0 +1,16 @@ +import { tan } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import CurveLab from './animation-curve-lab'; + +// 正切曲线:切换四种 CurveMode,观察快慢分布 +export default defineComponent(() => { + return () => ( + tan(mode)} + bindings={[]} + supportsMode + /> + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curve-tanh.tsx b/docs/.vitepress/components/demos/ui/animation-curve-tanh.tsx new file mode 100644 index 0000000..96432b8 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curve-tanh.tsx @@ -0,0 +1,31 @@ +import { tanh } from '@motajs/animate'; +import { defineComponent, ref } from 'vue'; +import { Slider } from '../../../../../packages-user/client-base/src/components/slider'; +import CurveLab from './animation-curve-lab'; + +const K_MIN = 0.5; +const K_MAX = 4; + +// 双曲正切曲线:调整比例参数 k,切换四种 CurveMode +export default defineComponent(() => { + const k = ref(2); + + return () => ( + tanh(k.value, mode)} + bindings={[k.value]} + supportsMode + > + + + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curves-basic.tsx b/docs/.vitepress/components/demos/ui/animation-curves-basic.tsx new file mode 100644 index 0000000..acfe979 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curves-basic.tsx @@ -0,0 +1,51 @@ +import { constant, linear, step } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import { createCurveRender, type CurveEntry } from './animation-curve-plot'; + +const CURVES: CurveEntry[] = [ + { label: 'linear()', color: '#7ee787', curve: linear() }, + { label: 'step(5)', color: '#f2b84b', curve: step(5) }, + { label: 'constant(0.5)', color: '#c58af9', curve: constant(0.5) } +]; + +// 基础曲线:线性、阶梯与常数 +export default defineComponent(() => { + const render = createCurveRender(CURVES); + + return () => ( + + + + + + + + {CURVES.map((entry, index) => ( + + + + + ))} + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curves-easing.tsx b/docs/.vitepress/components/demos/ui/animation-curves-easing.tsx new file mode 100644 index 0000000..4862862 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curves-easing.tsx @@ -0,0 +1,56 @@ +import { CurveMode, pow, sec, sin, tan } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import { createCurveRender, type CurveEntry } from './animation-curve-plot'; + +const CURVES: CurveEntry[] = [ + { label: 'sin()', color: '#2f6fed', curve: sin(CurveMode.EaseOut) }, + { + label: 'pow(2)', + color: '#7ee787', + curve: pow(2, CurveMode.EaseOut) + }, + { label: 'tan()', color: '#f2b84b', curve: tan(CurveMode.EaseOut) }, + { label: 'sec()', color: '#c58af9', curve: sec(CurveMode.EaseOut) } +]; + +// 缓动曲线:正弦、幂、正切与正割 +export default defineComponent(() => { + const render = createCurveRender(CURVES); + + return () => ( + + + + + + + + {CURVES.map((entry, index) => ( + + + + + ))} + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-curves-special.tsx b/docs/.vitepress/components/demos/ui/animation-curves-special.tsx new file mode 100644 index 0000000..f37647d --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-curves-special.tsx @@ -0,0 +1,64 @@ +import { CurveMode, cosh, sech, tanh } from '@motajs/animate'; +import { defineComponent } from 'vue'; +import { createCurveRender, type CurveEntry } from './animation-curve-plot'; + +const CURVES: CurveEntry[] = [ + { + label: 'cosh()', + color: '#2f6fed', + curve: cosh(2, CurveMode.EaseOut) + }, + { + label: 'tanh()', + color: '#7ee787', + curve: tanh(2, CurveMode.EaseOut) + }, + { + label: 'sech()', + color: '#f2b84b', + curve: sech(1, CurveMode.EaseOut) + } +]; + +// 双曲曲线:双曲余弦、双曲正切与双曲正割 +export default defineComponent(() => { + // 三条曲线都在 0 到 1 之间,纵轴固定为 0 到 1 + const render = createCurveRender(CURVES); + + return () => ( + + + + + + + + {CURVES.map((entry, index) => ( + + + + + ))} + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/animation-cycle.tsx b/docs/.vitepress/components/demos/ui/animation-cycle.tsx new file mode 100644 index 0000000..b75d9e7 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-cycle.tsx @@ -0,0 +1,123 @@ +import { CurveMode, sin } from '@motajs/animate'; +import { cycledTransition } from '@motajs/render-vue'; +import { defineComponent, ref, watch } from 'vue'; +import { Slider } from '../../../../../packages-user/client-base/src/components/slider'; + +// 循环渐变:两个滑动条调整循环的起点与终点 +export default defineComponent(() => { + const minValue = ref(0.25); + const maxValue = ref(0.9); + const glow = cycledTransition( + minValue.value, + maxValue.value, + 900, + sin(CurveMode.EaseOut) + )!; + + const applyRange = () => { + // 两个端点保持一前一后,避免区间塌成一个点 + if (maxValue.value - minValue.value < 0.05) { + if (minValue.value <= 0.95) { + maxValue.value = minValue.value + 0.05; + } else { + minValue.value = maxValue.value - 0.05; + } + } + glow.setRange(minValue.value, maxValue.value); + }; + + watch([minValue, maxValue], applyRange); + + return () => { + const trackLeft = 64; + const trackWidth = 352; + const trackY = 130; + const minX = trackLeft + minValue.value * trackWidth; + const maxX = trackLeft + maxValue.value * trackWidth; + const currentX = trackLeft + glow.ref.value * trackWidth; + + return ( + + + + + + + + + + + + + + + + + + + + + + + + ); + }; +}); diff --git a/docs/.vitepress/components/demos/ui/animation-transition-end-relation.tsx b/docs/.vitepress/components/demos/ui/animation-transition-end-relation.tsx new file mode 100644 index 0000000..36855b2 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-transition-end-relation.tsx @@ -0,0 +1,137 @@ +import { EndRelation } from '@motajs/animate'; +import { useTransition } from '@motajs/render-vue'; +import { defineComponent, onMounted, ref } from 'vue'; + +// 半程曲线在 1 处输出 0.5,回程曲线在 1 处回到 0 +const HALF = (p: number) => p * 0.5; +const RETURN = (p: number) => Math.sin(p * Math.PI) * 0.5; + +const curves = [ + { label: '半程曲线', curve: HALF, time: 600 }, + { label: '回程曲线', curve: RETURN, time: 900 } +]; + +// 同一目标配同一条曲线,比较 Target 与 Curve 两种结尾参考 +export default defineComponent(() => { + const targetValue = ref(0); + const curveValue = ref(0); + const index = ref(0); + const transition = useTransition()!; + + const play = () => { + const item = curves[index.value]; + targetValue.value = 0; + curveValue.value = 0; + transition + .transition(targetValue) + .curve(item.curve) + .to(1, item.time, EndRelation.Target); + transition + .transition(curveValue) + .curve(item.curve) + .to(1, item.time, EndRelation.Curve); + }; + + const next = () => { + index.value = (index.value + 1) % curves.length; + play(); + }; + + onMounted(() => { + requestAnimationFrame(play); + }); + + return () => { + const item = curves[index.value]; + const endpoint = item.curve(1); + const targetX = 24 + targetValue.value * 400; + const curveX = 24 + curveValue.value * 400; + const endX = 24 + endpoint * 400; + + return ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ); + }; +}); diff --git a/docs/.vitepress/components/demos/ui/animation-transition.tsx b/docs/.vitepress/components/demos/ui/animation-transition.tsx new file mode 100644 index 0000000..78f863a --- /dev/null +++ b/docs/.vitepress/components/demos/ui/animation-transition.tsx @@ -0,0 +1,93 @@ +import { linear, sin } from '@motajs/animate'; +import { useTransition } from '@motajs/render-vue'; +import { defineComponent, onMounted, ref } from 'vue'; + +// 单值渐变:Transition 让当前值走向目标值 +export default defineComponent(() => { + const value = ref(0.18); + const target = ref(0.82); + const transition = useTransition()!; + + // 设定新的目标值,执行器从当前值继续渐变 + const moveTo = (next: number, curve = sin()) => { + target.value = next; + transition.transition(value).curve(curve).to(next, 900); + }; + + onMounted(() => { + // 等执行器绑定到根激励源后再启动首段渐变 + requestAnimationFrame(() => moveTo(0.82)); + }); + + return () => { + const current = value.value; + const goal = target.value; + const targetX = 40 + goal * 400; + + return ( + + + + + + + + + + + + + + + + moveTo(0.82)} + > + + + + moveTo(0.18, linear())} + > + + + + + + + ); + }; +}); diff --git a/docs/.vitepress/components/demos/ui/excitation-curve-speed.tsx b/docs/.vitepress/components/demos/ui/excitation-curve-speed.tsx new file mode 100644 index 0000000..d99dd95 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/excitation-curve-speed.tsx @@ -0,0 +1,155 @@ +import { ExcitationVariator, RafExcitation } from '@motajs/animate'; +import { defineComponent, onUnmounted, ref } from 'vue'; + +// 变速曲线:最后两次激励时间戳与时间差 +export default defineComponent(() => { + const speed = ref(1); + const progress = ref(0); + const prevTs = ref(0); + const lastTs = ref(0); + const gap = ref(0); + const running = ref(false); + + let base = 0; + let hasBase = false; + let hasPrev = false; + let curveStart = 0; + const curveTime = 3000; + + const source = new RafExcitation(); + const variator = new ExcitationVariator(); + variator.bindExcitation(source); + + variator.add({ + excited(payload: number) { + if (!hasBase) { + base = payload; + hasBase = true; + } + if (hasPrev) prevTs.value = lastTs.value; + lastTs.value = payload - base; + if (hasPrev) gap.value = lastTs.value - prevTs.value; + hasPrev = true; + speed.value = variator.speed; + + if (running.value) { + const elapsed = source.payload() - curveStart; + progress.value = Math.min(elapsed / curveTime, 1); + if (progress.value >= 1) running.value = false; + } + } + }); + + const runCurve = () => { + if (running.value) return; + curveStart = source.payload(); + running.value = true; + progress.value = 0; + void variator.curveSpeed(p => 1.5 - 1.25 * p, curveTime); + }; + + const resetSpeed = () => { + variator.endAllCurves(); + variator.setSpeed(1); + speed.value = 1; + running.value = false; + progress.value = 0; + }; + + onUnmounted(() => { + variator.destroy(); + source.destroy(); + }); + + return () => ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/excitation-divider.tsx b/docs/.vitepress/components/demos/ui/excitation-divider.tsx new file mode 100644 index 0000000..983043e --- /dev/null +++ b/docs/.vitepress/components/demos/ui/excitation-divider.tsx @@ -0,0 +1,114 @@ +import { ExcitationDivider, IntervalExcitation } from '@motajs/animate'; +import { defineComponent, onUnmounted, ref } from 'vue'; + +// 分频器:统计输入源激励次数与输出端转发次数 +export default defineComponent(() => { + const divider = ref(1); + const upCount = ref(0); + const downCount = ref(0); + const upPayload = ref(0); + const downPayload = ref(0); + + const source = new IntervalExcitation(200); + const splitter = new ExcitationDivider(); + splitter.bindExcitation(source); + + source.add({ + excited(payload: number) { + upCount.value += 1; + upPayload.value = payload; + } + }); + + splitter.add({ + excited(payload: number) { + downCount.value += 1; + downPayload.value = payload; + } + }); + + const changeDivider = (value: number) => { + splitter.setDivider(value); + divider.value = value; + }; + + onUnmounted(() => { + splitter.unbindExcitation(); + splitter.destroy(); + source.destroy(); + }); + + const options = [1, 2, 3, 5]; + + return () => ( + + + + + + + + + + + + + + + + + + + {options.map((value, index) => { + const active = divider.value === value; + + return ( + changeDivider(value)} + > + + + + ); + })} + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/excitation-raf-payload.tsx b/docs/.vitepress/components/demos/ui/excitation-raf-payload.tsx new file mode 100644 index 0000000..f12e6b2 --- /dev/null +++ b/docs/.vitepress/components/demos/ui/excitation-raf-payload.tsx @@ -0,0 +1,84 @@ +import { RafExcitation } from '@motajs/animate'; +import { defineComponent, onUnmounted, ref } from 'vue'; + +// 载荷演示:RafExcitation 每帧广播当前时间戳 +export default defineComponent(() => { + const now = ref(0); + const start = ref(0); + const frames = ref(0); + const frameGap = ref(0); + + let last = 0; + let hasLast = false; + + const source = new RafExcitation(); + source.add({ + excited(payload: number) { + if (frames.value === 0) start.value = payload; + if (hasLast) frameGap.value = payload - last; + last = payload; + hasLast = true; + now.value = payload; + frames.value += 1; + } + }); + + onUnmounted(() => { + source.destroy(); + }); + + return () => ( + + + + + + + + + + + + + + + + + + + + + ); +}); diff --git a/docs/.vitepress/components/demos/ui/excitation-variator.tsx b/docs/.vitepress/components/demos/ui/excitation-variator.tsx new file mode 100644 index 0000000..267bd1f --- /dev/null +++ b/docs/.vitepress/components/demos/ui/excitation-variator.tsx @@ -0,0 +1,131 @@ +import { ExcitationVariator, RafExcitation } from '@motajs/animate'; +import { defineComponent, onUnmounted, ref } from 'vue'; + +// 变速器:输出端连续两次时间的差值 +export default defineComponent(() => { + const speed = ref(1); + const inputNow = ref(0); + const prevOut = ref(0); + const currOut = ref(0); + const gap = ref(0); + const hasPrev = ref(false); + + const source = new RafExcitation(); + const variator = new ExcitationVariator(); + variator.bindExcitation(source); + + let lastOut = 0; + + source.add({ + excited(payload: number) { + inputNow.value = payload; + } + }); + + variator.add({ + excited(payload: number) { + if (hasPrev.value) { + prevOut.value = lastOut; + gap.value = payload - lastOut; + } + currOut.value = payload; + lastOut = payload; + hasPrev.value = true; + speed.value = variator.speed; + } + }); + + const changeSpeed = (value: number) => { + variator.setSpeed(value); + speed.value = value; + }; + + onUnmounted(() => { + variator.destroy(); + source.destroy(); + }); + + return () => ( + + + + + + + + + + + + + + + + + + + + + + + + + changeSpeed(0.5)}> + + + + changeSpeed(1)}> + + + + changeSpeed(2)}> + + + + + ); +}); diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 31e9b1a..a6cf90c 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -376,6 +376,10 @@ export default defineConfig({ text: '自定义组件', link: '/render-guide/advanced/custom-components' }, + { + text: '动画', + link: '/render-guide/advanced/animation' + }, { text: 'UI 系统', link: '/render-guide/advanced/ui-system' @@ -409,6 +413,28 @@ export default defineConfig({ link: '/render-guide/advanced/inventory-example-6-animation-and-register' } ] + }, + { + text: '渲染底层', + collapsed: false, + items: [ + { + text: '动画曲线', + link: '/render-guide/internals/animation-curves' + }, + { + text: '动画激励', + link: '/render-guide/internals/animation-excitation' + }, + { + text: '动画执行器', + link: '/render-guide/internals/animation-runner' + }, + { + text: '渐变执行器', + link: '/render-guide/internals/animation-transition' + } + ] } ] }, diff --git a/docs/render-guide/advanced/animation.md b/docs/render-guide/advanced/animation.md new file mode 100644 index 0000000..1bab2c6 --- /dev/null +++ b/docs/render-guide/advanced/animation.md @@ -0,0 +1,389 @@ +# 动画 + +动画就是一系列数据按照指定方式变化:位置、透明度、颜色与进度条长度,都可以随时间连续改变。曲线决定「时间从起点走到终点时,数据按什么方式变化」;把数据与曲线交给动画系统,值就会平滑过渡,而不是瞬间跳过去。 + +本篇先讲曲线如何把时间映射成数据,再按基础、缓动与双曲三组介绍内置曲线的参数与形状,最后讲三个高层接口 `transitioned`、`transitionedColor` 与 `cycledTransition`。更底层的执行器与激励源见渲染底层。 + +## 前置知识 + +阅读本篇前,建议先读完: + +- [响应式](./reactivity.md) +- [UI 入门](../basics/ui-basics.md) + +## 动画的本质与曲线 + +一个动画由两部分组成:一份要变化的数据,和一条把时间进度映射成数据取值的曲线。时间进度通常叫 `progress`,从 `0`(开始)走到 `1`(结束)。曲线接收 `progress`,返回一个数;动画系统按这个返回值,在起始值与目标值之间取出当前值。 + +```ts +type ExcitationCurve = (progress: number) => number; +``` + +`progress` 在 `0` 到 `1` 之间,曲线的输出不要求也落在 `0` 到 `1`:输出可以超出这个范围,所以过程中可以低于起始值或高于目标值,也可以多次起伏。曲线只决定过渡过程,不决定动画最终落在哪个值;最终落点由使用曲线的动画接口给出。 + +内置曲线都从 `@motajs/animate` 导入。不带 `mode` 参数的曲线直接返回一条固定形状的曲线;带 `mode` 参数的曲线会在内部套用下面的曲线模式。 + +## 曲线模式 + +曲线本身只保证「缓进快出」这一种基本形状。给它套一个 `CurveMode`,就能改变快慢分布。`CurveMode` 是曲线的模式枚举,默认 `CurveMode.EaseIn`。 + +| 模式 | 含义 | 形状 | +| ---------------------- | ---------------- | ------------------------------ | +| `CurveMode.EaseIn` | 缓进快出 | 从起点慢慢加速,越接近终点越快 | +| `CurveMode.EaseOut` | 快进缓出 | 起步快,接近终点逐渐减速 | +| `CurveMode.EaseInOut` | 缓进缓出,中间快 | 两端慢、中段最快 | +| `CurveMode.EaseCenter` | 快进快出,中间缓 | 两端快、中段最慢 | + +这四种模式都从 `0` 开始、到 `1` 结束,区别只在过程中的快慢分布:`EaseIn` 越走越快,`EaseOut` 越走越慢,`EaseInOut` 两端慢、中段快,`EaseCenter` 两端快、中段慢。`CurveMode` 只改变形状,不改变时长与起止值;同一个曲线换模式只是让过程中快慢不同。各模式如何由一条缓进快出曲线换算得到,见[动画曲线](../internals/animation-curves.md#曲线模式)。 + +下面的演示用同一条正弦曲线,点四个按钮在四种模式之间切换。曲线连续变化,可以直观看出快慢分布。 + + + + + + +## 内置曲线 + +下面按基础、缓动与双曲三组列出参数与形状;同一组的多条曲线画在一张图里,便于对照。 + +### 基础曲线 + +三条基础曲线不接收 `mode` 参数,形状直接由参数决定。 + +| 曲线 | 参数 | +| ------------- | --------------------- | +| `linear()` | 无 | +| `step(k)` | `k`:阶梯数,取正整数 | +| `constant(k)` | `k`:常数输出值 | + + + + + + +### 缓动曲线 + +四条曲线都以「缓进快出」为基准,并接收可选的 `mode`;不传时默认 `CurveMode.EaseIn`。它们从 `0` 上升到 `1`,上升速度不同。 + +| 曲线 | 参数 | +| ----------------- | ------------------------------------ | +| `sin(mode?)` | `mode` 可选,默认 `CurveMode.EaseIn` | +| `tan(mode?)` | `mode` 可选,默认 `CurveMode.EaseIn` | +| `sec(mode?)` | `mode` 可选,默认 `CurveMode.EaseIn` | +| `pow(exp, mode?)` | `exp` 必需,指数;`mode` 可选 | + + + + + + +### 双曲曲线 + +三条双曲曲线同样接收可选的 `mode`,默认 `CurveMode.EaseIn`。`k` 是比例参数。 + +| 曲线 | 参数 | +| -------------------- | -------------------------------------------- | +| `cosh(k = 2, mode?)` | `k` 默认 `2`;`mode` 默认 `CurveMode.EaseIn` | +| `tanh(k = 2, mode?)` | `k` 默认 `2`;`mode` 默认 `CurveMode.EaseIn` | +| `sech(k = 1, mode?)` | `k` 默认 `1`;`mode` 默认 `CurveMode.EaseIn` | + + + + + + +曲线公式、模式换算与单条曲线的行为见[动画曲线](../internals/animation-curves.md)。 + +## 数值渐变 + +界面里经常需要让一个数值在两次状态之间平滑变化,例如透明度从 `0.25` 到 `1`、圆点从左边移到右边。自己管理执行器、选择对象、绑定激励源会很啰嗦;`transitioned` 把这些收进一个控制器:你只需要告诉它「现在去哪个值」,它负责在当前值与目标值之间平滑推进。 + +### 获取控制器 + +先创建控制器,并给它一个初始值、一次变化默认用多久,以及过程中用哪条曲线: + +```tsx +// setup +import { transitioned } from '@motajs/render-vue'; +import { CurveMode, sin } from '@motajs/animate'; + +// 初始值 0.25,默认 600ms,曲线用 sin() +const alpha = transitioned(0.25, 600, sin(CurveMode.EaseOut))!; +``` + +`transitioned(value, time, curve)` 返回一个数值渐变控制器,类型是 `ITransitionedController | null`:`value` 是初始值,`time` 是默认时长(毫秒),`curve` 是速率曲线。它只在组件 `setup` 中调用;在 `setup` 中返回值一定非空,所以这里用 `!` 收窄类型。返回的控制器带一个响应式引用 `ref`(类型 `Ref`),渲染时读 `alpha.ref.value` 就能拿到当前值。 + +### 执行渐变动画 + +控制器拿到后,当前值就是初始值。要让数值走向新目标,调用 `set(value, time?)`;省略 `time` 时使用控制器的默认时长: + +```tsx +// setup +const expand = () => { + // 从当前值走向 1,使用创建时的 600ms + alpha.set(1); +}; + +// 组件内容 +; +``` + +调用 `set(1)` 后,控制器从调用时的当前值出发,在 600ms 内走向 1;渲染函数读 `alpha.ref.value`,所以矩形的透明度会跟着变化。动画进行中再次 `set`,会从当时的当前值转向新目标;`time` 为 `0` 时直接落到目标值。 + +### 设置渐变参数 + +如果某一次变化想用不同节奏,或者之后都换一条曲线、一个时长,可以在下一次 `set` 前调用 `mode(curve)` 或 `setTime(time)`: + +```tsx +// setup +import { linear } from '@motajs/animate'; + +// 这一次改用 300ms +alpha.set(0.4, 300); + +// 之后的 set 都改用线性曲线与 1200ms +alpha.mode(linear()); +alpha.setTime(1200); +``` + +`mode(curve)` 替换后续 `set` 使用的速率曲线;`setTime(time)` 替换后续 `set` 的默认时长。两者只影响之后的调用,不会重设当前正在进行的渐变。 + +把三步连起来,就是一次完整的数值渐变。下面的示例同时驱动透明度、位置与进度条: + +```tsx +// setup +import { transitioned } from '@motajs/render-vue'; +import { CurveMode, linear, sin } from '@motajs/animate'; + +const alpha = transitioned(0.25, 600, sin(CurveMode.EaseOut))!; +const slide = transitioned(0, 600, sin(CurveMode.EaseOut))!; +const bar = transitioned(0.3, 600, sin(CurveMode.EaseOut))!; + +const expand = () => { + alpha.set(1); + slide.set(1, 300); + bar.set(1); +}; + +bar.mode(linear()); +bar.setTime(1200); + +// 组件内容 + + + +``` + +下面的 live 用三组元素展示 `alpha`、位置与进度条的渐变。 + + + + + + +## 颜色渐变 + +颜色字符串不能直接做数值加减;自己拆成红、绿、蓝、透明四个通道再分别推进,也很麻烦。`transitionedColor` 把颜色当作一个整体:它内部拆通道、同步推进,最后再拼回颜色字符串。 + +### 获取颜色控制器 + +```tsx +// setup +import { transitionedColor } from '@motajs/render-vue'; +import { CurveMode, sin } from '@motajs/animate'; + +const fill = transitionedColor('#2f6fed', 600, sin(CurveMode.EaseOut))!; +``` + +`transitionedColor(color, time, curve)` 返回一个颜色渐变控制器,类型是 `ITransitionedController | null`。`color` 是初始颜色,`time` 是默认时长,`curve` 是速率曲线。它返回的控制器与数值渐变同形,但 `ref.value` 是当前颜色字符串,可以直接交给 `fillStyle`、`strokeStyle`。 + +支持的颜色写法有十六进制 `#rgb`、`#rgba`、`#rrggbb`、`#rrggbbaa`,以及 `rgb(r, g, b)` 与 `rgba(r, g, b, a)`。只支持这些写法;其他格式不会按预期渐变。 + +### 执行颜色渐变 + +```tsx +// setup +const warm = () => { + fill.set('#f2b84b'); +}; + +// 组件内容 +; +``` + +调用 `set` 后,控制器从当前颜色走向目标颜色;渲染函数读 `fill.ref.value` 得到中间颜色。`set`、`mode`、`setTime` 的用法与数值渐变一致。 + +### 设置颜色渐变参数 + +```tsx +// setup +import { linear } from '@motajs/animate'; + +// 这一次改用 300ms +fill.set('#7ee787', 300); + +// 之后的 set 都改用线性曲线与 1200ms +fill.mode(linear()); +fill.setTime(1200); +``` + +`set` 的第二个参数只覆盖这一次的时长;`mode` 与 `setTime` 改的是之后的调用。 + +把填充色与描边色放进同一个示例: + +```tsx +// setup +import { transitionedColor } from '@motajs/render-vue'; +import { CurveMode, sin } from '@motajs/animate'; + +const fill = transitionedColor('#2f6fed', 600, sin(CurveMode.EaseOut))!; +const stroke = transitionedColor( + 'rgba(242, 184, 75, 0.9)', + 600, + sin(CurveMode.EaseOut) +)!; + +fill.set('#f2b84b'); +stroke.set('#7ee787'); + +// 组件内容 + + +``` + +下面的 live 同时渐变填充色与描边色。 + + + + + + +## 循环渐变 + +呼吸灯、闪烁这类效果需要数值在两个端点之间反复往返。每次到端点都手动重设目标,很容易接不上;`cycledTransition` 把往返过程包成一个自动循环的控制器。 + +### 获取循环控制器 + +```tsx +// setup +import { cycledTransition } from '@motajs/render-vue'; +import { CurveMode, sin } from '@motajs/animate'; + +// 在 0.25 与 1 之间往返,单程 900ms +const glow = cycledTransition(0.25, 1, 900, sin(CurveMode.EaseOut))!; +``` + +`cycledTransition(min, max, time, curve, maxStart = false)` 返回一个循环渐变控制器,类型是 `ICycledTransitionController | null`。`min` 与 `max` 是循环的两个端点,`time` 是单程耗时(毫秒),`curve` 是单程使用的速率曲线;`maxStart` 为 `true` 时从 `max` 开始,否则从 `min` 开始。控制器返回后会自动开始循环,组件卸载时停止,不需要手动清理。 + +### 读取循环值 + +循环已经自动开始,渲染时读 `glow.ref.value` 就能拿到当前值: + +```tsx +// 组件内容 + +``` + +这个圆形的透明度会在 0.25 与 1 之间反复变化。到端点后控制器会自动把目标切到另一端,不需要再调用 `set`。 + +### 设置循环参数 + +```tsx +// setup +import { linear } from '@motajs/animate'; + +const narrow = () => { + glow.setRange(0.5, 1); +}; + +glow.mode(linear()); +glow.setTime(1200); + +// 组件内容 +; +``` + +`setRange(min, max)` 修改循环的两个端点,并立即按新区间重新确定这一次的目标;`mode(curve)` 与 `setTime(time)` 修改后续单程使用的曲线与时长。 + +把两个循环放进同一个示例: + +```tsx +// setup +import { cycledTransition } from '@motajs/render-vue'; +import { CurveMode, linear, sin } from '@motajs/animate'; + +const glow = cycledTransition(0.25, 1, 900, sin(CurveMode.EaseOut))!; +const core = cycledTransition(0.5, 1, 900, linear(), true)!; + +const widen = () => { + glow.setRange(0.5, 1); +}; + +// 组件内容 + + +``` + +下面的 live 用两个滑动条分别调整循环的起点与终点,轨道上的圆点显示当前值。 + + + + + + +需要编排多对象、控制激励源或直接操作单个数值渐变时,继续读[动画曲线](../internals/animation-curves.md)、[动画激励](../internals/animation-excitation.md)、[动画执行器](../internals/animation-runner.md)与[渐变执行器](../internals/animation-transition.md)。 + + diff --git a/docs/render-guide/index.md b/docs/render-guide/index.md index 6ef34f1..96e466e 100644 --- a/docs/render-guide/index.md +++ b/docs/render-guide/index.md @@ -2,14 +2,15 @@ 本指南只讲画屏幕 / 写 UI:怎样用 TSX 画出界面、摆好位置、处理交互、拆成组件,以及 UI 系统与性能的取舍。数据端、存档与录像、插件系统、编辑器等与绘制屏幕关系不紧密的系统不在这里讲,仍见中级 / 高级教程;普通教程只保留主要的渲染逻辑,具体写法集中到本指南。 -本指南只收现有 27 篇自定义 UI 文档,不新增系统文档,也不增设系统页面。 +本指南只收现有 32 篇自定义 UI 文档,内容分为渲染基础、渲染进阶与渲染底层三层;不新增系统文档,也不增设系统页面。 -## 两级结构 +## 三级结构 -| 分区 | 定位 | 页面数 | -| -------- | -------------------------------------------- | ------ | -| 渲染基础 | 模板、元素、坐标、图形、文字与元素属性 | 10 | -| 渲染进阶 | 响应式、事件、组件化、UI 系统/性能与完整示例 | 17 | +| 分区 | 定位 | 页面数 | +| -------- | ---------------------------------------------- | ------ | +| 渲染基础 | 模板、元素、坐标、图形、文字与元素属性 | 10 | +| 渲染进阶 | 响应式、事件、动画、组件化、UI 系统/性能与示例 | 18 | +| 渲染底层 | 动画曲线、动画激励、执行器与渐变的内部实现 | 4 | 分层是深度标签,不是领域分类:同一层里可能既有元素,也有组件或示例;读到哪一层取决于你要解决的问题,不必按层读完全部页面。 @@ -18,6 +19,8 @@ - **完全没写过 UI**:从 [UI 通用模板(TSX)](./basics/ui-template.md) 起步,先拿模板跑起来,再用 [UI 入门](./basics/ui-basics.md) 认识标签、组件与渲染树。 - **写过基础界面,想加交互与组件**:从[响应式](./advanced/reactivity.md)接手,把状态、事件与条件渲染接进已有界面。 - **想了解 UI 系统与性能**:从 [UI 系统](./advanced/ui-system.md)读起,再看 [UI 性能](./advanced/ui-performance.md)的日常优化习惯。 +- **想让界面元素平滑变化**:从[动画](./advanced/animation.md)入手,用 `transitioned`、`transitionedColor` 与 `cycledTransition` 做数值、颜色和循环渐变。 +- **想弄清动画曲线与底层怎么推进**:先读[动画曲线](./internals/animation-curves.md),再看[动画激励](./internals/animation-excitation.md)、[动画执行器](./internals/animation-runner.md)与[渐变执行器](./internals/animation-transition.md)。 ## 阅读路径 @@ -25,8 +28,9 @@ - **从静态到交互**:[响应式](./advanced/reactivity.md) → [事件与交互](./advanced/events.md) → [条件渲染与循环渲染](./advanced/conditional-and-list-rendering.md) → [按键与快捷键](./advanced/hotkey-in-ui.md) → [什么是组件](./advanced/what-is-component.md) → [自定义组件](./advanced/custom-components.md)。适合界面已经画出来、要接数据和操作的时候。 - **做一个完整面板**:[示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md) → [示例(二)道具网格](./advanced/inventory-example-2-grid.md) → [示例(三)详情区](./advanced/inventory-example-3-detail.md) → [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md) → [示例(五)交互与状态](./advanced/inventory-example-5-state.md) → [示例(六)动画、拆分与注册](./advanced/inventory-example-6-animation-and-register.md)。适合把零件装成背包 / 装备面板。 - **改内置 UI 或做性能取舍**:[什么是组件](./advanced/what-is-component.md) → [内置组件:基础](./advanced/builtin-basic.md) → [内置组件:布局](./advanced/builtin-layout.md) → [内置组件:文本](./advanced/builtin-text.md) → [自定义组件](./advanced/custom-components.md) → [UI 系统](./advanced/ui-system.md) → [UI 性能](./advanced/ui-performance.md)。适合替换现成控件或处理缓存与列表开销。 +- **让数值与颜色动起来**:[响应式](./advanced/reactivity.md) → [动画](./advanced/animation.md) → 需要更深时读[动画曲线](./internals/animation-curves.md) → [动画激励](./internals/animation-excitation.md) → [动画执行器](./internals/animation-runner.md) / [渐变执行器](./internals/animation-transition.md)。适合给界面加过渡、循环闪烁或颜色变化。 -四条路径都建议先读 [UI 通用模板(TSX)](./basics/ui-template.md);模板是后面所有页面的起点。 +五条路径都建议先读 [UI 通用模板(TSX)](./basics/ui-template.md);模板是后面所有页面的起点。 ## 页面目录 @@ -47,25 +51,35 @@ ### 渲染进阶 -| 篇目 | 一句话说明 | 前置 | -| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| [响应式](./advanced/reactivity.md) | 数据变化如何自动推到画布元素,以及渲染函数读到什么才算依赖 | [UI 入门](./basics/ui-basics.md)、[第一个静态界面](./basics/first-static-ui.md) | -| [事件与交互](./advanced/events.md) | 点击、按下、抬起、移动、悬停与滚轮的捕获与冒泡 | [容器与坐标](./basics/container-and-coordinates.md)、[响应式](./advanced/reactivity.md) | -| [条件渲染与循环渲染](./advanced/conditional-and-list-rendering.md) | 用 `hidden` 或三元做条件、用 `.map()` 做循环 | [响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) | -| [按键与快捷键](./advanced/hotkey-in-ui.md) | 按键指令、分组、作用域,以及组件里怎么接 | [响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) | -| [什么是组件](./advanced/what-is-component.md) | 组件最基本的形态、props 的传法,以及组件与 `GameUI` 的关系 | [UI 入门](./basics/ui-basics.md) | -| [内置组件:基础](./advanced/builtin-basic.md) | `Input`、`Icons`、`Arrow`、`Selection`、`Progress`、`Background` 与 `Slider` | [什么是组件](./advanced/what-is-component.md) | -| [内置组件:布局](./advanced/builtin-layout.md) | `Scroll`、`Page`、`List` 与 `ListPage` 的区域与列表用法 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) | -| [内置组件:文本](./advanced/builtin-text.md) | `TextContent` 的折行与打字机、`ScrollText` 的自动滚动 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) | -| [自定义组件](./advanced/custom-components.md) | 怎么接收参数、发事件、留出内容位置与透传属性 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) | -| [UI 系统](./advanced/ui-system.md) | 控制器、实例与栈:打开关闭、隐藏显示与显示策略 | [事件与交互](./advanced/events.md) | -| [UI 性能](./advanced/ui-performance.md) | 一组日常习惯,用来减少不必要的绘制与内存占用 | [层级、变换与性能](./basics/layer-transform-performance.md)、[UI 系统](./advanced/ui-system.md) | -| [示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md) | 定下背包 / 装备面板的目标、组件拆分与骨架 | [第一个静态界面](./basics/first-static-ui.md)、[容器与坐标](./basics/container-and-coordinates.md) | -| [示例(二)道具网格](./advanced/inventory-example-2-grid.md) | 把道具数据、`ItemCell` 与 `ItemGrid` 填进左侧,让网格能显示与选中 | [示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md)、[基础图形](./basics/basic-shapes.md) | -| [示例(三)详情区](./advanced/inventory-example-3-detail.md) | 用 `ItemDetail` 填右侧:名称、数量、描述与空选中提示 | [示例(二)道具网格](./advanced/inventory-example-2-grid.md)、[文字](./basics/text.md)、[通用参数](./basics/common-props.md) | -| [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md) | 把普通网格换成 `Scroll`,并说明渲染树、事件与数据流的变化 | [示例(三)详情区](./advanced/inventory-example-3-detail.md)、[内置组件:布局](./advanced/builtin-layout.md) | -| [示例(五)交互与状态](./advanced/inventory-example-5-state.md) | 加 `ActionBar`:装备、使用、关闭,并把状态收口到面板 | [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md)、[响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) | -| [示例(六)动画、拆分与注册](./advanced/inventory-example-6-animation-and-register.md) | 让选中态与提示动起来,把代码落回文件并注册成 `GameUI` | [示例(五)交互与状态](./advanced/inventory-example-5-state.md)、[自定义组件](./advanced/custom-components.md)、[UI 系统](./advanced/ui-system.md) | +| 篇目 | 一句话说明 | 前置 | +| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| [响应式](./advanced/reactivity.md) | 数据变化如何自动推到画布元素,以及渲染函数读到什么才算依赖 | [UI 入门](./basics/ui-basics.md)、[第一个静态界面](./basics/first-static-ui.md) | +| [事件与交互](./advanced/events.md) | 点击、按下、抬起、移动、悬停与滚轮的捕获与冒泡 | [容器与坐标](./basics/container-and-coordinates.md)、[响应式](./advanced/reactivity.md) | +| [条件渲染与循环渲染](./advanced/conditional-and-list-rendering.md) | 用 `hidden` 或三元做条件、用 `.map()` 做循环 | [响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) | +| [按键与快捷键](./advanced/hotkey-in-ui.md) | 按键指令、分组、作用域,以及组件里怎么接 | [响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) | +| [什么是组件](./advanced/what-is-component.md) | 组件最基本的形态、props 的传法,以及组件与 `GameUI` 的关系 | [UI 入门](./basics/ui-basics.md) | +| [内置组件:基础](./advanced/builtin-basic.md) | `Input`、`Icons`、`Arrow`、`Selection`、`Progress`、`Background` 与 `Slider` | [什么是组件](./advanced/what-is-component.md) | +| [内置组件:布局](./advanced/builtin-layout.md) | `Scroll`、`Page`、`List` 与 `ListPage` 的区域与列表用法 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) | +| [内置组件:文本](./advanced/builtin-text.md) | `TextContent` 的折行与打字机、`ScrollText` 的自动滚动 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) | +| [自定义组件](./advanced/custom-components.md) | 怎么接收参数、发事件、留出内容位置与透传属性 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) | +| [动画](./advanced/animation.md) | 用曲线驱动 `transitioned`、`transitionedColor` 与 `cycledTransition`,让数值、颜色平滑变化或循环 | [响应式](./advanced/reactivity.md)、[UI 入门](./basics/ui-basics.md) | +| [UI 系统](./advanced/ui-system.md) | 控制器、实例与栈:打开关闭、隐藏显示与显示策略 | [事件与交互](./advanced/events.md) | +| [UI 性能](./advanced/ui-performance.md) | 一组日常习惯,用来减少不必要的绘制与内存占用 | [层级、变换与性能](./basics/layer-transform-performance.md)、[UI 系统](./advanced/ui-system.md) | +| [示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md) | 定下背包 / 装备面板的目标、组件拆分与骨架 | [第一个静态界面](./basics/first-static-ui.md)、[容器与坐标](./basics/container-and-coordinates.md) | +| [示例(二)道具网格](./advanced/inventory-example-2-grid.md) | 把道具数据、`ItemCell` 与 `ItemGrid` 填进左侧,让网格能显示与选中 | [示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md)、[基础图形](./basics/basic-shapes.md) | +| [示例(三)详情区](./advanced/inventory-example-3-detail.md) | 用 `ItemDetail` 填右侧:名称、数量、描述与空选中提示 | [示例(二)道具网格](./advanced/inventory-example-2-grid.md)、[文字](./basics/text.md)、[通用参数](./basics/common-props.md) | +| [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md) | 把普通网格换成 `Scroll`,并说明渲染树、事件与数据流的变化 | [示例(三)详情区](./advanced/inventory-example-3-detail.md)、[内置组件:布局](./advanced/builtin-layout.md) | +| [示例(五)交互与状态](./advanced/inventory-example-5-state.md) | 加 `ActionBar`:装备、使用、关闭,并把状态收口到面板 | [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md)、[响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) | +| [示例(六)动画、拆分与注册](./advanced/inventory-example-6-animation-and-register.md) | 让选中态与提示动起来,把代码落回文件并注册成 `GameUI` | [示例(五)交互与状态](./advanced/inventory-example-5-state.md)、[自定义组件](./advanced/custom-components.md)、[UI 系统](./advanced/ui-system.md) | + +### 渲染底层 + +| 篇目 | 一句话说明 | 前置 | +| ------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| [动画曲线](./internals/animation-curves.md) | `ExcitationCurve`、`CurveMode`、内置曲线与曲线计算函数 | [动画](./advanced/animation.md)、[响应式](./advanced/reactivity.md) | +| [动画激励](./internals/animation-excitation.md) | 激励源怎样驱动受激励对象,以及变速器与分频器如何接入 | [动画](./advanced/animation.md)、[响应式](./advanced/reactivity.md) | +| [动画执行器](./internals/animation-runner.md) | `Animater` 把多个对象的多个步骤组织成计划组并按时执行 | [动画激励](./internals/animation-excitation.md)、[动画](./advanced/animation.md)、[响应式](./advanced/reactivity.md) | +| [渐变执行器](./internals/animation-transition.md) | `Transition` 让单个数值平滑靠近目标值,处理曲线与结尾参考 | [动画激励](./internals/animation-excitation.md)、[动画](./advanced/animation.md)、[响应式](./advanced/reactivity.md) | ## 边界与注意 diff --git a/docs/render-guide/internals/animation-curves.md b/docs/render-guide/internals/animation-curves.md new file mode 100644 index 0000000..2fe642a --- /dev/null +++ b/docs/render-guide/internals/animation-curves.md @@ -0,0 +1,535 @@ +# 动画曲线 + +曲线把时间进度映射成数据取值:时间完成度从 `0` 走到 `1`,曲线返回一个数,动画系统再用它让数值从起始值逐步走到目标值。本篇是曲线的完整参考:先讲类型与四种模式,再按基础、缓动、双曲三组逐条列出内置曲线,每条曲线都配一个实时曲线图,带参数的曲线还可以在图上调整参数,最后汇总把曲线组合、变换、拼接与多维合并的计算函数。内置形状曲线与分组对照图的纵轴固定为 `0` 到 `1`;运算与变换的实时图按来源与结果的实际输出自适应纵轴范围,不裁剪曲线。高层用法与形状示例见[动画](../advanced/animation.md);单个数值的连续渐变见[渐变执行器](./animation-transition.md)。 + +## 前置知识 + +阅读本篇前,建议先读完: + +- [动画](../advanced/animation.md) +- [响应式](../advanced/reactivity.md) + +## 曲线与数据映射 + +曲线的类型是 `ExcitationCurve`,它只接收一个时间完成度,返回一个数: + +```ts +export type ExcitationCurve = (progress: number) => number; +``` + +- 输入是时间完成度,范围是 `0` 到 `1`;下面公式里记作 `x`。类型声明里的参数名是 `progress`,两者指同一个值。 +- 输出没有范围限制。动画系统不会把它裁剪到 `0` 到 `1`。 +- 曲线本身不知道起始值与目标值;它只回答「进度到这里时,映射结果是多少」。把结果用于计算当前值的动作由动画接口或执行器完成。 + +```ts +import { linear } from '@motajs/animate'; + +// 匀速曲线:x 为 0.5 时返回 0.5 +const curve = linear(); +console.log(curve(0.5)); +``` + +## 曲线模式 + +同一条曲线,换一个模式就会得到不同的快慢分布;先认识这四个模式,后面带 `mode` 参数的曲线才有共同的参照。 + +`CurveMode` 是曲线的模式枚举,默认值是 `CurveMode.EaseIn`: + +```ts +export const enum CurveMode { + /** 缓进快出 */ + EaseIn, + /** 快进缓出 */ + EaseOut, + /** 缓进缓出,中间快 */ + EaseInOut, + /** 快进快出,中间缓 */ + EaseCenter +} +``` + +| 模式 | 含义 | 形状 | +| ---------------------- | ---------------- | ------------------------------ | +| `CurveMode.EaseIn` | 缓进快出 | 从起点慢慢加速,越接近终点越快 | +| `CurveMode.EaseOut` | 快进缓出 | 起步快,接近终点逐渐减速 | +| `CurveMode.EaseInOut` | 缓进缓出,中间快 | 两端慢、中段最快 | +| `CurveMode.EaseCenter` | 快进快出,中间缓 | 两端快、中段最慢 | + +### 模式换算 + +已经有一条按「缓进快出」写好的曲线时,不必为四种模式各写一份;`applyCurveMode` 能在它外面套一层换算,得到新的形状。`applyCurveMode(func, mode)` 接收一条「缓进快出」曲线 $f(x)$,返回套用模式后的新曲线 $g(x)$: + +| 模式 | 换算 | +| ------------ | ------------------------------------------------------------------------------------ | +| `EaseIn` | $g(x) = f(x)$ | +| `EaseOut` | $g(x) = 1 - f(1 - x)$ | +| `EaseInOut` | $x < 0.5$ 时 $g(x) = \frac{f(2x)}{2}$;否则 $g(x) = 1 - \frac{f(2 - 2x)}{2}$ | +| `EaseCenter` | $x < 0.5$ 时 $g(x) = \frac{1 - f(1 - 2x)}{2}$;否则 $g(x) = \frac{1 + f(2x - 1)}{2}$ | + +```ts +import { applyCurveMode, CurveMode } from '@motajs/animate'; + +// 把一条缓进快出曲线 f(x) = x^2 换成快进缓出 +const easeOut = applyCurveMode((x: number) => x * x, CurveMode.EaseOut); +``` + +## 基础曲线 + +基础曲线不接收 `mode` 参数,形状只由自身参数决定。下面每个 live 都使用 `0` 到 `1` 的纵轴。 + +### 线性曲线 linear() + +没有参数,把输入 `x` 原样输出: + +$$ +f(x) = x,\quad x\in[0,1] +$$ + +输出始终在 `0` 到 `1`。下面的 live 没有控件,曲线固定为一条直线。 + + + + + + +### 阶梯曲线 step(k) + +参数 `k` 是分段数,取正整数。进度每走 `1/k`,输出跳变一次: + +$$ +f(x) = \frac{\lfloor x k \rfloor}{k},\quad x\in[0,1] +$$ + +live 把 `k` 限制在 `2` 到 `12`;`k` 越大,阶梯越细,输出仍在 `0` 到 `1`。 + + + + + + +### 常数曲线 constant(k) + +参数 `k` 是常数值,输出不随进度变化: + +$$ +f(x) = k,\quad x\in[0,1] +$$ + +输出始终等于 `k`,可以落在 `0` 到 `1` 之外。live 为了让曲线留在纵轴内,把 `k` 限制在 `0` 到 `1`;调整时看到的仍是同一条水平线。 + + + + + + +## 缓动曲线 + +缓动曲线以「缓进快出」为基准,接收可选的 `mode`,不传时默认 `CurveMode.EaseIn`。下面给出的是基准形状公式;切换模式后,曲线按上一节的换算改变快慢分布。 + +### 正弦曲线 sin(mode?) + +参数 `mode` 可选,默认 `CurveMode.EaseIn`: + +$$ +f(x) = 1 - \cos\left(\frac{x\pi}{2}\right),\quad x\in[0,1] +$$ + +基准形状从 `0` 走到 `1`。live 用四个按钮切换 `CurveMode`,曲线连续变化,可以直接看出快慢分布。 + + + + + + +### 正切曲线 tan(mode?) + +参数 `mode` 可选,默认 `CurveMode.EaseIn`: + +$$ +f(x) = \tan\left(\frac{x\pi}{4}\right),\quad x\in[0,1] +$$ + + + + + + +### 正割曲线 sec(mode?) + +参数 `mode` 可选,默认 `CurveMode.EaseIn`: + +$$ +f(x) = \sec\left(\frac{x\pi}{3}\right) - 1,\quad x\in[0,1] +$$ + + + + + + +### 幂曲线 pow(exp, mode?) + +`exp` 是指数,必需;`mode` 可选,默认 `CurveMode.EaseIn`。下面公式里把 `exp` 记作 `n`: + +$$ +f(x) = x^{n},\quad x\in[0,1] +$$ + +live 把 `exp` 限制在 `0.5` 到 `4`;`exp > 0` 时输出仍在 `0` 到 `1`。 + + + + + + +## 双曲曲线 + +三条双曲曲线同样接收可选的 `mode`,默认 `CurveMode.EaseIn`。`k` 是比例参数。 + +### 双曲余弦曲线 cosh(k = 2, mode?) + +`k` 默认 `2`;`mode` 可选,默认 `CurveMode.EaseIn`: + +$$ +f(x) = \frac{\cosh(xk) - 1}{\cosh(k) - 1},\quad x\in[0,1] +$$ + + + + + + +### 双曲正切曲线 tanh(k = 2, mode?) + +`k` 默认 `2`;`mode` 可选,默认 `CurveMode.EaseIn`: + +$$ +f(x) = 1 + \frac{\tanh((x - 1)k)}{\tanh(k)},\quad x\in[0,1] +$$ + + + + + + +### 双曲正割曲线 sech(k = 1, mode?) + +`k` 默认 `1`;`mode` 可选,默认 `CurveMode.EaseIn`: + +$$ +f(x) = \frac{1 - \operatorname{sech}(xk)}{1 - \operatorname{sech}(k)},\quad x\in[0,1] +$$ + + + + + + +## 曲线运算 + +现成曲线不够用时,不必从零写函数:先拿两条曲线做逐点运算,就能拼出叠加、衰减或复合后的形状。这一组函数把两条曲线逐点做运算,返回一条新曲线。下面的实时图里,蓝色与黄色是两条来源曲线,绿色是结果;纵轴按来源与结果的实际输出自适应,超出 `0` 到 `1` 的结果也会完整画出,函数本身不裁剪。 + +| 函数 | 结果 | +| -------------------------- | -------------------------- | +| `addCurve(curve1, curve2)` | $h(x) = f(x) + g(x)$ | +| `subCurve(curve1, curve2)` | $h(x) = f(x) - g(x)$ | +| `mulCurve(curve1, curve2)` | $h(x) = f(x) \cdot g(x)$ | +| `divCurve(curve1, curve2)` | $h(x) = \frac{f(x)}{g(x)}$ | +| `powCurve(curve1, curve2)` | $h(x) = f(x)^{g(x)}$ | +| `compositeCurve(c1, c2)` | $h(x) = c_1(c_2(x))$ | + +`compositeCurve` 是函数复合,`curve1` 是外层、`curve2` 是内层。其余五个函数都按同一进度逐点取值。 + +```ts +import { addCurve, constant, mulCurve, sin } from '@motajs/animate'; + +// 在正弦曲线上叠加一个固定偏移,再整体放大 +const lifted = addCurve(sin(), constant(0.2)); +const doubled = mulCurve(lifted, constant(2)); +``` + +### 相加 addCurve + +两条来源曲线逐点相加。结果可能超过 `1`,图中会按实际范围完整显示。 + + + + + + +### 相减 subCurve + +第一条曲线减第二条曲线。结果可能低于 `0`,图中同样按实际范围完整显示。 + + + + + + +### 相乘 mulCurve + +两条来源曲线逐点相乘。两条来源都落在 `0` 到 `1` 时,结果也落在 `0` 到 `1`。 + + + + + + +### 相除 divCurve + +第一条曲线除以第二条曲线。分母必须避开 `0`,示例用常数 `0.5` 作分母;结果超过 `1` 时按实际范围完整显示。 + + + + + + +### 取幂 powCurve + +第一条曲线作底数,第二条曲线作指数。底数保持非负时结果才有实数意义;示例用 `linear()` 作底、常数 `2` 作指数。 + + + + + + +### 复合 compositeCurve + +`compositeCurve(curve1, curve2)` 让外层 `curve1` 接收内层 `curve2` 的输出。示例的外层是 `sin()`,内层是 `pow(2)`。 + + + + + + +## 曲线变换 + +想保留曲线的基本形状,只把它整体抬高、翻转或压扁时,用这些变换,比重新写一条曲线省事。这一组函数改变一条曲线的整体位置、方向或尺度。下面的实时图按来源与结果的实际输出自适应纵轴范围,不裁剪曲线: + +| 函数 | 结果 | +| ----------------------------------- | --------------------------- | +| `moveCurve(curve, move = 0)` | $g(x) = f(x) + move$ | +| `oppositeCurve(curve, move = 0)` | $g(x) = move - f(x)$ | +| `scaleCurve(curve, scale = 1)` | $g(x) = f(x) \cdot scale$ | +| `reciprocalCurve(curve, scale = 1)` | $g(x) = \frac{scale}{f(x)}$ | + +此外,`normalize(curve)` 把曲线两端的值对齐到 `0` 与 `1`: + +$$ +g(x) = +\begin{cases} +\dfrac{f(x) - f(1)}{f(0) - f(1)}, & f(0) > f(1),\\[6pt] +\dfrac{f(x) - f(0)}{f(1) - f(0)}, & f(0) < f(1),\\[6pt] +f(x), & f(0) = f(1). +\end{cases} +$$ + +它只读 `curve(0)` 与 `curve(1)` 来选择参考端点,假定曲线单调,但不会检查或拒绝非单调曲线。非单调曲线仍按这两个端点归一化,中间取值可能落在 `[0, 1]` 之外;两端相等时原样返回。 + +### 平移 moveCurve + +给来源曲线加一个纵向偏移。结果超过 `1` 时按实际范围完整显示。 + + + + + + +### 取反 oppositeCurve + +以 `move` 为基准翻转来源曲线。`move` 为 `1` 时得到上下翻转、重新落回 `0` 到 `1` 的曲线。 + + + + + + +### 缩放 scaleCurve + +纵向缩放来源曲线。`scale` 小于 `1` 时整体压低,结果仍在 `0` 到 `1`。 + + + + + + +### 倒数 reciprocalCurve + +先取来源曲线的倒数,再乘缩放。来源取值在 `0.5` 到 `1`,避开分母过零;结果落在 `0.5` 到 `1`。 + + + + + + +### 归一化 normalize + +来源取 `0.2` 到 `0.8`,归一化后两端对齐到 `0` 与 `1`。它只用两端值决定方向,假定曲线单调,不会拒绝非单调曲线。 + + + + + + +## 曲线拼接 + +一段动画如果前半段和后半段要用不同节奏,单条曲线表达不了;`sequenceCurve` 能把几条现成曲线按时间比例接起来。`sequenceCurve(seq, duration, scale, move)` 把多条曲线按顺序拼成一条: + +- `seq`:曲线数组,按顺序执行。 +- `duration`:每段占用的时间比例,范围在 `0` 到 `1` 之间;各段之和通常应设为 `1`。 +- `scale`:每段输出在拼接时的缩放比例。 +- `move`:每段输出在拼接时的纵向偏移。 + +```ts +import { linear, sequenceCurve, sin } from '@motajs/animate'; + +// 参数依次是曲线序列、每段时长占比、每段缩放与每段偏移 +const curve = sequenceCurve([linear(), sin()], [0.5, 0.5], [1, 1], [0, 0]); +``` + +来源段各自都是完整的 `0` 到 `1` 形状,结果按 `duration` 分配的时间段依次取用。下面的实时图把两条来源段都画成完整曲线,绿色结果是两段各占一半时长的拼接结果。 + + + + + + +序列过长(超过约 100 段)可能影响性能;需要很多段时,先确认是否可以用公式直接表达。`duration` 之和不为 `1` 时的具体行为不在本篇的保证范围内,需要拼接时按总和 `1` 分配。 + +## 多维曲线 + +当一条曲线要同时给出多个分量(例如路径上的横纵坐标),或想把几组一维曲线当成一个整体传递时,就需要多维曲线。多维曲线本质是参数方程:同一个时间完成度同时输出多个值。相关类型有 `ExcitationCurve2D`、`ExcitationCurve3D` 与 `GeneralExcitationCurve`。 + +拆分把一条多维曲线变成多条一维曲线: + +| 函数 | 结果 | +| --------------------- | -------------------------- | +| `splitCurve2D(curve)` | $[c_1(x), c_2(x)]$ | +| `splitCurve3D(curve)` | $[c_1(x), c_2(x), c_3(x)]$ | +| `splitCurve(curve)` | 按维数拆成一维曲线数组 | + +合并把多条一维曲线组成一条多维曲线: + +| 函数 | 结果 | +| -------------------------------------- | ------------------------------------ | +| `stackCurve2D(curve1, curve2)` | $x \mapsto [c_1(x), c_2(x)]$ | +| `stackCurve3D(curve1, curve2, curve3)` | $x \mapsto [c_1(x), c_2(x), c_3(x)]$ | +| `stackCurve(curves)` | 任意维数的曲线;维数取数组长度 | + +```ts +import { + linear, + sin, + splitCurve, + splitCurve2D, + stackCurve2D +} from '@motajs/animate'; + +// 把一条二维曲线拆成两条一维曲线,再重新合成另一条二维曲线 +const [x, y] = splitCurve2D(stackCurve2D(linear(), sin())); +const [backX, backY] = splitCurve(stackCurve2D(x, y)); +console.log(backX(0.5), backY(0.5)); +``` + +多维曲线是参数曲线:同一个时间完成度同时给出多个分量,不是一个输入对应一个输出,所以不能画成单张「时间为横轴、单个取值为纵轴」的曲线图。`splitCurve3D` 与 `stackCurve3D` 只是多一维、多一列,`splitCurve` 与 `stackCurve` 则按任意维数处理。 + +## 边界与注意 + +- 输出不受 `0` 到 `1` 限制;不要为了「看起来正常」而把结果夹到区间内,否则过冲与回弹会失效。 +- `normalize` 只用两端值决定方向,假定曲线单调,但不会检查或拒绝非单调曲线;非单调曲线归一化后,中间取值可能超出 `[0, 1]`。 +- `divCurve` 与 `reciprocalCurve` 在分母为 `0` 的位置会产生 `Infinity` 或 `NaN`,组合时要确认除数不会过零。 +- `sequenceCurve` 的各段 `duration` 之和通常应设为 `1`;不要依赖总和不为 `1` 时的具体行为。 +- 曲线函数应当是纯函数;不要在曲线里读写外部状态,它会在每一帧被反复调用。 + + diff --git a/docs/render-guide/internals/animation-excitation.md b/docs/render-guide/internals/animation-excitation.md new file mode 100644 index 0000000..7db0cd8 --- /dev/null +++ b/docs/render-guide/internals/animation-excitation.md @@ -0,0 +1,344 @@ +# 动画激励 + +动画不会自己动:需要有人按节奏推一下。动画激励把这件事拆成两半——激励源决定什么时候推,受激励对象决定被推时做什么。动画执行器与渐变执行器都是受激励对象,所以能挂在同一个激励源上。 + +本篇按「受激励对象是什么、激励源是什么、四种内置激励源怎么用、组件里怎么接」的顺序讲。变速器与分频器本身也是激励源,会放在内置激励源里一起说明。 + +## 前置知识 + +阅读本篇前,建议先读完: + +- [动画](../advanced/animation.md) +- [响应式](../advanced/reactivity.md) + +## 激励模型 + +系统里有三个角色: + +| 角色 | 是什么 | 负责 | +| ------------------------- | ---------------------- | -------------------------------------- | +| `IExcitable` | 受激励对象 | 接收一次负载,执行自己的处理 | +| `IExcitation` | 激励源 | 决定什么时候推进,并管理所有受激励对象 | +| `IExcitableController` | 单个受激励对象的控制器 | 解除这次登记,或手动推进这一个对象 | + +「激励」就是按节奏推进一次:激励源把当前的负载交给每个登记过的对象。负载的类型由具体激励源决定;动画系统里的激励源都传数字时间,所以执行器接收的是 `number`。 + +激励源不关心对象是动画、渐变还是普通回调;动画执行器与渐变执行器都是 `IExcitable`,所以能挂在同一个激励源上。 + +```mermaid +flowchart LR + S[激励源] -->|负载| A[受激励对象 A] + S -->|负载| B[受激励对象 B] + S -->|add| C[控制器] -->|revoke| S +``` + +当一个激励源把另一个激励源当作时间来源时,本篇把前者叫 **输入源**,把登记在它上面、接收它推进的对象叫 **接收方**。例如变速器从输入源读取时间,再把换算后的时间交给接收方。 + +## 受激励对象 + +`IExcitable` 不需要继承任何类,也没有别的成员;它只要求一个具体方法 `excited(payload: T): void`。激励源每次推进时调用这个方法,`payload` 就是这次传来的负载。 + +```ts +import { IExcitable } from '@motajs/animate'; + +// 受激励对象:每次被推进时记下负载 +class TimeRecorder implements IExcitable { + last = 0; + + excited(payload: number): void { + this.last = payload; + } +} +``` + +要让激励源每次推进都通知它,需要把它登记进去。`add` 返回一个控制器;控制器只管理这一个对象,不影响同一个源上的其他接收方: + +```ts +import { RafExcitation } from '@motajs/animate'; + +const source = new RafExcitation(); +const recorder = new TimeRecorder(); + +// 登记后,源每推进一次,recorder 就收到一次时间 +const controller = source.add(recorder); + +// 只推进 recorder 一个对象,不广播给其他接收方 +controller?.excite(source.payload()); + +// 解除登记;之后源不会再推进这个对象 +controller?.revoke(); +``` + +`IExcitableController` 就是 `add` 返回的控制器,包含三个成员: + +- `excitable`:被登记的那个对象。 +- `revoke()`:把对象从当前激励源移除。 +- `excite(payload)`:只推进这一个对象,不广播给其他对象。 + +### 包装函数 excited + +如果手上只有一段函数,不想为它单独写一个类,`excited(func, thisArg?)` 可以把它包成 `IExcitable`: + +```ts +import { excited } from '@motajs/animate'; + +// 把函数包成受激励对象;每次激励时函数收到负载 +const recorder = excited(payload => { + console.log(payload); +}); +``` + +它返回的对象只有一个 `excited` 方法:每次激励源推进时调用 `func(payload)`,不会替调用方保存状态。包装后的对象可以直接交给 `add`、`onExcited` 等接收 `IExcitable` 的地方。 + +包装只提供 `excited`,不提供 `revoke` 或 `excite`;要解除登记或单独推进,仍然使用 `add` 返回的控制器。需要保存状态、读取上一次负载或提供多个方法时,写一个实现 `IExcitable` 的类更清楚。 + +`thisArg` 可选,用来固定 `func` 执行时的 `this`;省略时函数按原来的方式调用。 + +## 激励源接口 + +自带激励源之外,有时需要替换节奏或自己实现一个。无论哪种,都要满足同一套契约;内置激励源已经实现好,只有自己写源时才需要逐项实现。 + +| 成员 | 作用 | +| ----------------- | ----------------------------------------------------- | +| `payload()` | 读取当前负载 | +| `excite(payload)` | 把负载广播给当前所有受激励对象 | +| `add(object)` | 登记一个受激励对象,返回控制器;无法登记时返回 `null` | +| `remove(object)` | 移除一个受激励对象,返回是否移除成功 | +| `destroy()` | 终止激励源,停止继续推进 | + +`payload()` 回答「现在的时间或值是多少」,`excite()` 回答「把这一刻发给谁」。帧激励源每帧更新当前时间后调用一次 `excite()`;固定间隔激励源按定时器调用;变速器与分频器则在收到输入源的推进后,按自己的规则再推进接收方。 + +## 内置激励源 + +内置激励源分两类:帧激励源与固定间隔激励源负责产生时间,变速器与分频器负责加工另一个激励源的时间或次数。下面每个都先说为什么需要,再给一段最小用法,最后说明接收方会收到什么。 + +### 帧激励源 + +界面动画通常希望跟着屏幕刷新走;帧激励源就是这条默认节奏,根渲染器默认也用它。 + +`RafExcitation` 用 `requestAnimationFrame` 驱动,每一帧把当前时间戳作为负载广播出去。它最直接的用法是接到动画执行器上: + +```ts +import { Animater, RafExcitation } from '@motajs/animate'; + +const source = new RafExcitation(); +const animater = new Animater(); + +// 把执行器登记到帧激励源;之后执行器每帧被推进一次 +source.add(animater); +``` + +接收方拿到的负载是 `requestAnimationFrame` 的时间戳,单位毫秒,例如 `1234.5`。它不是从 `0` 开始的动画时间,而是浏览器给这一帧的时间;相邻两帧的差值反映这一帧间隔了多久。 + +- `payload()` 返回最近一帧的时间戳。 +- 构造时立即开始请求下一帧,所以第一次推进发生在下一帧,不是构造的瞬间。 +- `destroy()` 取消尚未执行的帧请求。 + +渲染器的根元素默认使用一个 `RafExcitation`,所以组件里拿到的动画执行器通常不需要自己创建激励源。 + +下面的 live 显示当前载荷、相邻两帧的时间差与已过的帧数。 + + + + + + +### 固定间隔激励源 + +有些逻辑只需要稳定节奏,不必跟屏幕刷新同步;固定间隔激励源按定时器推进,节奏由构造时传入的间隔决定。 + +`IntervalExcitation` 实现 `IIntervalExcitation`,用固定毫秒间隔触发。登记一个接收方后,它会按间隔反复推进: + +```ts +import { IntervalExcitation } from '@motajs/animate'; + +const source = new IntervalExcitation(100); +// 复用前面的 TimeRecorder +const recorder = new TimeRecorder(); + +// 约每 100ms 推进一次;接收方依次收到 0、100、200…… +source.add(recorder); +``` + +它用内部计数当负载:触发时先把当前计数发出去,再把计数加一个 `interval`。所以接收方依次拿到 `0`、`interval`、`2 × interval`……;`payload()` 返回计数器的当前值,第一次触发后它已经变成 `interval`。 + +这个计数不跟随真实时间(墙钟时间),也不保证每一次都恰好落在整百毫秒上。需要和真实时间对齐时,使用帧激励源。 + +### 变速器 + +需要整体放慢、加速,或让速度平滑变化时,不必改每个动画的时长;把变速器接在一个激励源后面,就能统一改变时间流速。 + +`ExcitationVariator` 实现 `IExcitationVariator`,本身就是一种 `IExcitation`。它先订阅一个输入源,再把输入时间按当前速度换算成自己的时间,最后用自己的时间推进接收方。 + +```ts +import { Animater, ExcitationVariator, RafExcitation } from '@motajs/animate'; + +const input = new RafExcitation(); +const variator = new ExcitationVariator(); +const animater = new Animater(); + +// 以帧激励源为输入源;绑定后速度重置为 1 +variator.bindExcitation(input); + +// 执行器登记在变速器上,收到的是变速器换算后的时间 +variator.add(animater); + +// 输入时间每前进 10ms,执行器只前进 5ms +variator.setSpeed(0.5); +``` + +接收方拿到的是变速器时间轴上的时间,不是输入源的原始时间。绑定时它从输入源当前时间起步;之后每次输入推进,它把「输入前进了多少」乘以当前速度,累加到自己的时间上,再发给接收方。`payload()` 返回这个时间。 + +速度改变的是时间流速,不是动画配置里的时长。一个动画在变速器时间轴上配置为 `400`,速度设为 `0.5` 后,它仍然需要变速器时间轴前进 `400`;只是这段变速器时间现在要用两倍的真实时间才能走完。改变速度不会重算已经过去的时间,只影响之后的推进。 + +`setSpeed` 必须放在 `bindExcitation` 之后:未绑定时它不会生效。绑定时速度会重置为 `1`,所以先绑定、再设置速度。 + +下面的 live 显示输出端连续两次时间的差值。切换速度后,相邻两次推进的时间差会随之改变。 + + + + + + +### 变速曲线 + +直接改速度会让时间流速瞬间跳变;需要慢慢加速或减速时,用 `curveSpeed` 在一段时间内按曲线改变速度。 + +`curveSpeed(curve, time, mode?)` 让速度在 `time` 毫秒内按曲线变化,返回一个 Promise,在曲线结束时兑现。已经有一条曲线在运行时,新曲线会排在它后面。 + +```ts +import { linear } from '@motajs/animate'; + +// 在输入源时间 300ms 内,速度从 1 线性降到 0.5 +await variator.curveSpeed(x => 1 - 0.5 * x, 300); +``` + +曲线的输入是这段时间的完成度,输出就是当前速度。第三个参数 `VariatorCurveMode` 决定曲线进度按哪条时间轴计算: + +| 模式 | 曲线进度按谁走 | +| --------------------------------- | ---------------------------------------------- | +| `VariatorCurveMode.SourceRelated` | 按输入源的时间走,速度变慢不会拖慢曲线本身 | +| `VariatorCurveMode.SelfRelated` | 按变速器自己的时间走,速度变慢时曲线也一起变慢 | + +默认是 `SourceRelated`。 + +下面的 live 用一条从 `1.5` 降到 `0.25` 的变速曲线演示这一点。它显示当前速度、输出端最后两次推进的时间,以及两者的时间差。速度越高,输出端时间推进越快,相邻两次推进的时间差也越大。 + + + + + + +### 分频器 + +不是每一次激励都需要处理,例如只需要低频刷新的逻辑;分频器把输入源的多次激励压成一次,减少接收方的更新次数。 + +`ExcitationDivider` 实现 `IExcitationDivider`,也是 `IExcitation`。它接收输入源的每一次推进,但只把其中一部分继续发给接收方。 + +```ts +import { ExcitationDivider, IntervalExcitation } from '@motajs/animate'; + +const input = new IntervalExcitation(100); +const divider = new ExcitationDivider(); +// 复用前面的 TimeRecorder +const recorder = new TimeRecorder(); + +// 绑定后分频比为 1,输入推进一次就转发一次 +divider.bindExcitation(input); +divider.add(recorder); + +// 之后输入每推进 3 次,接收方收到 1 次 +divider.setDivider(3); +``` + +接收方收到的负载仍是输入源传来的那一份,只是有些推进被丢掉了。`payload()` 返回最近一次转发出去的负载;从未绑定输入源时读取它会报错。 + +分频器改变的是激励次数,不是时间速度。它不能用来让动画整体变慢——那应该使用变速器。`setDivider` 可以在绑定后调用;未绑定时调用不会生效,也不会报错。 + +`divider` 是当前分频比例,默认 `1`。设置后,下一次输入推进会立即转发一次,之后每隔 `divider` 次输入推进再转发一次。 + +下面的 live 用固定间隔激励源驱动分频器:左侧是输入源的原始载荷与次数,右侧是接收方实际收到的载荷与次数。改变分频比后,接收方次数按比例减少,但收到的载荷仍是输入源传来的那一份。 + + + + + + +## 组件内的激励接入 + +渲染端把整块 UI 挂在一棵渲染树上,树的最顶层叫根渲染器;它自带一个激励源。渲染端还提供了两个组件内辅助函数,用来把每帧逻辑挂到根渲染器的激励源上。 + +### 登记受激励对象 onExcited + +已经有一个 `IExcitable`,又希望它跟着根渲染器的激励源每帧推进时,用 `onExcited`。手动 `add` 到根激励源也能做到,但组件卸载时容易漏掉移除,留下泄漏;这个函数把登记与清理放在一起。 + +`onExcited(excitable: IExcitable): void` 接收一个受激励对象,不接收函数。它只能在组件的 `setup` 或生命周期钩子中调用;在组件外调用不会生效。 + +```ts +import { onExcited } from '@motajs/render-vue'; + +// 复用前面的 TimeRecorder +const recorder = new TimeRecorder(); + +// 只在组件 setup 或生命周期钩子中调用 +onExcited(recorder); +``` + +调用后,根渲染器每帧推进时 `recorder.excited(time)` 会收到当前帧的时间戳。它返回 `void`,没有可操作的控制器;组件卸载时会自动移除登记,根渲染器变化时也会在新根上重新登记。不要在组件外使用它,也不要在卸载后继续依赖这个登记。 + +### 包装函数 onExcitedFunc + +每帧逻辑如果只是一段函数,不想先写一个 `IExcitable` 类,用 `onExcitedFunc`。它把函数包成受激励对象再登记,省掉手工包装。 + +`onExcitedFunc(func: (time: number) => void): void` 接收一个每帧调用的函数,参数是根渲染器当前帧的时间戳。它同样只能在组件的 `setup` 或生命周期钩子中调用;在组件外调用不会生效。 + +```ts +import { onExcitedFunc } from '@motajs/render-vue'; + +let elapsed = 0; + +// 只在组件 setup 或生命周期钩子中调用 +onExcitedFunc(time => { + // time 是根渲染器当前帧的时间戳 + elapsed = time; +}); +``` + +它内部用 `excited(func)` 包装后交给 `onExcited`,所以清理行为与 `onExcited` 相同:组件卸载时自动移除登记,根渲染器变化时重新登记。包装后的对象不保存状态;需要读取上一次负载或提供多个方法时,仍然写一个实现 `IExcitable` 的对象,再用 `onExcited` 登记。 + +## 与两个执行器的关系 + +`Animater` 与 `Transition` 都实现 `IExcitable`,因此: + +- 它们可以绑定任意数字激励源,包括 `RafExcitation`、`IntervalExcitation`、`ExcitationVariator` 与 `ExcitationDivider`。 +- 变速器与分频器也是激励源,可以接在执行器前面,分别改变时间流速与激励次数。 + +高层封装如 `transitioned`、`transitionedColor` 与 `cycledTransition` 也共享同一套根激励源,因此不需要再单独创建时钟。 + +## 边界与注意 + +- 变速器与分频器都要先绑定输入源才能工作;变速器未绑定时 `setSpeed` 不生效,分频器从未绑定输入源时读取 `payload()` 会报错。 +- 变速器绑定输入源时会把速度重置为 `1`,并把自己的时间对齐到输入源的当前时间;需要别的速度就在绑定之后设置。 +- `onExcited` 与 `onExcitedFunc` 只适用于组件内部;组件外要自己创建 `IExcitable` 并手动登记、移除。 +- 变速器改变的是时间流速,分频器改变的是激励次数;用分频器让动画变慢会跳过中间帧,不会拉长动画时间。 + + diff --git a/docs/render-guide/internals/animation-runner.md b/docs/render-guide/internals/animation-runner.md new file mode 100644 index 0000000..2eca344 --- /dev/null +++ b/docs/render-guide/internals/animation-runner.md @@ -0,0 +1,570 @@ +# 动画执行器 + +动画执行器 `Animater` 实现 `IAnimater`,负责把多个动画对象的多个步骤组织成一条时间线。它关心的是「谁在第几步动、下一步什么时候开始」,而不是单个数值的平滑过渡;一个数从当前值靠近目标值,用[渐变执行器](./animation-transition.md)。 + +## 前置知识 + +阅读本篇前,建议先读完: + +- [动画曲线](./animation-curves.md) +- [动画激励](./animation-excitation.md) +- [动画](../advanced/animation.md) +- [响应式](../advanced/reactivity.md) + +## 获取执行器与激励接入 + +执行器自己不产生时间:它只接收外部传来的时间戳,再据此推进计划。推动它的对象叫**激励源**:例如 `RafExcitation` 每帧把当前时间戳推给执行器一次。没有接上激励源时,计划可以写好,但一步都不会执行。所以动手编排之前,先要知道执行器从哪里来、怎样接上时间。 + +### 组件内获取 + +组件里通常不自己创建执行器:手写 `new` 既要记得绑定激励源,又容易在组件卸载后继续持有。`useAnimater(anim?, excitation?)` 返回 `IAnimater | null`,只能在组件的 `setup` 或生命周期钩子中调用;它默认把执行器接到根渲染器的激励源上,根渲染器变化时重新绑定,组件卸载时解除绑定。 + +不传执行器时,它内部新建一个,并在卸载时一并销毁;传入已有执行器时,只负责绑定与解绑,执行器仍由调用方持有。需要显式指定激励源时,传第二个参数。使用 `useAnimater` 时,不需要自己调用 `destroy()`。 + +```ts +import { ref } from 'vue'; +import { useAnimater } from '@motajs/render-vue'; + +const x = ref(0); + +// 只能在组件 setup 或生命周期钩子中调用; +// 它绑定根渲染器的激励源,并在组件卸载时自动解绑。 +const animater = useAnimater()!; // 尚无当前对象;尚无步骤;取得执行器 +``` + +### 手动创建 + +不在组件里时,`useAnimater` 会返回 `null`,这时可以自己 `new Animater()`。它可以在普通 JavaScript 允许的任何位置创建;但执行器不会自己找时间,必须由你调用 `bindExcitation(excitation)` 把它接到一个数字激励源上。之后用 `unbindExcitation()` 解除绑定,也可以再接到别的源。 + +手动创建的执行器由调用方负责生命周期。需要停止并重置时调用 `destroy()`:它会解绑激励源,并清掉已定义与正在执行的计划。这个清理是手动创建的场景才需要的;使用 `useAnimater` 时,卸载清理已经由它完成。 + +```ts +import { Animater, RafExcitation } from '@motajs/animate'; + +const excitation = new RafExcitation(); // 尚无当前对象;尚无步骤;创建激励源 +// 可在普通 JS 中创建;执行器不会自己找时间。 +const animater = new Animater(); // 尚无当前对象;尚无步骤;创建执行器 + +// 必须自己绑定激励源;不绑定就不会推进。 +animater.bindExcitation(excitation); // 尚无当前对象;尚无步骤;绑定执行器自己的激励源 + +// 不再需要推进时解绑;之后可以重新绑定。 +animater.unbindExcitation(); // 尚无当前对象;尚无步骤;解绑激励源 +``` + +两种方式绑定的不是同一个激励源:`useAnimater` 默认绑根渲染器的激励源;`new Animater` 绑你传给 `bindExcitation` 的那个源。重复绑定同一个源不会重复登记。 + +## 计划模型 + +动画是某个可写数值从当前值走向目标值的一段过程。一次动画至少要回答三件事:哪个数值、走向哪个目标、用多久;曲线决定这段时间里快慢怎么变。 + +定义动画就是把这几项信息写进一条时间线:先确定动画对象,再确定曲线,然后写步骤。步骤只记录意图,不会立刻修改对象的数值;提交整组之前,数值保持原样。 + +每个步骤都有开始与结束两个时刻,后续步骤可以挂在其中一个时刻上,再等待若干毫秒。挂在开始时刻上的称为**开始触发**,挂在结束时刻上的称为**结束触发**;触发点上可以继续挂步骤,于是形成顺序、延迟与重叠。 + +- **并行**:同一组里没有挂到任何触发点上的步骤,会随组开始一起启动。 +- **顺序**:把后一段挂到前一段的结束触发上;前一段结束、等待一段时间后,后一段才开始。 +- **延迟与重叠**:把后一段挂到前一段的开始触发上;前一段开始、等待一段时间后,后一段就启动。结束触发等待 `0` 表示紧接着开始,开始触发等待 `0` 表示同时开始。 +- **计划组**:一次提交的步骤集合是一组。组与组之间串行:后一组要等前一组的全部步骤、以及这些步骤上的触发点都结束,再经过组后等待,才真正开始。组内可以并行,组间不重叠。 +- **等待点**:每个步骤结束时会兑现一个完成信号;也可以按组内编号查到某个步骤的目标值、时长、曲线和完成信号,再等待它。完成信号只代表这个步骤结束,不代表整组结束。 + +下面的 live 用真实执行器播放一组计划:上方是对象 A 与 B 的当前值,下方色块是步骤段,竖线是播放头。播放头本身也是一条同组同时长的步骤,不是页面定时器。 + + + + + + +## 动画对象的选择 + +为了让动画系统知道它该如何执行动画、将当前值写入哪个对象,就必须先使用 `animate` 接口来绑定动画对象。`animate(content: IAnimatable): this` 选中的对象必须满足 `IAnimatable`:一个带可写 `value` 的对象;Vue 的 `ref` 就满足这个形状。执行器只改这个字段,不负责把值画到画布。 + +`animate` 只改变「之后的操作作用在谁身上」,本身不新增步骤,也不移动任何值。同一个对象在一个计划组里可以多次出现,它的步骤编号会继续累加。没有先选对象就调用 `to` 时,执行器不会添加任何步骤——计划看起来写了,实际不会动,所以选择对象要放在写步骤之前。 + +```ts +import { ref } from 'vue'; +import { useAnimater } from '@motajs/render-vue'; + +const x = ref(0); +const animater = useAnimater()!; + +animater.animate(x); // 当前对象:x;尚无步骤;选择 x 作为动画对象 +``` + +## 曲线 + +一条步骤只知道从当前值走向目标值、用多久;如果不再说明过程中的快慢,系统只能用匀速。`curve(curve: ExcitationCurve): this` 就是为此设置速率曲线的。`ExcitationCurve` 是 `(progress: number) => number`,把 `0`–`1` 的时间进度映射成一个数;不设置时使用线性曲线。 + +时间进度从 `0` 走到 `1`。曲线在当前进度下的返回值表示此时刻动画的完成度:为 `0` 时动画处于起点,为 `1` 时刚好执行到目标值,中间按曲线返回的比例推进。曲线返回值超出 `0` 到 `1` 时,值会越过目标或朝反方向走。 + +曲线在定义步骤时记入步骤,之后再改 `curve` 不会影响已经定义好的步骤。它会一直作用于后续步骤,直到再次调用 `curve`;`planEnd` 不会把它恢复成线性。 + +```ts +import { sin } from '@motajs/animate'; + +const x = ref(0); + +animater + .animate(x) // 当前对象:x;尚无步骤;选择 x + .curve(sin()) // 当前对象:x;尚无步骤;设置当前曲线 + .to(1, 400) // 当前对象:x;新增索引 1;写入步骤 + .planEnd(); // 当前对象:x;索引 1;结束本组,当前对象清空 +``` + +## 步骤与终值 + +计划模型与选好的对象还只是准备,要真正让某个值动起来,必须追加一条具体步骤:从当前值走到哪个目标值、用多久。`to(value: number, time: number, end: EndRelation = EndRelation.Target): this` 就是用来追加这条步骤的。不调用 `to`,再完整的模型也不会产生动画。 + +`value` 是目标值,`time` 是时长(毫秒),`end` 是结束参考方式。调用 `to` 只把步骤写进当前组,不会立刻修改动画对象的值;要等组开始并执行到这一步时才生效。如果当前正挂着开始触发或结束触发,这条步骤会挂到触发点,而不是随组开始;没有触发点时,它才是组启动步骤。 + +`EndRelation` 决定动画结束时把值写成什么: + +| 结尾参考 | 动画结束时的值 | +| -------------------- | -------------------------------------------------- | +| `EndRelation.Target` | 直接写成传入的目标值 | +| `EndRelation.Curve` | 停在曲线终点;不一定等于目标值 | +| `EndRelation.Self` | 正常结束时同 `Curve`;提前结束时停在接管那一刻的值 | + +默认是 `EndRelation.Target`。使用 `Curve` 时,如果曲线在终点不回到目标值,对象最终会停在另一个值;终点由曲线在 `1` 处的输出决定。 + +```ts +import { sin } from '@motajs/animate'; + +const x = ref(0); + +animater + .animate(x) // 当前对象:x;尚无步骤;选择 x + .curve(sin()) // 当前对象:x;尚无步骤;设置当前曲线 + .to(100, 400, EndRelation.Curve) // 当前对象:x;新增索引 1;写入步骤,结尾按曲线终点 + .planEnd(); // 当前对象:x;索引 1;结束本组,当前对象清空 +``` + +## 结束触发 + +组内步骤默认一起开始;如果希望后一段等前一段真正结束再开始,就需要把后一段挂到前一段的结束时刻上。`after(time = 0): this` 做这件事:它把后续步骤挂到上一次定义的步骤结束之后,再等待 `time` 毫秒。没有它,两段只能并行,或者靠猜时长来凑先后。 + +`after` 锚定的是上一次定义的步骤,不是当前 `animate` 选中的对象;如果还没有任何步骤,它不会建立关联。把 `after` 直接写在它要锚定的 `to` 后面,再选下一个对象,读起来就是「这段结束后,再让谁动」: + +```ts +const x = ref(0); +const y = ref(0); + +animater + .animate(x) // 当前对象:x;尚无步骤;选择 x + .to(1, 400) // 当前对象:x;新增索引 1;写入步骤 + .after(120) // 当前对象:x;索引 1;把后续步骤挂到索引 1 结束之后,等待 120ms + .animate(y) // 当前对象:y;尚无步骤;选择 y + .to(1, 150) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 结束之后) + .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空 +``` + +`after` 只能锚定上一条定义的步骤;要挂在组里其它对象、其它编号的步骤之后,就需要按对象与编号指定。`afterPlan(content: IAnimatable, index: number, time = 0): this` 就是为此把后续步骤挂到当前计划组里指定对象、指定索引的步骤结束之后。`index` 从 `1` 开始;找不到对应步骤时不会建立这个关联,若之前已经挂过触发,基准保持原样,否则后续步骤随组开始。 + +```ts +animater + .animate(x) // 当前对象:x;尚无步骤;选择 x + .to(100, 200) // 当前对象:x;新增索引 1;写入步骤 + .afterPlan(x, 1, 50) // 当前对象:x;索引 1;把后续步骤挂到 x 索引 1 结束之后,等待 50ms + .animate(y) // 当前对象:y;尚无步骤;选择 y + .to(50, 150) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 结束之后) + .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空 +``` + +调用 `after` 或 `afterPlan` 之后,后续的步骤会继续挂到同一个基准上,直到下一次 `after`、`when` 或 `planEnd` 改变它。两者都只能引用当前正在定义的组;已经封口的组不能再被挂触发点。 + +## 开始触发 + +结束触发只能让两段首尾相接;若希望后一段在前一段开始后某个时刻就启动,让两段重叠,就需要以开始时刻为基准。`when(time = 0): this` 把后续步骤挂到上一次定义的步骤开始时刻之后,再等待 `time` 毫秒。没有它,两段要么完全同时开始,要么等前一段结束。 + +```ts +animater + .animate(x) // 当前对象:x;尚无步骤;选择 x + .to(1, 400) // 当前对象:x;新增索引 1;写入步骤 + .when(100) // 当前对象:x;索引 1;把后续步骤挂到索引 1 开始之后,等待 100ms + .animate(y) // 当前对象:y;尚无步骤;选择 y + .to(1, 150) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 开始之后) + .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空 +``` + +`when` 也只能锚定上一条定义的步骤;要以后面组里任意一条已有步骤的开始时刻为基准,就需要按对象与编号指定。`whenPlan(content: IAnimatable, index: number, time = 0): this` 就是为此以当前计划组里指定对象、指定索引的步骤为基准,从它开始执行的时刻起等待 `time` 毫秒。写法与 `afterPlan` 相同,只是基准从「步骤结束」改为「步骤开始」。 + +```ts +animater + .animate(x) // 当前对象:x;尚无步骤;选择 x + .to(1, 500) // 当前对象:x;新增索引 1;写入步骤 + .whenPlan(x, 1, 200) // 当前对象:x;索引 1;把后续步骤挂到 x 索引 1 开始之后,等待 200ms + .animate(y) // 当前对象:y;尚无步骤;选择 y + .to(1, 200) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 开始之后) + .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空 +``` + +`when` 与 `after` 都锚定上一次定义的步骤,所以调用顺序会影响挂载点:先 `animate(y)` 不会改变锚点,紧接着的 `when` 或 `after` 仍然挂在 `x` 的上一条步骤上。把触发写在锚点步骤之后,可以少一次回头确认。 + +## 查询与等待 + +计划提交后,代码有时需要读出某一步的目标值与时长。`query(content: IAnimatable, index: number, plan?: number): IAnimationPlan | null` 就是为此查询步骤的;没有它,只能自己记住定义时写了什么,或者等整组结束后再回头找。 + +另一些时候,代码只想等某一步完成再继续,而不想等整组结束。`wait(content: IAnimatable, index: number, plan?: number): Promise` 就是为此等待单个步骤的;没有它,只能猜时长,或者在组尾统一处理。 + +`index` 是该对象在本计划组里的步骤编号,从 `1` 开始;`plan` 是计划组索引,由 `planEnd` 返回。省略 `plan` 时,`query` 查询当前正在定义中的组;`planEnd` 之后当前组已经封口,要查已定义的组必须显式传入组索引。`wait` 省略 `plan` 时先找当前正在执行的组;没有执行中的组时,按当前正在定义中的组查找。步骤不存在时立即兑现,步骤存在时只等这一条结束,不等整组。步骤被后续步骤接管时,它的完成信号也会兑现。 + +`IAnimationPlan` 的常用成员: + +| 成员 | 含义 | +| ------------- | -------------------------------- | +| `identifier` | 动画对象与组内步骤编号 | +| `curve` | 这个步骤的速率曲线 | +| `targetValue` | 目标值 | +| `time` | 动画时长 | +| `promise` | 这个步骤执行完毕后兑现的 Promise | + +```ts +const x = ref(0); + +const group = animater + .animate(x) // 当前对象:x;尚无步骤;选择 x + .to(100, 300) // 当前对象:x;新增索引 1;写入步骤 + .after(100) // 当前对象:x;索引 1;把后续步骤挂到索引 1 结束之后,等待 100ms + .to(200, 200) // 当前对象:x;新增索引 2;写入步骤(挂到索引 1 结束之后) + .planEnd(); // 当前对象:x;索引 2;结束本组,当前对象清空 + +const second = animater.query(x, 2, group); // 当前对象:无;组 group 索引 2;读取 x 的步骤 +// second?.targetValue 为 200 + +await animater.wait(x, 2, group); // 当前对象:无;组 group 索引 2;等待 x +``` + +`query` 与 `wait` 的默认范围不同:`query` 默认查当前正在定义的组,`wait` 默认查当前正在执行的组。定义完计划后要查询该组,通常显式传入 `planEnd` 的返回值。 + +## 计划组收尾 + +写步骤时,系统需要一个明确边界知道「这一组到这里定义完毕」,并据此决定什么时候开始执行、组前与组后各等多久、下一组怎样排队;`planEnd(preTime = 0, postTime = 0): number` 就是这条边界。不调用它,当前组不会提交,后续步骤会继续累积在同一组里,也不会开始执行。 + +`planEnd` 什么时候调用由你决定:在关闭它之前,当前组一直保持「定义中」,可以继续用 `to` 往里加步骤。它不需要在写完第一条步骤后立刻调用;但组只有在 `planEnd` 之后才会被排队执行。 + +`planEnd` 返回组索引,从 `1` 开始;没有定义任何步骤时返回 `-1`。 + +- `preTime` 是组执行前的等待时长(毫秒),等待结束后才开始组内第一批步骤。 +- `postTime` 是组执行后的等待时长(毫秒),组内步骤、开始触发与结束触发全部结束后再等待这么久,计划组才真正结束。 +- 后一个计划组会等前一个计划组全部结束之后才开始,因此组与组之间不会重叠。 + +```ts +const x = ref(0); +const y = ref(0); + +// 第一个计划组:x 与 y 同时走向各自目标 +animater + .animate(x) // 当前对象:x;尚无步骤;选择 x + .to(100, 300) // 当前对象:x;新增索引 1;写入步骤 + .animate(y) // 当前对象:y;尚无步骤;选择 y + .to(50, 300) // 当前对象:y;新增索引 1;写入步骤(随组开始,与 x 并行) + .planEnd(); // 当前对象:y;索引 1;结束组 1,当前对象清空 + +// 第二个计划组:等第一个组全部结束后,x 再回到 0 +animater + .animate(x) // 当前对象:x;新组重新计数,尚无步骤;选择 x + .to(0, 200) // 当前对象:x;新增索引 1;写入步骤 + .planEnd(); // 当前对象:x;索引 1;结束组 2,当前对象清空 +``` + +## 执行器状态与读取规则 + +把上面的操作放在一起看,`Animater` 是一台按状态工作的执行器:它记住当前选中的对象、当前曲线、触发基准,以及正在定义或执行的计划组。每个接口只读写其中一部分状态;理解这一点,才能判断一行代码在看谁、写谁。 + +| 操作 | 读取的状态 | 改变的状态 | +| ---------------------------------- | ---------------------------------------------- | -------------------------------------- | +| `animate(content)` | 无 | 当前对象,以及该对象的步骤容器 | +| `curve(curve)` | 无 | 当前曲线,供后续 `to` 记录 | +| `to(value, time, end)` | 当前对象、当前曲线、当前触发基准 | 向当前计划组写入一条步骤,步骤编号加一 | +| `after(time)` / `when(time)` | 上一个定义的步骤 | 触发基准与等待时长 | +| `afterPlan(...)` / `whenPlan(...)` | 当前计划组中指定对象、指定编号的步骤 | 触发基准与等待时长 | +| `planEnd(...)` | 当前计划组 | 关闭并排队该组,返回组编号 | +| `query(...)` | 默认读取当前正在定义的组 | 无 | +| `wait(...)` | 默认读取当前正在执行的组;没有时读正在定义的组 | 无 | +| `destroy()` | 无 | 解绑激励源,清空计划与执行状态 | + +其中最容易看错的是 `to`:它同时依赖选中的对象、当前曲线与当前触发基准。没有先用 `animate` 选中对象时,`to` 不写入任何步骤,计划看起来写了,实际不会动。 + +`after` 与 `when` 改的是触发基准,不是当前对象。之后即使换了对象,基准也会保持,直到下一次触发设置或 `planEnd`。 + +`query` 与 `wait` 的默认范围不同:`query` 默认读当前正在定义的组;`wait` 默认读当前正在执行的组,没有执行中的组时读当前正在定义的组。 + +## 组合与编排示例 + +下面每个示例前都先说明它表示的动画;示例里的 `x`、`y` 是已经声明好的动画对象,`animater` 由 `useAnimater()` 取得,`linear()` 来自 `@motajs/animate`。每个示例后配两个 live:一个看时间轴,一个看数值播放;两者都由真实执行器推进。 + +### 顺序执行 + +这个示例表示:`x` 先走完,`y` 才开始。 + +```ts +// x 走完,y 才开始 +animater + .animate(x) // 当前对象:x;尚无步骤;选择 x + .curve(linear()) // 当前对象:x;尚无步骤;设置当前曲线 + .to(1, 700) // 当前对象:x;新增索引 1;写入步骤 + .after() // 当前对象:x;索引 1;把后续步骤挂到索引 1 结束之后 + .animate(y) // 当前对象:y;尚无步骤;选择 y + .to(1, 450) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 结束之后) + .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空 +``` + +`after()` 不等待额外时间,所以 `y` 在 `x` 结束的同一刻启动。 + +时间轴视图:色块是步骤段,竖线是播放头。 + + + + + + +播放视图:两个圆点分别表示 `x` 与 `y` 的当前值。 + + + + + + +### 并行执行 + +这个示例表示:`x` 与 `y` 同时开始,各自走向自己的目标。 + +```ts +// x、y 同时开始,各自走向自己的目标 +animater + .animate(x) // 当前对象:x;尚无步骤;选择 x + .curve(linear()) // 当前对象:x;尚无步骤;设置当前曲线 + .to(1, 900) // 当前对象:x;新增索引 1;写入步骤(随组开始) + .animate(y) // 当前对象:y;尚无步骤;选择 y + .curve(linear()) // 当前对象:y;尚无步骤;设置当前曲线 + .to(0.5, 900) // 当前对象:y;新增索引 1;写入步骤(随组开始,与 x 并行) + .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空 +``` + +两条步骤都没有挂触发点,所以都会随组开始;它们只共享开始时刻,不共享目标、时长或曲线。 + +时间轴视图:两条步骤段从同一刻开始。 + + + + + + +播放视图:两个值同时变化。 + + + + + + +### 延迟与重叠 + +这个示例表示:`x` 先开始,`y` 在 `x` 开始 300ms 后启动,两者重叠 600ms。 + +```ts +// x 先走 1000ms,y 在 x 开始 300ms 后启动,两者重叠 600ms +animater + .animate(x) // 当前对象:x;尚无步骤;选择 x + .curve(linear()) // 当前对象:x;尚无步骤;设置当前曲线 + .to(1, 1000) // 当前对象:x;新增索引 1;写入步骤 + .when(300) // 当前对象:x;索引 1;把后续步骤挂到索引 1 开始之后,等待 300ms + .animate(y) // 当前对象:y;尚无步骤;选择 y + .to(1, 600) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 开始之后) + .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空 +``` + +`when(300)` 以 `x` 的开始为基准,所以 `y` 在 `x` 走了 300ms 时启动,而不是等 `x` 结束。 + +时间轴视图:`y` 的步骤段从 `x` 中段开始。 + + + + + + +播放视图:`x` 先动,`y` 稍后启动。 + + + + + + +### 两个计划组 + +这个示例表示:组 1 的 `x` 全部结束后,组 2 的 `y` 才开始;组间不需要额外写等待。 + +```ts +// 组 2 会等组 1 全部结束;不需要额外写等待 +const first = animater // 当前对象:无;尚无步骤;开始定义组 1 + .animate(x) // 当前对象:x;尚无步骤;选择 x + .curve(linear()) // 当前对象:x;尚无步骤;设置当前曲线 + .to(1, 600) // 当前对象:x;新增索引 1;写入步骤 + .planEnd(); // 当前对象:x;索引 1;结束组 1,当前对象清空 + +const second = animater // 当前对象:无;新组;开始定义组 2 + .animate(y) // 当前对象:y;新组重新计数,尚无步骤;选择 y + .curve(linear()) // 当前对象:y;尚无步骤;设置当前曲线 + .to(1, 600) // 当前对象:y;新增索引 1;写入步骤 + .planEnd(); // 当前对象:y;索引 1;结束组 2,当前对象清空 + +// 等组 1 的 x 步骤,或等组 2 的 y 步骤,都可以 +await animater.wait(x, 1, first); // 当前对象:无;组 first 索引 1;等待 x +await animater.wait(y, 1, second); // 当前对象:无;组 second 索引 1;等待 y +``` + +时间轴视图:两组首尾相接,中间没有重叠。 + + + + + + +播放视图:`x` 完成后,`y` 才从 0 开始。 + + + + + + +### 查询与等待指定步骤 + +这个示例表示:先读出 `y` 这条步骤的目标与时长,再只等待 `y` 结束。 + +```ts +const group = animater // 当前对象:无;尚无步骤;开始定义一组 + .animate(x) // 当前对象:x;尚无步骤;选择 x + .curve(linear()) // 当前对象:x;尚无步骤;设置当前曲线 + .to(1, 300) // 当前对象:x;新增索引 1;写入步骤 + .when(100) // 当前对象:x;索引 1;把后续步骤挂到索引 1 开始之后,等待 100ms + .animate(y) // 当前对象:y;尚无步骤;选择 y + .curve(linear()) // 当前对象:y;尚无步骤;设置当前曲线 + .to(1, 200) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 开始之后) + .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空 + +const yStep = animater.query(y, 1, group); // 当前对象:无;组 group 索引 1;读取 y 的步骤 +// yStep?.targetValue 为 1,yStep?.time 为 200 + +// 只等 y 这一条步骤,不等待整组 +await animater.wait(y, 1, group); // 当前对象:无;组 group 索引 1;等待 y +``` + +这里的 `query` 与 `wait` 都显式传入了 `planEnd` 返回的组索引,所以查的是已封口的组,而不是之后还在定义的组。 + +时间轴视图:`x` 与 `y` 重叠,等待只针对 `y` 那一段。 + + + + + + +播放视图:先显示查到的 `y` 目标与时长,再播放数值。 + + + + + + +### 中途改道 + +这个示例表示:`x` 的第一段走到 700ms 时被第二段接管,改为走回 0;`y` 仍按自己的节奏走完。 + +```ts +const group = animater // 当前对象:无;尚无步骤;开始定义一组 + .animate(x) // 当前对象:x;尚无步骤;选择 x + .curve(linear()) // 当前对象:x;尚无步骤;设置当前曲线 + .to(1, 1200, EndRelation.Self) // 当前对象:x;新增索引 1;写入步骤,结尾保留改道时的值 + .animate(y) // 当前对象:y;尚无步骤;选择 y + .curve(linear()) // 当前对象:y;尚无步骤;设置当前曲线 + .to(1, 1500) // 当前对象:y;新增索引 1;写入步骤 + .whenPlan(x, 1, 700) // 当前对象:y;索引 1;把触发基准改为 x 索引 1 开始后 700ms + .animate(x) // 当前对象:x;已有索引 1;重新选择 x + .curve(linear()) // 当前对象:x;已有索引 1;设置当前曲线 + .to(0, 500) // 当前对象:x;新增索引 2;写入步骤(挂到 x 索引 1 开始后 700ms) + .planEnd(); // 当前对象:x;索引 2;结束本组,当前对象清空 + +await animater.wait(x, 1, group); // 当前对象:无;组 group 索引 1;等待 x 第 1 段(改道时兑现) +await animater.wait(x, 2, group); // 当前对象:无;组 group 索引 2;等待 x 第 2 段 +``` + +第一段使用 `EndRelation.Self`,接管时会停在改道时刻的值;如果使用默认的 `Target`,它会先跳到原来的目标值,再被新步骤拉回。被接管的那一段不会触发它挂的结束触发点。 + +时间轴视图:`x` 的第一段在 700ms 处截断,第二段从那里接上。 + + + + + + +播放视图:`x` 在改道后从当前值走回 0,`y` 继续走完。 + + + + + + +## 与渐变执行器的分工 + +`Animater` 负责多个对象、多个步骤的编排;只是让单个数值连续靠近目标值时,用[渐变执行器](./animation-transition.md)。 + +## 边界与注意 + +- 同一个对象在同一时刻只能开始一条步骤:两条步骤同时启动会报错并跳过后一条;启动时刻更晚时,前一条会立刻结束再开始新的。 +- `after` 与 `when` 锚定上一次定义的步骤,与当前 `animate` 选中的对象无关;中间换了对象,锚点也不会跟着换。 +- 被接管的那一段不会触发它挂的结束触发点;需要停在接管时刻的值时用 `EndRelation.Self`,默认的 `Target` 会先跳到原目标值再被拉回。 + + diff --git a/docs/render-guide/internals/animation-transition.md b/docs/render-guide/internals/animation-transition.md new file mode 100644 index 0000000..7775c3a --- /dev/null +++ b/docs/render-guide/internals/animation-transition.md @@ -0,0 +1,253 @@ +# 渐变执行器 + +渐变执行器 `Transition` 实现 `ITransition`,负责让一个数值平滑地靠近目标值。它只处理一个数值、一段时长和一条曲线;需要给多个值排先后、控制并行关系时,使用[动画执行器](./animation-runner.md)。 + +## 模型 + +一次渐变只有四样东西: + +| 组成 | 是什么 | +| ---------- | --------------------------------------------------------- | +| 当前值 | 可写对象上的 `value`,渐变过程中由执行器更新 | +| 目标值 | 这次要靠近的数,由 `to` 的第一个参数给出 | +| 时长与曲线 | 用多久走完,以及过程中快慢怎么变化 | +| 激励源 | 按固定节奏推动执行器的来源,由 `useTransition` 或手动接入 | + +`IAnimatable` 是动画对象的形状:一个带可写 `value` 的对象,Vue 的 `ref` 也满足这个形状。当前值由执行器改写,调用方只读它。 + +曲线决定的是「已经走了多远」。它接收时间进度 `progress`(`0` 到 `1`),返回一个数;这个数表示此时刻动画的完成度:为 `0` 时动画处于起点,为 `1` 时刚好执行到目标值,中间按曲线返回的比例推进。 + +曲线返回值超出 `0` 到 `1` 时,当前值会越过目标值,或回到起始值之外。 + +调用 `to` 后,执行器记下目标值、时长与曲线。之后每次激励,它就让当前值向目标值靠近一点;到达结尾时,按结尾参考决定最终写什么值。没有激励源,`to` 不会开始。 + +```mermaid +flowchart LR + E[激励源] -->|excited| T[Transition] + T -->|更新当前值| V[IAnimatable.value] + C[to:目标值 / 时长 / 曲线] --> T +``` + +`ITransition` 本身是一个受激励对象(`IExcitable`):它接收激励源按节奏传来的数字时间戳,再推进自己的渐变。通过 `bindExcitation` 接入激励源、通过 `unbindExcitation` 解除。组件里通常交给 `useTransition`;不在组件内,或需要接到自定义激励源时,才手动绑定。 + +下面的 live 用真实的 `Transition` 驱动数值。当前值与目标值同时显示,按钮会重新设定目标,执行器从当前值继续渐变。 + + + + + + +## 执行器 + +自己 `new` 执行器还要手动找激励源并处理解绑,组件卸载时很容易漏掉清理;`useTransition` 把这些事收在一处。它必须在组件的 `setup` 或生命周期钩子里调用:它会把执行器绑定到根渲染器的激励源,并在组件卸载时解除绑定。 + +```tsx +// setup +import { defineComponent, ref } from 'vue'; +import { useTransition } from '@motajs/render-vue'; + +const MyPanel = defineComponent(() => { + const opacity = ref(0); + // 只能在组件 setup 或生命周期钩子里调用 + const transition = useTransition()!; + // 之后的 transition.transition(...).to(...) 都通过它执行 + + return () => ; +}); +``` + +`useTransition(tran?, excitation?)` 返回 `ITransition | null`。两个参数都可选:`tran` 是已有的执行器,`excitation` 是显式指定的激励源。省略时,函数会新建一个 `Transition`,并绑定根渲染器的激励源。 + +不传 `tran` 时,执行器由 `useTransition` 创建,组件卸载时会解除绑定并销毁它;传入 `tran` 时,函数只负责绑定与解绑,执行器仍由调用方持有。根渲染器变化时,两种情况都会重新绑定到新的激励源。 + +不在组件内,或需要接到自定义激励源时,才自己创建执行器并手动绑定。`RafExcitation` 是一个每帧给出时间戳的激励源,`Transition` 是渐变执行器本身: + +```ts +import { RafExcitation, Transition } from '@motajs/animate'; + +const excitation = new RafExcitation(); +const transition = new Transition(); + +// 绑定后执行器才会收到每一帧的时间戳 +transition.bindExcitation(excitation); + +// 不再使用时解绑 +transition.unbindExcitation(); +``` + +手动创建时,解绑与销毁由调用方负责;`useTransition` 只是替组件内场景处理了这些收尾。 + +## 对象选择 + +`to` 只会改「当前选中的对象」,所以开始渐变的下一步是告诉执行器改谁;不先选对象,后面的目标值没有落点。 + +`transition(animatable)` 选择后续 `to` 作用的数值对象,返回执行器本身,可以继续链式调用。 + +```ts +const opacity = ref(0); +const transition = useTransition()!; + +transition.transition(opacity).to(1, 300); +``` + +同一个执行器可以依次选择不同对象,各自调用 `to`;每个对象的渐变独立进行,`wait` 也按对象区分。`transition` 只改变「之后调用 `to` 时作用在谁身上」,不会停止之前已经在进行的渐变。 + +```ts +import { ref } from 'vue'; +import { linear, sin } from '@motajs/animate'; +import { useTransition } from '@motajs/render-vue'; + +const leftBar = ref(0); +const rightBar = ref(1); +const transition = useTransition()!; + +function playBars() { + // 选中 leftBar,后面的 to 只作用于它 + transition.transition(leftBar).curve(linear()).to(1, 600); + // 再选中 rightBar,两条渐变同时推进 + transition.transition(rightBar).curve(sin()).to(0, 600); +} +``` + +`playBars` 调用后,`leftBar` 与 `rightBar` 各自有一段正在进行的渐变;执行器每次被激励都会把两条都推进一次。它们只共享激励源,不共享目标、时长或曲线。 + +## 曲线设置 + +同样一段时间,是匀速走完还是先慢后快,由曲线决定;想要淡入淡出、回弹或强调结尾时,需要在这里换掉默认的线性曲线。 + +`curve(curve)` 设置后续 `to` 使用的速率曲线,直到下一次设置;不设置时使用线性曲线。曲线决定过程中的快慢,`time` 决定总耗时。 + +```ts +import { sin } from '@motajs/animate'; + +transition.transition(opacity).curve(sin()).to(1, 300); +``` + +一次渐变会使用调用 `to` 时已经设好的曲线;之后再改 `curve`,不会影响已经开始的那一次。需要让不同目标使用不同节奏时,在每次 `to` 前重新设置。各条曲线的形状见[动画曲线](./animation-curves.md)。 + +## 开始渐变 + +前面的选择与曲线只是准备,真正让数值开始变化的是 `to`;没有它,执行器不会产生任何一段渐变。 + +`to(value, time, end?)` 让当前选中的对象从自己的当前值出发,在 `time` 毫秒内走向 `value`。它需要两个前提:已经用 `transition` 选择了对象,并且已经绑定激励源;缺少任意一项时,调用不会开始渐变。使用顺序是:先用 `transition(对象)` 选中要改的数值,再用 `curve(...)` 选好曲线,最后调用 `to(...)` 启动渐变。 + +同一个对象在渐变途中再次调用 `to`,会从当前值重新出发,把目标改为新的值。之前那次渐变的等待仍会在新目标完成时兑现。 + +```ts +const opacity = ref(0); + +function fadeIn() { + transition.transition(opacity).to(1, 600); +} + +function dim() { + // 如果 fadeIn 还没结束,会从当前值出发,把目标改成 0.4 + transition.transition(opacity).to(0.4, 300); +} +``` + +## 结尾参考 + +曲线走到终点时未必等于目标值,最后该写哪一个需要明确;`EndRelation` 就是在回答这个问题,默认会直接写目标值。 + +`to` 的第三个参数是 `EndRelation`,决定渐变结束时把值写成什么: + +| 结尾参考 | 结束时的值 | +| -------------------- | --------------------------------------------------- | +| `EndRelation.Target` | 直接写成传入的目标值,默认使用这一种 | +| `EndRelation.Curve` | 结束时使用曲线终点值参考,不强制把值写成目标值 | +| `EndRelation.Self` | 正常结束时与 `Curve` 相同;提前结束时停在打断时的值 | + +使用 `Curve` 时,结束值由曲线终点决定,不强制等于目标值:曲线终点回到起点附近,值也会停在起点附近;曲线终点越过目标值,值也会停在越过后的位置。 + +```ts +import { ref } from 'vue'; +import { EndRelation } from '@motajs/animate'; + +// 曲线在终点只走了一半,所以 Curve 模式会停在半程 +const half = (p: number) => p * 0.5; +const value = ref(0); + +transition.transition(value).curve(half).to(1, 500, EndRelation.Curve); +``` + +下面的 live 并排比较 `Target` 与 `Curve`。曲线可以在「半程曲线」与「回程曲线」之间切换;后者到终点会回到起点,所以 `Curve` 那条也会回到起点。 + + + + + + +## 完成等待 + +要让两段动画接上,调用方需要知道上一段什么时候结束;`wait` 把这段时间变成一个可等待的信号,避免用定时器猜。 + +`wait(animatable)` 返回该对象当前渐变的 `Promise`;对象没有活动渐变时立即兑现。它只等待传入的对象,不等待其他对象的渐变。用法顺序是:先调用 `to` 启动一段渐变,再对同一个对象 `await wait(...)`。 + +```ts +async function fadeTo(value: number): Promise { + transition.transition(opacity).to(value, 300); + await transition.wait(opacity); +} +``` + +`wait` 在渐变途中被调用时,等待的是该对象当前这次渐变;如果中途又调用了 `to`,同一个 `Promise` 会在新目标完成时兑现。把多个 `to` 与 `wait` 串起来,就能写出顺序步骤: + +```ts +async function runStroke() { + // 第一段:正弦曲线,400ms 走到 1 + transition.transition(marker).curve(sin()).to(1, 400); + await transition.wait(marker); + + // 第二段:线性曲线,900ms 回到 0 + transition.transition(marker).curve(linear()).to(0, 900); + await transition.wait(marker); +} +``` + +第一段结束后,`wait` 才让出执行权;第二段从第一段写回的当前值继续。需要计划级等待时使用 `Animater`。 + +## 释放与销毁 + +执行器会持有选中的对象和激励源绑定;组件或动画结束时如果一直不清理,它就会继续惦记这些对象。 + +`revoke()` 释放当前通过 `transition` 选中的对象,避免执行器一直持有它;它不会停止已经开始的渐变。释放后,新的 `to` 需要重新用 `transition` 选择对象。清理顺序是:先 `revoke()` 放掉选中的对象,再按需重新 `transition` 选择;要停止整个执行器时再用 `destroy()`。 + +`destroy()` 解除激励源绑定并清理执行器;之后这个执行器不能再推进。由 `useTransition` 内部创建的执行器会在组件卸载时自动销毁;传入已有执行器时,组件卸载只解除绑定。 + +```ts +const transition = useTransition()!; +const opacity = ref(0); + +transition.transition(opacity).to(1, 600); + +// 释放选中对象:渐变继续,但之后的 to 需要重新 transition 选择 +transition.revoke(); +transition.transition(opacity).to(0.2, 300); + +// 解除激励源绑定:之后不会再推进 +transition.destroy(); +``` + +## 与动画执行器的分工 + +| 项目 | `Transition` | `Animater` | +| -------- | ---------------------------- | ----------------------------------- | +| 组织单位 | 单个数值的连续渐变 | 多个动画对象与多个计划组 | +| 时序关系 | 只有当前渐变的时长 | `after`、`when`、组前等待、组后等待 | +| 典型用途 | 淡入淡出、悬停反馈、颜色过渡 | 多对象编排、分段动画、并行与延迟 | + +需要「一个数慢慢变成另一个数」时用 `Transition`;需要给多个值排先后顺序、设置延迟或并行关系时,用[动画执行器](./animation-runner.md)。 + +