OpenGL Lua Shell Reference

Execution

Glush runs as either a stand-alone application or as a dynamic link library. The stand-alone application, when run, executes the init.lua file in the same directory as it was executed. As a special case, the Mac version will also check within the application directory structure for Contents/Resources/init.lua.

The dynamic link library is initialized upon require-ing the library. At this point the system initializes the GL context, however it will not run the behavior loop until it is explicitly invoked.

glush.display
 While this is not a function of the API, it is what Glush attempts to execute every frame. For your script to encorporate realtime content you must define this callback.

glush.run([display])
 This runs the execution loop for the library version of Glush. It does not exist for the executable version of Glush. Glush runs using the function in the parameter as the display callback. If the parameter is omitted then the function glush.display is used for the callback.

Utility

Some useful functions. Most of these are rough versions of what you could find in various Lua Rocks lying about. Consider these functions convenient alternatives to the effort it would take to going out of the way to download the rocks.

glush.chdir(dir)
 Changes directory to the specified dir.

dir = glush.getcwd()
 Returns the current directory.

flags = glush.clearFlags([newflags])
 By default every frame before the glush.display() function is called, these flags are passed to an glClear call. The default value is GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT.

x,y,b = glush.mouse()
 Returns the mouse coordinate x,y and button state. The coordinates are ranged [0,1] spanning the width and height of the window. The button state is a bit flag with the first bit the left button, the second bit the right button, and the third bit the middle button.

state = glush.kbd(key)
 Returns true/false whether the specified key is down or not. Keys are referred to by their key character (rather than scan code), or by certain special key names. Special key names include F1-F16, KP0-KP9, UP, DOWN, LEFT, RIGHT, PAGE_UP, PAGE_DOWN, HOME, END, INSERT, DEL, CAPSLOCK, LSHIFT, RSHIFT, LCTRL, RCTRL, LALT, RALT, LMETA, RMETA, BACKSPACE, TAB, RETURN, ESC, SPACE. Names are case-insensitive.

t = glush.timer()
 Returns the number of seconds since the application started

w,h = glush.dispSize()
 Returns the width and height of the display size, in pixels

glush.exit()
 Exits the application

Bitwise Operations

glush.bitand(x,y)
glush.bitor(x,y)
glush.bitxor(x,y)
glush.bitnot(x)
glush.bitshiftleft(x,y)
glush.bitshiftright(x,y)
 Performs the associated bit operation on the integer values of x and y

Threading and Callbacks

handle = glush.thread.fork(f)
 Create a new Lua thread that begins execution of f. Returns a thread handle.

glush.thread.wait(handle)
 Waits for the specified thread to finish.

glush.thread.sleep(delay)
 Suspends execution of the current thread for the specified number of seconds.

glush.thread.setTimeout(f, delay)
 Executes the specified function after the specified elapsed delay.

GUI

The following functions add controls to the menu on the left hand side of the screen. When creating a control, the first argument is typically a variable name. When updating the control the global variable with the associated name will be updated.

I chose this method for ease of implementation and ease of use. Someday I'll redesign it to instanciate control objects and allow getters via member methods.

glush.gui.checkbox(varname[, value])
 Creates a checkbox bound to the variable with the specified name. The variable value will be a boolean.

glush.gui.slider(varname, valueMin, value, valueMax)
 Creates a scrollbar and text field, both bound to the variable with the specificed name. Modifying the scrollbar or text field will both change the value of the associated variable. The variable value will be a number.

glush.gui.basis(varname[, xx, xy, yx, yy])
 Creates a 2D basis. The variable value will be a table with four elements. The first two components will be the first column vector of the basis. The second two components will be the second column vector.

glush.gui.tex2D(varname)
 Creates a 2D texture. The variable value will be the number of an OpenGL texture handle. To specify an initial texture, the variable must be previously initialized with a call to createTex2d

glush.gui.color(varname)
 Creates a HSV color picker. The variable value will be a table of three elements: the red, green, and blue components of the color

New GUI

I am in the process of designing a new GUI system.
Here are some lua bindings for the underlying GUI:
Note that the glush.menu table is also set to each menu object's metatable, so menu:XXXX(...) is equivalent to glush.menu.XXXX(menu, ...)'

menu = glush.menu.new([args])
 Creates a new menu.

The variable args is a table of key-value pairs. Each key-value pair represents a menu member method to call upon the menu's creation. The key is the member function name. The value is a table containing what parameters to pass to that member function.

For example,

glush.menu.new{pos={20, 10}}

is equivalent to

local m = glush.menu.new()
m:pos(20, 10)


menu:delete()
 Unlinks a menu from the GUI. Menus are only deleted once nothing else references them.

x, y = menu:pos([x, y])
 Returns the menu's position in menu-space coordinates. Sets the menu position if new values are provided. x, y numbers

sizeX, sizeY = menu:size([newSizeX, newSizeY])
 Returns the menu's size in menu-space coordinates. Sets the menu size if new values are provided. newSizeX, newSizeY numbers

scaleX, scaleY = menu:scale([newScaleX, newScaleY])
 Returns the menu's scale in the coordinate space of its parent. Sets the menu scale if new values are provided. newScaleX, newScaleY numbers

text = menu:text([text])
 Returns what text is to be rendered inside the menu. Sets the menu text if a new value is provided. text string

fontSizeX, fontSizeY = menu:fontSize([newFontSizeX, newFontSizeY])
 Returns the menu's font size in menu-space coordinates. Sets the menu font size if new values are provided. newSizeX, newSizeY numbers

r, g, b, a = menu:backgroundColor([r, g, b, a])
 r, g, b, a numbers ranging from 0 to 1

r, g, b, a = menu:fontColor([r, g, b, a])
 r, g, b, a numbers ranging from 0 to 1

r, g, b, a = menu:borderColor([r, g, b, a])
 r, g, b, a numbers ranging from 0 to 1

allow = menu:allowFocus([allow])
 allow boolean

open = menu:open()
 Returns true if the menu is still attached to the GUI, false otherwise.

menu:addChild(child)
 Add child as a child menu to the current menu.

menu:child(n)
 Returns the child at index n. Returns nil if no child is there. n number

n = menu:numChilds()
 Returns the number of children a menu has. n number

menu:parent(parent)
 Sets the parent of this menu to parent.

id = menu:texture([id])
 Returns the OpenGL 2D texture handle for this menu. 0 if none is bound. Sets the menu texture if a new value is provided. id number

visible = menu:visible([visible])
 visible boolean

priority = menu:topmostPriority([newPriority])
 call this to set the menu to the topmost

useNinePatch = menu:useNinePatch([newUseNinePatch])
 returns whether the texture is a nine-patch texture

u = menu:ninePatchUVBorder([newU])
 get/set the nine patch distance from the border in the texture

x = menu:ninePatchborder([newX])
 get/set the nine patch distance from the border in the menu

o = menu:occludesInput([newO])
 get/set whether this menu occludes input

sysSizeX, sysSizeY = menu.sysSize()
 Returns the range of menu-space coordinates in the screen. The upper left corner has coordinate 0, 0 while the lower right has coordinate sx, sy. sx, sy numbers

root = menu.root()
 Returns the root menu.

OpenGL 1.1

All functions exist in the 'gl' namespace. For example, glBegin is now gl.glBegin.

If you miss having OpenGL in the global namespace then just add the following line of code to the beginning of your Lua script:

for k,v in pairs(gl) do _G[k] = v end

All functions operate how you would expect them to in OpenGL with the exception of a few additions, changes, and shorthands:

glAreTexturesResident has not yet been implemented

glBitmap has not yet been implemented

glCallList(list0[, list1, ...])
 list0, list1, ... integers
glCallLists was not implemented

glClipPlane(plane, {px, py, pz, pw})
glClipPlane(plane, px, py, pz, pw)
 plane an integer; px, py, pz, pw numbers

glColor(cx,cy,cz[,cw]) maps to glColor3d, glColor4d
glColor{cx,cy,cz[,cw]} maps to glColor3dv, glColor4dv
 cx, cy, cz, cw all numbers

glColorPointer{data0, data1,...}
 data0, data1, ... numbers
 the type is passed to GL as GL_FLOAT data
glColorPointer(size, type, stride, pointer)
 size, type, stride, pointer integers
 'pointer' is cast to a pointer, which is useful for framebuffer operations

glDeleteTexture(texture0[, texture1, ...]) maps to glDeleteTextures
 texture0, texture1, ... integers
glDeleteTextures was not implemented

glDisable(cap0[, cap1, ...])
 cap0, cap1, ... integers
 the values are OR'd together behind the scenes

glDisableClientState(array0[, array1, ...])
 array0, array1, ... integers
 the values are OR'd together behind the scenes

glDrawElements(mode, count[, indices])
 mode, count, integers; indices a table of integers
 if indices is omitted then the contents of the last value of 'indices' will be used

glDrawPixels has not yet been implemented

glEdgeFlagPointer{data0, data1, ...}
 data0, data1, ... integers
glEdgeFlagPointer(stride, pointer)
 stride, pointer integers
 'pointer' is cast to a pointer, which is useful for framebuffer operations

glEnable(cap0[, cap1, ...])
 cap0, cap1, ... integers
 the values are OR'd together behind the scenes

glEnableClientState(array0[, array1, ...])
 array0, array1, ... integers
 the values are OR'd together behind the scenes

glEvalCoord(u) maps to glEvalCoord1d
glEvalCoord{u} maps to glEvalCoord1dv
glEvalCoord(u,v) maps to glEvalCoord2d
glEvalCoord{u,v} maps to glEvalCoord2dv
 u,v numbers

glEvalMesh(mode, i1, i2[, j1, j2]) maps to glEvalMesh1, glEvalMesh2
 mode, i1, i2, j1, j2 integers

glEvalPoint(i[, j]) maps to glEvalPoint1, glEvalPoint2

glFeedbackBuffer(size, type)
 size, type integers
 the feedback buffer will be returned as a table from the next subsequent call to glRenderMode

glFog(pname, param) maps to glFogf
 pname an integer, param a number
glFog(pname, {param0, param1, param2, param3}) maps to glFogfv
glFog(pname, param0, param1, param2, param3) maps to glFogfv
 pname an integer; param0, param1, param2, param3 numbers
glFog{[mode=mode;] [density=density;] [start=start;] [['end]'=end;] [index=index;] [color={cr, cg, cb, ca};]}
 mode, index integers; density, start, end, cr, cg, cb, ca numbers

glGenList([range]) maps to glGenLists
 range an integer
 if omitted, range takes on the value of 1
glGenLists was removed

glGet(pname)
 if the result is a single boolean, integer, or number value then it will be returned
 if the result contains multiple values then they will be returned in a single table

glGetLight has not yet been implemented
glGetMap has not yet been implemented
glGetMaterial has not yet been implemented
glGetPixelMap has not yet been implemented

glGetPointer(pname)
 pname an integer
 returns the associated pointer as lightuserdata

glGetPolygonStipple()
 returns a table of 32 integers
 
glGetTexEnv has not yet been implemented
glGetTexGen has not yet been implemented

glGetTexImage(target, level[, format, type, pixels])
 target, level, format, type, pixels integers
 'pixels' is cast to a pointer, which is useful for framebuffer operations
 if pixels is not provided then format will be overridden to GL_RGBA and the results will be returned in a 4-component array.

glGetTexLevelParameter(target, level, pname)
 target, level, pname integers
 returns the requested parameter as an integer
 
glGetTexParameter has not yet been implemented

glIndexPointer{data0, data1,...}
 data0, data1, ... numbers
 the type is passed to GL as GL_INT data
glIndexPointer(type, stride, pointer)
 type, stride, pointer integers
 'pointer' is cast to a pointer, which is useful for framebuffer operations

glIndex(c) maps to glIndexd
 c a number
 
glLight(light, pname, param) maps to glLightf
glLight(light, pname, param0, param1, param2) maps to glLightfv
glLight(light, pname, param0, param1, param2, param3) maps to glLightfv
 light, pname integers; param, param0, param1, param2, param3 numbers
glLight{
 [light]={
  [spotExponent=spotExponent;]
  [spotCutoff=spotCutoff;]
  [constantAttenuation=constantAttenuation;]
  [linearAttenuation=linearAttenuation;]
  [quadraticAttenuation=quadraticAttenuation;]
  [ambient={ambientR, ambientG, ambientB, ambientA};]
  [diffuse={diffuseR, diffuseG, diffuseB, diffuseA};]
  [specular={specularR, specularG, specularB, specularA};]
  [position={positionX, positionY, positionZ, positionW};]
  [spotDirection={spotDirectionX, spotDirectionY, spotDirectionZ};]
  [enable=enable;]
 },
 ...
}
 light an integer
 spotExponent, spotCutoff numbers
 constantAttenuation, linearAttenuation, quadraticAttenuation numbers
 ambientR, ambientG, ambientB, ambientA numbers
 diffuseR, diffuseG, diffuseB, diffuseA numbers
 specularR, specularG, specularB, specularA numbers
 positionX, positionY, positionZ, positionW numbers
 spotDirectionX, spotDirectionY, spotDirectionZ numbers
 enable a boolean
 
glLightModel(pname, param) maps to glLightModelf
glLightModel(pname, param0, param1, param2, param3) maps to glLightModelfv
 pname an integer; param, param0, param1, param2, param3 numbers
glLightModel{
 [ambient={ambientR, ambientG, ambientB, ambientA};]
 [localViewer=localViewer;]
 [twoSide=twoSide;]
 [colorControl=colorControl;]
}
 ambientR, ambientG, ambientB, ambientA numbers
 localViewer a number
 twoSide a number
 colorControl a number

glLoadMatrix{m00, m01, m02, m03, m10, m11, m12, m13, m20, m21, m22, m23, m30, m31, m32, m33}
 all the m's as numbers

glMaterial(face, pname, param0) maps to glMaterialf
glMaterial(face, pname, param0, param1, param2[, param3]) maps to glMaterialfv
glMaterial{
 [front=frontInfo;]
 [back=backInfo;]
 [frontAndBack=frontAndBackInfo;]
}
glMaterial{frontInfo, backInfo}
 face, pname integers; param0, param1, param2, param3 numbers
 frontInfo, backInfo, and frontAndBack tables consisting of the following members:
 {
  [ambient = {ambientR, ambientG, ambientB, ambientA};]
  [diffuse = {diffuseR, diffuseG, diffuseB, diffuseA};]
  [specular = {specularR, specularG, specularB, specularA};]
  [emission = {emissionR, emissionG, emissionB, emissionA};]
  [shininess = shininess;]
  [ambientAndDiffuse = {ambientAndDiffuseR, ambientAndDiffuseG, ambientAndDiffuseB, ambientAndDiffuseA};]
  [colorIndexes = {colorIndexR, colorIndexG, colorIndexB};]
 }
 all these member values are numbers.

glMultiTexCoord(target, s[, t[, r[, q]]]) maps to glMultiTexCoordNd
glMultiTexCoord(target, {s[, t[, r[, q]]]}) maps to glMultiTexCoordNdv
 target as integer; s, t, r, q numbers

glNormalPointer{data0, data1,...}
 data0, data1, ... numbers
 the type is passed to GL as GL_FLOAT data
glNormalPointer(type, stride, pointer)
 type, stride, pointer integers
 'pointer' is cast to a pointer, which is useful for framebuffer operations

glPolygonStipple{pattern1, pattern2, ... pattern32}  pattern1 through pattern32 integers
 Each 32-bit integer maps to the bit pattern of four 8-bit GLubytes that would be passed to the glPolygonStipple C binding.

glPrioritizeTextures(n, {texture1, texture2, ..., textureN}, {priorities1, priorities2, ..., prioritiesN})
 n, texture1, ..., textureN integers; priorities1, ..., prioritiesN numbers

glRasterPos(x,y) maps to glRasterPos2d
glRasterPos{x,y} maps to glRasterPos2dv
glRasterPos(x,y,z) maps to glRasterPos3d
glRasterPos{x,y,z} maps to glRasterPos3dv
glRasterPos(x,y,z,w) maps to glRasterPos4d
glRasterPos{x,y,z,w} maps to glRasterPos4dv

glReadPixels([x, y, width, height[, format, type, buffer])
 x, y, width, height, format, type, buffer integers
 if buffer is not provided then format is set to GL_RGBA and type is set to GL_FLOAT  if buffer is provided then it is cast to a pointer, which is useful for framebuffer operations

glRenderMode(mode)
 mode is an integer
 If setting the render mode results in populating a feedback buffer then that buffer will be returned as a table.

glScale(x,y,z) maps to glScaled
glScale{x,y,z} maps to glScaled

glSelectbuffer has not yet been implemented

glTexCoord(s) maps to glTexCoord1d
glTexCoord{s} maps to glTexCoord1dv
glTexCoord(s,t) maps to glTexCoord2d
glTexCoord{s,t} maps to glTexCoord2dv
glTexCoord(s,t,r) maps to glTexCoord3d
glTexCoord{s,t,r} maps to glTexCoord3dv
glTexCoord(s,t,r,q) maps to glTexCoord4d
glTexCoord{s,t,r,q} maps to glTexCoord4dv

glTexImage1D(target, level, internalFormat, width, border, format, type, data)
glTexSubImage1D(target, level, xofs, width, format, type, data)
glTexImage2D(target, level, internalFormat, width, height, border, format, type, data)
glTexSubImage2D(target, level, xofs, yofs, width, height, format, type, data)
glTexImage3D(target, level, internalFormat, xofs, yofs, width, height, depth, border, format, type, data)
 target, level, internalFormat, width, height, depth, border, format, type integers
 if data is a table then each element is read as a single GL_FLOAT component
 if data is a function then for each pixel the function is called with three parameters: the s, t, and r texel coordinates.
 if data is a string then each element is read from the string's binary data as the type specified in the type parameter.

glTranslate(x,y,z) maps to glTranslated
glTranslate{x,y,z} maps to glTranslated

glVertex(x,y) maps to glVertex2d
glVertex{x,y} maps to glVertex2dv
glVertex(x,y,z) maps to glVertex3d
glVertex{x,y,z} maps to glVertex3dv
glVertex(x,y,z,w) maps to glVertex4d
glVertex{x,y,z,w} maps to glVertex4dv

glVertexPointer{data0, data1,...}
 data0, data1, ... numbers
 the type is passed to GL as GL_FLOAT data
glVertexPointer(size, type, stride, pointer)
 size, type, stride, pointer integers
 'pointer' is cast to a pointer, which is useful for framebuffer operations