This shard allows for the direct use of all unsafe SDL functions. It is designed to use as a low-level foundation for your own libraries.
Note that it is NOT recommended to use these bindings unless you want to write your own wrappers (which are not provided). The bindings here are unsafe and are therefore able to crash your program.
You need to have SDL installed or the SDL library files accessible by Crystal for linking and running.
For the other SDL library bindings, you also need to have SDL_image, SDL_mixer and SDL_ttf available.
Depending on the SDL version, you should use either the main branch (for SDL 2) or the sdl3 branch (for SDL 3).
Simply add this shard (sdl-crystal-bindings) to your shard.yml.
This repository comes with pre-generated binding files.
Then, use require "sdl-crystal-bindings" (or "sdl-crystal-bindings/sdl3-crystal-bindings" for SDL3).
For the other SDL libraries, you can use require "sdl-crystal-bindings/sdl-image-bindings", for example (or "sdl3-image-bindings" for SDL3).
Note that the examples use the relative paths to the respective files.
Regular SDL functions, structs, enums, unions and constants are accessible using the LibSDL namespace, while
preprocessor macro functions are accessible using the LibSDLMacro module. This separation is due to the fact
that no functions can be added to the Crystal lib modules, which do not already exist in C. Since these are
simple macro expressions, they have no real analogon and thus need to be implemented separately.
Note that also the syntax differs from regular SDL in many aspects and is more oriented to Crystal (for example, functions are in snake_case, while structs are in CamelCase).
Currently, there is only one example for SDL2, as the previous examples were based on LazyFoo's tutorial (https://lazyfoo.net/tutorials/SDL/). However, they don't want their examples being used in foreign code (even if ported), so I decided to remove them in order to respect that questionable decision. See also (https://lazyfoo.net/faq.php) for details.
For SDL3, there are many examples from the official SDL website (with more to come).
If you want to see a specific example or have questions regarding the bindings and their usage, feel free to open an issue or pull request.
To update the bindings, you need to have Ruby, gcc and clang installed on your system (ideally Linux or it might not work).
Just call ruby generate.rb from the main directory of this shard and the files under src/ will be generated or updated.
The script will download the newest SDL headers and generate automated bindings.
If you need to add manual changes, please either use the filters from the script to exclude structs and/or modify the
files in the additions directory to add specific bindings manually.
If you encounter any problems while generating the bindings, please open an issue.
- Binding generator
- Working bindings
- Bindings for sdl_image, sdl_mixer and sdl_ttf
- Continuous integration
- Decoupling of the different libraries
- Fixed some binding inconsistencies
- Updated to recent SDL2 version
- Build script now correctly raises error on Windows
NOTE: This will be the last version with SDL2 alone. After that, release tags will be split into SDL2 and SDL3.
Furthermore, the syntax of the bindings will change in the newer versions to avoid some verbosity. If you want to maintain compatibility, you can still use the 0.2 version (which will also get a separate branch).
- Update to newer SDL2 version (with slightly different syntax)
- Minor bugfixes in version macros
- Support for SDL3
- Many examples for SDL3
- Stronger typing for internal types (instead of a simple alias)
- Enums get less verbose syntax (without redundant prefixes)
- Pseudo-enums (like keycodes) become true enums
- Merging of all functions and macros into one single module (if possible and helpful)
- More examples
- Documentation
- Automated binding generation via CI
- Fix weird formatting in some header files