Refactor ShaderLab documention

docs/zh/graphics/material/_meta.json

@@ -2,6 +2,6 @@
   "overview": { "title": "材质概述" },
   "examples": { "title": "指南和示例" },
   "builtinShaders": { "title": "内置着色器" },
-  "shaderLab": { "title": "ShaderLab 语法" },
+  "shaderLab": { "title": "ShaderLab" },
   "variables": "内置变量"
 }

docs/zh/graphics/material/examples/custom.mdx

@@ -2,7 +2,7 @@
 title: 自定义着色器
 ---
 
-类似于 Typescript 中的函数、类、属性， Shader 代码也有一套自己的 API 和配套的 [UIScript](/docs/graphics/material/shaderLab/editor/#uiscript)。本文可以帮助你如何基于这些 API 和 [ShaderLab](/docs/graphics/material/shaderLab/intro) 语法，自定义自己的 Shader。
+类似于 Typescript 中的函数、类、属性， Shader 代码也有一套自己的 API 和配套的 [UIScript](/docs/graphics/material/shaderLab/script)。本文可以帮助你如何基于这些 API 和 [ShaderLab](/docs/graphics/material/shaderLab/overview) ，自定义自己的 Shader。
 
 ## 快速上手
 
@@ -13,7 +13,7 @@ title: 自定义着色器
   style={{ zoom: "50%" }}
 />
 
-引擎会自动帮我们创建好 Shader 文件和 [UIScript](/docs/graphics/material/shaderLab/editor/#uiscript) 文件
+引擎会自动帮我们创建好 Shader 文件和 [UIScript](/docs/graphics/material/shaderLab/script) 文件
 
 <img
   src="https://gw.alipayobjects.com/zos/OasisHub/6351fa81-5159-4469-bd95-8f21a8f2f4ac/image-20250124162909194.png"

docs/zh/graphics/material/examples/shaderData.mdx

@@ -6,7 +6,7 @@ title: 使用着色器数据
 
 ### 设置数据
 
-我们推荐使用 [ShaderLab](/docs/graphics/material/shaderLab/intro) 语法来声明和使用着色器数据：
+我们推荐使用 [ShaderLab](/docs/graphics/material/shaderLab/overview) 来声明和使用着色器数据：
 
 ```glsl showLineNumbers {3,8,17,21}
 Editor {
@@ -41,7 +41,7 @@ Editor {
 ```
 
 <Callout type="positive">
-  参考 [ShaderLab 语法](/docs/graphics/material/shaderLab/editor/#properties-属性) 使用更多类型的数据。
+  参考 [ShaderLab 属性定义 ](/docs/graphics/material/shaderLab/property) 使用更多类型的数据。
 </Callout>
 
 当然，我们也可以通过代码设置着色器数据:

docs/zh/graphics/material/overview.mdx

@@ -8,7 +8,7 @@ title: 材质概述
 
 ## 着色器
 
-着色器(Shader)是一段运行在GPU中的程序，通常由顶点着色器和片元着色器组成，我们可以借助 [ShaderLab 语法](/docs/graphics/material/shaderLab/intro/) 很方便地书写这部分代码。
+着色器(Shader)是一段运行在GPU中的程序，通常由顶点着色器和片元着色器组成，我们可以借助 [ShaderLab 语法](/docs/graphics/material/shaderLab/overview/) 很方便地书写这部分代码。
 
 ## 着色器数据
 
@@ -20,6 +20,14 @@ Galacean 支持对[混合状态（BlendState）](/apis/core/#RenderState-BlendSt
 
 我们拿一个透明物体的标准渲染流程来举例，我们希望开启透明混合，并且因为透明物体是叠加渲染的，所以我们还要关闭深度写入，并设置为透明队列;
 
+```ts
+material.renderQueueType = RenderQueueType.Transparent;
+material.renderState.depthState.writeEnabled = false;
+material.renderState.blendState.enabled = true;
+```
+
+我们推荐使用 ShaderLab 来设置：
+
 ```ts showLineNumbers {3,7-12,14}
 Pass "Pass0" {
     DepthState {
@@ -40,5 +48,5 @@ Pass "Pass0" {
 
 <Callout type="info">
   渲染状态还可以设置为变量，然后通过着色器数据来控制，详情参考 [ShaderLab
-  文档](/docs/graphics/material/shaderLab/shader)。
+  渲染状态的设置](/docs/graphics/material/shaderLab/renderState)。
 </Callout>

docs/zh/graphics/material/shaderLab/_meta.json

@@ -1,8 +1,10 @@
 {
-  "intro": "总览",
-  "shader": "Shader",
-  "editor": "Editor",
-  "subShader": "SubShader",
-  "pass": "Pass",
-  "macro": "宏"
+  "overview": "总览介绍",
+  "property": "材质属性定义",
+  "script": "UIScript 的使用和绑定",
+  "global": "全局变量声明",
+  "renderState": "渲染状态设置",
+  "entry": "顶点、片元着色器程序编写",
+  "multi": "多 Pass Shader 编写",
+  "chunk": "Shader 代码段引用"
 }

docs/zh/graphics/material/shaderLab/chunk.mdx

@@ -0,0 +1,57 @@
+---
+title: Shader 代码段引用
+---
+
+为了方便代码段复用，ShaderLab 中可以如下使用 `include` 宏进行代码段引用，后续编译过程中会被自动扩展替换。
+
+```glsl showLineNumbers
+#include "{includeKey}"
+```
+
+为了能使代码段能够通过 `include` 宏进行引用，我们有 2 种方式进行代码段声明：
+
+## 1. 编辑器中创建 着色器 / 着色器片段
+
+创建的代码段 `includeKey` 为该文件在工程中的文件路径，比如下图中，如果想在 Shader 资产 `UnlitShader` 中引用 `ShaderChunk` 代码段，分别可以通过绝对路径和相对路径引用：
+```glsl showLineNumbers
+// 相对路径
+#include "./ShaderChunk.glsl"
+
+// 编辑器解决路径
+#include "/ShaderChunk.glsl"  // 项目资产根目录
+```
+
+<Image src="https://mdn.alipayobjects.com/huamei_aftkdx/afts/img/A*3UDUS6OtbPUAAAAAAAAAAAAAeteEAQ/fmt.webp"  />
+
+## 2. 脚本中显示注册代码段
+
+```ts showLineNumbers
+import { ShaderFactory } from '@galacean/engine';
+
+const commonSource = `// shader chunk`;
+ShaderFactory.registerInclude('includeKey', commonSource);
+```
+ShaderLab 中引用
+```glsl showLineNumbers
+#include "includeKey"
+```
+
+<Callout>
+
+当前版本中，引擎提供了 `PBR` ShaderLab 内置代码段，开发者可以通过这些内置代码段对 `PBR` Shader 进行自定义扩展。需要注意的是，需要对引擎内置 ShaderLab 代码段进行注册后才可使用。
+
+```ts showLineNumbers {4} filename="Typescript"
+import { registerIncludes } from "@galacean/engine-shader-shaderlab";
+
+// 对内置 ShaderLab 代码段注册。
+registerIncludes();
+```
+
+```glsl showLineNumbers filename="ShaderLab"
+...
+#include "Common.glsl"
+#include "BRDF.glsl"
+...
+```
+官方内置 `PBR` ShaderLab 代码段源码 [参考](https://github.com/galacean/engine/blob/main/packages/shader-shaderlab/src/shaders/PBR.gs)
+</Callout>