A shader is a GPU program there are four types currently supported. Vertex, which process the vertices position send on the GPU. Fragment is used to calculate the shading of pixels. Compute that allows you to run generic computation on the GPU and store the result to a Texture that can also be transferred to local memory for CPU processing. Finally, geometry (C/C++ only) that allows you to process primitives (as in triangles, lines etc...)
Shaders are attached to a Material that in turn provides available Texture (aka. Sampler) to the program. Sampler can be used in your program for texture mapping and other types of processing. Without a Shader attached a Material is unable to draw anything; either on screen or to a render target.
To give you a higher level of flexibility uniforms, an external variable that is declared inside your program. This special type of variable that can then be modified at runtime to drive certain parameters or to steer the internal behavior of your shader.
See Also
Name | Description |
---|---|
asset | Reference to the parent Asset where the Shader is contained. |
vertex_code | Stream that contains the raw vertex shader Shader code. |
fragment_code | Stream that contains the raw fragment shader Shader code. |
vertex_shader | Stream containing the parsed, converted and optionally optimized vertex shader code ready to be sent to GPU. |
fragment_shader | Stream containing the parsed, converted and optionally optimized fragment shader code ready to be sent to GPU. |
nodetree | Reference to the NodeTree used for visual Shader node programming. |
compute | Compute reference handling the settings of a compute Shader. |
attribute_count | Total amount of Attribute currently available within your Shader. |
uniform_count | Amount of Uniform variables present in your Shader. |
Name | Description |
---|---|
optimize | Enable or disable Shader optimization (editor only). |
revision | Internal code revision number. |
Name | Description |
---|---|
SetUniformInt | Helper to update an integer Uniform value. |
SetUniformFloat | Helper to update a float Uniform value. |
SetUniformVec2 | Update an existing two dimensional Uniform value. |
SetUniformVec3 | Update an existing vector 3d or color (RGB) Uniform value. |
SetUniformVec4 | Update an existing four dimensional vector or color (RGBA) Uniform value. |
SetUniformMat2 | Helper to set the value of a two dimensional Uniform matrix. |
SetUniformMat3 | Remove a RenderLayer by index. |
SetUniformMat4 | Function that update the value of a 4x4 Uniform matrix value. |
SetUniformArray | Helper to update an existing Uniform array. |
GetUniformInt | Retrieve the value of an integer Uniform. |
GetUniformFloat | Retrieve the value of a floating point Uniform. |
GetUniformVec2 | Retrieve the value of a two dimensional vector Uniform. |
GetUniformVec3 | Retrieve the value of a tri dimensional vector or color (RGB) Uniform. |
GetUniformVec4 | Retrieve the value of a 4d ector or color (RGBA) Uniform. |
GetUniformMat2 | Helper to retrieve the current 2x2 matrix value assigned to an existing Uniform. |
GetUniformMat3 | Helper to retrieve the current 3x3 matrix value assigned to an existing Uniform. |
GetUniformMat4 | Helper to retrieve the current 4x4 matrix value assigned to an existing Uniform. |
UseNodes | Enable or disable the use of a NodeTree for the current Shader. |
IsUsingNodes | Function to determine whether or not the active Shader is using nodes to generate its code. |
Build | Build the current Shader and create/update it on GPU. |
GetUniformAt | Generic helper to access a specific Uniform. |
GetAttributeAt | Directly access a specific Attribute by index. |
SetStorageSize | Function to set the storage size of a Compute Shader. |
SetStorage | Helper to assign a specific storage Texture to an existing compute Shader slot. |
GetStorage | Helper that returns the active storage Texture reference for a specific slot. |
Available settings when the Shader type is set to kCompute
.
Name | Description |
---|---|
size | Current size of the data set that will be handled by the compute Shader. |
absolute | Determine wheter or not the size of the compute Shader is absolute (pixels) or a ratio relative to the backbuffer size. |
width | The width of the compute Shader data set. |
height | The height of the compute Shader data set. |
workgroup | Size of the compute Shader workgroup that will be handling the data set. |
Structure to access read-only values and properties of a Uniform value.
Name | Description |
---|---|
type | The internal data type of the Uniform (as specified by OpenGL & ES). |
index | Index assigned to the Uniform is the case it is a Sampler. |
_int | Access the integer value assigned to the active Uniform. |
_float | Access the floating point value assigned to the active Uniform. |
_vec2 | Access the 2d vector value assigned to the active Uniform. |
_vec3 | Access the 3d vector value assigned to the active Uniform. |
_vec4 | Access the 4d vector value assigned to the active Uniform. |
_mat2 | Access the 2x2 matrix value assigned to the active Uniform. |
_mat3 | Access the 3x3 matrix value assigned to the active Uniform. |
_mat4 | Access the 4x4 matrix value assigned to the active Uniform. |
Read-only properties and settings of a Uniform defined inside a Shader code. By default, all uniforms will be accessible just like a regular member variable accessible from within the editor.
However, in the event, you do not want this variable to be access during development and strictly want to control it using code (either by Script or using a C/C++ plugin) simply add an _
to its name.
In example declaring the following: uniform float _gKernelSize;
will prevent _gKernelSize
to be accessed by the user. Removing the _
at the beginning of the Uniform name will tell the system to treat it as a regular member variable available to the user of the Shader.
Additionally applicable on uniforms of the type vec3
and vec4
; adding the keyword color
(case insensitive) will tell the system that the Uniform should be treated as RGB or RGBA and not a vector. As an example declaring uniform vec4 light_color;
will allow you to have access to the color picker while modifying the Uniform within the editor; while just calling it: uniform vec4 light;
will consider the Uniform as a regular 4d vector.
Name | Description |
---|---|
location | Internal location index assigned to the Uniform by the GPU. |
builtin | Determine wheter or not the Uniform is user defined or builtin. |
constant | Boolean that represent if the Uniform is a constant or a mutable value. |
value | Access the UniformValue of the Uniform. |
name | The name of the Uniform. |
A structure that accesses the active properties and settings of the vertex attributes contained in the Shader code.
Name | Description |
---|---|
location | Internal location index assigned to the Attribute by the GPU. |
type | The internal data type of the Attribute (as specified by OpenGL & ES). |
index | Index assigned to the Attribute is the case it is a Sampler. |
builtin | Boolean value that determine if the Attribute is builtin or user defined. |
name | The name of the Attribute as defined in the Shader code. |
Constant identifier to represent the type of Shader that can be accessed through the scripting interface.
kVertex
: Identify a vertex shader.kFragment
: Identify a fragment shader.kCompute
: Identify a compute shader.To facilitate writing shader and to bridge the underlying API with GLSL various type of builtins
variables and definitions are at your disposal. The following subsections list and explain each and every one of them that are available while writing your shaders.
Name | Description |
---|---|
POSITION | Vertex position in model space. |
WEIGHT | Weight index and count. |
POINTSIZE | Point size of the vertex. |
NORMAL | Vertex normal in model space. |
TEXCOORD | Texture coordinates for the channel pointed by index. |
TANGENT | Tangent coordinates for the channel pointed by index. |
COLOR | Vertex color for the channel pointed by index. |
Name | Description |
---|---|
SAMPLER | Predefined uniform sampler definition for each type supported. |
gfx_ModelViewMatrix | 4x4 matrix evaluated by multiplying the active model matrix with the active view matrix. |
gfx_ProjectionMatrix | The projection matrix of the active Camera. |
gfx_ModelViewProjectionMatrix | The current 4x4 modelview matrix multiplied by the active projection matrix. |
gfx_ViewMatrix | The 4x4 view matrix of the active Camera. |
gfx_ModelMatrix | Active model matrix used to transform each Geometry vertex. |
gfx_NormalMatrix | 3x3 matrix that contains the normalized rotational part of the model matrix. |
gfx_ViewMatrixInverseTranspose | The inverse and transposed modelview matrix allowing to convert back (ie) normals to worldspace. |
gfx_Viewport | Active viewport boundaries; where xy represent its location on the backbuffer and zw the width and height. |
gfx_Stats | Access the current statistics. |
gfx_Mirror | Allows you to detect mirrored instanced Geometry and invert its culling/normal direction. |
gfx_CameraPosition | Active camera location in world space. |
gfx_CameraDirection | Normalized direction vector of the active camera in world space. |
For each definition listed below all, you have to do use them within your shader is to copy and paste their associated code. Once the Shader parser detect them it will automatically append and fill the value of the definition.
In example writing #define MOBILE
in your Shader will result in the following input that will be sent to the GPU: #define MOBILE 1
(1
meaning that NRG is running on a mobile device and 0
means a regular desktop PC.)
Name | Description |
---|---|
MOBILE | Allows you to determine if the Shader is compiled on a mobile device (1 ) or on a regular desktop PC (0 ). |
GPU_TYPE | The type of GPU compiler the Shader have been compiled with. |
BACKBUFFER_WIDTH | The width of the backbuffer in pixel (total application screen width). |
BACKBUFFER_HEIGHT | The height of the backbuffer (available screen width). |
To ensure compatibility with all systems the way compute shader is written have been unified and simplified to mimic a regular fragment shader. Take the code below in example based on the ShaderToy default shader which has been converted to work with the NRG compute shader system:
uniform vec4 gfx_Stats; // Built-in frame stats uniform.
uniform vec4 gfx_Viewport; // Built-in viewport uniform.
void main() {
vec2 uv = gl_FragCoord.xy / vec2( gfx_Viewport.z, gfx_Viewport.w ); // Normalized pixel coordinates (from 0 to 1)
vec3 col = 0.5 + 0.5*cos((gfx_Stats.y)+uv.xyx+vec3(0,2,4)); // Time varying pixel color using the current frame number.
gl_FragData[0] = vec4(col,1.0); // Output to storage at index 0.
}
As you can see code above is no different from a regular fragment shader that render to texture; the only exception is that the rendering will be outputted into a kStorage
texture instead of a kAttachment
.
In other words, writing a compute shader using NRG is basically the same as writing a fragment shader. The internal system will handle all the conversion work (and optionally even writing the data set output to local memory) to ensure that your compute shaders can be reused as a regular fragment shader on platforms that do not support them.
To insure a proper integration on modern, mobile and/or compute shader extensions on older systems; the Shader parser will automatically enable the following features:
#extension GL_ARB_shading_language_420pack : enable
#extension GL_ARB_shader_image_load_store : enable
#extension GL_ARB_compute_shader : enable
To facilitate coding by reusing existing code, functions and global definitions throughout multiple Shader the instruction #pragma include
is available in your toolset. Since not all versions on OpenGL and OpenGLES support the include instructions (either natively or through extension) this alternate method handled directly by the internal parser allows you to connect existing Shader code using this directive.
If the #pragma include
directive is included inside a vertex shader the vertex code of the Shader will be available; the same rule applies if it is a fragment shader.
To use the directive inside your code all you have to do is to add the following statement: #pragma include "dir/shader_asset_name"
. Once the Shader gets compiled the internal parser will automatically extract the path and will look for the Shader Asset specified and append the appropriate code at the location where the directive is declared.
//#pragma include "dir/shader_asset_name"
#pragma include "shaders/common"
Another directive is also available to you to deal with uniform variables; #pragma parameter
. Using it before the uniform declaration will allow you to specify its range, step and default value.
The following example illustrate how to use and format the directive.
//#pragma parameter <uniform_name> "<comment>" <min_value> <max_value> <step> <default_value>
#pragma parameter g_MyExposure "Exposure Level." 0.0 2.0 0.1 1.25
uniform float g_MyExposure;
|