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. Note that the first build may take several minutes on machines that are not powerful such as Raspberry Pi.
NOTE: For the latest versions of SDL2, please use the master branch!
If you haven't created a Go module for your program, you can do it by making a directory called, for example, app and running the following command inside it:
go mod init app
After that you can start writing code that uses go-sdl2, for example, like the following:
// main.go
package main
import (
"github.com/veandco/go-sdl2/sdl"
)
func main() {
sdl.Init(sdl.INIT_EVERYTHING)
}Then to tell Go to fetch dependencies, you can run:
go mod tidy
and then the program can be built using:
go build
After that, you can execute your program:
./app
On Ubuntu 22.04 and above, type:
apt install libsdl2{,-image,-mixer,-ttf,-gfx}-dev
On Fedora 36 and above, type:
dnf install SDL2{,_image,_mixer,_ttf,_gfx}-devel
On Arch Linux, type:
pacman -S sdl2{,_image,_mixer,_ttf,_gfx}
On Gentoo, type:
emerge -av libsdl2 sdl2-{image,mixer,ttf,gfx}
On macOS, install SDL2 via Homebrew like so:
brew install sdl2{,_image,_mixer,_ttf,_gfx} pkg-config
On Windows,
- Install mingw-w64 from Mingw-builds. A 7z archive extractor software might be needed which can be downloaded here. In this example, we extract the content, which is
mingw64, intoC:\. - Download and install
SDL2-devel-[version]-mingw.zipfiles from https://github.com/libsdl-org/SDL/releases.- Extract the SDL2 folder from the archive using a tool like 7zip
- Inside the extracted SDL2 folder, copy the
i686-w64-mingw32and/orx86_64-w64-mingw32into mingw64 folder e.g.C:\mingw64
- Setup
Pathenvironment variable- Put mingw-w64 binaries location into system
Pathenvironment variable (e.g.C:\mingw64\bin)
- Put mingw-w64 binaries location into system
- Close and open terminal again so the new
Pathenvironment variable takes effect. Now we should be able to rungo buildinside the project directory. - Download and install SDL2 runtime libraries from https://github.com/libsdl-org/SDL/releases. Extract and copy the
.dllfile into the project directory. After that, the program should become runnable. - (Optional) You can repeat Step 2 for SDL_image, SDL_mixer, SDL_ttf
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 to go-sdl2 being under active development, a lot of breaking changes are going to happen during v0.x. With versioning system coming to Go soon, we'll make use of semantic versioning to ensure stability in the future.
Since v0.3.0, it is possible to build statically against included libraries in .go-sdl2-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 .go-sdl2-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.
- Install MinGW toolchain.
- On Arch Linux, it's simply
pacman -S mingw-w64.
- On Arch Linux, it's simply
- Download the SDL2 development package for MinGW here (and the others like SDL_image, SDL_mixer, etc.. here if you use them).
- Extract the SDL2 development package and copy the
x86_64-w64-mingw32folder inside recursively to the system's MinGWx86_64-w64-mingw32folder. You may also do the same for thei686-w64-mingw32folder.- On Arch Linux, it's
cp -r x86_64-w64-mingw32 /usr.
- On Arch Linux, it's
- Now you can start cross-compiling your Go program by running
env 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.exeexecutable file. - Before running the program, you need to put
SDL2.dllfrom the SDL2 runtime package (For others like SDL_image, SDL_mixer, etc.., look for them here) for Windows in the same folder as your executable. - Now you should be able to run the program using Wine or Windows!
- Install Homebrew
- Install MinGW through Homebrew via
brew install mingw-w64 - Download the SDL2 development package for MinGW here (and the others like SDL_image, SDL_mixer, etc.. here if you use them).
- Extract the SDL2 development package and copy the
x86_64-w64-mingwfolder inside recursively to the system's MinGWx86_64-w64-mingw32 folder. You may also do the same for thei686-w64-mingw32folder. 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. - Now you can start cross-compiling your Go program by running
env 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.exeexecutable file. - Before running the program, you need to put
SDL2.dllfrom the SDL2 runtime package (For others like SDL_image, SDL_mixer, etc.., look for them here) for Windows in the same folder as your executable. - Now you should be able to run the program using Wine or Windows!
- Install macOS toolchain via osxcross
- Run the following build command (replace the values in parentheses):
CGO_ENABLED=1 CC=[path-to-osxcross]/target/bin/[arch]-apple-darwin[version]-clang GOOS=darwin GOARCH=[arch] go build -tags static -ldflags "-s -w" -a
NOTE: The following example is for the master branch. Please check the README of v0.4.x for the stable version.
package main
import "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} // purple
pixel := sdl.MapRGBA(surface.Format, colour.R, colour.G, colour.B, colour.A)
surface.FillRect(&rect, pixel)
window.UpdateSurface()
running := true
for running {
for event := sdl.PollEvent(); event != nil; event = sdl.PollEvent() {
switch event.(type) {
case sdl.QuitEvent: // NOTE: Please use `*sdl.QuitEvent` for `v0.4.x` (current version).
println("Quit")
running = false
break
}
}
sdl.Delay(33)
}
}There are two ways a game might be running: one that updates on user input using sdl.WaitEvent() and one that updates regardless of user input using sdl.PollEvent(). You can check the examples of those two loops here.
For more runnable examples, see https://github.com/veandco/go-sdl2-examples. You can run any of the .go files with go run.
Why does the program not run on Windows?
Try putting the runtime libraries (e.g. SDL2.dll and friends) in the same folder as your program.
Why does my program crash randomly or hang?
Putting runtime.LockOSThread() at the start of your main() usually solves the problem (see SDL2 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 the render_queue or render_goroutines examples from https://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.
On macOS, 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 with brew info sdl2_mixer. You could also try installing sdl2_mixer with mpg123 by running brew install sdl2_mixer --with-mpg123.
On Other Operating Systems, you will need to compile smpeg and SDL_mixer from source with the MP3 option enabled. You can find smpeg in the external 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, see https://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 using sdl.Delay() or put the rendering code inside a draw loop.
This project exists thanks to all the people who contribute. [Contribute].
Become a financial contributor and help us sustain our community. [Contribute]
Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]
Go-SDL2 is BSD 3-clause licensed.