GeeXLab Rootard Guide > GeeXLab in a Nutshell

GeeXLab in a Nutshell

Last update: 2018.06.06 by JeGX

>> Back <<

1 - What is GeeXLab

GeeXLab is a cross-platform tool for real time 3D prototyping, demos creation, game development, interactive applications and creative coding. GeeXLab is available on all popular desktop platforms: Windows (32 and 64-bit), Linux (64-bit) and macOS. GeeXLab is also available for two popular SBCs (Single Board Computer): the Raspberry Pi and its competitor from ASUS, the Tinker Board.
GeeXLab is based on widely used standards such as GLSL (OpenGL Shading Language), Lua and Python programming languages.

GeeXLab 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. GeeXLab 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 your demo in several files (an XML for main structure, several Lua/Python files and several files for GLSL shaders). GeeXLab is flexible and you are free to organize things as you want!

GeeXLab offers a low level programming interface (or API). This low level API requires more lines of codes but allows a better control over the rendering. There is no scene graph management, it's up to you to manage how and when your objects are rendered. GeeXLab scripting API has also high level functions like the loading of 3D models or textures. Here is a code snippet:

Scene initialization:



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)
gh_camera.set_lookat(camera, 0, 0, 0, 1)

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 GeeXLab is easy to use! And with higher level libraries available in Lua or Python, even a kid can code with GeeXLab :)
The best way to learn GeeXLab is to study and hack the demos provided in the Learn Sample Pack and to test them in GeeXLab. Be sure to have a good text editor to quikly open and edit the demo's files.
Here are some good text editors for programming with GeeXLab

Notepad++: one of the best text editors for Windows. It is free and developed by a French guy!
Geany: a text editor for Windows, Linux and macOS. It's free and has everything you need to code GeeXLab demos
Sublime Text: a text editor for Windows, Linux and macOS. It's a commercial product but its free version is perfectly usable (if you forget the reminder to buy the paid version once out of 5 when you save a file).
Atom: a text editor for Windows, Linux and macOS. It is free and functional.

2 - How does GeeXLab work

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

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. For example, a scene with two INIT scripts (one Lua, and one Python), two FRAME scripts (one Lua and one Python) is perfectly valid.
The following diagram shows when the different scripts are executed:

3 - Scene Nodes

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

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, and so on.

4 - Help and Documentation

The entry point of all tutorials, documentation and help is the Routard Guide. The simplest way to get help is to post in GeeXLab 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.