Skip to content

Commit 01d657f

Browse files
hhhhkrxhhhhkrx
committed
docs: add screen space ambient occlusion docs
1 parent 337b019 commit 01d657f

File tree

2 files changed

+219
-0
lines changed

2 files changed

+219
-0
lines changed

‎docs/en/graphics/light/ambientOcclusion.mdx‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
title: Ambient Occlusion
3+
order: 7
4+
---
5+
6+
<Image src="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*1fx8QIhX-MsAAAAAgCAAAAgAegDwAQ/original" />
7+
8+
Ambient Occlusion (AO) is a rendering technique that enhances scene realism by simulating how objects occlude ambient light in crevices, recesses, and contact areas, making the scene appear more grounded and natural.
9+
10+
---
11+
12+
## Parameters Overview
13+
14+
| Parameter | Description |
15+
|------------------------|-------------|
16+
| **Enable** | Toggle to enable or disable Ambient Occlusion |
17+
| **Quality** | Controls the number of samples and algorithm complexity; lower quality improves performance, higher quality gives finer detail but costs more performance |
18+
| **Intensity** | Controls the overall strength of AO; higher values make occlusion darker |
19+
| **Power** | Adjusts the contrast of AO shadows; higher values make dark areas darker |
20+
| **Radius** | Controls the spread of AO; larger radius makes occlusion spread further |
21+
| **Bias** | Prevents self-occlusion artifacts to avoid surfaces darkening themselves |
22+
| **Bilateral Blur** | Removes noise without blurring object edges; larger values make AO smoother |
23+
| **Min Horizon Angle** | Ignores small angle occlusion to reduce artifacts |
24+
25+
---
26+
27+
## Parameter Details
28+
29+
**Radius**
30+
<Callout type="positive">
31+
Global range, determines how far AO can spread
32+
</Callout>
33+
- Controls the sampling range of AO. If the radius is too small, AO only appears in narrow contact areas, looking “stuck to the edge.” If the radius is too large, AO will spread into areas that shouldn’t be darkened.
34+
35+
<Image src="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*5YWVTZYSPuoAAAAAgQAAAAgAegDwAQ/original" />
36+
37+
---
38+
39+
**Bias**
40+
<Callout type="positive">
41+
Local adjustment, only affects the relation between the pixel itself and its sample points
42+
</Callout>
43+
- Typically a very small positive number (recommended `0.001 – 0.01`).
44+
- Adjusts the starting point of occlusion calculations to prevent a pixel from occluding itself.
45+
- Too small → surfaces may darken themselves.
46+
- Too large → legitimate occlusion may be skipped, resulting in overly clean visuals.
47+
- If your image looks too “dirty,” try increasing Bias. If occlusion looks too weak, try decreasing it.
48+
49+
<Image src="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*uQONRpF8Sv4AAAAAgIAAAAgAegDwAQ/original" />
50+
51+
---
52+
53+
**Bilateral Blur**
54+
- Blurs the AO texture to remove noise, but only within the same object surface while preserving sharp edges.
55+
- Higher values → smoother, softer AO with clean edges.
56+
- Lower values → noisier AO with possible banding or stripes.
57+
58+
<Image src="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*lq7WSK7fgjUAAAAAgFAAAAgAegDwAQ/original" />
59+
60+
---
61+
62+
**Min Horizon Angle**
63+
- Range: `0° – 45°`
64+
- Think of it as the “minimum angle required to start counting occlusion.”
65+
- Near `0°`: even tiny gaps are considered occluded.
66+
- At `45°`: only more obvious recesses are considered.
67+
68+
Example across `0° – 45°`:
69+
<Image src="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*zGxmS6vR8RoAAAAAgPAAAAgAegDwAQ/original" />
70+
71+
---
72+
73+
## Using Ambient Occlusion
74+
75+
1. In the **Scene** settings, locate **Ambient Occlusion**.
76+
2. Click **Enable**.
77+
78+
<Image src="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*FOuFQ4lKRLEAAAAAgEAAAAgAegDwAQ/original" />
79+
80+
- **Effect Comparison**
81+
82+
<Comparison
83+
leftSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*LEn7SLWoc4MAAAAAgEAAAAgAegDwAQ/fmt.webp"
84+
leftText="AO Disabled"
85+
rightSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*AT5IQ7dq3VsAAAAAgEAAAAgAegDwAQ/original"
86+
rightText="AO Enabled"
87+
/>
88+
89+
---
90+
91+
## Best Practices
92+
93+
1. **Why does AO look too dirty?**
94+
- Don’t set the radius too high.
95+
- Large radius + high intensity = dirty.
96+
- Moderate radius + Bilateral Blur = natural.
97+
98+
2. **Combine with other post-processing**
99+
- Use with [Bloom](/docs/graphics/postProcess/effects/#bloom) and [Tonemapping](/docs/graphics/postProcess/effects/#tonemapping) to make AO shadows blend more naturally into the final image.
100+
101+
---
102+
103+
## Limitations
104+
105+
Ambient Occlusion relies on the **depth buffer**, so it has the following limitations:
106+
107+
1. **No support for transparent objects**
108+
- Transparent materials do not write to the depth buffer, so AO cannot be applied correctly to transparent surfaces.
109+
110+
2. **Depth precision**
111+
- Galacean uses a **24-bit depth buffer** and does **not support 16-bit depth**.
112+
- This avoids banding and AO noise caused by insufficient precision in 16-bit depth.
113+
114+
<Callout info="warning">
115+
On some mobile devices, high-precision depth may increase performance cost.
116+
If you notice subtle “dirty spots,” try increasing **Bias** to mitigate the issue.
117+
</Callout>

‎docs/zh/graphics/light/ambientOcclusion.mdx‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: 环境光遮蔽
3+
order: 7
4+
---
5+
6+
<Image src="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*1fx8QIhX-MsAAAAAgCAAAAgAegDwAQ/original" />
7+
8+
环境光遮蔽（Ambient Occlusion, AO）是一种增强场景真实感的渲染技术，主要用来增强物体表面在缝隙、凹陷、接触点等区域的遮蔽感，从而让画面更真实。
9+
10+
---
11+
12+
13+
## 参数总览
14+
15+
| 参数 | 说明 |
16+
|-----------------------|------|
17+
| **启用 (Enable)** | 开关控制，是否启用环境光遮蔽效果 |
18+
| **质量 (Quality)** | 控制采样数量和算法复杂度，低质量能获得更好的性能，高质量更细腻但更耗性能 |
19+
| **强度 (Intensity)** | 控制 AO 的整体强弱，数值越大，暗角越明显 |
20+
| **对比度 (Power)** | 调整 AO 暗部的对比度，较高的值会让暗部更黑 |
21+
| **半径 (Radius)** | AO 的扩散范围，半径越大，暗角扩散越远 |
22+
| **偏移 (Bias)** | 防止自遮蔽伪影，避免物体表面自己发黑 |
23+
| **双边模糊 (Bilateral Blur)** | 用于去掉噪点，不会糊到轮廓外，值越大效果越模糊 |
24+
| **最小地平角 (Min Horizon Angle)** | 忽略小角度遮蔽，减少伪影 |
25+
---
26+
27+
## 参数说明
28+
**半径 (Radius)**
29+
<Callout type="positive">
30+
全局范围，决定 AO 能蔓延多远
31+
</Callout>
32+
- 控制 AO 采样的作用范围，半径太小 AO 只出现在很窄的接触区域，看起来“贴边”，半径太大 AO 会蔓延到本不该暗的地方。
33+
34+
<Image src="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*5YWVTZYSPuoAAAAAgQAAAAgAegDwAQ/original" />
35+
36+
37+
**偏移 (Bias)**
38+
<Callout type="positive">
39+
局部范围，只影响像素本身与采样点的关系
40+
</Callout>
41+
- 通常是一个很小的正数（建议 0.001 – 0.01）
42+
- 调整遮蔽的起点，避免像素把自己算进遮蔽里，偏移太小容易出现表面发黑，偏移太大本该有的遮蔽也会被忽略，画面过于干净，如果你的画面太脏建议增大偏移，如果画面遮蔽细节太弱建议减小偏移。
43+
44+
<Image src="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*uQONRpF8Sv4AAAAAgIAAAAgAegDwAQ/original" />
45+
46+
**双边模糊 (Bilateral Blur)**
47+
- 模糊 AO 图像以去掉噪点，只在同一物体表面模糊，保留物体的边缘清晰度，数值越大 AO 更平滑柔和，同时边缘清晰，数值越小 AO 可能有噪点或条纹。
48+
49+
<Image src="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*lq7WSK7fgjUAAAAAgFAAAAgAegDwAQ/original" />
50+
51+
52+
**最小地平角 (Min Horizon Angle)**
53+
- `0° – 45°`
54+
- 我们可以把它想象成“遮蔽开始计算的最小角度”，比如接近 `0°` 的时候任何小缝隙都会被算作遮蔽，而 `45°` 则只算比较明显的凹陷。
55+
56+
从`0° – 45°`的演示：
57+
<Image src="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*zGxmS6vR8RoAAAAAgPAAAAgAegDwAQ/original" />
58+
59+
---
60+
61+
## 使用环境光遮蔽
62+
63+
1. 在 **场景** 中找到 **环境光遮蔽 (Ambient Occlusion)**。
64+
2. 点击 **启用（Enable）**。
65+
66+
<Image src="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*FOuFQ4lKRLEAAAAAgEAAAAgAegDwAQ/original" />
67+
68+
69+
- **效果对比**
70+
71+
<Comparison
72+
leftSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*LEn7SLWoc4MAAAAAgEAAAAgAegDwAQ/fmt.webp"
73+
leftText="AO 关闭"
74+
rightSrc="https://mdn.alipayobjects.com/huamei_9ahbho/afts/img/A*AT5IQ7dq3VsAAAAAgEAAAAgAegDwAQ/original"
75+
rightText="AO 开启"
76+
/>
77+
78+
---
79+
80+
## 最佳实践
81+
1. 为什么 AO 看起来过脏？
82+
- AO 半径不要开太大，半径大 + 强度高 = 脏，半径适中 + 双边模糊 = 自然。
83+
84+
2. 适当结合后处理
85+
- 搭配 [Bloom](/docs/graphics/postProcess/effects/#泛光（Bloom）)、[色调映射](/docs/graphics/postProcess/effects/#色调映射（Tonemapping）) 可以让 AO 的黑白层次在画面里更自然。
86+
---
87+
88+
## 使用限制说明
89+
90+
环境光遮蔽（AO）的计算依赖 **深度图**，因此存在以下限制：
91+
1. **不支持透明物体**
92+
- 透明材质不会写入深度缓冲，所以 AO 无法正确计算透明表面的遮蔽效果。
93+
2. **深度精度**
94+
- Galacean 使用 **24-bit** 深度缓冲，不支持 **16-bit**，这是为了避免 **16-bit** 精度不足导致的 “分层感” 和 AO 噪点问题。
95+
<Callout info="warning">
96+
在部分移动端设备上，高精度深度可能增加一定的性能开销，如果出现轻微“脏点”，可适当增加 **偏移（Bias）** 来缓解。
97+
</Callout>
98+
99+
100+
101+
102+

0 commit comments

Comments
 (0)