OpenGL binding for Lua 5.1 Based on http://luagl.sourceforge.net

whatis · portability · download · how it works · reference ·

What is it LuaGL?

It's a library that provides access to all of the OpenGL functionality from Lua.

What is OpenGL?

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.

Portability

That library should run in all systems that support OpenGL.

License

LuaGL is a free software and uses the MIT License. It can be used at no cost for both academic and commercial purposes.

Download & Installation

You can download LuaGL from the sourceforge project home page here (OLD version only).

LuaGL also needs that you have the OpenGL library installed. All modern operating systems already have it, see OpenGL Platform & OS Implementations.

Authors

• Fabio Guerra
• Cleyde Marlyse

Changes from LuaGL in SourceForge

• Build from LuaGL 1.02-beta in SVN
• Removed the GLUT binding
• OpenGL constants can also be used as numbers
• Fixed DLL exports to enable require"luagl".

Changes by Antonio Scuri.

To do: change error handling to use luaL_check* functions.

How it works ?

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 to the library from a C host program, you must first call the 'luaopen_gl' function. To have access from Lua, simply call require"luagl".

This will create a name space called 'gl', and all the functions and constants will be inside of it.

OpenGL constants

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.

Argument specification

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.

Color and Vector data

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) 

Argument types

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 the most precise type of data. The stride value of an array won't be used too. For example:

gl.VertexPointer(vertex_array) 

binds:

void glVertexPointer (GLint size, GLenum type, GLsizei stride, const GLvoid *pointer); 

Where 'vertex_array' 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) 

Requesting OpenGL information

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:

image = gl.GetTexImage (target, level, format) 

For more information about functions names and parameters, see the Function Reference bellow.

Bit Pattern

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" ) 

Function Reference

Accum (op, value) -> none 
AlphaFunc (func, ref) -> none 
AreTexturesResident (texturesArray) -> residences 
ArrayElement (i) -> none 
Begin (mode) -> none 
BindTexture (target, texture) -> none 
Bitmap (xorig, yorig, ymove, bitmap) -> none 
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, pixels) -> none 
EdgeFlag (flag) -> 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 
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 
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, ustride, pointsArray) -> none 
Map (target, u1, u2, ustride, v1, v2, vstride, 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) -> none 
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, pixels) -> none 
TexParameter (target, pname, param) -> none 
TexParameter (target, pname, paramsArray) -> none 
TexSubImage (level, format, pixels, xoffset) -> none 
TexSubImage (level, format, pixels, xoffset, yoffset) -> none 
Translate (x, y, z) -> none 
Vertex (x, y, [z, w]) -> none 
Vertex (vArray) -> none 
VertexPointer (vertexArray) -> none 
VViewport (x, y, width, height) -> none