着色语言

简介

Godot使用类似于GLSL ES 3.0的着色语言。 支持大多数数据类型和函数,并且可能会随着时间的推移添加少数几种类型和函数。

如果您已经熟悉GLSL,:ref:`Godot着色器迁移指南<doc_migrating_to_godot_shader_language>`是一个帮助您从常规GLSL转换到Godot着色语言的资源。

数据类型

支持大多数GLSL ES 3.0数据类型:

类型

描述

void

Void数据类型,只对不返回任何内容的函数有用。

bool

布尔数据类型,只能包含“true”或“false”。

bvec2

Two-component vector of booleans.

bvec3

Three-component vector of booleans.

bvec4

Four-component vector of booleans.

int

签名标量整数。

ivec2

Two-component vector of signed integers.

ivec3

Three-component vector of signed integers.

ivec4

Four-component vector of signed integers.

uint

Unsigned scalar integer; can't contain negative numbers.

uvec2

Two-component vector of unsigned integers.

uvec3

Three-component vector of unsigned integers.

uvec4

Four-component vector of unsigned integers.

float

Floating-point scalar.

vec2

Two-component vector of floating-point values.

vec3

Three-component vector of floating-point values.

vec4

Four-component vector of floating-point values.

mat2

2x2矩阵,按主要顺序排列。

mat3

3x3矩阵,在列的主要顺序。

mat4

4x4矩阵,按主要顺序排列。

sampler2D

Sampler type for binding 2D textures, which are read as float.

isampler2D

用于绑定2D纹理的采样器类型,它们被读取为有符号整数。

usampler2D

用于绑定2D纹理的采样器类型,读取为无符号整数。

sampler2DArray

Sampler type for binding 2D texture arrays, which are read as float.

isampler2DArray

Sampler type for binding 2D texture arrays, which are read as signed integer.

usampler2DArray

Sampler type for binding 2D texture arrays, which are read as unsigned integer.

sampler3D

Sampler type for binding 3D textures, which are read as float.

isampler3D

Sampler type for binding 3D textures, which are read as signed integer.

usampler3D

Sampler type for binding 3D textures, which are read as unsigned integer.

samplerCube

用于绑定Cubemaps的采样器类型,读取为浮点数。

转换

就像GLSL ES 3.0一样,不允许在标量和相同大小但不同类型的向量之间进行隐式转换。 也不允许铸造不同大小的类型。 转换必须通过构造函数明确完成。

示例:

float a = 2; // invalid
float a = 2.0; // valid
float a = float(2); // valid

默认整数常量是有符号的,所以转换为无符号总是需要强制类型转换:

int a = 2; // valid
uint a = 2; // invalid
uint a = uint(2); // valid

成员

Individual scalar members of vector types are accessed via the "x", "y", "z" and "w" members. Alternatively, using "r", "g", "b" and "a" also works and is equivalent. Use whatever fits best for your needs.

For matrices, use the m[row][column] indexing syntax to access each scalar, or m[idx] to access a vector by row index. For example, for accessing the y position of an object in a mat4 you use m[3][1].

建设

向量类型的构造必须始终通过:

// The required amount of scalars
vec4 a = vec4(0.0, 1.0, 2.0, 3.0);
// Complementary vectors and/or scalars
vec4 a = vec4(vec2(0.0, 1.0), vec2(2.0, 3.0));
vec4 a = vec4(vec3(0.0, 1.0, 2.0), 3.0);
// A single scalar for the whole vector
vec4 a = vec4(0.0);

Construction of matrix types requires vectors of the same dimension as the matrix. You can also build a diagonal matrix using matx(float) syntax. Accordingly, mat4(1.0) is an identity matrix.

mat2 m2 = mat2(vec2(1.0, 0.0), vec2(0.0, 1.0));
mat3 m3 = mat3(vec3(1.0, 0.0, 0.0), vec3(0.0, 1.0, 0.0), vec3(0.0, 0.0, 1.0));
mat4 identity = mat4(1.0);

Matrices can also be built from a matrix of another dimension. There are two rules : If a larger matrix is constructed from a smaller matrix, the additional rows and columns are set to the values they would have in an identity matrix. If a smaller matrix is constructed from a larger matrix, the top, left submatrix of the larger matrix is used.

mat3 basis = mat3(WORLD_MATRIX);
mat4 m4 = mat4(basis);
mat2 m2 = mat2(m4);

混写

It is possible to obtain any combination of components in any order, as long as the result is another vector type (or scalar). This is easier shown than explained:

vec4 a = vec4(0.0, 1.0, 2.0, 3.0);
vec3 b = a.rgb; // Creates a vec3 with vec4 components.
vec3 b = a.ggg; // Also valid; creates a vec3 and fills it with a single vec4 component.
vec3 b = a.bgr; // Order does not matter.
vec3 b = a.xyz; // Also rgba, xyzw are equivalent.
vec3 b = a.stp; // And stpq (for texture coordinates).
float c = b.w; // Invalid, because "w" is not present in vec3 b.
vec3 c = b.xrt; // Invalid, mixing different styles is forbidden.
b.rrr = a.rgb; // Invalid, assignment with duplication.
b.bgr = a.rgb; // Valid assignment.

精确

It is possible to add precision modifiers to datatypes; use them for uniforms, variables, arguments and varyings:

lowp vec4 a = vec4(0.0, 1.0, 2.0, 3.0); // low precision, usually 8 bits per component mapped to 0-1
mediump vec4 a = vec4(0.0, 1.0, 2.0, 3.0); // medium precision, usually 16 bits or half float
highp vec4 a = vec4(0.0, 1.0, 2.0, 3.0); // high precision, uses full float or integer range (default)

Using lower precision for some operations can speed up the math involved (at the cost of less precision). This is rarely needed in the vertex processor function (where full precision is needed most of the time), but is often useful in the fragment processor.

Some architectures (mainly mobile) can benefit significantly from this, but there are downsides such as the additional overhead of conversion between precisions. Refer to the documentation of the target architecture for further information. In many cases, mobile drivers cause inconsistent or unexpected behavior and it is best to avoid specifying precision unless necessary.

数组

数组是存放多个相似类型变量的容器。注意:从godot3.2开始,只实现了局部数组和可变数组。

Local arrays

局部数组在函数中声明。它们可以使用所有允许的数据类型,但采样器除外。数组声明遵循C-style的语法。[const] + [precision] + typename + identifier + [array size]

void fragment() {
    float arr[3];
}

它们可以在开始时进行初始化,例如:

float float_arr[3] = float[3] (1.0, 0.5, 0.0); // first constructor

int int_arr[3] = int[] (2, 1, 0); // second constructor

vec2 vec2_arr[3] = { vec2(1.0, 1.0), vec2(0.5, 0.5), vec2(0.0, 0.0) }; // third constructor

bool bool_arr[] = { true, true, false }; // fourth constructor - size is defined automatically from the element count

您可以在一个表达式中声明多个数组(即使大小不同):

float a[3] = float[3] (1.0, 0.5, 0.0),
b[2] = { 1.0, 0.5 },
c[] = { 0.7 },
d = 0.0,
e[5];

要访问一个数组元素,请使用索引语法:

float arr[3];

arr[0] = 1.0; // setter

COLOR.r = arr[0]; // getter

数组有一个内置函数``.length()``(不要与内置的``length()``函数混淆)。它不接受任何参数,作用是返回数组的大小。

float arr[] = { 0.0, 1.0, 0.5, -1.0 };
for (int i = 0; i < arr.length(); i++) {
    // ...
}

注解

如果你使用一个低于0或大于数组大小的索引--着色器将崩溃并中断渲染。为了防止这种情况,请使用``length()``、``if``或``clamp()``函数来确保索引在0和数组的长度之间。总是仔细测试和检查你的代码。如果你传递了一个常量表达式或一个简单的数字,编辑器会检查它的边界以防止这种崩溃。

常量

在变量声明前使用``const``关键字可以使该变量不可改变,这意味着它不能被修改。除了采样器之外,所有的基本类型都可以声明为常量。访问和使用常量值的速度比使用统一变量uniform值稍快。常量必须在其声明时初始化。

const vec2 a = vec2(0.0, 1.0);
vec2 b;

a = b; // invalid
b = a; // valid

常量不能被修改,另外也不能有提示,但可以在一个表达式中声明多个常量(如果它们具有相同的类型),如

const vec2 V1 = vec2(1, 1), V2 = vec2(2, 2);

与变量类似,数组也可以用``const``来声明。

const float arr[] = { 1.0, 0.5, 0.0 };

arr[0] = 1.0; // invalid

COLOR.r = arr[0]; // valid

常量既可以全局声明(在任何函数之外),也可以局部声明(在函数内部)。当你想在整个着色器中访问一个不需要修改的值时,全局常量是非常有用的。像统一常量一样,全局常量在所有着色器范围是共享的,但它们在着色器之外是不可访问的。

shader_type spatial;

const float PI = 3.14159265358979323846;

运算符

Godot 着色器语言支持与GLSL ES 3.0相同的操作符集。下面是它们的优先级列表:

优先级

操作符

1 (最高)

括号分组

()

2

unary

+, -, !, ~

3

multiplicative

/, *, %

4

additive

+, -

5

逐位移位

<<, >>

6

相关的

<, >, <=, >=

7

平等

==, !=

8

bit-wise AND

&

9

bit-wise exclusive OR

^

10

bit-wise inclusive OR

|

11

logical AND

&&

12(最低)

logical inclusive OR

||

Flow control

Godot 着色器语言支持最常见的控制流类型:

// if and else
if (cond) {

} else {

}

// switch
switch(i) { // signed integer expression
    case -1:
        break;
    case 0:
        return; // break or return
    case 1: // pass-through
    case 2:
        break;
    //...
    default: // optional
        break;
}

// for loops
for (int i = 0; i < 10; i++) {

}

// while
while (true) {

}

// do while
do {

} while(true);

Keep in mind that, in modern GPUs, an infinite loop can exist and can freeze your application (including editor). Godot can't protect you from this, so be careful not to make this mistake!

警告

当导出 GLES2 项目到 HTML5时, WebGL 1.0将被使用。 WebGL 1.0不支持动态循环,所以使用这些的着色器将不会工作。

丢弃

片段和灯光功能可以使用 discard 关键字。 如果使用,则丢弃该片段并且不写入任何内容。

函数

It is possible to define functions in a Godot shader. They use the following syntax:

ret_type func_name(args) {
    return ret_type; // if returning a value
}

// a more specific example:

int sum2(int a, int b) {
    return a + b;
}

您只能使用上面定义的函数(编辑器中的较高位置)调用它们的函数。

Function arguments can have special qualifiers:

  • in: 表示参数仅用于读取(默认)。

  • out: 表示该参数只用于写入。

  • inout: 表示该参数以引用传递。

示例:

void sum2(int a, int b, inout int result) {
    result = a + b;
}

Varyings

To send data from the vertex to the fragment processor function, varyings are used. They are set for every primitive vertex in the vertex processor, and the value is interpolated for every pixel in the fragment processor.

shader_type spatial;

varying vec3 some_color;
void vertex() {
    some_color = NORMAL; // Make the normal the color.
}

void fragment() {
    ALBEDO = some_color;
}

Varying变量也可以被视为一个数组:

shader_type spatial;

varying float var_arr[3];
void vertex() {
    var_arr[0] = 1.0;
    var_arr[1] = 0.0;
}

void fragment() {
    ALBEDO = vec3(var_arr[0], var_arr[1], var_arr[2]); // red color
}

插值限定符

在着色管线期间内插某些值。 您可以使用 插值限定符 修改这些插值的完成方式。

shader_type spatial;

varying flat vec3 our_color;

void vertex() {
    our_color = COLOR.rgb;
}

void fragment() {
    ALBEDO = our_color;
}

There are two possible interpolation qualifiers:

限定符

描述

flat

该值未插值。

smooth

该值以透视正确的方式进行插值。 这是默认值。

统一值

Passing values to shaders is possible. These are global to the whole shader and are called uniforms. When a shader is later assigned to a material, the uniforms will appear as editable parameters in it. Uniforms can't be written from within the shader.

shader_type spatial;

uniform float some_value;

可以在编辑器中设置统一的材料。或者可以通过GDScript设置:

material.set_shader_param("some_value", some_value)

注解

“设置_着色器_参数”的第一个参数是着色器中统一值的名称。它必须与着色器中的统一值的名称完全匹配,否则将无法识别。

Any GLSL type except for void can be a uniform. Additionally, Godot provides optional shader hints to make the compiler understand for what the uniform is used.

shader_type spatial;

uniform vec4 color : hint_color;
uniform float amount : hint_range(0, 1);
uniform vec4 other_color : hint_color = vec4(1.0);

重要的是要明白,以颜色形式提供的纹理需要适当的sRGB->线性转换的提示(即``hint_albedo``),因为Godot的3D引擎在线性颜色空间中渲染。

以下提示的完整列表:

类型

暗示

描述

vec4

hint_color

用作颜色

int, float

hint_range(min, max[, step])

用作范围(最小/最大/步)

sampler2D

hint_albedo

用作反照率颜色,默认为白色

sampler2D

hint_black_albedo

用作反照率颜色,默认为黑色

sampler2D

hint_normal

用作法线贴图

sampler2D

hint_white

作为值,默认为白色。

sampler2D

hint_black

作为值,默认为黑色

sampler2D

hint_aniso

作为流程图,默认为右。

GDScript使用的变量类型与GLSL不同,所以当把变量从GDScript传递到着色器时,Godot会自动转换类型。以下是相应类型的表格:

GDScript type

GLSL type

bool

bool

int

int

float

float

Vector2

vec2

Vector3

vec3

Color

vec4

Transform

mat4

Transform2D

mat4

注解

Be careful when setting shader uniforms from GDScript, no error will be thrown if the type does not match. Your shader will just exhibit undefined behavior.

统一值也可以分配默认值:

shader_type spatial;

uniform vec4 some_vector = vec4(0.0);
uniform vec4 some_color : hint_color = vec4(1.0);

Built-in functions

A large number of built-in functions are supported, conforming to GLSL ES 3.0. When vec_type (float), vec_int_type, vec_uint_type, vec_bool_type nomenclature is used, it can be scalar or vector.

注解

对于GLES2后端不可用的函数列表,请参见:ref:GLES2和GLES3之间的差异文档 <doc_gles2_gles3_differences>.

函数

描述

vec_type radians (vec_type degrees)

将度数转换为弧度

vec_type degrees (vec_type radians)

将弧度转换为度数

vec_type sin (vec_type x)

正弦

vec_type cos (vec_type x)

余弦

vec_type tan (vec_type x)

正切

vec_type asin (vec_type x)

Arcsine

vec_type acos (vec_type x)

Arccosine

vec_type atan (vec_type y_over_x)

Arctangent

vec_type atan (vec_type y, vec_type x)

Arctangent to convert vector to angle

vec_type sinh (vec_type x)

Hyperbolic sine

vec_type cosh (vec_type x)

Hyperbolic cosine

vec_type tanh (vec_type x)

Hyperbolic tangent

vec_type asinh (vec_type x)

Inverse hyperbolic sine

vec_type acosh (vec_type x)

Inverse hyperbolic cosine

vec_type atanh (vec_type x)

Inverse hyperbolic tangent

vec_type pow (vec_type x, vec_type y)

Power (undefined if x < 0 or if x = 0 and y <= 0)

vec_type exp (vec_type x)

Base-e exponential

vec_type exp2 (vec_type x)

Base-2 exponential

vec_type log (vec_type x)

Natural logarithm

vec_type log2 (vec_type x)

Base-2 logarithm

vec_type sqrt (vec_type x)

Square root

vec_type inversesqrt (vec_type x)

Inverse square root

vec_type abs (vec_type x)

绝对

ivec_type abs (ivec_type x)

绝对

vec_type sign (vec_type x)

符号

ivec_type sign (ivec_type x)

符号

vec_type floor (vec_type x)

向下取整

vec_type round (vec_type x)

四舍五入

vec_type roundEven (vec_type x)

Round to the nearest even number

vec_type trunc (vec_type x)

截断

vec_type ceil (vec_type x)

Ceil

vec_type fract (vec_type x)

Fractional

vec_type mod (vec_type x, vec_type y)

vec_type mod (vec_type x , float y)

vec_type modf (vec_type x, out vec_type i)

Fractional of x, with i as integer part

vec_type min (vec_type a, vec_type b)

最小值

vec_type max (vec_type a, vec_type b)

最大值

vec_type clamp (vec_type x, vec_type min, vec_type max)

Clamp to min..max

float mix (float a, float b, float c)

Linear interpolate

vec_type mix (vec_type a, vec_type b, float c)

Linear interpolate (scalar coefficient)

vec_type mix (vec_type a, vec_type b, vec_type c)

Linear interpolate (vector coefficient)

vec_type mix (vec_type a, vec_type b, bvec_type c)

Linear interpolate (boolean-vector selection)

vec_type step (vec_type a, vec_type b)

b[i] < a[i] ? 0.0 : 1.0

vec_type step (float a, vec_type b)

b[i] < a ? 0.0 : 1.0

vec_type smoothstep (vec_type a, vec_type b, vec_type c)

Hermite interpolate

vec_type smoothstep (float a, float b, vec_type c)

Hermite interpolate

bvec_type isnan (vec_type x)

Returns true if scalar or vector component is NaN

bvec_type isinf (vec_type x)

Returns true if scalar or vector component is INF

ivec_type floatBitsToInt (vec_type x)

Float-> Int位复制,无转换

uvec_type floatBitsToUint (vec_type x)

Float-> UInt位复制,无转换

vec_type intBitsToFloat (ivec_type x)

Int-> Float位复制,无转换

vec_type uintBitsToFloat (uvec_type x)

UInt->浮点复制,无转换

float length (vec_type x)

Vector length

float distance (vec_type a, vec_type b)

Distance between vectors i.e length(a - b)

float dot (vec_type a, vec_type b)

点乘

vec3 叉乘(cross) (vec3 a, vec3 b)

叉乘

vec_type normalize (vec_type x)

标准化为单位长度

vec3 reflect (vec3 I, vec3 N)

反映

vec3 refract (vec3 I, vec3 N, float eta)

折射

vec_type faceforward (vec_type N, vec_type I, vec_type Nref)

If dot(Nref, I) < 0, return N, otherwise –N

mat_type matrixCompMult (mat_type x, mat_type y)

Matrix component multiplication

mat_type outerProduct (vec_type column, vec_type row)

Matrix outer product

mat_type transpose (mat_type m)

Transpose matrix

float determinant (mat_type m)

Matrix determinant

mat_type inverse (mat_type m)

Inverse matrix

bvec_type lessThan (vec_type x, vec_type y)

Bool vector comparison on < int/uint/float vectors

bvec_type greaterThan (vec_type x, vec_type y)

Bool vector comparison on > int/uint/float vectors

bvec_type lessThanEqual (vec_type x, vec_type y)

Bool vector comparison on <= int/uint/float vectors

bvec_type greaterThanEqual (vec_type x, vec_type y)

Bool vector comparison on >= int/uint/float vectors

bvec_type equal (vec_type x, vec_type y)

Bool vector comparison on == int/uint/float vectors

bvec_type notEqual (vec_type x, vec_type y)

Bool vector comparison on != int/uint/float vectors

bool any (bvec_type x)

Any component is true

bool all (bvec_type x)

All components are true

bvec_type not (bvec_type x)

Invert boolean vector

ivec2 textureSize (sampler2D_type s, int lod)

Get the size of a 2D texture

ivec3 textureSize (sampler2DArray_type s, int lod)

Get the size of a 2D texture array

ivec3 textureSize (sampler3D s, int lod)

Get the size of a 3D texture

ivec2 textureSize (samplerCube s, int lod)

Get the size of a cubemap texture

vec4_type texture (sampler2D_type s, vec2 uv [, float bias])

执行2D纹理读取

vec4_type texture (sampler2DArray_type s, vec3 uv [, float bias])

Perform a 2D texture array read

vec4_type texture (sampler3D_type s, vec3 uv [, float bias])

Perform a 3D texture read

vec4 texture (samplerCube s, vec3 uv [, float bias])

Perform a cubemap texture read

vec4_type textureProj (sampler2D_type s, vec3 uv [, float bias])

Perform a 2D texture read with projection

vec4_type textureProj (sampler2D_type s, vec4 uv [, float bias])

Perform a 2D texture read with projection

vec4_type textureProj (sampler3D_type s, vec4 uv [, float bias])

Perform a 3D texture read with projection

vec4_type textureLod (sampler2D_type s, vec2 uv, float lod)

在自定义mipmap上执行2D纹理读取

vec4_type textureLod (sampler2DArray_type s, vec3 uv, float lod)

Perform a 2D texture array read at custom mipmap

vec4_type textureLod (sampler3D_type s, vec3 uv, float lod)

Perform a 3D texture read at custom mipmap

vec4 textureLod (samplerCube s, vec3 uv, float lod)

Perform a 3D texture read at custom mipmap

vec4_type textureProjLod (sampler2D_type s, vec3 uv, float lod)

Perform a 2D texture read with projection/LOD

vec4_type textureProjLod (sampler2D_type s, vec4 uv, float lod)

Perform a 2D texture read with projection/LOD

vec4_type textureProjLod (sampler3D_type s, vec4 uv, float lod)

Perform a 3D texture read with projection/LOD

vec4_type texelFetch (sampler2D_type s, ivec2 uv, int lod)

Fetch a single texel using integer coordinates

vec4_type texelFetch (sampler2DArray_type s, ivec3 uv, int lod)

Fetch a single texel using integer coordinates

vec4_type texelFetch (sampler3D_type s, ivec3 uv, int lod)

Fetch a single texel using integer coordinates

vec_type dFdx (vec_type p)

Derivative in x using local differencing

vec_type dFdy (vec_type p)

Derivative in y using local differencing

vec_type fwidth (vec_type p)

Sum of absolute derivative in x and y