|
|
OpenGL binding for Lua 5 http://luagl.sourceforge.net |
|
|
|
OpenGL binding for Lua 5 http://luagl.sourceforge.net |
About · History · Usage · Reference
Its a library that provides access to the OpenGL 1.x library 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 SVN 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 internally it is 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 format parameter is not used. When stride is not used, then it is assumed to be 0. But notice that some OpenGL functions uses
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 light user data. 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.
Tables are processed internally in the highest precision supported by the OpenGL function. For instance, Array are usually processed as FLOAT, but in gl.PolygonStipple and gl.Bitmap they are processed as BYTE.
The notation "Array2" denotes a table of tables, usually for 2D arrays but can also be used for vertices and other secondary structures. 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.NewData (size[, type]) -> UserData (allocate UserData, default type is BYTE) gl.FreeData (UserData) -> none gl.SetDataValue (UserData, type, index, value) (handle UserData as array of numbers) gl.GetDataValue (UserData, type, index) -> value gl.SetData (UserData, type, valueArray) gl.GetData (UserData, type, size) -> valueArray
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 (must be BYTE type) 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) -> bufferUserData gl.FreeFeedbackBuffer(bufferUserData) 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) -> number gl.GenTextures (n) -> texturesArray gl.Get (pname) -> param1, param2, param3, ... (numbers) (not an array, a sequence of parameters) gl.GetArray (pname) -> paramsArray gl.GetConst (pname) -> param1, param2, param3, ... (enum) (not an array, a sequence of parameters) gl.GetClipPlane (plane) -> equationArray gl.GetError () -> error (enum) (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 (each pixel is an element of the array) gl.GetString (name) -> string gl.GetTexEnv (pname) -> paramsArray (ENV_MODE) or enum gl.GetTexGen (coord, pname) -> paramsArray (GEN_MODE) or enum gl.GetTexImage (target, level, format) -> pixelsArray gl.GetTexImageRaw (target, level, format, type, pixelsUserData) -> none gl.GetTexLevelParameter (target, level, pname) -> number gl.GetTexParameter (target, pname) -> paramsArray (BORDER_COLOR) or number (PRIORITY) or enum 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.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 (each pixel is an element of the array) gl.PolygonStipple (maskArray) -> none (total number of pixels is 32x32) 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) -> number 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) -> number (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[, border]) -> none (default border is 0) gl.TexImage (level, internalformat, format, pixelsArray2[, border]) -> 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