Lua GLSL Api

Development < Lua Scripting < Lua GLSL Api

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.

gl.CreateShader ( table shaderParams )
return: number shaderID

Create a shader from shaderParams table:

 ({[ 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. TCS shader can be used with spring version >= 104.0.1-596 (maintenance), it's also available in develop branch of spring.

• 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. TES shader can be used with spring version >= 104.0.1-596 (maintenance), it's also available in develop branch of spring.

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

<syntaxhighlight lang="c">uniform float frame;</syntaxhighlight>

• From 101.0 onwards, the engine will automatically fill in an appropriately named uniform for team colour if it is declared;

<syntaxhighlight lang="c">uniform vec4 teamColor;</syntaxhighlight>

gl.DeleteShader ( number shaderID )
return: nil

Deletes a shader identified by shaderID

gl.ActiveShader ( number shaderID, function func [, arg1 [, arg2 ... ] ] )
return: nil

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

gl.UseShader ( number shaderID )
return: bool linked

Binds a shader program identified by shaderID. Pass 0 to disable the shader. Returns wether the shader was successfully bound.

gl.GetShaderLog ( )
return: string infoLog

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.

gl.SetGeometryShaderParameter ( number shaderID, number param, number number )
return: nil

Sets the Geometry shader parameters for shaderID. Needed by geometry shader programs (check the opengl GL_ARB_geometry_shader4 extension for glProgramParameteri)
Was called SetShaderParameter before 104.0.1-596 (maintenance)

gl.SetTesselationShaderParameter ( number param, number number )
return: nil

Sets the tesselation shader parameters for shaderID. Needed by tesselation shader programs (check the opengl GL_ARB_tessellation_shader extension for glProgramParameteri)
Introduced in 104.0.1-596 (maintenance)

gl.GetActiveUniforms ( number shaderID )
return: table ActiveUniforms = { { name = "name", type = "type", length = number length, size = number size }, ...}

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

gl.GetUniformLocation ( number shaderID, string "name" )
return: number locationID

Returns the locationID of a shaders uniform. Needed for changing uniform values with gl.Uniform.

gl.Uniform ( number locationID, number f1 [, number f2 [, number f3 [, number f4 ] ] ] )
return: nil

Sets the uniform float value at the locationID for the currently active shader. Shader must be activated before setting uniforms.

gl.UniformInt ( number locationID, number int1 [, number int2 [, number int3 [, number int4 ] ] ] )
return: nil

Sets the uniform int value at the locationID for the currently active shader. Shader must be activated before setting uniforms.

gl.UniformArray ( number locationID, number type, table uniforms )
return: nil

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}. In 104.0 the maximum length of the uniforms table increased from 32 entries to 1024.

gl.UniformMatrix ( number locationID, string "shadows" | "camera" | "caminv" | "camprj" | number m1, number m2, number m3, number m4, number m5, number m6, number m7, number m8 ... , m16 )
return: nil

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.