SDL2 binding for Go
It's almost Chinese New Year so the author decided to hold back no more for this go-sdl2 release! It will also make for a nice checkpoint for people to settle into while it is developed for the next release.
This version brings most of the bindings from SDL2 2.0.6 to the latest version SDL2 2.0.10! They are the ones that are noted in the SDL2 release announcement posts with the exception of some system specific functions (such as Android, WinRT, etc..). More support for those system-specific functions may come within patch version updates! If anything needed is missing, we'd very much appreciate a report via Github issue so we can add it!
The website has also been in the works to become the hub that provides a more curated and centralized way of sharing how certain things are done using SDL2! It is meant as a complementary website in addition to the official one because the official one focuses more on C and lower-level usage. At the moment, this complementary website is focused on go-sdl2 as it is the only package the author is familiar with the C version being the next step. The main meat of the website is the basic, snippet-based tutorials, project-based tutorials, and external resources. The homepage shall serve as status report that relates to SDL2 development in general. Requests for SDL2-related tutorials are welcome via issues on Github!
Prior to v0.4.0, the static libraries weren't fetched as they were in a submodule. However, they have now been merged into the repository instead. This fixes static and/or cross-platform build when using the new Go Module system as it didn't fetch the (previously) sub-module go-sdl2-libs. While this may increase the Git repository size, it shouldn't affect its size as a Go Module dependency as the Git history is not included.
Most of the bindings for SDL2 Vulkan functions have been added which was long overdue since SDL2 2.0.6. It has also been written to be compatible with vulkan-go. Thanks @jclc!
In go-sdl2 v0.3.x, there would be warnings that are printed during build when it has functions that are not supported by the older SDL2. In v0.4.x, the warnings have been disabled by default. However, if user wants to enable it, they can set the CGO_CPPFLAGS to -DWARN_OUTDATED. An example is:
In addition, there is also plenty of fixes in this release and stability of API is even more enforced from here onwards!
CGO_CPPFLAGS=-DWARN_OUTDATED go get -v github.com/veandco/go-sdl2/sdl
Structs
AudioStream
DisplayEvent
SensorEvent
Sensor
MouseButtonEvent.Clicks
Functions
Surface.Duplicate()
RWops.LoadFileRW()
RWops.LoadFile()
Renderer.GetMetalLayer()
Renderer.GetMetalCommandEncoder()
Surface.ColorModel()
Surface.Bounds()
Surface.At()
Surface.Set()
Surface.HasColorKey()
TextInputEvent.GetText()
TextEditingEvent.GetText()
FRect.Empty()
FRect.Equals()
FRect.HasIntersection()
FRect.Intersect()
FPoint.InRect()
GameController.PlayerIndex()
GameController.Rumble()
Joystick.PlayerIndex()
Joystick.Rumble()
GameControllerMappingForDeviceIndex()
JoystickGetDevicePlayerIndex()
HasAVX2()
HasNEON()
ComposeCustomBlendMode()
WarpMouseGlobal()
LockJoysticks()
UnlockJoysticks()
SetYUVConversionMode()
GetYUVConversionMode()
GetYUVConversionModeForResolution()
SensorOpen()
SensorFromInstanceID()
NumSensors()
SensorGetDeviceName()
SensorGetDeviceType()
SensorGetDeviceNonPortableType()
SensorGetDeviceInstanceID()
SensorUpdate()
GetGlobalMouseState()
BytesPerPixel()
BitsPerPixel()
GetTouchDeviceType()
HasAVX512F()
IsAndroidTV()
IsTablet()
Constants
INIT_SENSOR
HINT_AUDIO_RESAMPLING_MODE
HINT_RENDER_LOGICAL_SIZE_MODE
HINT_MOUSE_NORMAL_SPEED_SCALE
HINT_MOUSE_RELATIVE_SPEED_SCALE
HINT_TOUCH_MOUSE_EVENTS
HINT_WINDOWS_INTRESOURCE_ICON
HINT_WINDOWS_INTRESOURCE_ICON_SMALL
HINT_IOS_HIDE_HOME_INDICATOR
HINT_RETURN_KEY_HIDES_IME
HINT_TV_REMOTE_AS_JOYSTICK
HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR
HINT_VIDEO_DOUBLE_BUFFER
HINT_MOUSE_DOUBLE_CLICK_TIME
HINT_MOUSE_DOUBLE_CLICK_RADIUS
BLENDMODE_INVALID
BLENDOPERATION_ADD
BLENDOPERATION_SUBTRACT
BLENDOPERATION_REV_SUBTRACT
BLENDOPERATION_MINIMUM
BLENDOPERATION_MAXIMUM
BLENDFACTOR_ZERO
BLENDFACTOR_ONE
BLENDFACTOR_SRC_COLOR
BLENDFACTOR_ONE_MINUS_SRC_COLOR
BLENDFACTOR_SRC_ALPHA
BLENDFACTOR_ONE_MINUS_SRC_ALPHA
BLENDFACTOR_DST_COLOR
BLENDFACTOR_ONE_MINUS_DST_COLOR
BLENDFACTOR_DST_ALPHA
BLENDFACTOR_ONE_MINUS_DST_ALPHA
YUV_CONVERSION_JPEG
YUV_CONVERSION_BT601
YUV_CONVERSION_BT709
YUV_CONVERSION_AUTOMATIC
STANDARD_GRAVITY
SENSOR_INVALID
SENSOR_UNKNOWN
SENSOR_ACCEL
SENSOR_GYRO
TOUCH_DEVICE_INVALID
TOUCH_DEVICE_DIRECT
TOUCH_DEVICE_INDIRECT_ABSOLUTE
TOUCH_DEVICE_INDIRECT_RELATIVE
Structs
Font.GlyphMetrics
Constants
DROPTEXT
DROPBEGIN
DROPCOMPLETE
MOUSEWHEEL_NORMAL
SYSWM_WINRT
SYSWM_ANDROID
SYSWM_VIVANTE
GL_CONTEXT_RESET_NOTIFICATION
GL_CONTEXT_NO_ERROR
GL_CONTEXT_RELEASE_BEHAVIOR
GL_FRAMEBUFFER_SRGB_CAPABLE
WINDOWEVENT_TAKE_FOCUS
WINDOWEVENT_HIT_TEST
Structs
AudioDeviceEvent
Functions
RWFromMem() (0ee14f91)RWops.FreeRW() to RWops.Free() 0ee14f91RWops.RWsize() to RWops.Size() 0ee14f91RWops.RWseek() to RWops.Seek() 0ee14f91RWops.RWread() to RWops.Read() and RWops.Read2() 0ee14f91RWops.RWtell() to RWops.Tell() 0ee14f91RWops.RWwrite() to RWops.Write() and RWops.Write2() 0ee14f91RWops.RWclose() to RWops.Close() 0ee14f91RWops.RWclose() to RWops.Close() 0ee14f91Window.VulkanCreateSurface to return unsafe.Pointer instead of uintptr 1bad697Functions
Init() now returns error instead of int
Every structures, constants, functions, etc.. now has their own comments for documentation purposes, and they all follow Go's documentation guidelines. You can also visit the original SDL2 function page by following the link that appears on the comment. Many many thanks to @malashin for taking on such a monstrous work!
Previously all the functions defined in go-sdl2 follow the native SDL2 such as having underscores, having Get prefix for getters, and even capitalizations such as TouchId in MultiGestureEvent (which has since become TouchID. Now, plenty of functions have started to follow the Go idiomatic naming conventions and more should follow along the road to the next version! You can see the full list of renamed names in BREAKING.md. Thanks again @malashin!
Examples and assets have been moved to separate repository to reduce base size of the main go-sdl2 repository. You can visit previous examples at https://github.com/veandco/go-sdl2-examples.
It is now possible to build standalone, dependency-free executables by fetching the package using the command go get -v -tags static github.com/veandco/go-sdl2/sdl. Thank you very much @gen2brain for the awesome feature!
Previously JoyDeviceEvent has Which field of JoystickID type which is wrong when a device is added. Therefore to match the behavior of native SDL2, we split the JoyDeviceEvent into JoyDeviceAddedEvent which uses int for its Which field, and JoyDeviceRemovedEvent which uses JoystickID for its Which field. This is also thanks to @malashin!
Previously, to get an Event's type and timestamp, you'd have to type-assert it into one of the specialized types such as WindowEvent or MouseButtonEvent and get them from the public fields Type and Timestamp. Now, you only need to use the common GetType() and GetTimestamp() methods from the base Event interface thanks to @malashin!
Functions:
Constants:
Structs:
Functions:
7e50e6a sdl/events: Fix DropEvent stubs #294 4bf5ad0 sdl/events: Fix DropEvent memory leak #274 3e3b649 sdl/events: fix stub function for SDL_AudioDeviceEvent d4575d0 sdl/events: fix stub function for SDL_AudioDeviceEvent b50c282 sdl/haptic: Fix HapticOpened() returning error on success 4156c30 sdl/surface: Fix stub functions 1efc02d sdl/video: Fix ShowMessageBox() 3420e58 sdl/video: Fix error handling 881e1de sdl/video: Fix stub #304
There is still plenty more of miscellaneous updates that you can check from the curated change log below!
9b73d5a sdl/haptic: Rename iHapticEffect interface to HapticEffect 0ff46e4 sdl/video: Make GL funcs into Window methods #325 (#326) 8e7373e sdl: Replace ints with booleans (#324) 1cae00e sdl/video: Make several functions return values instead of modifying user-provided values through pointers e5fd0c8 sdl: fix misspellings 99737f8 sdl/haptic: Change HapticEffect to interface instead of union (#316) 2b0e4a2 sdl/haptic: Export Dir from HapticDirection{} #315 930022a sdl/gamecontroller,joystick: Add new bindings for SDL 2.0.6 and 2.0.4 (#313) 8759fe0 sdl/surface_test.go: Fix image path 2ac4c06 sdl/video: Remove unused cMessageBoxData struct d715a56 sdl: Remove yuv_sw_c.go 4223939 sdl/haptic: Update error handling 566b724 sdl/video,render: Update error handling; Add SetError() and INIT_EVENTS 3d9462c sdl/render,video: Fix imports d577b44 sdl/render,video: Update imports c231b93 sdl/filesystem_test.go: Run TestGetBasePath only on SDL >= 2.0.1 87aaee2 sdl/cpuinfo_test.go: Run TestGetSystemRAM only on SDL >= 2.0.1 d3d0a1f sdl/events: add stub function for SDL_AudioDeviceEvent 27e36e0 sdl/events: add stub function for SDL_RENDER_DEVICE_RESET ddb9ec5 sdl/haptic: Make methods return bool and/or error instead of int 8c754f4 sdl/sdl: Add errorFromInt() helper function b565ce2 sdl/events: Merge KeyUpEvent and KeyDownEvent to KeyboardEvent 4e7bc65 sdl/mouse: Add fallback definitions for SDL_MOUSEWHEEL_NORMAL and SDL_MOUSEWHEEL_FLIPPED f2dd51e sdl/sdl_wrapper.h: Remove SDL_WINDOW_ALLOW_HIGHDPI definition 07a75b0 sdl/video: Add missing Window flags starting from SDL 2.0.4 6a5f9c4 sdl/mutex: Change Mutex, Sem, Cond to have methods instead of functions 9f2787c sdl/hints_test.go: Fix TestDelHintCallback to use different value for checking from TestAddHintCallback 4ebcc92 sdl: Change types of coordinate and size variables and parameters from int to int32 e798fe3 sdl/events: Fix tests #274 6cfd4a1 sdl/error: Fix documentation #265 bb8985e sdl/render: Fix typo in documentation fc1c183 sdl/render: Add warning message to SDL_UpdateYUVTexture() if used on older SDL2 versions ae9169a gfx: Change types of coordinate and size variables and parameters from int to int32 2da6abc img: Fix tests #265 e22dc78 ttf/sdl_ttf_test.go: Fix font path d487864 examples/audio_wav_memory: audio_wav_memory.go: Update API 82901b8 examples/text: text.go: Update API 509637d examples/text: Revert sdl.RenderUTF8_Solid() to sdl.RenderUTF8Solid() cad2c8a examples/text: Fixed text example 492f14c examples/opengl: Move gl init call 889be5f examples: Update examples to build with latest API b77db23 README: update the example to work out-of-box on macOS (#319) ff97cb1 README.md: Update Mac OS X to macOS ad8f1e5 README.md: Fix markdown syntax error c07017b README.md: Add a note about SDL_mixer 2.0.2 breaking MP3 playback 8289c73 README.md: Add cross-compiling guide for macOS to Windows c231ca3 README.md: Add links to download libraries for other packages like SDL_image, SDL_mixer, etc.. 4160874 README.md: Remove include flag for Linux-to-Windows cross-compiling as it's already defined 0da67c0 README.md: Add cross-compiling guide for Linux to Windows 50d371f README.md: Add installation note for those wishing to stay with latest stable version a33701c README.md: Update installation command on Fedora 807befe README.md: Update installation command on Arch Linux ce485b4 README.md: Update instructions for Ubuntu 2c2a89d README.md: Add installation instructions for Gentoo 906b4c7 BREAKING.md: Fix typo 48cbef8 Update video.go error handling, add SetError() and INIT_EVENTS f0d6bcc Remove note about "go install" since it's already been done by the "go get" step 33dc0c4 Add BREAKING.md for listing breaking changes between version tags 9887766 Update BREAKING.md