go-sdl2

Android

Support for Android is available via examples in the go-sdl2-examples repository: https://github.com/veandco/go-sdl2-examples/tree/master/examples/android.

iOS

There is currently no support for iOS.

Install the core SDL2 bindings and optional extension bindings using go get. If you are using the Go Module system and need the latest features, refer to the master branch.

Core bindings:

• github.com/veandco/go-sdl2/sdl

Optional extension bindings:

• github.com/veandco/go-sdl2/img (SDL2_image)
• github.com/veandco/go-sdl2/mix (SDL2_mixer)
• github.com/veandco/go-sdl2/ttf (SDL2_ttf)
• github.com/veandco/go-sdl2/gfx (SDL2_gfx)

go get -v github.com/veandco/go-sdl2/{sdl,img,mix,ttf}

Since v0.3.0, you can build statically against included libraries in .go-sdl2-libs. This is useful for creating portable binaries.

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

Windows Static Build (from Linux/macOS): CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc GOOS=windows GOARCH=amd64 go build -tags static -ldflags "-s -w"

Note: To hide the Command Prompt window on Windows, append -H windowsgui to the -ldflags value.

To maintain compatibility with older versions of SDL2, go-sdl2 uses CGO with #if guards to provide dummy implementations for functions introduced in newer SDL2 versions. This prevents compilation errors when building against an older library.

Implementation Pattern

1. Use the SDL_VERSION_ATLEAST(major, minor, patch) macro to check the installed version.
2. Use #if defined(WARN_OUTDATED) to provide a compile-time warning (enabled via CGO_CPPFLAGS=-DWARN_OUTDATED).
3. Define a static dummy function in the C block that does nothing.

Example for SDL_LockSensors (introduced in 2.0.14):

package sdl

/*
#include "sdl_wrapper.h"

#if !(SDL_VERSION_ATLEAST(2,0,14))

#if defined(WARN_OUTDATED)
#pragma message("SDL_LockSensors is not supported before SDL 2.0.14")
#endif

static void SDL_LockSensors(void)
{
    // do nothing
}

#endif
*/
import "C"

The go-sdl2 package is a wrapper around the C library, so the original SDL2 development libraries must be installed on your system.

To cross-compile from Linux to Windows, you need the MinGW toolchain and the SDL2 development package for MinGW.

1. Install MinGW: On Arch Linux, use pacman -S mingw-w64.
2. Setup SDL2 for MinGW: Download the SDL2 development package for MinGW. Extract it and copy the x86_64-w64-mingw32 folder recursively into your system's MinGW x86_64-w64-mingw32 folder (e.g., cp -r x86_64-w64-mingw32 /usr on Arch).
3. Build: Run the following command: 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
4. Deployment: Place SDL2.dll from the SDL2 runtime package in the same folder as your generated .exe.

To use go-sdl2 on Windows, follow these steps:

1. Install MinGW-w64: Download from Mingw-builds. Extract the content (e.g., mingw64) to C:\.
2. Install SDL2 Development Files: Download SDL2-devel-[version]-mingw.zip from SDL Releases. Extract it and copy the i686-w64-mingw32 and/or x86_64-w64-mingw32 folders into your C:\mingw64 directory.
3. Update PATH: Add the MinGW binaries location (e.g., C:\mingw64\bin) to your system Path environment variable. Restart your terminal.
4. Runtime DLLs: Download the SDL2 runtime libraries from SDL Releases. Extract and copy the .dll file into your project directory alongside your executable.

To use go-sdl2 in a new project, initialize a Go module and import the sdl package. You must run go mod tidy to fetch the dependencies before building.

// main.go
package main

import (
	"github.com/veandco/go-sdl2/sdl"
)

func main() {
	sdl.Init(sdl.INIT_EVERYTHING)
}

go mod init app
go mod tidy
go build
./app

Recent updates to the sdl package have introduced several breaking changes, primarily involving the renaming of RWops methods and changes to Window.VulkanCreateSurface return types.

RWops Method Renames

Most RWops methods have been renamed to remove the RW prefix:

• RWops.FreeRW() $\rightarrow$ RWops.Free()
• RWops.RWsize() $\rightarrow$ RWops.Size()
• RWops.RWseek() $\rightarrow$ RWops.Seek()
• RWops.RWread() $\rightarrow$ RWops.Read() and RWops.Read2()
• RWops.RWtell() $\rightarrow$ RWops.Tell()
• RWops.RWwrite() $\rightarrow$ RWops.Write() and RWops.Write2()
• RWops.RWclose() $\rightarrow$ RWops.Close()

Other sdl Changes

• RWFromMem() has changed.
• Window.VulkanCreateSurface now returns unsafe.Pointer instead of uintptr.