How to start with LuaGL ?

Download & Installation

You can download LuaGL from the sourceforge project home page here.

The package contains:

  • The binding of all the OpenGL functions;
  • The binding of some GLUT functions;
  • Two lua programs created for testing the library;
  • A simple example of an interpreter that uses the library and was used for the test programs.
  • A copy of this web page;

LuaGL also needs that you have the OpenGL and the GLUT libraries installed. It can be obtained with the following links:

http://www.opengl.org/developers/documentation/implementations.html
http://www.opengl.org/developers/documentation/glut.html

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 that will create a table named 'gl', and all the functions will be inside of it.

OpenGL constants

In Lua, 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')

Thanks to syntax sugar we can write also

gl.Begin "TRIANGLES"

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" )
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-Share Alike 2.5 License.