|
|
OpenGL binding for Lua 5.1 http://luagl.luaforge.net |
|
|
|
OpenGL binding for Lua 5.1 http://luagl.luaforge.net |
About · History · Usage · Reference
It’s a library that provides access to all of the OpenGL functionality from Lua. It was based on http://luagl.sourceforge.net.
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 LuaForge project home page.
LuaGL also needs that you have the OpenGL library installed. All modern operating systems already have it, see OpenGL Platform & OS Implementations.
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.
Changes in LuaGL from what was in SourceForge, done by Antonio Scuri. Report errors to scuri@tecgraf.puc-rio.br.
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.
All OpenGL constants were converted to strings, for example: instead of writing GL_QUADS, you should write 'QUADS'. In functions that expected a bitwise operation between mask parameters, in Lua will receive a string that contains all the constants strings separated by comma (,). For example:
gl.Begin("TRIANGLES")
gl.Clear('COLOR_BUFFER_BIT,DEPTH_BUFFER_BIT')
OpenGL constants can also 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.
It’s always used the floating point version of the functions, with the highest possible precision.
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). If there are more 4 value the extra parameters will be ignored.
For example:
v1 = { 0, 0 }
v2 = { 1, 1 }
Yellow = { 1, 1, 0 }
gl.Color(Yellow)
gl.Vertex(v1)
gl.Vertex(v2)
you can also call those:
gl.Color(1, 1, 0) gl.Vertex(0, 0) gl.Vertex(1, 1)
The OpenGL function parameters that specify the type of another argument, or the size of an array, won’t be used. Lua will always use tables and the most precise type of data supported by the function. The stride value of an array won’t be used too. For example:
gl.VertexPointer(vertexArray)
binds:
void glVertexPointer (GLint size, GLenum type, GLsizei stride, const GLvoid *pointer);
Where ‘vertexArray’ is an array of vectors. The size of the array returned by lua_getn function will be used as the size parameter. The type is the most precise possible, and the stride value is always set to zero. You can see an example of this function bellow:
v1 = { -1, -1 }
v2 = { 1, -1 }
v3 = { 1, 1 }
v4 = { -1, 1 }
vertices = { v1, v2, v3, v4 }
gl.VertexPointer(vertices)
In some image functions where the amount of data can be very large to use a Lua table, there are alternative functions that use an userdata to store the pixel array. This is more efficient and less memory consuming, but individual pixels can not be accessed in Lua.
The functions that request information from OpenGL, will now return the data by the function return value, instead of returning by a parameter. 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")
Accum (op, value) -> none AlphaFunc (func, ref) -> none AreTexturesResident (texturesArray) -> residencesArray ArrayElement (i) -> none Begin (mode) -> none BindTexture (target, texture) -> none Bitmap (xorig, yorig, xmove, ymove, bitmapArray) -> none BitmapRaw (width, height, xorig, yorig, xmove, ymove, bitmap) -> none (userdata) BlendFunc (sfactor, dfactor) -> none CallList (list) -> none CallLists (listArray) -> none Clear (mask) -> none ClearAccum (red, green, blue, alpha) -> none ClearColor (red, green, blue, alpha) -> none ClearDepth (depth) -> none ClearIndex (c) -> none ClearStencil (s) -> none ClipPlane (plane, equationArray) -> none Color (red, green, blue [, alpha]) -> none Color (color) -> none ColorMask (red, green, blue, alpha) -> none ColorMaterial (face, mode) -> none ColorPointer (colorArray) -> none CopyPixels (x, y, width, height, type) -> none CopyTexImage (level, internalFormat, border, x, y, width[, height]) -> none CopyTexSubImage (level, x, y, xoffset, width[, yoffset, height]) -> none CullFace (mode) -> none DeleteLists (list, range) -> none DeleteTextures (texturesArray) -> none DepthFunc (func) -> none DepthMask (flag) -> none DepthRange (zNear, zFar) -> none Disable (cap) -> none DisableClientState (array) -> none DrawArrays (mode, first, count) -> none DrawBuffer (mode) -> none DrawElements (mode, indicesArray) -> none DrawPixels (width, height, format, pixelsArray) -> none DrawPixelsRaw (width, height, format, type, pixels) -> none (userdata) EdgeFlag (flag) -> none EdgeFlag (flagArray) -> none EdgeFlagPointer (flagsArray) -> none Enable (cap) -> none EnableClientState (array) -> none End () -> none EndList () -> none EvalCoord (u[, v]) -> none EvalCoord (coordArray) -> none EvalMesh (mode, i1, i2[,j1, j2]) -> none EvalPoint (i[, j]) -> none FeedbackBuffer (size, type) -> dataArray Finish () -> none Flush () -> none Fog (pname, param) -> none Fog (pname, paramsArray) -> none FrontFace (mode) -> none Frustum (left, right, bottom, top, zNear, zFar) -> none GenLists (range) -> num GenTextures (n) -> texturesArray Get (pname) -> params (not an array, a sequence of parameters) GetArray (pname) -> paramsArray GetConst (pname) -> constant string GetClipPlane (plane) -> equationArray GetError () -> error flag GetLight (light, pname) -> paramsArray GetMap (target, query) -> vArray GetMaterial (face, pname) -> paramsArray GetPixelMap (map) -> valuesArray GetPointer (pname, n) -> valuesArray GetPolygonStipple () -> maskArray GetString (name) -> string GetTexEnv (pname) -> paramsArray GetTexGen (coord, pname) -> paramsArray GetTexImage (target, level, format) -> pixelsArray GetTexImageRaw (target, level, format, type, pixels) -> none (userdata) GetTexLevelParameter (target, level, pname) -> param GetTexParameter (target, pname) -> paramsArray Hint (target, mode) -> none Index (c) -> none IndexMask (mask) -> none IndexPointer (indexArray) -> none InitNames () -> none InterleavedArrays (format, dataArray) -> none IsEnabled (cap) -> true/false IsList (list) -> true/false IsTexture (texture) -> true/false Light (light, pname, param) -> none Light (light, pname, paramsArray) -> none LightModel (pname, param) -> none LightModel (pname, paramsArray) -> none LineStipple (factor, pattern) -> none LineWidth (width) -> none ListBase (base) -> none LoadIdentity () -> none LoadMatrix (mArray) -> none LoadName (name) -> none LogicOp (opcode) -> none Map (target, u1, u2, pointsArray) -> none Map (target, u1, u2, v1, v2, pointsArray) -> none MapGrid (un, u1, u2[, vn, v1, v2]) -> none Material (face, pname, param) -> none MatrixMode (mode) -> none MultMatrix (mArray) -> none NewList (list, mode) -> none Normal (nx, ny, nz) -> none Normal (nArray) -> none NormalPointer (normalArray) -> none Ortho (left, right, bottom, top, zNear, zFar) -> none PassThrough (token) -> none PixelMap (map, valuesArray) -> none PixelStore (pname, param) -> none PixelTransfer (pname, param) -> none PixelZoom (xfactor, yfactor) -> none PointSize (size) -> none PolygonMode (face, mode) -> none PolygonOffset (factor, units) -> none PolygonStipple (maskArray) -> none PopAttrib () -> none PopClientAttrib () -> none PopMatrix () -> none PopName () -> none PrioritizeTextures (texturesArray, prioritiesArray) -> none PushAttrib (mask) -> none PushClientAttrib (mask) -> none PushMatrix () -> none PushName (GLuint name) -> none RasterPos (x, y[, z, w]) -> none RasterPos (vArray) -> none ReadBuffer (mode) -> none ReadPixels (x, y, width, height, format) -> pixelsArray ReadPixelsRaw (x, y, width, height, format, type, pixels) -> none (userdata) Rect (x1, y1, x2, y2) -> none Rect (v1, v2) -> none RenderMode (mode) -> none Rotate (angle, x, y, z) -> none Scale (x, y, z) -> none Scissor (x, y, width, height) -> none SelectBuffer (size) -> SelectArray ShadeModel (mode) -> none StencilFunc (func, ref, mask) -> none StencilMask (mask) -> none StencilOp (fail, zfail, zpass) -> none TexCoord (s[, t, r, q]) -> none TexCoord (vArray) -> none TexCoordPointer(vArray) -> none TexEnv (pname, param) -> none TexEnv (pname, paramsArray) -> none TexGen (coord, pname, param) -> none TexGen (coord, pname, paramsArray) -> none TexImage (level, internalformat, format, pixelsArray) -> none TexImage1D (level, depth, width, border, format, type, pixels) -> none (userdata) TexImage2D (level, depth, width, height, border, format, type, pixels) -> none (userdata) TexParameter (target, pname, param) -> none TexParameter (target, pname, paramsArray) -> none TexSubImage (level, format, pixelsArray, xoffset[, yoffset]) -> none TexSubImage1D (level, xoffset, width, format, type, pixels) -> none (userdata) TexSubImage2D (level, xoffset, yoffset, width, height, format, type, pixels) -> none (userdata) Translate (x, y, z) -> none Vertex (x, y, [z, w]) -> none Vertex (vArray) -> none VertexPointer (vertexArray) -> none Viewport (x, y, width, height) -> none
GetString (name) -> string Ortho2D(left, right, bottom, top) -> none Perspective(fovy, aspect, near, far) -> none LookAt(Ex, Ey, Ez, Lx, Ly, Lz, Ux, Uy, Uz) -> none PickMatrix( x, y, deltax, deltay, viewportArray) -> none ErrorString(errorCode) -> string Build2DMipmaps(textureData) -> error