diff options
Diffstat (limited to '3rdparty/SDL2/docs/README-winrt.md')
-rw-r--r-- | 3rdparty/SDL2/docs/README-winrt.md | 68 |
1 files changed, 39 insertions, 29 deletions
diff --git a/3rdparty/SDL2/docs/README-winrt.md b/3rdparty/SDL2/docs/README-winrt.md index 741def67f3d..cccbbeaa853 100644 --- a/3rdparty/SDL2/docs/README-winrt.md +++ b/3rdparty/SDL2/docs/README-winrt.md @@ -2,11 +2,8 @@ WinRT ===== This port allows SDL applications to run on Microsoft's platforms that require -use of "Windows Runtime", aka. "WinRT", APIs. WinRT apps are currently -full-screen only, and run in what Microsoft sometimes refers to as their -"Modern" (formerly, "Metro"), environment. For Windows 8.x, Microsoft may also -refer to them as "Windows Store" apps, due to them being distributed, -primarily, via a Microsoft-run online store (of the same name). +use of "Windows Runtime", aka. "WinRT", APIs. Microsoft may, in some cases, +refer to them as either "Windows Store", or for Windows 10, "UWP" apps. Some of the operating systems that include WinRT, are: @@ -82,7 +79,9 @@ Here is a rough list of what works, and what doens't: * What partially works: * keyboard input. Most of WinRT's documented virtual keys are supported, as - well as many keys with documented hardware scancodes. + well as many keys with documented hardware scancodes. Converting + SDL_Scancodes to or from SDL_Keycodes may not work, due to missing APIs + (MapVirualKey()) in Microsoft's Windows Store / UWP APIs. * SDLmain. WinRT uses a different signature for each app's main() function. SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp (in `SDL\src\main\winrt\`) directly in order for their C-style main() @@ -160,7 +159,9 @@ following, at a high-level: the linker, and will copy SDL's .dll files to your app's final output. 4. adjust your app's build settings, at minimum, telling it where to find SDL's header files. -5. add a file that contains a WinRT-appropriate main function. +5. add files that contains a WinRT-appropriate main function, along with some + data to make sure mouse-cursor-hiding (via SDL_ShowCursor(SDL_DISABLE) calls) + work properly. 6. add SDL-specific app code. 7. build and run your app. @@ -268,33 +269,27 @@ To change these settings: 10. close the dialog, saving settings, by clicking the "OK" button -### 5. Add a WinRT-appropriate main function to the app. ### +### 5. Add a WinRT-appropriate main function, and a blank-cursor image, to the app. ### -C/C++-based WinRT apps do contain a `main` function that the OS will invoke when -the app starts launching. The parameters of WinRT main functions are different -than those found on other platforms, Win32 included. SDL/WinRT provides a -platform-appropriate main function that will perform these actions, setup key -portions of the app, then invoke a classic, C/C++-style main function (that take -in "argc" and "argv" parameters). The code for this file is contained inside -SDL's source distribution, under `src/main/winrt/SDL_winrt_main_NonXAML.cpp`. -You'll need to add this file, or a copy of it, to your app's project, and make -sure it gets compiled using a Microsoft-specific set of C++ extensions called -C++/CX. +A few files should be included directly in your app's MSVC project, specifically: +1. a WinRT-appropriate main function (which is different than main() functions on + other platforms) +2. a Win32-style cursor resource, used by SDL_ShowCursor() to hide the mouse cursor + (if and when the app needs to do so). *If this cursor resource is not + included, mouse-position reporting may fail if and when the cursor is + hidden, due to possible bugs/design-oddities in Windows itself.* -**NOTE: C++/CX compilation is currently required in at least one file of your -app's project. This is to make sure that Visual C++'s linker builds a 'Windows -Metadata' file (.winmd) for your app. Not doing so can lead to build errors.** - -To include `SDL_winrt_main_NonXAML.cpp`: +To include these files: 1. right-click on your project (again, in Visual C++'s Solution Explorer), navigate to "Add", then choose "Existing Item...". -2. open `SDL_winrt_main_NonXAML.cpp`, which is found inside SDL's source - distribution, under `src/main/winrt/`. Make sure that the open-file dialog - closes, either by double-clicking on the file, or single-clicking on it and - then clicking Add. -3. right-click on the file (as listed in your project), then click on - "Properties...". +2. navigate to the directory containing SDL's source code, then into its + subdirectory, 'src/main/winrt/'. Select, then add, the following files: + - `SDL_winrt_main_NonXAML.cpp` + - `SDL2-WinRTResources.rc` + - `SDL2-WinRTResource_BlankCursor.cur` +3. right-click on the file `SDL_winrt_main_NonXAML.cpp` (as listed in your + project), then click on "Properties...". 4. in the drop-down box next to "Configuration", choose, "All Configurations" 5. in the drop-down box next to "Platform", choose, "All Platforms" 6. in the left-hand list, click on "C/C++" @@ -302,6 +297,11 @@ To include `SDL_winrt_main_NonXAML.cpp`: 8. click the OK button. This will close the dialog. +**NOTE: C++/CX compilation is currently required in at least one file of your +app's project. This is to make sure that Visual C++'s linker builds a 'Windows +Metadata' file (.winmd) for your app. Not doing so can lead to build errors.** + + ### 6. Add app code and assets ### At this point, you can add in SDL-specific source code. Be sure to include a @@ -466,3 +466,13 @@ section. /nodefaultlib:vccorlibd /nodefaultlib:msvcrtd vccorlibd.lib msvcrtd.lib + +#### Mouse-motion events fail to get sent, or SDL_GetMouseState() fails to return updated values + +This may be caused by a bug in Windows itself, whereby hiding the mouse +cursor can cause mouse-position reporting to fail. + +SDL provides a workaround for this, but it requires that an app links to a +set of Win32-style cursor image-resource files. A copy of suitable resource +files can be found in `src/main/winrt/`. Adding them to an app's Visual C++ +project file should be sufficient to get the app to use them. |