From 94c244f45811f7252700f39b08654f2c2e358859 Mon Sep 17 00:00:00 2001 From: Relintai Date: Tue, 30 Apr 2024 20:48:19 +0200 Subject: [PATCH] Cleanups. --- .../shader_reference/01_shading_language.md | 349 +++++------------- .../shader_reference/02_spatial_shader.md | 262 ++++--------- .../shader_reference/03_canvas_item_shader.md | 141 +++---- .../16_shaders/your_first_shader/01_index.md | 13 +- .../02_your_first_2d_shader.md | 35 +- .../03_your_first_3d_shader.md | 22 +- .../04_your_second_3d_shader.md | 14 +- 03_usage/17_performance/01_introduction.md | 63 +--- 8 files changed, 227 insertions(+), 672 deletions(-) diff --git a/03_usage/16_shaders/shader_reference/01_shading_language.md b/03_usage/16_shaders/shader_reference/01_shading_language.md index 3926a1d..5abc0bc 100644 --- a/03_usage/16_shaders/shader_reference/01_shading_language.md +++ b/03_usage/16_shaders/shader_reference/01_shading_language.md @@ -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` | + diff --git a/03_usage/16_shaders/shader_reference/02_spatial_shader.md b/03_usage/16_shaders/shader_reference/02_spatial_shader.md index f1f938c..d86011e 100644 --- a/03_usage/16_shaders/shader_reference/02_spatial_shader.md +++ b/03_usage/16_shaders/shader_reference/02_spatial_shader.md @@ -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 )` diff --git a/03_usage/16_shaders/shader_reference/03_canvas_item_shader.md b/03_usage/16_shaders/shader_reference/03_canvas_item_shader.md index c856491..802baa3 100644 --- a/03_usage/16_shaders/shader_reference/03_canvas_item_shader.md +++ b/03_usage/16_shaders/shader_reference/03_canvas_item_shader.md @@ -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. | -+-------------------------------------+-------------------------------------------------------------------------------+ + diff --git a/03_usage/16_shaders/your_first_shader/01_index.md b/03_usage/16_shaders/your_first_shader/01_index.md index 4eae327..002af33 100644 --- a/03_usage/16_shaders/your_first_shader/01_index.md +++ b/03_usage/16_shaders/your_first_shader/01_index.md @@ -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