diff --git a/docs/en/graphics/shader/builtins/intro.mdx b/docs/en/graphics/shader/builtins/intro.mdx index 4698e4e7af..cd4d378709 100644 --- a/docs/en/graphics/shader/builtins/intro.mdx +++ b/docs/en/graphics/shader/builtins/intro.mdx @@ -6,9 +6,9 @@ Currently, the Galacean engine has many built-in shaders, such as | Type | Description | | :-- | :-- | -| [Unlit](/en/docs/graphics/shader/builtins/unlit) | The Unlit material is suitable for rendering baked models. It only requires setting a basic texture or color to display high-quality rendering results obtained from offline rendering. However, the downside is that it cannot display real-time light and shadow interactions because Unlit rendering is determined by the texture and is not affected by any lighting. Refer to [Baking Tutorial](/en/docs/art/bake-blender) and [Export Unlit Tutorial](/en/docs/graphics/shader/builtins/unlit) | -| [Blinn Phong](/en/docs/graphics/shader/builtins/blinnPhong) | The Blinn Phong material is suitable for scenes that do not require high realism. Although it does not follow physical principles, its efficient rendering algorithm and comprehensive optical components make it suitable for many scenes. | -| [PBR](/en/docs/graphics/shader/builtins/pbr) | The PBR material is suitable for applications that require realistic rendering. Since PBR is based on physical rendering and follows energy conservation, developers can ensure that the rendering effects are physically correct by adjusting parameters such as metallicity, roughness, and lighting. | +| [Unlit](/en/docs/graphics/shader/builtins/unlit) | The Unlit Shader is suitable for rendering baked models. It only requires setting a basic texture or color to display high-quality rendering results obtained from offline rendering. However, the downside is that it cannot display real-time light and shadow interactions because Unlit rendering is determined by the texture and is not affected by any lighting. Refer to [Baking Tutorial](/en/docs/art/bake-blender) and [Export Unlit Tutorial](/en/docs/graphics/shader/builtins/unlit) | +| [Blinn Phong](/en/docs/graphics/shader/builtins/blinnPhong) | The Blinn Phong Shader is suitable for scenes that do not require high realism. Although it does not follow physical principles, its efficient rendering algorithm and comprehensive optical components make it suitable for many scenes. | +| [PBR](/en/docs/graphics/shader/builtins/pbr) | The PBR Shader is suitable for applications that require realistic rendering. Since PBR is based on physical rendering and follows energy conservation, developers can ensure that the rendering effects are physically correct by adjusting parameters such as metallicity, roughness, and lighting. | You can directly debug the corresponding properties of the built-in shaders in the editor to observe real-time rendering effect changes. diff --git a/docs/en/graphics/shader/shaderLab/syntax/pass.mdx b/docs/en/graphics/shader/shaderLab/syntax/pass.mdx index 67ea7adfc9..7d35de7c52 100644 --- a/docs/en/graphics/shader/shaderLab/syntax/pass.mdx +++ b/docs/en/graphics/shader/shaderLab/syntax/pass.mdx @@ -7,15 +7,15 @@ Pass "PassName" { Tag {PipelineStage = "ShadowCaster"} ... - // 全局变量区：公共变量声明，结构体声明，函数声明 + // Glbals ... - // 渲染管线和渲染状态设置 + // Render pipeline and render state settings - // 指定顶点着色器和片元着色器 强调glsl语言 + // Specify the entry function of shader VertexShader = vert; - // 指定渲染队列 + // Specify render queue RenderQueueType = Transparent; } ``` @@ -28,17 +28,17 @@ It can be specified in the following two ways: 1. Explicit assignment - ``` - BlendState = blendState; - ``` +``` +BlendState = blendState; +``` 2. Declaration in the global variable domain of Pass - ``` - BlendState { - Rendering state property = Property value; - } - ``` +``` +BlendState { + Rendering state property = Property value; +} +``` ## Specifying uniform Variables @@ -53,16 +53,17 @@ vec3 u_lightDir; ## Declaring varying Variables -Specify by defining the output structure of the vertex shader and the input structure of the fragment shader +Specify by defining the output [structure](/en/docs/graphics/shader/shaderLab/syntax/shader/#structs-functions) of the vertex shader and the input structure of the fragment shader ```glsl struct v2f { vec3 color; -} +}; v2f vert(a2v o) { ... } + void frag(v2f i) { ... } @@ -84,3 +85,16 @@ Specify using the `RenderQueueType` directive, which is equivalent to the engine ``` RenderQueueType = Transparent; ``` + + +In addition to setting the render state and render queue in ShaderLab, developers can also configure these settings through the material API, such as: +```ts +// Render queue setting +material.renderQueueType = RenderQueueType.Opaque; + +// Render state setting const renderState = material.renderState.depthState; depthState.writeEnabled = false; + +``` +When render states and render queues are declared in ShaderLab, the corresponding settings in the material will be ignored." + +``` diff --git a/docs/en/graphics/shader/shaderLab/syntax/shader.mdx b/docs/en/graphics/shader/shaderLab/syntax/shader.mdx index bb94b85d49..6483e22b11 100644 --- a/docs/en/graphics/shader/shaderLab/syntax/shader.mdx +++ b/docs/en/graphics/shader/shaderLab/syntax/shader.mdx @@ -5,7 +5,7 @@ title: Shader ```glsl Shader "ShaderName" { ... - // 全局变量区：变量声明，结构体声明，渲染状态声明，材质属性定义 + // Global variables ... SubShader "SubShaderName" { ... @@ -33,7 +33,7 @@ EditorProperties ... } -// 宏 +// Macro EditorMacros { [On] UV_OFFSET("UV Offset", Range(1,100)) = 10; @@ -104,7 +104,7 @@ This module is used to define the UI display of the material bound to the Shader You can declare 4 types of global variables in ShaderLab: RenderState, Structs, Functions, and Single Variables. -- RenderState +### RenderState Includes BlendState, DepthState, StencilState, RasterState @@ -180,9 +180,9 @@ You can declare 4 types of global variables in ShaderLab: RenderState, Structs, BlendState customBlendState { Enabled = true; - // 常量复制方式 + // Constant variable assignment SourceColorBlendFactor = BlendFactor.SourceColor; - // 变量赋值方式 + // Variable assignment DestinationColorBlendFactor = material_DstBlend; } ... @@ -199,11 +199,11 @@ You can declare 4 types of global variables in ShaderLab: RenderState, Structs, - Constant assignment means the right side of the assignment statement is a specified engine enum variable, e.g., BlendFactor.SourceColor. - Variable assignment means the right side of the assignment statement is any variable name. The specific value of the variable is specified by the user at runtime through the ShaderData.setInt("material_DstBlend", BlendFactor.SourceColor) API. -- Structs, Functions +### Structs, Functions Same as the syntax in GLSL. -- Single Variables +### Single Variables ```glsl [lowp/mediump/highp] variableType variableName; diff --git a/docs/zh/graphics/shader/builtins/intro.mdx b/docs/zh/graphics/shader/builtins/intro.mdx index 391ad5882b..c1d90024b0 100644 --- a/docs/zh/graphics/shader/builtins/intro.mdx +++ b/docs/zh/graphics/shader/builtins/intro.mdx @@ -2,17 +2,17 @@ title: 介绍 --- -目前Galacean引擎内置了许多常用的Shader，诸如 +目前 Galacean 引擎内置了许多常用的 Shader，诸如 | 类型 | 描述 | | :-- | :-- | -| [Unlit ](/docs/graphics/shader/builtins/unlit) | Unlit 材质适用于烘焙好的模型渲染，她只需要设置一张基本纹理或者颜色，即可展现离线渲染得到的高质量渲染结果，但是缺点是无法实时展现光影交互，因为 Unlit 由纹理决定渲染，不受任何光照影响，可参考 [烘焙教程](/docs/art/bake-blender) 和 [导出 Unlit 教程](/docs/graphics/shader/builtins/unlit) | -| [Blinn Phong ](/docs/graphics/shader/builtins/blinnPhong) | Blinn Phong 材质适用于那些对真实感没有那么高要求的场景，虽然没有遵循物理，但是其高效的渲染算法和基本齐全的光学部分，可以适用很多的场景。 | -| [PBR ](/docs/graphics/shader/builtins/pbr) | PBR 材质适合需要真实感渲染的应用场景，因为 PBR 是基于物理的渲染，遵循能量守恒，开发者通过调整金属度、粗糙度、灯光等参数，能够保证渲染效果都是物理正确的。 | +| [Unlit ](/docs/graphics/shader/builtins/unlit) | Unlit Shader 适用于烘焙好的模型渲染，她只需要设置一张基本纹理或者颜色，即可展现离线渲染得到的高质量渲染结果，但是缺点是无法实时展现光影交互，因为 Unlit 由纹理决定渲染，不受任何光照影响，可参考 [烘焙教程](/docs/art/bake-blender) 和 [导出 Unlit 教程](/docs/graphics/shader/builtins/unlit) | +| [Blinn Phong ](/docs/graphics/shader/builtins/blinnPhong) | Blinn Phong Shader 适用于那些对真实感没有那么高要求的场景，虽然没有遵循物理，但是其高效的渲染算法和基本齐全的光学部分，可以适用很多的场景。 | +| [PBR ](/docs/graphics/shader/builtins/pbr) | PBR Shader 适合需要真实感渲染的应用场景，因为 PBR 是基于物理的渲染，遵循能量守恒，开发者通过调整金属度、粗糙度、灯光等参数，能够保证渲染效果都是物理正确的。 | 可以在编辑器中直接调试内置着色器的对应属性观察实时渲染效果变化。 - + > 与之对应的，也可以通过设置 PBRMaterial , BlinnPhongMaterial 与 UnlitMaterial 材质的 API 达到相同效果。 @@ -22,4 +22,4 @@ title: 介绍 | [alphaCutoff](/apis/core/#BaseMaterial-alphaCutoff) | 透明度裁剪值。可以设置裁剪值，在着色器中，透明度小于此数值的片元将会被裁减，参考 [案例](/embed/blend-mode) | | [renderFace](/apis/core/#BaseMaterial-renderFace) | 渲染面。可以决定渲染正面、背面、双面。 | | [blendMode](/apis/core/#BaseMaterial-blendMode) | 颜色混合模式。当设置材质为透明后，可以设置此枚举来决定颜色混合模式，参考 [案例](/embed/blend-mode) | -| [tilingOffset](/apis/core/#BlinnPhongMaterial-tilingOffset) | 纹理坐标的缩放与偏移。是一个 Vector4 数据，分别控制纹理坐标在 uv 方向上的缩放和偏移，参考 [案例](/embed/tiling-offset) | \ No newline at end of file +| [tilingOffset](/apis/core/#BlinnPhongMaterial-tilingOffset) | 纹理坐标的缩放与偏移。是一个 Vector4 数据，分别控制纹理坐标在 uv 方向上的缩放和偏移，参考 [案例](/embed/tiling-offset) | diff --git a/docs/zh/graphics/shader/shaderLab/syntax/pass.mdx b/docs/zh/graphics/shader/shaderLab/syntax/pass.mdx index 16aac2f726..2f851c61fd 100644 --- a/docs/zh/graphics/shader/shaderLab/syntax/pass.mdx +++ b/docs/zh/graphics/shader/shaderLab/syntax/pass.mdx @@ -28,17 +28,17 @@ Pass "PassName" { 1. 显示赋值 - ``` - BlendState = blendState; - ``` +``` +BlendState = blendState; +``` 2. Pass 全局变量域中声明指定 - ``` - BlendState { - 渲染状态属性 = 属性值; - } - ``` +``` +BlendState { + 渲染状态属性 = 属性值; +} +``` ## uniform 变量指定 @@ -53,16 +53,17 @@ vec3 u_lightDir; ## varying 变量声明 -通过定义顶点着色器出参结构体和片元着色器入参结构体指定 +通过定义顶点着色器出参[结构体](/docs/graphics/shader/shaderLab/syntax/shader/#结构体函数)和片元着色器入参结构体指定 ```glsl struct v2f { vec3 color; -} +}; v2f vert(a2v o) { ... } + void frag(v2f i) { ... } @@ -84,3 +85,17 @@ FragmentShader = frag; ``` RenderQueueType = Transparent; ``` + + +除了可以在 ShaderLab 中对渲染状态和渲染队列进行设置，开发者同样可以通过材质的API进行设置，如 +```ts +// 渲染队列设置 +material.renderQueueType = RenderQueueType.Opaque; + +// 渲染状态设置 const renderState = material.renderState.depthState; depthState.writeEnabled = false; + +``` +当 ShaderLab 中声明了渲染状态和渲染队列，材质相应的设置会被忽略。 + + +``` diff --git a/docs/zh/graphics/shader/shaderLab/syntax/shader.mdx b/docs/zh/graphics/shader/shaderLab/syntax/shader.mdx index e147a945b0..33dde649db 100644 --- a/docs/zh/graphics/shader/shaderLab/syntax/shader.mdx +++ b/docs/zh/graphics/shader/shaderLab/syntax/shader.mdx @@ -104,109 +104,109 @@ EditorMacros 可以在 ShaderLab 中声明 4 类全局变量：渲染状态(RenderState)，结构体，函数，以及单变量。 -- 渲染状态 - - 包含混合状态(BlendState)，深度状态(DepthState)，模板状态(StencilState)，光栅化状态(RasterState) - - - BlendState - - ```glsl - BlendState { - Enabled[n]: bool; - ColorBlendOperation[n]: BlendOperation; - AlphaBlendOperation[n]: BlendOperation; - SourceColorBlendFactor[n]: BlendFactor; - SourceAlphaBlendFactor[n]: BlendFactor; - DestinationColorBlendFactor[n]: BlendFactor; - DestinationAlphaBlendFactor[n]: BlendFactor; - ColorWriteMask[n]: float // 0xffffffff - BlendColor: vec4; - AlphaToCoverage: bool; - } - ``` - - [n] 可省略，在使用 MRT 的情况下， [n] 为指定某个 MRT 渲染状态，省略为设置所有 MRT 状态，BlendOperation 和 BlendFactor 枚举等同引擎 API - - - DepthState - - ```glsl - DepthState { - Enabled: bool; - WriteEnabled: bool; - CompareFunction: CompareFunction; - } - ``` - - CompareFunction 枚举等同引擎 API - - - StencilState - - ```glsl - StencilState { - Enabled: bool; - ReferenceValue: int; - Mask: float; // 0xffffffff - WriteMask: float; // 0xffffffff - CompareFunctionFront: CompareFunction; - CompareFunctionBack: CompareFunction; - PassOperationFront: StencilOperation; - PassOperationBack: StencilOperation; - FailOperationFront: StencilOperation; - FailOperationBack: StencilOperation; - ZFailOperationFront: StencilOperation; - ZFailOperationBack: StencilOperation; - } - ``` - - CompareFunction 和 StencilOperation 举等同引擎 API - - - RasterState - - ```glsl - RasterState { - CullMode: CullMode; - DepthBias: float; - SlopeScaledDepthBias: float; - } - ``` - - CullMode 举等同引擎 API - - 在`ShaderLab`中设置`BlendState`示例: +### 渲染状态 + +包含混合状态(BlendState)，深度状态(DepthState)，模板状态(StencilState)，光栅化状态(RasterState) + +- BlendState ```glsl - Shader "Demo" { - ... - BlendState customBlendState - { - Enabled = true; - // 常量复制方式 - SourceColorBlendFactor = BlendFactor.SourceColor; - // 变量赋值方式 - DestinationColorBlendFactor = material_DstBlend; - } - ... - Pass "0" { - ... - BlendState = customBlendState; - ... - } + BlendState { + Enabled[n]: bool; + ColorBlendOperation[n]: BlendOperation; + AlphaBlendOperation[n]: BlendOperation; + SourceColorBlendFactor[n]: BlendFactor; + SourceAlphaBlendFactor[n]: BlendFactor; + DestinationColorBlendFactor[n]: BlendFactor; + DestinationAlphaBlendFactor[n]: BlendFactor; + ColorWriteMask[n]: float // 0xffffffff + BlendColor: vec4; + AlphaToCoverage: bool; + } + ``` + + [n] 可省略，在使用 MRT 的情况下， [n] 为指定某个 MRT 渲染状态，省略为设置所有 MRT 状态，BlendOperation 和 BlendFactor 枚举等同引擎 API + +- DepthState + + ```glsl + DepthState { + Enabled: bool; + WriteEnabled: bool; + CompareFunction: CompareFunction; } ``` - 上述案例中对于 BlendState 属性赋值展示了 2 种方式: *常量赋值*和*变量赋值*方式: + CompareFunction 枚举等同引擎 API - - 常量赋值指赋值语句右端为指定的对应引擎枚举变量，譬如：BlendFactor.SourceColor - - 变量赋值指赋值语句右端为任一变量名，变量具体值由用户通过脚本方式在运行时通过 ShaderData.setInt("material_DstBlend", BlendFactor.SourceColor) API 进行指定 +- StencilState -- 结构体、函数 + ```glsl + StencilState { + Enabled: bool; + ReferenceValue: int; + Mask: float; // 0xffffffff + WriteMask: float; // 0xffffffff + CompareFunctionFront: CompareFunction; + CompareFunctionBack: CompareFunction; + PassOperationFront: StencilOperation; + PassOperationBack: StencilOperation; + FailOperationFront: StencilOperation; + FailOperationBack: StencilOperation; + ZFailOperationFront: StencilOperation; + ZFailOperationBack: StencilOperation; + } + ``` - 等同 glsl 中的语法 + CompareFunction 和 StencilOperation 举等同引擎 API -- 单变量 +- RasterState ```glsl - [lowp/mediump/highp] variableType variableName; + RasterState { + CullMode: CullMode; + DepthBias: float; + SlopeScaledDepthBias: float; + } ``` -与其他编程语言类似，ShaderLab 中的全局变量也有作用域和同名覆盖原则。简单来说，ShaderLab 中的全局变量的作用范围仅限于其声明的 SubShader 或 Pass 模块内部，而同名覆盖原则指的是如果存在与 Pass 内部同名的全局变量，则 Pass 内的全局变量会覆盖 SubShader 内的同名全局变量。 \ No newline at end of file + CullMode 举等同引擎 API + +在`ShaderLab`中设置`BlendState`示例: + +```glsl +Shader "Demo" { + ... + BlendState customBlendState + { + Enabled = true; + // 常量复制方式 + SourceColorBlendFactor = BlendFactor.SourceColor; + // 变量赋值方式 + DestinationColorBlendFactor = material_DstBlend; + } + ... + Pass "0" { + ... + BlendState = customBlendState; + ... + } +} +``` + +上述案例中对于 BlendState 属性赋值展示了 2 种方式: *常量赋值*和*变量赋值*方式: + +- 常量赋值指赋值语句右端为指定的对应引擎枚举变量，譬如：BlendFactor.SourceColor +- 变量赋值指赋值语句右端为任一变量名，变量具体值由用户通过脚本方式在运行时通过 ShaderData.setInt("material_DstBlend", BlendFactor.SourceColor) API 进行指定 + +### 结构体、函数 + +等同 glsl 中的语法 + +### 单变量 + +```glsl +[lowp/mediump/highp] variableType variableName; +``` + +与其他编程语言类似，ShaderLab 中的全局变量也有作用域和同名覆盖原则。简单来说，ShaderLab 中的全局变量的作用范围仅限于其声明的 SubShader 或 Pass 模块内部，而同名覆盖原则指的是如果存在与 Pass 内部同名的全局变量，则 Pass 内的全局变量会覆盖 SubShader 内的同名全局变量。