sdl

sdl is a SDL2 V module and a wrapper around libSDL2.

The module strives to support 100% of the SDL2 API.

So, among many other things, you can:

• Open windows and accelerated rendering contexts
• Render basic 2D graphics
• Handle input events from keyboards, touches, mice, gamepads and joysticks
• Play audio, sound effects and music

Install

If you want to use SDL2 v2.0.8 you can simply do:

v install sdl

If you want to use another version of SDL2 you will, currently, have to install it via git or by manual download.

An example of installing the system provided version of SDL2 via git:

git clone https://github.com/vlang/sdl.git ~/.vmodules/sdl
v ~/.vmodules/sdl/setup.vsh

Should sdl2-config be absent on your system you can try the following instead, by providing the version manually:

An example of installing SDL2 v2.0.12 via git:

git clone https://github.com/vlang/sdl.git ~/.vmodules/sdl
cd ~/.vmodules/sdl
git checkout 2.0.12

and for Windows:

git clone https://github.com/vlang/sdl.git %HOMEPATH%/.vmodules/sdl
cd %HOMEPATH%/.vmodules/sdl
git checkout 2.0.12

Then follow the steps in the Windows section below.

You can see what sdl releases are available in the GitHub repository via branches.

Also note that you'll need the SDL2 libraries available on your system see the Dependencies section below for more details.

Version notes

SDL2 v2.0.8 is currently the lowest version of SDL2 supported. SDL2 is backwards compatible - so anything written against v2.0.8 can be compiled and run against newer versions of the SDL2 library.

Also note that SDL2 is not compatible with SDL v1.x.

Notes on garbage collection and memory issues

Currently, with some setups, SDL2 is known to trigger crashes when used in conjunction with V's default garbage collector. Because of this you have to explicitly opt-in to use V's garbage collection with SDL2.

If you choose to use the garbage collector with SDL objects (by running apps importing sdl with v -d sdl_use_gc run) you may experience runtime crashes and output similar to this:

main__main: RUNTIME ERROR: invalid memory access

We are tracking the issue here: #744

The crashes can be avoided by simply not passing -d sdl_use_gc and managing memory manually with SDL's memory functions like sdl.free/1, sdl.malloc/1, sdl.calloc/2, sdl.realloc/2 and the various create_* and destroy functions.

Support

sdl is currently supported on:

• Linux
• MacOS (via homebrew)
• Windows

Examples

tVintris

You can run the tVintris example like this :

v run sdl/examples/tvintris/tvintris.v

Dependencies

Linux

Fedora

sudo dnf install SDL2-devel SDL2_ttf-devel SDL2_mixer-devel SDL2_image-devel

Ubuntu

sudo apt install libsdl2-ttf-dev libsdl2-mixer-dev libsdl2-image-dev

Arch

sudo pacman -S sdl2 sdl2_image sdl2_mixer sdl2_ttf

ClearLinux

sudo swupd bundle-add devpkg-SDL2_ttf devpkg-SDL2_mixer devpkg-SDL2_image

MacOS

Brew

brew install sdl2 sdl2_gfx sdl2_ttf sdl2_mixer sdl2_image sdl2_net

If you get no music with the above, try:

brew reinstall --build-from-source --force sdl2 sdl2_gfx sdl2_image sdl2_mixer sdl2_net sdl2_ttf webp libtiff libmodplug libogg

Windows

It is necessary to install the sdl2 development libraries for Windows. To do this, change to the root directory of the sdl module, like cd %HOMEPATH%\.vmodules\sdl and run v run windows_install_dependencies.vsh. This will create a directory called "thirdparty" which will be used to download and extract the required libraries. To successfully run a provided example or your own projects, the sdl dlls must be copied to the main application directory. e.g.:

copy thirdparty\SDL2-2.0.8\lib\x64\SDL2.dll examples\basic_window\
cd ..
v run sdl\examples\basic_window\main.v

Contributions

• nsauzede
• spytheman
• adlesh
• Larpon