From 4e5803d3492d8905f400eadd347add1a51ce5ab4 Mon Sep 17 00:00:00 2001 From: AZhan Date: Fri, 2 Aug 2024 17:09:09 +0800 Subject: [PATCH] Update `XR` , `Start` and `Input` doc (#2275) * feat: update doc --- docs/zh/_meta.json | 8 +- docs/zh/core/engine.md | 66 +++-- docs/zh/graphics/2D/2d.md | 13 +- docs/zh/graphics/2D/lottie.md | 14 +- docs/zh/graphics/2D/sprite.md | 6 +- docs/zh/graphics/2D/spriteAtlas.md | 26 +- docs/zh/graphics/2D/spriteMask.md | 4 +- docs/zh/graphics/2D/spriteRenderer.md | 4 +- docs/zh/graphics/camera/camera.md | 8 +- docs/zh/graphics/camera/component.md | 94 +++---- docs/zh/graphics/camera/control.md | 2 + docs/zh/graphics/camera/depthTexture.md | 14 - docs/zh/graphics/camera/texture.md | 19 ++ docs/zh/graphics/mesh/mesh.md | 16 +- docs/zh/graphics/renderer/renderer.md | 4 + docs/zh/graphics/shader/shaderLab/intro.md | 2 +- docs/zh/input/framebuffer-picker.md | 2 +- docs/zh/input/input.md | 37 +++ docs/zh/input/pointer.md | 6 +- docs/zh/miniProgram/miniProgame.md | 240 ++++++++++++++++++ docs/zh/quick-start/_meta.json | 8 + docs/zh/quick-start/overview.md | 84 +++--- .../{ => quickStart}/core-concept.md | 0 .../{ => quickStart}/flappy-bird.md | 0 docs/zh/quick-start/version.md | 72 ++++++ docs/zh/script/script.md | 17 ++ docs/zh/xr/_meta.json | 14 + docs/zh/xr/input.md | 57 ----- docs/zh/xr/manager.md | 46 ---- docs/zh/xr/overall.md | 30 ++- docs/zh/xr/quickStart/debug.md | 57 +++++ docs/zh/xr/quickStart/develop.md | 114 +++++++++ docs/zh/xr/session.md | 37 --- docs/zh/xr/start.md | 80 ------ docs/zh/xr/{ => system}/camera.md | 12 +- docs/zh/xr/{ => system}/features.md | 42 +-- docs/zh/xr/system/input.md | 61 +++++ docs/zh/xr/system/manager.md | 57 +++++ docs/zh/xr/system/session.md | 39 +++ docs/zh/xr/system/toolkit.md | 105 ++++++++ examples/xr-ar-imageTracking.ts | 2 +- 41 files changed, 1087 insertions(+), 432 deletions(-) delete mode 100644 docs/zh/graphics/camera/depthTexture.md create mode 100644 docs/zh/graphics/camera/texture.md create mode 100644 docs/zh/input/input.md create mode 100644 docs/zh/miniProgram/miniProgame.md create mode 100644 docs/zh/quick-start/_meta.json rename docs/zh/quick-start/{ => quickStart}/core-concept.md (100%) rename docs/zh/quick-start/{ => quickStart}/flappy-bird.md (100%) create mode 100644 docs/zh/quick-start/version.md create mode 100644 docs/zh/script/script.md create mode 100644 docs/zh/xr/_meta.json delete mode 100644 docs/zh/xr/input.md delete mode 100644 docs/zh/xr/manager.md create mode 100644 docs/zh/xr/quickStart/debug.md create mode 100644 docs/zh/xr/quickStart/develop.md delete mode 100644 docs/zh/xr/session.md delete mode 100644 docs/zh/xr/start.md rename docs/zh/xr/{ => system}/camera.md (65%) rename docs/zh/xr/{ => system}/features.md (67%) create mode 100644 docs/zh/xr/system/input.md create mode 100644 docs/zh/xr/system/manager.md create mode 100644 docs/zh/xr/system/session.md create mode 100644 docs/zh/xr/system/toolkit.md diff --git a/docs/zh/_meta.json b/docs/zh/_meta.json index 5ade027345..01db3970c4 100644 --- a/docs/zh/_meta.json +++ b/docs/zh/_meta.json @@ -54,7 +54,7 @@ } }, "input": { - "title": "输入", + "title": "交互", "theme": { "collapse": true } @@ -71,6 +71,12 @@ "collapse": true } }, + "miniProgram": { + "title": "小程序", + "theme": { + "collapse": true + } + }, "art": { "title": "美术", "theme": { diff --git a/docs/zh/core/engine.md b/docs/zh/core/engine.md index 9d24b7159a..55b2fe8786 100644 --- a/docs/zh/core/engine.md +++ b/docs/zh/core/engine.md @@ -5,7 +5,7 @@ type: 核心 label: Core --- -`Engine` 在 Galacean Engine 中扮演着总控制器的角色，主要包含了**画布**、**渲染控制**和**引擎子系统管理**等三大功能： +`Engine` 在 Galacean Engine 中扮演着总控制器的角色，主要包含了**画布**、**渲染控制**和**引擎子系统管理**等功能： - **[画布](/docs/core/canvas)**：主画布相关的操作，如修改画布宽高等。 - **渲染控制**： 控制渲染的执行/暂停/继续、垂直同步等功能。 @@ -25,46 +25,60 @@ label: Core const engine = await WebGLEngine.create({ canvas: "canvas" }); ``` -> `WebGLEngine.create` 不仅承担着实例化引擎的职责，还负责渲染上下文的配置和某些子系统的初始化。 +`WebGLEngine.create` 不仅承担着实例化引擎的职责，还负责渲染上下文的配置和某些子系统的初始化，下方是创建引擎时传入配置的类型说明： -### 渲染上下文 +```mermaid +--- +title: WebGLEngineConfiguration Interface +--- +classDiagram + EngineConfiguration <|-- WebGLEngineConfiguration + class EngineConfiguration { + <> + +IPhysics physics + +IXRDevice xrDevice + +ColorSpace colorSpace + +IShaderLab shaderLab + +IInputOptions input + } + + class WebGLEngineConfiguration{ + <> + +HTMLCanvasElement | OffscreenCanvas | string canvas + +WebGLGraphicDeviceOptions graphicDeviceOptions + } +``` -开发者可以在 [导出界面](/docs/assets-build) 设置上下文的渲染配置。 +编辑器导出的项目通常自动设置了编辑器配置的相关选项，比如开发者可以在 [导出界面](/docs/assets-build) 设置上下文的渲染配置： -您也可以通过脚本设置 [WebGLEngine](${api}rhi-webgl/WebGLEngine) 的第三个参数 [WebGLGraphicDeviceOptions](${api}rhi-webgl/WebGLGraphicDeviceOptions) 来进行管理，拿**画布透明**来举例，引擎默认是将画布的透明通道开启的，即画布会和背后的网页元素混合，如果需要关闭透明，可以这样设置： +又或者在编辑器的项目设置界面选择物理后端与 XR 后端： + + + +您也可以修改代码变更引擎配置，拿**画布透明**来举例，引擎默认是将画布的透明通道开启的，即画布会和背后的网页元素混合，如果需要关闭透明，可以这样设置： ```typescript const engine = await WebGLEngine.create({ canvas: htmlCanvas, - graphicDeviceOptions: { alpha: false }, + graphicDeviceOptions: { alpha: false } }); ``` 类似的，可以用 `webGLMode` 控制 WebGL1/2，除 `webGLMode` 外的属性将透传给上下文，详情可参考 [getContext 参数释义](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext#parameters)。 -### 物理系统 - -可参考 [物理系统](/docs/physics-overall) 文档 - -### 交互系统 - -可参考 [交互系统](/docs/input) 文档 - -### XR 系统 - -可参考 [XR 系统](/docs/xr-overall) 文档 +更多相关配置信息，可参考[物理系统](/docs/physics-overall)、[交互系统](/docs/input)、[XR 系统](/docs/xr-overall)。 ## 属性 -| 属性名称 | 属性释义 | -| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [time](/apis/core/#Engine-time) | 引擎时间相关的信息。 | -| [vSyncCount](/apis/core/#Engine-vSyncCount) | 引擎默认开启[垂直同步](https://baike.baidu.com/item/%E5%9E%82%E7%9B%B4%E5%90%8C%E6%AD%A5/7263524?fromtitle=V-Sync&fromid=691778)且刷新率 `vSyncCount` 为`1`，即与屏幕刷新率保持一致。如果 `vSyncCount` 设置为`2`，则每刷新 2 帧，引擎更新一次。 | -| [resourceManager](/apis/core/#Engine-resourceManager) | 资源管理 | -| [sceneManager](/apis/core/#Engine-sceneManager) | 场景管理。_Engine_ 是总控制器，_Scene_ 作为场景单元，可以方便大型场景的实体管理；_Camera_ 作为组件挂载在 _Scene_ 中的某一实体下，和现实中的摄像机一样，可以选择拍摄 _Scene_ 中的任何实体 ，最后渲染到屏幕上的一块区域或者离屏渲染。 | -| [inputManager](/apis/core/#Engine-inputManager) | 交互管理 | +| 属性名称 | 属性释义 | +| --- | --- | +| [time](/apis/core/#Engine-time) | 引擎时间相关信息，详情可参考[时间](/docs/core/time/) | +| [vSyncCount](/apis/core/#Engine-vSyncCount) | 垂直同步刷新率，引擎默认开启[垂直同步](https://baike.baidu.com/item/%E5%9E%82%E7%9B%B4%E5%90%8C%E6%AD%A5/7263524?fromtitle=V-Sync&fromid=691778)且刷新率 `vSyncCount` 为`1` （与屏幕刷新率保持一致）。若 `vSyncCount` 设置为`2`，则屏幕每刷新 2 帧，引擎更新 1 次。 | +| [resourceManager](/apis/core/#Engine-resourceManager) | 资源管理器，一般通过它进行资产的[加载](/docs/assets/load/)和[释放](/docs/assets/gc/) | +| [sceneManager](/apis/core/#Engine-sceneManager) | 场景管理器。Galacean 支持多场景同时渲染，通过场景管理器可以方便地管理当前场景的增删改查，详情可参考[场景](/docs/core/scene/) | +| [inputManager](/apis/core/#Engine-inputManager) | 交互管理器，一般通过它获取键盘，触控与滚轮信息，详情可参考[交互](/docs/input/input/) | ### 刷新率 @@ -86,8 +100,8 @@ engine.targetFrameRate = 120; ## 方法 -| 方法名称 | 方法释义 | -| ------------------------------------ | ------------------ | +| 方法名称 | 方法释义 | +| ------------------------------------- | ------------------ | | [run](/apis/core/#Engine-run) | 执行引擎渲染帧循环 | | [pause](/apis/core/#Engine-pause) | 暂停引擎渲染帧循环 | | [resume](/apis/core/#Engine-resume) | 恢复引擎渲渲染循环 | diff --git a/docs/zh/graphics/2D/2d.md b/docs/zh/graphics/2D/2d.md index b64a47abb0..9b67f1d5d7 100644 --- a/docs/zh/graphics/2D/2d.md +++ b/docs/zh/graphics/2D/2d.md @@ -19,10 +19,11 @@ Galacean 是 3D/2D 的互动解决方案，您可以在**编辑器主页**的** 接下来让我们来深入了解以下内容： -- [精灵](/docs/graphics-2d-sprite) -- [精灵渲染器](/docs/graphics-2d-spriteRenderer) -- [精灵遮罩](/docs/graphics-2d-spriteMask) -- [文字渲染器](/docs/graphics-2d-text) -- [精灵图集](/docs/graphics-2d-spriteAtlas) -- [Lottie](/docs/graphics-2d-lottie) +- [精灵](/docs/graphics/2D/sprite/) +- [精灵渲染器](/docs/graphics/2D/spriteRenderer/) +- [精灵遮罩](/docs/graphics/2D/spriteMask/) +- [文字渲染器](/docs/graphics/2D/text/) +- [精灵图集](/docs/graphics/2D/spriteAtlas/) +- [Lottie](/docs/graphics/2D/lottie/) - [Spine](/docs/graphics/2D/spine/overview) + diff --git a/docs/zh/graphics/2D/lottie.md b/docs/zh/graphics/2D/lottie.md index 08d13558af..2c4a6f1ca5 100644 --- a/docs/zh/graphics/2D/lottie.md +++ b/docs/zh/graphics/2D/lottie.md @@ -144,6 +144,12 @@ engine.resourceManager.load({ +### 版本依赖 +| 引擎版本 | Lottie 版本 | +| :--- | :--- | +| 1.2.x | 1.1.0-beta.0 | +| 1.3.x | 1.1.0-beta.0 | + ## 性能方面的建议 - 动画简单化。创建动画时需时刻记着保持 json 文件的精简，比如尽量不使用占用空间最多的路径关键帧动画。诸如自动跟踪描绘、颤动之类的技术会使得 json 文件变得非常大且耗性能。 @@ -163,10 +169,4 @@ engine.resourceManager.load({ - 删除那些关闭了和无用的属性。 - 只导出 1x 图。 - 为了防止 lottie 导出的兼容性问题，请尽量使用英文版本 AE ，图层需简洁，命名清晰 -- 避免大面积矢量部分，以及大面积粒子效果 - -### Lottie 使用版本说明 -| 引擎版本 | Lottie 版本 | -| :--- | :--- | -| 1.2.x | 1.1.0-beta.0 | -| 1.3.x | 1.1.0-beta.0 | \ No newline at end of file +- 避免大面积矢量部分，以及大面积粒子效果 \ No newline at end of file diff --git a/docs/zh/graphics/2D/sprite.md b/docs/zh/graphics/2D/sprite.md index ea7bef9d6d..4291c3ca38 100644 --- a/docs/zh/graphics/2D/sprite.md +++ b/docs/zh/graphics/2D/sprite.md @@ -6,7 +6,7 @@ group: 2D label: Graphics/2D --- -[Sprite](/apis/core/#Sprite) 是 2D 项目中最重要的资产，他从 [Texture2D](/docs/graphics-texture-2d) 中获取图形源数据，通过设置 [region](/apis/core/#Sprite-region)，[pivot](/apis/core/#Sprite-pivot) 等属性定制期望的渲染结果，若将其赋予[SpriteRenderer](/apis/core/#SpriteRenderer)，挂载了精灵渲染器的节点就可以在三维空间中展示 2D 图片，若将其赋予[SpriteMask](/docs/graphics-2d-spriteMask)，挂载了精灵遮罩的节点就可以对相应的 2D 元素实现遮罩效果，接下来就让我们深入了解精灵的属性和用法。 +[Sprite](/apis/core/#Sprite) 是 2D 项目中最重要的资产，他从 [Texture2D](/docs/graphics/texture/2d/) 中获取图形源数据，通过设置 [region](/apis/core/#Sprite-region)，[pivot](/apis/core/#Sprite-pivot) 等属性定制期望的渲染结果，若将其赋予[SpriteRenderer](/apis/core/#SpriteRenderer)，挂载了精灵渲染器的节点就可以在三维空间中展示 2D 图片，若将其赋予[SpriteMask](/docs/graphics/2D/spriteMask/)，挂载了精灵遮罩的节点就可以对相应的 2D 元素实现遮罩效果，接下来就让我们深入了解精灵的属性和用法。 ## 属性 @@ -33,13 +33,13 @@ pivot 代表精灵中心在 region 中的位置，如下： #### 上传精灵 -在 **[资产面板](/docs/assets-interface)** 空白处依次 **右键** → **Upload** → **Sprite** → **选中对应图片** 即可上传精灵资产，上传成功后当前资产列表会同步添加一份名为 `图片名.png` 的纹理资产和一份 `图片名-spr.png` 的精灵资产 +在 **[资产面板](/docs/assets/interface/)** 空白处依次 **右键** → **Upload** → **Sprite** → **选中对应图片** 即可上传精灵资产，上传成功后当前资产列表会同步添加一份名为 `图片名.png` 的纹理资产和一份 `图片名-spr.png` 的精灵资产 avatar #### 创建空白精灵 -在 **[资产面板](/docs/assets-interface)** 空白处依次 **右键** → **Create** → **Sprite** 即可创建一份空白的精灵资产。 +在 **[资产面板](/docs/assets/interface/)** 空白处依次 **右键** → **Create** → **Sprite** 即可创建一份空白的精灵资产。 avatar diff --git a/docs/zh/graphics/2D/spriteAtlas.md b/docs/zh/graphics/2D/spriteAtlas.md index 766de90980..5de50be9c0 100644 --- a/docs/zh/graphics/2D/spriteAtlas.md +++ b/docs/zh/graphics/2D/spriteAtlas.md @@ -20,7 +20,7 @@ label: Graphics/2D ### 创建精灵图集 -在 **[资产面板](/docs/assets-interface)** 内右键，选择`功能列表`中的`创建`，并选中`精灵图集`，此时，一个空白的精灵图集资产就创建成功了。 +在 **[资产面板](/docs/assets/interface/)** 内右键，选择`功能列表`中的`创建`，并选中`精灵图集`，此时，一个空白的精灵图集资产就创建成功了。 buildBox @@ -72,23 +72,27 @@ label: Graphics/2D | 设置名称 | 释义 | | ------------------ | ---------------------------------------- | -| 纹理最大宽度 | 打包得到纹理的最大限制宽度 | -| 纹理最大高度 | 打包得到纹理的最大限制高度 | +| 纹理最大宽度 | 打包得到纹理的最大限制宽度(1，2048] | +| 纹理最大高度 | 打包得到纹理的最大限制高度(1，2048] | | 边缘填充 | 打包精灵的边缘填充宽度 | | 允许旋转（未启用） | 是否通过旋转提高图集打包的空间利用率 | | 空白裁减（未启用） | 是否通过空白裁减提高图集打包的空间利用率 | +若打包遇到如下警告，说明图集结果的尺寸超过了纹理最大宽度和最大高度，此时可通过调整`纹理最大宽度`与`纹理最大高度`或**重新编排**打包的散图解决。 + + + #### 导出设置 image-20231208165430415 -| 属性 | 值 | -| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| 循环模式 U（[wrapModeU](/apis/core/#Texture-wrapModeU)） | 截取模式（[Clamp](/apis/core/#TextureWrapMode-Clamp)）、 重复模式（[Repeat](/apis/core/#TextureWrapMode-Repeat)）、镜像重复模式（[Mirror](/apis/core/#TextureWrapMode-Mirror)） | -| 循环模式 V（[wrapModeV](/apis/core/#Texture-wrapModeV)） | 截取模式（[Clamp](/apis/core/#TextureWrapMode-Clamp)）、重复模式（[Repeat](/apis/core/#TextureWrapMode-Repeat)）、 镜像重复模式（[Mirror](/apis/core/#TextureWrapMode-Mirror)） | -| 过滤模式（[filterMode](/apis/core/#Texture-filterMode)） | 点过滤（[Point](/apis/core/#TextureFilterMode-Point)）、双线性过滤（[Bilinear](/apis/core/#TextureFilterMode-Bilinear)）、 三线性过滤（[Trilinear](/apis/core/#TextureFilterMode-Trilinear)） | -| 各向异性过滤等级（[anisoLevel](/apis/core/#Texture-anisoLevel)） | 向向异性等级，1 ~ 16 | -| 纹理映射([Mipmap](/apis/core/#Texture-generateMipmaps)） | true , false | +| 属性 | 值 | +| --- | --- | +| 循环模式 U（[wrapModeU](/apis/core/#Texture-wrapModeU)） | 截取模式（[Clamp](/apis/core/#TextureWrapMode-Clamp)）、 重复模式（[Repeat](/apis/core/#TextureWrapMode-Repeat)）、镜像重复模式（[Mirror](/apis/core/#TextureWrapMode-Mirror)） | +| 循环模式 V（[wrapModeV](/apis/core/#Texture-wrapModeV)） | 截取模式（[Clamp](/apis/core/#TextureWrapMode-Clamp)）、重复模式（[Repeat](/apis/core/#TextureWrapMode-Repeat)）、 镜像重复模式（[Mirror](/apis/core/#TextureWrapMode-Mirror)） | +| 过滤模式（[filterMode](/apis/core/#Texture-filterMode)） | 点过滤（[Point](/apis/core/#TextureFilterMode-Point)）、双线性过滤（[Bilinear](/apis/core/#TextureFilterMode-Bilinear)）、 三线性过滤（[Trilinear](/apis/core/#TextureFilterMode-Trilinear)） | +| 各向异性过滤等级（[anisoLevel](/apis/core/#Texture-anisoLevel)） | 向向异性等级，1 ~ 16 | +| 纹理映射([Mipmap](/apis/core/#Texture-generateMipmaps)） | true , false | ### 最佳实践 @@ -144,7 +148,7 @@ galacean-tool-atlas p inputPath -o outputName engine.resourceManager .load({ url: "https://*cdnDir*/*atlasName*.atlas", - type: AssetType.SpriteAtlas, + type: AssetType.SpriteAtlas }) .then((atlas) => { // Get all sprites. diff --git a/docs/zh/graphics/2D/spriteMask.md b/docs/zh/graphics/2D/spriteMask.md index b2d874508e..4aa093ba2f 100644 --- a/docs/zh/graphics/2D/spriteMask.md +++ b/docs/zh/graphics/2D/spriteMask.md @@ -6,11 +6,11 @@ group: 2D label: Graphics/2D --- -精灵遮罩组件用于对 3D/2D 场景中的[精灵](/docs/graphics-2d-spriteRenderer)和[文本](/docs/graphics-2d-text)实现遮罩效果。 +精灵遮罩组件用于对 3D/2D 场景中的[精灵渲染器](/docs/graphics/2D/spriteRenderer/)和[文字渲染器](/docs/graphics/2D/text/)实现遮罩效果。 -通过 [SpriteMask](/apis/core/#SpriteMask) 提供的参数来控制和 [精灵](/docs/graphics-2d-sprite) 发生作用。 +通过 [SpriteMask](/apis/core/#SpriteMask) 提供的参数来控制和 [精灵](/docs/graphics/2D/sprite/) 发生作用。 | 参数 | 类型 | 说明 | | :-------------- | :----- | :----------------------------------------------------------------------------------------------- | diff --git a/docs/zh/graphics/2D/spriteRenderer.md b/docs/zh/graphics/2D/spriteRenderer.md index 10f092ba9c..18d1e0fc65 100644 --- a/docs/zh/graphics/2D/spriteRenderer.md +++ b/docs/zh/graphics/2D/spriteRenderer.md @@ -87,10 +87,10 @@ spriteRenderer.sprite = sprite; ### 遮罩 -请参考[精灵遮罩](/docs/graphics-2d-spriteMask)文档。 +请参考[精灵遮罩](/docs/graphics/2D/spriteMask/)文档。 ## 自定义材质 -请参考[自定义着色器](/docs/graphics-shader-custom)文档。 +请参考[自定义着色器](/docs/graphics/shader/custom/)文档。 diff --git a/docs/zh/graphics/camera/camera.md b/docs/zh/graphics/camera/camera.md index dca30df308..e36b258193 100644 --- a/docs/zh/graphics/camera/camera.md +++ b/docs/zh/graphics/camera/camera.md @@ -50,7 +50,7 @@ Galacean 中的局部坐标与世界坐标遵循`右手坐标系`，因此相机 介绍了相机的基本概念，接下来让我们上手： -- 在场景中添加[相机组件](/docs/graphics-camera-component) -- 通过[相机控件](/docs/graphics-camera-control)来更方便地操控[相机组件](/docs/graphics-camera-component) -- 在场景中使用[多相机](graphics-camera-multiCamera) -- 获取[相机深度纹理](graphics-camera-depthTexture) +- 在场景中添加[相机组件](/docs/graphics/camera/component/) +- 通过[相机控件](/docs/graphics/camera/control/)来更方便地操控[相机组件](/docs/graphics/camera/component/) +- 在场景中使用[多相机](/docs/graphics/camera/multiCamera/) +- 获取[相机纹理](/docs/graphics/camera/texture/) diff --git a/docs/zh/graphics/camera/component.md b/docs/zh/graphics/camera/component.md index f227af2468..b385ba9c22 100644 --- a/docs/zh/graphics/camera/component.md +++ b/docs/zh/graphics/camera/component.md @@ -60,27 +60,27 @@ camera.enableHDR = true; 其中每个属性对应的功能如下： -| 类型 | 属性 | 解释 | -| :------- | :------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | -| 通用 | [isOrthographic](/apis/core/#Camera-isOrthographic) | 通过设置 [isOrthographic](/apis/core/#Camera-isOrthographic) 来决定透视投影或正交投影。，默认是 `false` | -| | [nearClipPlane](/apis/core/#Camera-nearClipPlane) | 近裁剪平面 | -| | [farClipPlane](/apis/core/#Camera-farClipPlane) | 远裁剪平面 | -| | [viewport](/apis/core/#Camera-viewport) | 视口，确定内容最后被渲染到目标设备里的范围。 | -| | [priority](/apis/core/#Camera-priority) | 渲染优先级，用来确定在多相机的情况下按照什么顺序去渲染相机包含的内容。 | -| | [enableFrustumCulling](/apis/core/#Camera-enableFrustumCulling) | 是否开启视锥剔除，默认为 `true` | -| | [clearFlags](/apis/core/#Camera-clearFlags) | 在渲染这个相机前清理画布缓冲的标记 | -| | [cullingMask](/apis/core/#Camera-cullingMask) | 裁剪遮罩，用来选择性地渲染场景中的渲染组件。 | -| | [aspectRatio](/apis/core/#Camera-aspectRatio) | 渲染目标的宽高比，一般是根据 canvas 大小自动计算，也可以手动改变（不推荐） | -| | [renderTarget](/apis/core/#Camera-renderTarget) | 渲染目标，确定内容被渲染到哪个目标上。 | -| | [pixelViewport](/apis/core/#Camera-pixelViewport) | 屏幕上相机的视口（以像素坐标表示）。 在像素屏幕坐标中，左上角为(0, 0)，右下角为(1.0, 1.0)。 | -| 透视投影 | [fieldOfView](/apis/core/#Camera-fieldOfView) | 视角 | -| 正交投影 | [orthographicSize](/apis/core/#Camera-orthographicSize) | 正交模式下相机的一半尺寸 | -| 渲染相关 | [depthTextureMode](<(/apis/core/#Camera-depthTextureMode)>) | 深度纹理模式，默认为`DepthTextureMode.None`，如果开启，可以在 shader 中使用 `camera_DepthTexture` 深度纹理。 -| | [opaqueTextureEnabled](<(/apis/core/#Camera-opaqueTextureEnabled)>) | 是否启用非透明纹理，默认关闭，如果启用，可以在透明队列的 shader 中使用 `camera_OpaqueTexture` 非透明纹理。 | -| | [opaqueTextureDownsampling](<(/apis/core/#Camera-opaqueTextureDownsampling)>) | 启用非透明纹理时，可以设置降采样，可以根据清晰度需求和性能要求来进行设置。 | -| | [msaaSamples](<(/apis/core/#Camera-msaaSamples)>) | 多样本抗锯齿采样样本数量，仅当独立画布开启时才能生效，如 `enableHDR`、`enablePostProcess`、`opaqueTextureEnabled`。 | -| | [enableHDR](<(/apis/core/#Camera-enableHDR)>) | 是否启用 HDR 渲染，允许 shader 输出的颜色使用浮点数进行存储，可以得到更大范围的值，用于后处理等场景。 | -| | [enablePostProcess](<(/apis/core/#Camera-enablePostProcess)>) | 是否启用后处理，后处理配置详见[后处理教程](/docs/graphics/postProcess/postProcess)。| +| 类型 | 属性 | 解释 | +| :-- | :-- | :-- | +| 通用 | [isOrthographic](/apis/core/#Camera-isOrthographic) | 通过设置 [isOrthographic](/apis/core/#Camera-isOrthographic) 来决定透视投影或正交投影。若需要透视效果则设为 `false`，默认为 `false` | +| | [nearClipPlane](/apis/core/#Camera-nearClipPlane) | 近裁剪平面,若渲染物体与相机的距离小于此值则无法正常渲染 | +| | [farClipPlane](/apis/core/#Camera-farClipPlane) | 远裁剪平面，若渲染 物体与相机的距离大于此值则无法正常渲染 | +| | [viewport](/apis/core/#Camera-viewport) | 视口，确定内容最后被渲染到目标设备里的范围，修改此值可以决定最终渲染结果在渲染目标中的位置 | +| | [priority](/apis/core/#Camera-priority) | 渲染优先级，用来确定在多相机的情况下按照什么顺序去渲染相机包含的内容。 | +| | [enableFrustumCulling](/apis/core/#Camera-enableFrustumCulling) | 是否开启视锥剔除，开启后可剔除不在渲染范围内物体的渲染，默认为 `true` | +| | [clearFlags](/apis/core/#Camera-clearFlags) | 在渲染这个相机前清理画布缓冲的标记，通过编标记可以选择性地保留上次相机渲染的结果 | +| | [cullingMask](/apis/core/#Camera-cullingMask) | 裁剪遮罩，用来选择性地渲染场景中的渲染组件。 | +| | [aspectRatio](/apis/core/#Camera-aspectRatio) | 渲染目标的宽高比，一般是根据 canvas 大小自动计算，也可以手动改变（不推荐） | +| | [renderTarget](/apis/core/#Camera-renderTarget) | 渲染目标，确定内容被渲染到哪个目标上。 | +| | [pixelViewport](/apis/core/#Camera-pixelViewport) | 屏幕上相机的视口（以像素坐标表示）。若渲染目标为画布，且视口为整个画布，则左上角为(0, 0)，右下角为(canvas.width, canvas.height)。 | +| 透视投影 | [fieldOfView](/apis/core/#Camera-fieldOfView) | 视角，默认为 45 度（0，180） | +| 正交投影 | [orthographicSize](/apis/core/#Camera-orthographicSize) | 正交模式下相机取景上边框至下边框距离的一半 | +| 渲染相关 | [depthTextureMode](<(/apis/core/#Camera-depthTextureMode)>) | 深度纹理模式，默认为`DepthTextureMode.None`，如果开启，可以在 shader 中使用 `camera_DepthTexture` 深度纹理。详情可参考[相机纹理](/docs/graphics/camera/texture/) | +| | [opaqueTextureEnabled](<(/apis/core/#Camera-opaqueTextureEnabled)>) | 是否启用非透明纹理，默认关闭，如果启用，可以在透明队列的 shader 中使用 `camera_OpaqueTexture` 非透明纹理。 | +| | [opaqueTextureDownsampling](<(/apis/core/#Camera-opaqueTextureDownsampling)>) | 启用非透明纹理时，可以设置降采样，可以根据清晰度需求和性能要求来进行设置。 | +| | [msaaSamples](<(/apis/core/#Camera-msaaSamples)>) | 多样本抗锯齿采样样本数量，仅当独立画布开启时才能生效，如 `enableHDR`、`enablePostProcess`、`opaqueTextureEnabled`。 | +| | [enableHDR](<(/apis/core/#Camera-enableHDR)>) | 是否启用 HDR 渲染，允许 shader 输出的颜色使用浮点数进行存储，可以得到更大范围的值，用于后处理等场景。 | +| | [enablePostProcess](<(/apis/core/#Camera-enablePostProcess)>) | 是否启用后处理，后处理配置详见[后处理教程](/docs/graphics/postProcess/postProcess)。 | ### 裁剪遮罩 @@ -102,27 +102,7 @@ camera.enableHDR = true; ## 方法 -相机组件提供各种方法（主要涉及`渲染`与`空间转换`）方便开发者实现期望的定制能力。 - -| 类型 | 属性 | 解释 | -| :------- | :----------------------------------------------------------------- | :--------------------------------------- | -| 渲染 | [resetProjectionMatrix](/apis/core/#Camera-resetProjectionMatrix) | 重置自定义投影矩阵，恢复到自动模式。 | -| | [resetAspectRatio](/apis/core/#Camera-resetAspectRatio) | 重置自定义渲染横纵比，恢复到自动模式。 | -| | [render](/apis/core/#Camera-render) | 手动渲染。 | -| | [setReplacementShader](/apis/core/#Camera-setReplacementShader) | 设置全局渲染替换着色器。 | -| | [resetReplacementShader](/apis/core/#Camera-resetReplacementShader) | 清空全局渲染替换着色器。 | -| 空间转换 | [worldToViewportPoint](/apis/core/#Camera-worldToViewportPoint) | 将一个点从世界空间转换到视口空间。 | -| | [viewportToWorldPoint](/apis/core/#Camera-viewportToWorldPoint) | 将一个点从视口空间转换到世界空间。 | -| | [viewportPointToRay](/apis/core/#Camera-viewportPointToRay) | 通过视口空间中的一个点生成世界空间射线。 | -| | [screenToViewportPoint](/apis/core/#Camera-screenToViewportPoint) | 将一个点从屏幕空间转换到视口空间。 | -| | [viewportToScreenPoint](/apis/core/#Camera-viewportToScreenPoint) | 将一个点从视口空间转换到屏幕空间。 | -| | [worldToScreenPoint](/apis/core/#Camera-worldToScreenPoint) | 将一个点从世界空间转换到屏幕空间。 | -| | [screenToWorldPoint](/apis/core/#Camera-screenToWorldPoint) | 将一个点从屏幕空间转换到世界空间。 | -| | [screenPointToRay](/apis/core/#Camera-screenPointToRay) | 通过屏幕空间中的一个点生成世界空间射线。 | - -## 获取相机组件 - -在清楚相机组件挂载在哪个节点的前提下，可直接通过 `getComponent` 或 `getComponentsIncludeChildren` 获取： +相机组件提供各种方法（主要涉及`渲染`与`空间转换`）方便开发者实现期望的定制能力，在此之前，要先学会如何获取相机组件，在知道相机组件挂载在哪个节点的前提下，可直接通过 `getComponent` 或 `getComponentsIncludeChildren` 获取： ```typescript // 从挂载相机的节点上获取相机组件 @@ -135,9 +115,35 @@ const cameras = entity.getComponentsIncludeChildren(Camera, []); ```typescript // 获取这个场景中的所有相机组件（不推荐） -const cameras = scene._activeCameras; +const cameras = scene._componentsManager._activeCameras; ``` +| 类型 | 属性 | 解释 | +| :-- | :-- | :-- | +| 渲染 | [resetProjectionMatrix](/apis/core/#Camera-resetProjectionMatrix) | 重置自定义投影矩阵，恢复到自动模式。 | +| | [resetAspectRatio](/apis/core/#Camera-resetAspectRatio) | 重置自定义渲染横纵比，恢复到自动模式。 | +| | [render](/apis/core/#Camera-render) | 手动渲染。 | +| | [setReplacementShader](/apis/core/#Camera-setReplacementShader) | 设置全局渲染替换着色器。 | +| | [resetReplacementShader](/apis/core/#Camera-resetReplacementShader) | 清空全局渲染替换着色器。 | +| 空间转换 | [worldToViewportPoint](/apis/core/#Camera-worldToViewportPoint) | 将一个点从世界空间转换到视口空间。 | +| | [viewportToWorldPoint](/apis/core/#Camera-viewportToWorldPoint) | 将一个点从视口空间转换到世界空间。 | +| | [viewportPointToRay](/apis/core/#Camera-viewportPointToRay) | 通过视口空间中的一个点生成世界空间射线。 | +| | [screenToViewportPoint](/apis/core/#Camera-screenToViewportPoint) | 将一个点从屏幕空间转换到视口空间。 | +| | [viewportToScreenPoint](/apis/core/#Camera-viewportToScreenPoint) | 将一个点从视口空间转换到屏幕空间。 | +| | [worldToScreenPoint](/apis/core/#Camera-worldToScreenPoint) | 将一个点从世界空间转换到屏幕空间。 | +| | [screenToWorldPoint](/apis/core/#Camera-screenToWorldPoint) | 将一个点从屏幕空间转换到世界空间。 | +| | [screenPointToRay](/apis/core/#Camera-screenPointToRay) | 通过屏幕空间中的一个点生成世界空间射线。 | + +### Shader 替换 + +借助 `setReplacementShader` 全局替换 Shader 的能力可以观测特定的渲染效果： + + + +### 空间转换 + +需要注意的是 `screenToWorldPoint` 、 `viewportToWorldPoint` 等方法传入点的 Z 表示返回的点到相机的距离。 + ## onBeginRender 与 onEndRender -相机组件额外包含了 [onBeginRender](/apis/core/#Script-onBeginRender) 与 [onEndRender](/apis/core/#Script-onEndRender) 两个生命周期回调，它们的时序可参考[脚本生命周期时序图](/docs/script) +相机组件额外包含了 [onBeginRender](/apis/core/#Script-onBeginRender) 与 [onEndRender](/apis/core/#Script-onEndRender) 两个生命周期回调，它们的时序可参考[脚本生命周期时序图](/docs/script/class/#脚本生命周期) diff --git a/docs/zh/graphics/camera/control.md b/docs/zh/graphics/camera/control.md index 3725b05f2e..3dccbef265 100644 --- a/docs/zh/graphics/camera/control.md +++ b/docs/zh/graphics/camera/control.md @@ -10,6 +10,8 @@ label: Graphics/Camera 相机控件继承于功能强大的脚本，挂载在包含 `Camera` 组件的 `Entity` 上，因此可以顺其自然地拿到 `Camera` ，在生命周期函数中响应外部输入并执行相应的操作，**此类控件目前无法在编辑器中操作添加，需开发者在脚本中自行添加。** +> 需要注意的是，在添加相机控件前请务必保证节点已经添加 `Camera` 组件 + ## 轨道控制器 `OrbitControl`  用来模拟轨道交互，适用于围绕一个目标对象进行 360 度旋转交互，需要注意的是，**请务必在添加相机组件后再添加轨道控制器**。 diff --git a/docs/zh/graphics/camera/depthTexture.md b/docs/zh/graphics/camera/depthTexture.md deleted file mode 100644 index fbcccefa98..0000000000 --- a/docs/zh/graphics/camera/depthTexture.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -order: 4 -title: 相机深度纹理 -type: 图形 -group: 相机 -label: Graphics/Camera ---- - - -相机可以通过 [depthTextureMode](<(/apis/core/#Camera-depthTextureMode)>) 属性开启深度纹理，开启深度纹理后可以通过 `camera_DepthTexture` 属性在 Shader 中访问深度纹理。深度纹理可以用于实现软粒子和水面边缘过渡，以及一些简单的后处理效果。 - - - -注意：深度纹理仅渲染非透明物体。 diff --git a/docs/zh/graphics/camera/texture.md b/docs/zh/graphics/camera/texture.md new file mode 100644 index 0000000000..6690f8c97e --- /dev/null +++ b/docs/zh/graphics/camera/texture.md @@ -0,0 +1,19 @@ +--- +order: 4 +title: 相机纹理 +type: 图形 +group: 相机 +label: Graphics/Camera +--- + +## 深度纹理 + +相机可以通过 [depthTextureMode](/apis/galacean/#Camera) 属性开启深度纹理，开启深度纹理后可以通过 `camera_DepthTexture` 属性在 Shader 中访问深度纹理。深度纹理可以用于实现软粒子和水面边缘过渡，以及一些简单的后处理效果。 + + + +注意：深度纹理仅渲染非透明物体。 + +## 非透明纹理 + +相机可以通过 [opaqueTextureEnabled](/apis/galacean/#Camera) 属性开启非透明纹理，开启后可以在透明队列的 shader 中使用 `camera_OpaqueTexture`，同时可以设置降采样，根据清晰度需求和性能要求来设置 [opaqueTextureDownsampling](/apis/galacean/#Camera)。 diff --git a/docs/zh/graphics/mesh/mesh.md b/docs/zh/graphics/mesh/mesh.md index 0771a3ccf7..3a97ac0df4 100644 --- a/docs/zh/graphics/mesh/mesh.md +++ b/docs/zh/graphics/mesh/mesh.md @@ -6,15 +6,15 @@ group: 网格 label: Graphics/Mesh --- -网格是[网格渲染器](/docs/graphics-renderer-meshRenderer)的数据对象，它描述了顶点的各种信息（位置，拓扑，顶点色，UV 等）。 +网格是[网格渲染器](/docs/graphics/renderer/meshRenderer/)的数据对象，它描述了顶点的各种信息（位置，拓扑，顶点色，UV 等）。 ## 网格资产 网格资产一般来源于： -- 通过[导入模型](/docs/graphics-model-importGlTF)，获取第三方工具创建的[模型内置网格资产](/docs/graphics-model-assets) -- 编辑器的[内置网格资产](/docs/graphics-mesh-primitiveMesh) -- 开发者自身[创建网格资产](/docs/graphics-mesh-primitiveMesh) +- 通过[导入模型](/docs/graphics/model/importGlTF/)，获取第三方工具创建的[模型内置网格资产](/docs/graphics/model/assets/) +- 编辑器的[内置网格资产](/docs/graphics/mesh/primitiveMesh/) +- 开发者自身[创建网格资产](/docs/graphics/mesh/primitiveMesh/) ## 使用 @@ -26,9 +26,9 @@ label: Graphics/Mesh | 类型 | 描述 | | :----------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | -| [ModelMesh](/docs/graphics-mesh-modelMesh) | 封装了常用的设置顶点数据和索引数据的方法，非常简单易用。开发者若想要快速地去自定义几何体可以使用该类 | -| [BufferMesh](/docs/graphics-mesh-bufferMesh) | 可以自由操作顶点缓冲和索引缓冲数据，以及一些与几何体绘制相关的指令。具备高效、灵活、简洁等特点。开发者如果想高效灵活的实现自定义几何体就可以使用该类 | -| [内置几何体](/docs/graphics-mesh-primitiveMesh) | 本质上是预置的 ModelMesh , 包含常用的长方体，球体，平面，圆柱，圆环，圆柱与胶囊体。 | +| [ModelMesh](/docs/graphics/mesh/modelMesh/) | 封装了常用的设置顶点数据和索引数据的方法，非常简单易用。开发者若想要快速地去自定义几何体可以使用该类 | +| [BufferMesh](/docs/graphics/mesh/bufferMesh/) | 可以自由操作顶点缓冲和索引缓冲数据，以及一些与几何体绘制相关的指令。具备高效、灵活、简洁等特点。开发者如果想高效灵活的实现自定义几何体就可以使用该类 | +| [内置几何体](/docs/graphics/mesh/primitiveMesh/) | 本质上是预置的 ModelMesh , 包含常用的长方体，球体，平面，圆柱，圆环，圆柱与胶囊体。 | ## 使用 @@ -45,4 +45,4 @@ meshRenderer.mesh = new BufferMesh(engine); 自己构造几何体网格数据是一个比较痛苦的过程，因此 Galacean 内置了一些较为实用的几何体。 -- [内置几何体](/docs/graphics-model)：包含常用的长方体，球体，平面，圆柱，圆环，圆柱与胶囊体。 +- [内置几何体](/docs/graphics/mesh/primitiveMesh/)：包含常用的长方体，球体，平面，圆柱，圆环，圆柱与胶囊体。 diff --git a/docs/zh/graphics/renderer/renderer.md b/docs/zh/graphics/renderer/renderer.md index ff753923b0..1e3f537aa8 100644 --- a/docs/zh/graphics/renderer/renderer.md +++ b/docs/zh/graphics/renderer/renderer.md @@ -48,6 +48,10 @@ console.log("bounds", renderer.bounds); console.log("isCulled", renderer.isCulled); ``` +下方展示如何获取多个 `Renderer` 的整体包围盒： + + + ## 方法 `Renderer` 渲染器基类主要提供设置与获取材质相关的方法，需要注意的是，一个渲染器内可能包含多个材质，因此下列方法更像是在**操作材质数组的增删改查**。 diff --git a/docs/zh/graphics/shader/shaderLab/intro.md b/docs/zh/graphics/shader/shaderLab/intro.md index c2d154a64c..1fcbe9d5bf 100644 --- a/docs/zh/graphics/shader/shaderLab/intro.md +++ b/docs/zh/graphics/shader/shaderLab/intro.md @@ -10,7 +10,7 @@ title: ShaderLab ```mermaid flowchart LR - 创建着色器 --> 编辑 shaderlab --> 调试 shaderlab + 创建着色器 --> 编辑shaderlab --> 调试shaderlab ``` 以下是一个简单的 ShaderLab 使用示例，其中包含了两个 Shader。`normal` Shader 定义了一个只实现 MVP 转换的顶点着色器，并且通过 Uniform 变量指定了像素颜色的片元着色器。另外，`lines` Shader 是一个使用 ShaderLab 进行改造的 [shadertoy](https://www.shadertoy.com/view/DtXfDr) 示例。 diff --git a/docs/zh/input/framebuffer-picker.md b/docs/zh/input/framebuffer-picker.md index 916db9e52f..4c964a20d6 100644 --- a/docs/zh/input/framebuffer-picker.md +++ b/docs/zh/input/framebuffer-picker.md @@ -5,7 +5,7 @@ type: 交互 label: Interact --- -在三维应用中时常需要拾取场景中的物体，[射线包围盒](/docs/physics-manager#使用射线检测)是一种常用的方法，在 CPU 中进行拾取，**性能较好，但是精度较差**，因为包围盒比较简单，不能拾取复杂的模型。 +在三维应用中时常需要拾取场景中的物体，[射线包围盒](/docs/physics/manager/#使用射线检测)是一种常用的方法，在 CPU 中进行拾取，**性能较好，但是精度较差**，因为包围盒比较简单，不能拾取复杂的模型。 当拾取频率不高时，可以考虑使用**像素级精度**的 `FramebufferPicker` 组件；当拾取频率过高时，需要开发者评估好性能开销是否适合业务场景，因为该组件底层会进行 CPU-GPU 通信，即调用 `gl.readPixels` 。 diff --git a/docs/zh/input/input.md b/docs/zh/input/input.md new file mode 100644 index 0000000000..f0a9ecb5a6 --- /dev/null +++ b/docs/zh/input/input.md @@ -0,0 +1,37 @@ +--- +order: 0 +title: 交互总览 +type: 交互 +label: Interact +--- + +Galacean 提供了基本的输入系统，基于跨端跨平台的特性，交互系统在 PC 端和移动端都有很好的兼容性。当前的交互系统可以接受以下输入： + +- [触控](/docs/input/pointer/) +- [键盘](/docs/input/keyboard/) +- [滚轮](/docs/input/wheel/) + +## 初始化 + +在初始化引擎时，可以自定义**触控**，**键盘**与**滚轮**的监听源。 + + +image.png + +```typescript +// 将触控事件的监听源设置为 document +const engine = await WebGLEngine.create({ + canvas, + input: { + pointerTarget: document, + }, +}); +``` + +> ⚠️ 不要将触控的监听源设置为 `window` ，因为 `window` 无法接收 `PointerLevel` 事件，会导致触控信息紊乱。 + +> ⚠️ 若将键盘的监听源设置为某个 `HtmlElement`，需要设置它的 `tabIndex` 从而可以 focus ，例如您可以调用一次 `canvas.tabIndex = canvas.tabIndex;` + +## 帧缓冲拾取 + +若引擎的[触控回调](/docs/input/pointer/#触控回调)无法满足需求，可以尝试使用[帧缓冲拾取](/docs/input/framebuffer-picker/) diff --git a/docs/zh/input/pointer.md b/docs/zh/input/pointer.md index f0c0ea60cd..b2ded4840d 100644 --- a/docs/zh/input/pointer.md +++ b/docs/zh/input/pointer.md @@ -5,7 +5,7 @@ type: 交互 label: Interact --- -Galacean 的触控是基于 [PointerEvent](https://www.w3.org/TR/pointerevents3/) 实现的，它抹平了 [MouseEvent](https://developer.mozilla.org/zh-CN/docs/Web/API/MouseEvent) 与 [TouchEvent](https://developer.mozilla.org/zh-CN/docs/Web/API/TouchEvent) 的差异，使得触控在概念和接口上都得到了统一。 +Galacean 的触控是基于 [Pointer](https://www.w3.org/TR/pointerevents3/) 实现的，它抹平了 [Mouse](https://developer.mozilla.org/zh-CN/docs/Web/API/MouseEvent) 与 [Touch](https://developer.mozilla.org/zh-CN/docs/Web/API/TouchEvent) 的差异，使得触控在概念和接口上都得到了统一。 ## Pointer @@ -60,7 +60,7 @@ timeline ### 触控回调 -只需要为添加了 Collider 组件的 Entity 增加触控回调，就可以实现与渲染物体交互的能力。触控回调已经整合到引擎的[脚本组件生命周期](/docs/script#组件生命周期函数)中，用户可以很方便地添加以下事件，同时钩子函数中会携带触发此回调的 Pointer 实例。 +只需要为添加了 Collider 组件的 Entity 增加触控回调，就可以实现与渲染物体交互的能力。触控回调已经整合到引擎的[脚本生命周期](/docs/script/class/#脚本生命周期)中，用户可以很方便地添加以下事件，同时钩子函数中会携带触发此回调的 Pointer 实例。 | 接口 | 触发时机与频率 | | :------------------------------------------------- | :------------------------------------------------------------------------- | @@ -90,7 +90,7 @@ flowchart LR 添加碰撞体组件 --> 获取触控点 --> 通过画布坐标获取射线 --> 射线检测 ``` -添加碰撞体组件可参考[物理相关文档](/docs/physics-collider)，实现检测部分的代码逻辑如下： +添加碰撞体组件可参考[碰撞体组件](/docs/physics/collider/)，实现检测部分的代码逻辑如下： ```typescript // 假设当前有一个活动的触控点 diff --git a/docs/zh/miniProgram/miniProgame.md b/docs/zh/miniProgram/miniProgame.md new file mode 100644 index 0000000000..8141244547 --- /dev/null +++ b/docs/zh/miniProgram/miniProgame.md @@ -0,0 +1,240 @@ +--- +order: 0 +title: 小程序项目 +type: 小程序 +label: MiniProgram +--- + +目前 Galacean 已经适配到支付宝和淘宝小程序。本教程默认开发者已经具备一定的小程序开发能力，如果没有，请阅读下面教程，下载小程序开发工具及申请 AppId： + +- [支付宝小程序](https://opendocs.alipay.com/mini/developer) +- [淘宝小程序](https://miniapp.open.taobao.com/docV3.htm?docId=119114&docType=1&tag=dev) + +小程序项目发布: + +- [支付宝小程序发布](https://opendocs.alipay.com/mini/introduce/release) +- [淘宝小程序发布](https://developer.alibaba.com/docs/doc.htm?spm=a219a.7629140.0.0.258775fexQgSFj&treeId=635&articleId=117321&docType=1) + +## 项目导出 + +Galacean 编辑器导出支付宝小程序的功能仍在开发中，交互方式和模板工程后续可能会有改动。 + +image-20231008163057689 + +## 项目启动 + +点击下载后会下载一个 zip 文件，解压文件目录结构如下： + +```shell +. +├── mini # 📁 小程序执行目录 +│ ├── dist # 📁 代码构建结果 +│ ├── pages # 📁 小程序页面 +│ ├── app.json # ⚙️ 项目配置文件 +│ ├── app.js # 代码入口 +├── public # 📁 公共资源目录 +│ ├── scene.json # 场景文件 +│ └── ... # 其他 +├── src # 📁 源代码目录 +├── mini.project.json # ⚙️ 工程配置文件 +├── project.json # ⚙️ 编辑器导出工程配置 +└── ... # 其他 +``` + +接下来就可以安装依赖和启动项目： + +```shell +npm install +npm run dev +``` + +用小程序 IDE 打开可以看到： + +![image-20230420111035524](https://mdn.alipayobjects.com/rms/afts/img/A*kEUkTbfSMIwAAAAAAAAAAAAAARQnAQ/original/image-20230420111035524.png) + +## 本地资源处理 + +### 蚂蚁集团内部用户 + +直接使用『上传到 CDN 』即可（在导出面板选项中，参考上图），使用集团默认 CDN 即可。若想使用自定义 CDN，参考非蚂蚁集团内部用户。 + +### 非蚂蚁集团内部用户 + +1. public 文件请自行上传 CDN +2. 修改 scene.json 文件或配置 baseUrl + +## 包内文件加载（WIP） + +目前还没有支持小程序的本地文件加载。 + +## 已知问题 + +- 小程序不支持 WebAssembly，目前无法使用 PhysX 作为物理后端 +- 目前不支持本地文件加载，需要手动上传到 CDN + +## 补充说明 + +### 小程序项目使用 OrbitControl + +1. 引入二方库 + +```bash +npm install @galacean/engine-toolkit-controls -S +``` + +```typescript +import { OrbitControl } from "@galacean/engine-toolkit-controls/dist/miniprogram"; +``` + +2. 添加组件 + +`OrbitControl` 组件需要添加到相机节点上。 + +```typescript +cameraEntity.addComponent(OrbitControl); +``` + +3. 事件模拟派发 + +因为小程序不支持 `addEventListener` 添加监听事件，得手动添加事件的模拟，并且小程序的 canvas 的多指触控存在 bug，所以添加一个和 canvas 大小和位置一样的 view 层去派发触摸事件： + +```html + + + + + +``` + +```typescript +import { dispatchPointerUp, dispatchPointerDown, dispatchPointerMove, dispatchPointerLeave, dispatchPointerCancel } from "@galacean/engine-miniprogram-adapter"; + +Page({ + ... + onTouchEnd(e) { + dispatchPointerUp(e); + dispatchPointerLeave(e); + }, + onTouchStart(e) { + dispatchPointerDown(e); + }, + onTouchMove(e) { + dispatchPointerMove(e); + }, + onTouchCancel(e) { + dispatchPointerCancel(e); + } +}) +``` + +### Pro code 创建 Galacean 小程序项目 + +> 需要 Node.js 版本 >=12.0.0. + +使用 yarn 创建 + +```bash +yarn create @galacean/galacean-app --template miniprogram +``` + +使用 npm **6.x** 版本创建 + +``` +npm init @galacean/galacean-app --template miniprogram +``` + +使用 npm **7.x** 版本创建 + +```she +npm init @galacean/galacean-app -- --template miniprogram +``` + +**根据提示**完成后续步骤后，可以使用小程序开发工具打开项目： + +![image-20210609164550721](https://gw.alipayobjects.com/zos/OasisHub/3e2df40f-6ccd-4442-85f8-69233d04b3b5/image-20210609164550721.png) + +选择对应目录即可，顺利的话可以看到： + +![image-20210609164816776](https://gw.alipayobjects.com/zos/OasisHub/04386e9c-b882-41f7-8aa6-a1bf990d578b/image-20210609164816776.png) + +### 已有项目 Pro code 使用 Galacean + +本教程假设你已经有一定开发能力，若不熟悉小程序开发，请详细阅读[小程序开发文档](https://opendocs.alipay.com/mini/developer)。 + +1. 在项目目录中打开 `Terminal`，安装依赖： + +```bash +# 使用 npm +npm install @galacean/engine --save +npm install @galacean/engine-miniprogram-adapter --save +# 使用 yarn +yarn add @galacean/engine +yarn add @galacean/engine-miniprogram-adapter +``` + +2. 在小程序项目配置文件 `app.json` 里添加下面配置项： + +```json +{ + ... + "window": { + ... + "v8WorkerPlugins": "gcanvas_runtime", + "v8Worker": 1, + "enableSkia": "true" + } +} +``` + +3. 在需要添加互动的 axml 页面里加入 canvas 标签 + +```html + +``` + +使用 `onReady` 配置 `canvas` 初始化回调。需要设置 `canvas` 的 id，后面会用到。 + +4. 在页面的 `.js` 代码文件里添加回调函数，使用 `my._createCanvas` 创建所需的 canvas 上下文，之后在 `success` 回调里使用 galacean 即可. + +注意： + +1. 使用 `import * as GALACEAN from "@galacean/engine/dist/miniprogram"` 引入小程序依赖。 +2. 需要使用『@galacean/engine-miniprogram-adapter』里的 `registerCanvas` 注册 `canvas`。 + +详情可以参考下面代码： + +```js +import * as GALACEAN from "@galacean/engine/dist/miniprogram"; +import { registerCanvas } from "@galacean/engine-miniprogram-adapter"; + +Page({ + onCanvasReady() { + my._createCanvas({ + id: "canvas", + success: (canvas) => { + // 注册 canvas + registerCanvas(canvas); + // 适配 canvas 大小 + const info = my.getSystemInfoSync(); + const { windowWidth, windowHeight, pixelRatio, titleBarHeight } = info; + canvas.width = windowWidth * pixelRatio; + canvas.height = (windowHeight - titleBarHeight) * pixelRatio; + + // 创建引擎 + const engine = new GALACEAN.WebGLEngine(canvas); + // 剩余代码和 Galacean Web 版本一致 + ... + }, + }); + } +}) +``` diff --git a/docs/zh/quick-start/_meta.json b/docs/zh/quick-start/_meta.json new file mode 100644 index 0000000000..ba4f5553ca --- /dev/null +++ b/docs/zh/quick-start/_meta.json @@ -0,0 +1,8 @@ +{ + "overview": { + "title": "概述" + }, + "quickStart":{ + "title": "快速上手" + } +} diff --git a/docs/zh/quick-start/overview.md b/docs/zh/quick-start/overview.md index 52f69e66c9..abf0285ea9 100644 --- a/docs/zh/quick-start/overview.md +++ b/docs/zh/quick-start/overview.md @@ -5,14 +5,14 @@ type: 基础知识 label: Basics --- -**Galacean Engine** 是一套 Web 为先、移动优先、开源共建的实时互动解决方案，采用组件化架构与 [Typescript](https://www.typescriptlang.org/) 编写。它包含了[渲染](/docs/graphics-renderer)、[物理](/docs/physics-overall)、[动画](/docs/animation-system)和[交互](/docs/input)功能，并提供了具备完善工作流的可视化在线编辑器，帮助你在浏览器上创作绚丽的 2D/3D 互动应用。它主要由两部分组成： +**Galacean Engine** 是一套 Web 为先、移动优先、开源共建的实时互动解决方案，采用组件化架构并用 [Typescript](https://www.typescriptlang.org/) 编写。它包含[渲染](/docs/graphics/renderer/renderer)、[物理](/docs/physics/overall)、[动画](/docs/animation/overview)、[交互](/docs/input/input)、[XR](/docs/xr/overall)等功能，并提供了具备完善工作流的可视化在线编辑器，帮助你在浏览器上创作绚丽的 2D/3D 互动应用。它主要由两部分组成： - 编辑器：一个在线 Web 互动创作平台 [Editor](https://galacean.antgroup.com/editor) -- 运行时：一个 Web 为先、移动优先的高性能的互动运行时 [Runtime](https://github.com/galacean/runtime)，一系列非核心功能和偏业务逻辑定制功能 [Toolkit](https://github.com/galacean/runtime-toolkit) +- 运行时：一个 Web 为先、移动优先的高性能的互动运行时 [Runtime](https://github.com/galacean/runtime)，丰富的非核心功能和偏业务逻辑定制功能 [Toolkit](https://github.com/galacean/runtime-toolkit), 以及一系列二方生态包。 ## 编辑器 -[Galacean Editor](https://antg.antgroup.com/editor) 是一个在线 Web 互动创作平台。它可以帮助你快速的创建、编辑和导出一个互动项目。你可以通过 Galacean Editor 快速上传互动资产，创建和编辑材质、调整灯光、创建实体，从而创造出复杂的场景。 +[Galacean Editor](https://antg.antgroup.com/editor) 是一个在线 Web 互动创作平台。它可以帮助你快速地创建、编辑和导出一个互动项目。你可以通过 Galacean Editor 快速上传资产，编辑材质、调整灯光、创建实体，从而创造出复杂的场景。 使用编辑器创建互动项目的整体流程： @@ -21,7 +21,7 @@ flowchart LR 创建项目 --> 创建资产 --> 搭建场景 --> 编写脚本 --> 导出 ``` -通过编辑器可以让技术与美术同学更好地进行协作，你可以在[编辑器首页](https://galacean.antgroup.com/editor)通过项目模板快速开始第一个项目的开发。 +通过编辑器可以让技术与美术同学更好地进行协作，你可以在[编辑器首页](https://galacean.antgroup.com/editor)通过业务模板快速开始第一个项目的开发。 ## 运行时 @@ -31,12 +31,14 @@ flowchart LR 包括以下子包： -| 功能 | 解释 | API | -| :--------------------------------------------------------------------------------------------- | :--------------------- | -------------------------- | -| [@galacean/engine](https://www.npmjs.com/package/@galacean/engine) | 核心架构逻辑和核心功能 | [API](${api}core) | -| [@galacean/engine-physics-lite](https://www.npmjs.com/package/@galacean/engine-physics-lite) | 轻量级物理引擎 | [API](${api}physics-lite) | -| [@galacean/engine-physics-physx](https://www.npmjs.com/package/@galacean/engine-physics-physx) | 全功能物理引擎 | [API](${api}physics-physx) | -| [@galacean/engine-draco](https://www.npmjs.com/package/@galacean/engine-draco) | Draco 模型压缩 | [API](${api}draco) | +| 包 | 解释 | 相关文档 | +| :-- | :-- | --- | +| [@galacean/engine](https://www.npmjs.com/package/@galacean/engine) | 核心架构逻辑和核心功能 | [API](/apis/galacean) | +| [@galacean/engine-physics-lite](https://www.npmjs.com/package/@galacean/engine-physics-lite) | 轻量级物理引擎 | [Doc](/docs/physics/overall) | +| [@galacean/engine-physics-physx](https://www.npmjs.com/package/@galacean/engine-physics-physx) | 全功能物理引擎 | [Doc](/docs/physics/overall) | +| [@galacean/engine-shader-lab](https://www.npmjs.com/package/@galacean/engine-shader-lab) | Galacean Shader 编译器 | [Doc](/docs/graphics/shader/lab) | +| [@galacean/engine-xr](https://www.npmjs.com/package/@galacean/engine-xr) | XR 逻辑包 | [Doc](/docs/xr/overall) | +| [@galacean/engine-xr-webxr](https://www.npmjs.com/package/@galacean/engine-xr-webxr) | WebXR 后端 | [Doc](/docs/xr/overall) | 你可以通过 [NPM](https://docs.npmjs.com/) 的方式进行安装： @@ -50,62 +52,42 @@ npm install --save @galacean/engine import { WebGLEngine, Camera } from "@galacean/engine"; ``` -如果你只是想在本地快速完成一个 Demo， 推荐你使用 [create-galacean-app](https://github.com/galacean/create-galacean-app)， 它提供了一些常用的框架如 [React](https://reactjs.org/)、[Vue](https://vuejs.org/) 等模板。 - ### 工具包 非核心功能和偏业务逻辑定制功能由 galacean-toolkit 包提供（完成功能列表请查看[engine-toolkit](https://github.com/galacean/engine-toolkit/tree/main)）： -| 功能 | 解释 | API | -| :----------------------------------------------------------------------------------------------------------------------- | :----------- | :------------------------------------- | -| [@galacean/engine-toolkit-controls](https://www.npmjs.com/package/@galacean/engine-toolkit-controls) | 控制器 | [Doc](/docs/graphics-camera-control) | -| [@galacean/engine-toolkit-framebuffer-picker](https://www.npmjs.com/package/@galacean/engine-toolkit-framebuffer-picker) | 帧缓冲拾取 | [Doc](/docs/input-framebuffer-picker) | -| [@galacean/engine-toolkit-stats](https://www.npmjs.com/package/@galacean/engine-toolkit-stats) | 引擎统计面板 | [Doc](/docs/performance-stats) | -| ...... | | | - -你可以通过 [NPM](https://docs.npmjs.com/) 的方式进行安装： +| 包 | 解释 | API | +| :-- | :-- | :-- | +| [@galacean/engine-toolkit-controls](https://www.npmjs.com/package/@galacean/engine-toolkit-controls) | 控制器 | [Doc](/docs/graphics/camera/control/) | +| [@galacean/engine-toolkit-framebuffer-picker](https://www.npmjs.com/package/@galacean/engine-toolkit-framebuffer-picker) | 帧缓冲拾取 | [Doc](/docs/input/framebuffer-picker/) | +| [@galacean/engine-toolkit-stats](https://www.npmjs.com/package/@galacean/engine-toolkit-stats) | 引擎统计面板 | [Doc](/docs/performance/stats/) | +| ...... | | | -```bash -npm install --save @galacean/engine-toolkit-controls -``` +> 在同一项目中，请保证引擎核心包的版本一致和工具包的大版本保持一致，以 1.3.x 版本的引擎为例，需要配套使用 1.3.y 版本的工具包。 -然后在业务中引入使用： - -```typescript -import { OrbitControl } from " @galacean/engine-toolkit-controls"; -``` - -> 在同一项目中，请保证引擎核心包的版本一致和工具包的大版本保持一致，以 1.0.x 版本的引擎为例，需要配套使用 1.0.y 版本的工具包。 +### 二方生态包 另外还有一些二方生态包，引入和使用方式和引擎工具包相同： -| 功能 | 解释 | API | -| :------------------------------------------------------------------------------- | :---------- | :------------------------------ | -| [@galacean/engine-spine](https://www.npmjs.com/package/@galacean/engine-spine) | Spine 动画 | [Doc](/docs/graphics-2d-spine) | -| [@galacean/engine-lottie](https://www.npmjs.com/package/@galacean/engine-lottie) | Lottie 动画 | [Doc](/docs/graphics-lottie) | +| 包 | 解释 | API | +| :-- | :-- | :-- | +| [@galacean/engine-spine](https://www.npmjs.com/package/@galacean/engine-spine) | Spine 动画 | [Doc](/docs/graphics/2D/spine/) | +| [@galacean/engine-lottie](https://www.npmjs.com/package/@galacean/engine-lottie) | Lottie 动画 | [Doc](/docs/graphics/2D/lottie/) | -### 兼容性 +> 二方生态包的版本依赖关系，请参照对应文档说明。 -可以在支持 WebGL 的环境下运行，到目前为止，所有主流的移动端浏览器与桌面浏览器都支持这一标准。可以在 [CanIUse](https://caniuse.com/?search=webgl) 上检测运行环境的兼容性。 - -此外，**Galacean Runtime** 还支持在[支付宝/淘宝小程序](/docs/assets-build)中运行，同时也有开发者在社区贡献了[微信小程序/游戏的适配方案](https://github.com/deepkolos/platformize)。对于一些需要额外考虑兼容性的功能模块，当前的适配方案如下： +> [点击深入了解 Galacean 的版本管理](/docs/quick-start/version/) -| 模块 | 兼容考虑 | 具体文档 | -| :------------------------------ | :------------------------------------------------------- | :-------------------------------------------------------------------------------------- | -| [鼠标与触控](/docs/input) | [PointerEvent](https://caniuse.com/?search=PointerEvent) | 兼容请参照 [polyfill-pointer-event](https://github.com/galacean/polyfill-pointer-event) | -| [PhysX](/docs/physics-overall) | [WebAssembly](https://caniuse.com/?search=wasm) | 运行环境需支持 WebAssembly | +## 兼容性 -### 版本管理 +Galacean Runtime 在支持 WebGL 的环境下运行，到目前为止，所有主流的移动端浏览器与桌面浏览器都支持这一标准。可以在 [CanIUse](https://caniuse.com/?search=webgl) 上检测运行环境的兼容性。 -以 `@galacean/engine` 为例，你可以在 [Github](https://github.com/galacean/engine/releases) 或 [NPM](https://www.npmjs.com/package/@galacean/engine?activeTab=versions) 上查看所有可用版本，其中： - -- **alpha**：内部测试版，用于早期功能研发，有里程碑内的新功能但稳定性较差，例如 [1.0.0-alpha.6](https://www.npmjs.com/package/@galacean/engine/v/1.0.0-alpha.6) -- **beta**: 公开测试版，内部测试已基本完毕，稳定性较强，但可能仍有较少的问题与缺陷，例如 [1.0.0-beta.8](https://www.npmjs.com/package/@galacean/engine/v/1.0.0-beta.8) -- **stable**：正式稳定版，经过长期测试和验证，无重大缺陷，可投入生产的推荐版本，例如 [0.9.8](https://www.npmjs.com/package/@galacean/engine/v/0.9.8) - -每个里程碑版本更新迭代时会同步发布[版本升级引导](https://github.com/galacean/engine/wiki/Migration-Guide)，其中包含了本次更新的内容以及 BreakChange，可依据此文档进行版本的更新迭代。 +此外，**Galacean Runtime** 还支持在[支付宝/淘宝小程序](/docs/assets-build)中运行，同时也有开发者在社区贡献了[微信小程序/游戏的适配方案](https://github.com/deepkolos/platformize)。对于一些需要额外考虑兼容性的功能模块，当前的适配方案如下： -如果您的项目正在使用旧版本的 Oasis 进行开发，并且希望升级为 Galacean，可以参考 [@crazylxr](https://github.com/crazylxr) 提供的 [galacean-codemod](https://github.com/crazylxr/galacean-codemod) 工具。 +| 模块 | 兼容考虑 | 具体文档 | +| :-- | :-- | :-- | +| [鼠标与触控](/docs/input) | [PointerEvent](https://caniuse.com/?search=PointerEvent) | 兼容请参照 [polyfill-pointer-event](https://github.com/galacean/polyfill-pointer-event) | +| [PhysX](/docs/physics-overall) | [WebAssembly](https://caniuse.com/?search=wasm) | 在不支持 WebAssembly 的情况下，会降级为 JS 版本，略低于 WebAssembly 版本的性能与表现 | ## 开源共建 diff --git a/docs/zh/quick-start/core-concept.md b/docs/zh/quick-start/quickStart/core-concept.md similarity index 100% rename from docs/zh/quick-start/core-concept.md rename to docs/zh/quick-start/quickStart/core-concept.md diff --git a/docs/zh/quick-start/flappy-bird.md b/docs/zh/quick-start/quickStart/flappy-bird.md similarity index 100% rename from docs/zh/quick-start/flappy-bird.md rename to docs/zh/quick-start/quickStart/flappy-bird.md diff --git a/docs/zh/quick-start/version.md b/docs/zh/quick-start/version.md new file mode 100644 index 0000000000..030fced169 --- /dev/null +++ b/docs/zh/quick-start/version.md @@ -0,0 +1,72 @@ +--- +order: 0 +title: 版本管理 +type: 基础知识 +label: Basics +--- + +Galacean 有一套成熟的版本管理方案，本文将以 `@galacean/engine` 为例，介绍 Galacean 的管理工具，命名规则，发布策略及依赖管理。 + +## 版本管理工具 + +Galacean 使用的版本管理工具是 [Git](https://git-scm.com/) ，代码都托管在 [GitHub](https://github.com/galacean/) 上，并且所有的开发流程，包括[规划](https://github.com/galacean/engine/projects?query=is%3Aopen)，[里程碑](https://github.com/galacean/engine/milestones)，[架构设计](https://github.com/galacean/engine/wiki/Physical-system-design)在内的信息，全部都公开在 GitHub 的项目管理中，你可以通过[创建 issue](https://docs.github.com/zh/issues/tracking-your-work-with-issues/creating-an-issue) 与[提交 PR](https://docs.github.com/zh/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) 参与到引擎的建设当中。 + +## 包管理工具 + +Galacean 使用的包管理工具是 [NPM](https://www.npmjs.com/) ，您可以通过 npm 指令安装 [@galacean/engine](https://www.npmjs.com/package/@galacean/engine?activeTab=versions)： + +```bash +npm install --save @galacean/engine +``` + +然后在业务中引入使用： + +```typescript +import { WebGLEngine, Camera } from "@galacean/engine"; +``` + +## 版本命名规则与发布策略 + +Galacean 版本号格式是 `MAJOR.MINOR.PATCH-TAG.X` 。其中 `MAJOR.MINOR` 代表里程碑版本，通常伴随大量功能更新， `PATCH` 版本更新则表示向下兼容的错误修复，`TAG` 标签标记了该发布版本的用处。 + +| TAG | 释义 | +| :-- | :-- | +| **alpha** | 内部测试版，用于早期功能研发，有里程碑内的新功能但稳定性较差，例如 [1.3.0-alpha.3](https://www.npmjs.com/package/@galacean/engine/v/1.3.0-alpha.3) | +| **beta** | 公开测试版，内部测试已基本完毕，稳定性较强，但可能仍有较少的问题与缺陷，例如 [1.2.0-beta.7](https://www.npmjs.com/package/@galacean/engine/v/1.2.0-beta.7) | +| **latest** | 正式稳定版，经过长期测试和验证，无重大缺陷，可投入生产的推荐版本，例如 [1.1.3](https://www.npmjs.com/package/@galacean/engine/v/1.1.3) | +| **custom** | 内部为了测试特定功能而发布的，例如 [0.0.0-experimental-1.3-xr.9](https://www.npmjs.com/package/@galacean/engine/v/0.0.0-experimental-1.3-xr.9) | + +> 在 [Github](https://github.com/galacean/engine/releases) 或 [NPM](https://www.npmjs.com/package/@galacean/engine?activeTab=versions) 上可以查看所有可用版本。 + +## 版本升级 + +每个里程碑版本更新迭代时会同步发布[版本升级引导](https://github.com/galacean/engine/wiki/Migration-Guide)，其中包含了本次更新的内容以及 BreakChange，可依据此文档进行版本的更新迭代。 + +## 版本依赖 + +| 情况 | 规则 | +| :-- | :-- | +| **核心包** | 核心包之间请保证版本一致 | +| **工具包** 依赖 **核心包** | 保证工具包版本与引擎核心包的大版本一致，以 1.3.x 版本的工具包为例，依赖 1.3.y 版本的核心包 | +| **二方包** 依赖 **核心包** | 二方生态包对引擎版本的依赖关系，请参照对应文档说明，如 [Lottie](/docs/graphics/2D/lottie/#lottie-使用版本说明) | + +> 基本规则如上，若有特殊说明，请按照说明选择依赖。 + +## 其他 + +### 编辑器升级引擎版本 + +在 [项目设置](/docs/interface/menu/#项目设置) 中可以控制运行时的引擎版本。 + +### 运行时输出的版本信息 + +Galacean 大部分包运行时会在 `Console` 输出版本信息， + +image.png + +通常也会以此为依据判断包版本依赖是否出现： + +- 版本依赖不符合规则？ +- 出现了多个不同版本的同名依赖？ + +若出现以上问题，请排查工程并解决依赖问题。 diff --git a/docs/zh/script/script.md b/docs/zh/script/script.md new file mode 100644 index 0000000000..e36feb146c --- /dev/null +++ b/docs/zh/script/script.md @@ -0,0 +1,17 @@ +--- +order: 0 +title: 脚本总览 +type: 脚本 +label: Script +--- + +除了[内置组件](/docs/core/component/)之外，Galacean 引擎还提供了强大的脚本系统。脚本系统是衔接引擎能力和游戏逻辑的纽带，它扩展自 [Script](/apis/galacean/#Script)  基类，你可以通过自定义脚本扩展引擎的功能，也可以在脚本组件提供的生命周期钩子函数中编写自己的游戏逻辑代码。 + +在本章节，您可以了解到： + +- [脚本类](/docs/script/class/)：脚本回调的生命周期及如何用脚本控制实体 +- 脚本工作流 + - [创建脚本](/docs/script/create/)：声明与绑定脚本 + - [编辑脚本](/docs/script/edit/)：脚本编辑界面，引入三方包，预览及事件调试 + - [脚本参数](/docs/script/attributes/) + - [事件通信](/docs/script/communication/) \ No newline at end of file diff --git a/docs/zh/xr/_meta.json b/docs/zh/xr/_meta.json new file mode 100644 index 0000000000..05b37d87e9 --- /dev/null +++ b/docs/zh/xr/_meta.json @@ -0,0 +1,14 @@ +{ + "overall": { + "title": "XR 总览" + }, + "system": { + "title": "核心设计" + }, + "quickStart": { + "title": "快速上手" + }, + "compatibility": { + "title": "兼容性" + } +} diff --git a/docs/zh/xr/input.md b/docs/zh/xr/input.md deleted file mode 100644 index a27591dcf9..0000000000 --- a/docs/zh/xr/input.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -order: 5 -title: 交互管理器 -type: XR -label: XR ---- - -交互管理器从属于 XRManager 实例，你可以通过 `xrManager.inputManager` 获取，他管理所有的输入设备，包括但不限于： - -- 手柄 -- 头显 -- 手 -- …… - -## 方法 - -| 方法 | 解释 | -| :--------------------------------- | :--------------------- | -| getTrackedDevice | 通过类型获取某个设备 | -| addTrackedDeviceChangedListener | 添加监听设备变化的函数 | -| removeTrackedDeviceChangedListener | 移除监听设备变化的函数 | - -## 使用 - -通过如下代码可以监听设备的更新信息： - -```typescript -const { inputManager } = xrManager.inputManager; -inputManager.addTrackedDeviceChangedListener( - (added: readonly XRInput[], removed: readonly XRInput[]) => { - // 此处添加对新增设备和移除设备的处理 - } -); -``` - -通过如下代码可以获取左手手柄的姿态： - -```typescript -const controller = inputManager.getTrackedDevice( - XRTrackedInputDevice.LeftController -); -// 手柄的姿态 -controller.gripPose.position; -controller.gripPose.rotation; -controller.gripPose.matrix; -// 是否按下 select 键 -controller.isButtonDown(XRInputButton.Select); -// 是否抬起 select 键 -controller.isButtonUp(XRInputButton.Select); -// 是否一直按着 select 键 -controller.isButtonHeldDown(XRInputButton.Select); -``` - -> `XRInputButton.Select` 对应 WebXR 原生 `XRInputSourceEventType.selectXXX` 事件 -> `XRInputButton.Squeeze` 对应 WebXR 原生 `XRInputSourceEventType.squeezeXXX` 事件 - - diff --git a/docs/zh/xr/manager.md b/docs/zh/xr/manager.md deleted file mode 100644 index a1d9c5a0ce..0000000000 --- a/docs/zh/xr/manager.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -order: 2 -title: XR 管理器 -type: XR -label: XR ---- - -XR 管理器从属于 Engine 实例，你可以通过 `engine.xrManager` 获取。它在 XR 中扮演着总控制器的角色，主要管理： - -- 串联 XR 的整体流程 -- [XR 相机](/docs/xr-camera) -- [XR 会话](/docs/xr-session) -- [XR 交互](/docs/xr-input) -- [XR 功能](/docs/xr-features) - -## 属性 - -| 属性 | 类型 | 解释 | -| :----- | :-------------------------- | :------------------------------------------ | -| origin | [Entity](/apis/core/#Entity) | XR 初始化时的原点，它连接虚拟世界与现实世界 | - -> 若你在编辑器中，将 origin 节点放置在 `（1，1，1）` 这个位置，那么可以理解为，当 XR 空间展开时，你在现实世界里坐标的参考原点是 `（1，1，1）` ，他们建立连接的方式是彼此之间有固定的转换公式。 - -## 方法 - -| 方法 | 解释 | -| :----------------- | :--------------- | -| isSupportedFeature | 是否支持某个功能 | -| addFeature | 添加特定 XR 功能 | -| getFeature | 获取特定 XR 功能 | -| getFeatures | 获取所有 XR 功能 | -| enterXR | 进入 XR 会话 | -| exitXR | 退出 XR 会话 | - -## 整体流程 - -依据上方的属性与方法，梳理一下 XR 的整体流程： - -```mermaid -flowchart TD - A[初始化 XR 后端] --> B[设置 XR Origin] - B --> C[连接 XR 相机] - C --> D[添加 XR 能力] - D --> E[进入 XR 会话] - E --> F[退出 XR 会话] -``` \ No newline at end of file diff --git a/docs/zh/xr/overall.md b/docs/zh/xr/overall.md index 0115c47dc8..f4bc3c77a8 100644 --- a/docs/zh/xr/overall.md +++ b/docs/zh/xr/overall.md @@ -7,16 +7,32 @@ label: XR `XR` 是一个通用术语，用于描述扩展现实 `Extended Reality`的概念，它包含虚拟现实（Virtual Reality，VR）、增强现实（Augmented Reality，AR）、混合现实（Mixed Reality，MR）等。 +## 架构 + Galacean 对 XR 做了干净灵活的设计： -- 更加干净：不需 XR 能力时，包体不含任何 XR 逻辑，大小也不会增加分毫 -- 更加灵活：可插拔的功能，让开发更简单 +- 干净：不需 XR 能力时，包体不含任何 XR 逻辑，大小也不会增加分毫 +- 灵活：可插拔的功能，让开发更简单 - 面向未来：多后端设计，后续可适配不同平台不同接口 -image.png +image.png + +## 模块管理 + +| 包 | 解释 | 相关文档 | +| :-- | :-- | --- | +| [@galacean/engine-xr](https://www.npmjs.com/package/@galacean/engine-xr) | 核心架构逻辑 | [API](/apis/galacean) | +| [@galacean/engine-web-xr](https://www.npmjs.com/package/@galacean/engine-web-xr) | 后端包 | [Doc](/docs/physics/overall) | +| [@galacean/engine-toolkit-xr](https://www.npmjs.com/package/@galacean/engine-toolkit-xr) | 高级工具组件 | [Doc](/docs/xr/toolkit) | + +> `@galacean/engine-xr` 和 `@galacean/engine-web-xr`是实现 **WebXR** 必须引入的依赖，相较于上述两个包，`@galacean/engine-toolkit-xr` 则不是必须的，但它的存在可以让编辑器开发 XR 变得更加简单。 + +> XR 包之间的依赖规则遵守[版本依赖规则](/docs/quick-start/version/#版本依赖)，即 `@galacean/engine-xr` 和 `@galacean/engine-web-xr` 的版本需与 `@galacean/engine` 保持一致，`@galacean/engine-toolkit-xr` 的大版本需要与 `@galacean/engine` 保持一致。 + +## 快速上手 -在本章节，你可以了解到： +在本章节，您可以： -- [快速开发 XR 互动](/docs/xr-start)：XR 工作流与调试 -- [XR 管理器](/docs/xr-manager)：管理[相机](/docs/xr-camera)，[会话](/docs/xr-session)，[交互](/docs/xr-input)，[功能](/docs/xr-features)等 -- [XR 兼容性](/docs/xr-compatibility)：介绍当前 WebXR 的兼容性 +- 无需任何专业知识，即可快速[开发 XR 互动](/docs/xr/quickStart/develop)与[调试 XR 互动](/docs/xr/quickStart/debug) +- 若希望深度了解 Galacean XR ，可参考 [XR 核心逻辑](/docs/xr/system/manager) +- 最后，通过了解[XR 兼容性](/docs/xr/compatibility)可以整体把控项目风险 diff --git a/docs/zh/xr/quickStart/debug.md b/docs/zh/xr/quickStart/debug.md new file mode 100644 index 0000000000..a508722318 --- /dev/null +++ b/docs/zh/xr/quickStart/debug.md @@ -0,0 +1,57 @@ +--- +order: 1 +title: 调试 XR 互动 +type: XR +label: XR +--- + +本文将主要介绍如何在 PC 上调试，以及如何在 XR 设备预览并调试。 + +> 若无特殊说明，以下调试项目全部基于 WebXR 开发 + +## PC 调试 + +首先准备调试环境， PC 上使用支持 WebXR 的 Chrome 浏览器，并且安装 [Immersive Web Emulator](https://chromewebstore.google.com/detail/immersive-web-emulator/cgffilbpcibhmcfbgggfhfolhkfbhmik) 插件。 + +> 插件的使用方法可参考 [Immersive Web Emulator 仓库](https://github.com/meta-quest/immersive-web-emulator) + +准备完毕后，就可以在编辑器上预览 XR 项目了： + +image.png + +当然，将项目下载到本地脚本构建也可以预览： + +```bash +npm install +npm run https +``` + +image.png + +> WebXR 仅在安全环境（HTTPS）中可用，因此，构建项目调试时需启用 Https。 + +## 手机端调试 + +支持手机端调试需满足： + +- 手机支持 ARCore ，可参照[支持 ARCore 的设备](https://developers.google.com/ar/devices) +- 安装支持 WebXR 的浏览器（移动端 Chrome 应用） +- 额外安装 [Google Play Services for AR](https://play.google.com/store/apps/details?id=com.google.ar.core&hl=en_US&pli=1) + +> `Google Play Services for AR` 是由谷歌开发的增强现实平台（ARCore），有些手机自带此 App ，若没有，可在应用商店搜索，下图为小米应用商城的搜索结果。 + +image.png + +上述条件全都满足的前提下，就可以用手机预览本地构建的项目了（需要保证**手机与电脑在同一个局域网**）： + +image.png + +### 调试 + +请参考[远程调试安卓设备](https://developer.chrome.com/docs/devtools/remote-debugging?hl=zh-cn)，XR 设备同理。 + +> 在调试前确保手机开启 **`开发者选项`** ，且允许 **`USB 调试`** + +## 最佳实践 + +由于 XR 调试较为繁琐，我们建议大部分的工作和验证在 PC 预览与调试阶段完成，这样可以显著提升开发效率。 diff --git a/docs/zh/xr/quickStart/develop.md b/docs/zh/xr/quickStart/develop.md new file mode 100644 index 0000000000..a7afd48f75 --- /dev/null +++ b/docs/zh/xr/quickStart/develop.md @@ -0,0 +1,114 @@ +--- +order: 0 +title: 开发 XR 互动 +type: XR +label: XR +--- + +本篇文档讲分别讲述在编辑器和 ProCode 情况下如何快速开发 XR 互动。 + +## 编辑器 + +编辑器开发 XR 互动的流程如下所示： + +```mermaid +flowchart LR + 创建项目 --> 添加XR节点 --> 添加XR能力 --> 预览 --> 导出 +``` + +### 创建项目 + +在 **[首页](/docs/interface/intro/#%E9%A6%96%E9%A1%B5)** 点击 **创建项目** ，随后在 **[项目设置](/docs/interface/menu/#项目设置)** 中选择物理后端为 `WebXR` + +image.png + +### 添加 XR 节点 + +在 **[层级面板](/docs/interface/hierarchy/)** 添加 XR 节点 + +image.png + +> 添加 XR 节点会自动创建并选择 `origin` 和 `camera`，因此场景内不应该存在其他 `Camera` 组件，除非是有意为之。 + +> 场景内允许添加多个 XR 节点，但在同一时刻，有且只有一个 XR 节点生效。 + +### 预览 + +若已按照 [调试 XR 项目](/docs/xr/quickStart/debug/) 的要求使用 Chrome 与 [Immersive Web Emulator](https://chromewebstore.google.com/detail/immersive-web-emulator/cgffilbpcibhmcfbgggfhfolhkfbhmik) 插件，此时便可以直接预览。 + +image.png + +### XR 能力 + +为了实现炫酷的虚实融合效果，通常会为 XR 互动添加一些其他能力。 + +#### 锚点追踪 + +在任意激活的 Entity 上添加 `XR Anchor Manage` 组件，即可为 XR 添加锚点追踪的能力。 + +| 属性 | 释义 | +| :---------- | :------------------------------------------------------------------------- | +| Anchor List | 追踪的锚点列表，用 Position 和 RotationQuaternion 确定现实空间中的锚点位姿 | +| Prefab | 若设置预置体，锚点被追踪到时，该预置体会被实例化并挂载到追踪到的锚点上 | + +image.png + +#### 图片追踪 + +在任意激活的 Entity 上添加 `XR Image Manage` 组件，即可为 XR 添图片追踪的能力。 + +| 属性 | 释义 | +| :--------- | :--------------------------------------------------------------------- | +| Image List | 追踪的图片列表，添加 `ReferenceImageAssets` 来确定追踪的图片信息 | +| Prefab | 若设置预置体，锚点被追踪到时，该预置体会被实例化并挂载到追踪到的锚点上 | + +image.png + +其中，追踪的图片在编辑器中是一种资产，您可以通过在 **[资产面板](/docs/assets/interface/)** 空白处依次 **右键** → **Upload** → **XRReferenceImage** → **选中对应图片** 即可上传追踪图片。 + +| 属性 | 释义 | +| :----- | :--------------------------------------------------------------------- | +| name | 追踪图片的名称（唯一），可以根据此名称知晓被追踪到的图片 | +| Prefab | 若设置预置体，图片被追踪到时，该预置体会被实例化并挂载到追踪到的图片上 | + +> 图片追踪无法在编辑器侧进行调试，需导出构建后用手机预览并调试。 + +#### 平面追踪 + +在任意激活的 Entity 上添加 `XR Plane Manage` 组件，即可为 XR 添加平面追踪的能力。 + +| 属性 | 释义 | +| :-- | :-- | +| Detection Mode | 识别平面类型，包含 `None` 、 `Horizontal` 、`Vertical` 、`EveryThing`,可以决定追踪的平面类型，默认选择 `EveryThing` ，但在 `WebXR` 中通常识别到的是水平平面 | +| Prefab | 若设置预置体，平面被追踪到时，该预置体会被实例化并挂载到追踪到的平面上 | + +image.png + +### 注意 + +需要注意的是，`WebXR` 规定必须在页面上通过按钮的点击才可进入 XR 上下文，若为 XR 项目，编辑器在预览时会自动为项目自动添加按钮来协助开发者预览。但项目导出后此步骤需要开发者自行添加，只需在 `Button` 的 `onClick` 回调中添加下方代码即可： + +```typescript +// XR 管理器 +const xrManager = engine.xrManager; +// 开启的 XR 会话模式 +const xrMode = XRSessionMode.AR; +engine.xrManager.sessionManager.isSupportedMode(xrMode).then( + () => { + // 点击进入 XR 会话 + htmlButton.onclick = () => { + xrManager.enterXR(xrMode); + }; + }, + (error) => { + // 不支持该模式 + console.error(error); + } +); +``` + +## 脚本开发 + +在进入纯代码开发前，请先了解部分 [XR 管理器](/docs/xr/system/manager/) 内容，下方为开启 AR 互动的一个最简示例： + + \ No newline at end of file diff --git a/docs/zh/xr/session.md b/docs/zh/xr/session.md deleted file mode 100644 index c1d17707d7..0000000000 --- a/docs/zh/xr/session.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -order: 4 -title: 会话管理器 -type: XR -label: XR ---- - -会话管理器从属于 XRManager 实例，你可以通过 `xrManager.sessionManager` 获取。 - -## 属性 - -| 属性 | 类型 | 解释 | -| :----------------- | :------------- | :----------------------- | -| mode | XRSessionMode | (只读)获取当前会话类型 | -| state | XRSessionState | (只读)获取当前会话状态 | -| supportedFrameRate | Float32Array | (只读)获取硬件支持的帧率 | -| frameRate | number | (只读)获取硬件运行的帧率 | - -## 方法 - -| 方法 | 解释 | -| :-------------- | :------------------- | -| isSupportedMode | 获取是否支持会话类型 | -| run | 运行会话 | -| stop | 停止会话 | - -> 在进入 XR 会话后，开发者可以随时运行或停止会话，需要注意的是，这个状态不影响引擎的 `run` 和 `pause` 。 - -```mermaid -flowchart TD - A[enter session] --> B[run] - B --> C[stop] - C --> D[run] - D --> E[stop] - E --> F[……] - F --> G[exit session] -``` diff --git a/docs/zh/xr/start.md b/docs/zh/xr/start.md deleted file mode 100644 index d51b6d3fe3..0000000000 --- a/docs/zh/xr/start.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -order: 1 -title: 快速开发 XR 互动 -type: XR -label: XR ---- - -开发 XR 互动的流程如下所示： - -```mermaid -flowchart LR - 创建XR项目 --> 编辑项目 --> 导出 --> 本地构建 --> PC预览 --> XR设备预览 --> 正式发布 -``` - -编辑项目的环节与其他项目无异，本文将以 XR 模版为例，重点叙述 XR 项目的难点，**本地构建**， **PC 预览**与 **XR 设备预览**。 - -## 前置准备 - -由于我们引入的后端为 WebXR ，以 AR 项目为例，需要准备的运行环境与 XR 设备如下： - -- 支持 WebXR 的 PC 端浏览器（本文使用 Mac Chrome） -- 支持 WebXR 的终端与浏览器（本文使用安卓机与安卓机搭载的移动端 Chrome 应用） -- 安卓手机需额外安装 [Google Play Services for AR](https://play.google.com/store/apps/details?id=com.google.ar.core&hl=en_US&pli=1) - -> `Google Play Services for AR` 是由谷歌开发的增强现实平台（ARCore），有些手机自带此 App ，若没有，可在应用商店搜索，下图为小米应用商城的搜索结果。 - -image.png - -### PC 端调试 - -PC 端 Chrome 推荐安装 [Immersive Web Emulator](https://chromewebstore.google.com/detail/immersive-web-emulator/cgffilbpcibhmcfbgggfhfolhkfbhmik)，它是由 Meta 开发的可以让你在 Chrome 上便捷调试 WebXR 的工具，如下图所示，我们在用这款工具在 PC 端 Chrome 中模拟 XR 设备进行调试。 - -image.png - -> 上图左侧为 XR 业务面板视图区，右侧为开发者工具。 - -### 手机端调试 - -安卓机器在确认安装 `Google Play Services for AR` 后，可用 Chrome 打开 [AR 示例](https://immersive-web.github.io/webxr-samples/immersive-ar-session.html) 进行测试。 - -## XR 模版 - -在做好以上准备后，可以在**编辑器主页**的**菜单视图**侧依次**点击模版**-> **XR 模版**快速创建 XR 项目。 - -image.png - -## PC 端预览 - -按照如下命令行构建项目，即可在 PC 端调试： - -```bash -npm install -npm run https -``` - -随后在 Chrome 打开相应网址，即可调试 XR 项目。 - -image.png - -> WebXR 仅在安全环境（HTTPS）中可用，因此，构建项目调试时需启用 Https。 - -### 调试 - -如上文所述，在安装 `Immersive Web Emulator` 的前提下，依次 `打开开发者工具(F12)` -> `打开开发者工具(F12)` - -## 手机端预览 - -项目没有发布上线前，我们可以让手机与电脑在同一个局域网下进行测试。 - -image.png - -### 调试 - -请参考[远程调试安卓设备](https://developer.chrome.com/docs/devtools/remote-debugging?hl=zh-cn) - -> 在调试前确保手机开启 **`开发者选项`** ，且允许 **`USB 调试`** - -## 最佳实践 - -由于 XR 调试的困难，我们建议绝大部份的工作和验证在 PC 预览与调试阶段完成，这样可以显著提升开发效率。 diff --git a/docs/zh/xr/camera.md b/docs/zh/xr/system/camera.md similarity index 65% rename from docs/zh/xr/camera.md rename to docs/zh/xr/system/camera.md index 9dd90d2c79..9e1e80ccc7 100644 --- a/docs/zh/xr/camera.md +++ b/docs/zh/xr/system/camera.md @@ -1,5 +1,5 @@ --- -order: 3 +order: 4 title: 相机管理器 type: XR label: XR @@ -9,9 +9,9 @@ label: XR ## 属性 -| 属性 | 类型 | 解释 | -| :------------- | :----- | :--------------------- | -| fixedFoveation | number | 设置相机的固定视觉焦点 | +| 属性 | 类型 | 解释 | +| :-- | :-- | :-- | +| fixedFoveation | number | 设置相机的固定视觉焦点，详情可参考[fixedFoveation](https://developer.mozilla.org/en-US/docs/Web/API/XRProjectionLayer/fixedFoveation) | ## 方法 @@ -20,6 +20,10 @@ label: XR | attachCamera | 将虚拟世界的摄像头与现实世界的摄像头绑定 | | detachCamera | 解除虚拟世界的摄像头与现实世界的摄像头的绑定 | +> 当 XR 会话类型为 AR 时，需要绑定的相机类型为 `XRTrackedInputDevice.Camera` + +> 当 XR 会话类型为 VR 时，需要绑定的相机类型为 `XRTrackedInputDevice.LeftCamera` 和 `XRTrackedInputDevice.RightCamera` + ## 更新流程 只需将`现实相机`的参数和姿态完全同步给`虚拟相机`，`现实场景`和`虚拟场景`就可以保持**同步**。 diff --git a/docs/zh/xr/features.md b/docs/zh/xr/system/features.md similarity index 67% rename from docs/zh/xr/features.md rename to docs/zh/xr/system/features.md index 23361ca727..ae86700110 100644 --- a/docs/zh/xr/features.md +++ b/docs/zh/xr/system/features.md @@ -1,5 +1,5 @@ --- -order: 6 +order: 5 title: XR 能力 type: XR label: XR @@ -41,11 +41,7 @@ const anchor = anchorTracking.addAnchor(position, rotation); anchorTracking.removeAnchor(anchor); // 监听锚点变化 anchorTracking.addChangedListener( - ( - added: readonly XRAnchor[], - updated: readonly XRAnchor[], - removed: readonly XRAnchor[] - ) => { + (added: readonly XRAnchor[], updated: readonly XRAnchor[], removed: readonly XRAnchor[]) => { // 此处添加对新增锚点，更新锚点和移除锚点的处理 } ); @@ -86,16 +82,34 @@ xrManager.addFeature(XRPlaneTracking, XRPlaneMode.EveryThing); | addChangedListener | 添加监听平面变化的函数 | | removeChangedListener | 移除监听平面变化的函数 | -> 需要注意的是，图片追踪在添加功能时就需要指定追踪的图片，并且在 WebXR 中，同张图片只会被追踪一次。 +需要注意的是，图片追踪功能需要事先指定追踪的图片，引擎中用 `XRReferenceImage` 对象表示追踪的图片： + +| 属性 | 解释 | +| :------------ | :--------------------------------------------------------------------------------------------------- | +| name | 追踪图片的名称 | +| imageSource | 追踪图片的来源，一般使用 HtmlImageElement | +| physicalWidth | 追踪图片在现实世界的大小，默认以米为单位，若指定 `0.08` 则表示这张图片在现实世界中的尺寸为 `0.08` 米 | + +> 在 WebXR 中，同张图片只会被追踪一次。 ```typescript -// 在初始化时指定平面追踪的类型为所有 -xrManager.addFeature(XRImageTracking, [refImage]); +const image = new Image(); +image.onload = () => { + // 创建追踪图片 + const refImage = new XRReferenceImage("test", image, 0.08); + // 初始化图片追踪能力，并指定追踪图片 + xrManager.addFeature(XRImageTracking, [refImage]); +}; +image.src = "图片的 URL"; ``` -我们可以追踪现实图片，并为他们标记坐标系： +下方示例可以追踪现实图片，并标记坐标系： - + + +> 上方示例可直接生成二维码从手机侧体验，追踪图如下： + + image-20231007201437362 ## 碰撞检测 @@ -111,10 +125,6 @@ if (pointer) { const hitTest = xrManager.getFeature(XRHitTest); const { position } = pointer; // 通过屏幕空间坐标与现实空间的平面进行碰撞检测 - const result = hitTest.screenHitTest( - position.x, - position.y, - TrackableType.Plane - ); + const result = hitTest.screenHitTest(position.x, position.y, TrackableType.Plane); } ``` diff --git a/docs/zh/xr/system/input.md b/docs/zh/xr/system/input.md new file mode 100644 index 0000000000..9d66cba61c --- /dev/null +++ b/docs/zh/xr/system/input.md @@ -0,0 +1,61 @@ +--- +order: 3 +title: 交互管理器 +type: XR +label: XR +--- + +交互管理器从属于 XRManager 实例，你可以通过 `xrManager.inputManager` 获取，他管理所有的输入设备，包括但不限于： + +- 手柄 +- 头显 +- 手 +- …… + +## 方法 + +| 方法 | 解释 | +| :-- | :-- | +| getTrackedDevice | 通过类型获取某个设备，通过 `XRTrackedInputDevice` 指定希望获取的设备 | +| addTrackedDeviceChangedListener | 添加监听设备变化的函数，当设备增加或移除时，回调将被执行并且增加设备列表与移除设备列表将被作为入参 | +| removeTrackedDeviceChangedListener | 移除监听设备变化的函数 | + +当前支持的输入设备如下： + +| 枚举 | 解释 | +| :----------------------------------- | :----------------------- | +| XRTrackedInputDevice.Camera | 通常为 AR 设备的相机 | +| XRTrackedInputDevice.LeftCamera | 通常为 VR 设备头显的左眼 | +| XRTrackedInputDevice.RightCamera | 通常为 VR 设备头显的右眼 | +| XRTrackedInputDevice.Control | 通常为 AR 设备的遥控 | +| XRTrackedInputDevice.LeftControl | 通常为 VR 设备的左手柄 | +| XRTrackedInputDevice.RightController | 通常为 VR 设备的右手柄 | + +## 使用 + +通过如下代码可以监听设备的更新信息： + +```typescript +const { inputManager } = xrManager.inputManager; +inputManager.addTrackedDeviceChangedListener((added: readonly XRInput[], removed: readonly XRInput[]) => { + // 此处添加对新增设备和移除设备的处理 +}); +``` + +通过如下代码可以获取左手手柄的姿态： + +```typescript +const controller = inputManager.getTrackedDevice(XRTrackedInputDevice.LeftController); +// 手柄的姿态 +controller.gripPose.position; +controller.gripPose.rotation; +controller.gripPose.matrix; +// 是否按下 select 键 +controller.isButtonDown(XRInputButton.Select); +// 是否抬起 select 键 +controller.isButtonUp(XRInputButton.Select); +// 是否一直按着 select 键 +controller.isButtonHeldDown(XRInputButton.Select); +``` + +> `XRInputButton.Select` 对应 WebXR 原生 `XRInputSourceEventType.selectXXX` 事件 `XRInputButton.Squeeze` 对应 WebXR 原生 `XRInputSourceEventType.squeezeXXX` 事件 diff --git a/docs/zh/xr/system/manager.md b/docs/zh/xr/system/manager.md new file mode 100644 index 0000000000..4d1c52f42b --- /dev/null +++ b/docs/zh/xr/system/manager.md @@ -0,0 +1,57 @@ +--- +order: 1 +title: XR 管理器 +type: XR +label: XR +--- + +XR 管理器从属于 Engine 实例，你可以通过 `engine.xrManager` 获取。它在 XR 中扮演着总控制器的角色，主要管理： + +- 串联 XR 的整体流程 +- [XR 会话](/docs/xr/system/session/) +- [XR 交互](/docs/xr/system/input/) +- [XR 相机](/docs/xr/system/camera/) +- [XR 功能](/docs/xr/system/features/) + +## 属性 + +| 属性 | 类型 | 解释 | +| :-- | :-- | :-- | +| sessionManager | [XRSessionManager](/docs/xr/system/session/) | 会话管理器，管理 XR 会话的生命周期和上下文，通过它可以监听会话的状态变化 | +| inputManager | [XRInputManager](/docs/xr/system/input/) | 交互管理器，管理 XR 空间中的所有输入，包含手柄，头显，相机等设备，通过它可以获取所有设备信息 | +| cameraManager | [XRCameraManager](/docs/xr/system/camera/) | 相机管理器，管理 XR 空间中的头显和相机，负责连接虚拟相机和现实相机 | +| features | [XRFeature](/docs/xr/system/features/) | XR 开启的所有能力 | +| origin | [Entity](/apis/core/#Entity) | XR 初始化时的原点，它连接虚拟世界与现实世界 | + +> 若将 origin 节点放置在**场景**的 `（1，1，1）` 位置，那么当 XR 空间开启时，若追踪到的相机的位置为 `（x，y，z）` ，那么实际上相机在场景的世界坐标为 `（1 + x，1 + y，1 + z）` ，他们之间的转换即 origin 局部坐标至世界坐标的转换。 + +## 方法 + +| 方法 | 解释 | +| :-- | :-- | +| isSupportedFeature | 是否支持某个功能，开发者可以在使用前判断当前环境是否支持某功能 | +| addFeature | 添加特定 XR 功能，类似为节点添加组件 | +| getFeature | 获取特定 XR 功能，类似从节点获取组件 | +| enterXR | 进入 XR 会话，可以选择进入的 XR 会话类型（目前支持 `AR` 或 `VR`）, 若没有明确声明 `autoRun` 参数，在进入会话后会自动运行 XR 逻辑 | +| exitXR | 退出 XR 会话，所有的 XR 逻辑将被停止，上个会话添加的能力将被销毁，配置亦不会被保存， | + +## 整体流程 + +依据上方的属性与方法，梳理一下 XR 的整体流程： + +```mermaid +flowchart TD + A[Select Backend] --> B[set origin] + A --> C[attach camera] + A --> D[add feature] + B --> E[Session None] + C --> E + D --> E + E -- request --> F[Session Initializing] + F --> G[Session Initialized] + G -- run --> H[Session Running] + H -- pause --> I[Session Paused] + I -- exit --> J[Session None] +``` + + diff --git a/docs/zh/xr/system/session.md b/docs/zh/xr/system/session.md new file mode 100644 index 0000000000..b223df20e5 --- /dev/null +++ b/docs/zh/xr/system/session.md @@ -0,0 +1,39 @@ +--- +order: 2 +title: 会话管理器 +type: XR +label: XR +--- + +会话管理器从属于 XRManager 实例，你可以通过 `xrManager.sessionManager` 获取。 + +## 属性 + +| 属性 | 类型 | 解释 | +| :----------------- | :------------- | :----------------------- | +| mode | XRSessionMode | (只读)获取当前会话类型 | +| state | XRSessionState | (只读)获取当前会话状态 | +| supportedFrameRate | Float32Array | (只读)获取硬件支持的帧率 | +| frameRate | number | (只读)获取硬件运行的帧率 | + +## 方法 + +| 方法 | 解释 | +| :------------------------- | :-------------------------------------------------------------------------------------- | +| isSupportedMode | 获取是否支持会话类型，开发者可以在开启会话前判断当前环境是否支持，入参为 `AR` 或者 `VR` | +| addStateChangedListener | 添加对会话状态改变的监听，当状态改变时，回调将被执行并且最新的会话状态将被作为入参 | +| removeStateChangedListener | 移除对会话状态改变的监听 | +| run | 运行会话 | +| stop | 停止会话 | + +> XR 会话共有五种状态 `None` 、 `Initializing` 、 `Initialized` 、 `Running` 、 `Paused` ，各个状态之间的转换关系如下图，在进入 XR 会话后，开发者可以随时运行或停止会话，并且这个状态不影响引擎的 `run` 和 `pause` 。 + +```mermaid +flowchart TD + A[None] -- request --> B[Initializing] + B --> C[Initialized] + C -- AutoRun --> D[Running] + D <--> E[Paused] + D -- exit --> F[None] + E -- exit --> F +``` diff --git a/docs/zh/xr/system/toolkit.md b/docs/zh/xr/system/toolkit.md new file mode 100644 index 0000000000..3ab802d70e --- /dev/null +++ b/docs/zh/xr/system/toolkit.md @@ -0,0 +1,105 @@ +--- +order: 6 +title: 高级组件 +type: XR +label: XR +--- + +为了方便开发者快速[开发 XR 项目](/docs/xr/quickStart/develop/)，Galacean 提供了 [@galacean/engine-toolkit-xr](/docs/xr/system/toolkit/) 高级组件 ，本文将详细讲述高级组件的属性与接口。 + +| 类型 | 类 | 释义 | +| :-- | :-- | :-- | +| 组件 | TrackedComponent | 当目标物被追踪时，会在追踪到的预制体或模型上挂载此组件，可以利用 `XRAnchorManager.getTrackedComponentByTrackId` 函数根据 ID 获取 | +| | XROrigin | 可以在任意激活节点添加的组件，指定了 XR 空间的 `origin` 与 `camera`, **同一时刻至多生效一个** | +| 管理器 | XRAnchorManager | 可以在任意激活节点添加的组件，开启锚点追踪功能，并可配置追踪的锚点和追踪结果附加的预制体或模型， **同一时刻至多生效一个** | +| | XRImageManager | 可以在任意激活节点添加的组件，开启图片追踪功能，并可配置追踪的图片和追踪结果附加的预制体或模型， **同一时刻至多生效一个** | +| | XRPlaneManager | 可以在任意激活节点添加的组件，开启平面追踪功能，并可配置平面识别类型和追踪结果附加的预制体或模型， **同一时刻至多生效一个** | + +## 继承关系 + +```mermaid +flowchart TD + A[Script] --> B[TrackedComponent] + A --> C[XROrigin] + A --> D[XRTrackedObjectManager] + D --> E[XRAnchorManager] + D --> F[XRImageManager] + D --> G[XRPlaneManager] +``` + +> 本质上都是基于脚本实现的高级功能，是对 **@galacean/engine-xr** 核心操作的高级封装。 + +## XROrigin + +| 属性 | 类 | 释义 | +| :-- | :-- | :-- | +| mode | XRSessionMode | XR 会话模式，若为 `AR` 只需指定 `XRTrackedInputDevice.Camera`, 若为 `VR` 则需指定 `XRTrackedInputDevice.LeftCamera` 与 `XRTrackedInputDevice.RightCamera` | +| origin | Entity | 指定 `XRManager.origin` | +| camera | Entity | 将虚拟相机与设备相机相连接，通常为 AR 设备的相机 | +| leftCamera | Entity | 将虚拟相机与设备相机相连接，通常为头显设备的左眼 | +| rightCamera | Entity | 将虚拟相机与设备相机相连接，通常为头显设备的右眼 | + +## TrackedComponent + +| 属性 | 类 | 释义 | +| :----------------- | :-------- | :----------------------------------------------- | +| data | XRTracked | XR 追踪结果数据，包含追踪的 ID，位姿与状态等信息 | +| destroyedOnRemoval | boolean | 在追踪丢失后是否移除节点，通常为 `true` | + +## XRTrackedObjectManager + +| 属性 | 类 | 释义 | +| :----- | :------ | :-------------------------------------- | +| prefab | boolean | 在追踪丢失后是否移除节点，通常为 `true` | + +| 方法 | 释义 | +| :--------------------------- | :--------------------------------------------- | +| getTrackedComponentByTrackId | 可以通过唯一的追踪 ID 获取被追踪物体装载的组件 | + +## XRAnchorManager + +| 属性 | 类 | 释义 | +| :------ | :------- | :----------------- | +| anchors | 锚点数组 | 指定追踪的锚点位姿 | + +## XRImageManager + +| 属性 | 类 | 释义 | +| :------------- | :-------------------- | :------------- | +| trackingImages | XRReferenceImage 数组 | 指定追踪的图片 | + +## XRPlaneManager + +| 属性 | 类 | 释义 | +| :------------ | :---------- | :----------------- | +| detectionMode | XRPlaneMode | 指定追踪的平面类型 | + +下方展示如何 + +```typescript +const scene = sceneManager.scenes[0]; +const origin = scene.addRootEntity("origin"); +const camera = origin.createChild("camera"); +camera.addComponent(Camera); +const xrOrigin = origin.addComponent(XROrigin); + +// 设置模式，origin 与 camera +xrOrigin.mode = XRSessionMode.AR; +xrOrigin.origin = origin; +xrOrigin.camera = camera; + +// 添加平面识别高级管理器并配置识别的平面类型 +const xrPlaneManager = origin.addComponent(XRPlaneManager); +xrPlaneManager.detectionMode = XRPlaneMode.EveryThing; + +// 当追踪到平面时，通过 id 获取组件 +xrManager + .getFeature(XRPlaneTracking) + .addChangedListener( + (added: readonly XRTrackedPlane[], updated: readonly XRTrackedPlane[], removed: readonly XRTrackedPlane[]) => { + added.forEach((plane) => { + console.log("component", xrPlaneManager.getTrackedComponentByTrackId(plane.id)); + }); + } + ); +``` diff --git a/examples/xr-ar-imageTracking.ts b/examples/xr-ar-imageTracking.ts index afb6ade2b6..413d811d19 100644 --- a/examples/xr-ar-imageTracking.ts +++ b/examples/xr-ar-imageTracking.ts @@ -59,7 +59,7 @@ WebGLEngine.create({ }; image.src = - "https://mdn.alipayobjects.com/huamei_jvf0dp/afts/img/A*br03RK1-XTMAAAAAAAAAAAAADleLAQ/original"; + "https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*-MneS5WGJywAAAAAAAAAAAAADhuCAQ/original"; engine.run(); });