Refactor ShaderLab documention#2611
Conversation
Sway007
added
documentation
WalkthroughThe pull request comprises extensive updates to the ShaderLab documentation in Chinese. Several outdated sections—specifically the Editor, Pass, and SubShader guides—have been entirely removed. Existing documentation files, such as those covering macros, shader configuration, and overview details, have been restructured with improved formatting and examples. Additionally, the meta JSON files have been revised with simplified titles and a new key structure. New documentation files have been introduced to cover shader chunks, shader programming, global variable declarations, multi-pass shaders, material property definitions, render state configurations, and UIScript usage. Changes
Sequence Diagram(s)sequenceDiagram
participant M as Material
participant U as ShaderUIScript
participant E as Engine
M->>U: onMaterialShaderSwitched(material)
U->>U: Evaluate property changes (onPropertyChanged)
U->>U: Evaluate macro changes (onMacroChanged)
U->>E: Trigger shader update
Possibly related PRs
Suggested reviewers
Poem
Tip ⚡💬 Agentic Chat (Pro Plan, General Availability)
🪧 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 using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2611 +/- ##
==========================================
+ Coverage 68.98% 69.00% +0.02%
==========================================
Files 961 961
Lines 100345 100408 +63
Branches 8682 8699 +17
==========================================
+ Hits 69220 69291 +71
+ Misses 30865 30857 -8
Partials 260 260
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
docs/zh/graphics/material/shaderLab/intro.mdx (1)
27-36: Typo in the Editor module link.
The new “ShaderLab 语法模块参考” section is a welcome addition. However, the Editor entry’s link is currently written as./ediotrinstead of./editor. Please correct the typo to ensure the link works correctly.docs/zh/graphics/material/shaderLab/editor.mdx (1)
104-107: Language Note for Warning Callout.
The warning callout regarding mixed-type enums is informative. As noted by static analysis, consider adding a measure word between the numeral and the noun for improved clarity in the Chinese text.docs/zh/graphics/material/shaderLab/macro.mdx (3)
3-4: Usage of<br/>for SpacingThe
<br/>tag is used to introduce a line break. Verify that your markdown renderer supports HTML tags consistently; otherwise, consider using native markdown spacing where possible.
9-21: Structured Markdown Table for MacrosThe markdown table organizes the macros and their descriptions clearly. As a minor improvement, consider adding a space after the pipe in the
#undefrow (e.g., turning|#undef|等同 GLSL 用法 |into|#undef| 等同 GLSL 用法 |) for consistency and readability.
32-34: Include Macro Example in GLSLThe GLSL code block demonstrates how to use the
includemacro with a placeholder ({includeKey}). For added clarity, consider including a brief inline comment within the snippet to remind readers that{includeKey}is a placeholder for a registered key.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
docs/zh/graphics/material/shaderLab/editor.mdx(5 hunks)docs/zh/graphics/material/shaderLab/intro.mdx(1 hunks)docs/zh/graphics/material/shaderLab/macro.mdx(2 hunks)docs/zh/graphics/material/shaderLab/pass.mdx(5 hunks)docs/zh/graphics/material/shaderLab/shader.mdx(3 hunks)docs/zh/graphics/material/shaderLab/subShader.mdx(2 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/zh/graphics/material/shaderLab/shader.mdx
[uncategorized] ~135-~135: 数词与名词之间一般应存在量词，可能缺少量词。
Context: ...ctor.SourceColor。 2. 变量赋值 指赋值语句右端为任一变量名，变量具体值可由开发者通过脚本方式在运行时通过 `ShaderData.set...
(wa5)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: e2e (22.x)
- GitHub Check: codecov
🔇 Additional comments (42)
docs/zh/graphics/material/shaderLab/intro.mdx (1)
29-36: Well-structured Syntax Modules Table.
The table clearly organizes the syntax modules and their descriptions. It offers an effective navigation aid for developers.docs/zh/graphics/material/shaderLab/shader.mdx (2)
5-6: Enhanced Explanation of Shader Object.
The updated introduction now clearly explains the purpose of aShaderobject, detailing its nested structure (includingEditor,SubShader, andShaderPass). This additional context is very helpful.
7-21: Clear GLSL Code Block Example.
The embedded GLSL snippet effectively demonstrates the hierarchical structure of a Shader, including theEditorandSubShadersections as well as the global variable area. LGTM.docs/zh/graphics/material/shaderLab/editor.mdx (4)
3-3: Markup Improvement with<br/>.
The insertion of the<br/>tag at the beginning aids the visual separation of the content. This small markup change improves readability.
45-51: Enhanced Image Layout Using Flexbox.
Using a<div style={{display: "flex"}}>to display images side by side is an effective approach. The adjusted widths (435px and 200px) provide a clear visual hierarchy.
131-142: Comprehensive UIScript Section.
The updated UIScript section—including both the binding syntax and the discussion of callback registration—is very well documented. This should greatly assist developers in leveraging UIScript functionality in their materials.
263-266: Important Note on Material Property Binding.
The final callout clearly advises that this version of the ShaderLab material property module only addresses the Inspector UI and does not automatically declare the corresponding global variables inShaderPasscode. This is an important clarification for users.docs/zh/graphics/material/shaderLab/subShader.mdx (5)
5-6: Clear Introduction to the SubShader Module.
The revised introduction now effectively explains that theSubShadermodule is used both for setting shader tags and for declaring ShaderPass objects using theUsePassandPassdirectives.
7-20: Concise SubShader Syntax Example.
The provided GLSL snippet gives a clear and simple example of how aSubShaderis structured, including the Tags, UsePass, and Pass directives.
22-26: Enhanced Clarification on Tags Declaration.
The note now makes it explicit that theTagsdirective can be used to declare tags directly—without relying on the API call[SubShader.setTag]—which simplifies the developer’s workflow.
27-30: New ‘Pass’ Section Provides Valuable Detail.
Introducing a dedicated section onPasswith explanations around multi-pass shaders increases clarity. The description is thorough and links nicely to further details on thePassmodule.
34-45: UsePass Section is Clear and Informative.
The inclusion of a table listing built-in shaders alongside their pass paths offers an easy reference for developers. Overall, this section is helpful and well presented.🧰 Tools
🪛 LanguageTool
[uncategorized] ~36-~36: A punctuation mark might be missing here.
Context: ...页面。 ## UsePass 如果一个SubShader包含多个Pass，可以通过UsePass指令复用其他Pass对象，比如引擎内置的 PBR ...(AI_EN_LECTOR_MISSING_PUNCTUATION)
docs/zh/graphics/material/shaderLab/pass.mdx (13)
5-8: Comprehensive Pass Module Introduction.
The introductory text now explains that aPasscan be authored using both GLSL 100 and GLSL 300 standards, and it covers additional settings like rendering states and queues. This provides a solid conceptual foundation.
9-26: Pass Syntax Skeleton is Well Illustrated.
The code snippet clearly shows the structure of aPass(including shader entry assignments and render queue settings). This concise example helps clarify the expected syntax.
33-49: Explicit BlendState Assignment Example.
The “显示赋值” section shows how to define aBlendStateas a variable and then assign it to a Pass. This clear example is valuable for understanding how to manage rendering states explicitly.
51-66: Alternative Inline BlendState Declaration.
The section on declaringBlendStateinline within the Pass global variable domain is a useful complement to the previous example. It provides developers with flexibility in how they manage state declarations.
68-68: Clarification on Assignment Methods.
The note on differentiating between constant and variable assignments in rendering state properties is clear and informative.
70-80: Uniform Variable Declaration Section.
This section clearly explains that all GLSL-declared global variables in ShaderLab are treated as uniform variables. The code example is straightforward and helpful.
81-103: Varying Variables and Shader I/O Explained.
The description and example detailing how varying variables are declared between vertex and fragment shaders is clear and educative.
105-128: Shader Entry Functions Specification.
The code sample showing the use ofVertexShaderandFragmentShaderto designate shader entry points is concise and effective.
129-139: Render Queue Settings are Clear.
The section onRenderQueueTypedemonstrates its usage clearly while noting the equivalence to engine API values. This information is well presented.
141-154: Callout on API Override Behavior.
The info callout, including the TypeScript snippet, clearly explains that settings made in ShaderLab override any corresponding material API settings. This is an important clarification for developers.
156-160: MRT Support and Syntax Options.
The introduction to MRT (多目标渲染) effectively explains the dual support for GLSL syntaxes and outlines the two available methods for designating multiple render targets.
161-167: MRT Example Using gl_FragData.
The first MRT example clearly demonstrates how to assign values to multiple render targets withgl_FragData. This practical example is well documented.
169-183: MRT Example with Struct Return Is Clear.
The alternative MRT example—using a struct to return multiple outputs—provides a clear, modern approach to handling MRT in GLSL. This example is both thorough and easy to follow.docs/zh/graphics/material/shaderLab/macro.mdx (17)
1-1: Importing the Image ComponentThe import statement for the
Imagecomponent is correctly added, allowing its subsequent use in the document (e.g., for displaying illustrative graphics).
5-8: Title and Introductory TextThe section header “宏” and the introduction clearly inform readers that only specific GLSL-standard macros are supported in ShaderLab.
22-23: Clarification on Macro StandardsThe note clarifying that all macros (except
#include) adhere to GLSL standards—and the link to the official GLSL specification—provides useful context for readers.
24-26: Warning Callout on Macro ExpansionThe callout effectively warns that ShaderLab macros, expanded during preprocessing, cannot influence the parsing of ShaderLab structures. This is an important note for developers who might attempt dynamic macro-based logic.
28-30: Section Heading forinclude宏The heading “## include 宏” and the accompanying description clearly delineate the section focused on the include macro usage.
36-37: Introducing Code Segment Declaration MethodsThe text that introduces the two methods for declaring code segments is clear and lays the groundwork for the examples that follow.
38-40: Subsection on Editor-Based Shader CreationThe heading “### 1. 编辑器中创建 着色器 / 着色器片段” and its accompanying explanation provide a clear description of how to create shader code segments within the editor.
41-47: GLSL Example for Relative and Editor-Resolved PathsThe provided code block demonstrates both relative and absolute (editor-resolved) paths for including shader chunks. The inline comments help differentiate the two approaches.
49-49: Illustrative Image InclusionEmbedding an image via the
<Image>component enhances the documentation visually. This supports user understanding of the path concepts discussed.
51-52: Subsection on Script-Based Code Segment RegistrationThe heading “### 2. 脚本中显示注册代码段” clearly separates this method from the editor-based approach, improving the overall structure.
53-58: TypeScript Registration ExampleThe TypeScript snippet effectively demonstrates how to register an include key along with its shader source code using
ShaderFactory. The example is clear and concise.
59-62: GLSL Reference for Registered Code SegmentThis GLSL code block shows how to reference a previously registered include key, reinforcing the registration process explained in the earlier snippet.
64-67: Callout on Built-In ShaderLab Code SegmentsThe callout clearly explains the availability of built-in
PBRShaderLab code segments and the necessity of registration before they can be used. This is very useful for developers looking to customize PBR shading.
68-73: TypeScript Example for Registering Built-In SegmentsThe TypeScript code snippet provides a precise example of how to import and invoke
registerIncludesto register built-in ShaderLab segments. This concrete example further clarifies the registration process.
75-81: GLSL Example Demonstrating Usage of Built-In IncludesThe GLSL snippet, showing how to include files such as
"Common.glsl"and"BRDF.glsl", is an effective example of applying ShaderLab macros in a real-world scenario. Although the use of ellipses implies omitted context, ensure that surrounding documentation sufficiently explains the complete usage.
82-83: Reference Link to Official PBR ShaderLab CodeProviding a direct reference to the official built-in
PBRShaderLab code on GitHub is an excellent addition for users who may want to explore or extend the functionality.
83-84: Closure of Callout and Document CompletionThe callout is properly closed, and the document appears to end appropriately. Just confirm that no additional content is intended after the callout.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (7)
docs/zh/graphics/material/shaderLab/multi.mdx (1)
9-21: Multi-Pass Shader Example
The example code block clearly demonstrates how to declare several Pass blocks inside a SubShader. Consider adding brief inline comments within the code snippet to emphasize the purpose of each pass for readers who may be new to ShaderLab.docs/zh/graphics/material/shaderLab/overview.mdx (1)
29-37: Typographical Correction in Link
In the table of “ShaderLab 主要语法模块”, the link for the Editor module is written as[Editor](./ediotr). This appears to be a typographical error—please change “ediotr” to “editor”.docs/zh/graphics/material/shaderLab/renderState.mdx (2)
8-24: Code Snippet for 显示赋值The explicit assignment code snippet (lines 8–24) effectively demonstrates using a defined
BlendStatevariable and then assigning it within aPass.
• Consider ensuring that the ellipsis (...) is later replaced with complete, runnable examples for clarity.
75-84: Explanation & Callout on Assignment MethodsThe subsequent explanation (lines 75–84) and the nested callout effectively clarify the two assignment styles and remind the reader of the special case regarding render queue settings.
• A minor note: If any static analysis warnings (e.g., regarding missing quantifiers) persist on similar phrasing, consider a brief review for natural language consistency.docs/zh/graphics/material/shaderLab/property.mdx (2)
5-12: Introduction & Image UsageThe introductory paragraphs (lines 5–12) clearly explain how the
Editormodule binds shader material properties. The use of images (lines 7–11) enriches the explanation.
• Verify that the<Image>components’ attribute formatting is consistent across documents (e.g., spacing aroundsrc=) for stylistic uniformity.
79-92: Supported EditType Table – Typo NoticeThe table starting on line 81 lists the supported
EditTypevalues. Notice that in the example for Float type (line 85), "FLoat" is used instead of "Float".
Apply the following diff to correct the typo:-| Float | propertyName("Property Description", FLoat) = 0.5; <br/>propertyName("Property Description", Range(0.0, 1.0)) = 0.5; <br/> propertyName("Property Description", Enum(Item1: 1.0, Item2: 2.0, Item3: 3.0)) = 1.0; // 枚举 | +| Float | propertyName("Property Description", Float) = 0.5; <br/>propertyName("Property Description", Range(0.0, 1.0)) = 0.5; <br/> propertyName("Property Description", Enum(Item1: 1.0, Item2: 2.0, Item3: 3.0)) = 1.0; // 枚举 |docs/zh/graphics/material/shaderLab/script.mdx (1)
29-75: TypeScript Documentation for ShaderUIScriptThe TypeScript code snippet (lines 29–75) provides a thorough definition of the
ShaderUIScriptbase class.
• Typo in Documentation Comments: There are several occurrences of@parma(e.g., lines 53 and 65) which should be corrected to@param.
Below is a suggested diff for one occurrence (apply consistently to both methods):- /** - * @parma propertyName - Property name - * @parma onChanged - Fired on property changed - */ + /** + * @param propertyName - Property name + * @param onChanged - Fired on property changed + */If needed, I can generate a script to identify all instances of
@parmain the codebase.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (13)
docs/zh/graphics/material/_meta.json(1 hunks)docs/zh/graphics/material/shaderLab/_meta.json(1 hunks)docs/zh/graphics/material/shaderLab/chunk.mdx(1 hunks)docs/zh/graphics/material/shaderLab/editor.mdx(0 hunks)docs/zh/graphics/material/shaderLab/entry.mdx(1 hunks)docs/zh/graphics/material/shaderLab/global.mdx(1 hunks)docs/zh/graphics/material/shaderLab/multi.mdx(1 hunks)docs/zh/graphics/material/shaderLab/overview.mdx(2 hunks)docs/zh/graphics/material/shaderLab/pass.mdx(0 hunks)docs/zh/graphics/material/shaderLab/property.mdx(1 hunks)docs/zh/graphics/material/shaderLab/renderState.mdx(1 hunks)docs/zh/graphics/material/shaderLab/script.mdx(1 hunks)docs/zh/graphics/material/shaderLab/subShader.mdx(0 hunks)
💤 Files with no reviewable changes (3)
- docs/zh/graphics/material/shaderLab/subShader.mdx
- docs/zh/graphics/material/shaderLab/pass.mdx
- docs/zh/graphics/material/shaderLab/editor.mdx
✅ Files skipped from review due to trivial changes (1)
- docs/zh/graphics/material/_meta.json
🧰 Additional context used
🪛 LanguageTool
docs/zh/graphics/material/shaderLab/overview.mdx
[uncategorized] ~5-~5: 您的意思是""的""吗？
Context: ...高级抽象和管理特性以增强开发效率。通过 ShaderLab，开发者能够更便捷地定义材质属性、渲染配置和其他效果。尽管 ShaderLab 为着色器的编写引...
(wb4)
docs/zh/graphics/material/shaderLab/renderState.mdx
[uncategorized] ~87-~87: 数词与名词之间一般应存在量词，可能缺少量词。
Context: ...sparent;</Callout> ### 变量赋值 赋值语句右端为任一变量名，变量具体值可由开发者通过脚本方式在运行时通过ShaderData.set...
(wa5)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: e2e (22.x)
- GitHub Check: build (22.x, windows-latest)
- GitHub Check: codecov
🔇 Additional comments (38)
docs/zh/graphics/material/shaderLab/multi.mdx (3)
1-4: Clear YAML Header and Title
The YAML front matter and title (“多 Pass Shader 编写”) are clear and descriptive.
5-8: Introduction Clarity
The introductory paragraph explains the need for multi-pass shaders well. The brief description sets the stage for the detailed examples that follow.
23-49: UsePass Directive and Built-in Shaders
The “UsePass” section is well documented. The table listing the built-in shaders and their pass paths is useful, and the callout block explaining the tag setting is clear.docs/zh/graphics/material/shaderLab/entry.mdx (1)
1-4: YAML Header and Title
The header and title (“顶点、片元着色器程序编写”) are clear and set the right expectations for content on vertex and fragment shader programming.docs/zh/graphics/material/shaderLab/overview.mdx (3)
1-7: Clear Overview and Introduction
The front matter and introductory paragraphs effectively explain ShaderLab’s purpose and benefits. The simplification of the title to “ShaderLab” is on point.🧰 Tools
🪛 LanguageTool
[uncategorized] ~5-~5: 您的意思是""的""吗？
Context: ...高级抽象和管理特性以增强开发效率。通过ShaderLab，开发者能够更便捷地定义材质属性、渲染配置和其他效果。尽管ShaderLab为着色器的编写引...(wb4)
9-27: ShaderLab Syntax Example
The code block illustrating the overall ShaderLab syntax (from Shader to Pass) is clear and helpful in conveying the language structure.
38-146: Unlit ShaderLab Example Review
The “Unlit ShaderLab 示例” section provides a comprehensive code sample that covers material properties, pass configuration, and shader function declarations. Ensure that variables like${uiScriptPath}are defined in context, but overall the example is well constructed and informative.docs/zh/graphics/material/shaderLab/global.mdx (4)
1-5: Comprehensive Global Variable Documentation
The header and introductory text clearly outline the structure of global variable declarations within ShaderLab. The explanation regarding the three layers (Shader, SubShader, and Pass) is concise and informative.
7-18: Clear Presentation of Variable Types and Scope
The table listing the four types of global variables and the subsequent callout explaining variable scope are clear. This detail will help readers understand the overriding principles and the intended use of each variable type.
20-45: RenderState Subsections
The documentation for RenderState—including BlendState, DepthState, StencilState, and RasterState—is well organized, and the accompanying code examples are illustrative.
103-152: Structures, Functions, and Uniforms
The sections on declaring structures, functions, and single uniforms are thorough and mirror the GLSL syntax effectively. This detailed explanation aids developers in understanding how ShaderLab integrates with shader programming.docs/zh/graphics/material/shaderLab/chunk.mdx (4)
1-4: YAML Header and Title Check
The header and title (“Shader 代码段引用”) set clear expectations for this document, highlighting its focus on code chunk inclusion.
5-10: Explanation of theincludeMacro
The explanation of how to use theincludemacro with a simple code snippet is direct and effective. It quickly gives the reader an understanding of how code segments are referenced in ShaderLab.
11-23: Two Methods for Code Chunk Declaration
The documentation clearly distinguishes between creating shader fragments via the editor and registering them using scripts, with concise code examples for both approaches. This dual explanation is very valuable for developers with different workflows.
39-57: Callout Block on Built-in ShaderLab Includes
The callout effectively communicates the need to register built-in PBR ShaderLab chunks before they can be used. The provided TypeScript and ShaderLab code snippets are instructive and enhance clarity.docs/zh/graphics/material/shaderLab/renderState.mdx (8)
1-3: Frontmatter & Title ClarityThe frontmatter (lines 1–3) is clear and correctly establishes the document title "渲染状态设置."
5-7: Introduction ExplanationThe introductory text (lines 5–7) succinctly explains the concept that each Shader
Passcan have individual render state settings and outlines the two available methods.
26-27: Global Variable Reference NoteThe explanation following the first snippet (lines 26–27) clearly directs the reader to additional information in the global variables section.
28-44: Code Snippet for 全局变量域中声明指定The second code snippet (lines 28–44) shows an alternative method by directly declaring the
BlendStateinside thePass. The snippet is consistent with the explicit assignment method.
45-50: Callout Usage for Supplementary DetailsThe first callout block (lines 45–50) properly emphasizes that similar settings apply for
DepthStateand others, and notes the possible scope of global variables.
51-54: Section Introduction for 渲染状态属性设置The heading and introductory text (lines 51–54) for render state property settings are clear and well-positioned as a new section.
55-74: Shader "Demo" Code ExampleThe GLSL code snippet (lines 55–74) is comprehensive in demonstrating two methods of setting
BlendStateproperties (constant assignment vs variable assignment). Ensure that the snippet’s placeholders (e.g.,...) are eventually replaced with full examples.
89-101: Nested Callout for Material API SettingsThe nested callout (lines 89–101) concisely warns that settings via material APIs won’t take effect when the render states/queues are declared in ShaderLab. This is a useful reminder to readers.
docs/zh/graphics/material/shaderLab/_meta.json (1)
1-10: Meta JSON Structure UpdateThe restructured JSON (lines 1–10) clearly reflects the new documentation organization. The removal of old keys and the introduction of new, more descriptive keys (e.g.,
"renderState": "渲染状态设置") align well with the refactored docs.docs/zh/graphics/material/shaderLab/property.mdx (5)
1-3: Frontmatter & Document TitleThe frontmatter (lines 1–3) correctly sets the document title to "材质属性定义" and is well formatted.
15-47: Editor 模块语法骨架 Code SnippetThe GLSL code snippet (lines 15–47) effectively demonstrates the syntax for using the
Editormodule. The structure (withProperties,Macros, and the UIScript directive) is clear and instructive.
49-63: 材质属性定义 Code ExampleThe subsequent code snippet (lines 49–63) shows the basic syntax for declaring a property with multilingual comments. This is a good minimal example that reinforces the documentation.
64-77: Callout for Grouping PropertiesThe callout (lines 64–77) explaining the use of
Headerto group related properties is clear. It provides an informative example that readers can follow.
93-125: 材质宏属性定义 SectionThe section (lines 93–125) for material macro property definitions is well structured and provides clear examples (including a table of supported macro types). Overall, the document is informative and aligns with the refactoring goals.
docs/zh/graphics/material/shaderLab/script.mdx (9)
1-3: Frontmatter & TitleThe frontmatter (lines 1–3) accurately sets the document title to "UIScript 的使用和绑定."
5-7: Introduction of UIScript Binding ConceptThe introductory text (lines 5–7) clearly articulates the purpose of binding UIScript callbacks with custom material properties.
9-15: UIScript Binding Code SnippetThe GLSL snippet (lines 9–15) demonstrating UIScript binding within the
Editorblock is concise and to the point. Consider verifying that the placeholder path ("/path/to/script") is updated when integrating with actual examples.
16-19: Explanation on Script Path FormatsThe explanation (lines 16–19) clearly distinguishes between absolute and relative UIScript paths.
20-23: Image Display for UIScript DocumentationThe
<Image>component (lines 20–23) provides visual support for the documentation. The usage is consistent with other docs; just ensure that the image dimensions and captions meet design guidelines.
25-28: UIScript 接口 Section IntroductionThe heading (lines 25–28) introducing the UIScript interface is clear. The subsequent TypeScript code snippet will detail the API.
77-84: UIScript 编写 Section & ImageThe "UIScript 编写" section (lines 77–84) is clear and is well supplemented by the accompanying image that demonstrates how to create a UIScript.
87-133: Extended UIScript Example ImplementationThe extended TypeScript example (lines 87–133) nicely demonstrates inheritance from
ShaderUIScript, registering property callbacks, and overridingonMaterialShaderSwitched. The code is detailed and provides a realistic example of how to handle shader changes.
135-138: Final Callout WarningThe final callout (lines 135–138) effectively warns developers that UIScript binding does not implicitly declare global variables in ShaderPass. This is an important clarification.
| ```glsl showLineNumbers {4-5} | ||
| ... | ||
| Pass "0" { | ||
| ... | ||
| VertexShader = vert; | ||
| FragmentShader = frag; | ||
|
|
||
| v2f vert(a2v o) { | ||
| ... | ||
| } | ||
|
|
||
| ... | ||
|
|
||
| void frag(v2f i) { | ||
| ... | ||
| } | ||
| ... | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Shader Example Clarity and Consistency
The shader code examples are comprehensive and explain the structure of a Pass—detailing the vertex shader (VertexShader) and fragment shader (FragmentShader). However, in the fragment shader function (lines 52-56), the code uses vary.COLOR_0 even though the Varyings struct only defines fields such as uv and position. This inconsistency might confuse readers. Please either update the Varyings struct to include COLOR_0 or revise the fragment shader to reference an existing field.
| 赋值语句右端为任一变量名，变量具体值可由开发者通过脚本方式在运行时通过 `ShaderData.setInt("material_DstBlend", BlendFactor.SourceColor)` API 进行指定。 | ||
|
|
||
| <Callout type="positive"> | ||
| 除了可以在 ShaderLab 中对渲染状态和渲染队列进行设置，开发者同样可以通过材质的API进行设置，如 |
|
|
||
| ## UsePass | ||
|
|
||
| 开发者可以通过 `UsePass` 指令复用引擎内置的 Shader Pass，比如引擎内置的 PBR Pass: `UsePass "pbr/Default/Forward"`。目前可服用的引擎内置 `Pass` 如下： |
| } | ||
| ``` | ||
| <Callout> | ||
| `[n]` 为 ShaderLab 预留语法，为在 [MRT](./pass/#mrt多目标渲染) 多目标渲染下对渲染目标索引的指定。当前引擎尚不支持对 MRT 下各个渲染目标的 `BlendState` 进行单独设置，因此`n` 只能是0，或者省略。 |
|
|
||
| ## 渲染状态 | ||
|
|
||
| 包含混合状态(`BlendState`)，深度状态(`DepthState`)，模板状态(`StencilState`)，光栅化状态(`RasterState`)，渲染队列(`renderQueueType`)。 |
| } | ||
| ``` | ||
| <Callout> | ||
| [CompareFunction](/apis/galacean/#CompareFunction) 和 [StencilOperation](/apis/galacean/#StencilOperation) 举等同引擎 API |
| ``` | ||
|
|
||
| <Callout> | ||
| [CullMode](/apis/galacean/#CullMode) 举等同引擎 API |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
docs/zh/graphics/material/shaderLab/renderState.mdx (4)
6-6: Improve Chinese grammar and numeral consistency.Use a comma and colon for readability, and replace the Arabic numeral with a Chinese numeral for consistency.
- 在 ShaderLab 中我们有2种设置方式。 + 在 ShaderLab 中，有两种设置方式：
26-26: Clarify link text for the global variables section.The current link text “[章节]” is vague. It’s clearer to include the actual section name in the link.
- 如全局变量[章节](./global)所示，通过... + 如[全局变量](./global)章节所示，通过...
53-53: Use Chinese numeral and streamline wording.For consistency with other sections, replace “2种” with “两种” and adjust sentence structure.
- 单个渲染状态属性设置同样也有2种方式。 + 单个渲染状态属性同样也有两种设置方式。
75-75: Correct punctuation and numeric wording.Adjust punctuation to Chinese style and switch to Chinese numeral. Remove redundant word “方式” at the end.
- 上述案例中对于 `BlendState` 属性赋值展示了 2 种方式: **常量赋值** 和 **变量赋值** 方式: + 上述案例中对于 `BlendState` 属性赋值展示了两种方式：**常量赋值**和**变量赋值**。
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/zh/graphics/material/shaderLab/global.mdx(1 hunks)docs/zh/graphics/material/shaderLab/multi.mdx(1 hunks)docs/zh/graphics/material/shaderLab/renderState.mdx(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/zh/graphics/material/shaderLab/multi.mdx
- docs/zh/graphics/material/shaderLab/global.mdx
🧰 Additional context used
🪛 LanguageTool
docs/zh/graphics/material/shaderLab/renderState.mdx
[uncategorized] ~87-~87: 数词与名词之间一般应存在量词，可能缺少量词。
Context: ...sparent;</Callout> ### 变量赋值 赋值语句右端为任一变量名，变量具体值可由开发者通过脚本方式在运行时通过ShaderData.set...
(wa5)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: build (22.x, windows-latest)
- GitHub Check: codecov
- GitHub Check: e2e (22.x)
|
把🐰提的建议也改下 |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
docs/zh/graphics/material/shaderLab/renderState.mdx (5)
5-6: Improve Chinese grammar and numeric style
建议在“在 ShaderLab 中我们有2种设置方式。”中加入逗号并使用中文数字：
“在 ShaderLab 中，我们有两种设置方式。”
8-8: Use the correct technical term for 'explicit assignment'
建议将标题“显示赋值”更改为“显式赋值”，以准确表达“explicit assignment”的含义。
26-26: Clarify link text for the global variables section
当前链接文本为“章节”，建议改为“全局变量章节”或“全局变量”以提高可读性：
如全局变量[全局变量章节](./global)所示，...
28-28: Refine header phrasing
标题“全局变量域中声明指定”略显冗长和不够清晰，建议改为“在全局变量域中声明渲染状态”或“在全局作用域中声明渲染状态”。
75-75: Consistent numeric style in narrative text
建议将“展示了 2 种方式”中的“2”替换为中文数字“两”以保持前文一致：
“展示了两种方式”
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/zh/graphics/material/shaderLab/renderState.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/zh/graphics/material/shaderLab/renderState.mdx
[uncategorized] ~87-~87: 数词与名词之间一般应存在量词，可能缺少量词。
Context: ...sparent;</Callout> ### 变量赋值 赋值语句右端为任一变量名，变量具体值可由开发者通过脚本方式在运行时通过ShaderData.set...
(wa5)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: build (22.x, windows-latest)
- GitHub Check: codecov
- GitHub Check: e2e (22.x)
🔇 Additional comments (2)
docs/zh/graphics/material/shaderLab/renderState.mdx (2)
10-11: VerifyshowLineNumbersmeta syntax support
请确认文档站点的 MDX 渲染器或插件是否支持glsl showLineNumbers {4, 10}的代码块元信息格式，以确保行号高亮正确生效。
47-49: Verify anchor link correctness
请确认 “同一规则” 的锚点#全局变量作用域与global.mdx文件中的实际标题 slug 保持一致，避免链接失效。
3 participants
Please check if the PR fulfills these requirements
What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)
What is the current behavior? (You can also link to an open issue here)
What is the new behavior (if this is a feature change)?
Does this PR introduce a breaking change? (What changes might users need to make in their application due to this PR?)
Other information:
Summary by CodeRabbit
New Documentation
Removed Documentation
Updated Documentation