|
|
OpenGL binding for Lua 5.1 and 5.2 http://luagl.sourceforge.net |
|
|
|
OpenGL binding for Lua 5.1 and 5.2 http://luagl.sourceforge.net |
About · History · Usage · Reference
Its a library that provides access to all of the OpenGL (up to version 1.3) functionality from Lua.
OpenGL is a portable software interface to graphics hardware. More information about OpenGL can be obtained from http://www.opengl.org. You can find good tutorials about learning OpenGL at http://nehe.gamedev.net.
That library should run in all systems that support OpenGL.
LuaGL is a free software and uses the MIT License (the same License as Lua). It can be used at no cost for both academic and commercial purposes.
You can download LuaGL from the SourceForge files page.
LuaGL also needs that you have the OpenGL library installed. All modern operating systems already have it, see OpenGL Platform & OS Implementations.
The official support mechanism is by e-mail, using scuri@tecgraf.puc-rio.br.
We host the LuaGL support features at SourceForge: http://sourceforge.net/projects/luagl/. It provides us CVS Repository and Downloads.
Since this distribution does not include the GLUT binding, all the samples are based on the IUP toolkit. One sample uses IM to display an image. You can browse the samples here: examples.
This library works as a binding for all OpenGL commands, so you can have full access to the graphics hardware from Lua.
To have access the GL functions in Lua call require"luagl", or from a C host program you could call the 'luaopen_luagl' function. This will create a name space called 'gl', and all the functions and constants will be inside of it.
To have access the GLU functions in Lua call require"luaglu", or from a C host program you could call the 'luaopen_luaglu' function. This will create a name space called 'glu', and all the functions and constants will be inside of it.
Read the LINSTALL file for instructions on how to install the libraries on Linux.
Although the luagl and luaglu libraries have '51' and '52' suffixes they can be removed, by manually renaming the respective files. The only file that must retain its original name is the luagl_base library. This is valid for Windows and Linux. luagl_base is not a Lua module. (Since 1.8)
All OpenGL constants were also converted to strings, for example: instead of writing gl.QUADS, you can write 'QUADS'. Functions that expected a bitwise operation between mask parameters can receive a string that contains all the constants strings separated by comma (,). For example:
gl.Begin(gl.TRIANGLES) or gl.Begin("TRIANGLES")
gl.Clear(gl.COLOR_BUFFER_BIT+gl.DEPTH_BUFFER_BIT) or gl.Clear('COLOR_BUFFER_BIT,DEPTH_BUFFER_BIT')
OpenGL constants can be used as numbers using gl.XXX notation, where XXX is the constant name after "GL_" (for example: gl.QUADS). This is much faster than using the strings.
The argument specification (e.g., '2d', '3f', '4sv') at the end of most OpenGL functions names have been removed. For example the new gl.Light function binds the OpenGL functions: glLightf, glLightfv, glLighti, glLightiv.
The number of parameters defines the correct function to use. And it is always used the floating point version of the functions, with the highest possible precision.
Some functions that have a type parameter simply use the most precise possible (usually GL_DOUBLE or GL_FLOAT) and the parameter is not used. When stride is not used, then it is assumed to be 0.
Whenever is possible, GLboolean is mapped to boolean in Lua.
The color and the vector data can be represented by a lua array. A vector can have 2, 3 or 4 values (x, y, z, w), and colors can have 3 or 4 values (red, green, blue, alpha).
For example:
v1 = { 0, 0 }
v2 = { 1, 1 }
Yellow = { 1, 1, 0 }
gl.Color(Yellow)
gl.Vertex(v1)
gl.Vertex(v2)
you can also do:
gl.Color(1, 1, 0) gl.Vertex(0, 0) gl.Vertex(1, 1)
Arrays are handled as tables or as userdata. For example:
gl.DrawPixels (width, height, format, pixelsArray) -> none gl.DrawPixelsRaw (width, height, format, type, pixelsUserData) -> none
Using userdata is more efficient and less memory consuming, especially for large data. But individual values can NOT be accessed.
Some functions use a table that contains secondary tables, like in a 2D array. For example:
v1 = { -1, -1 }
v2 = { 1, -1 }
v3 = { 1, 1 }
v4 = { -1, 1 }
vertices = { v1, v2, v3, v4 }
gl.VertexPointer(vertices)
This function in particular accepts also a simple array as parameter, but must specify the number of elements of the secondary table:
vertices = { -1, -1, 1, -1, 1, 1, -1, 1}
gl.VertexPointer(vertices, 2)
This function also needs to keep its memory allocated after the call. So to release this internal memory you must call:
gl.VertexPointer(nil)
The functions that request information from OpenGL, will now return the data by the function return value. For example:
pixelsArray = gl.GetTexImage(target, level, format)
For more information about functions names and parameters, see the Function Reference bellow.
Functions that expects a number with a bit pattern, will accept a string with the mask numbers. All characters that are different to 0 and 1 will be ignored. For example:
gl.LineStipple(1, "1111000011110000") gl.LineStipple(1, "1010.0101.1000.1111") gl.LineStipple(1, "0000 0000 1111 1111")
gl.Accum (op, value) -> none gl.AlphaFunc (func, ref) -> none gl.AreTexturesResident (texturesArray) -> residencesArray gl.ArrayElement (i) -> none gl.Begin (mode) -> none gl.BindTexture (target, texture) -> none gl.Bitmap (xorig, yorig, xmove, ymove [, bitmapArray2]) -> none gl.BitmapRaw (width, height, xorig, yorig, xmove, ymove, bitmapUserData) -> none gl.BlendFunc (sfactor, dfactor) -> none gl.CallList (list) -> none gl.CallLists (listArray) -> none gl.Clear (mask) -> none gl.ClearAccum (red, green, blue, alpha) -> none gl.ClearColor (red, green, blue, alpha) -> none gl.ClearDepth (depth) -> none gl.ClearIndex (c) -> none gl.ClearStencil (s) -> none gl.ClipPlane (plane, equationArray) -> none gl.Color (red, green, blue [, alpha]) -> none gl.Color (colorArray) -> none gl.ColorMask (red, green, blue, alpha) -> none gl.ColorMaterial (face, mode) -> none gl.ColorPointer (colorArray2) -> none gl.ColorPointer (colorArray, size) -> none gl.ColorPointer (nil) -> none (releases internal memory) gl.CopyPixels (x, y, width, height, type) -> none gl.CopyTexImage (level, internalFormat, border, x, y, width[, height]) -> none gl.CopyTexSubImage (level, x, y, xoffset, width[, yoffset, height]) -> none gl.CullFace (mode) -> none gl.DeleteLists (list, range) -> none gl.DeleteTextures (texturesArray) -> none gl.DepthFunc (func) -> none gl.DepthMask (flag) -> none gl.DepthRange (zNear, zFar) -> none gl.Disable (cap) -> none gl.DisableClientState (array) -> none gl.DrawArrays (mode, first, count) -> none gl.DrawBuffer (mode) -> none gl.DrawElements (mode, indicesArray) -> none gl.DrawPixels (width, height, format, pixelsArray) -> none gl.DrawPixelsRaw (width, height, format, type, pixelsUserData) -> none gl.EdgeFlag (flag) -> none gl.EdgeFlag (flagArray) -> none gl.EdgeFlagPointer (flagsArray) -> none gl.EdgeFlagPointer (nil) -> none (releases internal memory) gl.Enable (cap) -> none gl.EnableClientState (array) -> none gl.End () -> none gl.EndList () -> none gl.EvalCoord (u[, v]) -> none gl.EvalCoord (coordArray) -> none gl.EvalMesh (mode, i1, i2[,j1, j2]) -> none gl.EvalPoint (i[, j]) -> none gl.FeedbackBuffer (size, type) -> dataArray gl.Finish () -> none gl.Flush () -> none gl.Fog (pname, param) -> none gl.Fog (pname, paramsArray) -> none gl.FrontFace (mode) -> none gl.Frustum (left, right, bottom, top, zNear, zFar) -> none gl.GenLists (range) -> num gl.GenTextures (n) -> texturesArray gl.Get (pname) -> param1, param2, param3, ... (not an array, a sequence of parameters) gl.GetArray (pname) -> paramsArray gl.GetConst (pname) -> string gl.GetClipPlane (plane) -> equationArray gl.GetError () -> error (nil if GL_NO_ERROR) gl.GetLight (light, pname) -> paramsArray gl.GetMap (target, query) -> vArray gl.GetMaterial (face, pname) -> paramsArray gl.GetPixelMap (map) -> valuesArray gl.GetPointer (pname, n) -> valuesArray gl.GetPolygonStipple () -> maskArray gl.GetString (name) -> string gl.GetTexEnv (pname) -> paramsArray gl.GetTexGen (coord, pname) -> paramsArray gl.GetTexImage (target, level, format) -> pixelsArray gl.GetTexImageRaw (target, level, format, type, pixelsUserData) -> none gl.GetTexLevelParameter (target, level, pname) -> param gl.GetTexParameter (target, pname) -> paramsArray gl.Hint (target, mode) -> none gl.Index (c) -> none gl.IndexMask (mask) -> none gl.IndexPointer (indexArray) -> none gl.IndexPointer (nil) -> none (releases internal memory) gl.InitNames () -> none gl.InterleavedArrays (format, dataArray) -> none gl.IsEnabled (cap) -> true/false gl.IsList (list) -> true/false gl.IsTexture (texture) -> true/false gl.Light (light, pname, param) -> none gl.Light (light, pname, paramsArray) -> none gl.LightModel (pname, param) -> none gl.LightModel (pname, paramsArray) -> none gl.LineStipple (factor, pattern) -> none gl.LineWidth (width) -> none gl.ListBase (base) -> none gl.LoadIdentity () -> none gl.LoadMatrix (mArray) -> none gl.LoadName (name) -> none gl.LogicOp (opcode) -> none gl.Map (target, u1, u2, pointsArray) -> none gl.Map (target, u1, u2, v1, v2, pointsArray2) -> none gl.MapGrid (un, u1, u2[, vn, v1, v2]) -> none gl.Material (face, pname, param) -> none gl.MatrixMode (mode) -> none gl.MultMatrix (mArray) -> none gl.NewList (list, mode) -> none gl.NewData (size) -> UserData (auxiliary function to allocate userdata) gl.FreeData (UserData) -> none gl.Normal (nx, ny, nz) -> none gl.Normal (nArray) -> none gl.NormalPointer (normalArray2) -> none gl.NormalPointer (normalArray, size) -> none gl.NormalPointer (nil) -> none (releases internal memory) gl.Ortho (left, right, bottom, top, zNear, zFar) -> none gl.PassThrough (token) -> none gl.PixelMap (map, valuesArray) -> none gl.PixelStore (pname, param) -> none gl.PixelTransfer (pname, param) -> none gl.PixelZoom (xfactor, yfactor) -> none gl.PointSize (size) -> none gl.PolygonMode (face, mode) -> none gl.PolygonOffset (factor, units) -> none gl.PolygonStipple (maskArray2) -> none gl.PolygonStipple (maskArray) -> none gl.PopAttrib () -> none gl.PopClientAttrib () -> none gl.PopMatrix () -> none gl.PopName () -> none gl.PrioritizeTextures (texturesArray, prioritiesArray) -> none gl.PushAttrib (mask) -> none gl.PushClientAttrib (mask) -> none gl.PushMatrix () -> none gl.PushName (GLuint name) -> none gl.RasterPos (x, y[, z, w]) -> none gl.RasterPos (vArray) -> none gl.ReadBuffer (mode) -> none gl.ReadPixels (x, y, width, height, format) -> pixelsArray gl.ReadPixelsRaw (x, y, width, height, format, type, pixelsUserData) -> none gl.Rect (x1, y1, x2, y2) -> none gl.Rect (v1, v2) -> none gl.RenderMode (mode) -> none gl.Rotate (angle, x, y, z) -> none gl.Scale (x, y, z) -> none gl.Scissor (x, y, width, height) -> none gl.SelectBuffer (size) -> SelectUserData gl.GetSelectBuffer(SelectUserData, index) -> value (return the value of a given index) gl.FreeSelectBuffer(SelectUserData) -> none gl.ShadeModel (mode) -> none gl.StencilFunc (func, ref, mask) -> none gl.StencilMask (mask) -> none gl.StencilOp (fail, zfail, zpass) -> none gl.TexCoord (s[, t, r, q]) -> none gl.TexCoord (vArray) -> none gl.TexCoordPointer (vArray2) -> none gl.TexCoordPointer (vArray, size) -> none gl.TexCoordPointer (nil) -> none (releases internal memory) gl.TexEnv (pname, param) -> none gl.TexEnv (pname, paramsArray) -> none gl.TexGen (coord, pname, param) -> none gl.TexGen (coord, pname, paramsArray) -> none gl.TexImage (level, internalformat, format, pixelsArray) -> none gl.TexImage (level, internalformat, format, pixelsArray2) -> none gl.TexImage1D (level, internalformat, width, border, format, type, pixelsUserData) -> none gl.TexImage2D (level, internalformat, width, height, border, format, type, pixelsUserData) -> none gl.TexParameter (target, pname, param) -> none gl.TexParameter (target, pname, paramsArray) -> none gl.TexSubImage (level, format, pixelsArray, xoffset[, yoffset]) -> none gl.TexSubImage (level, format, pixelsArray2, xoffset[, yoffset]) -> none gl.TexSubImage1D (level, xoffset, width, format, type, pixelsUserData) -> none gl.TexSubImage2D (level, xoffset, yoffset, width, height, format, type, pixelsUserData) -> none gl.Translate (x, y, z) -> none gl.Vertex (x, y, [z, w]) -> none gl.Vertex (vArray) -> none gl.VertexPointer (vertexArray2) -> none gl.VertexPointer (vertexArray, size) -> none gl.VertexPointer (nil) -> none (releases internal memory) gl.Viewport (x, y, width, height) -> none
glu.BuildMipmaps(components, format, pixelsArray) -> error
glu.BuildMipmaps(components, format, pixelsArray2) -> error
glu.Build1DMipmaps(components, width, format, type, pixelsUserData) -> error
glu.Build2DMipmaps(components, width, height, format, type, pixelsUserData) -> error
glu.Build2DMipmaps(textureArray2) -> error (alternative form)
(table must contain "target", "format", "type", "width", "height" and "components" fields)
(and data organized in lines as unnamed tables)
glu.Build3DMipmaps(components, width, height, depth, format, type, pixelsUserData) -> error
glu.ErrorString(errorCode) -> string
glu.GetString (name) -> string
glu.LookAt(Ex, Ey, Ez, Lx, Ly, Lz, Ux, Uy, Uz) -> none
glu.Ortho2D(left, right, bottom, top) -> none
glu.Perspective(fovy, aspect, near, far) -> none
glu.PickMatrix( x, y, deltax, deltay, viewportArray) -> none
glu.Project(objx, objy, objz, modelMatrixArray, projMatrixArray, viewportArray) -> error, winx, winy, winz
glu.ScaleImage(format, widthIn, heightIn, pixelsArrayIn, widthOut, heightOut) -> error, pixelsArrayOut
glu.ScaleImageRaw(format, widthIn, heightIn, typeIn, pixelsIn, widthOut, heightOut, typeOut, pixelsUserDataOut) -> error
glu.NewQuadric() -> quad
quad:Cylinder(base, top, height, slices, stacks) -> quad
quad:Disk(inner, outer, slices, loops) -> quad
quad:PartialDisk (inner, outer, slices, loops, start, sweep) -> quad
quad:DrawStyle(draw) -> quad
quad:Normals(normal) -> quad
quad:Orientation(orientation) -> quad
quad:Texture(texture) -> quad
quad:Sphere(radius, slices, stacks) -> quad
glu.NewNurbsRenderer() -> nurb
nurb:Callback(which, func) -> nurb
nurb:BeginCurve() -> nurb
nurb:BeginSurface() -> nurb
nurb:BeginTrim() -> nurb
nurb:EndCurve() -> nurb
nurb:EndSurface() -> nurb
nurb:EndTrim() -> nurb
nurb:Property(property, value)
nurb:Property(property) -> value
nurb:LoadSamplingMatrices (modelArray, perspectiveArray, viewArray) -> nurb
nurb:Curve(knotsArray, controlArray, type) -> nurb
nurb:Surface(sKnotsArray, tKnotsArray, controlArray2, type) -> nurb
nurb:PwlCurve(dataArray, type) -> nurb
glInterleavedArrays
gluQuadricCallback All the tessellation functions: gluNextContour gluBeginPolygon gluEndPolygon gluNewTess gluTessBeginContour gluTessBeginPolygon gluTessCallback gluTessEndContour gluTessEndPolygon gluTessNormal gluTessProperty gluTessVertex gluDeleteTess gluGetTessProperty