Shader

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

Static Variables


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.

Variables


Name Description
optimize Enable or disable Shader optimization (editor only).
revision Internal code revision number.

Functions


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.

Compute


Available settings when the Shader type is set to kCompute.

Static Variables


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.

UniformValue


Structure to access read-only values and properties of a Uniform value.

Static Variables


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.

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.

Static Variables


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.

Attribute


A structure that accesses the active properties and settings of the vertex attributes contained in the Shader code.

Static Variables


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.

ShaderType


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.

Builtins


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.

Attributes


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.

Uniforms


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.

Variables


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).

Compute Shader


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:

  • GLSL
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

Pragma Include


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.

  • GLSL
//#pragma include "dir/shader_asset_name"
#pragma include "shaders/common"

Pragma Parameter


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.

  • GLSL
//#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;




NRG - API 2022.4.384543 - Fri Nov 4 2022
Copyright © 2022 nrgcore.com. All Rights Reserved. Terms of Service - Privacy Policy - EULA