Repository files navigation

sdl is a SDL V module and a wrapper aroundlibSDL.Both SDL2 and SDL3 versions are supported through dedicatedbranches.

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

So, among many other things, you can:

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

You are currently reading the instructions forSDL3.For SDL2 instructions, see theREADME.md in any of the2.x.xbranches.

To usevlang/sdl you need SDL3 libraries installed and the correspondingvlang/sdlbranch checked out thatmatches the SDL3 version installed on the target system.

SeeDependencies section below for how to install SDL3for different OSes and systems.

If you have SDL3 installed on your system you can simply do:

v install sdlv~/.vmodules/sdl/setup.vsh

If you want to use another version of SDL3 you will, currently, have to installit viagit or by manual download.

An example of installing the system provided version of SDL3 viagit:

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

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

An example of installing the3.2.0 branch (thatmatches SDL3 version 3.2.0) viagit:

git clone https://github.com/vlang/sdl.git~/.vmodules/sdlcd~/.vmodules/sdlgit checkout 3.2.0

and for Windows:

git clone https://github.com/vlang/sdl.git %HOMEPATH%/.vmodules/sdlcd %HOMEPATH%/.vmodules/sdlgit checkout 3.2.0

Then follow the steps in theWindows section below.

You can see whatsdl releases are available in theGitHub repository via branches.

SDL3v3.2.0 is currently the lowest version of SDL3 supported.SDL3 is backwards compatible - so anything written againstv3.2.0 can be compiled and runagainstnewer versions of the SDL3 library.

Also note that SDL3is not compatible with SDLv1.x or2.x directly.

You can run SDL2 code using SDL3 libraries through thesdl2_compat support layer.You can read more about this compatibility in regards to V in the2.x branches README.md.

To use SDL3'smain-loop control inversion / callback setup viaSDL_MAIN_USE_CALLBACKS. You will need toimport sdl.callbacks,then define:

fninit() {callbacks.on_init(app_init)callbacks.on_quit(app_quit)callbacks.on_event(app_event)callbacks.on_iterate(app_iterate)}

Note that if the code for some of the callbacks is trivial, you do not haveto register it, just skip the call to the correspondingon_ function.

The examples inexamples/ports/* all function without a mainfunction, using that scheme.

The examplesoutside theports folder, use the normalfn main() { mechanism, without having to register callbacks.

Whether or not you want to use the "no main" approach for your own appsis up to you. V supports both ways for building SDL3 applications.

Read more about the no main, callbacks and reasonsinexamples/ports/README.md(examples/ports/README.md).

Currently, with some setups, SDL3 is known to trigger crashes when used in conjunctionwith V's default garbage collector. Because of this you have to explicitlyopt-into use V's garbage collection with SDL3.

If you choose to use the garbage collector with SDL objects(by running apps importingsdl withv -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 simplynot passing-d sdl_use_gc andmanaging memory manually with SDL's memory functions likesdl.free/1,sdl.malloc/1,sdl.calloc/2,sdl.realloc/2 and the variouscreate_* anddestroy functions.

sdl is currently supported on:

• Linux
• MacOS (viahomebrew)
• Windows

sudo pacman -S sdl3

brew install sdl3

It is necessary to install the SDL3 development libraries for Windows.To do this, change to the root directory of the sdl module, likecd %HOMEPATH%\.vmodules\sdland runv run windows_install_dependencies.vsh.This will create a directory called "thirdparty" which will be used to download andextract 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\SDL3-3.2.0\lib\x64\SDL3.dll examples\basic_window\cd ..v run sdl\examples\basic_window\main.v

SDL3 can be built from source on all supported platforms(some easier that others). SeeSDL3's documentation for more infoon building and installing from source

Various examples of running some of the included examples.

v run~/.vmodules/sdl/examples/basic_window/v run~/.vmodules/sdl/examples/versions/v run~/.vmodules/sdl/examples/ports/template.v# See `examples/ports/README.md` for more info on `SDL_MAIN_USE_CALLBACKS`.

Install emscripten SDK and followSDL3's emscripten build instructions.

Install the SDL3 emscripten build from thebuild directory with:

cd /path/to/SDL3/emscripten/buildmake install# should install to something like $HOME/.cache/emscripten/sysroot/...

export PKG_CONFIG_PATH_DEFAULTS=$HOME/.cache/emscripten/sysroot/lib/pkgconfig/mkdir /tmp/sdl_wasmv -os wasm32_emscripten -gc none -o /tmp/sdl_wasm/example.html~/.vmodules/sdl/examples/ports/renderer/05-rectangles/emrun /tmp/sdl_wasm/example.html

The recommended way is to build viavab and theextra commandvab-sdl.Seehttps://github.com/vlang/vab/blob/master/docs/docs.md#extending-vabfor more information.

Example of building an.apk forarm64-v8a:

vab sdl --assets~/.vmodules/sdl/examples/assets/ \        --archs"arm64-v8a" \~/.vmodules/sdl/examples/ports/renderer/06-textures/