This port allows SDL applications to run via Microsoft's Game Development Kit (GDK).
Windows (GDK) and Xbox One/Xbox Series (GDKX) are supported. Although most of the Xbox code is included in the public SDL source code, NDA access is required for a small number of source files. If you have access to GDKX, these required Xbox files are posted on the GDK forums here.
The Windows GDK port supports the full set of Win32 APIs, renderers, controllers, input devices, etc., as the normal Windows x64 build of SDL.
#defined on every GDK platform, and the
#defined on Windows GDK, specifically. (This distinction exists because other GDK platforms support a smaller subset of functionality. This allows you to mark code for "any" GDK separate from Windows GDK.)
NULLas the task queue will make the task get added to the global task queue.
WinMainthat performs the above GDK setup that you can use by #include'ing SDL_main.h in the source file that includes your standard main() function. If you are unable to do this, you can instead manually call
SDL_RunAppfrom your entry point, passing in your
NULLas the parameters. To use
SDL_PumpEvents(which is also called internally if using
SDL_GDKGetTaskQueue, if needed. When done with the queue, be sure to use
XTaskQueueCloseHandleto decrement the reference count (otherwise it will cause a resource leak).
SDL_GDKGetDefaultUserto get the default XUserHandle pointer.
SDL_GetPrefPathstill works, but only for single-player titles.
These functions mostly wrap around async APIs, and thus should be treated as synchronous alternatives. Also note that the single-player functions return on any OS errors, so be sure to validate the return values!
VisualC-GDK/SDL.sln solution includes the following targets for the Gaming.Desktop.x64 configuration:
MicrosoftGame.configto your valid IDs from Partner Center if you wish to test this.
If you set one of the test programs as a startup project, you can run it directly from Visual Studio.
These steps assume you already have a game using SDL that runs on Windows x64 along with a corresponding Visual Studio solution file for the x64 version. If you don't have this, it's easiest to use one of the test program vcxproj files in the
VisualC-GDK directory as a starting point, though you will still need to do most of the steps below.
In your game's existing Visual Studio Solution, go to Build > Configuration Manager. From the "Active solution platform" drop-down select "New...". From the drop-down list, select Gaming.Desktop.x64 and copy the settings from the x64 configuration.
VisualC-GDK/SDL.sln in Visual Studio, you need to build the SDL3 target for the Gaming.Desktop.x64 platform (Release is recommended). You will need to copy/keep track of the
XCurl.dll (which is output by Gaming.Desktop.x64), and
SDL3.lib output files for your game project.
Alternatively, you could setup your solution file to instead reference the SDL3 project file targets from the SDL source, and add those projects as a dependency. This would mean that SDL3 would be built when your game is built.
While the Gaming.Desktop.x64 configuration sets most of the required settings, there are some additional items to configure for your game project under the Gaming.Desktop.x64 Configuration:
SDL/includepath is referenced
Rather than using your own implementation of
WinMain, it's recommended that you instead
#include <SDL3/SDL_main.h> and declare a standard main function. If you are unable to do this, you can instead manually call
SDL_RunApp from your entry point, passing in your
SDL_main function and
NULL as the parameters; in that case
#define SDL_MAIN_HANDLED before including SDL_main.h
The game will not launch in the debugger unless required DLLs are included in the directory that contains the game's .exe file. You need to make sure that the following files are copied into the directory:
You can either copy these in a post-build step, or you can add the dlls into the project and set its Configuration Properties > General > Item type to "Copy file," which will also copy them into the output directory.
You can copy
VisualC-GDK/tests/testgdk/MicrosoftGame.config and use that as a starting point in your project. Minimally, you will want to change the Executable Name attribute, the DefaultDisplayName, and the Description.
This file must be copied into the same directory as the game's .exe file. As with the DLLs, you can either use a post-build step or the "Copy file" item type.
For basic testing, you do not need to change anything else in
MicrosoftGame.config. However, if you want to test any Xbox Live services (such as logging in users) or publish a package, you will need to setup a Game app on Partner Center.
Then, you need to set the following values to the values from Partner Center:
Several logo PNG files are required to be able to launch the game, even from the debugger. You can use the sample logos provided in
VisualC-GDK/logos. As with the other files, they must be copied into the same directory as the game's .exe file.
When debugging GDK games, there is no way to specify a working directory. Therefore, any required game data must also be copied into the output directory, likely in a post-build step.
At this point, you should be able to build and run your game from the Visual Studio Debugger. If you get any linker errors, make sure you double-check that you referenced all the required libs.
If you are testing Xbox Live functionality, it's likely you will need to change to the Sandbox for your title. To do this:
You can use one of the test program's
PackageLayout.xml as a starting point. Minimally, you will need to change the exe to the correct name and also reference any required game data. As with the other data files, it's easiest if you have this copy to the output directory, although it's not a requirement as you can specify relative paths to files.
To create the package:
cdto the directory containing the
PackageLayout.xmlwith the correct paths (if you use the local path as in the sample package layout, this would be from your .exe output directory)
mkdir Packageto create an output directory
makepkg pack /f PackageLayout.xml /lt /d . /nogameos /pc /pd Package
wdapp install PACKAGENAME.msixvc
As of June 2022 GDK, you must have a valid Title Id and MSAAppId in order to test Xbox Live functionality such as user login. Make sure these are set correctly in the
MicrosoftGame.config. This means that even testgdk will not let you login without setting these properties to valid values.
Furthermore, confirm that your PC is set to the correct sandbox.
Prior to June 2022 GDK, running from the Visual Studio debugger would still locally register the app (and it would appear on the start menu). To fix this, you have to uninstall it (it's simplest to right click on it from the start menu to uninstall it).