From 1294c5f1ca64ebabb0273a6ded64f7c7407feb5a Mon Sep 17 00:00:00 2001 From: unanmed <1319491857@qq.com> Date: Sat, 22 Mar 2025 17:20:36 +0800 Subject: [PATCH] docs: @motajs/render-core --- docs/.vitepress/config.ts | 106 +++- docs/api/motajs-render-core/Container.md | 118 +++++ .../api/motajs-render-core/ContainerCustom.md | 67 +++ docs/api/motajs-render-core/Event.md | 201 ++++++++ docs/api/motajs-render-core/GL2.md | 149 ++++++ docs/api/motajs-render-core/GL2Program.md | 186 +++++++ .../MotaOffscreenCanvas2D.md | 309 ++++++++++++ docs/api/motajs-render-core/MotaRenderer.md | 172 +++++++ docs/api/motajs-render-core/RenderAdapter.md | 230 +++++++++ docs/api/motajs-render-core/RenderItem.md | 475 ++++++++++++++++++ docs/api/motajs-render-core/Shader.md | 8 + docs/api/motajs-render-core/ShaderProgram.md | 8 + docs/api/motajs-render-core/Sprite.md | 118 +++++ docs/api/motajs-render-core/Transform.md | 330 ++++++++++++ docs/api/motajs-render-core/functions.md | 119 +++++ docs/api/motajs-render-core/index.md | 2 - 16 files changed, 2571 insertions(+), 27 deletions(-) create mode 100644 docs/api/motajs-render-core/Container.md create mode 100644 docs/api/motajs-render-core/ContainerCustom.md create mode 100644 docs/api/motajs-render-core/Event.md create mode 100644 docs/api/motajs-render-core/GL2.md create mode 100644 docs/api/motajs-render-core/GL2Program.md create mode 100644 docs/api/motajs-render-core/MotaOffscreenCanvas2D.md create mode 100644 docs/api/motajs-render-core/MotaRenderer.md create mode 100644 docs/api/motajs-render-core/RenderAdapter.md create mode 100644 docs/api/motajs-render-core/RenderItem.md create mode 100644 docs/api/motajs-render-core/Shader.md create mode 100644 docs/api/motajs-render-core/ShaderProgram.md create mode 100644 docs/api/motajs-render-core/Sprite.md create mode 100644 docs/api/motajs-render-core/Transform.md create mode 100644 docs/api/motajs-render-core/functions.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 6349ef3..6cc0b65 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -75,7 +75,7 @@ export default defineConfig({ text: '@motajs/client', collapsed: true, items: [ - { text: '目录', link: '/api/motajs-client/' } + { text: '主页', link: '/api/motajs-client/' } ] }, { @@ -83,7 +83,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/motajs-client-base/' }, { @@ -96,7 +96,7 @@ export default defineConfig({ text: '@motajs/common', collapsed: true, items: [ - { text: '目录', link: '/api/motajs-common/' }, + { text: '主页', link: '/api/motajs-common/' }, { text: '函数', link: '/api/motajs-common/functions' @@ -112,7 +112,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/motajs-legacy-client/' } ] @@ -122,7 +122,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/motajs-legacy-common/' } ] @@ -132,7 +132,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/motajs-legacy-system/' } ] @@ -141,14 +141,14 @@ export default defineConfig({ text: '@motajs/legacy-ui', collapsed: true, items: [ - { text: '目录', link: '/api/motajs-legacy-ui/' } + { text: '主页', link: '/api/motajs-legacy-ui/' } ] }, { text: '@motajs/render', collapsed: true, items: [ - { text: '目录', link: '/api/motajs-render/' } + { text: '主页', link: '/api/motajs-render/' } ] }, { @@ -156,8 +156,64 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/motajs-render-core/' + }, + { + text: '函数', + link: '/api/motajs-render-core/functions' + }, + { + text: '交互事件', + link: '/api/motajs-render-core/Event' + }, + { + text: 'MotaOffscreenCanvas2D', + link: '/api/motajs-render-core/MotaOffscreenCanvas2D' + }, + { + text: 'Transform', + link: '/api/motajs-render-core/Transform' + }, + { + text: 'RenderItem', + link: '/api/motajs-render-core/RenderItem' + }, + { + text: 'Container', + link: '/api/motajs-render-core/Container' + }, + { + text: 'ContainerCustom', + link: '/api/motajs-render-core/ContainerCustom' + }, + { + text: 'Sprite', + link: '/api/motajs-render-core/Sprite' + }, + { + text: 'MotaRenderer', + link: '/api/motajs-render-core/MotaRenderer' + }, + { + text: 'GL2', + link: '/api/motajs-render-core/GL2' + }, + { + text: 'GL2Program', + link: '/api/motajs-render-core/GL2Program' + }, + { + text: 'RenderAdapter', + link: '/api/motajs-render-core/RenderAdapter' + }, + { + text: 'Shader', + link: '/api/motajs-render-core/Shader' + }, + { + text: 'ShaderProgram', + link: '/api/motajs-render-core/ShaderProgram' } ] }, @@ -166,7 +222,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/motajs-render-elements/' } ] @@ -176,7 +232,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/motajs-render-style/' } ] @@ -186,7 +242,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/motajs-render-vue/' } ] @@ -195,7 +251,7 @@ export default defineConfig({ text: '@motajs/system', collapsed: true, items: [ - { text: '目录', link: '/api/motajs-system/' } + { text: '主页', link: '/api/motajs-system/' } ] }, { @@ -203,7 +259,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/motajs-system-action/' } ] @@ -212,14 +268,14 @@ export default defineConfig({ text: '@motajs/system-ui', collapsed: true, items: [ - { text: '目录', link: '/api/motajs-system-ui/' } + { text: '主页', link: '/api/motajs-system-ui/' } ] }, { text: '@motajs/types', collapsed: true, items: [ - { text: '目录', link: '/api/motajs-types/' } + { text: '主页', link: '/api/motajs-types/' } ] }, { @@ -227,7 +283,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/user-client-modules/' } ] @@ -237,7 +293,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/user-data-base/' } ] @@ -247,7 +303,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/user-data-fallback/' } ] @@ -257,7 +313,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/user-data-state/' } ] @@ -267,7 +323,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/user-data-utils/' } ] @@ -277,7 +333,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/user-entry-client/' } ] @@ -287,7 +343,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/user-entry-data/' } ] @@ -297,7 +353,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/user-legacy-plugin-client/' } ] @@ -307,7 +363,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: '目录', + text: '主页', link: '/api/user-legacy-plugin-data/' } ] diff --git a/docs/api/motajs-render-core/Container.md b/docs/api/motajs-render-core/Container.md new file mode 100644 index 0000000..9787b89 --- /dev/null +++ b/docs/api/motajs-render-core/Container.md @@ -0,0 +1,118 @@ +# Container 类 API 文档 + +本文档由 `DeepSeek R1` 模型生成并微调。 + +--- + +## 继承关系 + +```mermaid +graph LR + Container --> RenderItem --> EventEmitter +``` + +## 属性说明 + +| 属性名 | 类型 | 默认值 | 说明 | +| ---------------- | -------------- | ------ | ------------------------------ | +| `sortedChildren` | `RenderItem[]` | `[]` | 按 `zIndex` 排序后的子元素列表 | + +--- + +## 构造方法 + +### `constructor` + +**参数** + +- `type`: 渲染模式（`absolute` 绝对定位 / `static` 跟随摄像机） +- `cache`: 是否启用渲染缓存 +- `fall`: 是否启用变换矩阵下穿机制 + +**示例** + +```typescript +const container = new Container('static'); +``` + +--- + +## 方法说明 + +### `appendChild` + +```typescript +function appendChild(...children: RenderItem[]): void; +``` + +**描述** +添加子元素并触发重新排序。 +**示例** + +```typescript +const child = new RenderItem('static'); +container.appendChild(child); // 添加子元素 +``` + +--- + +### `removeChild` + +```typescript +function removeChild(...child: RenderItem[]): void; +``` + +**描述** +移除指定子元素并触发重新排序。 +**示例** + +```typescript +container.removeChild(child); // 移除子元素 +``` + +--- + +### `requestSort` + +```typescript +function requestSort(): void; +``` + +**描述** +标记需要重新排序子元素（在下一帧前自动执行）。 + +--- + +### `forEachChild` + +```typescript +function forEachChild(fn: (ele: RenderItem) => void): void; +``` + +**描述** +遍历元素的每一个子元素（DFS 遍历），并对每一个元素执行函数。 + +--- + +## 总使用示例 + +```typescript +// 创建基础容器 +const baseContainer = new Container('absolute'); +baseContainer.size(800, 600); + +// 添加子元素 +const sprite1 = new Sprite('static'); +sprite1.pos(100, 100).setZIndex(2); +baseContainer.appendChild(sprite1); + +const sprite2 = new Sprite('static'); +sprite2.pos(200, 200).setZIndex(1); +baseContainer.appendChild(sprite2); + +// 将容器添加到根元素 +rootElement.appendChild(baseContainer); + +// 动态修改子元素层级 +sprite1.setZIndex(0); // 自动触发重新排序 +``` diff --git a/docs/api/motajs-render-core/ContainerCustom.md b/docs/api/motajs-render-core/ContainerCustom.md new file mode 100644 index 0000000..86444b2 --- /dev/null +++ b/docs/api/motajs-render-core/ContainerCustom.md @@ -0,0 +1,67 @@ +# ContainerCustom 类 API 文档 + +本文档由 `DeepSeek R1` 模型生成并微调。 + +--- + +## 继承关系 + +```mermaid +graph LR + ContainerCustom --> Container --> RenderItem --> EventEmitter +``` + +--- + +## 属性说明 + +| 属性名 | 类型 | 默认值 | 说明 | +| ---------- | ------------------------- | ----------- | ---------------------- | +| `renderFn` | `CustomContainerRenderFn` | `undefined` | 自定义渲染函数（可选） | + +--- + +## 构造方法 + +继承自 `Container`，参数与父类一致。 + +--- + +## 方法说明 + +### `setRenderFn` + +```typescript +function setRenderFn(render?: CustomContainerRenderFn): void; +``` + +**描述** +设置自定义渲染函数，覆盖默认的子元素渲染逻辑。 +**参数** + +- `render`: 接收画布、子元素列表和变换矩阵的回调函数 + +**示例** + +```typescript +customContainer.setRenderFn((canvas, children, transform) => { + children.forEach(child => { + child.renderContent(canvas, transform); + }); +}); +``` + +--- + +## 总使用示例 + +```ts +// 创建自定义容器 +const customContainer = new ContainerCustom('static'); +customContainer.setRenderFn((canvas, children) => { + // 倒序渲染子元素 + children.reverse().forEach(child => { + child.renderContent(canvas, Transform.identity); + }); +}); +``` diff --git a/docs/api/motajs-render-core/Event.md b/docs/api/motajs-render-core/Event.md new file mode 100644 index 0000000..bfe4894 --- /dev/null +++ b/docs/api/motajs-render-core/Event.md @@ -0,0 +1,201 @@ +# Event 模块 API 文档 + +以下内容由 `DeepSeek R1` 模型生成并微调。 + +--- + +## 枚举说明 + +### MouseType + +| 值 | 说明 | +| --------- | ---------------- | +| `None` | 没有按键按下 | +| `Left` | 左键 | +| `Middle` | 中键（按下滚轮） | +| `Right` | 右键 | +| `Back` | 侧键后退 | +| `Forward` | 侧键前进 | + +### WheelType + +| 值 | 说明 | +| ------- | -------------------------- | +| `None` | 无单位 | +| `Pixel` | 以像素为单位 | +| `Line` | 以行为单位（约 1rem） | +| `Page` | 以页为单位（一个屏幕高度） | + +### ActionType + +| 值 | 说明 | +| ------- | -------------------------------- | +| `Click` | 点击事件（按下与抬起在同一元素） | +| `Down` | 鼠标或手指按下事件 | +| `Move` | 鼠标或手指移动事件 | +| `Up` | 鼠标或手指抬起事件 | +| `Enter` | 进入元素时触发 | +| `Leave` | 离开元素时触发 | +| `Wheel` | 滚轮事件 | + +### EventProgress + +| 值 | 说明 | +| --------- | -------- | +| `Capture` | 捕获阶段 | +| `Bubble` | 冒泡阶段 | + +--- + +## 接口说明 + +### IActionEventBase + +| 属性名 | 类型 | 说明 | +| ---------- | ------------ | ----------------------------------------------------------------- | +| `target` | `RenderItem` | 触发事件的元素 | +| `touch` | `boolean` | 是否为触摸操作（`true` 表示触摸，`false` 表示鼠标） | +| `type` | `MouseType` | 触发事件的按键类型（参考 `MouseType`） | +| `buttons` | `number` | 当前按下的按键（通过位运算判断，例如 `buttons & MouseType.Left`） | +| `altKey` | `boolean` | 是否按下 `Alt` 键 | +| `shiftKey` | `boolean` | 是否按下 `Shift` 键 | +| `ctrlKey` | `boolean` | 是否按下 `Ctrl` 键 | +| `metaKey` | `boolean` | 是否按下 `Windows/Command` 键 | + +--- + +### IActionEvent + +#### 继承关系 + +```mermaid +graph LR + IActionEvent --> IActionEventBase +``` + +| 属性名 | 类型 | 说明 | +| ------------ | -------- | -------------------------------------------- | +| `identifier` | `number` | 操作的唯一标识符（在按下、移动、抬起中一致） | +| `offsetX` | `number` | 相对于元素左上角的横坐标 | +| `offsetY` | `number` | 相对于元素左上角的纵坐标 | +| `absoluteX` | `number` | 相对于整个画布左上角的横坐标 | +| `absoluteY` | `number` | 相对于整个画布左上角的纵坐标 | + +#### 方法说明 + +##### `stopPropagation` + +```typescript +function stopPropagation(): void; +``` + +**描述** +停止事件的传播（捕获或冒泡阶段）。 + +**示例** + +```typescript +item.on('click', ev => { + ev.stopPropagation(); // 阻止事件继续传播 +}); +``` + +--- + +### IWheelEvent + +```mermaid +graph LR + IWheelEvent --> IActionEvent --> IActionEventBase +``` + +| 属性名 | 类型 | 说明 | +| ----------- | ----------- | -------------------- | +| `wheelX` | `number` | 横向滚动量 | +| `wheelY` | `number` | 纵向滚动量 | +| `wheelZ` | `number` | 垂直屏幕方向的滚动量 | +| `wheelType` | `WheelType` | 滚动量的单位类型 | + +--- + +### ERenderItemActionEvent + +描述了所有的交互事件类型。 + +| 事件名 | 参数类型 | 说明 | +| -------------- | ---------------------------- | ------------------ | +| `clickCapture` | `Readonly` | 点击事件的捕获阶段 | +| `click` | `Readonly` | 点击事件的冒泡阶段 | +| `downCapture` | `Readonly` | 按下事件的捕获阶段 | +| `down` | `Readonly` | 按下事件的冒泡阶段 | +| `moveCapture` | `Readonly` | 移动事件的捕获阶段 | +| `move` | `Readonly` | 移动事件的冒泡阶段 | +| `upCapture` | `Readonly` | 抬起事件的捕获阶段 | +| `up` | `Readonly` | 抬起事件的冒泡阶段 | +| `enter` | `Readonly` | 进入元素事件 | +| `leave` | `Readonly` | 离开元素事件 | +| `wheelCapture` | `Readonly` | 滚轮事件的捕获阶段 | +| `wheel` | `Readonly` | 滚轮事件的冒泡阶段 | + +--- + +### ActionEventMap + +| 键（ActionType） | 值类型 | 说明 | +| ---------------- | -------------- | ------------ | +| `Click` | `IActionEvent` | 点击事件 | +| `Down` | `IActionEvent` | 按下事件 | +| `Enter` | `IActionEvent` | 进入元素事件 | +| `Leave` | `IActionEvent` | 离开元素事件 | +| `Move` | `IActionEvent` | 移动事件 | +| `Up` | `IActionEvent` | 抬起事件 | +| `Wheel` | `IWheelEvent` | 滚轮事件 | + +--- + +## 总使用示例 + +::: code-group + +```typescript +// 创建渲染元素（以 Sprite 为例） +const item = new Sprite(); + +// 监听点击事件（冒泡阶段） +item.on('click', ev => { + console.log('点击坐标:', ev.offsetX, ev.offsetY); + ev.stopPropagation(); // 阻止冒泡 +}); + +// 监听滚轮事件（捕获阶段） +item.on('wheelCapture', ev => { + console.log('滚轮滚动量:', ev.wheelY, '单位:', WheelType[ev.wheelType]); +}); + +// 监听进入元素事件 +item.on('enter', ev => { + console.log('进入元素，触发按键:', MouseType[ev.type]); +}); +``` + +```tsx +// 监听点击事件（冒泡阶段） +const click = (ev: IActionEvent) => { + console.log('点击坐标:', ev.offsetX, ev.offsetY); + ev.stopPropagation(); // 阻止冒泡 +}; + +// 监听滚轮事件（捕获阶段） +const wheel = (ev: IWheelEvent) => { + console.log('滚轮滚动量:', ev.wheelY, '单位:', WheelType[ev.wheelType]); +}; + +// 监听进入元素事件 +const enter = (ev: IActionEventBase) => { + console.log('进入元素，触发按键:', MouseType[ev.type]); +}; + +; +``` + +::: diff --git a/docs/api/motajs-render-core/GL2.md b/docs/api/motajs-render-core/GL2.md new file mode 100644 index 0000000..ba30cb8 --- /dev/null +++ b/docs/api/motajs-render-core/GL2.md @@ -0,0 +1,149 @@ +# GL2 类 API 文档 + +**需丰富** + +本文档由 `DeepSeek R1` 模型生成并微调。 + +## 继承关系 + +```mermaid +graph LR + EventEmitter --> RenderItem + RenderItem --> GL2 +``` + +--- + +## 属性说明 + +| 属性名 | 类型 | 默认值 | 说明 | +| ------------------------------- | ------------------------ | ------------------ | --------------------------------------------- | +| `support` | `boolean`（静态） | 检测 WebGL2 支持性 | 标识当前环境是否支持 WebGL2 | +| `canvas` | `HTMLCanvasElement` | - | 绑定的 WebGL2 画布元素 | +| `gl` | `WebGL2RenderingContext` | - | WebGL2 渲染上下文 | +| `UNIFORM_1f` ~ `UNIFORM_4uiv` | `UniformType` 枚举 | 对应枚举值 | WebGL uniform 类型常量（共 25 种） | +| `U_MATRIX_2x2` ~ `U_MATRIX_4x4` | `UniformMatrix` 枚举 | 对应枚举值 | 矩阵类型 uniform 常量（9 种） | +| `ATTRIB_1f` ~ `ATTRIB_I4uiv` | `AttribType` 枚举 | 对应枚举值 | 顶点属性类型常量（12 种） | +| `MAX_TEXTURE_COUNT` | `number` | `0` | 最大纹理支持数量（实际值由 WebGL 上下文决定） | + +--- + +## 构造方法 + +### `constructor` + +**参数** + +- `type`: 渲染模式（`absolute` 绝对定位 / `static` 跟随摄像机） + +**行为** + +- 初始化 WebGL2 上下文 +- 自动检测 WebGL2 支持性（通过静态属性 `support`） +- 设置默认渲染模式 + +--- + +## 方法说明 + +### `createProgram` + +```typescript +function createProgram( + Program: ProgramConstructor, + vs?: string, + fs?: string +): T; +``` + +**描述** +创建 WebGL 着色器程序 +**参数** + +- `Program`: 着色器程序类（需继承 `GL2Program`） +- `vs`: 自定义顶点着色器代码（可选） +- `fs`: 自定义片元着色器代码（可选） + **示例** + +```typescript +class MyProgram extends GL2Program {} +const program = gl2.createProgram(MyProgram); +``` + +--- + +### `useProgram` + +```typescript +function useProgram(program: GL2Program): void; +``` + +**描述** +切换当前使用的着色器程序 +**示例** + +```typescript +gl2.useProgram(shaderProgram); +``` + +--- + +### `framebuffer` + +```typescript +function framebuffer( + name: string, + texture: IShaderTexture2D, + clear?: boolean +): void; +``` + +**描述** +将渲染结果输出到帧缓冲纹理 +**参数** + +- `name`: 帧缓冲名称 +- `texture`: 目标纹理对象 +- `clear`: 是否清空画布 + +--- + +### `drawScene`（抽象方法） + +```typescript +function drawScene( + canvas: MotaOffscreenCanvas2D, + gl: WebGL2RenderingContext, + program: GL2Program, + transform: Transform +): void; +``` + +**描述** +抽象渲染方法，子类必须实现具体绘制逻辑 + +--- + +## 静态方法说明 + +### `GL2.support` + +```typescript +static readonly support: boolean; +``` + +**描述** +静态只读属性，检测 WebGL2 支持性 +**示例** + +```typescript +if (GL2.support) { + // 初始化 WebGL2 功能 +} +``` + +--- + +## 总使用示例 + +暂时没有。 diff --git a/docs/api/motajs-render-core/GL2Program.md b/docs/api/motajs-render-core/GL2Program.md new file mode 100644 index 0000000..03bfa01 --- /dev/null +++ b/docs/api/motajs-render-core/GL2Program.md @@ -0,0 +1,186 @@ +# GL2Program 类 API 文档 + +**需丰富** + +本文档由 `DeepSeek R1` 模型生成并微调。 + +--- + +## 继承关系 + +```mermaid +graph LR + GL2Program --> EventEmitter +``` + +--- + +## 属性说明 + +| 属性名 | 类型 | 说明 | +| -------------- | ------------------------ | ------------------------------------------ | +| `gl` | `WebGL2RenderingContext` | WebGL2 渲染上下文 | +| `element` | `GL2` | 关联的 GL2 渲染元素 | +| `program` | `WebGLProgram \| null` | WebGL 着色器程序对象 | +| `renderMode` | `RenderMode` | 当前渲染模式（默认 `RenderMode.Elements`） | +| `usingIndices` | `IShaderIndices \| null` | 当前使用的顶点索引数组 | + +--- + +## 方法说明 + +### `defineUniform` + +```typescript +function defineUniform( + uniform: string, + type: T +): IShaderUniform | null; +``` + +**描述** +定义 Uniform 变量 +**参数** + +- `uniform`: Uniform 变量名 +- `type`: Uniform 类型（如 `GL2.UNIFORM_2f`） + **返回值** +- 操作对象（可设置值）或 `null`（定义失败） + +--- + +### `defineTexture` + +```typescript +function defineTexture( + name: string, + index: number, + w?: number, + h?: number +): IShaderTexture2D | null; +``` + +**描述** +定义纹理对象 +**参数** + +- `name`: 纹理名称 +- `index`: 纹理索引（建议不超过 8） +- `w`: 纹理宽度（可选） +- `h`: 纹理高度（可选） + **示例** + +```typescript +const tex = program.defineTexture('diffuse', 0, 512, 512); +``` + +--- + +### `paramElements` + +```typescript +function paramElements( + mode: GLenum, + count: number, + type: GLenum, + offset: number +): void; +``` + +**描述** +设置元素模式渲染参数 +**参数** + +- `mode`: 渲染模式（如 `gl.TRIANGLES`） +- `count`: 元素数量 +- `type`: 数据类型（如 `gl.UNSIGNED_SHORT`） +- `offset`: 数据偏移量 + +--- + +### `requestCompile` + +```typescript +function requestCompile(force?: boolean): boolean; +``` + +**描述** +请求编译着色器 +**参数** + +- `force`: 是否强制重新编译 + **返回值** +- `true` 表示编译成功 + +--- + +### `vs` + +```typescript +function vs(vs: string): void; +``` + +**描述** +设置顶点着色器代码 +**示例** + +```typescript +program.vs(` + ${GL2_PREFIX.VERTEX} + in vec4 aPosition; + void main() { + gl_Position = aPosition; + } +`); +``` + +--- + +## 事件说明 + +| 事件名 | 触发时机 | 参数类型 | +| -------- | ---------------- | -------- | +| `load` | 程序被加载使用时 | `[]` | +| `unload` | 程序被卸载时 | `[]` | + +--- + +## 总使用示例 + +```typescript +// 创建着色器程序 +const program = gl2.createProgram(GL2Program); + +// 定义着色器 +program.vs(` + ${GL2_PREFIX.VERTEX} + uniform mat4 uProjection; + in vec4 aPosition; + void main() { + gl_Position = uProjection * aPosition; + } +`); + +program.fs(` + ${GL2_PREFIX.FRAGMENT} + out vec4 fragColor; + uniform vec3 uColor; + void main() { + fragColor = vec4(uColor, 1.0); + } +`); + +// 定义 Uniform 和纹理 +const colorUniform = program.defineUniform('uColor', UniformType.Uniform3f); +const diffuseTex = program.defineTexture('diffuse', 0, 512, 512); + +// 设置渲染参数 +program.paramElements(gl.TRIANGLES, 6, gl.UNSIGNED_SHORT, 0); + +// 编译并应用 +if (program.requestCompile()) { + gl2.useProgram(program); + colorUniform?.set(1.0, 0.5, 0.2); + diffuseTex?.set(imageElement); +} +``` diff --git a/docs/api/motajs-render-core/MotaOffscreenCanvas2D.md b/docs/api/motajs-render-core/MotaOffscreenCanvas2D.md new file mode 100644 index 0000000..51cf160 --- /dev/null +++ b/docs/api/motajs-render-core/MotaOffscreenCanvas2D.md @@ -0,0 +1,309 @@ +# MotaOffscreenCanvas2D 类 API 文档 + +以下内容由 `DeepSeek R1` 模型生成并微调。 + +--- + +## 继承关系 + +```mermaid +graph LR + MotaOffscreenCanvas2D --> EventEmitter +``` + +--- + +## 属性说明 + +| 属性名 | 类型 | 默认值 | 说明 | +| ---------------- | -------------------------- | -------- | ------------------------------------------- | +| `canvas` | `HTMLCanvasElement` | - | 关联的 HTML 画布元素 | +| `ctx` | `CanvasRenderingContext2D` | - | 画布的 2D 渲染上下文 | +| `width` | `number` | 自动计算 | 画布的逻辑宽度（不包含缩放比例） | +| `height` | `number` | 自动计算 | 画布的逻辑高度（不包含缩放比例） | +| `autoScale` | `boolean` | `false` | 是否自动跟随 `core.domStyle.scale` 进行缩放 | +| `highResolution` | `boolean` | `true` | 是否启用高清画布（根据设备像素比例缩放） | +| `antiAliasing` | `boolean` | `true` | 是否启用抗锯齿 | +| `scale` | `number` | `1` | 当前画布的缩放比例 | +| `symbol` | `number` | `0` | 更新标识符，值变化表示画布被被动清空或调整 | +| `freezed` | `boolean`（只读） | `false` | 当前画布是否被冻结（冻结后不可修改属性） | +| `active` | `boolean`（只读） | `true` | 当前画布是否处于激活状态 | + +--- + +## 构造方法 + +### `constructor` + +```ts +function constructor( + alpha: boolean = true, + canvas?: HTMLCanvasElement +): MotaOffscreenCanvas2D; +``` + +**描述** +创建一个新的离屏画布。 +**参数** + +- `alpha`: 是否启用透明度通道（默认为 `true`）。 +- `canvas`: 可指定现有画布，未提供时自动创建新画布。 + **注意** +- 在自定义渲染元素中，建议使用 `RenderItem.requireCanvas` 而非直接调用此构造函数。 + +--- + +## 方法说明 + +### `size` + +```ts +function size(width: number, height: number): void; +``` + +**描述** +设置画布的尺寸。 +**参数** + +- `width`: 逻辑宽度（最小为 1）。 +- `height`: 逻辑高度（最小为 1）。 + **行为** +- 自动计算缩放比例（考虑 `highResolution` 和 `autoScale`）。 +- 调整画布物理尺寸和样式尺寸。 + +**示例** + +```typescript +const canvas = new MotaOffscreenCanvas2D(); +canvas.size(800, 600); // 设置画布尺寸为 800x600（逻辑尺寸） +``` + +--- + +### `withGameScale` + +```ts +function withGameScale(auto: boolean): void; +``` + +**描述** +设置画布是否跟随 `core.domStyle.scale` 自动缩放。 +**参数** + +- `auto`: 是否启用自动缩放。 + +**示例** + +```typescript +canvas.withGameScale(true); // 启用自动缩放 +``` + +--- + +### `setHD` + +```ts +function setHD(hd: boolean): void; +``` + +**描述** +设置是否为高清画布（基于设备像素比例）。 +**参数** + +- `hd`: 是否启用高清模式。 + +**示例** + +```typescript +canvas.setHD(false); // 关闭高清模式 +``` + +--- + +### `setAntiAliasing` + +```ts +function setAntiAliasing(anti: boolean): void; +``` + +**描述** +设置抗锯齿功能。 +**参数** + +- `anti`: 是否启用抗锯齿。 + +**示例** + +```typescript +canvas.setAntiAliasing(false); // 关闭抗锯齿 +``` + +--- + +### `clear` + +```ts +function clear(): void; +``` + +**描述** +清空画布内容。 +**注意** + +- 冻结状态下调用此方法会触发警告。 + +**示例** + +```typescript +canvas.clear(); // 清空画布 +``` + +--- + +### `delete` + +```ts +function delete(): void +``` + +**描述** +删除画布，释放资源并解除 DOM 绑定。 + +**示例** + +```typescript +canvas.delete(); // 删除画布 +``` + +--- + +### `freeze` + +```ts +function freeze(): void; +``` + +**描述** +冻结画布，禁止修改属性，并从全局列表中移除。 + +**示例** + +```typescript +canvas.freeze(); // 冻结画布 +``` + +--- + +### `activate` + +```ts +function activate(): void; +``` + +**描述** +激活画布，使其跟随游戏缩放调整尺寸。 + +**示例** + +```typescript +canvas.activate(); // 激活画布 +``` + +--- + +### `deactivate` + +```ts +function deactivate(): void; +``` + +**描述** +停用画布，不再自动调整尺寸，可能被垃圾回收。 + +**示例** + +```typescript +canvas.deactivate(); // 停用画布 +``` + +--- + +## 静态方法说明 + +### `MotaOffscreenCanvas2D.clone` + +```ts +function clone(canvas: MotaOffscreenCanvas2D): MotaOffscreenCanvas2D; +``` + +**描述** +复制一个画布对象，结果画布将被冻结。 +**返回值** + +- 复制的画布对象（不可修改属性，但可绘制）。 + +**示例** + +```typescript +const cloned = MotaOffscreenCanvas2D.clone(sourceCanvas); // 复制画布 +``` + +--- + +### `MotaOffscreenCanvas2D.refreshAll` + +```ts +function refreshAll(force: boolean = false): void; +``` + +**描述** +刷新所有已注册画布的尺寸（仅在窗口大小变化时自动调用）。 +**参数** + +- `force`: 是否强制刷新所有画布（默认仅刷新启用 `autoScale` 的画布）。 + +--- + +## 事件类型 + +### `resize` + +**触发时机** +当画布被动调整尺寸时触发（例如窗口大小变化或 `core.domStyle.scale` 变化）。 + +**监听示例** + +```typescript +canvas.on('resize', () => { + console.log('画布尺寸已调整'); +}); +``` + +--- + +## 使用示例 + +```typescript +// 创建画布 +const canvas = new MotaOffscreenCanvas2D(); + +// 配置属性 +canvas.size(800, 600); +canvas.withGameScale(true); +canvas.setHD(true); + +// 监听调整事件 +canvas.on('resize', () => { + console.log('画布尺寸已更新'); +}); + +// 绘制内容 +canvas.ctx.fillStyle = 'red'; +canvas.ctx.fillRect(0, 0, canvas.width, canvas.height); + +// 冻结画布 +canvas.freeze(); + +// 复制画布 +const cloned = MotaOffscreenCanvas2D.clone(canvas); +``` diff --git a/docs/api/motajs-render-core/MotaRenderer.md b/docs/api/motajs-render-core/MotaRenderer.md new file mode 100644 index 0000000..ac09213 --- /dev/null +++ b/docs/api/motajs-render-core/MotaRenderer.md @@ -0,0 +1,172 @@ +# MotaRenderer 类 API 文档 + +本文档由 `DeepSeek R1` 模型生成并微调。 + +--- + +## 继承关系 + +```mermaid +graph LR + EventEmitter --> RenderItem + RenderItem --> Container + Container --> MotaRenderer +``` + +--- + +## 属性说明 + +| 属性名 | 类型 | 默认值 | 说明 | +| -------- | ------------------------- | ----------- | ------------------------------- | +| `isRoot` | `boolean` | `true` | 标识为渲染树根节点 | +| `target` | `MotaOffscreenCanvas2D` | - | 绑定的目标画布 | +| `idMap` | `Map` | `new Map()` | ID 到渲染元素的映射表（受保护） | + +--- + +## 构造方法 + +### `constructor` + +**参数** + +- `id`: 目标 canvas 元素的 DOM ID（默认为 `render-main`） + +**行为** + +- 自动绑定指定 ID 的 canvas 元素 +- 初始化渲染循环和事件监听 +- 设置默认锚点为中心点（0.5, 0.5） + +**示例** + +```typescript +// 创建主渲染器 +const renderer = new MotaRenderer(); + +// 创建带自定义 ID 的渲染器 +const customRenderer = new MotaRenderer('game-canvas'); +``` + +--- + +## 方法说明 + +### `getElementById` + +```typescript +function getElementById(id: string): RenderItem | null; +``` + +**描述** +通过 ID 获取渲染树中的元素。 +**示例** + +```typescript +const hero = renderer.getElementById('player'); +``` + +--- + +### `refresh` + +```typescript +function refresh(): void; +``` + +**描述** +强制刷新渲染内容（清空画布并重新渲染所有元素）。 + +--- + +### `toTagTree` + +```typescript +function toTagTree(space?: number): string; +``` + +**描述** +（调试用）将渲染树输出为 XML 格式字符串。 +**参数** + +- `space`: 缩进空格数 + **示例** + +```typescript +console.log(renderer.toTagTree()); +/* 输出示例： + + + + + +*/ +``` + +--- + +### `destroy` + +```typescript +function destroy(): void; +``` + +**描述** +销毁渲染器，释放所有资源并解除事件监听。 + +--- + +## 静态方法说明 + +### `MotaRenderer.get` + +```typescript +function get(id: string): MotaRenderer | undefined; +``` + +**描述** +通过 ID 获取已注册的渲染器实例。 +**示例** + +```typescript +const mainRenderer = MotaRenderer.get('render-main'); +``` + +--- + +## 总使用示例 + +```typescript +// 初始化渲染器 +const renderer = new MotaRenderer(); + +// 创建游戏元素 +const player = new Sprite(); +player.size(32, 32); +player.setRenderFn(canvas => { + canvas.ctx.fillStyle = 'blue'; + canvas.ctx.fillRect(0, 0, 32, 32); +}); + +// 添加交互逻辑 +player.on('click', ev => { + console.log('玩家被点击', ev.offsetX, ev.offsetY); +}); + +// 构建场景 +const scene = new Container('absolute'); +scene.appendChild(player); +renderer.appendChild(scene); + +// 动态查找元素 +setTimeout(() => { + const found = renderer.getElementById('player'); + found?.pos(100, 100); +}, 1000); + +// 销毁渲染器（退出时调用） +window.addEventListener('beforeunload', () => { + renderer.destroy(); +}); +``` diff --git a/docs/api/motajs-render-core/RenderAdapter.md b/docs/api/motajs-render-core/RenderAdapter.md new file mode 100644 index 0000000..6650d97 --- /dev/null +++ b/docs/api/motajs-render-core/RenderAdapter.md @@ -0,0 +1,230 @@ +# RenderAdapter API 文档 + +本文档由 `DeepSeek R1` 模型生成并微调。 + +--- + +```mermaid +graph LR + RenderAdapter --> 无继承关系 +``` + +_RenderAdapter 为独立类，无父类或子类。_ + +--- + +## 属性说明 + +| 属性名 | 类型 | 描述 | +| ------------------ | --------------------------------- | ------------------------------ | +| `items` | `Set` | 所有元素的集合 | +| `id` | `string` | 适配器的唯一标识符 | +| `adapters`（静态） | `Map>` | 全局存储所有已创建的适配器实例 | + +--- + +## 构造方法 + +### `constructor` + +```typescript +function constructor(id: string): RenderAdapter; +``` + +创建一个适配器实例并自动注册到全局 `adapters` 集合中。 +**示例：** + +```typescript +const adapter = new RenderAdapter('ui-elements'); +``` + +--- + +## 方法说明 + +### `add` + +```typescript +function add(item: T): void; +``` + +向集合中添加一个元素。 +**示例：** + +```typescript +adapter.add(document.getElementById('box')); +``` + +### `remove` + +```typescript +function remove(item: T): void; +``` + +从集合中移除一个元素。 +**示例：** + +```typescript +adapter.remove(document.getElementById('box')); +``` + +### `receiveGlobal` + +```typescript +function receiveGlobal( + id: string, + fn: (...params: any[]) => Promise +): void; +``` + +注册全局异步函数（不与具体元素绑定）。 +**示例：** + +```typescript +adapter.receiveGlobal('refresh', async () => { + await fetchData(); +}); +``` + +### `receive` + +```typescript +function receive( + id: string, + fn: (item: T, ...params: any[]) => Promise +): void; +``` + +注册元素的异步执行函数。 +**示例：** + +```typescript +adapter.receive('fadeOut', async (element: HTMLElement) => { + element.style.opacity = '0'; + await new Promise(resolve => setTimeout(resolve, 1000)); +}); +``` + +### `receiveSync` + +```typescript +function receiveSync(id: string, fn: (item: T, ...params: any[]) => any): void; +``` + +注册元素的同步执行函数。 +**示例：** + +```typescript +adapter.receiveSync('highlight', (element: HTMLElement) => { + element.style.backgroundColor = 'yellow'; +}); +``` + +### `all` + +```typescript +function all(fn: string, ...params: any[]): Promise; +``` + +对所有元素执行异步函数，返回 `Promise.all` 结果。 +**示例：** + +```typescript +await adapter.all('fadeOut'); // 所有元素淡出 +``` + +### `any` + +```typescript +function any(fn: string, ...params: any[]): Promise; +``` + +对所有元素执行异步函数，返回 `Promise.any` 结果。 +**示例：** + +```typescript +await adapter.any('loadImage'); // 任一图片加载完成即继续 +``` + +### `sync` + +```typescript +function sync(fn: string, ...params: any[]): R[]; +``` + +对所有元素执行同步函数。 +**示例：** + +```typescript +adapter.sync('highlight'); // 所有元素高亮 +``` + +### `global` + +```typescript +function global(id: string, ...params: any[]): Promise; +``` + +调用全局异步函数。 +**示例：** + +```typescript +await adapter.global('refresh'); // 触发全局刷新 +``` + +### `destroy` + +```typescript +function destroy(): void; +``` + +销毁适配器实例并从全局 `adapters` 中移除。 +**示例：** + +```typescript +adapter.destroy(); +``` + +--- + +## 静态方法说明 + +### `RenderAdapter.get` + +```typescript +function get(id: string): RenderAdapter | undefined; +``` + +通过 ID 获取已注册的适配器实例。 +**示例：** + +```typescript +const adapter = RenderAdapter.get('ui-elements'); +``` + +--- + +## 总使用示例 + +```typescript +// 创建适配器 +const animationAdapter = new RenderAdapter('animations'); + +// 注册动画函数 +animationAdapter.receive('slideLeft', async (element: HTMLElement) => { + element.style.transform = 'translateX(-100px)'; + await new Promise(resolve => setTimeout(resolve, 500)); +}); + +// 添加元素 +const box = document.getElementById('box'); +animationAdapter.add(box); + +// 执行动画 +animationAdapter.all('slideLeft').then(() => { + console.log('所有元素滑动完成'); +}); + +// 销毁适配器 +animationAdapter.destroy(); +``` diff --git a/docs/api/motajs-render-core/RenderItem.md b/docs/api/motajs-render-core/RenderItem.md new file mode 100644 index 0000000..bfa8cc1 --- /dev/null +++ b/docs/api/motajs-render-core/RenderItem.md @@ -0,0 +1,475 @@ +# RenderItem 类 API 文档 + +**需丰富** + +本文档由 `DeepSeek R1` 模型生成并微调。 + +--- + +## 继承关系 + +```mermaid +graph LR + RenderItem --> EventEmitter +``` + +--- + +## 接口说明 + +### IRenderUpdater + +```typescript +interface IRenderUpdater { + update(item?: RenderItem): void; +} +``` + +**描述** +定义元素更新能力的接口。`RenderItem` 通过 `update` 方法通知父元素需要重新渲染。 + +--- + +### IRenderAnchor + +```typescript +interface IRenderAnchor { + anchorX: number; + anchorY: number; + setAnchor(x: number, y: number): void; +} +``` + +**描述** +管理元素锚点的接口。锚点用于定位元素的渲染基准点（如中心点、左上角等）。 + +--- + +### IRenderConfig + +```typescript +interface IRenderConfig { + highResolution: boolean; + antiAliasing: boolean; + setHD(hd: boolean): void; + setAntiAliasing(anti: boolean): void; +} +``` + +**描述** +管理画布渲染配置的接口，控制高清模式和抗锯齿的开关。 + +--- + +### IRenderChildable + +```typescript +interface IRenderChildable { + children: Set; + appendChild(...child: RenderItem[]): void; + removeChild(...child: RenderItem[]): void; + requestSort(): void; +} +``` + +**描述** +管理子元素的接口。需在子类中实现具体逻辑（如 `Container` 元素）。 + +## 属性说明 + +| 属性名 | 类型 | 默认值 | 说明 | +| ---------------- | -------------------------- | --------------- | ---------------------------------------------------- | +| `uid` | `number` | 自动递增 | 元素的唯一标识符 | +| `id` | `string` | `''` | 元素 ID（原则不可重复） | +| `zIndex` | `number` | `0` | 元素的纵深层级（决定遮挡关系） | +| `width` | `number` | `200` | 元素的逻辑宽度 | +| `height` | `number` | `200` | 元素的逻辑高度 | +| `anchorX` | `number` | `0` | 锚点横坐标（`0` 左端，`1` 右端） | +| `anchorY` | `number` | `0` | 锚点纵坐标（`0` 上端，`1` 下端） | +| `type` | `RenderItemPosition` | `'static'` | 渲染模式（`absolute` 绝对定位，`static` 跟随摄像机） | +| `highResolution` | `boolean` | `true` | 是否启用高清画布 | +| `antiAliasing` | `boolean` | `true` | 是否启用抗锯齿 | +| `hidden` | `boolean` | `false` | 元素是否隐藏 | +| `filter` | `string` | `'none'` | 元素的滤镜效果 | +| `composite` | `GlobalCompositeOperation` | `'source-over'` | 渲染混合模式 | +| `alpha` | `number` | `1` | 元素的不透明度（`0` 透明，`1` 不透明） | +| `cursor` | `string` | `'inherit'` | 鼠标悬停时的光标样式 | +| `noEvent` | `boolean` | `false` | 是否忽略交互事件 | +| `isRoot` | `boolean` | `false` | 是否为根元素（需实现 `IRenderTreeRoot` 接口） | +| `connected` | `boolean` | 自动计算 | 元素是否已连接到根元素 | + +**特殊属性说明** + +- `transform`: 元素的变换矩阵（`Transform` 实例），修改时会自动触发 `updateTransform`。 + +--- + +## 构造方法 + +### `constructor(type: RenderItemPosition, enableCache: boolean = true, transformFallThrough: boolean = false)` + +**参数** + +- `type`: 渲染模式（`absolute` 或 `static`） +- `enableCache`: 是否启用渲染缓存（默认启用） +- `transformFallThrough`: 是否启用变换矩阵下穿机制（默认关闭） + +**示例** + +```typescript +const item = new RenderItem('absolute'); +``` + +--- + +## 方法说明 + +### `size` + +```typescript +function size(width: number, height: number): void; +``` + +**描述** +设置元素的尺寸。 +**示例** + +```typescript +item.size(300, 200); // 设置宽度 300，高度 200 +``` + +--- + +### `pos` + +```typescript +function pos(x: number, y: number): void; +``` + +**描述** +设置元素的坐标（等效于修改 `transform` 的平移量）。 +**示例** + +```typescript +item.pos(100, 50); // 设置坐标为 (100, 50) +``` + +--- + +### `append` + +```typescript +function append(parent: RenderItem): void; +``` + +**描述** +将元素添加到指定父元素下。 +**示例** + +```typescript +const parent = new RenderItem('static'); +item.append(parent); // 将 item 添加为 parent 的子元素 +``` + +--- + +### `remove` + +```typescript +function remove(): boolean; +``` + +**描述** +从父元素中移除当前元素。 +**返回值** + +- `true` 表示移除成功，`false` 表示失败。 + **示例** + +```typescript +item.remove(); // 从父元素中移除 +``` + +--- + +### `hide` + +```typescript +function hide(): void; +``` + +**描述** +隐藏元素。 +**示例** + +```typescript +item.hide(); // 隐藏元素 +``` + +--- + +### `show` + +```typescript +function show(): void; +``` + +**描述** +显示元素。 +**示例** + +```typescript +item.show(); // 显示元素 +``` + +--- + +### `delegateTicker` + +```typescript +function delegateTicker(fn: TickerFn, time?: number, end?: () => void): number; +``` + +**描述** +委托动画帧函数，持续执行指定时间。 +**返回值** + +- 委托 ID，可用于移除。 + **示例** + +```typescript +const id = item.delegateTicker(() => { + console.log('每帧执行'); +}, 1000); // 持续 1 秒 +``` + +--- + +### `destroy` + +```typescript +function destroy(): void; +``` + +**描述** +销毁元素，释放资源。 +**示例** + +```typescript +item.destroy(); // 销毁元素 +``` + +### `getAbsolutePosition` + +```typescript +function getAbsolutePosition(x?: number, y?: number): [number, number]; +``` + +**描述** +获取元素在全局坐标系中的绝对坐标。 +**示例** + +```typescript +const [absX, absY] = item.getAbsolutePosition(); // 获取元素原点绝对坐标 +``` + +--- + +### `getBoundingRect` + +```typescript +function getBoundingRect(): DOMRectReadOnly; +``` + +**描述** +获取元素的包围矩形（相对于父元素坐标系）。 +**示例** + +```typescript +const rect = item.getBoundingRect(); +console.log(rect.width, rect.height); +``` + +--- + +### `setZIndex` + +```typescript +function setZIndex(zIndex: number): void; +``` + +**描述** +设置元素的纵深层级（`zIndex` 越大越靠前）。 +**示例** + +```typescript +item.setZIndex(5); // 置顶显示 +``` + +--- + +### `requestRenderFrame` + +```typescript +function requestRenderFrame(fn: () => void): void; +``` + +**描述** +在下一帧渲染时执行函数（适用于需要在渲染流程中更新的操作）。 +**示例** + +```typescript +item.requestRenderFrame(() => { + item.pos(item.x + 1, item.y); // 每帧右移 1 单位 +}); +``` + +--- + +### `setFilter` + +```typescript +function setFilter(filter: string): void; +``` + +**描述** +设置元素的 CSS 滤镜效果（如模糊、灰度等）。 +**示例** + +```typescript +item.setFilter('blur(5px)'); // 添加模糊效果 +``` + +--- + +## 受保护方法说明 + +### `render` + +```typescript +protected abstract render(canvas: MotaOffscreenCanvas2D, transform: Transform): void; +``` + +**描述** +抽象渲染方法，子类必须实现此方法以定义具体渲染逻辑。 +**示例** + +```typescript +class CustomItem extends RenderItem { + protected render(canvas: MotaOffscreenCanvas2D) { + canvas.ctx.fillStyle = 'red'; + canvas.ctx.fillRect(0, 0, this.width, this.height); + } +} +``` + +--- + +### `isActionInElement` + +```typescript +protected isActionInElement(x: number, y: number): boolean; +``` + +**描述** +判断坐标点是否在元素范围内（可覆盖实现自定义碰撞检测）。 +**默认行为** +检测坐标是否在 `[0, width] x [0, height]` 矩形内。 + +--- + +## 静态方法说明 + +### `RenderItem.ticker` + +**类型** + +```typescript +const ticker: Ticker; +``` + +**描述** +全局动画帧管理器，用于处理所有委托的动画帧函数。 + +--- + +## 事件说明 + +事件继承自 [ERenderItemActionEvent](./Event.md#erenderitemactionevent) + +| 事件名 | 参数类型 | 说明 | +| -------------- | ------------------------- | ------------------ | +| `beforeRender` | `Transform` | 渲染前触发 | +| `afterRender` | `Transform` | 渲染后触发 | +| `destroy` | `[]` | 元素销毁时触发 | +| `transform` | `[RenderItem, Transform]` | 变换矩阵更新时触发 | + +--- + +## 总使用示例 + +::: code-group + +```typescript [基础操作] +// 创建元素（以 Sprite 为例） +const item = new Sprite('static'); + +// 设置属性 +item.size(400, 300); +item.pos(100, 50); +item.setAnchor(0.5, 0.5); // 设置中心锚点 +item.setZIndex(2); + +// 监听渲染事件 +item.on('beforeRender', transform => { + console.log('即将渲染，变换矩阵:', transform); +}); + +// 添加动画效果 +const tickerId = item.delegateTicker(time => { + item.pos(Math.sin(time / 1000) * 100, 50); +}); + +// 销毁元素 +setTimeout(() => { + item.destroy(); +}, 5000); +``` + +```typescript [创建自定义元素] +// 创建自定义可交互元素 +class Button extends RenderItem { + constructor() { + super('static'); + this.size(100, 40); + this.on('click', ev => { + console.log('按钮被点击！坐标:', ev.offsetX, ev.offsetY); + }); + } + + protected render(canvas: MotaOffscreenCanvas2D) { + // 绘制圆角矩形按钮 + const ctx = canvas.ctx; + ctx.fillStyle = '#4CAF50'; + ctx.roundRect(0, 0, this.width, this.height, 8); + ctx.fill(); + } +} + +// 使用按钮 +const button = new Button(); +button.pos(200, 150); +button.append(parentElement); + +// 添加鼠标悬停效果 +button.on('enter', () => button.setFilter('brightness(1.2)')); +button.on('leave', () => button.setFilter('none')); +``` + +::: + +# RenderItem 类 API 文档（补充部分） + +本文档由 `DeepSeek R1` 模型生成并微调。 + +--- diff --git a/docs/api/motajs-render-core/Shader.md b/docs/api/motajs-render-core/Shader.md new file mode 100644 index 0000000..5855817 --- /dev/null +++ b/docs/api/motajs-render-core/Shader.md @@ -0,0 +1,8 @@ +# Shader 类 API 文档 + +```mermaid +graph LR + Shader --> GL2 --> RenderItem --> EventEmitter +``` + +用法同 [GL2](./GL2.md) diff --git a/docs/api/motajs-render-core/ShaderProgram.md b/docs/api/motajs-render-core/ShaderProgram.md new file mode 100644 index 0000000..6180271 --- /dev/null +++ b/docs/api/motajs-render-core/ShaderProgram.md @@ -0,0 +1,8 @@ +# Shader 类 API 文档 + +```mermaid +graph LR + ShaderProgram --> GL2Program --> EventEmitter +``` + +用法同 [GL2Program](./GL2Program.md) diff --git a/docs/api/motajs-render-core/Sprite.md b/docs/api/motajs-render-core/Sprite.md new file mode 100644 index 0000000..af845eb --- /dev/null +++ b/docs/api/motajs-render-core/Sprite.md @@ -0,0 +1,118 @@ +# Sprite 类 API 文档 + +本文档由 `DeepSeek R1` 模型生成并微调。 + +--- + +## 继承关系 + +```mermaid +graph LR + Sprite --> RenderItem --> EventEmitter +``` + +--- + +## 属性说明 + +| 属性名 | 类型 | 默认值 | 说明 | +| ---------- | ---------------- | ---------- | -------------------------------------- | +| `renderFn` | `RenderFunction` | `() => {}` | 自定义渲染函数，用于定义精灵的绘制逻辑 | + +--- + +## 构造方法 + +### `constructor` + +**参数** + +- `type`: 渲染模式（`absolute` 绝对定位 / `static` 跟随摄像机） +- `cache`: 是否启用渲染缓存（默认启用） +- `fall`: 是否启用变换矩阵下穿机制（默认关闭） + +**示例** + +```typescript +const sprite = new Sprite('static'); +``` + +--- + +## 方法说明 + +### `setRenderFn` + +```typescript +function setRenderFn(fn: RenderFunction): void; +``` + +**描述** +设置自定义渲染函数，用于定义精灵的具体绘制逻辑。 +**参数** + +- `fn`: 接收画布和变换矩阵的回调函数，格式为 `(canvas, transform) => void` + +**示例** + +```typescript +sprite.setRenderFn((canvas, transform) => { + // 绘制一个红色矩形 + canvas.ctx.fillStyle = 'red'; + canvas.ctx.fillRect(0, 0, sprite.width, sprite.height); +}); +``` + +--- + +## 总使用示例 + +```typescript +// 创建精灵实例 +const sprite = new Sprite('absolute'); +sprite.size(100, 100); // 设置尺寸 +sprite.pos(200, 150); // 设置坐标 + +// 定义渲染逻辑 +sprite.setRenderFn(canvas => { + const ctx = canvas.ctx; + // 绘制渐变圆形 + const gradient = ctx.createRadialGradient(50, 50, 0, 50, 50, 50); + gradient.addColorStop(0, 'yellow'); + gradient.addColorStop(1, 'orange'); + ctx.fillStyle = gradient; + ctx.beginPath(); + ctx.arc(50, 50, 50, 0, Math.PI * 2); + ctx.fill(); +}); + +// 添加到父容器 +container.appendChild(sprite); + +// 监听变换事件 +sprite.on('transform', (item, transform) => { + console.log('精灵变换矩阵更新:', transform); +}); +``` + +--- + +## 高级用法示例 + +```typescript +// 创建动态旋转精灵 +const rotatingSprite = new Sprite('static'); +rotatingSprite.size(80, 80); +rotatingSprite.setRenderFn((canvas, transform) => { + canvas.ctx.fillStyle = 'blue'; + canvas.ctx.fillRect(0, 0, 80, 80); +}); + +// 每帧旋转 +rotatingSprite.delegateTicker(time => { + rotatingSprite.transform.setRotate(time / 1000); +}); + +// 添加到场景 +rootContainer.appendChild(rotatingSprite); +``` diff --git a/docs/api/motajs-render-core/Transform.md b/docs/api/motajs-render-core/Transform.md new file mode 100644 index 0000000..406e77c --- /dev/null +++ b/docs/api/motajs-render-core/Transform.md @@ -0,0 +1,330 @@ +# Transform 类 API 文档 + +以下内容由 `DeepSeek R1` 模型生成并微调。 + +--- + +## 继承关系 + +```mermaid +graph LR + Transform --> EventEmitter +``` + +--- + +## 属性说明 + +| 属性名 | 类型 | 默认值 | 说明 | +| -------------- | --------------------- | ----------- | ----------------------------------------------------------- | +| `mat` | `mat3` | 单位矩阵 | 存储当前变换的 3x3 矩阵 | +| `x` | `number` | `0` | 水平平移量 | +| `y` | `number` | `0` | 垂直平移量 | +| `scaleX` | `number` | `1` | 水平缩放比例 | +| `scaleY` | `number` | `1` | 垂直缩放比例 | +| `rad` | `number` | `0` | 旋转弧度值（范围：`[0, 2π)`） | +| `modified` | `boolean`（私有） | `false` | 标识变换是否被修改过 | +| `bindedObject` | `ITransformUpdatable` | `undefined` | 绑定的对象（当变换更新时自动调用其 `updateTransform` 方法） | + +--- + +## 构造方法 + +### `constructor` + +创建一个新的变换实例，初始化为单位矩阵。 + +```typescript +const transform = new Transform(); +``` + +--- + +## 方法说明 + +### `bind` + +```typescript +function bind(obj?: ITransformUpdatable): void; +``` + +**描述** +绑定一个对象，当变换更新时自动调用其 `updateTransform` 方法（若存在）。 + +**示例** + +```typescript +const obj = { updateTransform: () => console.log('Transform updated!') }; +transform.bind(obj); +``` + +--- + +### `reset` + +```typescript +function reset(): void; +``` + +**描述** +重置所有参数到初始状态（单位矩阵）。 + +**示例** + +```typescript +transform.reset(); // 重置为 x=0, y=0, scaleX=1, scaleY=1, rad=0 +``` + +--- + +### `scale` + +```typescript +function scale(x: number, y: number = x): this; +``` + +**描述** +叠加缩放变换（相对于当前状态）。 + +**参数** + +- `x`: 水平缩放比例 +- `y`: 垂直缩放比例（默认同 `x`） + +**示例** + +```typescript +transform.scale(2); // 水平和垂直均放大2倍 +transform.scale(1.5, 0.5); // 水平放大1.5倍，垂直缩小到0.5倍 +``` + +--- + +### `translate` + +```typescript +function translate(x: number, y: number): this; +``` + +**描述** +叠加平移变换（相对于当前状态）。 + +**参数** + +- `x`: 水平平移量 +- `y`: 垂直平移量 + +**示例** + +```typescript +transform.translate(100, 50); // 向右平移100单位，向下平移50单位 +``` + +--- + +### `rotate` + +```typescript +function rotate(rad: number): this; +``` + +**描述** +叠加旋转变换（相对于当前状态）。 + +**参数** + +- `rad`: 旋转弧度值 + +**示例** + +```typescript +transform.rotate(Math.PI / 2); // 顺时针旋转90度 +``` + +--- + +### `setScale` + +```typescript +function setScale(x: number, y: number = x): this; +``` + +**描述** +直接设置缩放比例（非叠加，覆盖当前状态）。 + +**示例** + +```typescript +transform.setScale(3, 2); // 设置水平缩放3倍，垂直缩放2倍 +``` + +--- + +### `setTranslate` + +```typescript +function setTranslate(x: number, y: number): this; +``` + +**描述** +直接设置平移量（非叠加，覆盖当前状态）。 + +**示例** + +```typescript +transform.setTranslate(200, 100); // 直接定位到(200, 100) +``` + +--- + +### `setRotate` + +```typescript +function setRotate(rad: number): this; +``` + +**描述** +直接设置旋转角度（非叠加，覆盖当前状态）。 + +**示例** + +```typescript +transform.setRotate(Math.PI); // 设置旋转180度 +``` + +--- + +### `transformed` + +```typescript +function transformed(x: number, y: number): vec3; +``` + +**描述** +将坐标点 `(x, y)` 应用当前变换矩阵，返回变换后的坐标。 + +**返回值** + +- `vec3`: 变换后的三维坐标（`[x, y, 1]`） + +**示例** + +```typescript +const point = transform.transformed(10, 20); // 应用变换后的坐标 +``` + +--- + +### `untransformed` + +```typescript +function untransformed(x: number, y: number): vec3; +``` + +**描述** +将坐标点 `(x, y)` 逆向应用当前变换矩阵，返回原坐标。 + +**示例** + +```typescript +const origin = transform.untransformed(50, 30); // 逆向变换后的坐标 +``` + +--- + +### `clone` + +```typescript +function clone(): Transform; +``` + +**描述** +复制当前变换实例。 + +**示例** + +```typescript +const cloned = transform.clone(); // 生成一个完全相同的副本 +``` + +--- + +## 静态方法说明 + +### `Transform.transformed` + +```typescript +function transformed(transform: Transform, x: number, y: number): vec3; +``` + +**描述** +静态方法，直接通过变换矩阵计算坐标点 `(x, y)` 的变换结果。 + +**示例** + +```typescript +const result = Transform.transformed(transform, 5, 5); +``` + +--- + +### `Transform.untransformed` + +```typescript +function untransformed(transform: Transform, x: number, y: number): vec3; +``` + +**描述** +静态方法，直接通过变换矩阵逆向计算坐标点 `(x, y)` 的原位置。 + +**示例** + +```typescript +const origin = Transform.untransformed(transform, 100, 50); +``` + +--- + +## 接口说明 + +### `ITransformUpdatable` + +```typescript +interface ITransformUpdatable { + updateTransform?(): void; +} +``` + +**描述** +可绑定对象的接口，当变换更新时触发 `updateTransform` 方法（可选）。 + +--- + +## 总使用示例 + +```typescript +// 创建变换实例 +const transform = new Transform(); + +// 应用变换 +transform + .translate(50, 30) + .scale(2) + .rotate(Math.PI / 4); + +// 绑定对象 +const obj = { + updateTransform: () => console.log('Transform updated!') +}; +transform.bind(obj); + +// 坐标转换 +const transformedPoint = transform.transformed(10, 10); +console.log('Transformed point:', transformedPoint); + +// 复制变换 +const cloned = transform.clone(); + +// 静态方法使用 +const staticResult = Transform.transformed(cloned, 5, 5); +``` diff --git a/docs/api/motajs-render-core/functions.md b/docs/api/motajs-render-core/functions.md new file mode 100644 index 0000000..a428eaf --- /dev/null +++ b/docs/api/motajs-render-core/functions.md @@ -0,0 +1,119 @@ +# 函数 API 文档 + +本文档由 `DeepSeek R1` 模型生成并微调。 + +--- + +## 函数说明 + +### `isWebGLSupported` + +**功能** +检测浏览器是否支持 WebGL 1.0 +**返回值** + +- `true`: 支持 +- `false`: 不支持 + +**示例** + +```typescript +if (isWebGLSupported()) { + // 初始化 WebGL 1.0 功能 +} +``` + +--- + +### `isWebGL2Supported` + +**功能** +检测浏览器是否支持 WebGL 2.0 +**返回值** + +- `true`: 支持 +- `false`: 不支持 + +--- + +### `addTiming` + +**功能** +组合两个缓动函数为加法函数 +**数学表达** +`newTiming(p) = timing1(p) + timing2(p)` + +**参数** + +- `timing1`: 第一个缓动函数 +- `timing2`: 第二个缓动函数 + +**示例** + +```typescript +const linear = (p: number) => p; +const bounce = (p: number) => p * p; +const combined = addTiming(linear, bounce); // p + p² +``` + +--- + +### `multiplyTiming` + +**功能** +组合两个缓动函数为乘法函数 +**数学表达** +`newTiming(p) = timing1(p) * timing2(p)` + +--- + +### `isSetEqual` + +**功能** +判断两个集合是否相等（元素完全相同） +**实现逻辑** + +1. 直接引用相同 → `true` +2. 大小不同 → `false` +3. 检查 set1 是否是 set2 的子集 + +--- + +### `transformCanvas` + +**功能** +将变换矩阵应用到画布上下文 +**实现逻辑** + +```typescript +const mat = transform.mat; // 获取 3x3 矩阵 +const [a, b, , c, d, , e, f] = mat; // 分解为 2D 变换参数 +ctx.transform(a, b, c, d, e, f); // 应用变换 +``` + +**参数** + +- `canvas`: 目标画布对象 +- `transform`: 变换矩阵 + +**示例** + +```typescript +const transform = new Transform(); +transform.translate(100, 50); +transformCanvas(myCanvas, transform); // 应用平移变换 +``` + +--- + +## 工具函数关系图 + +```mermaid +graph LR + checkSupport --> isWebGLSupported + checkSupport --> isWebGL2Supported + addTiming --> 组合缓动函数 + multiplyTiming --> 组合缓动函数 + isSetEqual --> 集合操作 + transformCanvas --> 矩阵变换 +``` diff --git a/docs/api/motajs-render-core/index.md b/docs/api/motajs-render-core/index.md index cff088e..9ddbb44 100644 --- a/docs/api/motajs-render-core/index.md +++ b/docs/api/motajs-render-core/index.md @@ -1,3 +1 @@ # @motajs/render-core - -目录：