README.org

July 4, 2025 · View on GitHub

#+title: Raylib

This library provides hand-written FFI bindings to [[https://github.com/raysan5/raylib/][Raylib]] for SBCL and ECL.

Writing them by hand and avoiding CFFI has proven to:

have fewer dependencies
avoid runtime issues involving ASDF / UIOP
have much better performance

Keep in mind, however, that since these bindings are hand-written, not all functions are available. There may also occasionally be drift between the SBCL and ECL as well.

Games made with this:

[[https://github.com/fosskers/aero-fighter][Aero Fighter]]

Table of Contents :TOC_5_gh:noexport:

[[#compilation][Compilation]]
- [[#shared-objects][Shared Objects]]
- [[#other-dependencies][Other Dependencies]]
- [[#test-run][Test Run]]
[[#compiler-notes][Compiler Notes]]
- [[#sbcl][SBCL]]
  - [[#loading][Loading]]
  - [[#binding-techniques][Binding Techniques]]
    - [[#types-and-construction][Types and Construction]]
    - [[#field-access][Field Access]]
    - [[#booleans][Booleans]]
- [[#ecl][ECL]]
  - [[#loading-1][Loading]]
  - [[#binding-techniques-1][Binding Techniques]]
    - [[#headers][Headers]]
    - [[#types-and-construction-1][Types and Construction]]
    - [[#freeing-memory][Freeing Memory]]
    - [[#field-access-1][Field Access]]
    - [[#booleans-1][Booleans]]
[[#depending-on-this][Depending on This]]
- [[#downstream-makefile][Downstream Makefile]]
- [[#creating-release-builds][Creating Release Builds]]

Compilation

** Shared Objects

The Raylib C code has been vendored into this repository. To build it, as well as the "shim" code necessary to work around Raylib's pattern of passing all structs by-value, do:

#+begin_example make #+end_example

This will produce =liblisp-raylib.so= and =liblisp-raylib-shim.so= in =lib/=.

** Other Dependencies

Luckily there is only one other dependency: =trivial-garbage=. You can fetch it with [[https://github.com/fosskers/vend][vend]] or similar tools:

#+begin_example vend get #+end_example

** Test Run

Once the =raylib= system builds and loads, you can test it with the small game loop sample at the bottom of the =package.lisp= file. If a window opens and you see the FPS counter, then it works. Press ESC to close the window.

Compiler Notes

As mentioned, this library does not use CFFI, a "convenience" library generally advertised to simplify the process of binding to C libraries. Convenient though it is, it comes at a cost I deemed unacceptable for game development. Hence it was necessary to crack open the compiler manuals and write the bindings separately for each compiler. It's honestly not that much work, especially if you know you'll only ever bind to a subset of the entire underlying API.

** SBCL

Despite being a Lisp-in-Lisp compiler, its C handling is excellent.

*** Loading

The SBCL variant builds and loads as-is via a usual =asdf:load-system=.

If you alter the bindings during development, it's enough to dynamically call the =load-shared-objects= function to update what's in your running image.

*** Binding Techniques

**** Types and Construction

Let's observe how the =Vector2= type and its constructor =_MakeVector2= are bound.

"Wait a minute," I hear you thinking, "Raylib is C - it has no special constructor for =Vector2=." And you'd be right: =_MakeVector2= is a shim function that heap-allocates a =Vector2= for us and returns the pointer.

#+begin_src c Vector2 *_MakeVector2(float x, float y) { Vector2 *v = malloc(sizeof(Vector2));

v->x = x; v->y = y;

return v; } #+end_src

"Hold on," you pipe up again, "why pointers? Raylib passes everything around by-value." Right again. Unfortunately, neither SBCL nor ECL support by-value struct passing at the moment. So instead we do everything with pointers to the structs we need:

#+begin_src lisp (define-alien-type nil (struct vector2-raw (x float) (y float)))

(define-alien-routine ("_MakeVector2" make-vector2-raw) (* (struct vector2-raw)) (x float) (y float)) #+end_src

This isn't quite useful, as we can't easily access the inner fields without arcane calls, nor does the Garbage Collector know what to do with this. We wrap some more:

#+begin_src lisp (defstruct (vector2 (:constructor @vector2)) (pointer nil :type (alien (* (struct vector2-raw (x single-float :offset 0) (y single-float :offset 32))))))

(declaim (ftype (function (&key (:x real) (:y real)) vector2) make-vector2)) (defun make-vector2 (&key x y) (let* ((ptr (make-vector2-raw (float x) (float y))) (v (@vector2 :pointer ptr))) (tg:finalize v (lambda () (free-alien ptr))))) #+end_src

Three things to note:

It is critical for SBCL that the =:offset= values are set correctly within the type hint. Otherwise it has to do a lot of guessing at runtime and you'll see a big performance hit.
We see =trivial-garbage:finalize= in action. This ensures that as our wrapper CL struct is getting cleaned up, it will free the underlying C memory.
We add a =declaim= mostly for documentation purposes, but also to express for convenience that this function can flexibly accept most number types as input, enabling:

#+begin_src lisp (raylib:make-vector2 :x 0 :y 0) ; No need to pass 0.0 #+end_src

**** Field Access

We use a macro:

#+begin_src lisp (defmacro vector2-x (v) "The X slot of a Vector2'." (slot (vector2-pointer ,v) 'x)) #+end_src

Since =slot= can be used with =setf= as well, =vector2-x= (etc.) naturally becomes both a getter and a setter.

Other Raylib functions that require a =Vector2= as input are bound in such a way that they accept our wrapped =vector2= and internally unwrap it before calling down into C. **** Booleans

When interpreting a C bool back into Lisp, SBCL needs to be told exactly how big, in bits, the underlying number value was. For =stdlib= bools, this is 8 bits:

#+begin_src lisp (define-alien-routine ("IsGamepadAvailable" is-gamepad-available) (boolean 8) (gamepad int)) #+end_src

Otherwise you will get very strange overflowing behaviour, and calls that should yield =T= will not.

** ECL

ECL is a bit more sensitive than SBCL, but still fully functional if you know what to be careful of.

*** Loading

The =libffi= system dependency incurs a performance penalty. Further, with future aims of compiling to WASM, we wish to avoid this dependency altogether. Hence our ECL-based bindings are entirely "static" and avoid its =:dffi= feature.

This means that during development, we need to load our system in a special way:

#+begin_src lisp (progn (let* ((path (merge-pathnames "lib/" (ext:getcwd))) (args (format nil "-Wl,-rpath,~~a -L~~a" path path))) (setf c:user-linker-flags args) (setf c:user-linker-libs "-llisp-raylib -llisp-raylib-shim")) (asdf:load-system :raylib :force t)) #+end_src

This code can be found in the =repl.lisp= file, which you can run to load these bindings in the expected way. After that, develop as normal. Keep in mind however that when you compile a new function, do so at the file-level (with =C-c C-k= or otherwise) at not at the individual function level (=C-c C-c=).

*** Binding Techniques

**** Headers

ECL transforms our bindings directly into C code. If we're calling any external functions, we need to tell ECL about them. =clines= injects raw C into the resulting compiled file:

#+begin_src lisp ;; For access to my various _Foo' functions. (ffi:clines "#include \"shim.h\"") ;; For access to free'. (ffi:clines "#include <stdlib.h>") #+end_src

**** Types and Construction

As with SBCL, let's look at how we bind to =Vector2=.

#+begin_src lisp (ffi:def-struct vector2-raw (x :float) (y :float))

(ffi:def-function ("_MakeVector2" make-vector2-raw) ((x :float) (y :float)) :returning (* vector2-raw)) #+end_src

These are actually macros that call down into similar primitives for injecting raw C right into the file.

#+begin_src lisp (defstruct (vector2 (:constructor @vector2)) (pointer nil :type si:foreign-data))

(defun make-vector2 (&key x y) (let* ((ptr (make-vector2-raw x y)) (v (@vector2 :pointer ptr))) (tg:finalize v (lambda () (free! ptr))))) #+end_src

Somewhat simpler than the SBCL, as we don't need to hand-hold the =:type= hint. Garbage Collection, however, requires special attention.

**** Freeing Memory

Note the =free!= within the finalizer above.

#+begin_src lisp ;; NOTE: 2025-01-03 This is highly bespoke and comes directly from the maintainer of ECL. (defun free! (ptr) "A custom call to C's `free' that ensures everything is properly reset." (ffi:c-inline (ptr) (:object) :void "void *ptr = ecl_foreign_data_pointer_safe(#0); #0->foreign.size = 0; #0->foreign.data = NULL; free(ptr);" :one-liner nil)) #+end_src

It's magic but it works. Without this, you will get segfaults.

**** Field Access

#+begin_src lisp (defmacro vector2-x (v) "The X slot of a Vector2'." (ffi:get-slot-value (vector2-pointer ,v) 'vector2-raw 'x)) #+end_src

As with SBCL, this can be used as both a getter and a setter.

**** Booleans

ECL doesn't seem to interpret C =stblib= bools back into a friendly Lisp type, so we need to help it:

#+begin_src lisp (ffi:def-function ("IsGamepadAvailable" is-gamepad-available-raw) ((gamepad :int)) :returning :unsigned-byte)

(defun is-gamepad-available (n) (= 1 (is-gamepad-available-raw n))) #+end_src

Depending on This ** Downstream Makefile

Your =Makefile= in a project that depends on this could look this:

#+begin_src makefile PLATFORM ?= PLATFORM_DESKTOP_GLFW

dev: lib/ lib/liblisp-raylib.so lib/liblisp-raylib-shim.so

lib/: mkdir lib/

lib/liblisp-raylib.so: cd vendored/raylib/ && $(MAKE) PLATFORM=$ (PLATFORM) cp vendored/raylib/lib/liblisp-raylib.so lib/

lib/liblisp-raylib-shim.so: lib/liblisp-raylib.so cp vendored/raylib/lib/liblisp-raylib-shim.so lib/

clean: rm -rf lib/ cd vendored/raylib/ && $(MAKE) clean #+end_src

This copies the underlying =.so= files into a =lib/= local to your application, so that when the =raylib= system loads, it will find them where it expects.

** Creating Release Builds