Module Shaders

Shader creation and management

These functions are ONLY available if the graphics adapter supports GLSL. Please test in your scripts if one of them exists before you use them. In headless mode, the gl. callouts are nil.

See also:

Functions

gl.GetShaderLog
Returns the shader compilation error log.
gl.CreateShader
Create a shader from shaderParams table:
gl.DeleteShader
Deletes a shader identified by shaderID
gl.UseShader
Binds a shader program identified by shaderID.
gl.ActiveShader
Binds a shader program identified by shaderID, and calls the Lua func with the specified arguments.
gl.GetActiveUniforms
Query the active (actually used) uniforms of a shader and identify their names, types (float, int, uint) and sizes (float, vec4, ...).
gl.GetUniformLocation
Returns the locationID of a shaders uniform.
gl.Uniform
Sets the uniform float value at the locationID for the currently active shader.
gl.UniformInt
Sets the uniform int value at the locationID for the currently active shader.
gl.UniformArray
Sets the an array of uniform values at the locationID for the currently active shader.
gl.UniformMatrix
Sets the a uniform mat4 locationID for the currently active shader.
gl.GetEngineUniformBufferDef
gl.GetEngineModelUniformDataDef
gl.SetGeometryShaderParameter
Sets the Geometry shader parameters for shaderID.
gl.SetTesselationShaderParameter
Sets the tesselation shader parameters for shaderID.

Functions

gl.GetShaderLog()

Returns the shader compilation error log.

This is empty if the shader linking failed, in that case, check your in/out blocks and ensure they match.

Returns:

  1. string infoLog

gl.CreateShader(shaderParams)

Create a shader from shaderParams table:

( table shaderParams )

Parameters:

  1. shaderParams table

Returns:

  1. number

    shaderID

    ({[ vertex   = "glsl code" ,]
  [ tcs      = "glsl code" ,]
  [ tes      = "glsl code" ,]
  [ geometry = "glsl code" ,]
  [ fragment = "glsl code" ,]
  [ uniform       = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
  [ uniformInt    = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
  [ uniformFloat  = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
  [ uniformMatrix = { uniformName = number value, ...} ,]
  [ geoInputType = number inType,]
  [ geoOutputType = number outType,]
  [ geoOutputVerts = number maxVerts,]
  [ definitions = "string of shader #defines", ]
})
    • The "Vertex" or vertex-shader is your GLSL-Code as string, its written in a C-Dialect. This shader is busy deforming the geometry of a unit but it can not create new polygons. Use it for waves, wobbling surfaces etc.
    • The "Geometry" or Geometry-shader can create new vertices and vertice-stripes from points.
    • The "TCS" or Tesselation Control Shader controls how much tessellation a particular patch gets; it also defines the size of a patch, thus allowing it to augment data. It can also filter vertex data taken from the vertex shader. The main purpose of the TCS is to feed the tessellation levels to the Tessellation primitive generator stage, as well as to feed patch data (as its output values) to the Tessellation Evaluation Shader stage.
    • The "TES" or Tesselation Evaluation Shader takes the abstract patch generated by the tessellation primitive generation stage, as well as the actual vertex data for the entire patch, and generates a particular vertex from it. Each TES invocation generates a single vertex. It can also take per-patch data provided by the Tessellation Control Shader.
    • The "Fragment" or Fragment-shader (sometimes called pixel-Shader) is post processing the allready rendered picture (for example drawing stars on the sky)- remember textures are not always 2 dimensional pictures. They can contain information about the depth, or the third value marks areas and the strength at which these are processed.
    • The Uniforms are the values, you send along with the shader-program. To use them in the shader-program declare them like this: uniform float frame;

    The engine will automatically fill in an appropriately named uniform for team colour if it is declared;

    uniform vec4 teamColor;

gl.DeleteShader(shaderID)

Deletes a shader identified by shaderID

Parameters:

  1. shaderID number

Returns:

  1. nil

gl.UseShader(shaderID)

Binds a shader program identified by shaderID.

Pass 0 to disable the shader. Returns wether the shader was successfully bound.

Parameters:

  1. shaderID number

Returns:

  1. bool linked

gl.ActiveShader(shaderID, func[, arg1[, arg2[, argn]]])

Binds a shader program identified by shaderID, and calls the Lua func with the specified arguments.

Can be used in NON-drawing events (to update uniforms etc.)!

Parameters:

  1. shaderID number
  2. func func
  3. arg1 any (optional)
  4. arg2 any (optional)
  5. argn any (optional)

Returns:

  1. nil

gl.GetActiveUniforms(shaderID)

Query the active (actually used) uniforms of a shader and identify their names, types (float, int, uint) and sizes (float, vec4, ...).

Parameters:

  1. shaderID number

Returns:

  1. table ActiveUniforms = { { name = "name", type = "type", length = number length, size = number size }, ...}

gl.GetUniformLocation(shaderID, name)

Returns the locationID of a shaders uniform.

Needed for changing uniform values with @function gl.Uniform.

Parameters:

  1. shaderID number
  2. name string

Returns:

  1. number locationID

gl.Uniform(locationID, f1[, f2[, f3[, f4]]])

Sets the uniform float value at the locationID for the currently active shader.

Shader must be activated before setting uniforms.

Parameters:

  1. locationID number |string uniformName
  2. f1 number
  3. f2 number (optional)
  4. f3 number (optional)
  5. f4 number (optional)

Returns:

  1. nil

gl.UniformInt(locationID, int1[, int2[, int3[, int4]]])

Sets the uniform int value at the locationID for the currently active shader.

Shader must be activated before setting uniforms.

Parameters:

  1. locationID number |string uniformName
  2. int1 number
  3. int2 number (optional)
  4. int3 number (optional)
  5. int4 number (optional)

Returns:

  1. nil

gl.UniformArray(locationID, type, uniforms)

Sets the an array of uniform values at the locationID for the currently active shader.

Shader must be activated before setting uniforms. Type can be one of {1 = int, 2 = float, 3 = float matrix}.

Parameters:

  1. locationID number |string uniformName
  2. type number
  3. uniforms table Array up to 1024 elements

Returns:

  1. nil

gl.UniformMatrix(locationID, m1[, m2[, mn[, m16]]])

Sets the a uniform mat4 locationID for the currently active shader.

Shader must be activated before setting uniforms. Can set one one common matrix like shadow, or by passing 16 additional numbers for the matrix.

Parameters:

  1. locationID number |string uniformName
  2. m1 string or number "shadows" | "camera" | "caminv" | "camprj"
  3. m2 number (optional)
  4. mn number (optional)
  5. m16 number (optional)

Returns:

  1. nil

gl.GetEngineUniformBufferDef(index)

Return the GLSL compliant definition of UniformMatricesBuffer(idx=0) or UniformParamsBuffer(idx=1) structure.

Parameters:

  1. index number

Returns:

  1. string glslDefinition

gl.GetEngineModelUniformDataDef(index)

Return the GLSL compliant definition of ModelUniformData structure (per Unit/Feature buffer available on GPU)

Parameters:

  1. index number

Returns:

  1. string glslDefinition

gl.SetGeometryShaderParameter(shaderID, param, number)

Sets the Geometry shader parameters for shaderID.

Needed by geometry shader programs (check the opengl GL_ARB_geometry_shader4 extension for glProgramParameteri)

Parameters:

  1. shaderID number
  2. param number
  3. number number

Returns:

  1. nil

gl.SetTesselationShaderParameter(param, number)

Sets the tesselation shader parameters for shaderID.

Needed by tesselation shader programs (check the opengl GL_ARB_tessellation_shader extension for glProgramParameteri)

Parameters:

  1. param number
  2. number number

Returns:

  1. nil