SDL: Sync wiki -> headers. (5b7b3)

SDL Commits
1 
From 5b7b3da701a6112c33c5dd2684d74157b977e9ed Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 28 Feb 2023 12:56:01 -0500
Subject: [PATCH] Sync wiki -> headers.

---
 docs/README-.md            |   6 +
 docs/README-android.md     |  28 ++--
 docs/README-cmake.md       |  12 +-
 docs/README-directfb.md    |  10 +-
 docs/README-dynapi.md      | 108 ++++++-------
 docs/README-gdk.md         | 310 ++++++++++++++++++-------------------
 docs/README-gesture.md     |   6 +-
 docs/README-git.md         |  38 ++---
 docs/README-hg.md          |   8 +-
 docs/README-ios.md         |  22 +--
 docs/README-kmsbsd.md      |  54 +++----
 docs/README-linux.md       |  34 ++--
 docs/README-macos.md       |  14 +-
 docs/README-nacl.md        |  52 +++----
 docs/README-ngage.md       |  88 +++++------
 docs/README-os2.md         | 184 +++++++++++-----------
 docs/README-pandora.md     |   2 +-
 docs/README-ps2.md         |   4 +-
 docs/README-psp.md         |   4 +-
 docs/README-raspberrypi.md |  40 ++---
 docs/README-riscos.md      |  82 +++++-----
 docs/README-touch.md       |   2 +-
 docs/README-versions.md    | 120 +++++++-------
 docs/README-visualc.md     | 228 +++++++++++++--------------
 docs/README-vita.md        |  66 ++++----
 docs/README-windows.md     | 116 +++++++-------
 docs/README-winrt.md       | 128 +++++++--------
 27 files changed, 886 insertions(+), 880 deletions(-)
 create mode 100644 docs/README-.md

diff --git a/docs/README-.md b/docs/README-.md
new file mode 100644
index 000000000000..0c0235e6440c
--- /dev/null
+++ b/docs/README-.md
@@ -0,0 +1,6 @@
+#
+
+<!-- BEGIN CATEGORY LIST -->
+- [raspberrypi](raspberrypi)
+<!-- END CATEGORY LIST -->
+
diff --git a/docs/README-android.md b/docs/README-android.md
index a247e5721021..4933046e7c30 100644
--- a/docs/README-android.md
+++ b/docs/README-android.md
@@ -26,9 +26,9 @@ How the port works
 ================================================================================
 
 - Android applications are Java-based, optionally with parts written in C
-- As SDL apps are C-based, we use a small Java shim that uses JNI to talk to 
+- As SDL apps are C-based, we use a small Java shim that uses JNI to talk to
   the SDL library
-- This means that your application C code must be placed inside an Android 
+- This means that your application C code must be placed inside an Android
   Java project, along with some C support code that communicates with Java
 - This eventually produces a standard Android .apk package
 
@@ -69,7 +69,7 @@ done in the build directory for the app!
 
 
 For more complex projects, follow these instructions:
-    
+
 1. Copy the android-project directory wherever you want to keep your projects
    and rename it to the name of your project.
 2. Move or symlink this SDL directory into the "<project>/app/jni" directory
@@ -132,15 +132,15 @@ Here's an example of a minimal class file:
 
     --- MyGame.java --------------------------
     package com.gamemaker.game;
-    
-    import org.libsdl.app.SDLActivity; 
-    
+
+    import org.libsdl.app.SDLActivity;
+
     /**
-     * A sample wrapper class that just calls SDLActivity 
-     */ 
-    
+     * A sample wrapper class that just calls SDLActivity
+     */
+
     public class MyGame extends SDLActivity { }
-    
+
     ------------------------------------------
 
 Then replace "SDLActivity" in AndroidManifest.xml with the name of your
@@ -179,7 +179,7 @@ may want to keep this fact in mind when building your APK, specially when large
 files are involved.
 For more information on which extensions get compressed by default and how to
 disable this behaviour, see for example:
-    
+
 http://ponystyle.com/blog/2010/03/26/dealing-with-asset-compression-in-android-apps/
 
 
@@ -350,7 +350,7 @@ I get output from addr2line showing that it's in the quit function, in testsprit
 You can add logging to your code to help show what's happening:
 
     #include <android/log.h>
-    
+
     __android_log_print(ANDROID_LOG_INFO, "foo", "Something happened! x = %d", x);
 
 If you need to build without optimization turned on, you can create a file called
@@ -440,7 +440,7 @@ where you only update a portion of the screen on each frame, you may notice a
 variety of visual glitches on Android, that are not present on other platforms.
 This is caused by SDL's use of EGL as the support system to handle OpenGL ES/ES2
 contexts, in particular the use of the eglSwapBuffers function. As stated in the
-documentation for the function "The contents of ancillary buffers are always 
+documentation for the function "The contents of ancillary buffers are always
 undefined after calling eglSwapBuffers".
 Setting the EGL_SWAP_BEHAVIOR attribute of the surface to EGL_BUFFER_PRESERVED
 is not possible for SDL as it requires EGL 1.4, available only on the API level
@@ -459,7 +459,7 @@ Two legitimate ways:
 Activity by calling Activity.finish().
 
 - Android OS can decide to terminate your application by calling onDestroy()
-(see Activity life cycle). Your application will receive a SDL_QUIT event you 
+(see Activity life cycle). Your application will receive a SDL_QUIT event you
 can handle to save things and quit.
 
 Don't call exit() as it stops the activity badly.
diff --git a/docs/README-cmake.md b/docs/README-cmake.md
index b10751c1a347..a86be338c128 100644
--- a/docs/README-cmake.md
+++ b/docs/README-cmake.md
@@ -3,10 +3,10 @@
 (www.cmake.org)
 
 SDL's build system was traditionally based on autotools. Over time, this
-approach has suffered from several issues across the different supported 
+approach has suffered from several issues across the different supported
 platforms.
 To solve these problems, a new build system based on CMake was introduced.
-It is developed in parallel to the legacy autotools build system, so users 
+It is developed in parallel to the legacy autotools build system, so users
 can experiment with it without complication.
 
 The CMake build system is supported on the following platforms:
@@ -59,15 +59,15 @@ if(MYGAME_VENDORED)
 else()
     # 1. Look for a SDL2 package, 2. look for the SDL2 component and 3. fail if none can be found
     find_package(SDL2 REQUIRED CONFIG REQUIRED COMPONENTS SDL2)
-    
-    # 1. Look for a SDL2 package, 2. Look for the SDL2maincomponent and 3. DO NOT fail when SDL2main is not available 
+
+    # 1. Look for a SDL2 package, 2. Look for the SDL2maincomponent and 3. DO NOT fail when SDL2main is not available
     find_package(SDL2 REQUIRED CONFIG COMPONENTS SDL2main)
 endif()
 
-# Create your game executable target as usual 
+# Create your game executable target as usual
 add_executable(mygame WIN32 mygame.c)
 
-# SDL2::SDL2main may or may not be available. It is e.g. required by Windows GUI applications  
+# SDL2::SDL2main may or may not be available. It is e.g. required by Windows GUI applications
 if(TARGET SDL2::SDL2main)
     # It has an implicit dependency on SDL2 functions, so it MUST be added before SDL2::SDL2 (or SDL2::SDL2-static)
     target_link_libraries(mygame PRIVATE SDL2::SDL2main)
diff --git a/docs/README-directfb.md b/docs/README-directfb.md
index 3b28eef344e2..bbc6e993ba78 100644
--- a/docs/README-directfb.md
+++ b/docs/README-directfb.md
@@ -12,7 +12,7 @@ Supports:
 What you need:
 
 * DirectFB 1.0.1, 1.2.x, 1.3.0
-* Kernel-Framebuffer support: required: vesafb, radeonfb .... 
+* Kernel-Framebuffer support: required: vesafb, radeonfb ....
 * Mesa 7.0.x	   - optional for OpenGL
 
 The `/etc/directfbrc` file should contain the following lines to make
@@ -44,7 +44,7 @@ To use hardware accelerated YUV-overlays for YUV-textures, use:
 export SDL_DIRECTFB_YUV_DIRECT=1

-This is disabled by default. It will only support one
+This is disabled by default. It will only support one
YUV texture, namely the first. Every other YUV texture will be
rendered in software.

@@ -84,7 +84,7 @@ As of this writing 20100802 you need to pull Mesa from git and do the following:

git clone git://anongit.freedesktop.org/git/mesa/mesa
-cd mesa 
+cd mesa
git checkout 2c9fdaf7292423c157fc79b5ce43f0f199dd753a

@@ -92,10 +92,10 @@ Edit configs/linux-directfb so that the Directories-section looks like this:

# Directories
-SRC_DIRS     = mesa glu 
+SRC_DIRS     = mesa glu
GLU_DIRS     = sgi
DRIVER_DIRS  = directfb
-PROGRAM_DIRS = 
+PROGRAM_DIRS =

Then do the following:
diff --git a/docs/README-dynapi.md b/docs/README-dynapi.md
index 47b726b1df44…7649c1d93a2d 100644
— a/docs/README-dynapi.md
+++ b/docs/README-dynapi.md
@@ -4,29 +4,29 @@ Originally posted on Ryan’s Google+ account.

Background:

– The Steam Runtime has (at least in theory) a really kick-ass build of SDL2,

  • but developers are shipping their own SDL2 with individual Steam games.
  • These games might stop getting updates, but a newer SDL2 might be needed later.
  • Certainly we’ll always be fixing bugs in SDL, even if a new video target isn’t
    ± The Steam Runtime has (at least in theory) a really kick-ass build of SDL2,
  • but developers are shipping their own SDL2 with individual Steam games.
  • These games might stop getting updates, but a newer SDL2 might be needed later.
  • Certainly we’ll always be fixing bugs in SDL, even if a new video target isn’t
    ever needed, and these fixes won’t make it to a game shipping its own SDL.
    – Even if we replace the SDL2 in those games with a compatible one, that is to
  • say, edit a developer’s Steam depot (yuck!), there are developers that are
  • statically linking SDL2 that we can’t do this for. We can’t even force the
    ± Even if we replace the SDL2 in those games with a compatible one, that is to
  • say, edit a developer’s Steam depot (yuck!), there are developers that are
  • statically linking SDL2 that we can’t do this for. We can’t even force the
    dynamic loader to ignore their SDL2 in this case, of course.
  • If you don’t ship an SDL2 with the game in some form, people that disabled the
  • Steam Runtime, or just tried to run the game from the command line instead of
  • Steam Runtime, or just tried to run the game from the command line instead of
    Steam might find themselves unable to run the game, due to a missing dependency.
  • If you want to ship on non-Steam platforms like GOG or Humble Bundle, or target
  • generic Linux boxes that may or may not have SDL2 installed, you have to ship
  • the library or risk a total failure to launch. So now, you might have to have
  • a non-Steam build plus a Steam build (that is, one with and one without SDL2
  • included), which is inconvenient if you could have had one universal build
  • generic Linux boxes that may or may not have SDL2 installed, you have to ship
  • the library or risk a total failure to launch. So now, you might have to have
  • a non-Steam build plus a Steam build (that is, one with and one without SDL2
  • included), which is inconvenient if you could have had one universal build
    that works everywhere.
    – We like the zlib license, but the biggest complaint from the open source
  • community about the license change is the static linking. The LGPL forced this
    ± We like the zlib license, but the biggest complaint from the open source
  • community about the license change is the static linking. The LGPL forced this
    as a legal, not technical issue, but zlib doesn’t care. Even those that aren’t
  • concerned about the GNU freedoms found themselves solving the same problems:
  • swapping in a newer SDL to an older game often times can save the day.
  • concerned about the GNU freedoms found themselves solving the same problems:
  • swapping in a newer SDL to an older game often times can save the day.
    Static linking stops this dead.

So here’s what we did:
@@ -45,7 +45,7 @@ Except that is all done with a bunch of macro magic so we don’t have to maintain
every one of these.

What is jump_table.SDL_init()? Eventually, that’s a function pointer of the real
-SDL_Init() that you’ve been calling all this time. But at startup, it looks more
+SDL_Init() that you’ve been calling all this time. But at startup, it looks more
like this:

@@ -56,12 +56,12 @@ Uint32 SDL_Init_DEFAULT(Uint32 flags)
}

-SDL_InitDynamicAPI() fills in jump_table with all the actual SDL function
-pointers, which means that this _DEFAULT function never gets called again.
+SDL_InitDynamicAPI() fills in jump_table with all the actual SDL function
+pointers, which means that this _DEFAULT function never gets called again.
First call to any SDL function sets the whole thing up.

So you might be asking, what was the value in that? Isn’t this what the operating
-system’s dynamic loader was supposed to do for us? Yes, but now we’ve got this
+system’s dynamic loader was supposed to do for us? Yes, but now we’ve got this
level of indirection, we can do things like this:

@@ -69,34 +69,34 @@ export SDL_DYNAMIC_API=/my/actual/libSDL-2.0.so.0
./MyGameThatIsStaticallyLinkedToSDL2

-And now, this game that is statically linked to SDL, can still be overridden
-with a newer, or better, SDL. The statically linked one will only be used as
+And now, this game that is statically linked to SDL, can still be overridden
+with a newer, or better, SDL. The statically linked one will only be used as
far as calling into the jump table in this case. But in cases where no override
-is desired, the statically linked version will provide its own jump table,
+is desired, the statically linked version will provide its own jump table,
and everyone is happy.

So now:
– Developers can statically link SDL, and users can still replace it.
± Developers can statically link SDL, and users can still replace it.
(We’d still rather you ship a shared library, though!)
– Developers can ship an SDL with their game, Valve can override it for, say,

  • new features on SteamOS, or distros can override it for their own needs,
    ± Developers can ship an SDL with their game, Valve can override it for, say,
  • new features on SteamOS, or distros can override it for their own needs,
    but it’ll also just work in the default case.
    – Developers can ship the same package to everyone (Humble Bundle, GOG, etc),
    ± Developers can ship the same package to everyone (Humble Bundle, GOG, etc),
    and it’ll do the right thing.
    – End users (and Valve) can update a game’s SDL in almost any case,
    ± End users (and Valve) can update a game’s SDL in almost any case,
    to keep abandoned games running on newer platforms.
    – Everyone develops with SDL exactly as they have been doing all along.
    ± Everyone develops with SDL exactly as they have been doing all along.
    Same headers, same ABI. Just get the latest version to enable this magic.

A little more about SDL_InitDynamicAPI():

-Internally, InitAPI does some locking to make sure everything waits until a
-single thread initializes everything (although even SDL_CreateThread() goes
+Internally, InitAPI does some locking to make sure everything waits until a
+single thread initializes everything (although even SDL_CreateThread() goes
through here before spinning a thread, too), and then decides if it should use
-an external SDL library. If not, it sets up the jump table using the current
+an external SDL library. If not, it sets up the jump table using the current
SDL’s function pointers (which might be statically linked into a program, or in
-a shared library of its own). If so, it loads that library and looks for and
+a shared library of its own). If so, it loads that library and looks for and
calls a single function:

@@ -104,35 +104,35 @@ SInt32 SDL_DYNAPI_entry(Uint32 version, void *table, Uint32 tablesize);

That function takes a version number (more on that in a moment), the address of
-the jump table, and the size, in bytes, of the table.
-Now, we’ve got policy here: this table’s layout never changes; new stuff gets
-added to the end. Therefore SDL_DYNAPI_entry() knows that it can provide all
+the jump table, and the size, in bytes, of the table.
+Now, we’ve got policy here: this table’s layout never changes; new stuff gets
+added to the end. Therefore SDL_DYNAPI_entry() knows that it can provide all
the needed functions if tablesize <= sizeof its own jump table. If tablesize is
bigger (say, SDL 2.0.4 is trying to load SDL 2.0.3), then we know to abort, but
if it’s smaller, we know we can provide the entire API that the caller needs.

-The version variable is a failsafe switch.
-Right now it’s always 1. This number changes when there are major API changes
-(so we know if the tablesize might be smaller, or entries in it have changed).
-Right now SDL_DYNAPI_entry gives up if the version doesn’t match, but it’s not
-inconceivable to have a small dispatch library that only supplies this one
+The version variable is a failsafe switch.
+Right now it’s always 1. This number changes when there are major API changes
+(so we know if the tablesize might be smaller, or entries in it have changed).
+Right now SDL_DYNAPI_entry gives up if the version doesn’t match, but it’s not
+inconceivable to have a small dispatch library that only supplies this one
function and loads different, otherwise-incompatible SDL libraries and has the
-right one initialize the jump table based on the version. For something that
-must generically catch lots of different versions of SDL over time, like the
+right one initialize the jump table based on the version. For something that
+must generically catch lots of different versions of SDL over time, like the
Steam Client, this isn’t a bad option.

Finally, I’m sure some people are reading this and thinking,
-“I don’t want that overhead in my project!”
+“I don’t want that overhead in my project!”

-To which I would point out that the extra function call through the jump table
-probably wouldn’t even show up in a profile, but lucky you: this can all be
-disabled. You can build SDL without this if you absolutely must, but we would
-encourage you not to do that. However, on heavily locked down platforms like
+To which I would point out that the extra function call through the jump table
+probably wouldn’t even show up in a profile, but lucky you: this can all be
+disabled. You can build SDL without this if you absolutely must, but we would
+encourage you not to do that. However, on heavily locked down platforms like
iOS, or maybe when debugging, it makes sense to disable it. The way this is
-designed in SDL, you just have to change one #define, and the entire system
-vaporizes out, and SDL functions exactly like it always did. Most of it is
-macro magic, so the system is contained to one C file and a few headers.
-However, this is on by default and you have to edit a header file to turn it
-off. Our hopes is that if we make it easy to disable, but not too easy,
-everyone will ultimately be able to get what they want, but we’ve gently
+designed in SDL, you just have to change one #define, and the entire system
+vaporizes out, and SDL functions exactly like it always did. Most of it is
+macro magic, so the system is contained to one C file and a few headers.
+However, this is on by default and you have to edit a header file to turn it
+off. Our hopes is that if we make it easy to disable, but not too easy,
+everyone will ultimately be able to get what they want, but we’ve gently
nudged everyone towards what we think is the best solution.
diff --git a/docs/README-gdk.md b/docs/README-gdk.md
index 5f6b18be3f40…b8ba2b4337a5 100644
— a/docs/README-gdk.md
+++ b/docs/README-gdk.md
@@ -1,155 +1,155 @@
-GDK
-=====

-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.

-Requirements

-* Microsoft Visual Studio 2022 (in theory, it should also work in 2017 or 2019, but this has not been tested)
-* Microsoft GDK June 2022 or newer (public release here)
-* To publish a package or successfully authenticate a user, you will need to create an app id/configure services in Partner Center. However, for local testing purposes (without authenticating on Xbox Live), the identifiers used by the GDK test programs in the included solution will work.

-Windows GDK Status

-The Windows GDK port supports the full set of Win32 APIs, renderers, controllers, input devices, etc., as the normal Windows x64 build of SDL.

-* Additionally, the GDK port adds the following:

    • Compile-time platform detection for SDL programs. The __GDK__ is #defined on every GDK platform, and the __WINGDK__ is #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.)
    • GDK-specific setup:
    • Initializing/uninitializing the game runtime, and initializing Xbox Live services
    • Creating a global task queue and setting it as the default for the process. When running any async operations, passing in NULL as the task queue will make the task get added to the global task queue.
    • An implementation on WinMain that performs the above GDK setup (you should link against SDL2main.lib, as in Windows x64). If you are unable to do this, you can instead manually call SDL_GDKRunApp from your entry point, passing in your SDL_main function and NULL as the parameters.
    • Global task queue callbacks are dispatched during SDL_PumpEvents (which is also called internally if using SDL_PollEvent).
    • You can get the handle of the global task queue through SDL_GDKGetTaskQueue, if needed. When done with the queue, be sure to use XTaskQueueCloseHandle to decrement the reference count (otherwise it will cause a resource leak).

-* What doesn’t work:

    • Compilation with anything other than through the included Visual C++ solution file

-## VisualC-GDK Solution

-The included VisualC-GDK/SDL.sln solution includes the following targets for the Gaming.Desktop.x64 configuration:

-* SDL2 (DLL) - This is the typical SDL2.dll, but for Gaming.Desktop.x64.
-* SDL2main (lib) - This contains a drop-in implementation of WinMain that is used as the entry point for GDK programs.
-* tests/testgamecontroller - Standard SDL test program demonstrating controller functionality.
-* tests/testgdk - GDK-specific test program that demonstrates using the global task queue to login a user into Xbox Live.

  • NOTE: As of the June 2022 GDK, you cannot test user logins without a valid Title ID and MSAAppId. You will need to manually change the identifiers in the MicrosoftGame.config to your valid IDs from Partner Center if you wish to test this.
    -* tests/testsprite2 - Standard SDL test program demonstrating sprite drawing functionality.

-If you set one of the test programs as a startup project, you can run it directly from Visual Studio.

-Windows GDK Setup, Detailed Steps

-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.

-### 1. Add a Gaming.Desktop.x64 Configuration ###

-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.

-### 2. Build SDL2 and SDL2main for GDK ###

-Open VisualC-GDK/SDL.sln in Visual Studio, you need to build the SDL2 and SDL2main targets for the Gaming.Desktop.x64 platform (Release is recommended). You will need to copy/keep track of the SDL2.dll, XCurl.dll (which is output by Gaming.Desktop.x64), SDL2.lib, and SDL2main.lib output files for your game project.

-Alternatively, you could setup your solution file to instead reference the SDL2/SDL2main project file targets from the SDL source, and add those projects as a dependency. This would mean that SDL2 and SDL2main would both be built when your game is built.

-### 3. Configuring Project Settings ###

-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:

-* Under C/C++ > General > Additional Include Directories, make sure the SDL/include path is referenced
-* Under Linker > General > Additional Library Directories, make sure to reference the path where the newly-built SDL2.lib and SDL2main.lib are
-* Under Linker > Input > Additional Dependencies, you need the following:

    • SDL2.lib
    • SDL2main.lib (unless not using)
    • xgameruntime.lib
    • ../Microsoft.Xbox.Services.141.GDK.C.Thunks.lib
      -* Note that in general, the GDK libraries depend on the MSVC C/C++ runtime, so there is no way to remove this dependency from a GDK program that links against GDK.

-### 4. Setting up SDL_main ###

-Rather than using your own implementation of WinMain, it’s recommended that you instead #include "SDL_main.h" and declare a standard main function. If you are unable to do this, you can instead manually call SDL_GDKRunApp from your entry point, passing in your SDL_main function and NULL as the parameters.

-### 5. Required DLLs ###

-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:

-* Your SDL2.dll
-* “$(Console_GRDKExtLibRoot)Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release\Microsoft.Xbox.Services.141.GDK.C.Thunks.dll”
-* XCurl.dll

-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.

-### 6. Setting up MicrosoftGame.config ###

-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:

-* Identity tag - Name and Publisher attributes
-* TitleId
-* MSAAppId

-### 7. Adding Required Logos

-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.

-### 8. Copying any Data Files ###

-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.

-### 9. Build and Run from Visual Studio ###

-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:

-1. Run “Desktop VS 2022 Gaming Command Prompt” from the Start Menu
-2. Switch the sandbox name with:

  • XblPCSandbox SANDBOX.#
    -3. (To switch back to the retail sandbox):
  • XblPCSandbox RETAIL

-### 10. Packaging and Installing Locally

-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:

-1. Run “Desktop VS 2022 Gaming Command Prompt” from the Start Menu
-2. cd to the directory containing the PackageLayout.xml with the correct paths (if you use the local path as in the sample package layout, this would be from your .exe output directory)
-3. mkdir Package to create an output directory
-4. To package the file into the Package directory, use:

  • makepkg pack /f PackageLayout.xml /lt /d . /nogameos /pc /pd Package
    -5. To install the package, use:
  • wdapp install PACKAGENAME.msixvc
    -6. Once the package is installed, you can run it from the start menu.
    -7. As with when running from Visual Studio, if you need to test any Xbox Live functionality you must switch to the correct sandbox.

-Troubleshooting

-#### Xbox Live Login does not work

-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.

-#### “The current user has already installed an unpackaged version of this app. A packaged version cannot replace this.” error when installing

-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).
+GDK
+=====
+
+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.
+
+
+Requirements
±-----------
+
+* Microsoft Visual Studio 2022 (in theory, it should also work in 2017 or 2019, but this has not been tested)
+* Microsoft GDK June 2022 or newer (public release here)
+* To publish a package or successfully authenticate a user, you will need to create an app id/configure services in Partner Center. However, for local testing purposes (without authenticating on Xbox Live), the identifiers used by the GDK test programs in the included solution will work.
+

(Patch may be truncated, please check the link at the top of this post.)