mirror of
https://github.com/galacean/engine.git
synced 2026-05-22 17:00:49 +08:00
doc: fix mermaid syntax error
This commit is contained in:
Kbscript
@@ -20,7 +20,7 @@ The overall workflow for creating interactive projects using the editor:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Add Animation Clip --> Create Animation Controller and Import Animation Clip --> Add Animation Control Component to Play Animation
|
||||
A[Add Animation Clip] --> B[Create Animation Controller and Import Animation Clip] --> C[Add Animation Control Component to Play Animation]
|
||||
```
|
||||
|
||||
### 1. Add Animation Clip
|
||||
|
||||
@@ -13,7 +13,7 @@ In Galacean, the asset workflow typically follows these steps:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Import Assets --> Edit Assets --> Build and Export --> Distribute --> Load
|
||||
A[Import Assets] --> B[Edit Assets] --> C[Build and Export] --> Distribute --> Load
|
||||
```
|
||||
|
||||
This chapter will mainly cover:
|
||||
|
||||
@@ -17,7 +17,7 @@ The overall process of creating an interactive project using the editor:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Create Project --> Create Assets --> Build Scene --> Write Scripts --> Export
|
||||
A[Create Project] --> B[Create Assets] --> B[Build Scene] --> C[Write Scripts] --> Export
|
||||
```
|
||||
|
||||
The editor allows better collaboration between technical and artistic team members. You can quickly start the development of your first project through business templates on the [editor homepage](https://galacean.antgroup.com/editor).
|
||||
|
||||
@@ -10,7 +10,7 @@ Models typically refer to 3D models created by designers using 3D modeling softw
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Modeling software exports model --> Import model into Galacean editor --> Adjust model
|
||||
A[Modeling software exports model] --> B[Import model into Galacean editor] --> C[Adjust model]
|
||||
```
|
||||
|
||||
This chapter mainly addresses the following issues developers might encounter:
|
||||
|
||||
@@ -6,4 +6,4 @@
|
||||
"assets": { "title": "Shader Assets" },
|
||||
"shaderLab": { "title": "ShaderLab" },
|
||||
"shaderAPI": { "title": "Shader API [Experimental]" }
|
||||
}
|
||||
}
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
order: 3
|
||||
title: Blinn Phong
|
||||
type: Shader
|
||||
group: Mesh
|
||||
label: Graphics/Shader
|
||||
---
|
||||
|
||||
[BlinnPhongMaterial](/apis/core/#BlinnPhongMaterial) is not based on physical rendering, but its efficient rendering algorithm and comprehensive optical components can still be applied to many scenarios.
|
||||
|
||||
<playground src="blinn-phong.ts"></playground>
|
||||
|
||||
## Editor Usage
|
||||
|
||||
<img src="https://gw.alipayobjects.com/zos/OasisHub/eaa93827-29a4-46ad-b9d3-f179fa200c57/blinn.gif" alt="blinn" style="zoom:100%;" />
|
||||
|
||||
## Parameter Introduction
|
||||
|
||||
| Parameter | Application |
|
||||
| :---------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [baseColor](/apis/core/#BlinnPhongMaterial-baseColor) | Base color. **Base color \* Base texture = Final base color.** |
|
||||
| [baseTexture](/apis/core/#BlinnPhongMaterial-baseTexture) | Base texture. Used in conjunction with base color, it is a multiplication relationship. |
|
||||
| [specularColor](/apis/core/#BlinnPhongMaterial-specularColor) | Specular reflection color. **Specular reflection color \* Specular reflection texture = Final specular reflection color.** |
|
||||
| [specularTexture](/apis/core/#BlinnPhongMaterial-specularTexture) | Specular reflection texture. Used in conjunction with specular reflection color, it is a multiplication relationship. |
|
||||
| [normalTexture](/apis/core/#BlinnPhongMaterial-normalTexture) | Normal texture. Can set a normal texture to create a visual sense of concavity and convexity, and can also control the degree of concavity and convexity through normal intensity. |
|
||||
| [normalIntensity ](/apis/core/#BlinnPhongMaterial-normalIntensity) | Normal intensity. Used to control the degree of concavity and convexity. |
|
||||
| [emissiveColor](/apis/core/#BlinnPhongMaterial-emissiveColor) | Emissive color. **Emissive color \* Emissive texture = Final emissive color. Can render color even without lighting.** |
|
||||
| [emissiveTexture](/apis/core/#BlinnPhongMaterial-emissiveTexture) | Emissive texture. Used in conjunction with emissive color, it is a multiplication relationship. |
|
||||
| [shininess](/apis/core/#BlinnPhongMaterial-shininess) | Specular reflection coefficient. The larger the value, the more concentrated the specular reflection effect. |
|
||||
| [tilingOffset](/apis/core/#BlinnPhongMaterial-tilingOffset) | Scaling and offset of texture coordinates. It is a Vector4 data, which controls the scaling and offset of texture coordinates in the uv direction, refer to [example](/embed/tiling-offset) |
|
||||
|
||||
如果需要通过脚本使用材质，可以前往[材质的使用教程](/en/docs/graphics-material-script)。
|
||||
@@ -1,485 +0,0 @@
|
||||
---
|
||||
order: 5
|
||||
title: Shader Lab
|
||||
type: Shader
|
||||
group: Graphics/Shader
|
||||
---
|
||||
|
||||
`ShaderLab` is a Shader wrapper language designed for the Galacean engine. It allows developers to write custom Shaders using familiar [GLSL](https://www.khronos.org/files/opengles_shading_language.pdf) syntax while providing additional advanced abstractions and management features to enhance development efficiency. Through ShaderLab, developers can more conveniently define material properties, rendering configurations, and other effects. While ShaderLab introduces convenience for writing shaders, it does not replace GLSL but is compatible with it. Developers can write native GLSL code blocks within the ShaderLab framework to enjoy the advantages of both. The workflow for using ShaderLab is as follows:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Create Shader --> Edit ShaderLab --> Debug ShaderLab
|
||||
```
|
||||
|
||||
Here is a simple example of using ShaderLab, which includes two Shaders. The `normal` Shader defines a vertex shader that only implements MVP transformation and specifies a fragment shader for pixel color using Uniform variables. Additionally, the `lines` Shader is an example from [shadertoy](https://www.shadertoy.com/view/DtXfDr) transformed using ShaderLab.
|
||||
|
||||
<playground src="shader-lab-simple.ts"></playground>
|
||||
|
||||
## Create Shader
|
||||
|
||||
#### Create in Editor
|
||||
|
||||
In the editor, you can add 3 types of ShaderLab templates: Custom, `PBR`, and Shader Fragment.
|
||||
|
||||
<img src="https://mdn.alipayobjects.com/huamei_aftkdx/afts/img/A*MiW5RYzGUhwAAAAAAAAAAAAADteEAQ/original" style="zoom:50%;">
|
||||
|
||||
Among them, **Custom** and **`PBR`** are Shader templates written using ShaderLab syntax, while **Shader Fragment** is for convenient code snippet reuse. In ShaderLab, you can use the `include` macro to reference code snippets for later automatic expansion and replacement during the compilation process. See the syntax standard module for detailed usage.
|
||||
|
||||
#### Create in Script
|
||||
|
||||
Currently, `ShaderLab` is not integrated into the engine's core package. You need to pass the newly created `ShaderLab` object during engine initialization; otherwise, the engine cannot interpret Shaders written using ShaderLab syntax.
|
||||
|
||||
1. Initialize `ShaderLab`
|
||||
|
||||
```ts
|
||||
import { ShaderLab } from '@galacean/engine-shaderlab';
|
||||
|
||||
const shaderLab = new ShaderLab();
|
||||
// 使用ShaderLab初始化Engine
|
||||
const engine = await WebGLEngine.create({ canvas: 'canvas', shaderLab });
|
||||
```
|
||||
|
||||
2. Create Shader
|
||||
|
||||
```glsl
|
||||
// Create Shader directly using ShaderLab
|
||||
const shader = Shader.create(galaceanShaderCode);
|
||||
```
|
||||
|
||||
## Writing `ShaderLab`
|
||||
|
||||
### Edit Shaders in Editor
|
||||
|
||||
Double-click on the Shader asset created in the previous step to navigate to the code editing page.
|
||||
|
||||
> A Galacean VSCode plugin will be released in future versions, providing syntax checking, auto-completion, and code synchronization features for `ShaderLab`. Stay tuned.
|
||||
|
||||
<img src="https://mdn.alipayobjects.com/huamei_aftkdx/afts/img/A*Djs2RJsoPawAAAAAAAAAAAAADteEAQ/original" style="zoom:50%;">
|
||||
|
||||
### Syntax Standards
|
||||
|
||||
The syntax skeleton of `ShaderLab` is as follows, with detailed explanations and usage of each module in the following sections.
|
||||
|
||||
```glsl
|
||||
Shader "ShaderName" {
|
||||
...
|
||||
SubShader "SubShaderName" {
|
||||
...
|
||||
Pass "PassName" {
|
||||
...
|
||||
}
|
||||
...
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
#### Shader
|
||||
|
||||
```glsl
|
||||
Shader "ShaderName" {
|
||||
...
|
||||
// 全局变量区：变量声明，结构体声明，渲染状态声明，材质属性定义
|
||||
...
|
||||
SubShader "SubShaderName" {
|
||||
...
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
In ShaderLab, a `Shader` is a collection encapsulating shader programs and other engine rendering settings related information in the traditional rendering pipeline. It allows defining multiple shader programs within the same `Shader` object and instructs Galacean on how to use them during the rendering process. The `Shader` object has a nested structure containing `SubShader` and `Pass` substructures.
|
||||
|
||||
#### Material Property Definition
|
||||
|
||||
```glsl
|
||||
// Uniform
|
||||
EditorProperties
|
||||
{
|
||||
material_BaseColor("Offset unit scale", Color) = (1,1,1,1);
|
||||
...
|
||||
|
||||
Header("Emissive")
|
||||
{
|
||||
material_EmissiveColor("Emissive color", Color) = (1,1,1,1);
|
||||
...
|
||||
}
|
||||
...
|
||||
}
|
||||
|
||||
// 宏
|
||||
EditorMacros
|
||||
{
|
||||
[On] UV_OFFSET("UV Offset", Range(1,100)) = 10;
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
This module is used to define the UI display of the material bound to this Shader in the editor Inspector panel. ShaderLab material properties separate macro properties and other Uniform properties using `EditorProperties` and `EditorMacros` for declaration. The declaration format is as follows:
|
||||
|
||||
1. Uniform Properties
|
||||
|
||||
```glsl
|
||||
EditorProperties {
|
||||
propertyName("label in Inspector", type) [= defaultValue];
|
||||
...
|
||||
[ Header("blockName") {
|
||||
propertyName("label in Inspector", type) [= defaultValue];
|
||||
...
|
||||
} ]
|
||||
}
|
||||
```
|
||||
|
||||
> You can use nested `Header` blocks to categorize material properties hierarchically.
|
||||
|
||||
Supported types include
|
||||
|
||||
| Type | Example |
|
||||
| :-: | :-- |
|
||||
| Bool | propertyName("Property Description", Boolean) = true; |
|
||||
| Int | propertyName("Property Description", Int) = 1; <br/>propertyName("Property Description", Range(0,8)) = 1 |
|
||||
| Float | propertyName("Property Description", Float) = 0.5; <br/>propertyName("Property Description", Range(0.0, 1.0)) = 0.5; |
|
||||
| Texture2D | propertyName("Property Description", Texture2D); |
|
||||
| TextureCube | propertyName("Property Description", TextureCube); |
|
||||
| Color | propertyName("Property Description", Color) = (0.25, 0.5, 0.5, 1); |
|
||||
| Vector2 | propertyName("Property Description", Vector2) = (0.25, 0.5); |
|
||||
| Vector3 | propertyName("Property Description", Vector3) = (0.25, 0.5, 0.5); |
|
||||
| Vector4 | propertyName("Property Description", Vector4) = (0.25, 0.5, 0.5, 1.0); |
|
||||
|
||||
2. Macro Properties
|
||||
|
||||
```glsl
|
||||
EditorMacros {
|
||||
[\[Off/On\]] propertyName("label in Inspector"[, type]) [= defaultValue];
|
||||
...
|
||||
[ Header("blockName") {
|
||||
[\[Off/On\]] propertyName("label in Inspector"[, type]) [= defaultValue];
|
||||
...
|
||||
} ]
|
||||
}
|
||||
```
|
||||
|
||||
All include enabling and disabling functionality, initialized through the `[On/Off]` directive, with types including
|
||||
|
||||
| Type | Example |
|
||||
| :-: | :-- |
|
||||
| None (Toggle Macro) | macroName("Macro Description"); |
|
||||
| Bool | macroName("Macro Description", Boolean) = true; |
|
||||
| Int | macroName("Macro Description", Int) = 1; <br/> macroName("Macro Description", Range(0,8)) = 1; |
|
||||
| Float | macroName("Macro Description", Float) = 0.5; <br/> macroName("Macro Description", Range(0.0, 1.0)) = 0.5; |
|
||||
| Color | macroName("Macro Description", Color) = (0.25, 0.5, 0.5, 1); |
|
||||
| Vector2 | macroName("Macro Description", Vector2) = (0.25, 0.5); |
|
||||
| Vector3 | macroName("Macro Description", Vector3) = (0.25, 0.5, 0.5); |
|
||||
| Vector4 | macroName("Macro Description", Vector4) = (0.25, 0.5, 0.5, 1.0); |
|
||||
|
||||
> Note that the current version of ShaderLab material properties module only defines the Inspector UI panel for the material bound to this Shader in the editor and does not automatically declare corresponding global variables in your `ShaderPass` code. If the variable is referenced in the `ShaderPass` code, it needs to be explicitly declared and supplemented in the global variable module (see below).
|
||||
|
||||
#### Global Variables
|
||||
|
||||
Four types of global variables can be declared in ShaderLab: RenderState, structs, functions, and single variables.
|
||||
|
||||
- RenderState
|
||||
|
||||
Includes 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] can be omitted. When using MRT, [n] specifies a certain MRT rendering state. Omitting it sets all MRT states. BlendOperation and BlendFactor enumerations are equivalent to the engine API.
|
||||
|
||||
- DepthState
|
||||
|
||||
```glsl
|
||||
DepthState {
|
||||
Enabled: bool;
|
||||
WriteEnabled: bool;
|
||||
CompareFunction: CompareFunction;
|
||||
}
|
||||
```
|
||||
|
||||
CompareFunction enumeration is equivalent to the engine 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 and StencilOperation enumerations are equivalent to the engine API.
|
||||
|
||||
- RasterState
|
||||
|
||||
```glsl
|
||||
RasterState {
|
||||
CullMode: CullMode;
|
||||
DepthBias: float;
|
||||
SlopeScaledDepthBias: float;
|
||||
}
|
||||
```
|
||||
|
||||
CullMode enumeration is equivalent to the engine API.
|
||||
|
||||
Setting `BlendState` in `ShaderLab` example:
|
||||
|
||||
```glsl
|
||||
Shader "Demo" {
|
||||
...
|
||||
BlendState customBlendState
|
||||
{
|
||||
Enabled = true;
|
||||
// 常量复制方式
|
||||
SourceColorBlendFactor = BlendFactor.SourceColor;
|
||||
// 变量赋值方式
|
||||
DestinationColorBlendFactor = material_DstBlend;
|
||||
}
|
||||
...
|
||||
Pass "0" {
|
||||
...
|
||||
BlendState = customBlendState;
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The above example demonstrates two ways to assign values to the BlendState property: *constant assignment* and *variable assignment*:
|
||||
|
||||
- Constant assignment refers to assigning the corresponding engine enumeration variable on the right side of the assignment statement, such as: BlendFactor.SourceColor
|
||||
- Variable assignment refers to assigning any variable name on the right side of the assignment statement, and the specific value of the variable is specified by the user at runtime through the ShaderData.setInt("material_DstBlend", BlendFactor.SourceColor) API using a script.
|
||||
|
||||
- Structs, Functions
|
||||
|
||||
Equivalent to the syntax in glsl.
|
||||
|
||||
- Single Variable
|
||||
|
||||
```glsl
|
||||
[lowp/mediump/highp] variableType variableName;
|
||||
```
|
||||
|
||||
Similar to other programming languages, global variables in ShaderLab also have scope and name overriding rules. In ShaderLab, the scope of global variables is limited to the SubShader or Pass module in which they are declared. The name overriding rule means that if there is a global variable with the same name inside a Pass, the global variable within the Pass will override the global variable with the same name in the SubShader.
|
||||
|
||||
#### SubShader
|
||||
|
||||
```glsl
|
||||
SubShader "SubShaderName" {
|
||||
...
|
||||
// 全局变量区：变量声明，结构体声明，渲染状态声明
|
||||
...
|
||||
Tags {ReplaceTag = "opaque"}
|
||||
|
||||
UsePass "ShaderName/SubShaderName/PassName"
|
||||
|
||||
Pass "PassName" {
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A `Shader` object can contain multiple SubShaders, but at least one SubShader. It represents a specific implementation of a rendering pipeline, defining multiple implementation steps (Passes) of a rendering effect. The current SubShader can be specified by custom tags, such as `ReplaceTag`, in conjunction with [`Camera.setReplacementShader`](/apis/core/#Camera) to specify shaders that may need to be replaced.
|
||||
|
||||
- `UsePass` Directive
|
||||
|
||||
If a SubShader contains multiple Passes, you can reuse other Pass objects using the `UsePass` directive, such as the built-in PBR Pass: `UsePass "pbr/Default/Forward"`
|
||||
|
||||
| Built-in Shader | Pass Path |
|
||||
| :-------------: | :-----------------------: |
|
||||
| PBR | pbr/Default/Forward |
|
||||
| Unlit | unlit/Default/Forward |
|
||||
| Skybox | skybox/Default/Forward |
|
||||
| Particle-shader | particle-shader/Default/Forward |
|
||||
| SpriteMask | SpriteMask/Default/Forward |
|
||||
| Sprite | Sprite/Default/Forward |
|
||||
|
||||
#### Pass
|
||||
|
||||
```glsl
|
||||
Pass "PassName" {
|
||||
Tag {PipelineStage = "ShadowCaster"}
|
||||
|
||||
...
|
||||
// 全局变量区：公共变量声明，结构体声明，函数声明
|
||||
...
|
||||
|
||||
// 渲染管线和渲染状态设置
|
||||
|
||||
// 指定顶点着色器和片元着色器 强调glsl语言
|
||||
VertexShader = vert;
|
||||
|
||||
// 指定渲染队列
|
||||
RenderQueueType = RenderQueueType.Transparent;
|
||||
}
|
||||
```
|
||||
|
||||
`Pass` is the basic element of a `Shader` object. A simple shader object may only contain one Pass, but more complex shaders can contain multiple Passes. It defines the operations performed at specific stages of the rendering pipeline, such as shader programs running on the GPU, rendering states, and rendering pipeline-related settings.
|
||||
|
||||
- Rendering State Specification
|
||||
|
||||
It can be specified in two ways:
|
||||
|
||||
1. Direct assignment
|
||||
|
||||
```
|
||||
BlendState = blendState;
|
||||
```
|
||||
|
||||
|
||||
2. Pass declaration in the global variable scope
|
||||
|
||||
```
|
||||
BlendState blendState {
|
||||
RenderStateProperty = Value;
|
||||
}
|
||||
```
|
||||
|
||||
- Uniform variable specification
|
||||
|
||||
Declare directly as a global variable
|
||||
|
||||
```glsl
|
||||
mediump vec4 u_color;
|
||||
float material_AlphaCutoff;
|
||||
mat4 renderer_ModelMat;
|
||||
vec3 u_lightDir;
|
||||
```
|
||||
|
||||
- Attribute variable declaration
|
||||
|
||||
Specify through defining the structure of the vertex shader function input parameters
|
||||
|
||||
```glsl
|
||||
struct a2v {
|
||||
vec4 POSITION;
|
||||
}
|
||||
|
||||
v2f vert(a2v o) {
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
- Varying variable declaration
|
||||
|
||||
Specify through defining the structure of the vertex shader output parameters and the fragment shader input parameters
|
||||
|
||||
```glsl
|
||||
struct v2f {
|
||||
vec3 color;
|
||||
}
|
||||
|
||||
v2f vert(a2v o) {
|
||||
...
|
||||
}
|
||||
void frag(v2f i) {
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
- Vertex and fragment shader specification
|
||||
|
||||
Specify the shader entry functions explicitly through `VertexShader` and `FragmentShader`
|
||||
|
||||
```
|
||||
VertexShader = vert;
|
||||
FragmentShader = frag;
|
||||
```
|
||||
|
||||
- Render queue setting
|
||||
|
||||
Specify through the `RenderQueueType` directive, where `RenderQueueType` is equivalent to the engine API.
|
||||
|
||||
```
|
||||
RenderQueueType = RenderQueueType.Transparent;
|
||||
```
|
||||
|
||||
#### `include` macro
|
||||
|
||||
For code reuse convenience, in ShaderLab, you can use the `include` macro as shown below for code snippet references, which will be automatically expanded and replaced during the subsequent compilation process.
|
||||
|
||||
```glsl
|
||||
#include "{includeKey}"
|
||||
```
|
||||
|
||||
To enable code snippets to be referenced through the `include` macro, we have 2 ways to declare code snippets:
|
||||
|
||||
1. Create shaders / shader fragments in the editor
|
||||
|
||||
The `includeKey` of the created code snippet is the file path in the project, such as `/Root/Effect.glsl`
|
||||
|
||||
2. Explicitly register code snippets in scripts
|
||||
|
||||
```ts
|
||||
import { ShaderFactory } from '@galacean/engine';
|
||||
|
||||
const commonSource = `// shader chunk`;
|
||||
ShaderFactory.registerInclude('includeKey', commonSource);
|
||||
```
|
||||
|
||||
#### Unsupported GLSL syntax formats currently
|
||||
|
||||
1. The 0 before and after the decimal point in floating-point numbers cannot be omitted
|
||||
|
||||
- ❌ `float n = 1. + .9;`
|
||||
- ✅ `float n = 1.0 + 0.9;`
|
||||
|
||||
2. When assigning a function call return value as a property in a variable assignment statement, the function call needs to be enclosed in parentheses
|
||||
|
||||
- ❌ `float a3 = texture2D(u_texture, (p.xy * 0.4 + um) * u_water_scale).x;`
|
||||
- ✅ `float a3 = (texture2D(u_texture, (p.xy * 0.4 + um) * u_water_scale)).x;`
|
||||
|
||||
3. If / for conditional statements should not omit "{}" when there is only one line of code after the statement
|
||||
|
||||
- ❌
|
||||
```
|
||||
if(dis < EPS || dis > MAX_DIS)
|
||||
break;
|
||||
```
|
||||
- ✅
|
||||
```
|
||||
if(dis < EPS || dis > MAX_DIS) {
|
||||
break;
|
||||
}
|
||||
```
|
||||
|
||||
## Material binding shader
|
||||
|
||||
After creating custom shader assets using `ShaderLab`, we can achieve user-defined materials by binding the shader to a newly created material.
|
||||
|
||||
<img src="https://mdn.alipayobjects.com/huamei_aftkdx/afts/img/A*tVDOTq0ms2gAAAAAAAAAAAAADteEAQ/original" style="zoom:50%;">
|
||||
|
||||
- Reflecting material properties in `ShaderLab`
|
||||
|
||||
If we write a `Material Property Definition` module in `ShaderLab`, the properties defined in the module will be exposed in the Inspector panel of the material asset bound with this shader
|
||||
|
||||
<img src="https://mdn.alipayobjects.com/huamei_aftkdx/afts/img/A*38UISKqK2WUAAAAAAAAAAAAADteEAQ/original" style="zoom:50%">
|
||||
|
||||
## An example of implementing planar shadows using multi-pass technique
|
||||
|
||||
<playground src="shader-lab.ts"></playground>
|
||||
|
||||
@@ -1,72 +0,0 @@
|
||||
---
|
||||
order: 1
|
||||
title: PBR
|
||||
type: Shader
|
||||
group: Mesh
|
||||
label: Graphics/Shader
|
||||
---
|
||||
|
||||
PBR stands for **Physically Based Rendering**, which means **Physically Based Rendering** in Chinese. It was first proposed by Disney in 2012 and later widely used in the gaming industry. Compared to traditional rendering methods like **Blinn-Phong**, PBR follows energy conservation, adheres to physical rules, and allows artists to achieve correct rendering effects even in complex scenes by adjusting a few simple parameters. PBR, based on physical rendering, introduces [IBL](/en/docs/graphics-light-ambient) to simulate global illumination, making it easier to adjust rendering effects through parameters such as metallicness and roughness.
|
||||
|
||||
<playground src="pbr-base.ts"></playground>
|
||||
|
||||
## Editor Usage
|
||||
|
||||
Based on the interaction between light and materials in the real world, insulators (i.e., when metallicness is 0) can still reflect about 4% of pure light, rendering the surrounding environment. In the model below, the metallicness is 0, but you can still vaguely see the reflection of the surrounding environment:
|
||||
|
||||
<img src="https://gw.alipayobjects.com/zos/OasisHub/1017d75b-03a3-4c06-8971-524544373429/image-20231007153753006.png" alt="image-20231007153753006" style="zoom:50%;" />
|
||||
|
||||
By adjusting the metallicness of the material, you can observe that the higher the metallicness, the clearer the surrounding environment becomes, and it transitions from white pure color to colored. This is because dielectric materials (i.e., when metallicness is 1) reflect all light 100% from the object's surface, resulting in a colored reflection of the surrounding environment:
|
||||
|
||||
<img src="https://gw.alipayobjects.com/zos/OasisHub/711f8b97-247c-465e-8cf2-4896b0c78534/metal.gif" alt="metal" style="zoom:100%;" />
|
||||
|
||||
In addition, there are many common properties that can be configured, such as anisotropy, roughness, ambient occlusion, emissive light, transparency, and more:
|
||||
|
||||
<img src="https://gw.alipayobjects.com/zos/OasisHub/2c8dde75-9557-41db-a1d0-6ca9352530e4/material-anisotropy.gif" alt="material-anisotropy" style="zoom:100%;" />
|
||||
|
||||
<img src="https://gw.alipayobjects.com/zos/OasisHub/4806589e-386f-404a-82e5-d273e98b707d/other.gif" alt="other" style="zoom:100%;" />
|
||||
|
||||
## Parameter Introduction
|
||||
|
||||
| Parameter | Application |
|
||||
| :-- | :-- |
|
||||
| [metallic](/apis/core/#PBRMaterial-metallic) | Metallicness. Simulates the material's degree of metallicity. A higher metallic value results in stronger specular reflection, reflecting more of the surrounding environment. |
|
||||
| [roughness](/apis/core/#PBRMaterial-roughness) | Roughness. Simulates the material's roughness. A higher roughness value makes the microsurface less smooth, resulting in a blurry specular reflection. |
|
||||
| [roughnessMetallicTexture](/apis/core/#PBRMaterial-roughnessMetallicTexture) | Metallic roughness texture. Used in conjunction with metallic roughness, it is a multiplication relationship. |
|
||||
| [baseColor](/apis/core/#PBRBaseMaterial-baseColor) | Base color. **Base color** \* **Base color texture** = **Final base color**. The base color is the object's albedo value, different from traditional diffuse colors, as it contributes to both specular and diffuse colors. We can control the contribution ratio through the aforementioned metallicness and roughness. |
|
||||
| [emissiveColor](/apis/core/#PBRBaseMaterial-emissiveColor) | Emissive color. Allows rendering of color even without lighting. |
|
||||
| [baseTexture](/apis/core/#PBRBaseMaterial-baseTexture) | Base color texture. Used in conjunction with the base color, it is a multiplication relationship. |
|
||||
| [normalTexture](/apis/core/#PBRBaseMaterial-normalTexture) | Normal texture. Can be set to create a visual bump effect and control the bump intensity through the normal strength. |
|
||||
| [emissiveTexture](/apis/core/#PBRBaseMaterial-emissiveTexture) | Emissive texture. By setting an emissive texture and emissive color ([emissiveFactor](/apis/core/#PBRBaseMaterial-emissiveTexture})), an emissive effect can be achieved, rendering color even without lighting. |
|
||||
| [occlusionTexture](/apis/core/#PBRBaseMaterial-occlusionTexture) | Occlusion texture. Enhances object shadow details by setting an occlusion texture. |
|
||||
| [tilingOffset](/apis/core/#PBRBaseMaterial-tilingOffset) | Texture coordinate scaling and offset. A Vector4 data that controls the scaling and offset of texture coordinates in the UV direction, refer to the [example](/embed/tiling-offset). |
|
||||
| [clearCoat](/apis/core/#PBRBaseMaterial-clearCoat) | Strength of the clear coat, default is 0, which means the clear coat effect is not enabled, refer to the [example](/embed/pbr-clearcoat). |
|
||||
| [clearCoatTexture](/apis/core/#PBRBaseMaterial-clearCoatTexture) | Clear coat strength texture, multiplied with clear coat. |
|
||||
| [clearCoatRoughness](/apis/core/#PBRBaseMaterial-clearCoatRoughness) | Roughness of the clear coat. |
|
||||
| [clearCoatRoughnessTexture](/apis/core/#PBRBaseMaterial-clearCoatRoughnessTexture) | Clear coat roughness texture, multiplied with clear coat roughness. |
|
||||
| [clearCoatNormalTexture](/apis/core/#PBRBaseMaterial-clearCoatNormalTexture) | Clear coat normal texture. If not set, it will share the original material's normal. |
|
||||
|
||||
In addition to the above common parameters, PBR provides two workflows: **Metal-Roughness** and **Specular-Glossiness**, corresponding to [PBRMaterial](/apis/core/#PBRMaterial) and [PBRSpecularMaterial](/apis/core/#PBRSpecularMaterial), respectively.
|
||||
|
||||
### PBRMaterial
|
||||
|
||||
| Parameter | Description |
|
||||
| :-- | :-- |
|
||||
| [metallic](/apis/core/#PBRMaterial-metallic) | Metallic. Simulates the metallicity of the material. The higher the metallic value, the stronger the specular reflection, reflecting more of the surrounding environment. |
|
||||
| [roughness](/apis/core/#PBRMaterial-roughness) | Roughness. Simulates the roughness of the material. The higher the roughness value, the more uneven the microsurface, resulting in a blurry specular reflection. |
|
||||
| [roughnessMetallicTexture](/apis/core/#PBRMaterial-roughnessMetallicTexture) | Metallic Roughness Texture. Used in conjunction with metallic roughness, it is a multiplication relationship. |
|
||||
| [anisotropy](/apis/core/#PBRMaterial-anisotropy) | Anisotropy Strength. Default is 0, disabling anisotropic calculations. Refer to [example](/embed/pbr-anisotropy). |
|
||||
| [anisotropyRotation](/apis/core/#PBRMaterial-anisotropyRotation) | Anisotropy Rotation Angle. Rotate along the tangent and bitangent space by the corresponding angle. |
|
||||
| [anisotropyTexture](/apis/core/#PBRMaterial-anisotropyTexture) | Anisotropy Texture. The RG channels store the anisotropic direction, which will be multiplied by the result of anisotropyRotation; the B channel stores the anisotropic strength, which will be multiplied by anisotropy. |
|
||||
|
||||
### PBRSpecularMaterial
|
||||
|
||||
| Parameter | Description |
|
||||
| :-- | :-- |
|
||||
| [specularColor](/apis/core/#PBRMaterial-specularColor) | Specular Color. Unlike the metal roughness workflow, which calculates specular reflection based on metallicity and base color, this directly uses specular color to represent the specular reflection color. (Note: Only effective when the metal roughness workflow is disabled). |
|
||||
| [glossiness](/apis/core/#PBRMaterial-glossiness) | Glossiness. Simulates the smoothness, opposite to roughness. (Note: Only effective when the metal roughness workflow is disabled). |
|
||||
| [specularGlossinessTexture](/apis/core/#PBRMaterial-specularGlossinessTexture) | Specular Glossiness Texture. Used in conjunction with specular glossiness, it is a multiplication relationship. |
|
||||
|
||||
> **Note**: PBR must enable [ambient light](/en/docs/graphics-light-ambient).
|
||||
|
||||
If you need to use materials through scripts, you can refer to the [material usage tutorial](/en/docs/graphics-material-script).
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
order: 0
|
||||
title: Shader Overview
|
||||
type: Shader
|
||||
group: Mesh
|
||||
label: Graphics/Shader
|
||||
---
|
||||
|
||||
As mentioned in the [Material Tutorial](/en/docs/graphics-material-composition), shaders can write vertex and fragment code to determine the color of pixels rendered to the screen.
|
||||
|
||||
<img src="https://gw.alipayobjects.com/zos/OasisHub/a3f74864-241e-4cd8-9ad4-733c2a0b2cc2/image-20240206153815596.png" alt="image-20240206153815596" style="zoom:50%;" />
|
||||
|
||||
This section contains the following relevant information:
|
||||
|
||||
- Built-in Shaders
|
||||
- [PBR](/en/docs/graphics-shader-pbr)
|
||||
- [Unlit](/en/docs/graphics-shader-unlit)
|
||||
- [Blinn Phong](/en/docs/graphics-shader-blinnPhong)
|
||||
- [Custom Shaders](/en/docs/graphics-shader-custom)
|
||||
- [Shader Lab](/en/docs/graphics-shader-lab)
|
||||
|
||||
## Built-in Shaders
|
||||
|
||||
| Type | Description |
|
||||
| :-- | :-- |
|
||||
| [Unlit ](/en/docs/graphics-material-Unlit) | Unlit material is suitable for rendering pre-baked models. It only requires setting a basic texture or color to display high-quality rendering results obtained offline. However, the drawback is that it cannot show real-time lighting interactions because Unlit rendering is determined by textures and is not affected by any lighting. Refer to [Baking Tutorial](/en/docs/graphics-bake-blender) and [Export Unlit Tutorial](/en/docs/graphics-material-Unlit) for more information. |
|
||||
| [Blinn Phong ](/en/docs/graphics-material-BlinnPhong) | Blinn Phong material is suitable for scenes that do not require a high level of realism. Although it does not follow physics, its efficient rendering algorithm and basic optical components make it suitable for many scenarios. |
|
||||
| [PBR ](/en/docs/graphics-material-PBR) | PBR material is suitable for applications that require realistic rendering because PBR is based on physical rendering, following energy conservation. By adjusting parameters such as metalness, roughness, and lighting, developers can ensure that the rendering effects are physically accurate. |
|
||||
|
||||
The following properties can be directly used in built-in shaders.
|
||||
|
||||
<img src="https://gw.alipayobjects.com/zos/OasisHub/94cf8176-569d-4605-bd73-967b03316c3d/image-20240206173751409.png" alt="image-20240206173751409" style="zoom:50%;" />
|
||||
|
||||
| Parameter | Application |
|
||||
| :-- | :-- |
|
||||
| [isTransparent](/apis/core/#BaseMaterial-isTransparent) | Transparency. It can be used to set whether the material is transparent. If set to transparent, you can use [BlendMode](/apis/core/#BaseMaterial-blendMode) to set the color blending mode. |
|
||||
| [alphaCutoff](/apis/core/#BaseMaterial-alphaCutoff) | Alpha cutoff value. It can be used to set a cutoff value, where fragments with transparency lower than this value will be clipped. Refer to the [example](/embed/blend-mode) |
|
||||
| [renderFace](/apis/core/#BaseMaterial-renderFace) | Render face. It can determine whether to render the front face, back face, or both faces. |
|
||||
| [blendMode](/apis/core/#BaseMaterial-blendMode) | Color blending mode. When the material is set to transparent, this enum can be used to determine the color blending mode. Refer to the [example](/embed/blend-mode) |
|
||||
| [tilingOffset](/apis/core/#BlinnPhongMaterial-tilingOffset) | Scale and offset of texture coordinates. It is a Vector4 data that controls the scaling and offset of texture coordinates in the UV direction. Refer to the [example](/embed/tiling-offset) |
|
||||
6
docs/en/graphics/shader/shaderLab/_meta.json
Normal file
6
docs/en/graphics/shader/shaderLab/_meta.json
Normal file
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"intro": "Introduction",
|
||||
"create": "Create",
|
||||
"syntax": "Syntax",
|
||||
"usage": "Usage"
|
||||
}
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: ShaderLab
|
||||
title: Introduction
|
||||
---
|
||||
|
||||
> In the [Custom Shader](/en/docs/graphics/shader/custom/) section, we learned how to create custom Shaders using the native WebGL GLSL language. In this section, we will introduce another way to create Shaders --- ShaderLab.
|
||||
@@ -10,7 +10,7 @@ Although ShaderLab introduces convenience for writing shaders, it does not repla
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Create Shader --> Edit shaderlab --> Debug shaderlab
|
||||
A[Create Shader] --> B[Edit shaderlab] --> C[Debug shaderlab]
|
||||
```
|
||||
|
||||
Below is a simple example of using ShaderLab, which includes two Shaders. The `normal` Shader defines a vertex shader that only implements MVP transformation and a fragment shader that specifies the pixel color through a Uniform variable. Additionally, the `lines` Shader is a [shadertoy](https://www.shadertoy.com/view/DtXfDr) example modified using ShaderLab.
|
||||
|
||||
@@ -1,69 +0,0 @@
|
||||
---
|
||||
order: 2
|
||||
title: Unlit
|
||||
type: Shader
|
||||
group: Mesh
|
||||
label: Graphics/Shader
|
||||
---
|
||||
|
||||
In some simple scenarios, you may not want to calculate lighting. The engine provides [UnlitMaterial](/apis/core/#UnlitMaterial), which uses the most minimal shader code and only requires providing color or texture to render. Unlit material is suitable for rendering pre-baked models. It only needs to set a basic texture or color to display the high-quality rendering results obtained from offline rendering. However, the drawback is that it cannot show real-time light and shadow interactions because Unlit rendering is determined by textures and is not affected by any lighting.
|
||||
|
||||
<playground src="unlit-material.ts"></playground>
|
||||
|
||||
## Editor Usage
|
||||
|
||||
<img src="https://gw.alipayobjects.com/zos/OasisHub/6be78a08-3075-4cd1-8cad-9757fc34f695/unlit.gif" alt="unlit" style="zoom:100%;" />
|
||||
|
||||
## Parameter Introduction
|
||||
|
||||
| Parameter | Application |
|
||||
| :-- | :-- |
|
||||
| [baseColor](/apis/core/#UnlitMaterial-baseColor) | Base color. **Base color \* Base color texture = Final color.** |
|
||||
| [baseTexture](/apis/core/#UnlitMaterial-baseTexture) | Base texture. Used in conjunction with the base color, it is a multiplication relationship. |
|
||||
| [tilingOffset](/apis/core/#UnlitMaterial-tilingOffset) | Scaling and offset of texture coordinates. It is a Vector4 data that controls the scaling and offset of texture coordinates in the UV direction. Refer to the [example](/embed/tiling-offset) |
|
||||
|
||||
If you need to use the material through scripts, you can refer to the [tutorial on using materials](/en/docs/graphics-material-script).
|
||||
|
||||
## Exporting Unlit Material in Blender
|
||||
|
||||
As mentioned in the [baking tutorial](/en/docs/graphics-bake-blender), if you have already created baked textures and want a **convenient material** where the color is only influenced by the baked texture without adding lights, debugging normals, or fine-tuning high-level properties like metal roughness, you can try Galacean's [UnlitMaterial](/apis/core/#UnlitMaterial). glTF has a dedicated [KHR_materials_unlit](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_materials_unlit) plugin, and Galacean will parse the plugin to generate Unlit materials.
|
||||
|
||||
<img src="https://gw.alipayobjects.com/zos/OasisHub/39965fc2-3fc2-44b9-a294-a04eb4441120/1623652741734-090284d5-9b1a-4db8-9231-dc3f4d188a38-20210614150743080.png" alt="image.png" style="zoom:50%;" />
|
||||
|
||||
Test model: [TREX.zip](https://www.yuque.com/attachments/yuque/0/2021/zip/381718/1623651429048-7f6a3610-d5cb-4a73-97f5-0d37d0c63b2c.zip?_lake_card=%7B%22src%22%3A%22https%3A%2F%2Fwww.yuque.com%2Fattachments%2Fyuque%2F0%2F2021%2Fzip%2F381718%2F1623651429048-7f6a3610-d5cb-4a73-97f5-0d37d0c63b2c.zip%22%2C%22name%22%3A%22TREX.zip%22%2C%22size%22%3A499161%2C%22type%22%3A%22application%2Fx-zip-compressed%22%2C%22ext%22%3A%22zip%22%2C%22status%22%3A%22done%22%2C%22taskId%22%3A%22u458bcbec-d647-4328-8036-3d5eb12860f%22%2C%22taskType%22%3A%22upload%22%2C%22id%22%3A%22ua8a5baad%22%2C%22card%22%3A%22file%22%7D)
|
||||
|
||||
Next, we will explain how to export a glTF file with the unlit plugin using Blender software.
|
||||
|
||||
1. Import Model
|
||||
|
||||
|
||||
|
||||
2. Modify Shader
|
||||
|
||||
The default shader type is BSDF, we need to change the shader type in the material properties panel from **surface** to **Background**.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
3. Add Baked Texture
|
||||
|
||||
Add the baked texture, connect Color and Shader together.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
4. Export glTF
|
||||
|
||||
If the preview is correct, export as glTF.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Drag the exported glTF file into the editor or [glTF Viewer](https://galacean.antgroup.com/#/gltf-viewer), if the material type is **UnlitMaterial**, it means that the glTF has been exported with the [KHR_materials_unlit](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_materials_unlit) plugin, and Galacean has parsed it into an Unlit material.
|
||||
|
||||
|
||||
@@ -87,7 +87,7 @@ Touch callbacks are implemented based on raycasting. Customizing raycasting is a
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Add Collider Component --> Get Touch Point --> Get Ray from Canvas Coordinates --> Raycasting
|
||||
A[Add Collider Component] --> B[Get Touch Point] --> C[Get Ray from Canvas Coordinates] --> Raycasting
|
||||
```
|
||||
|
||||
Refer to [Collider Component](/en/docs/physics/collider/) for adding a collider component. The code logic for implementing the detection part is as follows:
|
||||
|
||||
@@ -13,7 +13,7 @@ The process for developing XR interactions in the editor is as follows:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Create Project --> Add XR Node --> Add XR Capabilities --> Preview --> Export
|
||||
A[Create Project] --> B[Add XR Node] --> C[Add XR Capabilities] --> D[Preview] --> E[Export]
|
||||
```
|
||||
|
||||
### Create Project
|
||||
|
||||
@@ -9,7 +9,7 @@ The process of developing XR interaction is as follows:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Create XR Project --> Edit Project --> Export --> Local Build --> PC Preview --> XR Device Preview --> Formal Release
|
||||
A[Create XR Project] --> B[Edit Project] --> C[Export] --> D[Local Build] --> E[PC Preview] --> F[XR Device Preview] --> G[Formal Release]
|
||||
```
|
||||
|
||||
The editing process of the project is no different from other projects. This article will take the XR template as an example, focusing on the difficulties of XR projects, **Local Build**, **PC Preview**, and **XR Device Preview**.
|
||||
|
||||
@@ -8,7 +8,7 @@ title: ShaderLab 语法标准
|
||||
|
||||
> 未来版本会推出 Galacean VSCode 插件，该插件会为`ShaderLab`提供语法检测和自动补全功能以及代码同步功能，敬请期待
|
||||
|
||||
<Image src="https://mdn.alipayobjects.com/huamei_aftkdx/afts/img/A*Djs2RJsoPawAAAAAAAAAAAAADteEAQ/original" style={{zoom:"50%"}}/>
|
||||
<Image src="https://mdn.alipayobjects.com/huamei_aftkdx/afts/img/A*Djs2RJsoPawAAAAAAAAAAAAADteEAQ/original" style={{zoom:"50%"}}/>
|
||||
|
||||
## 语法标准
|
||||
|
||||
|
||||
Reference in New Issue
Block a user