docs: update shadow document #2265
Conversation
WalkthroughThe documentation has been extensively revised to enhance clarity and organization regarding shadow rendering and post-processing effects. Key concepts are elaborated with clearly defined parameters, improving readability. New sections on shadow behavior and post-process effects like Bloom and Tonemapping have been introduced, making the content more accessible in both English and Chinese versions. Changes
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (invoked as PR comments)
Additionally, you can add CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Outside diff range, codebase verification and nitpick comments (10)
docs/zh/graphics/light/shadow.md (5)
9-9: Clarify ShadowMap explanation.The explanation of ShadowMap technology is clear but could be enhanced with a brief mention of its advantages or common use cases.
42-46: Clarify shadow bias explanation.The explanation of shadow bias is clear but could be enhanced with practical tips or common pitfalls.
48-48: Highlight performance impact of shadows.The explanation mentions the performance impact of shadows. It would be beneficial to highlight this impact more prominently.
Line range hint
52-56:
Clarify cascade shadows explanation.The explanation of cascade shadows is clear but could be enhanced with a brief mention of its advantages or common use cases.
Line range hint
60-60:
Clarify shadow selection explanation.The explanation of shadow selection is clear but could be enhanced with a brief mention of how to prioritize lights if needed.
docs/en/graphics/light/shadow.md (5)
9-9: Clarify ShadowMap explanation.The explanation of ShadowMap technology is clear but could be enhanced with a brief mention of its advantages or common use cases.
42-46: Clarify shadow bias explanation.The explanation of shadow bias is clear but could be enhanced with practical tips or common pitfalls.
48-48: Highlight performance impact of shadows.The explanation mentions the performance impact of shadows. It would be beneficial to highlight this impact more prominently.
52-56: Clarify cascade shadows explanation.The explanation of cascade shadows is clear but could be enhanced with a brief mention of its advantages or common use cases.
Tools
LanguageTool
[style] ~52-~52: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... scene, the objects in the distance are very small, which will seriously waste the depth m...(EN_WEAK_ADJECTIVE)
[style] ~52-~52: The phrase ‘a lot of’ might be wordy and overused. Consider using an alternative.
Context: ...riously waste the depth map and produce a lot of blanks. So the engine uses the Stable C...(A_LOT_OF)
60-60: Clarify shadow selection explanation.The explanation of shadow selection is clear but could be enhanced with a brief mention of how to prioritize lights if needed.
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files selected for processing (4)
- docs/en/graphics/light/directional.md (1 hunks)
- docs/en/graphics/light/shadow.md (1 hunks)
- docs/zh/graphics/light/directional.md (1 hunks)
- docs/zh/graphics/light/shadow.md (2 hunks)
Files skipped from review due to trivial changes (1)
- docs/zh/graphics/light/directional.md
Additional context used
Markdownlint
docs/zh/graphics/light/shadow.md
72-72: null
Images should have alternate text (alt text)(MD045, no-alt-text)
docs/en/graphics/light/shadow.md
72-72: null
Images should have alternate text (alt text)(MD045, no-alt-text)
LanguageTool
docs/en/graphics/light/shadow.md
[grammar] ~22-~22: Using ‘plenty’ without ‘of’ is considered to be informal.
Context: ...#Scene-shadowCascades) | Cascade shadow quantity settings. Generally used to split shadow resolut...(PLENTY_OF_NOUNS)
[style] ~52-~52: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... scene, the objects in the distance are very small, which will seriously waste the depth m...(EN_WEAK_ADJECTIVE)
[style] ~52-~52: The phrase ‘a lot of’ might be wordy and overused. Consider using an alternative.
Context: ...riously waste the depth map and produce a lot of blanks. So the engine uses the Stable C...(A_LOT_OF)
Additional comments not posted (11)
docs/en/graphics/light/directional.md (1)
21-22: Ensure correct link to shadow documentation.Verify that the link to the shadow documentation is correct and accessible.
docs/zh/graphics/light/shadow.md (5)
11-11: Ensure the new section title is accurate.The new section title "场景配置" (Scene Configuration) should accurately reflect the content within the section.
17-26: Ensure parameter links are correct.Verify that the links to the parameters in the table are correct and accessible.
28-28: Ensure the new section title is accurate.The new section title "灯光配置" (Light Configuration) should accurately reflect the content within the section.
34-40: Ensure parameter links are correct.Verify that the links to the parameters in the table are correct and accessible.
66-66: Ensure correct link to mesh renderer component.Verify that the link to the mesh renderer component is correct and accessible.
docs/en/graphics/light/shadow.md (5)
11-11: Ensure the new section title is accurate.The new section title "Scene Configuration" should accurately reflect the content within the section.
17-26: Ensure parameter links are correct.Verify that the links to the parameters in the table are correct and accessible.
Tools
LanguageTool
[grammar] ~22-~22: Using ‘plenty’ without ‘of’ is considered to be informal.
Context: ...#Scene-shadowCascades) | Cascade shadow quantity settings. Generally used to split shadow resolut...(PLENTY_OF_NOUNS)
28-28: Ensure the new section title is accurate.The new section title "Light Configuration" should accurately reflect the content within the section.
34-40: Ensure parameter links are correct.Verify that the links to the parameters in the table are correct and accessible.
66-66: Ensure correct link to mesh renderer component.Verify that the link to the mesh renderer component is correct and accessible.
docs/zh/graphics/light/shadow.md
Outdated
| 从 `1.3` 版本开始，引擎支持投射透明裁剪（Alpha Test）物体和透明（Transparent）物体的阴影，其中，透明物体投射阴影需要在场景面板中打开 `Transparent` 开关: | ||
|
|
||
| 在这一案例当中，背景其实只是一张贴图，但通过增加一个透明阴影，可以使得 3D 物体更加自然地融合到场景当中。 | ||
|  |
There was a problem hiding this comment.
Add alt text for images.
The images should have alternate text (alt text) to improve accessibility.
- 
+ Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 从 `1.3` 版本开始，引擎支持投射透明裁剪（Alpha Test）物体和透明（Transparent）物体的阴影，其中，透明物体投射阴影需要在场景面板中打开 `Transparent` 开关: | |
| 在这一案例当中，背景其实只是一张贴图，但通过增加一个透明阴影，可以使得 3D 物体更加自然地融合到场景当中。 | |
|  | |
| 从 `1.3` 版本开始，引擎支持投射透明裁剪（Alpha Test）物体和透明（Transparent）物体的阴影，其中，透明物体投射阴影需要在场景面板中打开 `Transparent` 开关: | |
|  |
Tools
Markdownlint
72-72: null
Images should have alternate text (alt text)(MD045, no-alt-text)
| Starting from version `1.3`, the engine supports casting shadows of `alpha cutoff` objects and `transparent` objects. Among them, transparent objects casting shadows need to turn on the `Transparent` switch in the scene panel: | ||
|
|
||
| <playground src="transparent-shadow.ts"></playground> | ||
|  |
There was a problem hiding this comment.
Add alt text for images.
The images should have alternate text (alt text) to improve accessibility.
- 
+ Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Starting from version `1.3`, the engine supports casting shadows of `alpha cutoff` objects and `transparent` objects. Among them, transparent objects casting shadows need to turn on the `Transparent` switch in the scene panel: | |
| <playground src="transparent-shadow.ts"></playground> | |
|  | |
| Starting from version `1.3`, the engine supports casting shadows of `alpha cutoff` objects and `transparent` objects. Among them, transparent objects casting shadows need to turn on the `Transparent` switch in the scene panel: | |
|  |
Tools
Markdownlint
72-72: null
Images should have alternate text (alt text)(MD045, no-alt-text)
|
补充一下阴影配置调试的参考，类似最小可用原则，比如：
|
|
阴影类型，偏移，强度等属性是灯光的属性，现在是在 Shadow 里介绍的，需要调整或者加个 link 跳转 |
docs/zh/graphics/light/shadow.md
Outdated
| | [Cascades](/apis/core/#Scene-shadowCascades) | 级联阴影数量设置。一般用于大场景分割阴影分辨率。 | | ||
| | [ShadowTwoCascadeSplits](/apis/core/#Scene-shadowTwoCascadeSplits) | 划分二级级联阴影的参数。 | | ||
| | [ShadowFourCascadeSplits](/apis/core/#Scene-shadowFourCascadeSplits) | 划分四级级联阴影的参数。 | | ||
| | [Distance](/apis/core/#Scene-shadowDistance) | 最远阴影距离。超过这个距离后看不到阴影。 | |
|
|
||
| 基于这样的原理就比较好理解在 `Light` 组件中有关阴影的各项属性设置： | ||
| 场景中拥有一些配置能够影响全局阴影： |
There was a problem hiding this comment.
先描述了级联阴影的配置，然后再说级联阴影，感觉有点奇怪。
docs/zh/graphics/light/shadow.md
Outdated
|
|
||
| 目前引擎**只支持为一盏有向光 `DirectLight` 开启阴影**，这主要是因为阴影的渲染使得 DrawCall 翻倍，会严重影响渲染的性能。一般来说都会使用 `DirectLight` 模仿太阳光，所以才只支持一盏。对于有向光的阴影，有两点需要注意。 | ||
| 目前引擎**只支持为一盏有向光 `DirectLight` 投射阴影**，这主要是因为阴影的渲染使得 DrawCall 翻倍，会严重影响渲染的性能。一般来说都会使用 `DirectLight` 模仿太阳光，所以才只支持一盏。对于有向光的阴影，有两点需要注意。 | ||
|
|
||
| ### 级联阴影 |
There was a problem hiding this comment.
感觉对级联阴影的介绍没有 Unity 的好，我们像是在表述「级联阴影」用于大场景分割阴影分辨率，提高了贴图利用率，反观 Unity ，表述的是级联阴影是为了解决什么问题，这样说明用户会更明白自己在什么情况下使用级联阴影。
|
如果这里提到了直接光的概念，上部分就直接分好类吧：
|
There was a problem hiding this comment.
Actionable comments posted: 1
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files selected for processing (3)
- docs/zh/graphics/light/light.md (1 hunks)
- docs/zh/graphics/light/shadow.md (1 hunks)
- docs/zh/graphics/postProcess/postProcess.mdx (2 hunks)
Additional context used
Markdownlint
docs/zh/graphics/light/shadow.md
50-50: null
Images should have alternate text (alt text)(MD045, no-alt-text)
Additional comments not posted (9)
docs/zh/graphics/light/light.md (3)
21-21: LGTM!The note about performance implications and recommendations for using direct light sources is clear and helpful.
29-29: LGTM!The section on indirect light is clear and the playground example is a useful addition.
12-15: Verify the links for direct light types.Ensure that the links to directional light, point light, and spot light are correct and functional.
Verification successful
Verify the links for direct light types.
Ensure that the links to directional light, point light, and spot light are correct and functional.
Verified: The links for direct light types are correct and functional.
The links to directional light, point light, and spot light are correctly referenced in the
docs/zh/graphics/light/light.mdfile.
方向光links to/docs/graphics-light-directional点光源links to/docs/graphics-light-point聚光灯links to/docs/graphics-light-spotScripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Description: Verify the links for direct light types. # Test: Ensure that the links are correct and functional. rg --type md $'/docs/graphics-light-directional\n/docs/graphics-light-point\n/docs/graphics-light-spot'Length of output: 294
Script:
#!/bin/bash # Description: Verify the links for direct light types. # Test: Ensure that the links are correct and functional. rg --type md '/docs/graphics-light-directional' rg --type md '/docs/graphics-light-point' rg --type md '/docs/graphics-light-spot'Length of output: 603
docs/zh/graphics/light/shadow.md (4)
9-9: LGTM!The introduction to shadow rendering techniques is clear and informative.
11-24: LGTM!The section on scene configuration is clear and provides useful information about parameters that affect global shadows.
26-38: LGTM!The section on light configuration is clear and provides useful information about parameters related to shadow casting.
42-44: LGTM!The section on casting and receiving shadows is clear and provides useful information about the mesh renderer component.
docs/zh/graphics/postProcess/postProcess.mdx (2)
11-15: LGTM!The replacement of two
<Image>components with a single<Comparison>component enhances the presentation and improves clarity.
76-76: LGTM!The change in the section header to "最佳实践" indicates a broader focus on best practices and is a positive improvement.
There was a problem hiding this comment.
Actionable comments posted: 4
Outside diff range, codebase verification and nitpick comments (3)
docs/zh/graphics/light/shadow.md (3)
28-30: Add alt text for images.The images should have alternate text (alt text) to improve accessibility.
- <img src="https://gw.alipayobjects.com/zos/OasisHub/1b572189-db78-4f56-9d42-d8b5ea1fe857/image-20240724183629537.png" alt="image-20240724183629537" style="zoom:50%;" /> + <img src="https://gw.alipayobjects.com/zos/OasisHub/1b572189-db78-4f56-9d42-d8b5ea1fe857/image-20240724183629537.png" alt="Light configuration example" style="zoom:50%;" />
42-46: Add alt text for images.The images should have alternate text (alt text) to improve accessibility.
-  + 
Line range hint
64-66:
Add alt text for images.The images should have alternate text (alt text) to improve accessibility.
- <img src="https://gw.alipayobjects.com/zos/OasisHub/f3125f0f-09e6-4404-a84c-7013df5c0db3/image-20240724184711014.png" alt="image-20240724184711014" style="zoom:50%;" /> + <img src="https://gw.alipayobjects.com/zos/OasisHub/f3125f0f-09e6-4404-a84c-7013df5c0db3/image-20240724184711014.png" alt="Mesh renderer example" style="zoom:50%;" />Tools
Markdownlint
50-50: null
Images should have alternate text (alt text)(MD045, no-alt-text)
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files selected for processing (3)
- docs/en/graphics/light/shadow.md (1 hunks)
- docs/zh/graphics/light/shadow.md (1 hunks)
- docs/zh/graphics/postProcess/effects.mdx (1 hunks)
Additional context used
Markdownlint
docs/zh/graphics/light/shadow.md
50-50: null
Images should have alternate text (alt text)(MD045, no-alt-text)
docs/en/graphics/light/shadow.md
72-72: null
Images should have alternate text (alt text)(MD045, no-alt-text)
LanguageTool
docs/en/graphics/light/shadow.md
[grammar] ~22-~22: Using ‘plenty’ without ‘of’ is considered to be informal.
Context: ...#Scene-shadowCascades) | Cascade shadow quantity settings. Generally used to split shadow resolut...(PLENTY_OF_NOUNS)
[style] ~52-~52: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... scene, the objects in the distance are very small, which will seriously waste the depth m...(EN_WEAK_ADJECTIVE)
[style] ~52-~52: The phrase ‘a lot of’ might be wordy and overused. Consider using an alternative.
Context: ...riously waste the depth map and produce a lot of blanks. So the engine uses the Stable C...(A_LOT_OF)
Additional comments not posted (28)
docs/zh/graphics/light/shadow.md (3)
15-15: Reorganize the section for better flow.The section on cascade shadows should be introduced after explaining what cascade shadows are.
Line range hint
70-72:
Add alt text for images.The images should have alternate text (alt text) to improve accessibility.
Tools
Markdownlint
50-50: null
Images should have alternate text (alt text)(MD045, no-alt-text)
23-23: Clarify distance parameter.Specify that the distance is between the camera and the shadow.
- | [Distance](/apis/core/#Scene-shadowDistance) | 最远阴影距离（与摄像机之间的距离），超过这个距离后看不到阴影。 | + | [Distance](/apis/core/#Scene-shadowDistance) | 最远阴影距离（与摄像机之间的距离），超过这个距离后看不到阴影。 |Likely invalid or redundant comment.
docs/zh/graphics/postProcess/effects.mdx (14)
1-7: LGTM!The metadata section looks good and is correctly formatted.
9-13: LGTM!The introduction to the Bloom effect is clear and concise.
15-17: LGTM!The properties section is well-organized.
19-24: LGTM!The comparison images for the Down Scale property effectively illustrate the differences.
28-33: LGTM!The comparison images for the Threshold property are clear and informative.
37-42: LGTM!The comparison images for the Scatter property are well-presented.
46-51: LGTM!The comparison images for the Intensity property are clear and useful.
55-60: LGTM!The comparison images for the Tint property are effectively illustrating the differences.
64-69: LGTM!The comparison images for the Dirt Texture property are clear and informative.
73-78: LGTM!The comparison images for the Dirt Intensity property are well-presented.
80-83: LGTM!The introduction to the Tonemapping effect is clear and concise.
86-88: LGTM!The callout section is clear and provides useful information.
92-97: LGTM!The comparison images for the Tonemapping effect are clear and informative.
101-108: LGTM!The comparison images for the Mode property effectively illustrate the differences.
docs/en/graphics/light/shadow.md (11)
Line range hint
1-9:
LGTM!The metadata section looks good and is correctly formatted.
Tools
LanguageTool
[grammar] ~22-~22: Using ‘plenty’ without ‘of’ is considered to be informal.
Context: ...#Scene-shadowCascades) | Cascade shadow quantity settings. Generally used to split shadow resolut...(PLENTY_OF_NOUNS)
[style] ~52-~52: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... scene, the objects in the distance are very small, which will seriously waste the depth m...(EN_WEAK_ADJECTIVE)
[style] ~52-~52: The phrase ‘a lot of’ might be wordy and overused. Consider using an alternative.
Context: ...riously waste the depth map and produce a lot of blanks. So the engine uses the Stable C...(A_LOT_OF)
Markdownlint
72-72: null
Images should have alternate text (alt text)(MD045, no-alt-text)
9-11: LGTM!The introduction to shadows is clear and concise.
13-26: LGTM!The scene configuration section is well-organized and informative.
Tools
LanguageTool
[grammar] ~22-~22: Using ‘plenty’ without ‘of’ is considered to be informal.
Context: ...#Scene-shadowCascades) | Cascade shadow quantity settings. Generally used to split shadow resolut...(PLENTY_OF_NOUNS)
30-40: LGTM!The light configuration section is well-organized and informative.
42-48: LGTM!The explanation of shadow bias is clear and well-illustrated.
48-50: Clarification needed on the limitation of shadow casting.The explanation about the limitation of shadow casting for one directional light is clear, but it might be helpful to mention if there are any plans to support multiple directional lights in the future.
52-56: LGTM!The explanation of cascade shadows is clear and well-illustrated.
Tools
LanguageTool
[style] ~52-~52: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... scene, the objects in the distance are very small, which will seriously waste the depth m...(EN_WEAK_ADJECTIVE)
[style] ~52-~52: The phrase ‘a lot of’ might be wordy and overused. Consider using an alternative.
Context: ...riously waste the depth map and produce a lot of blanks. So the engine uses the Stable C...(A_LOT_OF)
60-62: LGTM!The shadow selection section is clear and informative.
64-66: LGTM!The projectors and receivers section is well-organized and informative.
68-70: LGTM!The transparent shadows section is clear and informative.
70-72: Add alt text for images.The images should have alternate text (alt text) to improve accessibility.
-  + Tools
Markdownlint
72-72: null
Images should have alternate text (alt text)(MD045, no-alt-text)
docs/zh/graphics/light/shadow.md
Outdated
| @@ -6,75 +6,47 @@ group: 光照 | |||
| label: Graphics/Light | |||
| --- | |||
|
|
|||
| 阴影能够有效增强渲染画面的立体感和真实感。在实时渲染中，一般使用所谓的 ShadowMap 技术来进行阴影的绘制，简单来说就是把光源作为一个虚拟的相机渲染场景的深度，然后从场景相机渲染画面时，比较渲染的物体与深度信息的关系，如果物体的深度比深度信息中的要深，会导致被其他物体遮挡，由此渲染阴影。 | |||
| 阴影能够有效增强渲染画面的立体感和真实感。在实时渲染中，一般使用所谓的 ShadowMap 技术来进行阴影的绘制，简单来说就是把光源作为一个虚拟的相机渲染场景的深度，然后从场景相机渲染画面时，如果物体的深度比之前保存的深度信息中的要深，认为被其他物体遮挡，则渲染阴影。 | |||
There was a problem hiding this comment.
Improve clarity and organization.
The introduction to shadow rendering is clear, but it can be enhanced by explaining the purpose of ShadowMap technology before diving into its implementation details.
+ 阴影能够有效增强渲染画面的立体感和真实感。为了实现这一点，通常使用所谓的 ShadowMap 技术。简单来说，就是把光源作为一个虚拟的相机渲染场景的深度，然后从场景相机渲染画面时，如果物体的深度比之前保存的深度信息中的要深，认为被其他物体遮挡，则渲染阴影。
- 阴影能够有效增强渲染画面的立体感和真实感。在实时渲染中，一般使用所谓的 ShadowMap 技术来进行阴影的绘制，简单来说就是把光源作为一个虚拟的相机渲染场景的深度，然后从场景相机渲染画面时，如果物体的深度比之前保存的深度信息中的要深，认为被其他物体遮挡，则渲染阴影。Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 阴影能够有效增强渲染画面的立体感和真实感。在实时渲染中，一般使用所谓的 ShadowMap 技术来进行阴影的绘制，简单来说就是把光源作为一个虚拟的相机渲染场景的深度，然后从场景相机渲染画面时，如果物体的深度比之前保存的深度信息中的要深，认为被其他物体遮挡，则渲染阴影。 | |
| 阴影能够有效增强渲染画面的立体感和真实感。为了实现这一点，通常使用所谓的 ShadowMap 技术。简单来说，就是把光源作为一个虚拟的相机渲染场景的深度，然后从场景相机渲染画面时，如果物体的深度比之前保存的深度信息中的要深，认为被其他物体遮挡，则渲染阴影。 |
docs/zh/graphics/light/shadow.md
Outdated
| | [Shadow Type](/apis/core/#Light-shadowType) | 阴影投射类型。 | | ||
| | [Shadow Bias](/apis/core/#Light-shadowBias) | 阴影的偏移 。 | | ||
| | [Normal Bias](/apis/core/#Light-shadowNormalBias) | 阴影的法向偏移 。 | | ||
| | [Near Plane](/apis/core/#Light-shadowNearPlane) | 渲染深度图时的近裁面 。 | | ||
| | [Strength](/apis/core/#Light-shadowStrength) | 阴影强度 。 | | ||
|
|
||
| ## 投射物与接受物 |
There was a problem hiding this comment.
Clarify parameter descriptions.
Some parameter descriptions can be made clearer by explaining their impact on performance and visual quality.
- | [Shadow Type](/apis/core/#Light-shadowType) | 阴影投射类型。 |
- | [Shadow Bias](/apis/core/#Light-shadowBias) | 阴影的偏移 。 |
- | [Normal Bias](/apis/core/#Light-shadowNormalBias) | 阴影的法向偏移 。 |
- | [Near Plane](/apis/core/#Light-shadowNearPlane) | 渲染深度图时的近裁面 。 |
- | [Strength](/apis/core/#Light-shadowStrength) | 阴影强度 。 |
+ | [Shadow Type](/apis/core/#Light-shadowType) | 阴影投射类型。不同类型的阴影会影响渲染性能和视觉效果。 |
+ | [Shadow Bias](/apis/core/#Light-shadowBias) | 阴影的偏移，防止阴影失真。 |
+ | [Normal Bias](/apis/core/#Light-shadowNormalBias) | 阴影的法向偏移，避免阴影失真。 |
+ | [Near Plane](/apis/core/#Light-shadowNearPlane) | 渲染深度图时的近裁面，影响阴影的精度。 |
+ | [Strength](/apis/core/#Light-shadowStrength) | 阴影强度，控制阴影的透明度。 |Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | [Shadow Type](/apis/core/#Light-shadowType) | 阴影投射类型。 | | |
| | [Shadow Bias](/apis/core/#Light-shadowBias) | 阴影的偏移 。 | | |
| | [Normal Bias](/apis/core/#Light-shadowNormalBias) | 阴影的法向偏移 。 | | |
| | [Near Plane](/apis/core/#Light-shadowNearPlane) | 渲染深度图时的近裁面 。 | | |
| | [Strength](/apis/core/#Light-shadowStrength) | 阴影强度 。 | | |
| ## 投射物与接受物 | |
| | [Shadow Type](/apis/core/#Light-shadowType) | 阴影投射类型。不同类型的阴影会影响渲染性能和视觉效果。 | | |
| | [Shadow Bias](/apis/core/#Light-shadowBias) | 阴影的偏移，防止阴影失真。 | | |
| | [Normal Bias](/apis/core/#Light-shadowNormalBias) | 阴影的法向偏移，避免阴影失真。 | | |
| | [Near Plane](/apis/core/#Light-shadowNearPlane) | 渲染深度图时的近裁面，影响阴影的精度。 | | |
| | [Strength](/apis/core/#Light-shadowStrength) | 阴影强度，控制阴影的透明度。 | | |
| ## 投射物与接受物 |
| 从 `1.3` 版本开始，引擎支持投射透明裁剪（Alpha Cutoff）物体和透明（Transparent）物体的阴影，其中，透明物体投射阴影需要在场景面板中打开 `Transparent` 开关: | ||
|
|
||
| <playground src="transparent-shadow.ts"></playground> | ||
|  |
There was a problem hiding this comment.
Clarify limitations.
Clarify why only one directional light can cast shadows and the impact on performance.
- 目前，引擎只能为一盏方向光 `DirectLight` 开启阴影，这主要是因为阴影的渲染使得 DrawCall 翻倍，会严重影响渲染的性能。在没有确定[主光(scene.sun)](/apis/core/#Scene-sun)的情况下，引擎会默认选择光强最强的那一盏灯投射阴影:
+ 目前，引擎只能为一盏方向光 `DirectLight` 开启阴影，这主要是因为阴影的渲染使得 DrawCall 翻倍，会严重影响渲染的性能。通常，`DirectLight` 用于模拟阳光，因此仅支持一盏方向光。在没有确定[主光(scene.sun)](/apis/core/#Scene-sun)的情况下，引擎会默认选择光强最强的那一盏灯投射阴影:Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 从 `1.3` 版本开始，引擎支持投射透明裁剪（Alpha Cutoff）物体和透明（Transparent）物体的阴影，其中，透明物体投射阴影需要在场景面板中打开 `Transparent` 开关: | |
| <playground src="transparent-shadow.ts"></playground> | |
|  | |
| 从 `1.3` 版本开始，引擎支持投射透明裁剪（Alpha Cutoff）物体和透明（Transparent）物体的阴影，其中，透明物体投射阴影需要在场景面板中打开 `Transparent` 开关: | |
|  | |
| 目前，引擎只能为一盏方向光 `DirectLight` 开启阴影，这主要是因为阴影的渲染使得 DrawCall 翻倍，会严重影响渲染的性能。通常，`DirectLight` 用于模拟阳光，因此仅支持一盏方向光。在没有确定[主光(scene.sun)](/apis/core/#Scene-sun)的情况下，引擎会默认选择光强最强的那一盏灯投射阴影: |
Tools
Markdownlint
50-50: null
Images should have alternate text (alt text)(MD045, no-alt-text)
| | [Cast Shadow](/apis/core/#Scene-castShadows) | 是否投射阴影。这是总开关。 | | ||
| | [Transparent](/apis/core/#Scene-enableTransparentShadow) | 是否投射透明阴影。开启后，透明物体也能投射阴影。 | | ||
| | [Resolution](/apis/core/#Scene-shadowResolution) | Shadowmap 的分辨率。`Low` 选项使用 512 分辨率，`Medium` 选项使用 1024 分辨率，`High` 选项使用 2048 分辨率，`VeryHigh` 选项使用 4096 分辨率。 | | ||
| | [Cascades](/apis/core/#Scene-shadowCascades) | [级联阴影](https://learn.microsoft.com/en-us/windows/win32/dxtecharts/cascaded-shadow-maps) 数量设置。一般用于大场景分割 shadowmap 分辨率，可以改善不同距离的阴影锯齿。开启二级级联阴影后，可以通过[ShadowTwoCascadeSplits](/apis/core/#Scene-shadowTwoCascadeSplits)配置，开启四级级联阴影后，可以通过[ShadowFourCascadeSplits](/apis/core/#Scene-shadowFourCascadeSplits)配置。 | | ||
| | [Distance](/apis/core/#Scene-shadowDistance) | 最远阴影距离（与摄像机之间的距离），超过这个距离后看不到阴影。 | | ||
| | [Fade Border](/apis/core/#Scene-shadowFadeBorder) | 阴影衰减距离，表示从阴影距离的多少比例开始衰减，范围为 [0~1]，为 0 时表示没有衰减。 | |
There was a problem hiding this comment.
Clarify parameter descriptions.
Some parameter descriptions can be made clearer by explaining their impact on performance and visual quality.
- | [Resolution](/apis/core/#Scene-shadowResolution) | Shadowmap 的分辨率。`Low` 选项使用 512 分辨率，`Medium` 选项使用 1024 分辨率，`High` 选项使用 2048 分辨率，`VeryHigh` 选项使用 4096 分辨率。 |
+ | [Resolution](/apis/core/#Scene-shadowResolution) | Shadowmap 的分辨率。`Low` 选项使用 512 分辨率，`Medium` 选项使用 1024 分辨率，`High` 选项使用 2048 分辨率，`VeryHigh` 选项使用 4096 分辨率。较高的分辨率会提高阴影的细节，但也会增加性能开销。 |Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | [Cast Shadow](/apis/core/#Scene-castShadows) | 是否投射阴影。这是总开关。 | | |
| | [Transparent](/apis/core/#Scene-enableTransparentShadow) | 是否投射透明阴影。开启后，透明物体也能投射阴影。 | | |
| | [Resolution](/apis/core/#Scene-shadowResolution) | Shadowmap 的分辨率。`Low` 选项使用 512 分辨率，`Medium` 选项使用 1024 分辨率，`High` 选项使用 2048 分辨率，`VeryHigh` 选项使用 4096 分辨率。 | | |
| | [Cascades](/apis/core/#Scene-shadowCascades) | [级联阴影](https://learn.microsoft.com/en-us/windows/win32/dxtecharts/cascaded-shadow-maps) 数量设置。一般用于大场景分割 shadowmap 分辨率，可以改善不同距离的阴影锯齿。开启二级级联阴影后，可以通过[ShadowTwoCascadeSplits](/apis/core/#Scene-shadowTwoCascadeSplits)配置，开启四级级联阴影后，可以通过[ShadowFourCascadeSplits](/apis/core/#Scene-shadowFourCascadeSplits)配置。 | | |
| | [Distance](/apis/core/#Scene-shadowDistance) | 最远阴影距离（与摄像机之间的距离），超过这个距离后看不到阴影。 | | |
| | [Fade Border](/apis/core/#Scene-shadowFadeBorder) | 阴影衰减距离，表示从阴影距离的多少比例开始衰减，范围为 [0~1]，为 0 时表示没有衰减。 | | |
| | [Cast Shadow](/apis/core/#Scene-castShadows) | 是否投射阴影。这是总开关。 | | |
| | [Transparent](/apis/core/#Scene-enableTransparentShadow) | 是否投射透明阴影。开启后，透明物体也能投射阴影。 | | |
| | [Resolution](/apis/core/#Scene-shadowResolution) | Shadowmap 的分辨率。`Low` 选项使用 512 分辨率，`Medium` 选项使用 1024 分辨率，`High` 选项使用 2048 分辨率，`VeryHigh` 选项使用 4096 分辨率。较高的分辨率会提高阴影的细节，但也会增加性能开销。 | | |
| | [Cascades](/apis/core/#Scene-shadowCascades) | [级联阴影](https://learn.microsoft.com/en-us/windows/win32/dxtecharts/cascaded-shadow-maps) 数量设置。一般用于大场景分割 shadowmap 分辨率，可以改善不同距离的阴影锯齿。开启二级级联阴影后，可以通过[ShadowTwoCascadeSplits](/apis/core/#Scene-shadowTwoCascadeSplits)配置，开启四级级联阴影后，可以通过[ShadowFourCascadeSplits](/apis/core/#Scene-shadowFourCascadeSplits)配置。 | | |
| | [Distance](/apis/core/#Scene-shadowDistance) | 最远阴影距离（与摄像机之间的距离），超过这个距离后看不到阴影。 | | |
| | [Fade Border](/apis/core/#Scene-shadowFadeBorder) | 阴影衰减距离，表示从阴影距离的多少比例开始衰减，范围为 [0~1]，为 0 时表示没有衰减。 | |
There was a problem hiding this comment.
Actionable comments posted: 1
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files selected for processing (1)
- docs/zh/graphics/light/shadow.md (1 hunks)
Additional context used
Markdownlint
docs/zh/graphics/light/shadow.md
50-50: null
Images should have alternate text (alt text)(MD045, no-alt-text)
Additional comments not posted (7)
docs/zh/graphics/light/shadow.md (7)
9-9: Approved: Improved clarity in the introduction.The introduction to shadow rendering is now clearer and more concise.
11-11: Approved: New section for scene configuration.The new section "场景配置" effectively introduces parameters that influence global shadows.
15-24: Approved: New parameter table for scene configuration.The table effectively lists and describes parameters related to shadow casting and transparency.
26-26: Approved: New section for light configuration.The new section "灯光配置" effectively introduces parameters that influence shadows within the light configuration.
30-38: Approved: New parameter table for light configuration.The table effectively lists and describes parameters related to shadow type, bias, near plane, and strength.
42-52: Approved: Updated section on transparent shadows.The section effectively explains the new capabilities introduced in version 1.3, allowing shadows to be cast from transparent objects.
Tools
Markdownlint
50-50: null
Images should have alternate text (alt text)(MD045, no-alt-text)
13-13: Add alt text for the image.The image should have alternate text to improve accessibility.
- <img src="https://gw.alipayobjects.com/zos/OasisHub/51e08840-95c0-4c68-82f0-0d2e29fbe966/image-20240726111645816.png" alt="image-20240726111645816" style="zoom:50%;" /> + <img src="https://gw.alipayobjects.com/zos/OasisHub/51e08840-95c0-4c68-82f0-0d2e29fbe966/image-20240726111645816.png" alt="Scene configuration parameters" style="zoom:50%;" />Likely invalid or redundant comment.
|
|
||
| <playground src="cascaded-shadow.ts"></playground> | ||
| <img src="https://gw.alipayobjects.com/zos/OasisHub/1b572189-db78-4f56-9d42-d8b5ea1fe857/image-20240724183629537.png" alt="image-20240724183629537" style="zoom:50%;" /> |
There was a problem hiding this comment.
Add alt text for the image.
The image should have alternate text to improve accessibility.
- <img src="https://gw.alipayobjects.com/zos/OasisHub/1b572189-db78-4f56-9d42-d8b5ea1fe857/image-20240724183629537.png" alt="image-20240724183629537" style="zoom:50%;" />
+ <img src="https://gw.alipayobjects.com/zos/OasisHub/1b572189-db78-4f56-9d42-d8b5ea1fe857/image-20240724183629537.png" alt="Light configuration parameters" style="zoom:50%;" />Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <img src="https://gw.alipayobjects.com/zos/OasisHub/1b572189-db78-4f56-9d42-d8b5ea1fe857/image-20240724183629537.png" alt="image-20240724183629537" style="zoom:50%;" /> | |
| <img src="https://gw.alipayobjects.com/zos/OasisHub/1b572189-db78-4f56-9d42-d8b5ea1fe857/image-20240724183629537.png" alt="Light configuration parameters" style="zoom:50%;" /> |
Summary by CodeRabbit