Update antiAliasing docs (#2679)

* refactor: update antiAliasing docs
2026-06-20 11:22:21 +08:00 · 2025-05-22 17:26:52 +08:00
parent 7185439a63
commit 263efcb9e4
6 changed files with 119 additions and 17 deletions
--- a/docs/en/graphics/camera/component.md
+++ b/docs/en/graphics/camera/component.md
@@ -19,9 +19,9 @@ After adding it, you can view the camera properties in the inspector, and the ca
 You can also mount the camera component to an [Entity](/en/docs/core/entity) in the script with the following code:

 ```typescript
-// 创建实体
+// Create an entity
 const entity = root.createChild("cameraEntity");
-// 创建相机组件
+// Create camera
 const camera = entity.addComponent(Camera);
 ```

@@ -34,28 +34,30 @@ By modifying the properties of the camera component, you can customize the rende
 You can also get the camera component and set the corresponding properties through the script.

 ```typescript
-// 从挂载相机的节点上获取相机组件
+// Get the camera component from the node where the camera is mounted
 const camera = entity.getComponent(Camera);
-// 设置相机类型
+// Set the camera type
 camera.isOrthographic = true;
-// 设置相机的近平面
+// Set the near plane of the camera
 camera.nearClipPlane = 0.1;
-// 设置相机的远平面
+// Set the far plane of the camera
 camera.farClipPlane = 100;
-// 设置相机的 FOV（角度制）
+// Set the camera's FOV (Angle mode)
 camera.fieldOfView = 45;
-// 设置相机在画布上的渲染区域（归一化）
+// Set the camera's rendered area on the canvas (normalized)
 camera.viewport = new Vector4(0, 0, 1, 1);
-// 设置相机的渲染优先级（值越小，渲染优先级越高）
+// Set the render priority of the camera (lower value means higher render priority)
 camera.priority = 0;
-// 设置相机是否开启视锥体裁剪
+// Sets whether the camera enables cone cropping
 camera.enableFrustumCulling = true;
-// 设置相机渲染前的清除标记
+// Sets the clear mark before camera rendering
 camera.clearFlags = CameraClearFlags.All;
-// 开启后处理
+// Enable post-processing
 camera.enablePostProcess = true;
-// 开启 HDR
+// Enable HDR
 camera.enableHDR = true;
+// Enable FXAA
+camera.antiAliasing = AntiAliasing.FXAA;
 ```

 The functionality corresponding to each property is as follows:
@@ -78,7 +80,8 @@ The functionality corresponding to each property is as follows:
 | Rendering Related | [depthTextureMode](/apis/core/#Camera-depthTextureMode) | Depth texture mode, default is `DepthTextureMode.None`. If enabled, the `camera_DepthTexture` depth texture can be used in the shader. For details, refer to [Camera Texture](/en/docs/graphics/camera/texture/). |
 |  | [opaqueTextureEnabled](/apis/core/#Camera-opaqueTextureEnabled) | Whether to enable opaque texture. Default is off. If enabled, the `camera_OpaqueTexture` opaque texture can be used in the shader of the transparent queue. |
 |  | [opaqueTextureDownsampling](/apis/core/#Camera-opaqueTextureDownsampling) | When opaque texture is enabled, downsampling can be set according to clarity and performance requirements. |
-|  | [msaaSamples](/apis/core/#Camera-msaaSamples) | Number of samples for multi-sample anti-aliasing, effective only when the standalone canvas is enabled, such as `enableHDR`, `enablePostProcess`, `opaqueTextureEnabled`. |
+|  | [antiAliasing](/apis/core/#Camera-antiAliasing) | Select the anti-aliasing method, the default is not turned on, see the details:[antiAliasing](/docs/graphics/quality/antiAliasing)。 |
+|  | [msaaSamples](/apis/core/#Camera-msaaSamples) | Multiple anti-aliasing sample number, default 4 times, see details[antiAliasing](/docs/graphics/quality/antiAliasing)。 |
 |  | [enableHDR](/apis/core/#Camera-enableHDR) | Whether to enable HDR rendering, allowing the shader's output color to be stored using floating-point numbers, providing a wider range of values for post-processing and other scenarios. |
 |  | [enablePostProcess](/apis/core/#Camera-enablePostProcess) | Whether to enable post-processing. For post-processing configuration, see [Post-Processing Tutorial](/en/docs/graphics/postProcess/postProcess). |
 |  | [postProcessMask](/apis/core/#Camera-postProcessMask) | Post-processing mask, which determines the effective post-processing components. For post-processing configuration, [Post-Processing Tutorial](/en/docs/graphics/postProcess/postProcess). |
--- a/docs/en/graphics/quality/antiAliasing.mdx
+++ b/docs/en/graphics/quality/antiAliasing.mdx
@@ -0,0 +1,50 @@
+---
+order: 0
+title: Anti Aliasing
+---
+
+Anti-Aliasing (AA) is an image processing technique that aims to reduce the "aliasing" edges in images and make them smoother and more natural.
+
+<Comparison
+  leftSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*i_i6TJFeLV8AAAAAAAAAAAAAegDwAQ/original"
+  leftText="OFF"
+  rightSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*41n8SZdM8jYAAAAAAAAAAAAAegDwAQ/original"
+  rightText="FXAA + MSAA"
+/>
+
+## FXAA (Fast Approximate Anti-Aliasing)
+[Fast Approximate Anti-Aliasing (FXAA)](https://en.wikipedia.org/wiki/Fast_approximate_anti-aliasing) is screen-space anti-aliasing mode applied after the camera renders the final image,it can smooth all pixels, including by `shader-generated specular`, `alpha-cutoff edge`.
+
+<Comparison
+  leftSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*oTb9Trh4Y9sAAAAAAAAAAAAAegDwAQ/original"
+  leftText="FXAA OFF"
+  rightSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*my-aSI1FnpoAAAAAAAAAAAAAegDwAQ/original"
+  rightText="FXAA ON"
+/>
+
+Galacean turns off 'FXAA' by default, which you can configure via 'antiAliasing' under the Camera or call [antiAliasing](/apis/core/#Camera-antiAliasing) interface.
+
+## MSAA (Multiple Sampling Anti-Aliasing)
+[Multiple Sampling Anti-Aliasing (MSAA)](https://en.wikipedia.org/wiki/Multisample_anti-aliasing) is a hardware-level anti-aliasing technology, mainly addressing the jagged edges of geometric shapes. Since jagged edges caused by materials, textures, and transparency and other non-geometric objects are not affected by `MSAA`, this means that you can use `MSAA` and `FXAA` together.
+
+<Callout type="info">
+Materials, textures, and transparent surfaces are not affected by MSAA, which means you can use MSAA with FXAA.
+</Callout>
+
+<Comparison
+  leftSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*oTb9Trh4Y9sAAAAAAAAAAAAAegDwAQ/original"
+  leftText="MSAA OFF"
+  rightSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*9T8LSJ2ORscAAAAAAAAAAAAAegDwAQ/original"
+  rightText="MSAA 4x"
+/>
+
+<Callout type="warning">It can be seen that in this scenario, the leaves with transparent clipping (alphaCutoff) are not affected by MSAA, and the opaque bones are affected by MSAA.</Callout>
+
+In Galacean, the default 'msaaSamples' under the camera is' 4x'. You can modify the 'msaaSamples' to customize the 'MSAA' quality. Or directly call [msaaSamples](/apis/core/#Camera-msaaSamples) interface Settings.
+
+## How to use it in the editor?
+
+To see the anti-aliasing effect, preview through the camera window:
+
+![image](https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*-fwHQJ6nC90AAAAAAAAAAAAAegDwAQ/original) 
+![image](https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*dgVPSrM27dcAAAAAAAAAAAAAegDwAQ/original) 
--- a/docs/en/platform/platform.mdx
+++ b/docs/en/platform/platform.mdx
@@ -38,7 +38,6 @@ The platform-related export configuration will be described separately in the pl
 | Texture Type | Texture type, supports KTX2 and Original:<br/> **Original**：No processing is done on the texture <br/> **KTX2**：Enable texture compression <Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*yHPrSrhyo0sAAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}} /> Selecting KTX2 allows you to choose different compression formats:<br/> **ETC1S：** Small size, very small memory, but low quality, suitable for albedo, specular and other textures <br/> **UASTC：** Large size, high quality, suitable for normal textures <br/> <Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*_Ga2SKIDvv0AAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}} /> If the ETC1S compression format is selected, you can set the compression quality through Quality (the larger the value, the better the rendering quality):<Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*ZhviTYuo7A4AAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}} />|
 | Tree shaking | Whether to crop the exported assets: <br/>  **None:** Export all assets without cropping <br/> **Current Scene:** Export only the assets used in the current scene <br/> **All Scene:** Treeshaking all scenes, exporting all the assets used by the scenes <Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*BJbwQrdlghwAAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}} />|
 | WebGL Mode | Select the version to use with WebGL:<br/> **Auto：** WebGL2.0 is preferred. If the operating environment does not support it, it will automatically switch to WebGL1.0 <br/> **WebGL1.0：** Using WebGL1.0 <br/>  **WebGL2.0：**  Using WebGL2.0 <Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*HszfTJChrdEAAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}} />|
-| Anti-Alias | Whether to enable anti-aliasing |
 | Alpha | Whether the canvas supports transparent background. If you want the content below the canvas to be visible, you can turn it on. |
 | Preserve Drawing Buffer | Controls whether the drawing buffer retains its contents after calling the gl.clear() method. |
 | DPR Mode | [The pixel ratio of the device](/en/docs/core/canvas)，Control the size of the canvas by calling engine.canvas.resizeByClientSize: <br/> **Auto：** Automatic adaptation, that is, the parameter is window.devicePixelRatio <br/> **Fixed：** Developers set their own parameters <Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*EQOxSI8I8awAAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}} /> After selecting Fixed, developers can enter the parameters they need to set. <Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*-7YfTLegt_AAAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}} />| 
--- a/docs/zh/graphics/camera/component.md
+++ b/docs/zh/graphics/camera/component.md
@@ -56,6 +56,8 @@ camera.clearFlags = CameraClearFlags.All;
 camera.enablePostProcess = true;
 // 开启 HDR
 camera.enableHDR = true;
+// 开启 FXAA
+camera.antiAliasing = AntiAliasing.FXAA;
 ```

 其中每个属性对应的功能如下：
@@ -78,7 +80,8 @@ camera.enableHDR = true;
 | 渲染相关 | [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`。 |
+|  | [antiAliasing](/apis/core/#Camera-antiAliasing) | 选择抗锯齿方法，默认不开启，详见[抗锯齿](/docs/graphics/quality/antiAliasing)。 |
+|  | [msaaSamples](/apis/core/#Camera-msaaSamples) | 多样本抗锯齿采样样本数量，默认4倍，详见[抗锯齿](/docs/graphics/quality/antiAliasing)。 |
 |  | [enableHDR](/apis/core/#Camera-enableHDR) | 是否启用 HDR 渲染，允许 shader 输出的颜色使用浮点数进行存储，可以得到更大范围的值，用于后处理等场景。 |
 |  | [enablePostProcess](/apis/core/#Camera-enablePostProcess) | 是否启用后处理，后处理配置详见[后处理教程](/docs/graphics/postProcess/postProcess)。 |
 |  | [postProcessMask](/apis/core/#Camera-postProcessMask) | 后处理遮罩，决定生效的后处理组件，后处理配置详见[后处理教程](/docs/graphics/postProcess/postProcess)。 |
--- a/docs/zh/graphics/quality/antiAliasing.mdx
+++ b/docs/zh/graphics/quality/antiAliasing.mdx
@@ -0,0 +1,48 @@
+---
+order: 0
+title: 抗锯齿
+---
+
+抗锯齿（Anti-Aliasing，简称 AA）是一种图像处理技术，目的是减少图像中“锯齿状”边缘（aliasing），让画面更平滑、更自然。
+
+<Comparison
+  leftSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*i_i6TJFeLV8AAAAAAAAAAAAAegDwAQ/original"
+  leftText="OFF"
+  rightSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*41n8SZdM8jYAAAAAAAAAAAAAegDwAQ/original"
+  rightText="FXAA + MSAA"
+/>
+
+## FXAA (快速近似抗锯齿)
+[快速近似抗锯齿 (FXAA)](https://en.wikipedia.org/wiki/Fast_approximate_anti-aliasing) 是一种在相机渲染最终图像后的屏幕空间抗锯齿算法，通过检测边缘像素的颜色对比度使锯齿变得更平滑,
+所以它可以处理所有像素的锯齿，包括 `着色器生成的高光`，`透明裁剪（alphaCutoff）后的边缘`。
+
+<Comparison
+  leftSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*oTb9Trh4Y9sAAAAAAAAAAAAAegDwAQ/original"
+  leftText="FXAA OFF"
+  rightSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*my-aSI1FnpoAAAAAAAAAAAAAegDwAQ/original"
+  rightText="FXAA ON"
+/>
+Galacean 中默认 `FXAA` 关闭，你可以通过相机下的`抗锯齿`进行配置，或者直接调用 [antiAliasing](/apis/core/#Camera-antiAliasing) 接口设置。
+
+## MSAA (多重采样抗锯齿)
+[多重采样抗锯齿 (MSAA)](https://en.wikipedia.org/wiki/Multisample_anti-aliasing) 是一种硬件级别的抗锯齿技术，主要解决几何边缘的锯齿问题，由于材质、纹理、和透明等非几何体造成的锯齿不会受到 `MSAA` 影响，这意味着你可以将 `MSAA` 和 `FXAA` 一起搭配使用。
+
+
+<Comparison
+  leftSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*oTb9Trh4Y9sAAAAAAAAAAAAAegDwAQ/original"
+  leftText="MSAA OFF"
+  rightSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*9T8LSJ2ORscAAAAAAAAAAAAAegDwAQ/original"
+  rightText="MSAA 4x"
+/>
+
+
+<Callout type="warning">可以看到该场景里使用透明裁剪（alphaCutoff）的叶片无法受到 MSAA 影响，不透明的骨头会受到 MSAA 影响。</Callout>
+
+Galacean 中 `MSAA采样` 默认为`4倍`，你可以修改相机下 `MSAA采样` 来自定义 `MSAA` 质量，或者直接调用 [msaaSamples](/apis/core/#Camera-msaaSamples) 接口设置。
+
+## 编辑器中如何使用？
+
+要观察抗锯齿效果需通过相机窗口预览：
+
+![image](https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*-fwHQJ6nC90AAAAAAAAAAAAAegDwAQ/original) 
+![image](https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*dgVPSrM27dcAAAAAAAAAAAAAegDwAQ/original) 
--- a/docs/zh/platform/platform.mdx
+++ b/docs/zh/platform/platform.mdx
@@ -38,7 +38,6 @@ label: Platform
 | Texture Type | 纹理类型，支持 KTX2 和 Original：<br/> **Original**：不对纹理做任何处理 <br/> **KTX2**：开启纹理压缩 <Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*yHPrSrhyo0sAAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}}/> 选择 KTX2 可以选择不同的压缩格式：<br/> **ETC1S：** 尺寸小，内存极小，但是质量较低，适合 albedo, specular 等贴图 <br/> **UASTC：** 尺寸大，质量高，适合 normal 这类贴图 <br/> <Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*_Ga2SKIDvv0AAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}} /> 如果选择了 ETC1S 压缩格式，可以通过 Quality 来设置压缩质量(值越大，渲染质量越好)：<Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*ZhviTYuo7A4AAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}} />|
 | Tree shaking | 是否对导出的资产进行裁剪： <br/>  **None:** 不进行裁剪，导出所有资产 <br/> **Current Scene:** 只导出当前场景用到的资产 <br/> **All Scene:** 对所有场景 treeshaking，导出全量场景用到的资产 <Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*BJbwQrdlghwAAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}} />|
 | WebGL Mode | 选择使用 WebGL 的版本：<br/> **Auto：** 优先使用 WebGL2.0, 如果运行环境不支持自动切到 WebGL1.0 <br/> **WebGL1.0：** 使用 WebGL1.0 <br/>  **WebGL2.0：**  使用 WebGL2.0 <Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*HszfTJChrdEAAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}} />|
-| Anti-Alias | 是否开启抗锯齿 |
 | Alpha | 画布是否支持透明背景，如果希望画布下方的内容可以透出可以开启 |
 | Preserve Drawing Buffer | 用于控制在调用 gl.clear() 方法后，绘图缓冲区是否保留其内容 |
 | DPR Mode | [设备的像素比](/docs/core/canvas)，通过调用 engine.canvas.resizeByClientSize 来控制画布的尺寸 <br/> **Auto：** 自动适配，即参数为 window.devicePixelRatio <br/> **Fixed：** 开发者自行设置参数 <Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*EQOxSI8I8awAAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}} /> 选择 Fixed 后，开发者可以自行输入需要设置的参数 <Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*-7YfTLegt_AAAAAAAAAAAAAADjCHAQ/fmt.webp" style={{zoom: "50%"}} />|