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