![[lumen logo]](images/logo-1.png){kind=logo}
Though it should go without saying, to make use of Lumen you will need a computer system that supports OpenGL. Nowadays that is almost every computer system out there, but as we have found, not all of them.
To test whether your X11 system supports OpenGL, run this command:
glxinfo | grep 'OpenGL version'
That should print something like this:
OpenGL version string: 2.1.2 NVIDIA 304.64
or this:
OpenGL version string: 4.2.11762 Compatibility Profile Context
If it does not print a version string, then you have some investigating to do. While you may be able to build Lumen and its applications, it is likely that they won't run properly.
We have been told that "if you are running Windows 98/Me/NT/2000/XP/2003/Vista" then your system supports OpenGL. As with all things Microsoft, that may or may not be true.
To build Lumen itself, you'll need an Ada compiler that supports Ada 2005. One good free compiler is GNAT from AdaCore Technologies. Yes, that's all! Lumen is not a binding to an external library; anything it requires should be part of your system already.
To build the demos, and probably any other application that uses the library, you'll need the "development" versions of the X11 and OpenGL libraries; on Debian and presumably Ubuntu, the package names are:
libx11-devlibgl1-mesa-devlibglu1-mesa-devAnalagous packages surely exist on other distributions and platforms. These are apparently only needed to create some crucial softlinks, but needed they are, so be sure to install them if you want to build the demos. (And trust us, you do want to build the demos!)
In order to build the demos on Microsoft Windows, you need to have the OpenGL libraries in your path:
OpenGL32.libGdi32.libYou can acquire these files as part of the Microsoft Windows SDK. Another option is to build them yourself from OpenGL32.dll and Gdi32.dll following the GNAT Users's Guide.
Currently you must build Lumen and its demo apps from source. To do this, you'll need the git version control application.
The latest version of the Lumen library can be fetched using this git command:
git clone https://github.com/karakalo/lumen.git
The repository is also replicated for historical reasons at NiEstu, so as an alternative to the above you can use this:
git clone git://ftp.niestu.com/lumen
That will create a subdirectory named lumen containing the library and its
docs.
The demo applications were recently split into their own repository, so to fetch the demos, use this command:
git clone https://github.com/karakalo/lumen-demos.git
or this alternative:
git clone git://ftp.niestu.com/lumen-demos
That will create a subdirectory named lumen-demos containing the sources of
the demo apps. You should create this in a location parallel to the lumen
directory, or elsewhere in your filesystem, not under lumen itself.
Once you have fetched the sources, you will no doubt wish to build applications, either the prepackaged demos, or your own apps. To do this, you must first build the library itself. Make sure you have installed the listed requirements, then proceed below according to your platform.
You need to tell Lumen which operating system you're using. This is done by setting the GPR scenario variable OS. It currently supports three values:
Linux: Compiles Lumen for an X11-based systemMacOSX: Compiles Lumen for MacOSXWindows_NT: Compiles Lumen for Microsoft WindowsPlease substitute $OS with the value representing your operating system in
the following commands. The default is Linux, which in this context means
"X11", so if you're building for X11, you can omit the OS specifier, meaning
you do not need to add "-XOS=Linux" to the gprbuild commands described
below.
To build Lumen itself, do:
cd /path/where/you/put/lumen
gprbuild -P lumen
That should create liblumen.a and a clutter of .ali files in the
lib directory.
The gprbuild command has some configuration it likes, and if that's not set
up on your system yet, it may give you some static. The program gprconfig
lets you set that up, choosing which compilers and languages to use for
builds. Pick at least a C compiler and an Ada compiler from its menu, and
save the config, after which the above command should work. You only need
to do this once, as it saves the information in a config file. And you often
do not need to do it at all: Most Linux distributions of GNAT, for example,
come pre-configured.
If you want to build the optional Linux joystick support as well, this command should do it:
cd /path/where/you/put/lumen
gprbuild -P joy
The command should add lumen-joystick.ali and liblumenjoy.a to the lib
directory, which will allow you to build the joystick demos. And if you have
a joystick or a game pad or something similar, you should be able to actually
run them!
For compiling Lumen itself, do:
cd \path\where\you\put\lumen
gprbuild -P lumen -XOS=Windows_NT
That should create liblumen.??? and a clutter of .ali files in the lib
directory.
Lumen includes several working applications to demonstrate its use. These are
simple, brainless apps, but should work out of the box. See the section on
identifying your platform for information on the
$OS setting used in the commands below.
Now that Lumen applications may be located in and built in any arbitrary directory, you must tell the compiler where to find the Lumen library that you built above. To do this, you must set an environment variable; on most Unix systems, you can do it thusly:
GPR_PROJECT_PATH=/path/where/you/put/lumen
export GPR_PROJECT_PATH
On MS-Windows, there is a system configuration dialog that lets you set environment variables. On both systems, you need do this only once, before you start building applications.
Once you have built the library, you should be able to build
the demo programs by changing into the lumen-demos directory and
running this command:
cd /path/where/you/put/lumen-demos
gprbuild -P demos -XOS=$OS
That should create various executables in the bin directory, which you can
run according to the instructions on their respective description pages.
Lumen now also includes the first few lessons from the NeHe OpenGL tutorials, which can be built thusly:
cd /path/where/you/put/lumen-demos
gprbuild -P nehe XOS=$OS
This should create more executables in the bin directory.
Lumen now also includes the first few tutorials from the OpenGL Tutorials site, which can be built thusly:
cd /path/where/you/put/lumen-demos
gprbuild -P ogltut -XOS=$OS
This should create more executables in the bin directory.
The demos now use the "streamlined" OpenGL bindings used by Lumen internally,
declared in Lumen.GL and Lumen.GLU. The library also includes some thin
OpenGL bindings, though we discourage their direct use; either use the
streamlined bindings, or wait for our fancy "thick" Lumen.OpenGL bindings.
Lumen currently supports any version of OpenGL. Work is underway to support OpenGL ES, which is the variant used for mobile and embedded systems such as Android. Once that is available, this documentation will be updated to describe its use.
The current streamlined bindings are intended to support OpenGL 3.3, though some calls may be missing. If you find a call you need that doesn't have a binding yet, please let us know and we will add it. Bindings to earlier versions should be fairly complete.
Lumen currently does use one GNAT-specific library routine, so it is dependent on GNAT. It's a very trivial task being done, though, and we're working on replacing it with in-line code. No reports have come in of anyone trying to build it with another compiler, though, so it's not a priority.
See the Getting Started page for more details about how to begin using Lumen.
That's all for now, but more is coming soon!
Last Updated: 11 Feb 2013 18:37:22