Overview

The GL Lua Shell is compiler-free means of coding quick OpenGL demos in the language of Lua. It currently covers nearly all of OpenGL 1.1 as well as a few extensions that have since become incorporated into OpenGL in later versions.

I originally wrote this with the intention of using it for rapid prototyping. Having no compile time is a general benefit. Added to that the flexibility of the language Lua (lambda functions, operator overloading, superset of OOP functionality) and I figured it was a worthwhile invention.

At first I coded a lot of do-this-all-at-once functions for getting myself off the ground. glLight and glMaterial were overloaded to accept not only their default parameters, but also tables which would allow a user to pass all their desired information through using only one call.

Design patterns changed soon when I realized if I moved enough of the bottleneck to the GPU then the CPU could spare itself the extra time dinking around with a scripting language.

Hotkeys

Press 'Esc' to toggle the menu. Scripts can define menu components, exposing different variables that can be manipulated.

Press ~ to toggle the console. The console should show you a report of any errors that occurred when loading the script. The console also allows directly writing code to the current Lua state.

Press 'F2' to reload your script at any time.

Building

I use Lua true to the original source code all with one minor modification. I've added support for timeslice-based multithreading in Lua. To accomplish this I use the instruction-based debug hook callback. When a hook finishes it calls lua_yield(). This is where things get hairy. lua_yield() will cause a Lua error if it is run from Lua code, called from a C function, called from Lua code. While it fails this way under this condition, Lua exposes no means of deducing whether the current state would fail such a yield. For this reason I implemented one additional function in Lua: lua_canyield(). It looks like so:

	LUA_API int lua_canyield(lua_State *L) {
	  return L->nCcalls <= L->baseCcalls;
	}

If you can't or don't want to add this function then just compile it with the "DISABLE_LUA_THREADS" macro set. So far none of my posted projects make use of the functionality so you shouldn't be missing out on anything.

Running on Windows

The gLuSh.exe application checks its first argument for what Lua file to execute. If none is provided then it searches out "init.lua" by default.

For the windows users you can invoke a file by either running the command:

gLuSh.exe filename

You can also drag the Lua file onto the glush.exe. Clever Windows UI. You can also create an "init.lua" file in the same directory and type into it the following one-liner:

require 'whatever-your-filename-is-without-the-.lua-extension'

. . . and then double-click the glush.exe file. Things should work fine.

For font support make sure the included font.bmp file is placed in the same folder as gLuSh.exe.

Running on Mac OS X

Running OS X prevents users from an easy access to invoking the gLuSh command-line application. It is tucked away inside the .app directory structure. Instead just be sure to rely upon the "init.lua" file. Make sure there is an "init.lua" file in the same folder as gLuSh.app. Make sure it has the sole line in it:

require 'whatever-your-filename-is-without-the-.lua-extension'

Then double-click the .app file.

Font support should be bundled in that directory structure, so you can sleep well at night.

Running Standalone

The binaries now come with dynamic linked libraries of Glush. To run Glush via standalone Lua, execute the following:

lua standalone.lua

Take a look at the contents of standalone.lua for an example of how to use Glush as a dynamic link library. Notice that this method of using Glush is still very experimental.

Screensaver

And yet there's more! Glush now runs as a screensaver on windows! Download the windows binary to find it there. I'm still working out what should be done about current working directories. The glush.scr will run the init.lua in its current directory. Unfortunately it won't be picked up by your Display Properties unless it is in your system folder. This means bringing the init.lua into the system folder with it. I'm still working these kinks out...

Reference

The reference information for GL scripting can be found here.

Demos

Here are a few programs I have made, demonstrating Glush's capabilities:

Download the Source Code Here
Download the Mac OS X Binary (app, dylib, so) Here
Download the Windows Binary (exe, dll, screensaver) Here
Source Code Dependencies Core Libraries v.2