SDL2 binding for Go

go-sdl2 is SDL2 wrapped for Go users. It enables interoperability between Go and the SDL2 library which is written in C. That means the original SDL2 installation is required for this to work.

Table of Contents

• Documentation
• Examples
• Requirements
• Installation
• Cross-compiling
• FAQ
• License

Documentation

• GoDoc documentation for go-sdl2
• Original SDL2 wiki

Examples

package mainimport "github.com/veandco/go-sdl2/sdl"func main() {if err := sdl.Init(sdl.INIT_EVERYTHING); err != nil {panic(err)}defer sdl.Quit()window, err := sdl.CreateWindow("test", sdl.WINDOWPOS_UNDEFINED, sdl.WINDOWPOS_UNDEFINED,800, 600, sdl.WINDOW_SHOWN)if err != nil {panic(err)}defer window.Destroy()surface, err := window.GetSurface()if err != nil {panic(err)}surface.FillRect(nil, 0)rect := sdl.Rect{0, 0, 200, 200}colour := sdl.Color{R: 255, G: 0, B: 255, A: 255} // purplepixel := sdl.MapRGBA(surface.Format, colour.R, colour.G, colour.B, colour.A)surface.FillRect(&rect, pixel)window.UpdateSurface()running := truefor running {for event := sdl.PollEvent(); event != nil; event = sdl.PollEvent() {switch event.(type) {case *sdl.QuitEvent:println("Quit")running = falsebreak}}}}

For more complete examples, seehttps://github.com/veandco/go-sdl2-examples. You can run any of the.go files withgo run.

Requirements

• SDL2
• SDL2_image (optional)
• SDL2_mixer (optional)
• SDL2_ttf (optional)
• SDL2_gfx (optional)

Below is some commands that can be used to install the required packages insome Linux distributions. Some older versions of the distributions such asUbuntu 13.10 may also be used but it may miss an optional package such aslibsdl2-ttf-dev on Ubuntu 13.10's case which is available in Ubuntu 14.04.

OnUbuntu 14.04 and above, type:
apt install libsdl2{,-image,-mixer,-ttf,-gfx}-dev

OnFedora 25 and above, type:
yum install SDL2{,_image,_mixer,_ttf,_gfx}-devel

OnArch Linux, type:
pacman -S sdl2{,_image,_mixer,_ttf,_gfx}

OnGentoo, type:
emerge -av libsdl2 sdl2-{image,mixer,ttf,gfx}

OnmacOS, install SDL2 viaHomebrew like so:
brew install sdl2{,_image,_mixer,_ttf,_gfx} pkg-config

OnWindows,

1. Install mingw-w64 fromMingw-builds
   • Version: latest (at time of writing 6.3.0)
   • Architecture: x86_64
   • Threads: win32
   • Exception: seh
   • Build revision: 1
   • Destination Folder: Select a folder that your Windows user owns
2. Install SDL2http://libsdl.org/download-2.0.php
   • Extract the SDL2 folder from the archive using a tool like7zip
   • Inside the folder, copy thei686-w64-mingw32 and/orx86_64-w64-mingw32 depending on the architecture you chose into your mingw-w64 folder e.g.C:\Program Files\mingw-w64\x86_64-6.3.0-win32-seh-rt_v5-rev1\mingw64
3. Setup Path environment variable
   • Put your mingw-w64 binaries location into your system Path environment variable. e.g.C:\Program Files\mingw-w64\x86_64-6.3.0-win32-seh-rt_v5-rev1\mingw64\bin andC:\Program Files\mingw-w64\x86_64-6.3.0-win32-seh-rt_v5-rev1\mingw64\x86_64-w64-mingw32\bin
4. Open up a terminal such asGit Bash and rungo get -v github.com/veandco/go-sdl2/sdl.
5. (Optional) You can repeatStep 2 forSDL_image,SDL_mixer,SDL_ttf
   • NOTE: pre-build the libraries for faster compilation by runninggo install github.com/veandco/go-sdl2/{sdl,img,mix,ttf}

• Or you can install SDL2 viaMsys2 like so:pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-SDL2{,_image,_mixer,_ttf,_gfx}

Installation

To get the bindings, type:
go get -v github.com/veandco/go-sdl2/sdl
go get -v github.com/veandco/go-sdl2/img
go get -v github.com/veandco/go-sdl2/mix
go get -v github.com/veandco/go-sdl2/ttf
go get -v github.com/veandco/go-sdl2/gfx

or type this if you use Bash terminal:
go get -v github.com/veandco/go-sdl2/{sdl,img,mix,ttf}

Due togo-sdl2 being under active development, a lot of breaking changes are going to happen during v0.x. Withversioning system coming to Go soon, we'll make use of semantic versioning to ensure stability in the future.

Static compilation

Since v0.3.0, it is possible to build statically against included libraries in_libs. To build statically, run:

CGO_ENABLED=1 CC=gcc GOOS=linux GOARCH=amd64 go build -tags static -ldflags "-s -w"

You can also cross-compile to another OS. For example, to Windows:

CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc GOOS=windows GOARCH=amd64 go build -tags static -ldflags "-s -w"

On Windows, if you would like to hide the Command Prompt window when running the statically-compiled program, you could append-H windowsgui to the-ldflags value.

For the list of OS and architecture, you can see inside the_libs directory.

NOTE: If you're using the new Go Module system, you will need to refer to the master branch for now by running:

go get -v github.com/veandco/go-sdl2/sdl@master

Before building the program.

Cross-compiling

Linux to Windows

1. Install MinGW toolchain.
   • OnArch Linux, it's simplypacman -S mingw-w64.
2. Download the SDL2 development package for MinGWhere (and the others likeSDL_image,SDL_mixer, etc..here if you use them).
3. Extract the SDL2 development package and copy thex86_64-w64-mingw32 folder inside recursively to the system's MinGWx86_64-w64-mingw32 folder. You may also do the same for thei686-w64-mingw32 folder.
   • OnArch Linux, it'scp -r x86_64-w64-mingw32 /usr.
4. Now you can start cross-compiling your Go program by runningenv CGO_ENABLED="1" CC="/usr/bin/x86_64-w64-mingw32-gcc" GOOS="windows" CGO_LDFLAGS="-lmingw32 -lSDL2" CGO_CFLAGS="-D_REENTRANT" go build -x main.go. You can change some of the parameters if you'd like to. In this example, it should produce amain.exe executable file.
5. Before running the program, you need to putSDL2.dll from theSDL2 runtime package (For others likeSDL_image,SDL_mixer, etc.., look for themhere) for Windows in the same folder as your executable.
6. Now you should be able to run the program using Wine or Windows!

macOS to Windows

1. InstallHomebrew
2. Install MinGW through Homebrew viabrew install mingw-w64
3. Download the SDL2 development package for MinGWhere (and the others likeSDL_image,SDL_mixer, etc..here if you use them).
4. Extract the SDL2 development package and copy thex86_64-w64-mingw folder inside recursively to the system's MinGWx86_64-w64-mingw32 folder. You may also do the same for thei686-w64-mingw32 folder. The path to MinGW may be slightly different but the command should look something likecp -r x86_64-w64-mingw32 /usr/local/Cellar/mingw-w64/5.0.3/toolchain-x86_64.
5. Now you can start cross-compiling your Go program by runningenv CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc GOOS=windows CGO_LDFLAGS="-L/usr/local/Cellar/mingw-w64/5.0.3/toolchain-x86_64/x86_64-w64-mingw32/lib -lSDL2" CGO_CFLAGS="-I/usr/local/Cellar/mingw-w64/5.0.3/toolchain-x86_64/x86_64-w64-mingw32/include -D_REENTRANT" go build -x main.go. You can change some of the parameters if you'd like to. In this example, it should produce amain.exe executable file.
6. Before running the program, you need to putSDL2.dll from theSDL2 runtime package (For others likeSDL_image,SDL_mixer, etc.., look for themhere) for Windows in the same folder as your executable.
7. Now you should be able to run the program using Wine or Windows!

Linux to macOS (static build using podman or docker)

1. Run a container. This example uses Debian image with Podman.

podman run -it --name debian debian:latest bash

1. Install required packages.

apt update && apt install -y vim git curl xz-utils clang make cmake libxml2-dev libssl-dev libz-dev

1. Clone osxcross

cd /optgit clone https://github.com/tpoechtrager/osxcross

1. Build macOS SDK

cd /opt/osxcross/tarballscurl -O https://s3.veand.co/go-sdl2/MacOSX11.3.sdk.tar.xzcd /opt/osxcrossSDK_VERSION=11.3 ./build.sh

1. Download and extract Go

cd /optcurl -L -O https://go.dev/dl/go1.20.linux-amd64.tar.gztar xf go1.20.linux-amd64.tar.gz

1. Set up PATH for Go by editing ~/.profile

vim ~/.profile

Put the following content at the bottom of~/.profile:

# ~/.profileexport GOROOT="/opt/go"export GOPATH="/opt/.go"export PATH="$GOPATH/bin:$GOROOT/bin:$PATH"

Reload .profile

. ~/.profile

1. Set up an example go-sdl2 project

cd /optmkdir examplecd /opt/examplego mod init examplevim main.go

Put the following code inmain.go:

package mainimport ("github.com/veandco/go-sdl2/sdl""github.com/veandco/go-sdl2/ttf""github.com/veandco/go-sdl2/img""github.com/veandco/go-sdl2/mix")func main() {sdl.Init(sdl.INIT_EVERYTHING)ttf.Init()img.Init(img.INIT_PNG)mix.Init(mix.INIT_MP3)}

Then rungo mod tidy to download the dependencies.

1. Create a build script for cross-compiling the program to macOS

vim build.sh

Put the following content inbuild.sh:

#!/usr/bin/env bashexport TARGET="x86_64-apple-darwin20.4"export OSXCROSS="/opt/osxcross"export SDK_VERSION=11.3export DARWIN="${OSXCROSS}/target"export DARWIN_SDK="${DARWIN}/SDK/MacOSX${SDK_VERSION}.sdk"export PATH="${DARWIN}/bin:${DARWIN_SDK}/bin:${PATH}"export LDFLAGS="-L${DARWIN_SDK}/lib -mmacosx-version-min=10.10"export CC="${TARGET}-clang"export CXX="${TARGET}-clang++"CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 go build -tags static -ldflags "-s -w"

Then make it executable and run it:

chmod +x build.sh./build.sh

1. After it finished building, you can copy the executable to your local machine by running this on the host machine:

podman cp debian:/opt/example/example .

FAQ

Why does the program not run on Windows?Try putting theruntime libraries (e.g.SDL2.dll and friends) in the same folder as your program.

Why does my program crash randomly or hang?Puttingruntime.LockOSThread() at the start of your main() usually solves the problem (seeSDL2 FAQ about multi-threading).

UPDATE: Recent update added a call queue system where you can put thread-sensitive code and have it called synchronously on the same OS thread. See therender_queue orrender_goroutines examples fromhttps://github.com/veandco/go-sdl2-examples to see how it works.

Why can't SDL_mixer seem to play MP3 audio file?Your installed SDL_mixer probably doesn't support MP3 file.

OnmacOS, this is easy to correct. First remove the faulty mixer:brew remove sdl2_mixer, then reinstall it with the MP3 option:brew install sdl2_mixer --with-flac --with-fluid-synth --with-libmikmod --with-libmodplug --with-smpeg2. If necessary, check which options you can enable withbrew info sdl2_mixer. You could also try installing sdl2_mixer with mpg123 by runningbrew install sdl2_mixer --with-mpg123.

OnOther Operating Systems, you will need to compile smpeg and SDL_mixer from source with the MP3 option enabled. You can find smpeg in theexternal directory of SDL_mixer. Refer to issue#148 for instructions.

Note that there seems to be a problem with SDL_mixer 2.0.2 so you can also try to revert back to 2.0.1 and see if it solves your problem

Does go-sdl2 support compiling on mobile platforms like Android and iOS?For Android, seehttps://github.com/veandco/go-sdl2-examples/tree/master/examples/android.

There is currently no support for iOS yet.

Why does my window not immediately render after creation?It appears the rendering subsystem needs some time to be able to present the drawn pixels. This can be workaround by adding delay usingsdl.Delay() or put the rendering code inside a draw loop.

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute].

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

License

Go-SDL2 is BSD 3-clause licensed.