Module Tsdl

SDL thin bindings.

Consult the binding conventions, the binding coverage and examples of use.

Given the thinness of the binding most functions are documented by linking directly to SDL's own documentation. Unfortunately it seems that the wiki that held it is no longer being updated. For this reason latest API entry points no longer link to the documentation for now (upstream issue about the problem).

Open the module to use it, this defines only the module Sdl in your scope.

Note. The module initialization code calls SDL_SetMainReady.

References

• SDL API

SDL

Binding conventions

Naming

C names are transformed as follows. The SDL_ is mapped to the module name Sdl, for the rest add an underscore between each minuscule and majuscule and lower case the result (e.g. SDL_GetError maps to Sdl.get_error). Part of the name may also be wrapped by a module, (e.g. SDL_INIT_VIDEO becomes Sdl.Init.video). If you open Tsdl, your code will look mostly like SDL code but in accordance with OCaml's programming conventions. Exceptions to the naming convention do occur for technical reasons.

Errors

All functions that return an Sdl.result have the string returned by Sdl.get_error () in the Error (`Msg _) case.

Bit fields and enumerants

Most bit fields and enumerants are not mapped to variants, they are represented by OCaml values of a given abstract type in a specific module with a composition operator to combine them and a testing operator to test them. The flags for initializing SDL in the module Sdl.Init is an example of that:

match Sdl.init Sdl.Init.(video + timer + audio) with
| Error _ -> ...
| Ok () -> ...

Using variants in that case is inconvenient for the binding function and of limited use since most of the time bit fields are given to setup state and, as such, are less likley to be used for pattern matching.

Examples

Toplevel

To use Tsdl in the toplevel with findlib just issue:

> #use "topfind";;
> #require "tsdl.top";;

This automatically loads the library and opens the Tsdl module.

OpenGL window

The following is the minimum you need to get a working OpenGL window with SDL.

open Tsdl

let main () = match Sdl.init Sdl.Init.(video + events) with
| Error (`Msg e) -> Sdl.log "Init error: %s" e; exit 1
| Ok () ->
    match Sdl.create_window ~w:640 ~h:480 "SDL OpenGL" Sdl.Window.opengl with
    | Error (`Msg e) -> Sdl.log "Create window error: %s" e; exit 1
    | Ok w ->
        Sdl.pump_events ();
        Sdl.delay 3000l;
        Sdl.destroy_window w;
        Sdl.quit ();
        exit 0

let () = main ()

This can be compiled to byte and native code with:

> ocamlfind ocamlc -package tsdl -thread -linkpkg -o min.byte min.ml
> ocamlfind ocamlopt -package tsdl -thread -linkpkg -o min.native min.ml