mono/MonoGame — pull request #2031 by flibitijibibo (2013-09-25 11:59:17+00:00)
Title: MonoGame-SDL2

This is MonoGame-SDL2, a new MonoGame desktop platform that uses SDL2 as its base platform library.

The details of this pull request have been organized as follows:
- 1: Platform Support
- 2: Libraries
- 3: About the SDL2_GameWindow
- 4: About the SDL2 Event Loop
- 5: About the SDL2_GamePad
- 6: About Song and Video playback
- 7: Example Titles
- 8: Third-Party Contributors

___1: PLATFORM SUPPORT___
MonoGame-SDL2 currently "officially" supports Windows, Mac OSX and GNU/Linux. However, MG-SDL2 platform support is wholly dependent on an operating system's native support for Mono, SDL2 and OpenAL. If an operating system supports these three libraries, then MonoGame-SDL2 is expected to work there. This adds the possibility of supporting more platforms, such as FreeBSD, Haiku, and other SDL2-supported platforms.

To more easily support distributing MonoGame-SDL2 titles on the Mac, MonoKickstart has been updated to support 32- and 64-bit OSX (Snow Leopard 10.6.8 or higher). Without the burden of MonoMac, it is now possible to create and distribute 64-bit Mac OSX MonoGame titles.

_All_ platform code is determined at runtime. This means that a single set of MonoGame-SDL2 assemblies is expected to work on _all_ target platforms without recompilation. The notable exception is potential incompatibilities with output from the .NET/Mono compilers against the .NET/Mono runtimes (for instance, .NET assemblies on the Mono runtime).

___2: LIBRARIES___
MonoGame-SDL2 depends on SDL2# and TheoraPlay#. At the native level, MonoGame-SDL2 requires the following native libraries:

- SDL2: http://www.libsdl.org/
- OpenAL (OpenAL Soft strongly recommended: http://kcat.strangesoft.net/openal.html )
- For Song playback...
- SDL2_mixer: http://www.libsdl.org/projects/SDL_mixer/
- libogg/libvorbis/libvorbisfile, or FLAC: http://xiph.org/
- For Video playback...
- TheoraPlay (found in TheoraPlay# repo): http://icculus.org/theoraplay/
- libogg/libvorbis/libtheora/libtheoradec: http://xiph.org/

If you do not use Song/Video playback, those additional libraries are NOT required. If you do not use Video playback, you can even ignore TheoraPlay# when packaging your game.

Windows and Linux do NOT use OpenTK, and OSX does NOT use MonoMac. However, we use the OpenTK OpenGL and OpenAL bindings, which are currently bundled in SDL2# as "MiniTK".

___3: ABOUT THE SDL2_GameWindow___
MonoGame-SDL2's GameWindow is notable for its behavior with regard to display management, particularly in fullscreen mode.

A common problem with OpenTK, and cross-platform display management in general, is that fullscreen modes are _very_ inconsistent in behavior and are incredibly volatile, particularly on Linux and in several situations on OSX (most notably Retina Displays). To resolve this, SDL2 includes a feature called "SDL_WINDOW_FULLSCREEN_DESKTOP", which will _always_ set the fullscreen resolution at the resolution set by the operating system's desktop environment. So, if your desktop is set to 1920x1200, SDL_WINDOW_FULLSCREEN_DESKTOP will _always_ set the fullscreen resolution to 1920x1200.

In combination with SDL_WINDOW_FULLSCREEN_DESKTOP, SDL2_GameWindow uses an internal framebuffer object to act as the "backbuffer", which retains the _actual_ desired resolution. Upon calling SwapBuffers, we blit the framebuffer to the backbuffer, scaling the image to the desktop resolution if needed. Mouse cursor positions are also scaled when necessary, for the sake of accuracy.

On top of resolving the issue of fullscreen instability, it also allows MonoGame developers to set the depth-stencil attachment of "backbuffer", something that was previously not possible without trashing the OpenGL context.

When querying your game's current resolution, it is _strongly_ recommended that you use GraphicsAdapter.CurrentDisplayMode, as SDL2_GameWindow.ClientBounds will give you the SDL2 window resolution, which may be different than the resolution in fullscreen mode. Both have their usefulness, but for portability and accuracy purposes, the GraphicsAdapter is given the "intended" resolution, while the SDL2_GameWindow has been given the info based on its platform-specific behavior, per the XNA4 specification.

The SDL2_GameWindow's Handle property will return the SDL_Window* IntPtr, so rather than using System.Windows.Forms, you should use SDL2# when directly modifying the GameWindow on MG-SDL2.

For window icons, we attempt to load a BMP file that is the name of the window. For example, naming the window "FEZ" will attempt to load "FEZ.bmp" as the window icon.

___4: ABOUT THE SDL2 EVENT LOOP___
Rather than using callbacks, the SDL2 platform polls events pumped by the SwapBuffers call. The event loop can be found here:

https://github.com/flibitijibibo/MonoGame/blob/mg-sdl2-final/MonoGame.Framework/SDL2/SDL2_GameWindow.cs#L341

This simplifies event tracking as well as maintenance of various events. For example, controller hotplugging support can be added simply by adding the DEVICE events to this loop.

___5: ABOUT THE SDL2_GamePad___
The GamePad support has been completely rewritten to drastically improve controller support.

At the same time, MonoGame-SDL2 both improves configurability of controller support as well as automating configuration of controllers for MonoGame titles.

SDL2 has a subsystem called "SDL_GameController", a system added by Alfred Reynolds at Valve Software. When a joystick is recognized by SDL2 as a GameController, the device is automatically configured around the Xbox 360 controller format. Within SDL2 itself, Xbox 360 controllers, PS3 controllers and various Logitech controllers are automatically supported, but GameController bindings can be found from outside of libSDL2 itself. For example, if an SDL2 title is run via Steam, SDL2 will obtain controller configurations from Steam Big Picture Mode, so _any_ controller that has been run through Steam Big Picture will automatically be configured for a MonoGame-SDL2 title. This feature is of significant importance for SteamOS in particular.

In situations where a joystick is NOT supported by SDL_GameController, users can configure joysticks with the MonoGameJoystick.cfg configuration file. This has been documented on the PCGamingWiki:

http://pcgamingwiki.com/wiki/Engine:MonoGame#Joysticks

Another new addition to MonoGame is support for controller vibration. SDL2 not only provides haptic support, but provides left/right motor support where supported. Currently, Windows and Linux support left/right vibration, while OSX does not. In situations where the haptic device does not support left/right vibration, we simply run a simple sine wave vibration using the left/right strengths.

While SDL2 does support controller hotplugging, MonoGame-SDL2 currently does NOT support hotplugging.

___6: ABOUT SONG AND VIDEO PLAYBACK___
MonoGame-SDL2 uses SDL2_mixer for Song playback. We automatically look for FLAC and Ogg Vorbis by default, but any format that SDL2_mixer supports is expected to run on MonoGame-SDL2. mp3 support is NOT checked for by default, primarily due to patent/licensing concerns.

MonoGame-SDL2 contains a brand new VideoPlayer based on TheoraPlay#. Rather than using Windows Media Video, MG-SDL2 reads in Ogg Theora video data.

Audio is streamed into OpenAL, and video can be streamed either via software rendering or via OpenGL acceleration. For MonoGame-SDL2, we use the YUV->RGBA OpenGL acceleration by default.

___7: EXAMPLE GAMES___
Since SDL2# development began in April of this year, MonoGame-SDL2 has shipped in over half a dozen commercial titles across multiple promotions, including the Humble Indie Bundle, and many of them will be among the first to ship on Valve's new SteamOS.

Some games currently using MonoGame-SDL2 are...

Capsized: http://store.steampowered.com/app/95300
Gateways: http://store.steampowered.com/app/216290
Escape Goat: http://steamcommunity.com/sharedfiles/filedetails/?id=92951461
Soulcaster I/II: http://www.magicaltimebean.com/soulcaster-ii/
FEZ: http://store.steampowered.com/app/224760
A Virus Named TOM: http://store.steampowered.com/app/207650

___8: THIRD-PARTY CONTRIBUTORS___
The following developers were involved in the development of MonoGame-SDL2, and have been CC'd into this thread, with their related attributions.

- @sulix - General MonoGame-SDL2 development/design/bugfixing, Humble QA
- @khbecker - VideoPlayer bugfixing, Humble QA
- @xanather - TextInputEvent support for MonoGame-SDL2