docs/README-winrt.md
changeset 10486 5bf595c48fd4
parent 10171 5b61e12c0a30
child 10828 2160677a2f0f
     1.1 --- a/docs/README-winrt.md	Fri Oct 07 17:30:21 2016 -0700
     1.2 +++ b/docs/README-winrt.md	Fri Oct 07 17:46:58 2016 -0700
     1.3 @@ -1,478 +1,478 @@
     1.4 -WinRT
     1.5 -=====
     1.6 -
     1.7 -This port allows SDL applications to run on Microsoft's platforms that require
     1.8 -use of "Windows Runtime", aka. "WinRT", APIs.  Microsoft may, in some cases,
     1.9 -refer to them as either "Windows Store", or for Windows 10, "UWP" apps.
    1.10 -
    1.11 -Some of the operating systems that include WinRT, are:
    1.12 -
    1.13 -* Windows 10, via its Universal Windows Platform (UWP) APIs
    1.14 -* Windows 8.x
    1.15 -* Windows RT 8.x (aka. Windows 8.x for ARM processors)
    1.16 -* Windows Phone 8.x
    1.17 -
    1.18 -
    1.19 -Requirements
    1.20 -------------
    1.21 -
    1.22 -* Microsoft Visual C++ (aka Visual Studio), either 2015, 2013, or 2012
    1.23 -  - Free, "Community" or "Express" editions may be used, so long as they
    1.24 -    include  support for either "Windows Store" or "Windows Phone" apps.
    1.25 -    "Express" versions marked as supporting "Windows Desktop" development
    1.26 -    typically do not include support for creating WinRT apps, to note.
    1.27 -    (The "Community" editions of Visual C++ do, however, support both
    1.28 -    desktop/Win32 and WinRT development).
    1.29 -  - Visual C++ 2012 can only build apps that target versions 8.0 of Windows,
    1.30 -    or  Windows Phone.  8.0-targetted apps will run on devices running 8.1
    1.31 -    editions of Windows, however they will not be able to take advantage of
    1.32 -    8.1-specific features.
    1.33 -  - Visual C++ 2013 cannot create app projects that target Windows 8.0.
    1.34 -    Visual C++ 2013 Update 4, can create app projects for Windows Phone 8.0,
    1.35 -    Windows Phone 8.1, and Windows 8.1, but not Windows 8.0.  An optional
    1.36 -    Visual Studio add-in, "Tools for Maintaining Store apps for Windows 8",
    1.37 -    allows Visual C++ 2013 to load and build Windows 8.0 projects that were
    1.38 -    created with Visual C++ 2012, so long as Visual C++ 2012 is installed
    1.39 -    on the same machine.  More details on targeting different versions of
    1.40 -    Windows can found at the following web pages:
    1.41 -      - [Develop apps by using Visual Studio 2013](http://msdn.microsoft.com/en-us/library/windows/apps/br211384.aspx)
    1.42 -      - [To add the Tools for Maintaining Store apps for Windows 8](http://msdn.microsoft.com/en-us/library/windows/apps/dn263114.aspx#AddMaintenanceTools)
    1.43 -* A valid Microsoft account - This requirement is not imposed by SDL, but
    1.44 -  rather by Microsoft's Visual C++ toolchain.  This is required to launch or 
    1.45 -  debug apps.
    1.46 -
    1.47 -
    1.48 -Status
    1.49 -------
    1.50 -
    1.51 -Here is a rough list of what works, and what doens't:
    1.52 -
    1.53 -* What works:
    1.54 -  * compilation via Visual C++ 2012 through 2015
    1.55 -  * compile-time platform detection for SDL programs.  The C/C++ #define,
    1.56 -    `__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
    1.57 -  * GPU-accelerated 2D rendering, via SDL_Renderer.
    1.58 -  * OpenGL ES 2, via the ANGLE library (included separately from SDL)
    1.59 -  * software rendering, via either SDL_Surface (optionally in conjunction with
    1.60 -    SDL_GetWindowSurface() and SDL_UpdateWindowSurface()) or via the
    1.61 -    SDL_Renderer APIs
    1.62 -  * threads
    1.63 -  * timers (via SDL_GetTicks(), SDL_AddTimer(), SDL_GetPerformanceCounter(),
    1.64 -    SDL_GetPerformanceFrequency(), etc.)
    1.65 -  * file I/O via SDL_RWops
    1.66 -  * mouse input  (unsupported on Windows Phone)
    1.67 -  * audio, via a modified version of SDL's XAudio2 backend
    1.68 -  * .DLL file loading.  Libraries *MUST* be packaged inside applications.  Loading
    1.69 -    anything outside of the app is not supported.
    1.70 -  * system path retrieval via SDL's filesystem APIs
    1.71 -  * game controllers.  Support is provided via the SDL_Joystick and
    1.72 -    SDL_GameController APIs, and is backed by Microsoft's XInput API.
    1.73 -  * multi-touch input
    1.74 -  * app events.  SDL_APP_WILLENTER* and SDL_APP_DIDENTER* events get sent out as
    1.75 -    appropriate.
    1.76 -  * window events
    1.77 -  * using Direct3D 11.x APIs outside of SDL.  Non-XAML / Direct3D-only apps can
    1.78 -    choose to render content directly via Direct3D, using SDL to manage the
    1.79 -    internal WinRT window, as well as input and audio.  (Use
    1.80 -    SDL_GetWindowWMInfo() to get the WinRT 'CoreWindow', and pass it into
    1.81 -    IDXGIFactory2::CreateSwapChainForCoreWindow() as appropriate.)
    1.82 -
    1.83 -* What partially works:
    1.84 -  * keyboard input.  Most of WinRT's documented virtual keys are supported, as
    1.85 -    well as many keys with documented hardware scancodes.  Converting
    1.86 -    SDL_Scancodes to or from SDL_Keycodes may not work, due to missing APIs
    1.87 -    (MapVirualKey()) in Microsoft's Windows Store / UWP APIs.
    1.88 -  * SDLmain.  WinRT uses a different signature for each app's main() function.
    1.89 -    SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
    1.90 -    (in `SDL\src\main\winrt\`) directly in order for their C-style main()
    1.91 -    functions to be called.
    1.92 -
    1.93 -* What doesn't work:
    1.94 -  * compilation with anything other than Visual C++
    1.95 -  * programmatically-created custom cursors.  These don't appear to be supported
    1.96 -    by WinRT.  Different OS-provided cursors can, however, be created via
    1.97 -    SDL_CreateSystemCursor() (unsupported on Windows Phone)
    1.98 -  * SDL_WarpMouseInWindow() or SDL_WarpMouseGlobal().  This are not currently
    1.99 -    supported by WinRT itself.
   1.100 -  * joysticks and game controllers that aren't supported by Microsoft's XInput
   1.101 -    API.
   1.102 -  * turning off VSync when rendering on Windows Phone.  Attempts to turn VSync
   1.103 -    off on Windows Phone result either in Direct3D not drawing anything, or it
   1.104 -    forcing VSync back on.  As such, SDL_RENDERER_PRESENTVSYNC will always get
   1.105 -    turned-on on Windows Phone.  This limitation is not present in non-Phone
   1.106 -    WinRT (such as Windows 8.x), where turning off VSync appears to work.
   1.107 -  * probably anything else that's not listed as supported
   1.108 -
   1.109 -
   1.110 -
   1.111 -Upgrade Notes
   1.112 --------------
   1.113 -
   1.114 -#### SDL_GetPrefPath() usage when upgrading WinRT apps from SDL 2.0.3
   1.115 -
   1.116 -SDL 2.0.4 fixes two bugs found in the WinRT version of SDL_GetPrefPath().
   1.117 -The fixes may affect older, SDL 2.0.3-based apps' save data.  Please note
   1.118 -that these changes only apply to SDL-based WinRT apps, and not to apps for
   1.119 -any other platform.
   1.120 -
   1.121 -1. SDL_GetPrefPath() would return an invalid path, one in which the path's
   1.122 -   directory had not been created.  Attempts to create files there
   1.123 -   (via fopen(), for example), would fail, unless that directory was
   1.124 -   explicitly created beforehand.
   1.125 -
   1.126 -2. SDL_GetPrefPath(), for non-WinPhone-based apps, would return a path inside
   1.127 -   a WinRT 'Roaming' folder, the contents of which get automatically
   1.128 -   synchronized across multiple devices.  This process can occur while an
   1.129 -   application runs, and can cause existing save-data to be overwritten
   1.130 -   at unexpected times, with data from other devices.  (Windows Phone apps
   1.131 -   written with SDL 2.0.3 did not utilize a Roaming folder, due to API
   1.132 -   restrictions in Windows Phone 8.0).
   1.133 -
   1.134 -
   1.135 -SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
   1.136 -
   1.137 -1. making sure that SDL_GetPrefPath() returns a directory in which data
   1.138 -   can be written to immediately, without first needing to create directories.
   1.139 -
   1.140 -2. basing SDL_GetPrefPath() off of a different, non-Roaming folder, the
   1.141 -   contents of which do not automatically get synchronized across devices
   1.142 -   (and which require less work to use safely, in terms of data integrity).
   1.143 -
   1.144 -Apps that wish to get their Roaming folder's path can do so either by using
   1.145 -SDL_WinRTGetFSPathUTF8(), SDL_WinRTGetFSPathUNICODE() (which returns a
   1.146 -UCS-2/wide-char string), or directly through the WinRT class,
   1.147 -Windows.Storage.ApplicationData.
   1.148 -
   1.149 -
   1.150 -
   1.151 -Setup, High-Level Steps
   1.152 ------------------------
   1.153 -
   1.154 -The steps for setting up a project for an SDL/WinRT app looks like the
   1.155 -following, at a high-level:
   1.156 -
   1.157 -1. create a new Visual C++ project using Microsoft's template for a,
   1.158 -   "Direct3D App".
   1.159 -2. remove most of the files from the project.
   1.160 -3. make your app's project directly reference SDL/WinRT's own Visual C++
   1.161 -   project file, via use of Visual C++'s "References" dialog.  This will setup
   1.162 -   the linker, and will copy SDL's .dll files to your app's final output.
   1.163 -4. adjust your app's build settings, at minimum, telling it where to find SDL's
   1.164 -   header files.
   1.165 -5. add files that contains a WinRT-appropriate main function, along with some
   1.166 -   data to make sure mouse-cursor-hiding (via SDL_ShowCursor(SDL_DISABLE) calls)
   1.167 -   work properly.
   1.168 -6. add SDL-specific app code.
   1.169 -7. build and run your app.
   1.170 -
   1.171 -
   1.172 -Setup, Detailed Steps
   1.173 ----------------------
   1.174 -
   1.175 -### 1. Create a new project ###
   1.176 -
   1.177 -Create a new project using one of Visual C++'s templates for a plain, non-XAML,
   1.178 -"Direct3D App" (XAML support for SDL/WinRT is not yet ready for use).  If you
   1.179 -don't see one of these templates, in Visual C++'s 'New Project' dialog, try
   1.180 -using the textbox titled, 'Search Installed Templates' to look for one.
   1.181 -
   1.182 -
   1.183 -### 2. Remove unneeded files from the project ###
   1.184 -
   1.185 -In the new project, delete any file that has one of the following extensions:
   1.186 -
   1.187 -- .cpp
   1.188 -- .h
   1.189 -- .hlsl
   1.190 -
   1.191 -When you are done, you should be left with a few files, each of which will be a
   1.192 -necessary part of your app's project.  These files will consist of:
   1.193 -
   1.194 -- an .appxmanifest file, which contains metadata on your WinRT app.  This is
   1.195 -  similar to an Info.plist file on iOS, or an AndroidManifest.xml on Android.
   1.196 -- a few .png files, one of which is a splash screen (displayed when your app
   1.197 -  launches), others are app icons.
   1.198 -- a .pfx file, used for code signing purposes.
   1.199 -
   1.200 -
   1.201 -### 3. Add references to SDL's project files ###
   1.202 -
   1.203 -SDL/WinRT can be built in multiple variations, spanning across three different
   1.204 -CPU architectures (x86, x64, and ARM) and two different configurations
   1.205 -(Debug and Release).  WinRT and Visual C++ do not currently provide a means
   1.206 -for combining multiple variations of one library into a single file.
   1.207 -Furthermore, it does not provide an easy means for copying pre-built .dll files
   1.208 -into your app's final output (via Post-Build steps, for example).  It does,
   1.209 -however, provide a system whereby an app can reference the MSVC projects of
   1.210 -libraries such that, when the app is built:
   1.211 -
   1.212 -1. each library gets built for the appropriate CPU architecture(s) and WinRT
   1.213 -   platform(s).
   1.214 -2. each library's output, such as .dll files, get copied to the app's build 
   1.215 -   output.
   1.216 -
   1.217 -To set this up for SDL/WinRT, you'll need to run through the following steps:
   1.218 -
   1.219 -1. open up the Solution Explorer inside Visual C++ (under the "View" menu, then
   1.220 -   "Solution Explorer")
   1.221 -2. right click on your app's solution.
   1.222 -3. navigate to "Add", then to "Existing Project..."
   1.223 -4. find SDL/WinRT's Visual C++ project file and open it.  Different project
   1.224 -   files exist for different WinRT platforms.  All of them are in SDL's
   1.225 -   source distribution, in the following directories:
   1.226 -    * `VisualC-WinRT/UWP_VS2015/`        - for Windows 10 / UWP apps
   1.227 -    * `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
   1.228 -    * `VisualC-WinRT/WinRT80_VS2012/`    - for Windows 8.0 apps
   1.229 -    * `VisualC-WinRT/WinRT81_VS2013/`    - for Windows 8.1 apps
   1.230 -5. once the project has been added, right-click on your app's project and
   1.231 -   select, "References..."
   1.232 -6. click on the button titled, "Add New Reference..."
   1.233 -7. check the box next to SDL
   1.234 -8. click OK to close the dialog
   1.235 -9. SDL will now show up in the list of references.  Click OK to close that
   1.236 -   dialog.
   1.237 -
   1.238 -Your project is now linked to SDL's project, insofar that when the app is
   1.239 -built, SDL will be built as well, with its build output getting included with
   1.240 -your app.
   1.241 -
   1.242 -
   1.243 -### 4. Adjust Your App's Build Settings ###
   1.244 -
   1.245 -Some build settings need to be changed in your app's project.  This guide will
   1.246 -outline the following:
   1.247 -
   1.248 -- making sure that the compiler knows where to find SDL's header files
   1.249 -- **Optional for C++, but NECESSARY for compiling C code:** telling the
   1.250 -  compiler not to use Microsoft's C++ extensions for WinRT development.
   1.251 -- **Optional:** telling the compiler not generate errors due to missing
   1.252 -  precompiled header files.
   1.253 -
   1.254 -To change these settings:
   1.255 -
   1.256 -1. right-click on the project
   1.257 -2. choose "Properties"
   1.258 -3. in the drop-down box next to "Configuration", choose, "All Configurations"
   1.259 -4. in the drop-down box next to "Platform", choose, "All Platforms"
   1.260 -5. in the left-hand list, expand the "C/C++" section
   1.261 -6. select "General"
   1.262 -7. edit the "Additional Include Directories" setting, and add a path to SDL's
   1.263 -   "include" directory
   1.264 -8. **Optional: to enable compilation of C code:** change the setting for
   1.265 -   "Consume Windows Runtime Extension" from "Yes (/ZW)" to "No".  If you're 
   1.266 -   working with a completely C++ based project, this step can usually be 
   1.267 -   omitted.
   1.268 -9. **Optional: to disable precompiled headers (which can produce 
   1.269 -   'stdafx.h'-related build errors, if setup incorrectly:** in the left-hand 
   1.270 -   list, select "Precompiled Headers", then change the setting for "Precompiled 
   1.271 -   Header" from "Use (/Yu)" to "Not Using Precompiled Headers".
   1.272 -10. close the dialog, saving settings, by clicking the "OK" button
   1.273 -
   1.274 -
   1.275 -### 5. Add a WinRT-appropriate main function, and a blank-cursor image, to the app. ###
   1.276 -
   1.277 -A few files should be included directly in your app's MSVC project, specifically:
   1.278 -1. a WinRT-appropriate main function (which is different than main() functions on
   1.279 -   other platforms)
   1.280 -2. a Win32-style cursor resource, used by SDL_ShowCursor() to hide the mouse cursor
   1.281 -   (if and when the app needs to do so).  *If this cursor resource is not
   1.282 -   included, mouse-position reporting may fail if and when the cursor is
   1.283 -   hidden, due to possible bugs/design-oddities in Windows itself.*
   1.284 -
   1.285 -To include these files:
   1.286 -
   1.287 -1. right-click on your project (again, in Visual C++'s Solution Explorer), 
   1.288 -   navigate to "Add", then choose "Existing Item...".
   1.289 -2. navigate to the directory containing SDL's source code, then into its
   1.290 -   subdirectory, 'src/main/winrt/'.  Select, then add, the following files:
   1.291 -   - `SDL_winrt_main_NonXAML.cpp`
   1.292 -   - `SDL2-WinRTResources.rc`
   1.293 -   - `SDL2-WinRTResource_BlankCursor.cur`
   1.294 -3. right-click on the file `SDL_winrt_main_NonXAML.cpp` (as listed in your
   1.295 -   project), then click on "Properties...".
   1.296 -4. in the drop-down box next to "Configuration", choose, "All Configurations"
   1.297 -5. in the drop-down box next to "Platform", choose, "All Platforms"
   1.298 -6. in the left-hand list, click on "C/C++"
   1.299 -7. change the setting for "Consume Windows Runtime Extension" to "Yes (/ZW)".
   1.300 -8. click the OK button.  This will close the dialog.
   1.301 -
   1.302 -
   1.303 -**NOTE: C++/CX compilation is currently required in at least one file of your 
   1.304 -app's project.  This is to make sure that Visual C++'s linker builds a 'Windows 
   1.305 -Metadata' file (.winmd) for your app.  Not doing so can lead to build errors.**
   1.306 -
   1.307 -
   1.308 -### 6. Add app code and assets ###
   1.309 -
   1.310 -At this point, you can add in SDL-specific source code.  Be sure to include a 
   1.311 -C-style main function (ie: `int main(int argc, char *argv[])`).  From there you 
   1.312 -should be able to create a single `SDL_Window` (WinRT apps can only have one 
   1.313 -window, at present), as well as an `SDL_Renderer`.  Direct3D will be used to 
   1.314 -draw content.  Events are received via SDL's usual event functions 
   1.315 -(`SDL_PollEvent`, etc.)  If you have a set of existing source files and assets, 
   1.316 -you can start adding them to the project now.  If not, or if you would like to 
   1.317 -make sure that you're setup correctly, some short and simple sample code is 
   1.318 -provided below.
   1.319 -
   1.320 -
   1.321 -#### 6.A. ... when creating a new app ####
   1.322 -
   1.323 -If you are creating a new app (rather than porting an existing SDL-based app), 
   1.324 -or if you would just like a simple app to test SDL/WinRT with before trying to 
   1.325 -get existing code working, some working SDL/WinRT code is provided below.  To 
   1.326 -set this up:
   1.327 -
   1.328 -1. right click on your app's project
   1.329 -2. select Add, then New Item.  An "Add New Item" dialog will show up.
   1.330 -3. from the left-hand list, choose "Visual C++"
   1.331 -4. from the middle/main list, choose "C++ File (.cpp)"
   1.332 -5. near the bottom of the dialog, next to "Name:", type in a name for your 
   1.333 -source file, such as, "main.cpp".
   1.334 -6. click on the Add button.  This will close the dialog, add the new file to 
   1.335 -your project, and open the file in Visual C++'s text editor.
   1.336 -7. Copy and paste the following code into the new file, then save it.
   1.337 -
   1.338 -
   1.339 -    #include <SDL.h>
   1.340 -    
   1.341 -    int main(int argc, char **argv)
   1.342 -    {
   1.343 -        SDL_DisplayMode mode;
   1.344 -        SDL_Window * window = NULL;
   1.345 -        SDL_Renderer * renderer = NULL;
   1.346 -        SDL_Event evt;
   1.347 -    
   1.348 -        if (SDL_Init(SDL_INIT_VIDEO) != 0) {
   1.349 -            return 1;
   1.350 -        }
   1.351 -    
   1.352 -        if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
   1.353 -            return 1;
   1.354 -        }
   1.355 -    
   1.356 -        if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
   1.357 -            return 1;
   1.358 -        }
   1.359 -    
   1.360 -        while (1) {
   1.361 -            while (SDL_PollEvent(&evt)) {
   1.362 -            }
   1.363 -    
   1.364 -            SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
   1.365 -            SDL_RenderClear(renderer);
   1.366 -            SDL_RenderPresent(renderer);
   1.367 -        }
   1.368 -    }
   1.369 -
   1.370 -
   1.371 -#### 6.B. Adding code and assets ####
   1.372 -
   1.373 -If you have existing code and assets that you'd like to add, you should be able 
   1.374 -to add them now.  The process for adding a set of files is as such.
   1.375 -
   1.376 -1. right click on the app's project
   1.377 -2. select Add, then click on "New Item..."
   1.378 -3. open any source, header, or asset files as appropriate.  Support for C and 
   1.379 -C++ is available.
   1.380 -
   1.381 -Do note that WinRT only supports a subset of the APIs that are available to 
   1.382 -Win32-based apps.  Many portions of the Win32 API and the C runtime are not 
   1.383 -available.
   1.384 -
   1.385 -A list of unsupported C APIs can be found at 
   1.386 -<http://msdn.microsoft.com/en-us/library/windows/apps/jj606124.aspx>
   1.387 -
   1.388 -General information on using the C runtime in WinRT can be found at 
   1.389 -<https://msdn.microsoft.com/en-us/library/hh972425.aspx>
   1.390 -
   1.391 -A list of supported Win32 APIs for WinRT apps can be found at 
   1.392 -<http://msdn.microsoft.com/en-us/library/windows/apps/br205757.aspx>.  To note, 
   1.393 -the list of supported Win32 APIs for Windows Phone 8.0 is different.  
   1.394 -That list can be found at 
   1.395 -<http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj662956(v=vs.105).aspx>
   1.396 -
   1.397 -
   1.398 -### 7. Build and run your app ###
   1.399 -
   1.400 -Your app project should now be setup, and you should be ready to build your app.  
   1.401 -To run it on the local machine, open the Debug menu and choose "Start 
   1.402 -Debugging".  This will build your app, then run your app full-screen.  To switch 
   1.403 -out of your app, press the Windows key.  Alternatively, you can choose to run 
   1.404 -your app in a window.  To do this, before building and running your app, find 
   1.405 -the drop-down menu in Visual C++'s toolbar that says, "Local Machine".  Expand 
   1.406 -this by clicking on the arrow on the right side of the list, then click on 
   1.407 -Simulator.  Once you do that, any time you build and run the app, the app will 
   1.408 -launch in window, rather than full-screen.
   1.409 -
   1.410 -
   1.411 -#### 7.A. Running apps on older, ARM-based, "Windows RT" devices ####
   1.412 -
   1.413 -**These instructions do not include Windows Phone, despite Windows Phone
   1.414 -typically running on ARM processors.**  They are specifically for devices
   1.415 -that use the "Windows RT" operating system, which was a modified version of
   1.416 -Windows 8.x that ran primarily on ARM-based tablet computers.
   1.417 -
   1.418 -To build and run the app on ARM-based, "Windows RT" devices, you'll need to:
   1.419 -
   1.420 -- install Microsoft's "Remote Debugger" on the device.  Visual C++ installs and 
   1.421 -  debugs ARM-based apps via IP networks.
   1.422 -- change a few options on the development machine, both to make sure it builds 
   1.423 -  for ARM (rather than x86 or x64), and to make sure it knows how to find the 
   1.424 -  Windows RT device (on the network).
   1.425 -
   1.426 -Microsoft's Remote Debugger can be found at 
   1.427 -<https://msdn.microsoft.com/en-us/library/hh441469.aspx>.  Please note 
   1.428 -that separate versions of this debugger exist for different versions of Visual 
   1.429 -C++, one each for MSVC 2015, 2013, and 2012.
   1.430 -
   1.431 -To setup Visual C++ to launch your app on an ARM device:
   1.432 -
   1.433 -1. make sure the Remote Debugger is running on your ARM device, and that it's on 
   1.434 -   the same IP network as your development machine.
   1.435 -2. from Visual C++'s toolbar, find a drop-down menu that says, "Win32".  Click 
   1.436 -   it, then change the value to "ARM".
   1.437 -3. make sure Visual C++ knows the hostname or IP address of the ARM device.  To 
   1.438 -   do this:
   1.439 -    1. open the app project's properties
   1.440 -    2. select "Debugging"
   1.441 -    3. next to "Machine Name", enter the hostname or IP address of the ARM 
   1.442 -       device
   1.443 -    4. if, and only if, you've turned off authentication in the Remote Debugger,
   1.444 -       then change the setting for "Require Authentication" to No
   1.445 -    5. click "OK"
   1.446 -4. build and run the app (from Visual C++).  The first time you do this, a 
   1.447 -   prompt will show up on the ARM device, asking for a Microsoft Account.  You 
   1.448 -   do, unfortunately, need to log in here, and will need to follow the 
   1.449 -   subsequent registration steps in order to launch the app.  After you do so, 
   1.450 -   if the app didn't already launch, try relaunching it again from within Visual 
   1.451 -   C++.
   1.452 -
   1.453 -
   1.454 -Troubleshooting
   1.455 ----------------
   1.456 -
   1.457 -#### Build fails with message, "error LNK2038: mismatch detected for 'vccorlib_lib_should_be_specified_before_msvcrt_lib_to_linker'"
   1.458 -
   1.459 -Try adding the following to your linker flags.  In MSVC, this can be done by
   1.460 -right-clicking on the app project, navigating to Configuration Properties ->
   1.461 -Linker -> Command Line, then adding them to the Additional Options
   1.462 -section.
   1.463 -
   1.464 -* For Release builds / MSVC-Configurations, add:
   1.465 -
   1.466 -    /nodefaultlib:vccorlib /nodefaultlib:msvcrt vccorlib.lib msvcrt.lib
   1.467 -
   1.468 -* For Debug builds / MSVC-Configurations, add:
   1.469 -
   1.470 -    /nodefaultlib:vccorlibd /nodefaultlib:msvcrtd vccorlibd.lib msvcrtd.lib
   1.471 -
   1.472 -
   1.473 -#### Mouse-motion events fail to get sent, or SDL_GetMouseState() fails to return updated values
   1.474 -
   1.475 -This may be caused by a bug in Windows itself, whereby hiding the mouse
   1.476 -cursor can cause mouse-position reporting to fail.
   1.477 -
   1.478 -SDL provides a workaround for this, but it requires that an app links to a
   1.479 -set of Win32-style cursor image-resource files.  A copy of suitable resource
   1.480 -files can be found in `src/main/winrt/`.  Adding them to an app's Visual C++
   1.481 -project file should be sufficient to get the app to use them.
   1.482 +WinRT
   1.483 +=====
   1.484 +
   1.485 +This port allows SDL applications to run on Microsoft's platforms that require
   1.486 +use of "Windows Runtime", aka. "WinRT", APIs.  Microsoft may, in some cases,
   1.487 +refer to them as either "Windows Store", or for Windows 10, "UWP" apps.
   1.488 +
   1.489 +Some of the operating systems that include WinRT, are:
   1.490 +
   1.491 +* Windows 10, via its Universal Windows Platform (UWP) APIs
   1.492 +* Windows 8.x
   1.493 +* Windows RT 8.x (aka. Windows 8.x for ARM processors)
   1.494 +* Windows Phone 8.x
   1.495 +
   1.496 +
   1.497 +Requirements
   1.498 +------------
   1.499 +
   1.500 +* Microsoft Visual C++ (aka Visual Studio), either 2015, 2013, or 2012
   1.501 +  - Free, "Community" or "Express" editions may be used, so long as they
   1.502 +    include  support for either "Windows Store" or "Windows Phone" apps.
   1.503 +    "Express" versions marked as supporting "Windows Desktop" development
   1.504 +    typically do not include support for creating WinRT apps, to note.
   1.505 +    (The "Community" editions of Visual C++ do, however, support both
   1.506 +    desktop/Win32 and WinRT development).
   1.507 +  - Visual C++ 2012 can only build apps that target versions 8.0 of Windows,
   1.508 +    or  Windows Phone.  8.0-targetted apps will run on devices running 8.1
   1.509 +    editions of Windows, however they will not be able to take advantage of
   1.510 +    8.1-specific features.
   1.511 +  - Visual C++ 2013 cannot create app projects that target Windows 8.0.
   1.512 +    Visual C++ 2013 Update 4, can create app projects for Windows Phone 8.0,
   1.513 +    Windows Phone 8.1, and Windows 8.1, but not Windows 8.0.  An optional
   1.514 +    Visual Studio add-in, "Tools for Maintaining Store apps for Windows 8",
   1.515 +    allows Visual C++ 2013 to load and build Windows 8.0 projects that were
   1.516 +    created with Visual C++ 2012, so long as Visual C++ 2012 is installed
   1.517 +    on the same machine.  More details on targeting different versions of
   1.518 +    Windows can found at the following web pages:
   1.519 +      - [Develop apps by using Visual Studio 2013](http://msdn.microsoft.com/en-us/library/windows/apps/br211384.aspx)
   1.520 +      - [To add the Tools for Maintaining Store apps for Windows 8](http://msdn.microsoft.com/en-us/library/windows/apps/dn263114.aspx#AddMaintenanceTools)
   1.521 +* A valid Microsoft account - This requirement is not imposed by SDL, but
   1.522 +  rather by Microsoft's Visual C++ toolchain.  This is required to launch or 
   1.523 +  debug apps.
   1.524 +
   1.525 +
   1.526 +Status
   1.527 +------
   1.528 +
   1.529 +Here is a rough list of what works, and what doens't:
   1.530 +
   1.531 +* What works:
   1.532 +  * compilation via Visual C++ 2012 through 2015
   1.533 +  * compile-time platform detection for SDL programs.  The C/C++ #define,
   1.534 +    `__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
   1.535 +  * GPU-accelerated 2D rendering, via SDL_Renderer.
   1.536 +  * OpenGL ES 2, via the ANGLE library (included separately from SDL)
   1.537 +  * software rendering, via either SDL_Surface (optionally in conjunction with
   1.538 +    SDL_GetWindowSurface() and SDL_UpdateWindowSurface()) or via the
   1.539 +    SDL_Renderer APIs
   1.540 +  * threads
   1.541 +  * timers (via SDL_GetTicks(), SDL_AddTimer(), SDL_GetPerformanceCounter(),
   1.542 +    SDL_GetPerformanceFrequency(), etc.)
   1.543 +  * file I/O via SDL_RWops
   1.544 +  * mouse input  (unsupported on Windows Phone)
   1.545 +  * audio, via a modified version of SDL's XAudio2 backend
   1.546 +  * .DLL file loading.  Libraries *MUST* be packaged inside applications.  Loading
   1.547 +    anything outside of the app is not supported.
   1.548 +  * system path retrieval via SDL's filesystem APIs
   1.549 +  * game controllers.  Support is provided via the SDL_Joystick and
   1.550 +    SDL_GameController APIs, and is backed by Microsoft's XInput API.
   1.551 +  * multi-touch input
   1.552 +  * app events.  SDL_APP_WILLENTER* and SDL_APP_DIDENTER* events get sent out as
   1.553 +    appropriate.
   1.554 +  * window events
   1.555 +  * using Direct3D 11.x APIs outside of SDL.  Non-XAML / Direct3D-only apps can
   1.556 +    choose to render content directly via Direct3D, using SDL to manage the
   1.557 +    internal WinRT window, as well as input and audio.  (Use
   1.558 +    SDL_GetWindowWMInfo() to get the WinRT 'CoreWindow', and pass it into
   1.559 +    IDXGIFactory2::CreateSwapChainForCoreWindow() as appropriate.)
   1.560 +
   1.561 +* What partially works:
   1.562 +  * keyboard input.  Most of WinRT's documented virtual keys are supported, as
   1.563 +    well as many keys with documented hardware scancodes.  Converting
   1.564 +    SDL_Scancodes to or from SDL_Keycodes may not work, due to missing APIs
   1.565 +    (MapVirualKey()) in Microsoft's Windows Store / UWP APIs.
   1.566 +  * SDLmain.  WinRT uses a different signature for each app's main() function.
   1.567 +    SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
   1.568 +    (in `SDL\src\main\winrt\`) directly in order for their C-style main()
   1.569 +    functions to be called.
   1.570 +
   1.571 +* What doesn't work:
   1.572 +  * compilation with anything other than Visual C++
   1.573 +  * programmatically-created custom cursors.  These don't appear to be supported
   1.574 +    by WinRT.  Different OS-provided cursors can, however, be created via
   1.575 +    SDL_CreateSystemCursor() (unsupported on Windows Phone)
   1.576 +  * SDL_WarpMouseInWindow() or SDL_WarpMouseGlobal().  This are not currently
   1.577 +    supported by WinRT itself.
   1.578 +  * joysticks and game controllers that aren't supported by Microsoft's XInput
   1.579 +    API.
   1.580 +  * turning off VSync when rendering on Windows Phone.  Attempts to turn VSync
   1.581 +    off on Windows Phone result either in Direct3D not drawing anything, or it
   1.582 +    forcing VSync back on.  As such, SDL_RENDERER_PRESENTVSYNC will always get
   1.583 +    turned-on on Windows Phone.  This limitation is not present in non-Phone
   1.584 +    WinRT (such as Windows 8.x), where turning off VSync appears to work.
   1.585 +  * probably anything else that's not listed as supported
   1.586 +
   1.587 +
   1.588 +
   1.589 +Upgrade Notes
   1.590 +-------------
   1.591 +
   1.592 +#### SDL_GetPrefPath() usage when upgrading WinRT apps from SDL 2.0.3
   1.593 +
   1.594 +SDL 2.0.4 fixes two bugs found in the WinRT version of SDL_GetPrefPath().
   1.595 +The fixes may affect older, SDL 2.0.3-based apps' save data.  Please note
   1.596 +that these changes only apply to SDL-based WinRT apps, and not to apps for
   1.597 +any other platform.
   1.598 +
   1.599 +1. SDL_GetPrefPath() would return an invalid path, one in which the path's
   1.600 +   directory had not been created.  Attempts to create files there
   1.601 +   (via fopen(), for example), would fail, unless that directory was
   1.602 +   explicitly created beforehand.
   1.603 +
   1.604 +2. SDL_GetPrefPath(), for non-WinPhone-based apps, would return a path inside
   1.605 +   a WinRT 'Roaming' folder, the contents of which get automatically
   1.606 +   synchronized across multiple devices.  This process can occur while an
   1.607 +   application runs, and can cause existing save-data to be overwritten
   1.608 +   at unexpected times, with data from other devices.  (Windows Phone apps
   1.609 +   written with SDL 2.0.3 did not utilize a Roaming folder, due to API
   1.610 +   restrictions in Windows Phone 8.0).
   1.611 +
   1.612 +
   1.613 +SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
   1.614 +
   1.615 +1. making sure that SDL_GetPrefPath() returns a directory in which data
   1.616 +   can be written to immediately, without first needing to create directories.
   1.617 +
   1.618 +2. basing SDL_GetPrefPath() off of a different, non-Roaming folder, the
   1.619 +   contents of which do not automatically get synchronized across devices
   1.620 +   (and which require less work to use safely, in terms of data integrity).
   1.621 +
   1.622 +Apps that wish to get their Roaming folder's path can do so either by using
   1.623 +SDL_WinRTGetFSPathUTF8(), SDL_WinRTGetFSPathUNICODE() (which returns a
   1.624 +UCS-2/wide-char string), or directly through the WinRT class,
   1.625 +Windows.Storage.ApplicationData.
   1.626 +
   1.627 +
   1.628 +
   1.629 +Setup, High-Level Steps
   1.630 +-----------------------
   1.631 +
   1.632 +The steps for setting up a project for an SDL/WinRT app looks like the
   1.633 +following, at a high-level:
   1.634 +
   1.635 +1. create a new Visual C++ project using Microsoft's template for a,
   1.636 +   "Direct3D App".
   1.637 +2. remove most of the files from the project.
   1.638 +3. make your app's project directly reference SDL/WinRT's own Visual C++
   1.639 +   project file, via use of Visual C++'s "References" dialog.  This will setup
   1.640 +   the linker, and will copy SDL's .dll files to your app's final output.
   1.641 +4. adjust your app's build settings, at minimum, telling it where to find SDL's
   1.642 +   header files.
   1.643 +5. add files that contains a WinRT-appropriate main function, along with some
   1.644 +   data to make sure mouse-cursor-hiding (via SDL_ShowCursor(SDL_DISABLE) calls)
   1.645 +   work properly.
   1.646 +6. add SDL-specific app code.
   1.647 +7. build and run your app.
   1.648 +
   1.649 +
   1.650 +Setup, Detailed Steps
   1.651 +---------------------
   1.652 +
   1.653 +### 1. Create a new project ###
   1.654 +
   1.655 +Create a new project using one of Visual C++'s templates for a plain, non-XAML,
   1.656 +"Direct3D App" (XAML support for SDL/WinRT is not yet ready for use).  If you
   1.657 +don't see one of these templates, in Visual C++'s 'New Project' dialog, try
   1.658 +using the textbox titled, 'Search Installed Templates' to look for one.
   1.659 +
   1.660 +
   1.661 +### 2. Remove unneeded files from the project ###
   1.662 +
   1.663 +In the new project, delete any file that has one of the following extensions:
   1.664 +
   1.665 +- .cpp
   1.666 +- .h
   1.667 +- .hlsl
   1.668 +
   1.669 +When you are done, you should be left with a few files, each of which will be a
   1.670 +necessary part of your app's project.  These files will consist of:
   1.671 +
   1.672 +- an .appxmanifest file, which contains metadata on your WinRT app.  This is
   1.673 +  similar to an Info.plist file on iOS, or an AndroidManifest.xml on Android.
   1.674 +- a few .png files, one of which is a splash screen (displayed when your app
   1.675 +  launches), others are app icons.
   1.676 +- a .pfx file, used for code signing purposes.
   1.677 +
   1.678 +
   1.679 +### 3. Add references to SDL's project files ###
   1.680 +
   1.681 +SDL/WinRT can be built in multiple variations, spanning across three different
   1.682 +CPU architectures (x86, x64, and ARM) and two different configurations
   1.683 +(Debug and Release).  WinRT and Visual C++ do not currently provide a means
   1.684 +for combining multiple variations of one library into a single file.
   1.685 +Furthermore, it does not provide an easy means for copying pre-built .dll files
   1.686 +into your app's final output (via Post-Build steps, for example).  It does,
   1.687 +however, provide a system whereby an app can reference the MSVC projects of
   1.688 +libraries such that, when the app is built:
   1.689 +
   1.690 +1. each library gets built for the appropriate CPU architecture(s) and WinRT
   1.691 +   platform(s).
   1.692 +2. each library's output, such as .dll files, get copied to the app's build 
   1.693 +   output.
   1.694 +
   1.695 +To set this up for SDL/WinRT, you'll need to run through the following steps:
   1.696 +
   1.697 +1. open up the Solution Explorer inside Visual C++ (under the "View" menu, then
   1.698 +   "Solution Explorer")
   1.699 +2. right click on your app's solution.
   1.700 +3. navigate to "Add", then to "Existing Project..."
   1.701 +4. find SDL/WinRT's Visual C++ project file and open it.  Different project
   1.702 +   files exist for different WinRT platforms.  All of them are in SDL's
   1.703 +   source distribution, in the following directories:
   1.704 +    * `VisualC-WinRT/UWP_VS2015/`        - for Windows 10 / UWP apps
   1.705 +    * `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
   1.706 +    * `VisualC-WinRT/WinRT80_VS2012/`    - for Windows 8.0 apps
   1.707 +    * `VisualC-WinRT/WinRT81_VS2013/`    - for Windows 8.1 apps
   1.708 +5. once the project has been added, right-click on your app's project and
   1.709 +   select, "References..."
   1.710 +6. click on the button titled, "Add New Reference..."
   1.711 +7. check the box next to SDL
   1.712 +8. click OK to close the dialog
   1.713 +9. SDL will now show up in the list of references.  Click OK to close that
   1.714 +   dialog.
   1.715 +
   1.716 +Your project is now linked to SDL's project, insofar that when the app is
   1.717 +built, SDL will be built as well, with its build output getting included with
   1.718 +your app.
   1.719 +
   1.720 +
   1.721 +### 4. Adjust Your App's Build Settings ###
   1.722 +
   1.723 +Some build settings need to be changed in your app's project.  This guide will
   1.724 +outline the following:
   1.725 +
   1.726 +- making sure that the compiler knows where to find SDL's header files
   1.727 +- **Optional for C++, but NECESSARY for compiling C code:** telling the
   1.728 +  compiler not to use Microsoft's C++ extensions for WinRT development.
   1.729 +- **Optional:** telling the compiler not generate errors due to missing
   1.730 +  precompiled header files.
   1.731 +
   1.732 +To change these settings:
   1.733 +
   1.734 +1. right-click on the project
   1.735 +2. choose "Properties"
   1.736 +3. in the drop-down box next to "Configuration", choose, "All Configurations"
   1.737 +4. in the drop-down box next to "Platform", choose, "All Platforms"
   1.738 +5. in the left-hand list, expand the "C/C++" section
   1.739 +6. select "General"
   1.740 +7. edit the "Additional Include Directories" setting, and add a path to SDL's
   1.741 +   "include" directory
   1.742 +8. **Optional: to enable compilation of C code:** change the setting for
   1.743 +   "Consume Windows Runtime Extension" from "Yes (/ZW)" to "No".  If you're 
   1.744 +   working with a completely C++ based project, this step can usually be 
   1.745 +   omitted.
   1.746 +9. **Optional: to disable precompiled headers (which can produce 
   1.747 +   'stdafx.h'-related build errors, if setup incorrectly:** in the left-hand 
   1.748 +   list, select "Precompiled Headers", then change the setting for "Precompiled 
   1.749 +   Header" from "Use (/Yu)" to "Not Using Precompiled Headers".
   1.750 +10. close the dialog, saving settings, by clicking the "OK" button
   1.751 +
   1.752 +
   1.753 +### 5. Add a WinRT-appropriate main function, and a blank-cursor image, to the app. ###
   1.754 +
   1.755 +A few files should be included directly in your app's MSVC project, specifically:
   1.756 +1. a WinRT-appropriate main function (which is different than main() functions on
   1.757 +   other platforms)
   1.758 +2. a Win32-style cursor resource, used by SDL_ShowCursor() to hide the mouse cursor
   1.759 +   (if and when the app needs to do so).  *If this cursor resource is not
   1.760 +   included, mouse-position reporting may fail if and when the cursor is
   1.761 +   hidden, due to possible bugs/design-oddities in Windows itself.*
   1.762 +
   1.763 +To include these files:
   1.764 +
   1.765 +1. right-click on your project (again, in Visual C++'s Solution Explorer), 
   1.766 +   navigate to "Add", then choose "Existing Item...".
   1.767 +2. navigate to the directory containing SDL's source code, then into its
   1.768 +   subdirectory, 'src/main/winrt/'.  Select, then add, the following files:
   1.769 +   - `SDL_winrt_main_NonXAML.cpp`
   1.770 +   - `SDL2-WinRTResources.rc`
   1.771 +   - `SDL2-WinRTResource_BlankCursor.cur`
   1.772 +3. right-click on the file `SDL_winrt_main_NonXAML.cpp` (as listed in your
   1.773 +   project), then click on "Properties...".
   1.774 +4. in the drop-down box next to "Configuration", choose, "All Configurations"
   1.775 +5. in the drop-down box next to "Platform", choose, "All Platforms"
   1.776 +6. in the left-hand list, click on "C/C++"
   1.777 +7. change the setting for "Consume Windows Runtime Extension" to "Yes (/ZW)".
   1.778 +8. click the OK button.  This will close the dialog.
   1.779 +
   1.780 +
   1.781 +**NOTE: C++/CX compilation is currently required in at least one file of your 
   1.782 +app's project.  This is to make sure that Visual C++'s linker builds a 'Windows 
   1.783 +Metadata' file (.winmd) for your app.  Not doing so can lead to build errors.**
   1.784 +
   1.785 +
   1.786 +### 6. Add app code and assets ###
   1.787 +
   1.788 +At this point, you can add in SDL-specific source code.  Be sure to include a 
   1.789 +C-style main function (ie: `int main(int argc, char *argv[])`).  From there you 
   1.790 +should be able to create a single `SDL_Window` (WinRT apps can only have one 
   1.791 +window, at present), as well as an `SDL_Renderer`.  Direct3D will be used to 
   1.792 +draw content.  Events are received via SDL's usual event functions 
   1.793 +(`SDL_PollEvent`, etc.)  If you have a set of existing source files and assets, 
   1.794 +you can start adding them to the project now.  If not, or if you would like to 
   1.795 +make sure that you're setup correctly, some short and simple sample code is 
   1.796 +provided below.
   1.797 +
   1.798 +
   1.799 +#### 6.A. ... when creating a new app ####
   1.800 +
   1.801 +If you are creating a new app (rather than porting an existing SDL-based app), 
   1.802 +or if you would just like a simple app to test SDL/WinRT with before trying to 
   1.803 +get existing code working, some working SDL/WinRT code is provided below.  To 
   1.804 +set this up:
   1.805 +
   1.806 +1. right click on your app's project
   1.807 +2. select Add, then New Item.  An "Add New Item" dialog will show up.
   1.808 +3. from the left-hand list, choose "Visual C++"
   1.809 +4. from the middle/main list, choose "C++ File (.cpp)"
   1.810 +5. near the bottom of the dialog, next to "Name:", type in a name for your 
   1.811 +source file, such as, "main.cpp".
   1.812 +6. click on the Add button.  This will close the dialog, add the new file to 
   1.813 +your project, and open the file in Visual C++'s text editor.
   1.814 +7. Copy and paste the following code into the new file, then save it.
   1.815 +
   1.816 +
   1.817 +    #include <SDL.h>
   1.818 +    
   1.819 +    int main(int argc, char **argv)
   1.820 +    {
   1.821 +        SDL_DisplayMode mode;
   1.822 +        SDL_Window * window = NULL;
   1.823 +        SDL_Renderer * renderer = NULL;
   1.824 +        SDL_Event evt;
   1.825 +    
   1.826 +        if (SDL_Init(SDL_INIT_VIDEO) != 0) {
   1.827 +            return 1;
   1.828 +        }
   1.829 +    
   1.830 +        if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
   1.831 +            return 1;
   1.832 +        }
   1.833 +    
   1.834 +        if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
   1.835 +            return 1;
   1.836 +        }
   1.837 +    
   1.838 +        while (1) {
   1.839 +            while (SDL_PollEvent(&evt)) {
   1.840 +            }
   1.841 +    
   1.842 +            SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
   1.843 +            SDL_RenderClear(renderer);
   1.844 +            SDL_RenderPresent(renderer);
   1.845 +        }
   1.846 +    }
   1.847 +
   1.848 +
   1.849 +#### 6.B. Adding code and assets ####
   1.850 +
   1.851 +If you have existing code and assets that you'd like to add, you should be able 
   1.852 +to add them now.  The process for adding a set of files is as such.
   1.853 +
   1.854 +1. right click on the app's project
   1.855 +2. select Add, then click on "New Item..."
   1.856 +3. open any source, header, or asset files as appropriate.  Support for C and 
   1.857 +C++ is available.
   1.858 +
   1.859 +Do note that WinRT only supports a subset of the APIs that are available to 
   1.860 +Win32-based apps.  Many portions of the Win32 API and the C runtime are not 
   1.861 +available.
   1.862 +
   1.863 +A list of unsupported C APIs can be found at 
   1.864 +<http://msdn.microsoft.com/en-us/library/windows/apps/jj606124.aspx>
   1.865 +
   1.866 +General information on using the C runtime in WinRT can be found at 
   1.867 +<https://msdn.microsoft.com/en-us/library/hh972425.aspx>
   1.868 +
   1.869 +A list of supported Win32 APIs for WinRT apps can be found at 
   1.870 +<http://msdn.microsoft.com/en-us/library/windows/apps/br205757.aspx>.  To note, 
   1.871 +the list of supported Win32 APIs for Windows Phone 8.0 is different.  
   1.872 +That list can be found at 
   1.873 +<http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj662956(v=vs.105).aspx>
   1.874 +
   1.875 +
   1.876 +### 7. Build and run your app ###
   1.877 +
   1.878 +Your app project should now be setup, and you should be ready to build your app.  
   1.879 +To run it on the local machine, open the Debug menu and choose "Start 
   1.880 +Debugging".  This will build your app, then run your app full-screen.  To switch 
   1.881 +out of your app, press the Windows key.  Alternatively, you can choose to run 
   1.882 +your app in a window.  To do this, before building and running your app, find 
   1.883 +the drop-down menu in Visual C++'s toolbar that says, "Local Machine".  Expand 
   1.884 +this by clicking on the arrow on the right side of the list, then click on 
   1.885 +Simulator.  Once you do that, any time you build and run the app, the app will 
   1.886 +launch in window, rather than full-screen.
   1.887 +
   1.888 +
   1.889 +#### 7.A. Running apps on older, ARM-based, "Windows RT" devices ####
   1.890 +
   1.891 +**These instructions do not include Windows Phone, despite Windows Phone
   1.892 +typically running on ARM processors.**  They are specifically for devices
   1.893 +that use the "Windows RT" operating system, which was a modified version of
   1.894 +Windows 8.x that ran primarily on ARM-based tablet computers.
   1.895 +
   1.896 +To build and run the app on ARM-based, "Windows RT" devices, you'll need to:
   1.897 +
   1.898 +- install Microsoft's "Remote Debugger" on the device.  Visual C++ installs and 
   1.899 +  debugs ARM-based apps via IP networks.
   1.900 +- change a few options on the development machine, both to make sure it builds 
   1.901 +  for ARM (rather than x86 or x64), and to make sure it knows how to find the 
   1.902 +  Windows RT device (on the network).
   1.903 +
   1.904 +Microsoft's Remote Debugger can be found at 
   1.905 +<https://msdn.microsoft.com/en-us/library/hh441469.aspx>.  Please note 
   1.906 +that separate versions of this debugger exist for different versions of Visual 
   1.907 +C++, one each for MSVC 2015, 2013, and 2012.
   1.908 +
   1.909 +To setup Visual C++ to launch your app on an ARM device:
   1.910 +
   1.911 +1. make sure the Remote Debugger is running on your ARM device, and that it's on 
   1.912 +   the same IP network as your development machine.
   1.913 +2. from Visual C++'s toolbar, find a drop-down menu that says, "Win32".  Click 
   1.914 +   it, then change the value to "ARM".
   1.915 +3. make sure Visual C++ knows the hostname or IP address of the ARM device.  To 
   1.916 +   do this:
   1.917 +    1. open the app project's properties
   1.918 +    2. select "Debugging"
   1.919 +    3. next to "Machine Name", enter the hostname or IP address of the ARM 
   1.920 +       device
   1.921 +    4. if, and only if, you've turned off authentication in the Remote Debugger,
   1.922 +       then change the setting for "Require Authentication" to No
   1.923 +    5. click "OK"
   1.924 +4. build and run the app (from Visual C++).  The first time you do this, a 
   1.925 +   prompt will show up on the ARM device, asking for a Microsoft Account.  You 
   1.926 +   do, unfortunately, need to log in here, and will need to follow the 
   1.927 +   subsequent registration steps in order to launch the app.  After you do so, 
   1.928 +   if the app didn't already launch, try relaunching it again from within Visual 
   1.929 +   C++.
   1.930 +
   1.931 +
   1.932 +Troubleshooting
   1.933 +---------------
   1.934 +
   1.935 +#### Build fails with message, "error LNK2038: mismatch detected for 'vccorlib_lib_should_be_specified_before_msvcrt_lib_to_linker'"
   1.936 +
   1.937 +Try adding the following to your linker flags.  In MSVC, this can be done by
   1.938 +right-clicking on the app project, navigating to Configuration Properties ->
   1.939 +Linker -> Command Line, then adding them to the Additional Options
   1.940 +section.
   1.941 +
   1.942 +* For Release builds / MSVC-Configurations, add:
   1.943 +
   1.944 +    /nodefaultlib:vccorlib /nodefaultlib:msvcrt vccorlib.lib msvcrt.lib
   1.945 +
   1.946 +* For Debug builds / MSVC-Configurations, add:
   1.947 +
   1.948 +    /nodefaultlib:vccorlibd /nodefaultlib:msvcrtd vccorlibd.lib msvcrtd.lib
   1.949 +
   1.950 +
   1.951 +#### Mouse-motion events fail to get sent, or SDL_GetMouseState() fails to return updated values
   1.952 +
   1.953 +This may be caused by a bug in Windows itself, whereby hiding the mouse
   1.954 +cursor can cause mouse-position reporting to fail.
   1.955 +
   1.956 +SDL provides a workaround for this, but it requires that an app links to a
   1.957 +set of Win32-style cursor image-resource files.  A copy of suitable resource
   1.958 +files can be found in `src/main/winrt/`.  Adding them to an app's Visual C++
   1.959 +project file should be sufficient to get the app to use them.