Relintai/pandemonium_engine_docs
1
0
Fork 0
mirror of https://github.com/Relintai/pandemonium_engine_docs.git synced 2025-01-04 14:49:52 +01:00
Code Issues Packages Projects Releases Wiki Activity

Cleanups.

Browse Source
This commit is contained in:
Relintai 2024-04-30 20:48:19 +02:00
parent 42ee7816c2
commit 94c244f458
8 changed files with 227 additions and 672 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

349
03_usage/16_shaders/shader_reference/01_shading_language.md
View File

@ -1,10 +1,8 @@
Shading language
================
# Shading language
Introduction
------------
## Introduction
Pandemonium uses a shading language similar to GLSL ES 3.0. Most datatypes and functions are supported,
and the few remaining ones will likely be added over time.
@ -12,77 +10,45 @@ and the few remaining ones will likely be added over time.
If you are already familiar with GLSL, the `Pandemonium Shader Migration Guide( doc_converting_glsl_to_pandemonium_shaders )`
is a resource that will help you transition from regular GLSL to Pandemonium's shading language.
Data types
----------
## Data types
Most GLSL ES 3.0 datatypes are supported:
+---------------------+---------------------------------------------------------------------------------+
| Type | Description |
+=====================+=================================================================================+
| **void** | Void datatype, useful only for functions that return nothing. |
+---------------------+---------------------------------------------------------------------------------+
| **bool** | Boolean datatype, can only contain `true` or `false`. |
+---------------------+---------------------------------------------------------------------------------+
| **bvec2** | Two-component vector of booleans. |
+---------------------+---------------------------------------------------------------------------------+
| **bvec3** | Three-component vector of booleans. |
+---------------------+---------------------------------------------------------------------------------+
| **bvec4** | Four-component vector of booleans. |
+---------------------+---------------------------------------------------------------------------------+
| **int** | Signed scalar integer. |
+---------------------+---------------------------------------------------------------------------------+
| **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 matrix, in column major order. |
+---------------------+---------------------------------------------------------------------------------+
| **mat3** | 3x3 matrix, in column major order. |
+---------------------+---------------------------------------------------------------------------------+
| **mat4** | 4x4 matrix, in column major order. |
+---------------------+---------------------------------------------------------------------------------+
| **sampler2D** | Sampler type for binding 2D textures, which are read as float. |
+---------------------+---------------------------------------------------------------------------------+
| **isampler2D** | Sampler type for binding 2D textures, which are read as signed integer. |
+---------------------+---------------------------------------------------------------------------------+
| **usampler2D** | Sampler type for binding 2D textures, which are read as unsigned integer. |
+---------------------+---------------------------------------------------------------------------------+
| **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** | Sampler type for binding Cubemaps, which are read as floats. |
+---------------------+---------------------------------------------------------------------------------+
Casting
~~~~~~~
| Type | Description |
|---------------------|---------------------------------------------------------------------------------|
| **void** | Void datatype, useful only for functions that return nothing. |
| **bool** | Boolean datatype, can only contain `true` or `false`. |
| **bvec2** | Two-component vector of booleans. |
| **bvec3** | Three-component vector of booleans. |
| **bvec4** | Four-component vector of booleans. |
| **int** | Signed scalar integer. |
| **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 matrix, in column major order. |
| **mat3** | 3x3 matrix, in column major order. |
| **mat4** | 4x4 matrix, in column major order. |
| **sampler2D** | Sampler type for binding 2D textures, which are read as float. |
| **isampler2D** | Sampler type for binding 2D textures, which are read as signed integer. |
| **usampler2D** | Sampler type for binding 2D textures, which are read as unsigned integer. |
| **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** | Sampler type for binding Cubemaps, which are read as floats. |
### Casting
Just like GLSL ES 3.0, implicit casting between scalars and vectors of the same size but different type is not allowed.
Casting of types of different size is also not allowed. Conversion must be done explicitly via constructors.
@ -103,8 +69,7 @@ Default integer constants are signed, so casting is always needed to convert to
uint a = uint(2); // valid
```
Members
~~~~~~~
### Members
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
@ -114,8 +79,7 @@ For matrices, use the `m[column][row]` 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]`.
Constructing
~~~~~~~~~~~~
### Constructing
Construction of vector types must always pass:
@ -151,8 +115,7 @@ from a larger matrix, the top, left submatrix of the larger matrix is used.
mat2 m2 = mat2(m4);
```
Swizzling
~~~~~~~~~
### Swizzling
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:
@ -170,8 +133,7 @@ is another vector type (or scalar). This is easier shown than explained:
b.bgr = a.rgb; // Valid assignment. "b"'s "blue" component will be "a"'s "red" and vice versa.
```
Precision
~~~~~~~~~
### Precision
It is possible to add precision modifiers to datatypes; use them for uniforms, variables, arguments and varyings:
@ -192,14 +154,12 @@ 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.
Arrays
------
## Arrays
Arrays are containers for multiple variables of a similar type.
Note: As of Pandemonium 3.2, only local and varying arrays have been implemented.
Local arrays
~~~~~~~~~~~~
### Local arrays
Local arrays are declared in functions. They can use all of the allowed datatypes, except samplers.
The array declaration follows a C-style syntax: `[const] + [precision] + typename + identifier + [array size]`.
@ -256,8 +216,7 @@ Note:
If you use an index below 0 or greater than array size - the shader will crash and break rendering. To prevent this, use `length()`, `if`, or `clamp()` functions to ensure the index is between 0 and the array's length. Always carefully test and check your code. If you pass a constant expression or a simple number, the editor will check its bounds to prevent this crash.
Constants
---------
## Constants
Use the `const` keyword before the variable declaration to make that variable immutable, which means that it cannot be modified. All basic types, except samplers can be declared as constants. Accessing and using a constant value is slightly faster than using a uniform. Constants must be initialized at their declaration.
@ -294,41 +253,28 @@ Global constants are useful when you want to have access to a value throughout y
const float PI = 3.14159265358979323846;
```
Operators
---------
## Operators
Pandemonium shading language supports the same set of operators as GLSL ES 3.0. Below is the list of them in precedence order:
+-------------+------------------------+------------------+
| Precedence | Class | Operator |
+-------------+------------------------+------------------+
| 1 (highest) | parenthetical grouping | **()** |
+-------------+------------------------+------------------+
| 2 | unary | **+, -, !, ~** |
+-------------+------------------------+------------------+
| 3 | multiplicative | **/, \*, %** |
+-------------+------------------------+------------------+
| 4 | additive | **+, -** |
+-------------+------------------------+------------------+
| 5 | bit-wise shift | **<<, >>** |
+-------------+------------------------+------------------+
| 6 | relational | **<, >, <=, >=** |
+-------------+------------------------+------------------+
| 7 | equality | **==, !=** |
+-------------+------------------------+------------------+
| 8 | bit-wise AND | **&** |
+-------------+------------------------+------------------+
| 9 | bit-wise exclusive OR | **^** |
+-------------+------------------------+------------------+
| 10 | bit-wise inclusive OR | **|** |
+-------------+------------------------+------------------+
| 11 | logical AND | **&&** |
+-------------+------------------------+------------------+
| 12 (lowest) | logical inclusive OR | **||** |
+-------------+------------------------+------------------+
Flow control
------------
| Precedence | Class | Operator |
|-------------|------------------------|------------------|
| 1 (highest) | parenthetical grouping | **()** |
| 2 | unary | **+, -, !, ~** |
| 3 | multiplicative | **/, \*, %** |
| 4 | additive | **+, -** |
| 5 | bit-wise shift | **<<, >>** |
| 6 | relational | **<, >, <=, >=** |
| 7 | equality | **==, !=** |
| 8 | bit-wise AND | **&** |
| 9 | bit-wise exclusive OR | **^** |
| 10 | bit-wise inclusive OR | **|** |
| 11 | logical AND | **&&** |
| 12 (lowest) | logical inclusive OR | **||** |
## Flow control
Pandemonium Shading language supports the most common types of flow control:
@ -375,17 +321,14 @@ Pandemonium can't protect you from this, so be careful not to make this mistake!
Warning:
When exporting a GLES2 project to HTML5, WebGL 1.0 will be used. WebGL 1.0
doesn't support dynamic loops, so shaders using those won't work there.
Discarding
----------
## Discarding
Fragment and light functions can use the **discard** keyword. If used, the fragment is discarded and nothing is written.
Functions
---------
## Functions
It is possible to define functions in a Pandemonium shader. They use the following syntax:
@ -419,8 +362,7 @@ Example below:
}
```
Varyings
~~~~~~~~
### Varyings
To send data from the vertex to the fragment (or light) processor function, *varyings* are
used. They are set for every primitive vertex in the *vertex processor*, and the
@ -499,8 +441,7 @@ Note that varying may not be assigned in custom functions or a *light processor*
This limitation was introduced to prevent incorrect usage before initialization.
Interpolation qualifiers
~~~~~~~~~~~~~~~~~~~~~~~~
### Interpolation qualifiers
Certain values are interpolated during the shading pipeline. You can modify how these interpolations
are done by using *interpolation qualifiers*.
@ -521,17 +462,15 @@ are done by using *interpolation qualifiers*.
There are two possible interpolation qualifiers:
+-------------------+---------------------------------------------------------------------------------+
| Qualifier | Description |
+===================+=================================================================================+
| **flat** | The value is not interpolated. |
+-------------------+---------------------------------------------------------------------------------+
| **smooth** | The value is interpolated in a perspective-correct fashion. This is the default.|
+-------------------+---------------------------------------------------------------------------------+
| Qualifier | Description |
|-------------------|----------------------------------------------------------------------------------|
| **flat** | The value is not interpolated. |
| **smooth** | The value is interpolated in a perspective-correct fashion. This is the default. |
Uniforms
~~~~~~~~
### Uniforms
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.
@ -569,48 +508,33 @@ It's important to understand that textures that are supplied as color require hi
Full list of hints below:
+----------------+------------------------------+------------------------------------------------------+
| Type | Hint | Description |
+================+==============================+======================================================+
|----------------|------------------------------|------------------------------------------------------|
| **vec4** | hint_color | Used as color. |
+----------------+------------------------------+------------------------------------------------------+
| **int, float** | hint_range(min, max[, step]) | Restricted to values in a range (with min/max/step). |
+----------------+------------------------------+------------------------------------------------------+
| **sampler2D** | hint_albedo | Used as albedo color, default white. |
+----------------+------------------------------+------------------------------------------------------+
| **sampler2D** | hint_black_albedo | Used as albedo color, default black. |
+----------------+------------------------------+------------------------------------------------------+
| **sampler2D** | hint_normal | Used as normalmap. |
+----------------+------------------------------+------------------------------------------------------+
| **sampler2D** | hint_white | As value, default to white. |
+----------------+------------------------------+------------------------------------------------------+
| **sampler2D** | hint_black | As value, default to black |
+----------------+------------------------------+------------------------------------------------------+
| **sampler2D** | hint_aniso | As flowmap, default to right. |
+----------------+------------------------------+------------------------------------------------------+
GDScript uses different variable types than GLSL does, so when passing variables from GDScript
to shaders, Pandemonium converts the type automatically. Below is a table of the corresponding types:
+-----------------+-----------+
| GDScript type | GLSL type |
+=================+===========+
|-----------------|-----------|
| **bool** | **bool** |
+-----------------+-----------+
| **int** | **int** |
+-----------------+-----------+
| **float** | **float** |
+-----------------+-----------+
| **Vector2** | **vec2** |
+-----------------+-----------+
| **Vector3** | **vec3** |
+-----------------+-----------+
| **Color** | **vec4** |
+-----------------+-----------+
| **Transform** | **mat4** |
+-----------------+-----------+
| **Transform2D** | **mat4** |
+-----------------+-----------+
Note:
Be careful when setting shader uniforms from GDScript, no error will be thrown if the
@ -625,8 +549,7 @@ Uniforms can also be assigned default values:
uniform vec4 some_color : hint_color = vec4(1.0);
```
Built-in variables
------------------
## Built-in variables
A large number of built-in variables are available, like `UV`, `COLOR` and `VERTEX`. What variables are available depends on the type of shader (`spatial`, `canvas_item` or `particle`) and the function used (`vertex`, `fragment` or `light`).
For a list of the build-in variables that are available, please see the corresponding pages:
@ -635,8 +558,7 @@ For a list of the build-in variables that are available, please see the correspo
- `Canvas item shaders ( doc_canvas_item_shader )`
- `Particle shaders ( doc_particle_shader )`
Built-in functions
------------------
## 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.
@ -645,202 +567,105 @@ Note:
For a list of the functions that are not available in the GLES2 backend, please see the
`Differences between GLES2 and GLES3 doc ( doc_gles2_gles3_differences )`.
+------------------------------------------------------------------------+---------------------------------------------------------------+
| Function | Description |
+========================================================================+===============================================================+
|------------------------------------------------------------------------|---------------------------------------------------------------|
| vec_type **radians** (vec_type degrees) | Convert degrees to radians |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **degrees** (vec_type radians) | Convert radians to degrees |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **sin** (vec_type x) | Sine |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **cos** (vec_type x) | Cosine |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **tan** (vec_type x) | Tangent |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| 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 **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) | Absolute |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| ivec_type **abs** (ivec_type x) | Absolute |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **sign** (vec_type x) | Sign |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| ivec_type **sign** (ivec_type x) | Sign |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **floor** (vec_type x) | Floor |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **round** (vec_type x) | Round |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **roundEven** (vec_type x) | Round to the nearest even number |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **trunc** (vec_type x) | Truncation |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **ceil** (vec_type x) | Ceil |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **fract** (vec_type x) | Fractional |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **mod** (vec_type x, vec_type y) | Remainder |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **mod** (vec_type x , float y) | Remainder |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| 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) | Minimum |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **max** (vec_type a, vec_type b) | Maximum |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| 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 bit copying, no conversion |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| uvec_type **floatBitsToUint** (vec_type x) | Float->UInt bit copying, no conversion |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **intBitsToFloat** (ivec_type x) | Int->Float bit copying, no conversion |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **uintBitsToFloat** (uvec_type x) | UInt->Float bit copying, no conversion |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| 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) | Dot product |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec3 **cross** (vec3 a, vec3 b) | Cross product |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec_type **normalize** (vec_type x) | Normalize to unit length |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec3 **reflect** (vec3 I, vec3 N) | Reflect |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| vec3 **refract** (vec3 I, vec3 N, float eta) | Refract |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| 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]) | Perform a 2D texture read |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| 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) | Perform a 2D texture read at custom mipmap |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| 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` |
+------------------------------------------------------------------------+---------------------------------------------------------------+
| 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` |

262
03_usage/16_shaders/shader_reference/02_spatial_shader.md
View File

@ -1,103 +1,67 @@
Spatial shaders
===============
# Spatial shaders
Spatial shaders are used for shading 3D objects. They are the most complex type of shader Pandemonium offers.
Spatial shaders are highly configurable with different render modes and different rendering options
(e.g. Subsurface Scattering, Transmission, Ambient Occlusion, Rim lighting etc). Users can optionally
write vertex, fragment, and light processor functions to affect how objects are drawn.
Render modes
^^^^^^^^^^^^
#### Render modes
+---------------------------------+-----------------------------------------------------------------------+
| Render mode | Description |
+=================================+=======================================================================+
| **blend_mix** | Mix blend mode (alpha is transparency), default. |
+---------------------------------+-----------------------------------------------------------------------+
| **blend_add** | Additive blend mode. |
+---------------------------------+-----------------------------------------------------------------------+
| **blend_sub** | Subtractive blend mode. |
+---------------------------------+-----------------------------------------------------------------------+
| **blend_mul** | Multiplicative blend mode. |
+---------------------------------+-----------------------------------------------------------------------+
| **depth_draw_opaque** | Only draw depth for opaque geometry (not transparent). |
+---------------------------------+-----------------------------------------------------------------------+
| **depth_draw_always** | Always draw depth (opaque and transparent). |
+---------------------------------+-----------------------------------------------------------------------+
| **depth_draw_never** | Never draw depth. |
+---------------------------------+-----------------------------------------------------------------------+
| **depth_draw_alpha_prepass** | Do opaque depth pre-pass for transparent geometry. |
+---------------------------------+-----------------------------------------------------------------------+
| **depth_test_disable** | Disable depth testing. |
+---------------------------------+-----------------------------------------------------------------------+
| **cull_front** | Cull front-faces. |
+---------------------------------+-----------------------------------------------------------------------+
| **cull_back** | Cull back-faces (default). |
+---------------------------------+-----------------------------------------------------------------------+
| **cull_disabled** | Culling disabled (double sided). |
+---------------------------------+-----------------------------------------------------------------------+
| **unshaded** | Result is just albedo. No lighting/shading happens in material. |
+---------------------------------+-----------------------------------------------------------------------+
| **diffuse_lambert** | Lambert shading for diffuse (default). |
+---------------------------------+-----------------------------------------------------------------------+
| **diffuse_lambert_wrap** | Lambert wrapping (roughness dependent) for diffuse. |
+---------------------------------+-----------------------------------------------------------------------+
| **diffuse_oren_nayar** | Oren Nayar for diffuse. |
+---------------------------------+-----------------------------------------------------------------------+
| **diffuse_burley** | Burley (Disney PBS) for diffuse. |
+---------------------------------+-----------------------------------------------------------------------+
| **diffuse_toon** | Toon shading for diffuse. |
+---------------------------------+-----------------------------------------------------------------------+
| **specular_schlick_ggx** | Schlick-GGX for specular (default). |
+---------------------------------+-----------------------------------------------------------------------+
| **specular_blinn** | Blinn for specular (compatibility). |
+---------------------------------+-----------------------------------------------------------------------+
| **specular_phong** | Phong for specular (compatibility). |
+---------------------------------+-----------------------------------------------------------------------+
| **specular_toon** | Toon for specular. |
+---------------------------------+-----------------------------------------------------------------------+
| **specular_disabled** | Disable specular. |
+---------------------------------+-----------------------------------------------------------------------+
| **skip_vertex_transform** | VERTEX/NORMAL/etc. need to be transformed manually in vertex function.|
+---------------------------------+-----------------------------------------------------------------------+
| **world_vertex_coords** | VERTEX/NORMAL/etc. are modified in world coordinates instead of local.|
+---------------------------------+-----------------------------------------------------------------------+
| **ensure_correct_normals** | Use when non-uniform scale is applied to mesh. |
+---------------------------------+-----------------------------------------------------------------------+
| **vertex_lighting** | Use vertex-based lighting. |
+---------------------------------+-----------------------------------------------------------------------+
| **shadows_disabled** | Disable computing shadows in shader. |
+---------------------------------+-----------------------------------------------------------------------+
| **ambient_light_disabled** | Disable contribution from ambient light and radiance map. |
+---------------------------------+-----------------------------------------------------------------------+
| **shadow_to_opacity** | Lighting modifies the alpha so shadowed areas are opaque and |
| | non-shadowed areas are transparent. Useful for overlaying shadows onto|
| | a camera feed in AR. |
+---------------------------------+-----------------------------------------------------------------------+
Built-ins
^^^^^^^^^
| Render mode | Description |
|---------------------------------|------------------------------------------------------------------------|
| **blend_mix** | Mix blend mode (alpha is transparency), default. |
| **blend_add** | Additive blend mode. |
| **blend_sub** | Subtractive blend mode. |
| **blend_mul** | Multiplicative blend mode. |
| **depth_draw_opaque** | Only draw depth for opaque geometry (not transparent). |
| **depth_draw_always** | Always draw depth (opaque and transparent). |
| **depth_draw_never** | Never draw depth. |
| **depth_draw_alpha_prepass** | Do opaque depth pre-pass for transparent geometry. |
| **depth_test_disable** | Disable depth testing. |
| **cull_front** | Cull front-faces. |
| **cull_back** | Cull back-faces (default). |
| **cull_disabled** | Culling disabled (double sided). |
| **unshaded** | Result is just albedo. No lighting/shading happens in material. |
| **diffuse_lambert** | Lambert shading for diffuse (default). |
| **diffuse_lambert_wrap** | Lambert wrapping (roughness dependent) for diffuse. |
| **diffuse_oren_nayar** | Oren Nayar for diffuse. |
| **diffuse_burley** | Burley (Disney PBS) for diffuse. |
| **diffuse_toon** | Toon shading for diffuse. |
| **specular_schlick_ggx** | Schlick-GGX for specular (default). |
| **specular_blinn** | Blinn for specular (compatibility). |
| **specular_phong** | Phong for specular (compatibility). |
| **specular_toon** | Toon for specular. |
| **specular_disabled** | Disable specular. |
| **skip_vertex_transform** | VERTEX/NORMAL/etc. need to be transformed manually in vertex function. |
| **world_vertex_coords** | VERTEX/NORMAL/etc. are modified in world coordinates instead of local. |
| **ensure_correct_normals** | Use when non-uniform scale is applied to mesh. |
| **vertex_lighting** | Use vertex-based lighting. |
| **shadows_disabled** | Disable computing shadows in shader. |
| **ambient_light_disabled** | Disable contribution from ambient light and radiance map. |
| **shadow_to_opacity** | Lighting modifies the alpha so shadowed areas are opaque and |
| | non-shadowed areas are transparent. Useful for overlaying shadows onto |
| | a camera feed in AR. |
#### Built-ins
Values marked as "in" are read-only. Values marked as "out" are for optional writing and will
not necessarily contain sensible values. Values marked as "inout" provide a sensible default
value, and can optionally be written to. Samplers are not subjects of writing and they are
not marked.
Global built-ins
^^^^^^^^^^^^^^^^
#### Global built-ins
Global built-ins are available everywhere, including custom functions.
+-------------------+--------------------------+
| Built-in | Description |
+===================+==========================+
|-------------------|--------------------------|
| in float **TIME** | Global time, in seconds. |
+-------------------+--------------------------+
Vertex built-ins
^^^^^^^^^^^^^^^^
#### Vertex built-ins
Vertex data (`VERTEX`, `NORMAL`, `TANGENT`, `BITANGENT`) are presented in local
model space. If not written to, these values will not be modified and be passed through
@ -135,176 +99,104 @@ is usually:
This allows you to easily adjust the shader to a particle system using default particles material. When writing a custom particle
shader, this value can be used as desired.
+--------------------------------------+--------------------------------------------------------+
| Built-in | Description |
+======================================+========================================================+
|--------------------------------------|--------------------------------------------------------|
| in vec2 **VIEWPORT_SIZE** | Size of viewport (in pixels). |
+--------------------------------------+--------------------------------------------------------+
| inout mat4 **WORLD_MATRIX** | Model space to world space transform. |
+--------------------------------------+--------------------------------------------------------+
| in mat4 **INV_CAMERA_MATRIX** | World space to view space transform. |
+--------------------------------------+--------------------------------------------------------+
| inout mat4 **PROJECTION_MATRIX** | View space to clip space transform. |
+--------------------------------------+--------------------------------------------------------+
| in mat4 **CAMERA_MATRIX** | View space to world space transform. |
+--------------------------------------+--------------------------------------------------------+
| inout mat4 **MODELVIEW_MATRIX** | Model space to view space transform (use if possible). |
+--------------------------------------+--------------------------------------------------------+
| inout mat4 **INV_PROJECTION_MATRIX** | Clip space to view space transform. |
+--------------------------------------+--------------------------------------------------------+
| in vec3 **NODE_POSITION_WORLD** | Node position, in world space. |
+--------------------------------------+--------------------------------------------------------+
| in vec3 **NODE_POSITION_VIEW** | Node position, in view space. |
+--------------------------------------+--------------------------------------------------------+
| in vec3 **CAMERA_POSITION_WORLD** | Camera position, in world space. |
+--------------------------------------+--------------------------------------------------------+
| in vec3 **CAMERA_DIRECTION_WORLD** | Camera direction, in world space. |
+--------------------------------------+--------------------------------------------------------+
| inout vec3 **VERTEX** | Vertex in local coordinates. |
+--------------------------------------+--------------------------------------------------------+
| out vec4 **POSITION** | If written to, overrides final vertex position. |
+--------------------------------------+--------------------------------------------------------+
| inout vec3 **NORMAL** | Normal in local coordinates. |
+--------------------------------------+--------------------------------------------------------+
| inout vec3 **TANGENT** | Tangent in local coordinates. |
+--------------------------------------+--------------------------------------------------------+
| inout vec3 **BINORMAL** | Binormal in local coordinates. |
+--------------------------------------+--------------------------------------------------------+
| out float **ROUGHNESS** | Roughness for vertex lighting. |
+--------------------------------------+--------------------------------------------------------+
| inout vec2 **UV** | UV main channel. |
+--------------------------------------+--------------------------------------------------------+
| inout vec2 **UV2** | UV secondary channel. |
+--------------------------------------+--------------------------------------------------------+
| in bool **OUTPUT_IS_SRGB** | `true` when calculations happen in sRGB color space |
| | (`true` in GLES2, `false` in GLES3). |
+--------------------------------------+--------------------------------------------------------+
| in bool **OUTPUT_IS_SRGB** | `true` when calculations happen in sRGB color space |
| | (`true` in GLES2, `false` in GLES3). |
| inout vec4 **COLOR** | Color from vertices. |
+--------------------------------------+--------------------------------------------------------+
| inout float **POINT_SIZE** | Point size for point rendering. |
+--------------------------------------+--------------------------------------------------------+
| in int **INSTANCE_ID** | Instance ID for instancing. |
+--------------------------------------+--------------------------------------------------------+
| in vec4 **INSTANCE_CUSTOM** | Instance custom data (for particles, mostly). |
+--------------------------------------+--------------------------------------------------------+
Note:
`MODELVIEW_MATRIX` combines both the `WORLD_MATRIX` and `INV_CAMERA_MATRIX` and is better suited when floating point issues may arise. For example, if the object is very far away from the world origin, you may run into floating point issues when using the seperated `WORLD_MATRIX` and `INV_CAMERA_MATRIX`.
Fragment built-ins
^^^^^^^^^^^^^^^^^^
#### Fragment built-ins
The default use of a Pandemonium fragment processor function is to set up the material properties of your object
and to let the built-in renderer handle the final shading. However, you are not required to use all
these properties, and if you don't write to them, Pandemonium will optimize away the corresponding functionality.
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| Built-in | Description |
+===================================+==================================================================================================+
|-----------------------------------|--------------------------------------------------------------------------------------------------|
| in vec2 **VIEWPORT_SIZE** | Size of viewport (in pixels). |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in vec4 **FRAGCOORD** | Coordinate of pixel center in screen space. `xy` specifies position in window, `z` |
| | specifies fragment depth if `DEPTH` is not used. Origin is lower-left. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in vec4 **FRAGCOORD** | Coordinate of pixel center in screen space. `xy` specifies position in window, `z` |
| | specifies fragment depth if `DEPTH` is not used. Origin is lower-left. |
| in mat4 **WORLD_MATRIX** | Model space to world space transform. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in mat4 **INV_CAMERA_MATRIX** | World space to view space transform. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in mat4 **CAMERA_MATRIX** | View space to world space transform. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in mat4 **PROJECTION_MATRIX** | View space to clip space transform. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in mat4 **INV_PROJECTION_MATRIX** | Clip space to view space transform. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in vec3 **NODE_POSITION_WORLD** | Node world space position. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in vec3 **NODE_POSITION_VIEW** | Node view space position. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in vec3 **CAMERA_POSITION_WORLD** | Camera world space position. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in vec3 **CAMERA_DIRECTION_WORLD**| Camera world space direction. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in vec3 **VERTEX** | Vertex that comes from vertex function (default, in view space). |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in vec3 **VIEW** | Vector from camera to fragment position (in view space). |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in bool **FRONT_FACING** | `true` if current face is front face. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in bool **FRONT_FACING** | `true` if current face is front face. |
| inout vec3 **NORMAL** | Normal that comes from vertex function (default, in view space). |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| inout vec3 **TANGENT** | Tangent that comes from vertex function. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| inout vec3 **BINORMAL** | Binormal that comes from vertex function. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out vec3 **NORMALMAP** | Set normal here if reading normal from a texture instead of NORMAL. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **NORMALMAP_DEPTH** | Depth from variable above. Defaults to 1.0. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in vec2 **UV** | UV that comes from vertex function. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in vec2 **UV2** | UV2 that comes from vertex function. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in bool **OUTPUT_IS_SRGB** | `true` when calculations happen in sRGB color space (`true` in GLES2, `false` in GLES3). |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in bool **OUTPUT_IS_SRGB** | `true` when calculations happen in sRGB color space (`true` in GLES2, `false` in GLES3). |
| in vec4 **COLOR** | COLOR that comes from vertex function. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out vec3 **ALBEDO** | Albedo (default white). |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **ALPHA** | Alpha (0..1); if written to, the material will go to the transparent pipeline. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **ALPHA_SCISSOR** | If written to, values below a certain amount of alpha are discarded. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **METALLIC** | Metallic (0..1). |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **SPECULAR** | Specular. Defaults to 0.5, best not to modify unless you want to change IOR. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **ROUGHNESS** | Roughness (0..1). |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **RIM** | Rim (0..1). If used, Pandemonium calculates rim lighting. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **RIM_TINT** | Rim Tint, goes from 0 (white) to 1 (albedo). If used, Pandemonium calculates rim lighting. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **CLEARCOAT** | Small added specular blob. If used, Pandemonium calculates Clearcoat. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **CLEARCOAT_GLOSS** | Gloss of Clearcoat. If used, Pandemonium calculates Clearcoat. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **RIM** | Rim (0..1). If used, Pandemonium calculates rim lighting. |
| out float **RIM_TINT** | Rim Tint, goes from 0 (white) to 1 (albedo). If used, Pandemonium calculates rim lighting. |
| out float **CLEARCOAT** | Small added specular blob. If used, Pandemonium calculates Clearcoat. |
| out float **CLEARCOAT_GLOSS** | Gloss of Clearcoat. If used, Pandemonium calculates Clearcoat. |
| out float **ANISOTROPY** | For distorting the specular blob according to tangent space. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out vec2 **ANISOTROPY_FLOW** | Distortion direction, use with flowmaps. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **SSS_STRENGTH** | Strength of Subsurface Scattering. If used, Subsurface Scattering will be applied to object. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out vec3 **TRANSMISSION** | Transmission mask (default 0,0,0). Allows light to pass through object. Only applied if used. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out vec3 **EMISSION** | Emission color (can go over 1,1,1 for HDR). |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **AO** | Strength of Ambient Occlusion. For use with pre-baked AO. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **AO_LIGHT_AFFECT** | How much AO affects lights (0..1; default 0). |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| sampler2D **SCREEN_TEXTURE** | Built-in Texture for reading from the screen. Mipmaps contain increasingly blurred copies. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| sampler2D **DEPTH_TEXTURE** | Built-in Texture for reading depth from the screen. Must convert to linear using INV_PROJECTION. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| out float **DEPTH** | Custom depth value (0..1). |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in vec2 **SCREEN_UV** | Screen UV coordinate for current pixel. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
| in vec2 **POINT_COORD** | Point Coordinate for drawing points with POINT_SIZE. |
+-----------------------------------+--------------------------------------------------------------------------------------------------+
Note:
Shaders going through the transparent pipeline when `ALPHA` is written to
may exhibit transparency sorting issues. Read the
`transparency sorting section in the 3D rendering limitations page ( doc_3d_rendering_limitations_transparency_sorting )`
for more information and ways to avoid issues.
Light built-ins
^^^^^^^^^^^^^^^
#### Light built-ins
Writing light processor functions is completely optional. You can skip the light function by setting
render_mode to `unshaded`. If no light function is written, Pandemonium will use the material
@ -340,62 +232,40 @@ Warning:
**Rendering > Quality > Shading > Force Vertex Shading** is enabled in the
Project Settings. (It's enabled by default on mobile platforms.)
+-----------------------------------+-----------------------------------------------------+
| Built-in | Description |
+===================================+=====================================================+
|-----------------------------------|-----------------------------------------------------|
| in float **TIME** | Elapsed total time in seconds. |
+-----------------------------------+-----------------------------------------------------+
| in vec2 **VIEWPORT_SIZE** | Size of viewport (in pixels). |
+-----------------------------------+-----------------------------------------------------+
| in vec4 **FRAGCOORD** | Coordinate of pixel center in screen space. |
| | `xy` specifies position in window, `z` |
| | specifies fragment depth if `DEPTH` is not used. |
| | `xy` specifies position in window, `z` |
| | specifies fragment depth if `DEPTH` is not used. |
| | Origin is lower-left. |
+-----------------------------------+-----------------------------------------------------+
| in mat4 **WORLD_MATRIX** | Model space to world space transform. |
+-----------------------------------+-----------------------------------------------------+
| in mat4 **INV_CAMERA_MATRIX** | World space to view space transform. |
+-----------------------------------+-----------------------------------------------------+
| in mat4 **CAMERA_MATRIX** | View space to world space transform. |
+-----------------------------------+-----------------------------------------------------+
| in mat4 **PROJECTION_MATRIX** | View space to clip space transform. |
+-----------------------------------+-----------------------------------------------------+
| in mat4 **INV_PROJECTION_MATRIX** | Clip space to view space transform. |
+-----------------------------------+-----------------------------------------------------+
| in vec3 **NORMAL** | Normal vector, in view space. |
+-----------------------------------+-----------------------------------------------------+
| in vec2 **UV** | UV that comes from vertex function. |
+-----------------------------------+-----------------------------------------------------+
| in vec2 **UV2** | UV2 that comes from vertex function. |
+-----------------------------------+-----------------------------------------------------+
| in vec3 **VIEW** | View vector, in view space. |
+-----------------------------------+-----------------------------------------------------+
| in vec3 **LIGHT** | Light Vector, in view space. |
+-----------------------------------+-----------------------------------------------------+
| in vec3 **ATTENUATION** | Attenuation based on distance or shadow. |
+-----------------------------------+-----------------------------------------------------+
| in bool **OUTPUT_IS_SRGB** | `true` when calculations happen in sRGB color |
| | space (`true` in GLES2, `false` in GLES3). |
+-----------------------------------+-----------------------------------------------------+
| in bool **OUTPUT_IS_SRGB** | `true` when calculations happen in sRGB color |
| | space (`true` in GLES2, `false` in GLES3). |
| in vec3 **ALBEDO** | Base albedo. |
+-----------------------------------+-----------------------------------------------------+
| in vec3 **LIGHT_COLOR** | Color of light multiplied by energy. |
+-----------------------------------+-----------------------------------------------------+
| out float **ALPHA** | Alpha (0..1); if written to, the material will go |
| | to the transparent pipeline. |
+-----------------------------------+-----------------------------------------------------+
| in float **ROUGHNESS** | Roughness. |
+-----------------------------------+-----------------------------------------------------+
| in vec3 **TRANSMISSION** | Transmission mask from fragment function. |
+-----------------------------------+-----------------------------------------------------+
| out vec3 **DIFFUSE_LIGHT** | Diffuse light result. |
+-----------------------------------+-----------------------------------------------------+
| out vec3 **SPECULAR_LIGHT** | Specular light result. |
+-----------------------------------+-----------------------------------------------------+
Note:
Shaders going through the transparent pipeline when `ALPHA` is written to
may exhibit transparency sorting issues. Read the
`transparency sorting section in the 3D rendering limitations page ( doc_3d_rendering_limitations_transparency_sorting )`

141
03_usage/16_shaders/shader_reference/03_canvas_item_shader.md
View File

@ -1,7 +1,6 @@
CanvasItem shaders
==================
# CanvasItem shaders
CanvasItem shaders are used to draw all 2D elements in Pandemonium. These include
all nodes that inherit from CanvasItems, and all GUI elements.
@ -10,57 +9,44 @@ CanvasItem shaders contain less built-in variables and functionality than Spatia
shaders, but they maintain the same basic structure with vertex, fragment, and
light processor functions.
Render modes
^^^^^^^^^^^^
#### Render modes
+---------------------------------+----------------------------------------------------------------------+
| Render mode | Description |
+=================================+======================================================================+
| **blend_mix** | Mix blend mode (alpha is transparency), default. |
+---------------------------------+----------------------------------------------------------------------+
| **blend_add** | Additive blend mode. |
+---------------------------------+----------------------------------------------------------------------+
| **blend_sub** | Subtractive blend mode. |
+---------------------------------+----------------------------------------------------------------------+
| **blend_mul** | Multiplicative blend mode. |
+---------------------------------+----------------------------------------------------------------------+
| **blend_premul_alpha** | Pre-multiplied alpha blend mode. |
+---------------------------------+----------------------------------------------------------------------+
| **blend_disabled** | Disable blending, values (including alpha) are written as-is. |
+---------------------------------+----------------------------------------------------------------------+
| **unshaded** | Result is just albedo. No lighting/shading happens in material. |
+---------------------------------+----------------------------------------------------------------------+
| **light_only** | Only draw on light pass. |
+---------------------------------+----------------------------------------------------------------------+
| **skip_vertex_transform** | VERTEX/NORMAL/etc need to be transformed manually in vertex function.|
+---------------------------------+----------------------------------------------------------------------+
Built-ins
^^^^^^^^^
| Render mode | Description |
|---------------------------------|-----------------------------------------------------------------------|
| **blend_mix** | Mix blend mode (alpha is transparency), default. |
| **blend_add** | Additive blend mode. |
| **blend_sub** | Subtractive blend mode. |
| **blend_mul** | Multiplicative blend mode. |
| **blend_premul_alpha** | Pre-multiplied alpha blend mode. |
| **blend_disabled** | Disable blending, values (including alpha) are written as-is. |
| **unshaded** | Result is just albedo. No lighting/shading happens in material. |
| **light_only** | Only draw on light pass. |
| **skip_vertex_transform** | VERTEX/NORMAL/etc need to be transformed manually in vertex function. |
#### Built-ins
Values marked as "in" are read-only. Values marked as "out" are for optional writing and will
not necessarily contain sensible values. Values marked as "inout" provide a sensible default
value, and can optionally be written to. Samplers are not subjects of writing and they are
not marked.
Global built-ins
^^^^^^^^^^^^^^^^
#### Global built-ins
Global built-ins are available everywhere, including custom functions.
+-------------------+-----------------------------------------------------------------------------+
| Built-in | Description |
+===================+=============================================================================+
|-------------------|-----------------------------------------------------------------------------|
| in float **TIME** | Global time since the engine has started, in seconds (always positive). |
| | It's subject to the rollover setting (which is 3,600 seconds by default). |
| | It's not affected by `time_scale( Engine_property_time_scale )` |
| | or pausing, but you can override the `TIME` variable's time scale by |
| | calling `VisualServer.set_shader_time_scale()` with the desired |
| | time scale factor as parameter (`1.0` being the default). |
+-------------------+-----------------------------------------------------------------------------+
| | It's not affected by `time_scale( Engine_property_time_scale )` |
| | or pausing, but you can override the `TIME` variable's time scale by |
| | calling `VisualServer.set_shader_time_scale()` with the desired |
| | time scale factor as parameter (`1.0` being the default). |
Vertex built-ins
^^^^^^^^^^^^^^^^
#### Vertex built-ins
Vertex data (`VERTEX`) is presented in local space (pixel coordinates, relative to the camera).
If not written to, these values will not be modified and be passed through as they came.
@ -111,38 +97,27 @@ is usually:
* **y**: Phase during lifetime (0 to 1).
* **z**: Animation frame.
+--------------------------------+----------------------------------------------------------------+
| Built-in | Description |
+================================+================================================================+
|--------------------------------|----------------------------------------------------------------|
| in mat4 **WORLD_MATRIX** | Image space to view space transform. |
+--------------------------------+----------------------------------------------------------------+
| in mat4 **EXTRA_MATRIX** | Extra transform. |
+--------------------------------+----------------------------------------------------------------+
| in mat4 **PROJECTION_MATRIX** | View space to clip space transform. |
+--------------------------------+----------------------------------------------------------------+
| in vec4 **INSTANCE_CUSTOM** | Instance custom data. |
+--------------------------------+----------------------------------------------------------------+
| in bool **AT_LIGHT_PASS** | `true` if this is a light pass. |
+--------------------------------+----------------------------------------------------------------+
| in bool **AT_LIGHT_PASS** | `true` if this is a light pass. |
| inout vec2 **VERTEX** | Vertex, in image space. |
+--------------------------------+----------------------------------------------------------------+
| in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of default 2D texture. |
| | For a Sprite with a texture of size 64x32px, |
| | **TEXTURE_PIXEL_SIZE** = :code:`vec2(1/64, 1/32)` |
+--------------------------------+----------------------------------------------------------------+
| inout vec2 **UV** | Texture coordinates. |
+--------------------------------+----------------------------------------------------------------+
| inout vec4 **COLOR** | Color from vertex primitive. |
+--------------------------------+----------------------------------------------------------------+
| in vec4 **MODULATE** | Final modulate color. |
| | If used, **COLOR** will not be multiplied by modulate |
| | automatically after the fragment function. |
+--------------------------------+----------------------------------------------------------------+
| inout float **POINT_SIZE** | Point size for point drawing. |
+--------------------------------+----------------------------------------------------------------+
Fragment built-ins
^^^^^^^^^^^^^^^^^^
#### Fragment built-ins
Certain Nodes (for example, `Sprites`) display a texture by default. However,
when a custom fragment function is attached to these nodes, the texture lookup needs to be done
@ -162,50 +137,35 @@ it to the `NORMALMAP` property. Pandemonium will handle converting it for use in
NORMALMAP = texture(NORMAL_TEXTURE, UV).rgb;
```
+----------------------------------+----------------------------------------------------------------+
| Built-in | Description |
+==================================+================================================================+
| in vec4 **FRAGCOORD** | Coordinate of pixel center. In screen space. `xy` specifies |
| | position in window, `z` specifies fragment depth if |
| | `DEPTH` is not used. Origin is lower-left. |
+----------------------------------+----------------------------------------------------------------+
|----------------------------------|----------------------------------------------------------------|
| in vec4 **FRAGCOORD** | Coordinate of pixel center. In screen space. `xy` specifies |
| | position in window, `z` specifies fragment depth if |
| | `DEPTH` is not used. Origin is lower-left. |
| inout vec3 **NORMAL** | Normal read from **NORMAL_TEXTURE**. Writable. |
+----------------------------------+----------------------------------------------------------------+
| out vec3 **NORMALMAP** | Configures normal maps meant for 3D for use in 2D. If used, |
| | overwrites **NORMAL**. |
+----------------------------------+----------------------------------------------------------------+
| inout float **NORMALMAP_DEPTH** | Normalmap depth for scaling. |
+----------------------------------+----------------------------------------------------------------+
| in vec2 **UV** | UV from vertex function. |
+----------------------------------+----------------------------------------------------------------+
| inout vec4 **COLOR** | Color from vertex function and output fragment color. If |
| | unused, will be set to **TEXTURE** color. |
+----------------------------------+----------------------------------------------------------------+
| in vec4 **MODULATE** | Final modulate color. |
| | If used, **COLOR** will not be multiplied by modulate |
| | automatically after the fragment function. |
+----------------------------------+----------------------------------------------------------------+
| in sampler2D **TEXTURE** | Default 2D texture. |
+----------------------------------+----------------------------------------------------------------+
| in sampler2D **NORMAL_TEXTURE** | Default 2D normal texture. |
+----------------------------------+----------------------------------------------------------------+
| in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of default 2D texture. |
| | For a Sprite with a texture of size 64x32px, |
| | **TEXTURE_PIXEL_SIZE** = :code:`vec2(1/64, 1/32)` |
+----------------------------------+----------------------------------------------------------------+
| in vec2 **SCREEN_UV** | Screen UV for use with **SCREEN_TEXTURE**. |
+----------------------------------+----------------------------------------------------------------+
| in vec2 **SCREEN_PIXEL_SIZE** | Size of individual pixels. Equal to inverse of resolution. |
+----------------------------------+----------------------------------------------------------------+
| in vec2 **POINT_COORD** | Coordinate for drawing points. |
+----------------------------------+----------------------------------------------------------------+
| in bool **AT_LIGHT_PASS** | `true` if this is a light pass. |
+----------------------------------+----------------------------------------------------------------+
| in bool **AT_LIGHT_PASS** | `true` if this is a light pass. |
| in sampler2D **SCREEN_TEXTURE** | Screen texture, mipmaps contain gaussian blurred versions. |
+----------------------------------+----------------------------------------------------------------+
Light built-ins
^^^^^^^^^^^^^^^
#### Light built-ins
Light processor functions work differently in 2D than they do in 3D. In CanvasItem shaders, the
shader is called once for the object being drawn, and then once for each light touching that
@ -215,50 +175,35 @@ that object; this can be useful when you only want the object visible where it i
When the shader is on a light pass, the `AT_LIGHT_PASS` variable will be `true`.
+-------------------------------------+-------------------------------------------------------------------------------+
| Built-in | Description |
+=====================================+===============================================================================+
| in vec4 **FRAGCOORD** | Coordinate of pixel center. In screen space. `xy` specifies |
| | position in window, `z` specifies fragment depth if |
| | `DEPTH` is not used. Origin is lower-left. |
+-------------------------------------+-------------------------------------------------------------------------------+
|-------------------------------------|-------------------------------------------------------------------------------|
| in vec4 **FRAGCOORD** | Coordinate of pixel center. In screen space. `xy` specifies |
| | position in window, `z` specifies fragment depth if |
| | `DEPTH` is not used. Origin is lower-left. |
| in vec3 **NORMAL** | Input Normal. Although this value is passed in, |
| | **normal calculation still happens outside of this function**. |
+-------------------------------------+-------------------------------------------------------------------------------+
| in vec2 **UV** | UV from vertex function, equivalent to the UV in the fragment function. |
+-------------------------------------+-------------------------------------------------------------------------------+
| in vec4 **COLOR** | Input Color. |
| | This is the output of the fragment function (with final modulation applied, |
| | if **MODULATE** is not used in any function of the shader). |
+-------------------------------------+-------------------------------------------------------------------------------+
| in vec4 **MODULATE** | Final modulate color. |
| | If used, **COLOR** will not be multiplied by modulate |
| | automatically after the fragment function. |
+-------------------------------------+-------------------------------------------------------------------------------+
| sampler2D **TEXTURE** | Current texture in use for CanvasItem. |
+-------------------------------------+-------------------------------------------------------------------------------+
| in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of default 2D texture. |
| | For a Sprite with a texture of size 64x32px, |
| | **TEXTURE_PIXEL_SIZE** = :code:`vec2(1/64, 1/32)` |
+-------------------------------------+-------------------------------------------------------------------------------+
| in vec2 **SCREEN_UV** | **SCREEN_TEXTURE** Coordinate (for using with screen texture). |
+-------------------------------------+-------------------------------------------------------------------------------+
| in vec2 **POINT_COORD** | UV for Point Sprite. |
+-------------------------------------+-------------------------------------------------------------------------------+
| inout vec2 **LIGHT_VEC** | Vector from light to fragment in local coordinates. It can be modified to |
| | alter illumination direction when normal maps are used. |
+-------------------------------------+-------------------------------------------------------------------------------+
| inout vec2 **SHADOW_VEC** | Vector from light to fragment in local coordinates. It can be modified to |
| | alter shadow computation. |
+-------------------------------------+-------------------------------------------------------------------------------+
| inout float **LIGHT_HEIGHT** | Height of Light. Only effective when normals are used. |
+-------------------------------------+-------------------------------------------------------------------------------+
| inout vec4 **LIGHT_COLOR** | Color of Light. |
+-------------------------------------+-------------------------------------------------------------------------------+
| in vec2 **LIGHT_UV** | UV for Light texture. |
+-------------------------------------+-------------------------------------------------------------------------------+
| out vec4 **SHADOW_COLOR** | Shadow Color of Light. |
+-------------------------------------+-------------------------------------------------------------------------------+
| inout vec4 **LIGHT** | Value from the Light texture and output color. Can be modified. If not used, |
| | the light function is ignored. |
+-------------------------------------+-------------------------------------------------------------------------------+

13
03_usage/16_shaders/your_first_shader/01_index.md
View File

@ -1,11 +1,11 @@
Your first shader
=================
# Your first shader
This tutorial series will walk you through writing your first shader. It is intended
for people who have very little prior experience with shaders and want to get started
with the basics. This tutorial will not cover advanced topics and it is not
comprehensive. For a comprehensive and detailed overview of shaders in Pandemonium see the
`Shading Reference Page <toc-shading-reference )`.
`Shading Reference Page ( toc-shading-reference )`.
The "your first shader" tutorials walk you through the process of writing a shader
step-by-step.
@ -13,10 +13,3 @@ step-by-step.
For a more general introduction into shaders and the OpenGL Shading Language, use
`The Book of Shaders ( https://thebookofshaders.com )`.
.. toctree::
:maxdepth: 1
:name: toc-your-first-shader
your_first_2d_shader
your_first_3d_shader
your_second_3d_shader

35
03_usage/16_shaders/your_first_shader/02_your_first_2d_shader.md
View File

@ -1,10 +1,8 @@
Your first 2D shader
====================
# Your first 2D shader
Introduction
------------
## Introduction
Shaders are special programs that execute on the GPU and are used for rendering
graphics. All modern rendering is done with shaders. For a more detailed
@ -16,12 +14,12 @@ walking you through the process of writing a shader with both vertex and
fragment functions. This tutorial targets absolute beginners to shaders.
Note:
If you have experience writing shaders and are just looking for an
overview of how shaders work in Pandemonium, see the `Shading Reference
<toc-shading-reference )`.
( toc-shading-reference )`.
Setup
-----
## Setup
`CanvasItem ( doc_canvas_item_shader )` shaders are used to draw all 2D
objects in Pandemonium, while `Spatial ( doc_spatial_shader )` shaders are
@ -43,7 +41,7 @@ To begin, create a Sprite node. You can use any CanvasItem, but for this
tutorial we will use a Sprite.
In the Inspector, click beside "Texture" where it says "[empty]" and select
"Load", then select "Icon.png)". For new projects, this is the Pandemonium icon. You
"Load", then select "Icon.png". For new projects, this is the Pandemonium icon. You
should now see the icon in the viewport.
Next, look down in the Inspector, under the CanvasItem section, click beside
@ -57,8 +55,7 @@ Click beside "Shader" and select "New Shader". Finally, click on the new shader
resource and the shader editor will open. You are now ready to begin writing
your first shader.
Your first CanvasItem shader
----------------------------
## Your first CanvasItem shader
In Pandemonium, all shaders start with a line specifying what type of shader they are.
It uses the following format:
@ -79,8 +76,7 @@ writing a shader with both vertex and fragment functions. Light functions are
significantly more complex than vertex and fragment functions and so will not be
covered here.
Your first fragment function
----------------------------
## Your first fragment function
The fragment function runs for every pixel in a Sprite and determines what color
that pixel should be.
@ -129,8 +125,7 @@ other functions or to assign values to `COLOR` directly.
![](img/UV.png)
Using `TEXTURE` built-in
^^^^^^^^^^^^^^^^^^^^^^^^^^
#### Using `TEXTURE` built-in
When you want to adjust a color in a Sprite you cannot just adjust the color
from the texture manually like in the code below.
@ -158,8 +153,7 @@ can be accessed in the shader using `TEXTURE`. Use it together with `UV` and
![](img/blue-tex.png)
Uniform input
^^^^^^^^^^^^^
#### Uniform input
Uniform input is used to pass data into a shader that will be the same across
the entire shader.
@ -190,8 +184,7 @@ called "Shader Param". Unfold that section and you will see the uniform you just
declared. If you change the value in the editor, it will overwrite the default
value you provided in the shader.
Interacting with shaders from code
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#### Interacting with shaders from code
You can change uniforms from code using the function `set_shader_param()`
which is called on the node's material resource. With a Sprite node, the
@ -205,8 +198,7 @@ following code can be used to set the `blue` uniform.
Note that the name of the uniform is a string. The string must match exactly
with how it is written in the shader, including spelling and case.
Your first vertex function
--------------------------
## Your first vertex function
Now that we have a fragment function, let's write a vertex function.
@ -237,8 +229,7 @@ animation.
}
```
Conclusion
----------
## Conclusion
At their core, shaders do what you have seen so far, they compute `VERTEX` and
`COLOR`. It is up to you to dream up more complex mathematical strategies for

22
03_usage/16_shaders/your_first_shader/03_your_first_3d_shader.md
View File

@ -1,7 +1,6 @@
Your first 3D shader
====================
# Your first 3D shader
You have decided to start writing your own custom Spatial shader. Maybe you saw
a cool trick online that was done with shaders, or you have found that the
@ -25,14 +24,14 @@ are going to take the concepts from this tutorial and walk through how to set up
custom materials in a fragment shader by writing an ocean water shader.
Note:
This tutorial assumes some basic shader knowledge such as types
(`vec2`, `float`, `sampler2D`), and functions. If you are
uncomfortable with these concepts it is best to get a gentle
introduction from `The Book of Shaders
( https://thebookofshaders.com )` before completing this tutorial.
Where to assign my material
---------------------------
## Where to assign my material
In 3D, objects are drawn using `Meshes`. Meshes are a resource
type that store geometry (the shape of your object) and materials (the color and
@ -59,8 +58,7 @@ instance then you should set the material on the Meshinstance.
For this tutorial we will set our material on the mesh itself rather than taking
advantage of the MeshInstance's ability to override materials.
Setting up
----------
## Setting up
Add a new `MeshInstance` node to your scene.
@ -97,8 +95,7 @@ Now click beside "Shader" where it says "[empty]" and select "New Shader".
The shader editor should now pop up and you are ready to begin writing your
first Spatial shader!
Shader magic
------------
## Shader magic
![](img/shader-error.png)
@ -157,8 +154,7 @@ What we want to achieve is the look of little hills; after all. `cos` and
This looks better, but it is still too spiky and repetitive, let's make it a
little more interesting.
Noise heightmap
---------------
## Noise heightmap
Noise is a very popular tool for faking the look of terrain. Think of it as
similar to the cosine function where you have repeating hills except, with
@ -218,8 +214,7 @@ Right now it is too spiky, we want to soften the hills a bit. To do that, we
will use a uniform. You already used a uniform above to pass in the noise
texture, now let's learn how they work.
Uniforms
--------
## Uniforms
Uniform variables allow you to pass data from the game into the shader. They are
very useful for controlling shader effects. Uniforms can be almost any datatype
@ -269,8 +264,7 @@ Using uniforms, we can even change the value every frame to animate the height
of the terrain. Combined with `Tweens`, this can be
especially useful for simple animations.
Interacting with light
----------------------
## Interacting with light
First, turn wireframe off. To do so, click in the upper-left of the Viewport
again, where it says "Perspective", and select "Display Normal".

14
03_usage/16_shaders/your_first_shader/04_your_second_3d_shader.md
View File

@ -1,7 +1,6 @@
Your second 3D shader
=====================
# Your second 3D shader
From a high-level, what Pandemonium does is give the user a bunch of parameters that
can be optionally set (`AO`, `SSS_Strength`, `RIM`, etc.). These
@ -20,8 +19,7 @@ vertex function runs per vertex and sets properties such as `VERTEX`
(position) and `NORMAL`, while the fragment shader runs per pixel and, most
importantly, sets the `ALBEDO` color of the `Mesh( MeshInstance )`.
Your first spatial fragment function
------------------------------------
## Your first spatial fragment function
As mentioned in the previous part of this tutorial. The standard use of the
fragment function in Pandemonium is to set up different material properties and let
@ -179,8 +177,7 @@ Let's set them to `vec3(0.01, 0.03, 0.05)`.
![](img/dark-water.png)
Animating with `TIME`
-----------------------
## Animating with `TIME`
Going back to the vertex function, we can animate the waves using the built-in
variable `TIME`.
@ -240,8 +237,7 @@ This results in waves that move slowly, but not in a very natural way. The next
section will dig deeper into using shaders to create more complex effects, in
this case realistic waves, by adding a few more mathematical functions.
Advanced effects: waves
-----------------------
## Advanced effects: waves
What makes shaders so powerful is that you can achieve complex effects by using
math. To illustrate this, we are going to take our waves to the next level by
@ -347,5 +343,5 @@ to do was add a bit of math!
For more information about Spatial shaders read the `Shading Language
( doc_shading_language )` doc and the `Spatial Shaders ( doc_spatial_shader )`
doc. Also look at more advanced tutorials in the `Shading section
<toc-learn-features-shading )` and the `3D <toc-learn-features-3d )`
( toc-learn-features-shading )` and the `3D ( toc-learn-features-3d )`
sections.

63
03_usage/17_performance/01_introduction.md
View File

@ -1,10 +1,8 @@
Optimization
============
# Optimization
Introduction
------------
## Introduction
Pandemonium follows a balanced performance philosophy. In the performance world,
there are always trade-offs, which consist of trading speed for usability
@ -39,60 +37,3 @@ With this clear, the aim of this tutorial section is to explain how to get the
maximum performance out of Pandemonium. While the tutorials can be read in any order,
it is a good idea to start from `doc_general_optimization`.
Common
------
.. toctree::
:maxdepth: 1
:name: toc-learn-features-general-optimization
general_optimization
using_servers
CPU
---
.. toctree::
:maxdepth: 1
:name: toc-learn-features-cpu-optimization
cpu_optimization
GPU
---
.. toctree::
:maxdepth: 1
:name: toc-learn-features-gpu-optimization
gpu_optimization
using_multimesh
2D
--
.. toctree::
:maxdepth: 1
:name: toc-learn-features-2d-optimization
batching
3D
--
.. toctree::
:maxdepth: 1
:name: toc-learn-features-3d-optimization
optimizing_3d_performance
vertex_animation/index
Multi-threading
---------------
.. toctree::
:maxdepth: 1
:name: toc-learn-features-threads
threads/thread_safe_apis
threads/using_multiple_threads