CL-HORDE3D

What is CL-HORDE3D?

A CFFI¹ wrapper for the Horde3D library. Display flashy 3D graphics with Common Lisp. I use it to visualize some AI experiments I enjoy to develop in my free time. Unfortunately I do not have very much of it, so the progress on CL-HORDE3D is unlikely to be fast.

What is Horde3D?

From the Horde3D² website:

Horde3D is a small open source 3D rendering engine. It is written in
an effort to create a graphics engine that offers the stunning
visual effects expected in next-generation games while at the same
time being as lightweight and conceptually clean as
possible. Horde3D has a simple and intuitive interface accessible
from virtually any programming language and is particularly suitable
for rendering large crowds of animated characters in next-generation
quality.

Horde3D is an OpenGL based graphics engine that does not use the fixed function pipeline but is built around the usage of shader programs. It only runs on OpenGL 2.0 compatible graphics hardware. It is a rather lean engine. Though it is written in C++, it exports a C API which can be easily wrapped.

Dependencies

Lisp Libraries

CFFI
Lispbuilder-sdl³ (for the examples)

Foreign libraries

Horde3D
SDL⁴ (for the examples)

License

To make things easy, CL-HORDE3D is published under the same license as Horde3D: The Eclipse Public License - v 1.0.⁵

Compatibility with different Horde3D Versions

cl-horde3d currently works together with the Horde3D_SDK_1.0.0-beta4. It should also run with the community svn version, as the API is compatible, but currently it crashes right at the start in the native code at h3dInit().

There is also a horde3d-beta3-branch in the GIT repository which contains an older version of cl-horde3d which should run with Horde3D 1.0.0 beta3.

Compatibility with Lisps

CL-HORDE3D should theoretically run on all lisps that CFFI supports. I tested cl-horde3d with the following lisps on a amd64 Gentoo Linux system:

Clozure Common Lisp: Works with 1.3 and 1.4.
SBCL: Crashes in the foreign code, in the h3dInit function, during OpenGL shader initialization. There seems to be something wrong with the shared libs loading, perhaps I shouldn’t load the libs at load time. The knight example did run with Horde3D beta3, but only without HDR (which means a big render target buffer). I need to look into this further.
Clisp: Like SBCL.

I would like to hear about success or failure with other lisps and operating systems. I’m also grateful for tips how to debug this better. Attaching gdb to the lisp process did not yet give me the insight I needed.

Translating the Horde3D API from C to CL

I have chosen to not translate the API literally, but to adjust the naming to the habits in the Common Lisp world. That’s what I did:

I dropped the h3d prefix from all names and used a common lisp package instead.
I dropped all type suffixes from enum- and function names, in a dynamic typed language they make less sense.
I `lispified’ all symbols (lower case with hyphens instead of camel case)
I dropped all -Element suffixes from the enumerations (debatable)
I adhered to the common-lisp tradition of not using abbreviations, so I renamed all occurrences of
- ‘res’ to resource
- ‘mat’ to ‘material’ (or ‘matrix’)
- ‘vert’ to ‘vertex’
- ‘elem’ to ‘element’
- ‘comp’ to ‘component’
- ‘tex’ to ‘texture’

Horde3D Extensions

There is code in CL-HORDE3D for the terrain and the sound extension, but it is totally untested and might not run at all. It is therefore disabled by default. The organization of source files for the extension will very likely change in the future.

Running the examples

Make sure you have Horde3D installed and that you can run the example binaries that come with it.
Install Lispbuilder SDL.
Either you symlink the top level Horde3D directory with the name ‘Horde3D’ into the top level directory of cl-horde3d, or you adjust the horde3d-home-directory variable in src/examples.lisp to point to your Horde3D installation. The examples will load resources and assets from there.
Load the horde3d-examples system with asdf. (Use CCL, other Lisp implementations will not work right now.)
run (horde3d-examples:knight) or (horde3d-examples:chicago) from the REPL. The example programs should have the same controls available as the original examples, but the mouse is not captured.