You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> This article will detail the considerations for upgrading Cocos Creator 3.0 materials to v3.1.
4
+
5
+
## 1. Shader upgrades and changes
6
+
7
+
### 1.1 Built-in header file changes
8
+
9
+
The standard shader header `shading-standard` from v3.0 has become `standard-surface-entry` from v3.1, making the effect compatible with both the forward render pipeline and the deferred render pipeline.
10
+
11
+
The `cc-fog` header file from v3.0 is now `cc-fog-vs/fs` from v3.1, split into vertex shader and fragment shader versions.
12
+
13
+
### 1.2 Vertex shaders
14
+
15
+
-`gl_Position`
16
+
17
+
The main function name of `VS` in v3.1 has been changed from `vert` to `main`, and a new macro `gl_Position` has been added to assign a value to the return value.
18
+
19
+
```c
20
+
CCProgram standard-vs %{
21
+
precision highp float;
22
+
23
+
// Include your headfile
24
+
25
+
#include <cc-fog-vs> // Note the change in the header file name here
26
+
27
+
// Fill in your data here
28
+
29
+
void main () {
30
+
31
+
// Fill in your data here
32
+
33
+
gl_Position = fill in your data result;
34
+
}
35
+
}%
36
+
```
37
+
38
+
### 1.3 Fragment shaders
39
+
40
+
-`CC_STANDARD_SURFACE_ENTRY()`
41
+
42
+
Load the standard shader header file `standard-surface-entry` and use the v3.1 standard shader output function `CC_STANDARD_SURFACE_ENTRY()` to replace the original v3.0 shader output function `frag()`.
43
+
44
+
```c
45
+
CCProgram standard-fs %{
46
+
47
+
// Include your headfile
48
+
49
+
#include <cc-fog-fs> // Note the change in the header file name here
50
+
#include <standard-surface-entry> // Note the change in the name of the standard shader header file here
51
+
52
+
// Fill in your data here
53
+
54
+
void surf (out StandardSurface s) {
55
+
56
+
// Fill in your data here
57
+
58
+
}
59
+
CC_STANDARD_SURFACE_ENTRY() // Standard shader output function
60
+
}%
61
+
```
62
+
63
+
## 2. Deferred Rendering Pipeline
64
+
65
+
### 2.1 Deferred Rendering Pipeline
66
+
67
+
The biggest difference between v3.1 and v3.0 is that v3.1 supports the deferred render pipeline. The engine comes with a standard `standard-surface-entry` header file that supports both the forward render pipeline and the deferred render pipeline, which is used as follows:
68
+
69
+
```c
70
+
CCEffect %{
71
+
techniques:
72
+
73
+
// Fill in your data here
74
+
75
+
- &deferred
76
+
vert: // your Vertex shader
77
+
frag: // your Fragment shader
78
+
phase: deferred
79
+
propertyIndex: 0
80
+
blendState:
81
+
targets: // turn off blending
82
+
- blend: false
83
+
- blend: false
84
+
- blend: false
85
+
- blend: false
86
+
properties: // your properties name
87
+
88
+
// Fill in your data here
89
+
90
+
}%
91
+
92
+
// fill in your data here
93
+
94
+
CCProgram standard-fs %{
95
+
precision highp float;
96
+
#include <cc-global>
97
+
#include <shared-ubos>
98
+
#include <cc-fog-fs> // Note the change in the header file name here.
99
+
#include <standard-surface-entry> // Note the change in the name of the standard shader header file here
100
+
101
+
// Fill in your data here
102
+
void surf (out StandardSurface s) {
103
+
104
+
// Fill in your data here
105
+
106
+
}
107
+
CC_STANDARD_SURFACE_ENTRY() // Standard shader output function
108
+
}%
109
+
110
+
// fill in your data here
111
+
112
+
```
113
+
114
+
### 2.2 Render pipeline determination
115
+
116
+
The header file `standard-surface-entry` determines which render pipeline is selected, and the lighting calculation is in the file `shading-standard-additive`.
117
+
118
+
If it is a deferred render pipeline, the `deferred-lighting` effect file is called first, followed by the light calculation file `shading-standard-additive`.
119
+
120
+
```c
121
+
#defineCC_STANDARD_SURFACE_ENTRY()
122
+
#if CC_FORWARD_ADD
123
+
#include <shading-standard-additive>
124
+
125
+
// Fill in your data here
126
+
127
+
#elif CC_PIPELINE_TYPE == CC_PIPELINE_TYPE_FORWARD // Determine if it is the forward render pipeline
128
+
129
+
// Fill in your data here
130
+
131
+
#elif CC_PIPELINE_TYPE == CC_PIPELINE_TYPE_DEFERRED // Determine if it is the deferred render pipeline
132
+
133
+
// Fill in your data here
134
+
135
+
#endif
136
+
```
137
+
138
+
## 3. Parameter transfer upgrade
139
+
140
+
The macro for passing shadow parameters from vertex shaders to fragment shaders was originally `CCPassShadowParams` in v3.0, but was changed to `CC_TRANSFER_SHADOW` in v3.1.
141
+
142
+
The v3.1 vertex shader transfers `FOG` parameters to the fragment shader, using the `CC_TRANSFER_FOG` macro directly.
Copy file name to clipboardexpand all lines: en/material-system/overview.md
+9
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,14 @@
1
1
# Material System Overview
2
2
3
+
## Material System Upgrade Guide
4
+
5
+
Cocos Creator has supported the material system since v2.x. Since then, the design of the material system and the built-in Shader API are continually being improved, there may be some adjustments in the upgrade from v2.x to v3.0 and subsequent upgrades. The Effect asset does not currently support automatic upgrades, so please refer to the following documentation to upgrade:
6
+
7
+
-[v2.x to v3.0 Material Upgrade Guide](./effect-2.x-to-3.0.md)
8
+
-[v3.0 to v3.1 Material Upgrade Guide](./Material-upgrade-documentation-for-v3.0-to-v3.1.md)
9
+
10
+
## Material System Class Diagram
11
+
3
12
The material system plays an essential role in any game engine infrastructure, it controls the way everything is drawn on screen and much more.
4
13
5
14
The general structure of the system is as follows:
0 commit comments