Lua OpenGL Api

Development < Lua Scripting < Lua OpenGL Api

Contents

Spring

gl.GetSun 

 ()        -> number sunPosX, number sunPosY, number sunPosZ
 ( "pos" ) -> number sunPosX, number sunPosY, number sunPosZ
 ( "shadowDensity" [, "unit"] ) -> number shadowDensity
 ( "diffuse"       [, "unit"] ) -> nil | number r, number g, number b
 ( "ambient"       [, "unit"] ) -> nil | number r, number g, number b
 ( "specular" )                 -> nil | number r, number g, number b

gl.ConfigScreen used for Unit LODs 

 ( number screenWidth, number screenDistance ) -> nil

gl.DrawMiniMap argument new in 0.82+ 

 ( boolean tansform = true ) -> nil

gl.SlaveMiniMap 

 ( boolean mode ) -> nil

gl.ConfigMiniMap 

 ( int px, int py, int sx, int sy ) -> nil

gl.GetViewSizes 

 ( ) -> number x, number y


Matrices & Viewport

gl.Viewport 

 ( number x, number y, number w, number h ) -> nil

gl.PushMatrix 

 () -> nil

gl.PopMatrix 

 () -> nil

gl.Translate 

 (number x, number y, number z) -> nil

gl.Scale 

 ( number x, number y, number z ) -> nil

gl.Rotate 

 ( number angle, number x, number y, number z ) -> nil

gl.Billboard 

 ( ) -> nil

Use this to draw 2d primitives in DrawWorld(). To render a 2D billboarded quad in the gameworld at world position x,y,z, you do the following (at a minimum; I am skipping blending / depthtesting) here: 

 gl.PushMatrix()
 gl.Texture(read what you need here)
 gl.Translate(x,y,z)
 gl.Billboard()			
 gl.TexRect(x1,y1,x2,y2)
 gl.PopMatrix()

gl.MatrixMode 

 ( number mode ) -> nil

gl.LoadIdentity 

 ( ) -> nil

gl.LoadMatrix 

 ( ) -> nil

gl.MultMatrix 

 ( ?? ) -> ??

gl.Ortho 

 ( number left, number right, number bottom, number top, number near, number far ) -> nil

gl.Frustum 

 ( number left, number right, number bottom, number top, number near, number far ) -> nil

gl.PushPopMatrix 

 ( ?? ) -> ??

gl.ClipPlane 

 ( int plane, note: $plane can only be 1 or 2
 boolean enable |
 number A, number B, number C, number D ) -> nil

Clear

gl.Clear 

 ( GL.DEPTH_BUFFER_BIT [, number cleardepth] ) -> nil
 ( GL.STENCIL_BUFFER_BIT [, int clearstencil] ) -> nil
 ( GL.COLOR_BUFFER_BIT | GL.ACCUM_BUFFER_BIT [, number r, number g, number b, number a] ) -> nil


ResetState/Matrices

gl.ResetState DON'T USE IT UNLESS YOU KNOW WHAT YOU ARE DOING! Each call-in has different default states, but this function resets all states to the states below no matter what! 

 () -> nil


 ShadeModel = GL.SMOOTH
 Scissor    = false
 Texture    = false
 Lighting    = false,
 ColorMask  = true, true, true, true
 DepthMask  = false
 DepthTest  = false  (GL.LEQUAL)
 Culling    = false  (GL.BACK)
 LogicOp    = false  (GL.INVERT)
 AlphaTest  = false  (GL.GREATER, 0.5f)
 Blending   = true (GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA)

gl.ResetMatrices 

 () -> nil


 Resets GL.TEXTURE matrix stack
 Resets GL.MODELVIEW matrix stack
 Resets GL.PROJECTION matrix stack


Draw Basics

gl.BeginEnd 

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

gl.Color 

 ( { number r, number g, number b[, number a] } |
     number r, number g, number b[, number a] ) -> nil

gl.Vertex 

 ( { number x, number y [, number z [, number w ]] } |
   number x, number y |
   number x, number y, number z |
   number x, number y, number z, number w ) -> nil

gl.Normal 

 (  number x, number y, number z |
  { number x, number y, number z } ) -> nil

gl.EdgeFlag 

 ( boolean enable ) -> nil

gl.Rect 

 ( number x1, number y1, number x2, number y2 ) -> nil

gl.TexRect texture rect 

 ( number x1, number y1, number x2, number y2,
 [ boolean flip_s, boolean flip_t | number s1, number t1, number s2, number t2 ] ) -> nil

gl.Shape 

( number GLtype,
  elements = {
    [1] = { v | vertex   = { number x, number y, number z },           required
            n | normal   = { number x, number y, number z },           optional
            t | texcoord = { number x, number y },                     optional
            c | color    = { number r, number g, number b, number a }  optional
    },
    etc ...
  }
) -> nil

gl.SecondaryColor 

 ( { number r, number g, number b } |
     number r, number g, number b ) -> nil

gl.FogCoord 

 ( number value ) -> nil


Display Lists

Display Lists save given vertex attributes in a static buffer, so the GPU can directly read them (without the CPU). Display Lists are a lot faster (10-60x) than standard drawing with glShape/glBeginEnd, so try to use them when ever you can. If you want to learn more about them, g00gle is your friend ;)

gl.CreateList 

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

gl.CallList 

 ( number listID ) -> nil

gl.DeleteList 

 ( number listID ) -> nil


Text

gl.Text 

 (string "text", number x, number y, number size [, string "options"] )


 options are:
   horizontal alignment:
      'c' = center
      'r' = right
   vertical alignment:
      'a' = ascender
      't' = top
      'v' = vertical center
      'x' = baseline
      'b' = bottom
      'd' = descender
   decorations:
      'o' = black outline
      'O' = white outline
      's' = shadow
   other:
      'n' = don't round vertex coords to nearest integer (font may get blurry)

fontlines.png


gl.GetTextWidth 

 (string "text") -> number width  (in pixels, with a font size of 1.0)

gl.GetTextHeight 

 ( string "text" ) -> nil | number height, number descender, number numlines (in pixels, with a font size of 1.0)
 further descriptions here: GetTextHeight


If you have multiple gl.Text calls, then you can bunch them between a gl.BeginText and gl.EndText to speedup the rendering.
gl.BeginText 

 ( ) -> nil

gl.EndText 

 ( ) -> nil

Unit/Feature Draw Functions

gl.Unit (draws an unit; on default it uses LOD, with lod<0 it is turned off, else it defines a specific level) 

 ( number unitID, [ boolean rawdraw, int lod ] ) -> nil

gl.UnitRaw (doesn't apply worldspace->unit transformation! only works if rawdraw is true ) 

 ( number unitID, [ boolean rawdraw, int lod ] ) -> nil

gl.UnitShape 

 ( number unitDefID, number teamID ) -> nil

gl.Feature 

 ( number featureID ) -> nil

gl.FeatureShape 

 ( number featureDefID, number teamID ) -> nil

gl.UnitMultMatrix (world space -> unit space) 

 ( number unitID ) -> nil

gl.UnitPieceMultMatrix (unit space -> piece space) 

 ( number unitID, int piece ) -> nil

gl.UnitPiece (draws the unit piece) 

 ( number unitID, int piece ) -> nil

gl.UnitPieceMatrix (use gl.UnitPieceMultMatrix instead!) 

 ( number unitID, int piece ) -> nil

gl.DrawListAtUnit 

 ( number unitID, number listID, [ boolean midPos,
     number scaleX, number scaleY, number scaleZ,
     number degrees, number rotX, number rotX, number rotZ ] ) -> nil

gl.DrawFuncAtUnit 

 ( number unitID, boolean midPos, function [, arg1,... ]) -> nil


States (Blending,AlphaTest...)

gl.Blending 

 ( boolean enable | number srcmode, number dstmode ) -> nil
 ( string mode ) -> nil
mode maybe:
"add" = GL.ONE, GL.ONE
"alpha_add" = GL.SRC_ALPHA, GL.ONE
"alpha" = GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA
"reset" = GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA
"color" = GL.SRC_COLOR, GL.ONE_MINUS_SRC_ALPHA
"modulate" = GL.DST_COLOR, GL.ZERO
"disable" = GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA


gl.BlendEquation 

 ( number mode ) -> nil

gl.BlendFunc 

 ( number srcmode, number dstmode ) -> nil

gl.BlendEquationSeparate (needs openGL2.0!) 

 ( number modeRGB, number modeAlpha ) -> nil

gl.BlendFuncSeparate (needs openGL2.0!) 

 ( number srcRGB, number dstRGB,  number srcAlpha, number dstAlpha ) -> nil

gl.AlphaTest 

 ( boolean enable | number func, number threshold ) -> nil

gl.DepthTest 

 ( boolean enable | number func ) -> nil

gl.Culling 

 ( boolean enable | number face ) -> nil

gl.DepthClamp not always available, needs GL.NV_depth_clamp! 

 ( boolean enable ) -> nil

gl.DepthMask 

 ( boolean enable ) -> nil

gl.ColorMask 

 ( boolean ) -> nil
 ( boolean r, boolean g, boolean b, boolean a ) -> nil

gl.LogicOp 

 ( boolean enable | number func ) -> nil

gl.Fog 

 ( boolean enable ) -> nil

gl.Smoothing 

( (boolean enable | number POINT), 
  (boolean enable | number LINE),
  (boolean enable | number POLYGON) ) -> nil

gl.EdgeFlag 

( boolean enable ) -> nil

gl.Scissor 

 ( boolean ) -> nil
 ( int x, int y, int w, int h ) -> nil

gl.LineStipple 

 ( string any ) -> nil (use springs default line stipple)
 ( boolean enable ) -> nil
 ( int factor, number pattern ) -> nil

gl.PolygonMode 

 ( number face, number mode ) -> nil

gl.PolygonOffset 

 ( boolean enable | number factor, number units ) -> nil

gl.PushAttrib 

 ( [ number attrib ] ) -> nil

gl.PopAttrib 

 () -> nil

Stencil

gl.StencilTest 

 ( boolean enable ) -> nil

gl.StencilMask 

 ( number mask ) -> nil

gl.StencilFunc 

 ( number func, number ref, number mask ) -> nil

gl.StencilOp 

 ( number fail, number zfail, number zpass ) -> nil


gl.StencilMaskSeparate (needs openGL2.0!) 

 ( number face, number mask ) -> nil

gl.StencilFuncSeparate (needs openGL2.0!) 

 ( number face, number func, number ref, number mask ) -> nil

gl.StencilOpSeparate (needs openGL2.0!) 

 ( number face, number fail, number zfail, number zpass ) -> nil


LineWidth & PointSize

gl.LineWidth 

 ( number width ) -> nil

gl.PointSize (values != 1 can break severely on ATI cards, see http://springrts.com/mantis/view.php?id=2390) 

 ( number size ) -> nil

gl.PointSprite (needs openGL2.0!) 

 ( boolean enable, [boolean coord_replace, boolean coord_origin_upper] ) -> nil

gl.PointParameter (needs openGL2.0!) 

 ( number v1, number v2, number v3, 
   [ number sizeMin, number sizeMax, number sizeFade ] ) -> nil

Textures

gl.Texture 

 ( [ number texNum, ] boolean enable | string name ) -> nil | boolean loaded

This is the only call-out that is needed to load and draw any texture in a Lua script. All you have to do is pass it a valid path to a valid png and it will use that image for drawing any subsequent textured rectangles. This is shown in the last line of the following list of valid strings for the name parameter.


`name` maybe:
#12 = unitDef 12 buildpic
 %34:1 = unitDef 34 s3o tex2 (:0->tex1,:1->tex2)
 %-102:0 = featureDef 102 s3o tex1
 !56 = lua generated texture 56 (= return value of gl.CreateTexture)
$units = 3do textureatlas tex1
$units1 = 3do textureatlas tex1
$units2 = 3do textureatlas tex2
$shadow = shadowmap
$specular = specular cube map
$reflection = reflection cube map
$shading = ground shading texture
$grass = grass shading texture
$heightmap = heightmap (needs HeightMapTexture=1 set in spring config)
$minimap = minimap texture
$info = info texture (los, airlos, radar, jammer)
${opt}:/LuaUI/images/image.png = load a texture from the VFS 
  possible ${opt}'s are:
     'n' = nearest
     'l' = linear
     'a' = aniso
     'i' = invert
     'g' = greyed
     'c' = clamped
     'b' = border
     't%r,%g,%b' = tint
     'r%width,%height' = resize

   example: ":iac:/LuaUI/images/image.png"
   example: ":cr16,16:/LuaUI/images/image.png"
   example2: ":t1.0,0.5,0:/LuaUI/images/image.png"  (orange tint)

gl.CreateTexture 

 ( int xsize, int ysize,
 [ { 
   [target     = number,] (like GL.TEXTURE_1D,GL.TEXTURE_2D,...)
   [format     = number,]
   [min_filter = number,]
   [mag_filter = number,]
   [wrap_s     = number,]
   [wrap_t     = number,]
   [wrap_r     = number,]
   [aniso      = number,]
   [border     = boolean,]
   [fbo        = boolean,] (needs GLEW_EXT_framebuffer_object!)
   [fboDepth   = boolean] (needs GLEW_EXT_framebuffer_object!)
 } ]
 ) -> string

gl.DeleteTexture 

 ( string texture ) -> boolean

gl.DeleteTextureFBO (needs GLEW_EXT_framebuffer_object!) 

 ( string texture ) -> boolean

gl.TextureInfo 

 ( string texture ) -> nil | {
     xsize = number,
     ysize = number,
     alpha = boolean, //not used yet
     type  = number,  //not used yet
   }


  the format of the texture string is the same as in gl.Texture()

gl.TexCoord 

 ( number x | 
   number x, number y |
   number x, number y, number z |
   number x, number y, number z, number w |
   { number x [, number y [, number z [, number w ]]] } ) -> nil

gl.MultiTexCoord 

 ( int texNum,
   number x |
   number x, number y |
   number x, number y, number z |
   number x, number y, number z, number w |
   { number x [, number y [, number z [, number w ]]] } ) -> nil

gl.TexEnv 

 ( number target, number pname,
   number value |
   number var1, number var2, number var3 ) -> nil

gl.MultiTexEnv 

 ( int texNum, number target, number pname,
   number value |
   number var1, number var2, number var3 ) -> nil

gl.TexGen 

 ( number target,
   boolean state |
   number pname, number value |
   number pname, number var1, number var2, number var3 ) -> nil

gl.MultiTexGen 

 ( int texNum, number target,
   boolean state |
   number pname, number value |
   number pname, number var1, number var2, number var3 ) -> nil

gl.CopyToTexture 

 (string texture, int xoff, int yoff, int x, int y, int w, int h 
 [,number target,number level])->nil

gl.RenderToTexture (needs GLEW_EXT_framebuffer_object!) 

 ( string fbotexture, lua_func ) -> nil

gl.GenerateMipmap (needs glGenerateMipmapEXT!) 

 ( string texture ) -> boolean

PixelReadback

gl.SaveImage 

 ( number x, number y, number w, number h,
   string filename [, table {alpha=boolean, yflip=boolean} ] ) -> nil | boolean success

gl.ReadPixels 

 ( number x, number y, number w, number h [, number format = GL.RGBA ] )
   -> nil 
   | number r,[g,[b,[a]]] 
   | table { { {1 = number r, 2 = number g, 3 = number b, 4 = number a}, ... }, ... }

Lights

gl.Lighting 

 ( boolean enable ) -> nil

gl.ShadeModel 

 ( number mode ) -> nil

gl.Light 

 ( int light, 
 boolean enable |
 number pname, number param |
 number pname, number param1, number param2, number param3 ) -> nil

gl.Material 

 ({
   ambient   = {number r, number g, number b[, number a]},
   diffuse   = {number r, number g, number b[, number a]},
   ambidiff  = {number r, number g, number b[, number a]},
   emission  = {number r, number g, number b[, number a]},
   specular  = {number r, number g, number b[, number a]},
   shininess = number specularExponent
 }) -> nil


Hardware relevant

gl.HasExtension 

 ( string extname ) -> boolean

gl.GetNumber 

 ( number ext, int count ) -> number [, number, number, ... #count ]

gl.GetString 

 ( number ext ) -> string


DrawGroundPrimitives

gl.DrawGroundCircle 

 ( number x, number y, number z, number radius, number divs [, number slope ] ) -> nil

Note: number divs is the number of sides the circle will have. the higher the smoother the circle (and more GPU intensive)


gl.DrawGroundQuad Note: x1,z1,x2 & z2 are rounded, so don't use it for very small or moving objects. x and z are correspond to the coordinates displayed by the tooltip 

 ( number x1, number z1, number x2, number z2,
   [ boolean useNorm, (does nothing!)
     [ number tu1, number tv1, number tu2, number tv2 |
       boolean useTextureCoord ] ] ) -> nil

Queries

gl.CreateQuery needs >=OpengGL2.0! 

 ( ) -> nil | userdata query

gl.DeleteQuery needs >=OpengGL2.0! 

 ( userdata query ) -> nil

gl.RunQuery needs >=OpengGL2.0! 

 ( userdata query, function, arg1, arg2, ... ) -> nil

gl.GetQuery needs >=OpengGL2.0! 

 ( userdata query ) -> nil | number renderedFragments


Extended

gl.ActiveTexture 

 ( int texNum, function [, arg1,... ] ) -> nil

gl.GetGlobalTexNames 

 () -> { [1] = string texture, etc ... }

gl.GetGlobalTexCoords gets the texcoord of a 3do texture in the 3do texture atlas 

 ( string 3doTextureName ) -> number xstart, number ystart, number xend, number yend

gl.UnsafeState 

 ( number state [, boolean disable_state ], function, arg1, arg2, ... ) -> nil
 Calls glEnable(state) or glDisable(state) (if disable_state==true) and
then calls the lua_function and afterwards reverts the state.

gl.GetShadowMapParams 

 () -> number xmid, number ymid, number p17, number p18

gl.GetMatrixData 

 ( GL.PROJECTION [, int i] ) -> nil | number, etc.. | number Matrix[i]
 ( GL.MODELVIEW  [, int i] ) -> nil | number, etc.. | number Matrix[i] 
 ( GL.TEXTURE    [, int i] ) -> nil | number, etc.. | number Matrix[i]
 ( "shadow" )                -> nil | number, etc.. 
 ( "camera" )                -> nil | number, etc.. 
 ( "caminv" )                -> nil | number, etc.. 
 ( "camprj" )                -> nil | number, etc.. 
 ( "billboard" )             -> nil | number, etc..

gl.Flush 

 () -> nil

gl.Finish 

 () -> nil

Shaders (GLSL) 

 Lua_GLSL_Api
Retrieved from "http://springrts.com/mediawiki/index.php?title=Lua_OpenGL_Api&oldid=26991"

 
 

Page editing toolbox

Browse
Main page
Community portal
Current events
Recent changes
Random page
Help
Edit
View source
Editing help
This page
Discuss this page
New section
Printable version
Context
Page history
What links here
Related changes
My pages
Log in
Special pages
New pages
<imagelist>
Statistics
More...

Site layout created by Roflcopter et al.