Update particle renderer, camera depth texture and clone doc (#803)

* docs: update particle renderer doc * docs: add camera depth doc * docs: add depth texture playground * doc: update clone doc * docs: fix doc error * docs: fix doc * docs: fix doc * fix: doc image * fix: doc order --------- Co-authored-by: GuoLei1990 <[email protected]>
galacean · Sep 16, 2023 · 53127f8 · 53127f8
1 parent abefd0b
commit 53127f8
Show file tree

Hide file tree

Showing 8 changed files with 491 additions and 209 deletions.
diff --git a/docs/camera.md b/docs/camera.md
@@ -77,10 +77,12 @@ Therefore, when used in actual projects, the type of projection is generally det
 |  | [priority](${api}core/Camera#priority) | The rendering priority is used to determine the order in which the content contained in the camera is rendered in the case of multiple cameras. |
 |  | [renderTarget](${api}core/Camera#renderTarget) | The rendering target determines which target the content will be rendered to. |
 |  | [viewport](${api}core/Camera#viewport) | The viewport, which determines the scope of the content that is finally rendered to the target device. |
+| | [pixelViewport](${api}core/Camera#pixelViewport) | The viewport of the camera in pixel coordinates on the screen. In pixel screen coordinates, the upper-left corner is (0, 0), and the lower-right corner is (1.0, 1.0). |
 |  | [nearClipPlane](${api}core/Camera#nearClipPlane) | Near clipping plane |
 |  | [farClipPlane](${api}core/Camera#farClipPlane) | Far clipping plane |
 | Perspective projection | [fieldOfView](${api}core/Camera#fieldOfView) | Field of view |
 | Orthogonal projection | [orthographicSize](${api}core/Camera#orthographicSize) | Half the size of the camera in orthographic mode |
+|  | [depthTextureMode]((${api}core/Camera#depthTextureMode)) | Depth texture mode, defalut is `DepthTextureMode.None` |
 
 For details, please read [API documentation](${api}core/Camera)。
 
@@ -100,6 +102,13 @@ In the case of multiple cameras, we can combine the camera's `renderTarget`,  `p
 
 Since in Galacean, the world coordinate system is a right-handed system, the positive direction of any node faces the -Z axis. Similarly, the positive direction of the camera (viewing direction) is also the -Z axis direction, and so on. In Unity and other world coordinates In a left-handed engine, the positive direction of the camera is the +Z axis.
 
+### Depth texture
+
+The camera can enable the depth texture through the [depthTextureMode]((${api}core/Camera#depthTextureMode)) attribute. After the depth texture is enabled, the depth texture can be accessed in the Shader through the `camera_DepthTexture` attribute. Depth textures can be used to achieve soft particles and water edge transitions, as well as some simple post-processing effects.
+Note: Depth textures only render non-transparent objects.
+
+<playground src="camera-depth-texture.ts"></playground>
+
 ## method
 
 | Properties | Explanation |

diff --git a/docs/camera.zh-CN.md b/docs/camera.zh-CN.md
@@ -65,19 +65,21 @@ entity.engine.sceneManager.activeScene._activeCameras[0];
 
 ## 属性
 
-| 类型     | 属性                                                   | 解释                                                         |
-| :------- | :----------------------------------------------------- | :----------------------------------------------------------- |
-| 通用     | [isOrthographic](${api}core/Camera#isOrthographic)     | 是否正交投影，默认是 `false`                                 |
-|          | [aspectRatio](${api}core/Camera#aspectRatio)           | 画布宽高比，一般是根据 canvas 大小自动计算，也可以手动改变（不推荐） |
-|          | [cullingMask](${api}core/Camera#cullingMask)           | 裁剪遮罩，用来选择性地渲染场景中的渲染组件。                 |
-|          | [priority](${api}core/Camera#priority)                 | 渲染优先级，用来确定在多相机的情况下按照什么顺序去渲染相机包含的内容。 |
-|          | [renderTarget](${api}core/Camera#renderTarget)         | 渲染目标，确定内容最后被渲染到哪个目标上。                   |
-|          | [viewport](${api}core/Camera#viewport)                 | 视口，确定内容最后被渲染到目标设备里的范围。                 |
-|          | [nearClipPlane](${api}core/Camera#nearClipPlane)       | 近裁剪平面                                                   |
-|          | [farClipPlane](${api}core/Camera#farClipPlane)         | 远裁剪平面                                                   |
-|          | [clearFlags](${api}core/Camera#clearFlags)             | 在渲染这个相机前清理画布缓冲的标记                           |
-| 透视投影 | [fieldOfView](${api}core/Camera#fieldOfView)           | 视角                                                         |
-| 正交投影 | [orthographicSize](${api}core/Camera#orthographicSize) | 正交模式下相机的一半尺寸                                     |
+| 类型     | 属性                                                     | 解释                                                         |
+| :------- | :------------------------------------------------------- | :----------------------------------------------------------- |
+| 通用     | [isOrthographic](${api}core/Camera#isOrthographic)       | 是否正交投影，默认是 `false`                                 |
+|          | [aspectRatio](${api}core/Camera#aspectRatio)             | 画布宽高比，一般是根据 canvas 大小自动计算，也可以手动改变（不推荐） |
+|          | [cullingMask](${api}core/Camera#cullingMask)             | 裁剪遮罩，用来选择性地渲染场景中的渲染组件。                 |
+|          | [priority](${api}core/Camera#priority)                   | 渲染优先级，用来确定在多相机的情况下按照什么顺序去渲染相机包含的内容。 |
+|          | [renderTarget](${api}core/Camera#renderTarget)           | 渲染目标，确定内容最后被渲染到哪个目标上。                   |
+|          | [viewport](${api}core/Camera#viewport)                   | 视口，确定内容最后被渲染到目标设备里的范围。                 |
+|          | [pixelViewport](${api}core/Camera#pixelViewport)         | 屏幕上相机的视口（以像素坐标表示）。 在像素屏幕坐标中，左上角为(0, 0)，右下角为(1.0, 1.0)。 |
+|          | [nearClipPlane](${api}core/Camera#nearClipPlane)         | 近裁剪平面                                                   |
+|          | [farClipPlane](${api}core/Camera#farClipPlane)           | 远裁剪平面                                                   |
+|          | [clearFlags](${api}core/Camera#clearFlags)               | 在渲染这个相机前清理画布缓冲的标记                           |
+| 透视投影 | [fieldOfView](${api}core/Camera#fieldOfView)             | 视角                                                         |
+| 正交投影 | [orthographicSize](${api}core/Camera#orthographicSize)   | 正交模式下相机的一半尺寸                                     |
+|          | [depthTextureMode]((${api}core/Camera#depthTextureMode)) | 深度我哪里模式，模型不生成                                   |
 
 详情请查看 [API 文档](${api}core/Camera)。
 
@@ -99,6 +101,13 @@ entity.engine.sceneManager.activeScene._activeCameras[0];
 
 为了方便区分，我们可以使用人脸朝向法判断，无论在左手系或者右手系，将右手放在 +X 轴上，将头部放在 +Y 轴上，此时面部朝向即正方向。
 
+### 深度纹理
+
+相机可以通过 [depthTextureMode]((${api}core/Camera#depthTextureMode)) 属性开启深度纹理，开启深度纹理后可以通过 `camera_DepthTexture` 属性在 Shader 中访问深度纹理。深度纹理可以用于实现软粒子和水面边缘过渡，以及一些简单的后处理效果。
+注意：深度纹理仅渲染非透明物体。
+
+<playground src="camera-depth-texture.ts"></playground>
+
 ## 方法
 
 | 属性                                                         | 解释                                     |

diff --git a/docs/custom-material.md b/docs/custom-material.md
@@ -67,32 +67,41 @@ In the above, we gave the material a shader, this time the program can start ren
 
 ### Properties
 
-| Name         | Type | Meaning                              |
-| :----------- | :--- | ------------------------------------ |
-| camera_ViewMat    | mat4 | viewport matrix                      |
-| camera_ProjMat    | mat4 | projection matrix                    |
-| camera_VPMat      | mat4 | viewport projection matrix           |
-| camera_ViewInvMat | mat4 | viewport inverse matrix              |
-| camera_Position  | vec3 | camera position                      |
-| renderer_LocalMat   | mat4 | model local coordinate system matrix |
-| renderer_ModelMat   | mat4 | model world Coordinate System Matrix |
-| renderer_MVMat      | mat4 | model viewport matrix                |
-| renderer_MVPMat     | mat4 | model viewport projection matrix     |
-| renderer_NormalMat  | mat4 | normal inverse transpose matrix      |
+#### Renderer
+
+| Name     | Type | Meaning                      |
+| :----------------- | :--- | ------------------------------------ |
+| renderer_LocalMat  | mat4 | model local coordinate system matrix |
+| renderer_ModelMat  | mat4 | model world Coordinate System Matrix |
+| renderer_MVMat     | mat4 | model viewport matrix                |
+| renderer_MVPMat    | mat4 | model viewport projection matrix     |
+| renderer_NormalMat | mat4 | normal matrix      |
+
+#### Camera
+
+| Name                     | Type      | Meaning                                                      |
+| :----------------------- | :-------- | ------------------------------------------------------------ |
+| camera_ViewMat           | mat4      | viewport matrix                                              |
+| camera_ProjMat           | mat4      | projection matrix                                            |
+| camera_VPMat             | mat4      | viewport projection matrix                                   |
+| camera_ViewInvMat        | mat4      | viewport inverse matrix                                      |
+| camera_Position          | vec3      | camera position                                              |
+| camera_DepthTexture      | sampler2D | camera depth information texture                             |
+| camera_DepthBufferParams | Vec4      | camera depth buffer params: (x: 1.0 - far / near, y: far / near, z: 0, w: 0) |
 
 #### Time
 
 | Name              | Type | Meaning                                                      |
 | :---------------- | :--- | :----------------------------------------------------------- |
 | scene_ElapsedTime | vec4 | Total time elapsed since engine started: (x: t, y: sin(t), z: cos(t), w: 0) |
-| oasis_DeltaTime   | vec4 | Interval time from previous frame: (x: dt, y: 0, z: 0, w: 0) |
+| scene_DeltaTime   | vec4 | Interval time from previous frame: (x: dt, y: 0, z: 0, w: 0) |
 
 #### Fog
 
 | Name            | Type | Meaning                                                      |
 | :-------------- | :--- | :----------------------------------------------------------- |
-| oasis_FogColor  | vec4 | Fog color                                                    |
-| oasis_FogParams | vec4 | Fog parameters: (x: -1/(end-start), y: end/(end-start), z: density / ln(2), w: density / sqr(ln(2)) |
+| scene_FogColor  | vec4 | Fog color                                                    |
+| scene_FogParams | vec4 | Fog parameters: (x: -1/(end-start), y: end/(end-start), z: density / ln(2), w: density / sqr(ln(2)) |
 
 
 
@@ -102,7 +111,7 @@ In the above, we gave the material a shader, this time the program can start ren
 
 In addition to the built-in variables, we can upload any variable with a custom name in the shader (it is recommended to use u\_\*\*, v\_\*\* to represent uniform and varying variables respectively), the only thing we have to do is using the correct interface according to the shader variable type. The upload interface is all in [ShaderData](${api}core/ShaderData), and the shaderData instance objects are saved in the four categories [Scene](${api}core/Scene), [Camera](${api}core/Camera), [Renderer](${api}core/Renderer), [Material](${api}core/Material) of the engine , we only need to call the interface in these shaderData, upload variables, and engine will automatically help us assemble these data at the bottom layer and optimize performance such as judging duplication.
 
-![image-20210722153638785](https://gw.alipayobjects.com/zos/OasisHub/fc605510-5b14-476f-8c91-03205c623b4b/image-20210722153638785.png)
+![original](https://mdn.alipayobjects.com/huamei_jvf0dp/afts/img/A*vC3NTp2qOuAAAAAAAAAAAAAADleLAQ/original)
 
 ### ShaderData separate benefits
 

diff --git a/docs/custom-material.zh-CN.md b/docs/custom-material.zh-CN.md
@@ -66,35 +66,43 @@ const material = new Material(engine, Shader.find("demo"));
 
 ### 属性
 
-#### 变换
-
-
-| 名字 | 类型 | 解释 |
-| :--- | :--- | ---- |
-| camera_ViewMat | mat4 | 视口矩阵 |
-| camera_ProjMat | mat4 | 投影矩阵 |
-| camera_VPMat | mat4 | 视口投影矩阵 |
-| camera_ViewInvMat | mat4 | 视口逆矩阵 |
-| camera_Position | vec3 | 相机位置 |
-| renderer_LocalMat | mat4 | 模型本地坐标系矩阵 |
-| renderer_ModelMat | mat4 | 模型世界坐标系矩阵 |
-| renderer_MVMat | mat4 | 模型视口矩阵 |
-| renderer_MVPMat | mat4 | 模型视口投影矩阵 |
-| renderer_NormalMat | mat4 | 法线逆转置矩阵 |
+#### 渲染器
+
+
+| 名字               | 类型 | 解释               |
+| :----------------- | :--- | ------------------ |
+| renderer_LocalMat  | mat4 | 模型本地坐标系矩阵 |
+| renderer_ModelMat  | mat4 | 模型世界坐标系矩阵 |
+| renderer_MVMat     | mat4 | 模型视口矩阵       |
+| renderer_MVPMat    | mat4 | 模型视口投影矩阵   |
+| renderer_NormalMat | mat4 | 法线矩阵        |
+
+#### 相机
+
+
+| 名字                     | 类型      | 解释                                                         |
+| :----------------------- | :-------- | ------------------------------------------------------------ |
+| camera_ViewMat           | mat4      | 视口矩阵                                                     |
+| camera_ProjMat           | mat4      | 投影矩阵                                                     |
+| camera_VPMat             | mat4      | 视口投影矩阵                                                 |
+| camera_ViewInvMat        | mat4      | 视口逆矩阵                                                   |
+| camera_Position          | vec3      | 相机位置                                                     |
+| camera_DepthTexture      | sampler2D | 深度信息纹理                                                 |
+| camera_DepthBufferParams | Vec4      | 相机深度缓冲参数：(x: 1.0 - far / near, y: far / near, z: 0, w: 0) |
 
 #### 时间
 
 | 名字              | 类型 | 解释                                                      |
 | :---------------- | :--- | :-------------------------------------------------------- |
 | scene_ElapsedTime | vec4 | 引擎启动后经过的总时间：(x: t, y: sin(t), z:cos(t), w: 0) |
-| oasis_DeltaTime   | vec4 | 距离上一帧的间隔时间：(x: dt, y: 0, z:0, w: 0)            |
+| scene_DeltaTime   | vec4 | 距离上一帧的间隔时间：(x: dt, y: 0, z:0, w: 0)            |
 
 #### 雾
 
 | 名字            | 类型 | 解释                                                         |
 | :-------------- | :--- | :----------------------------------------------------------- |
-| oasis_FogColor  | vec4 | 雾的颜色                                                     |
-| oasis_FogParams | vec4 | 雾的参数：(x: -1/(end-start), y: end/(end-start), z: density / ln(2), w: density / sqr(ln(2)) |
+| scene_FogColor  | vec4 | 雾的颜色                                                     |
+| scene_FogParams | vec4 | 雾的参数：(x: -1/(end-start), y: end/(end-start), z: density / ln(2), w: density / sqr(ln(2)) |
 
 ## 上传 shader 变量
 
@@ -103,7 +111,7 @@ const material = new Material(engine, Shader.find("demo"));
 除了内置的变量，我们可以在 shader 中上传任何自定义名字的变量(建议使用 u_** 、 v_** 分别表示 uniform、varying变量)，我们唯一要做的就是根据 shader 的变量类型，使用正确的接口。
 上传接口全部保存在 [ShaderData](${api}core/ShaderData) 中，而 shaderData 实例对象又分别保存在引擎的四大类 [Scene](${api}core/Scene)、[Camera](${api}core/Camera)、[Renderer](${api}core/Renderer)、[Material](${api}core/Material) 中，我们只需要分别往这些 shaderData 中调用接口，上传变量，引擎便会在底层自动帮我们组装这些数据，并进行判重等性能的优化。
 
-![](https://gw.alipayobjects.com/mdn/rms_d27172/afts/img/A*yR97QbVx-QwAAAAAAAAAAAAAARQnAQ)
+![](https://mdn.alipayobjects.com/huamei_jvf0dp/afts/img/A*ijQMQJM_Vy0AAAAAAAAAAAAADleLAQ/original)
 
 ### shaderData 分开的好处
 shaderData 分别保存在引擎的四大类 [Scene](${api}core/Scene)、[Camera](${api}core/Camera)、[Renderer](${api}core/Renderer)、[Material](${api}core/Material) 中，这样做的好处之一就是底层可以根据上传时机上传某一块 uniform，提升性能；另外，将材质无关的 shaderData 剥离出来，可以实现共享材质，比如两个 renderer ，共享了一个材质，虽然都要操控同一个 shader，但是因为这一部分 shader 数据的上传来源于两个 renderer 的 shaderData，所以是不会影响彼此的渲染结果的。

diff --git a/docs/entity-clone.md b/docs/entity-clone.md
@@ -29,19 +29,19 @@ class CustomScript extends Script{
   c:Vector3 = new Vector3(0,0,0);
 }
 
-// init entity and script.
+// Init entity and script
 const entity = engine.createEntity();
 const script = entity.addComponent(CustomScript);
 script.a = true;
 script.b = 2;
 script.c.set(1,1,1);
 
-// clone logic.
+// Clone logic
 const cloneEntity = entity.clone();
 const cloneScript = cloneEntity.getComponent(CustomScript);
-console.log(cloneScript.a);// output is true.
-console.log(cloneScript.b);// output is 2.
-console.log(cloneScript.c);// output is (1,1,1).
+console.log(cloneScript.a); // output is true.
+console.log(cloneScript.b); // output is 2.
+console.log(cloneScript.c); // output is (1,1,1).
 ```
 ### Clone decorator
 In addition to the default cloning method, the engine also provides a "cloning decorator" to customize the cloning method of script fields. The engine has four built-in clone decorations:
@@ -74,15 +74,15 @@ class CustomScript extends Script{
   d:Vector3[] = [new Vector3(0,0,0)];
 }
 
-//init entity and script.
+// Init entity and script
 const entity = engine.createEntity();
 const script = entity.addComponent(CustomScript);
 script.a = true;
 script.b = 2;
 script.c[0].set(1,1,1);
 script.d[0].set(1,1,1);
 
-// clone logic.
+// Clone logic
 const cloneEntity = entity.clone();
 const cloneScript = cloneEntity.getComponent(CustomScript);
 console.log(cloneScript.a);// output is false,ignoreClone will ignore the value.
@@ -96,8 +96,9 @@ cloneScript.d[0].set(2,2,2);// change the field d[0] value to (2,2,2).
 console.log(script.c[0]);// output is (2,2,2). bacause shallowClone let c[0] use the same reference with cloneScript's c[0].
 console.log(script.d[0]);// output is (1,1,1). bacause deepClone let d[0] use the different reference with cloneScript's d[0].
 ```
-Note:
+- Notice: 
 
-- `shallowClone` and `deepClone` are applicable to *Object*, *Array* and *Class* types.
-- `shallowClone` will keep its own references independent after cloning, and clone all its internal fields by means of assignment (if the internal field is a basic type, the value will be copied, if the internal field is a reference type, its reference address will be copied).
-- `deepClone` If *Class* is encountered in the deep cloning process, it will call the object's [cloneTo()](${api}design/IClone#cloneTo) to implement cloning, and the object needs to implement [IClone](${api}design /IClone) interface.
+  - `shallowClone` and `deepClone` are usually used for *Object*, *Array* and *Class* types.
+  - `shallowClone` will keep its own reference independent after cloning, and use assignment to clone all its internal fields (if the internal field is a basic type, the value will be copied, if the internal field is a reference type, its reference address will be copied).
+  - `deepClone` is a deep clone, which will perform deep recursion on the properties. How to clone the sub-properties of the properties depends on the decorator of the sub-properties.
+  - If the clone decorator cannot meet the requirements, you can add a custom clone by implementing the [_cloneTo()](${api}design/IClone#cloneTo) method.