Lua GLSL Api

From Spring

Development < Lua Scripting < Lua GLSL Api

These functions are ONLY available if the graphic board supports GLSL.

Please test in your scripts if one of them exists before you use them!


gl.CreateShader

 ({[ 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", ]
 }) -> number shaderID
  • 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:
uniform float frame;
  • From 101.0 onwards, the engine will automatically fill in an appropriately named uniform for team colour if it is declared;
uniform vec4 teamColor;

gl.DeleteShader

 ( number shaderID ) -> nil

gl.ActiveShader can be used in NON-drawing events (to update uniforms etc.)!

 ( number shaderID, function [, arg1 [, arg2, ..]] ) -> nil

gl.UseShader

 ( number shaderID ) -> boolean linked

gl.GetShaderLog

 ( ) -> string "infoLog"

gl.SetShaderParameter Renamed to SetGeometryShaderParameter in spring version >= 104.0.1-596 (maintenance). needed by geometry shader programs (check the opengl GL_ARB_geometry_shader4 extension for glProgramParameteri)

 ( number shaderID, number param, number value ) -> nil

gl.SetTesselationShaderParameter Available for spring versions >= 104.0.1-596 (maintenance). needed by tesselation shader programs (check the opengl GL_ARB_tessellation_shader extension for glProgramParameteri)

 ( number param, number value ) -> nil

gl.GetActiveUniforms

 ( number shaderID ) -> { 
     [1] = { name = "name", type = "type", length = number length, size = number size },
     ...
   }

gl.GetUniformLocation

 ( number shaderID, name uniformName ) -> number locationID

gl.Uniform

 ( number locationID, number f1 [,number f2 [,number f3 [,number f4]]] ) -> nil

gl.UniformInt

 ( number locationID, number int1 [,number int2 [,number int3 [,number int4]]] ) -> nil

gl.UniformArray New in version 95.0

 ( number locationID, number type, table uniforms ) -> nil

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, 
   "shadow" |
   "camera" |
   "caminv" |
   "camprj" |
   number m1, number m2, number m3, number m4 |
   number m1, ... , number m9 |
   number m1, ... , number m16
 ) -> nil