Overview of GLSL Hacker (and GeeXLab)



This article describes what is GLSL Hacker GeeXLab and how it works.

Update (2015.12.02): This article is also valid if you replace GLSL Hacker by GeeXLab!

Article index:

1 – What is GLSL Hacker

GLSL Hacker is a cross-platform tool for real time 3D prototyping, for creating demos, games, interactive applications and creative coding. GLSL Hacker is available on all popular desktop platforms: Windows, Linux and OSX (64-bit on all platforms) as well as on the Raspberry Pi (32-bit).


Overview of GLSL Hacker - Supported operating systems

GLSL Hacker is based on widely used standards such as GLSL (OpenGL Shading Language), Lua and Python programming languages.





GLSL Hacker does not have a sophisticated graphical user interface with tons of menus and options. Instead, it relies on simple text files to store the code of a demo. GLSL Hacker does not force you to use a particular structure and organization for the files. It’s up to you to manage the files of your demo. You can have a single file that holds everything (XML nodes, Lua/Python scripts and GLSL programs) or you can split you demo in several files (an XML for main structure, several Lua/Python files and several files for GLSL shaders). GLSL Hacker is flexible and you are free to organize things as you want!

Compared to its predecessor GeeXLab (GLSL Hacker can be seen as a highly revamped version of it), GLSL Hacker offers a programming interface (or API) with a lower level of abstraction. This low level API requires more lines of codes but allows a better control of the rendering. There is no scene graph management, it’s up to you to manage how your objects are rendered (ordering, OpenGL render states). GLSL Hacker API has also high level functions like the loading of 3D models or textures. Here is a code snippet:

Objects creation:

local aspect = screenW / screenH
camera = gh_camera.create_persp(60.0, aspect, 1.0, 1000.0)
gh_camera.set_viewport(camera, 0, 0, screenW, screenH)
gh_camera.set_position(camera, 2, 2, 4)

ground_tex = gh_texture.create_from_file("ground.jpg", 0, 0)
ground_mesh = gh_mesh.create_plane(100, 100, 10, 10)

-- texture_gpu_prog is a GLSL program defined in the XML file.
glsl_prog = gh_node.getid("texture_gpu_prog")

Scene rendering:

gh_camera.bind(camera)
gh_renderer.clear_color_depth_buffers(0, 0, 0, 1.0, 1.0)
gh_gpu_program.bind(glsl_prog)
gh_texture.bind(ground_tex, 0)
gh_object.render(ground_mesh)

Sounds easy, isn’it? It’s because GLSL Hacker is easy to use! And with higher level libraries available in Lua or Python, even a kid can code with GLSL Hacker 🙂

The best way to learn GLSL Hacker is to study and hack the demos provided in the Code Sample Pack and to test them in GLSL Hacker. Be sure to have a good text editor to quikly open and edit the demo’s files.

2 – How does GLSL Hacker work

GLSL Hacker works like an internet browser: you load (or drag’n’drop) a source code file (the 3D scene) and GLSL Hacker plays it. That’s all. You can also load a scene file using the command line.


Overview of GLSL Hacker - how it works

The entry point is a XML file. This file simply holds the different scripts (Lua, Python, GLSL) that make up the 3D scene. There are several types of scripts:

  • INIT scripts: these scripts are executed once at the beginning of the scene.
  • FRAME scripts: these scripts are executed at every frame.
  • SIZE scripts: these scripts are executed when the window is resized.
  • DRAG_N_DROP scripts: these scripts are executed when a drop file occurs (currently this feature is only available under Windows and Mac OS X).
  • TERMINATE scripts: these scripts are executed at the end of the demo and are usually used to clean up resources.

A scene can have one or several scripts of the same type. What’s more, Lua and Python scripts can be present in the same scene (see this demo: host_api/Lua_Python_SharedVar/ available in the Code Sample Pack). For example, a scene with two INIT scripts (one Lua, and one Python), two FRAME scripts (one Lua and one Python) is perfectly valid.


Overview of GLSL Hacker - Lua and Python scripts

The following diagram shows when the different scripts are executed:


Overview of GLSLHacker - scripts execution flow

3 – Scene Nodes

A scene in GLSL Hacker is made up of nodes. Nearly everything is node: a GLSL program, a texture, a mesh.


Overview of GLSL Hacker - Nodes hierarchy

That’s why you will use several libraries of the scripting API (also called host API in some docs and articles) depending on the task to do: gh_node, gh_camera, gh_object, gh_mesh. gh_texture, etc.

4 – Help and Documentation

The entry point of all tutorials, documentation and help is HERE.

The simplest way to get help is to post in GLSL Hacker forums. There is a forum in english HERE and a forum in french HERE.

The scripting API reference guide for all functions you can use in Lua and Python is available HERE.

And of course, there is also this blog 😉