ocaml-sdl3

OCaml Bindings to the SDL3 library

SDL3 is the new version (first release 2025) of the famous SDL library. ("A cross-platform development library designed to provide low level access to audio, keyboard, mouse, joystick, and graphics hardware via OpenGL/Direct3D/Metal/Vulkan. ")

The ocaml-sdl3 project (opam name is just sdl3) aims at giving access to (almost) all SDL3 functions from an ocaml program (running from Linux, MacOS or Windows), by creating bindings via the ctypes library. The bindings are meant to be very thin (that is to say: very close to the C version). Nothing prevents you from constructing nice and safer wrappers for functions you use the most.

Compiled ocaml programs using this library will dynamically load the SDL3 library at runtime.

These bindings are "automatically" generated by analyzing the SDL headers thanks to the clang library. The generator itself is currently manually written in Python (alas! I was not aware of clangml when I started the project) and is not part of this repository.

Warning! early stage of developpment!

There are more than a thousand functions bound... don't expect all of them to work! Very few have been tested yet. On the other hand you can see that the examples below already cover quite a lot of interesting stuff.

Because the game is to try to write everything "automatically" (with currently very rare manual adjustments), the overall structure can be weird at places, and the quality is far from a manually corrected API like tsdl (which provides bindings for SDL2).

But, again, it is already usable for some examples (see the bin directory). However, use at your own risk! Core dumped possible. Overall organization may change. Many signatures should be improved.

Install

The sdl3 opam package is available through:

opam pin https://github.com/sanette/ocaml-sdl3.git

Obviously, you also need SDL3. Currently, we are based on SDL 3.4.12. However, you can do with another version >= 3.2.0 : unless in debug mode, your code should work as long as you only use functions that are covered by 3.4.12 and by your installed version.

To install 3.4.12, For instance, do

git clone https://github.com/libsdl-org/SDL.git vendored/SDL
cd vendored/SDL
git checkout release-3.4.12

and then follow build instructions.

Try examples

First, enter:

dune clean
dune build
cd bin
export SDL3_LIBRARY=SDL/build/libSDL3.so

(adjust SDL3_LIBRARY to your correct location and OS --- the file for Windows should probably be "SDL3.dll", and for MacOS either "libSDL3.so.0" or "libSDL3.dylib"]).

Official SDL3 examples

Some examples from https://examples.libsdl.org/SDL3/ have been adapted to OCaml-SDL3. (I use them in an essential way to validate/fix the bindings.)

• examples/template.ml is the template (using the 'callback' style) used for all of these examples. You can execute this empty template with:

  cd examples/template.ml
  dune exec ./template.exe
  

• examples/renderer/01-clear

  cd examples/renderer/01-clear
  dune exec ./clear.exe
  

• examples/renderer/10-geometry: requires SDL >= 3.4.0

  cd examples/renderer/10-geometry
  dune exec ./geometry.exe
  

• examples/renderer/17-read-pixels: requires SDL >= 3.4.0

  cd examples/renderer/17-read-pixels
  dune exec ./read_pixels.exe
  

• examples/renderer/19-affine-textures: requires SDL >= 3.4.0

  cd examples/renderer/19-affine-textures
  dune exec ./affine_textures.exe
  

  

• examples/renderer/20-blending

  cd examples/renderer/20-blending
  dune exec ./blending.exe
  

• examples/camera/01-read-and-draw

  cd examples/camera/01-read-and-draw
  dune exec ./read_and_draw.exe
  

• examples/audio/01-simple-playback

  cd examples/audio/01-simple-playback
  dune exec ./simple_playback.exe
  

• examples/audio/02-simple-playback-callback

  cd examples/audio/02-simple-playback-callback
  dune exec ./simple_playback_callback.exe
  

• examples/audio/04-multiple-streams

  cd examples/audio/04-multiple-streams
  dune exec ./multiple_streams.exe
  

• examples/storage/01-user

  cd examples/storage/01-user
  dune exec ./user.exe
  

Other examples

Webcam example

This one is the same as the official examples/camera/01-read-and-draw but programmed with the usual "main" style.

dune exec ./camera.exe

This should open your webcam and show the content in a window

Loading PNG, animating sprite, typing debug text, and pixel drawing example

requires SDL >= 3.4.0

dune exec ./example.exe

This should show a bouncing ball and draw some pixels in a straight line. It also demonstrates using debug text and event loop.

Documentation

In order to find the ocaml name corresponding to an SDL function, see the list of bound functions.

MLI interfaces are generated for all SDL functions, and include documentation extracted from the SDL sources, and minimally adapted to the OCaml version. For each SDL* function, you can open the corresponding *_bindings.mli file, and you will find

• a link to the original SDL documentation for that function, within the SDL3 wiki.
• the explanation of what the original C function does
• the list of parameters for the OCaml version
• list of result values for the OCaml version

Because the bindings are very thin, this should be sufficient in most cases to understand how to use a function. If not, don't hesitate to open a github issue.

WARNING/TODO... the (huge) Sdl3_types.ml file has no MLI interface at this moment. To obtain function signatures, rely on your editor smart mode (merlin), or look at the examples. (And because of this, running odoc on the sources is not very interesting, as it will replace meaningful types like surface into their abstruse local expansions like Sdl3__.Sdl3_types.Surface._t_raw Ctypes.structure Ctypes.ptr )