docs/README-winrt.md
author Sam Lantinga <slouken@libsdl.org>
Tue, 23 Apr 2019 07:59:31 -0700
changeset 12714 9b7633bd0aa0
parent 11726 27d08f1aab80
child 12810 77707a081153
permissions -rw-r--r--
Use _Exit() when available
slouken@10486
     1
WinRT
slouken@10486
     2
=====
slouken@10486
     3
slouken@10486
     4
This port allows SDL applications to run on Microsoft's platforms that require
slouken@10486
     5
use of "Windows Runtime", aka. "WinRT", APIs.  Microsoft may, in some cases,
slouken@10486
     6
refer to them as either "Windows Store", or for Windows 10, "UWP" apps.
slouken@10486
     7
slouken@10486
     8
Some of the operating systems that include WinRT, are:
slouken@10486
     9
slouken@10486
    10
* Windows 10, via its Universal Windows Platform (UWP) APIs
slouken@10486
    11
* Windows 8.x
slouken@10486
    12
* Windows RT 8.x (aka. Windows 8.x for ARM processors)
slouken@10486
    13
* Windows Phone 8.x
slouken@10486
    14
slouken@10486
    15
slouken@10486
    16
Requirements
slouken@10486
    17
------------
slouken@10486
    18
dludwig@11446
    19
* Microsoft Visual C++ (aka Visual Studio), either 2017, 2015, 2013, or 2012
slouken@10486
    20
  - Free, "Community" or "Express" editions may be used, so long as they
slouken@10486
    21
    include  support for either "Windows Store" or "Windows Phone" apps.
slouken@10486
    22
    "Express" versions marked as supporting "Windows Desktop" development
slouken@10486
    23
    typically do not include support for creating WinRT apps, to note.
slouken@10486
    24
    (The "Community" editions of Visual C++ do, however, support both
slouken@10486
    25
    desktop/Win32 and WinRT development).
slouken@11720
    26
  - Visual Studio 2017 can be used, however it is recommended that you install
dludwig@11446
    27
    the Visual C++ 2015 build tools.  These build tools can be installed
dludwig@11446
    28
    using VS 2017's installer.  Be sure to also install the workload for
dludwig@11446
    29
    "Universal Windows Platform development", its optional component, the
dludwig@11446
    30
    "C++ Universal Windows Platform tools", and for UWP / Windows 10
dludwig@11446
    31
    development, the "Windows 10 SDK (10.0.10240.0)".  Please note that
dludwig@11446
    32
    targeting UWP / Windows 10 apps from development machine(s) running
dludwig@11446
    33
    earlier versions of Windows, such as Windows 7, is not always supported
dludwig@11446
    34
    by Visual Studio, and you may get error(s) when attempting to do so.
slouken@10486
    35
  - Visual C++ 2012 can only build apps that target versions 8.0 of Windows,
slouken@11720
    36
    or  Windows Phone.  8.0-targeted apps will run on devices running 8.1
slouken@10486
    37
    editions of Windows, however they will not be able to take advantage of
slouken@10486
    38
    8.1-specific features.
slouken@10486
    39
  - Visual C++ 2013 cannot create app projects that target Windows 8.0.
slouken@10486
    40
    Visual C++ 2013 Update 4, can create app projects for Windows Phone 8.0,
slouken@10486
    41
    Windows Phone 8.1, and Windows 8.1, but not Windows 8.0.  An optional
slouken@10486
    42
    Visual Studio add-in, "Tools for Maintaining Store apps for Windows 8",
slouken@10486
    43
    allows Visual C++ 2013 to load and build Windows 8.0 projects that were
slouken@10486
    44
    created with Visual C++ 2012, so long as Visual C++ 2012 is installed
slouken@10486
    45
    on the same machine.  More details on targeting different versions of
slouken@10486
    46
    Windows can found at the following web pages:
slouken@10486
    47
      - [Develop apps by using Visual Studio 2013](http://msdn.microsoft.com/en-us/library/windows/apps/br211384.aspx)
slouken@10486
    48
      - [To add the Tools for Maintaining Store apps for Windows 8](http://msdn.microsoft.com/en-us/library/windows/apps/dn263114.aspx#AddMaintenanceTools)
slouken@10486
    49
* A valid Microsoft account - This requirement is not imposed by SDL, but
slouken@10486
    50
  rather by Microsoft's Visual C++ toolchain.  This is required to launch or 
slouken@10486
    51
  debug apps.
slouken@10486
    52
slouken@10486
    53
slouken@10486
    54
Status
slouken@10486
    55
------
slouken@10486
    56
slouken@11720
    57
Here is a rough list of what works, and what doesn't:
slouken@10486
    58
slouken@10486
    59
* What works:
slouken@10486
    60
  * compilation via Visual C++ 2012 through 2015
slouken@10486
    61
  * compile-time platform detection for SDL programs.  The C/C++ #define,
slouken@10486
    62
    `__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
slouken@10486
    63
  * GPU-accelerated 2D rendering, via SDL_Renderer.
slouken@10486
    64
  * OpenGL ES 2, via the ANGLE library (included separately from SDL)
slouken@10486
    65
  * software rendering, via either SDL_Surface (optionally in conjunction with
slouken@10486
    66
    SDL_GetWindowSurface() and SDL_UpdateWindowSurface()) or via the
slouken@10486
    67
    SDL_Renderer APIs
slouken@10486
    68
  * threads
slouken@10486
    69
  * timers (via SDL_GetTicks(), SDL_AddTimer(), SDL_GetPerformanceCounter(),
slouken@10486
    70
    SDL_GetPerformanceFrequency(), etc.)
slouken@10486
    71
  * file I/O via SDL_RWops
slouken@10486
    72
  * mouse input  (unsupported on Windows Phone)
icculus@11726
    73
  * audio, via SDL's WASAPI backend (if you want to record, your app must 
icculus@11726
    74
    have "Microphone" capabilities enabled in its manifest, and the user must 
icculus@11726
    75
    not have blocked access. Otherwise, capture devices will fail to work,
icculus@11726
    76
    presenting as a device disconnect shortly after opening it.)
slouken@10486
    77
  * .DLL file loading.  Libraries *MUST* be packaged inside applications.  Loading
slouken@10486
    78
    anything outside of the app is not supported.
slouken@10486
    79
  * system path retrieval via SDL's filesystem APIs
slouken@10486
    80
  * game controllers.  Support is provided via the SDL_Joystick and
dludwig@11502
    81
    SDL_GameController APIs, and is backed by Microsoft's XInput API.  Please
dludwig@11502
    82
    note, however, that Windows limits game-controller support in UWP apps to,
dludwig@11502
    83
    "Xbox compatible controllers" (many controllers that work in Win32 apps,
dludwig@11502
    84
    do not work in UWP, due to restrictions in UWP itself.) 
slouken@10486
    85
  * multi-touch input
slouken@10486
    86
  * app events.  SDL_APP_WILLENTER* and SDL_APP_DIDENTER* events get sent out as
slouken@10486
    87
    appropriate.
slouken@10486
    88
  * window events
slouken@10486
    89
  * using Direct3D 11.x APIs outside of SDL.  Non-XAML / Direct3D-only apps can
slouken@10486
    90
    choose to render content directly via Direct3D, using SDL to manage the
slouken@10486
    91
    internal WinRT window, as well as input and audio.  (Use
slouken@10486
    92
    SDL_GetWindowWMInfo() to get the WinRT 'CoreWindow', and pass it into
slouken@10486
    93
    IDXGIFactory2::CreateSwapChainForCoreWindow() as appropriate.)
slouken@10486
    94
slouken@10486
    95
* What partially works:
slouken@10486
    96
  * keyboard input.  Most of WinRT's documented virtual keys are supported, as
slouken@10486
    97
    well as many keys with documented hardware scancodes.  Converting
slouken@10486
    98
    SDL_Scancodes to or from SDL_Keycodes may not work, due to missing APIs
philipp@10828
    99
    (MapVirtualKey()) in Microsoft's Windows Store / UWP APIs.
slouken@10486
   100
  * SDLmain.  WinRT uses a different signature for each app's main() function.
slouken@10486
   101
    SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
slouken@10486
   102
    (in `SDL\src\main\winrt\`) directly in order for their C-style main()
slouken@10486
   103
    functions to be called.
slouken@10486
   104
slouken@10486
   105
* What doesn't work:
slouken@10486
   106
  * compilation with anything other than Visual C++
slouken@10486
   107
  * programmatically-created custom cursors.  These don't appear to be supported
slouken@10486
   108
    by WinRT.  Different OS-provided cursors can, however, be created via
slouken@10486
   109
    SDL_CreateSystemCursor() (unsupported on Windows Phone)
slouken@10486
   110
  * SDL_WarpMouseInWindow() or SDL_WarpMouseGlobal().  This are not currently
slouken@10486
   111
    supported by WinRT itself.
dludwig@11502
   112
  * joysticks and game controllers that either are not supported by
dludwig@11502
   113
    Microsoft's XInput API, or are not supported within UWP apps (many
dludwig@11502
   114
    controllers that work in Win32, do not work in UWP, due to restrictions in
dludwig@11502
   115
    UWP itself).
slouken@10486
   116
  * turning off VSync when rendering on Windows Phone.  Attempts to turn VSync
slouken@10486
   117
    off on Windows Phone result either in Direct3D not drawing anything, or it
slouken@10486
   118
    forcing VSync back on.  As such, SDL_RENDERER_PRESENTVSYNC will always get
slouken@10486
   119
    turned-on on Windows Phone.  This limitation is not present in non-Phone
slouken@10486
   120
    WinRT (such as Windows 8.x), where turning off VSync appears to work.
slouken@10486
   121
  * probably anything else that's not listed as supported
slouken@10486
   122
slouken@10486
   123
slouken@10486
   124
slouken@10486
   125
Upgrade Notes
slouken@10486
   126
-------------
slouken@10486
   127
slouken@10486
   128
#### SDL_GetPrefPath() usage when upgrading WinRT apps from SDL 2.0.3
slouken@10486
   129
slouken@10486
   130
SDL 2.0.4 fixes two bugs found in the WinRT version of SDL_GetPrefPath().
slouken@10486
   131
The fixes may affect older, SDL 2.0.3-based apps' save data.  Please note
slouken@10486
   132
that these changes only apply to SDL-based WinRT apps, and not to apps for
slouken@10486
   133
any other platform.
slouken@10486
   134
slouken@10486
   135
1. SDL_GetPrefPath() would return an invalid path, one in which the path's
slouken@10486
   136
   directory had not been created.  Attempts to create files there
slouken@10486
   137
   (via fopen(), for example), would fail, unless that directory was
slouken@10486
   138
   explicitly created beforehand.
slouken@10486
   139
slouken@10486
   140
2. SDL_GetPrefPath(), for non-WinPhone-based apps, would return a path inside
slouken@10486
   141
   a WinRT 'Roaming' folder, the contents of which get automatically
slouken@10486
   142
   synchronized across multiple devices.  This process can occur while an
slouken@10486
   143
   application runs, and can cause existing save-data to be overwritten
slouken@10486
   144
   at unexpected times, with data from other devices.  (Windows Phone apps
slouken@10486
   145
   written with SDL 2.0.3 did not utilize a Roaming folder, due to API
slouken@10486
   146
   restrictions in Windows Phone 8.0).
slouken@10486
   147
slouken@10486
   148
slouken@10486
   149
SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
slouken@10486
   150
slouken@10486
   151
1. making sure that SDL_GetPrefPath() returns a directory in which data
slouken@10486
   152
   can be written to immediately, without first needing to create directories.
slouken@10486
   153
slouken@10486
   154
2. basing SDL_GetPrefPath() off of a different, non-Roaming folder, the
slouken@10486
   155
   contents of which do not automatically get synchronized across devices
slouken@10486
   156
   (and which require less work to use safely, in terms of data integrity).
slouken@10486
   157
slouken@10486
   158
Apps that wish to get their Roaming folder's path can do so either by using
slouken@10486
   159
SDL_WinRTGetFSPathUTF8(), SDL_WinRTGetFSPathUNICODE() (which returns a
slouken@10486
   160
UCS-2/wide-char string), or directly through the WinRT class,
slouken@10486
   161
Windows.Storage.ApplicationData.
slouken@10486
   162
slouken@10486
   163
slouken@10486
   164
slouken@10486
   165
Setup, High-Level Steps
slouken@10486
   166
-----------------------
slouken@10486
   167
slouken@10486
   168
The steps for setting up a project for an SDL/WinRT app looks like the
slouken@10486
   169
following, at a high-level:
slouken@10486
   170
slouken@10486
   171
1. create a new Visual C++ project using Microsoft's template for a,
slouken@10486
   172
   "Direct3D App".
slouken@10486
   173
2. remove most of the files from the project.
slouken@10486
   174
3. make your app's project directly reference SDL/WinRT's own Visual C++
slouken@10486
   175
   project file, via use of Visual C++'s "References" dialog.  This will setup
slouken@10486
   176
   the linker, and will copy SDL's .dll files to your app's final output.
slouken@10486
   177
4. adjust your app's build settings, at minimum, telling it where to find SDL's
slouken@10486
   178
   header files.
slouken@10486
   179
5. add files that contains a WinRT-appropriate main function, along with some
slouken@10486
   180
   data to make sure mouse-cursor-hiding (via SDL_ShowCursor(SDL_DISABLE) calls)
slouken@10486
   181
   work properly.
slouken@10486
   182
6. add SDL-specific app code.
slouken@10486
   183
7. build and run your app.
slouken@10486
   184
slouken@10486
   185
slouken@10486
   186
Setup, Detailed Steps
slouken@10486
   187
---------------------
slouken@10486
   188
slouken@10486
   189
### 1. Create a new project ###
slouken@10486
   190
slouken@10486
   191
Create a new project using one of Visual C++'s templates for a plain, non-XAML,
slouken@10486
   192
"Direct3D App" (XAML support for SDL/WinRT is not yet ready for use).  If you
slouken@10486
   193
don't see one of these templates, in Visual C++'s 'New Project' dialog, try
slouken@10486
   194
using the textbox titled, 'Search Installed Templates' to look for one.
slouken@10486
   195
slouken@10486
   196
slouken@10486
   197
### 2. Remove unneeded files from the project ###
slouken@10486
   198
slouken@10486
   199
In the new project, delete any file that has one of the following extensions:
slouken@10486
   200
slouken@10486
   201
- .cpp
slouken@10486
   202
- .h
slouken@10486
   203
- .hlsl
slouken@10486
   204
slouken@10486
   205
When you are done, you should be left with a few files, each of which will be a
slouken@10486
   206
necessary part of your app's project.  These files will consist of:
slouken@10486
   207
slouken@10486
   208
- an .appxmanifest file, which contains metadata on your WinRT app.  This is
slouken@10486
   209
  similar to an Info.plist file on iOS, or an AndroidManifest.xml on Android.
slouken@10486
   210
- a few .png files, one of which is a splash screen (displayed when your app
slouken@10486
   211
  launches), others are app icons.
slouken@10486
   212
- a .pfx file, used for code signing purposes.
slouken@10486
   213
slouken@10486
   214
slouken@10486
   215
### 3. Add references to SDL's project files ###
slouken@10486
   216
slouken@10486
   217
SDL/WinRT can be built in multiple variations, spanning across three different
slouken@10486
   218
CPU architectures (x86, x64, and ARM) and two different configurations
slouken@10486
   219
(Debug and Release).  WinRT and Visual C++ do not currently provide a means
slouken@10486
   220
for combining multiple variations of one library into a single file.
slouken@10486
   221
Furthermore, it does not provide an easy means for copying pre-built .dll files
slouken@10486
   222
into your app's final output (via Post-Build steps, for example).  It does,
slouken@10486
   223
however, provide a system whereby an app can reference the MSVC projects of
slouken@10486
   224
libraries such that, when the app is built:
slouken@10486
   225
slouken@10486
   226
1. each library gets built for the appropriate CPU architecture(s) and WinRT
slouken@10486
   227
   platform(s).
slouken@10486
   228
2. each library's output, such as .dll files, get copied to the app's build 
slouken@10486
   229
   output.
slouken@10486
   230
slouken@10486
   231
To set this up for SDL/WinRT, you'll need to run through the following steps:
slouken@10486
   232
slouken@10486
   233
1. open up the Solution Explorer inside Visual C++ (under the "View" menu, then
slouken@10486
   234
   "Solution Explorer")
slouken@10486
   235
2. right click on your app's solution.
slouken@10486
   236
3. navigate to "Add", then to "Existing Project..."
slouken@10486
   237
4. find SDL/WinRT's Visual C++ project file and open it.  Different project
slouken@10486
   238
   files exist for different WinRT platforms.  All of them are in SDL's
slouken@10486
   239
   source distribution, in the following directories:
slouken@10486
   240
    * `VisualC-WinRT/UWP_VS2015/`        - for Windows 10 / UWP apps
slouken@10486
   241
    * `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
slouken@10486
   242
    * `VisualC-WinRT/WinRT80_VS2012/`    - for Windows 8.0 apps
slouken@10486
   243
    * `VisualC-WinRT/WinRT81_VS2013/`    - for Windows 8.1 apps
slouken@10486
   244
5. once the project has been added, right-click on your app's project and
slouken@10486
   245
   select, "References..."
slouken@10486
   246
6. click on the button titled, "Add New Reference..."
slouken@10486
   247
7. check the box next to SDL
slouken@10486
   248
8. click OK to close the dialog
slouken@10486
   249
9. SDL will now show up in the list of references.  Click OK to close that
slouken@10486
   250
   dialog.
slouken@10486
   251
slouken@10486
   252
Your project is now linked to SDL's project, insofar that when the app is
slouken@10486
   253
built, SDL will be built as well, with its build output getting included with
slouken@10486
   254
your app.
slouken@10486
   255
slouken@10486
   256
slouken@10486
   257
### 4. Adjust Your App's Build Settings ###
slouken@10486
   258
slouken@10486
   259
Some build settings need to be changed in your app's project.  This guide will
slouken@10486
   260
outline the following:
slouken@10486
   261
slouken@10486
   262
- making sure that the compiler knows where to find SDL's header files
slouken@10486
   263
- **Optional for C++, but NECESSARY for compiling C code:** telling the
slouken@10486
   264
  compiler not to use Microsoft's C++ extensions for WinRT development.
slouken@10486
   265
- **Optional:** telling the compiler not generate errors due to missing
slouken@10486
   266
  precompiled header files.
slouken@10486
   267
slouken@10486
   268
To change these settings:
slouken@10486
   269
slouken@10486
   270
1. right-click on the project
slouken@10486
   271
2. choose "Properties"
slouken@10486
   272
3. in the drop-down box next to "Configuration", choose, "All Configurations"
slouken@10486
   273
4. in the drop-down box next to "Platform", choose, "All Platforms"
slouken@10486
   274
5. in the left-hand list, expand the "C/C++" section
slouken@10486
   275
6. select "General"
slouken@10486
   276
7. edit the "Additional Include Directories" setting, and add a path to SDL's
slouken@10486
   277
   "include" directory
slouken@10486
   278
8. **Optional: to enable compilation of C code:** change the setting for
slouken@10486
   279
   "Consume Windows Runtime Extension" from "Yes (/ZW)" to "No".  If you're 
slouken@10486
   280
   working with a completely C++ based project, this step can usually be 
slouken@10486
   281
   omitted.
slouken@10486
   282
9. **Optional: to disable precompiled headers (which can produce 
slouken@10486
   283
   'stdafx.h'-related build errors, if setup incorrectly:** in the left-hand 
slouken@10486
   284
   list, select "Precompiled Headers", then change the setting for "Precompiled 
slouken@10486
   285
   Header" from "Use (/Yu)" to "Not Using Precompiled Headers".
slouken@10486
   286
10. close the dialog, saving settings, by clicking the "OK" button
slouken@10486
   287
slouken@10486
   288
slouken@10486
   289
### 5. Add a WinRT-appropriate main function, and a blank-cursor image, to the app. ###
slouken@10486
   290
slouken@10486
   291
A few files should be included directly in your app's MSVC project, specifically:
slouken@10486
   292
1. a WinRT-appropriate main function (which is different than main() functions on
slouken@10486
   293
   other platforms)
slouken@10486
   294
2. a Win32-style cursor resource, used by SDL_ShowCursor() to hide the mouse cursor
slouken@10486
   295
   (if and when the app needs to do so).  *If this cursor resource is not
slouken@10486
   296
   included, mouse-position reporting may fail if and when the cursor is
slouken@10486
   297
   hidden, due to possible bugs/design-oddities in Windows itself.*
slouken@10486
   298
slouken@10486
   299
To include these files:
slouken@10486
   300
slouken@10486
   301
1. right-click on your project (again, in Visual C++'s Solution Explorer), 
slouken@10486
   302
   navigate to "Add", then choose "Existing Item...".
slouken@10486
   303
2. navigate to the directory containing SDL's source code, then into its
slouken@10486
   304
   subdirectory, 'src/main/winrt/'.  Select, then add, the following files:
slouken@10486
   305
   - `SDL_winrt_main_NonXAML.cpp`
slouken@10486
   306
   - `SDL2-WinRTResources.rc`
slouken@10486
   307
   - `SDL2-WinRTResource_BlankCursor.cur`
slouken@10486
   308
3. right-click on the file `SDL_winrt_main_NonXAML.cpp` (as listed in your
slouken@10486
   309
   project), then click on "Properties...".
slouken@10486
   310
4. in the drop-down box next to "Configuration", choose, "All Configurations"
slouken@10486
   311
5. in the drop-down box next to "Platform", choose, "All Platforms"
slouken@10486
   312
6. in the left-hand list, click on "C/C++"
slouken@10486
   313
7. change the setting for "Consume Windows Runtime Extension" to "Yes (/ZW)".
slouken@10486
   314
8. click the OK button.  This will close the dialog.
slouken@10486
   315
slouken@10486
   316
slouken@10486
   317
**NOTE: C++/CX compilation is currently required in at least one file of your 
slouken@10486
   318
app's project.  This is to make sure that Visual C++'s linker builds a 'Windows 
slouken@10486
   319
Metadata' file (.winmd) for your app.  Not doing so can lead to build errors.**
slouken@10486
   320
slouken@10486
   321
slouken@10486
   322
### 6. Add app code and assets ###
slouken@10486
   323
slouken@10486
   324
At this point, you can add in SDL-specific source code.  Be sure to include a 
slouken@10486
   325
C-style main function (ie: `int main(int argc, char *argv[])`).  From there you 
slouken@10486
   326
should be able to create a single `SDL_Window` (WinRT apps can only have one 
slouken@10486
   327
window, at present), as well as an `SDL_Renderer`.  Direct3D will be used to 
slouken@10486
   328
draw content.  Events are received via SDL's usual event functions 
slouken@10486
   329
(`SDL_PollEvent`, etc.)  If you have a set of existing source files and assets, 
slouken@10486
   330
you can start adding them to the project now.  If not, or if you would like to 
slouken@10486
   331
make sure that you're setup correctly, some short and simple sample code is 
slouken@10486
   332
provided below.
slouken@10486
   333
slouken@10486
   334
slouken@10486
   335
#### 6.A. ... when creating a new app ####
slouken@10486
   336
slouken@10486
   337
If you are creating a new app (rather than porting an existing SDL-based app), 
slouken@10486
   338
or if you would just like a simple app to test SDL/WinRT with before trying to 
slouken@10486
   339
get existing code working, some working SDL/WinRT code is provided below.  To 
slouken@10486
   340
set this up:
slouken@10486
   341
slouken@10486
   342
1. right click on your app's project
slouken@10486
   343
2. select Add, then New Item.  An "Add New Item" dialog will show up.
slouken@10486
   344
3. from the left-hand list, choose "Visual C++"
slouken@10486
   345
4. from the middle/main list, choose "C++ File (.cpp)"
slouken@10486
   346
5. near the bottom of the dialog, next to "Name:", type in a name for your 
slouken@10486
   347
source file, such as, "main.cpp".
slouken@10486
   348
6. click on the Add button.  This will close the dialog, add the new file to 
slouken@10486
   349
your project, and open the file in Visual C++'s text editor.
slouken@10486
   350
7. Copy and paste the following code into the new file, then save it.
slouken@10486
   351
slouken@10486
   352
slouken@10486
   353
    #include <SDL.h>
slouken@10486
   354
    
slouken@10486
   355
    int main(int argc, char **argv)
slouken@10486
   356
    {
slouken@10486
   357
        SDL_DisplayMode mode;
slouken@10486
   358
        SDL_Window * window = NULL;
slouken@10486
   359
        SDL_Renderer * renderer = NULL;
slouken@10486
   360
        SDL_Event evt;
slouken@10486
   361
    
slouken@10486
   362
        if (SDL_Init(SDL_INIT_VIDEO) != 0) {
slouken@10486
   363
            return 1;
slouken@10486
   364
        }
slouken@10486
   365
    
slouken@10486
   366
        if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
slouken@10486
   367
            return 1;
slouken@10486
   368
        }
slouken@10486
   369
    
slouken@10486
   370
        if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
slouken@10486
   371
            return 1;
slouken@10486
   372
        }
slouken@10486
   373
    
slouken@10486
   374
        while (1) {
slouken@10486
   375
            while (SDL_PollEvent(&evt)) {
slouken@10486
   376
            }
slouken@10486
   377
    
slouken@10486
   378
            SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
slouken@10486
   379
            SDL_RenderClear(renderer);
slouken@10486
   380
            SDL_RenderPresent(renderer);
slouken@10486
   381
        }
slouken@10486
   382
    }
slouken@10486
   383
slouken@10486
   384
slouken@10486
   385
#### 6.B. Adding code and assets ####
slouken@10486
   386
slouken@10486
   387
If you have existing code and assets that you'd like to add, you should be able 
slouken@10486
   388
to add them now.  The process for adding a set of files is as such.
slouken@10486
   389
slouken@10486
   390
1. right click on the app's project
slouken@10486
   391
2. select Add, then click on "New Item..."
slouken@10486
   392
3. open any source, header, or asset files as appropriate.  Support for C and 
slouken@10486
   393
C++ is available.
slouken@10486
   394
slouken@10486
   395
Do note that WinRT only supports a subset of the APIs that are available to 
slouken@10486
   396
Win32-based apps.  Many portions of the Win32 API and the C runtime are not 
slouken@10486
   397
available.
slouken@10486
   398
slouken@10486
   399
A list of unsupported C APIs can be found at 
slouken@10486
   400
<http://msdn.microsoft.com/en-us/library/windows/apps/jj606124.aspx>
slouken@10486
   401
slouken@10486
   402
General information on using the C runtime in WinRT can be found at 
slouken@10486
   403
<https://msdn.microsoft.com/en-us/library/hh972425.aspx>
slouken@10486
   404
slouken@10486
   405
A list of supported Win32 APIs for WinRT apps can be found at 
slouken@10486
   406
<http://msdn.microsoft.com/en-us/library/windows/apps/br205757.aspx>.  To note, 
slouken@10486
   407
the list of supported Win32 APIs for Windows Phone 8.0 is different.  
slouken@10486
   408
That list can be found at 
slouken@10486
   409
<http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj662956(v=vs.105).aspx>
slouken@10486
   410
slouken@10486
   411
slouken@10486
   412
### 7. Build and run your app ###
slouken@10486
   413
slouken@10486
   414
Your app project should now be setup, and you should be ready to build your app.  
slouken@10486
   415
To run it on the local machine, open the Debug menu and choose "Start 
slouken@10486
   416
Debugging".  This will build your app, then run your app full-screen.  To switch 
slouken@10486
   417
out of your app, press the Windows key.  Alternatively, you can choose to run 
slouken@10486
   418
your app in a window.  To do this, before building and running your app, find 
slouken@10486
   419
the drop-down menu in Visual C++'s toolbar that says, "Local Machine".  Expand 
slouken@10486
   420
this by clicking on the arrow on the right side of the list, then click on 
slouken@10486
   421
Simulator.  Once you do that, any time you build and run the app, the app will 
slouken@10486
   422
launch in window, rather than full-screen.
slouken@10486
   423
slouken@10486
   424
slouken@10486
   425
#### 7.A. Running apps on older, ARM-based, "Windows RT" devices ####
slouken@10486
   426
slouken@10486
   427
**These instructions do not include Windows Phone, despite Windows Phone
slouken@10486
   428
typically running on ARM processors.**  They are specifically for devices
slouken@10486
   429
that use the "Windows RT" operating system, which was a modified version of
slouken@10486
   430
Windows 8.x that ran primarily on ARM-based tablet computers.
slouken@10486
   431
slouken@10486
   432
To build and run the app on ARM-based, "Windows RT" devices, you'll need to:
slouken@10486
   433
slouken@10486
   434
- install Microsoft's "Remote Debugger" on the device.  Visual C++ installs and 
slouken@10486
   435
  debugs ARM-based apps via IP networks.
slouken@10486
   436
- change a few options on the development machine, both to make sure it builds 
slouken@10486
   437
  for ARM (rather than x86 or x64), and to make sure it knows how to find the 
slouken@10486
   438
  Windows RT device (on the network).
slouken@10486
   439
slouken@10486
   440
Microsoft's Remote Debugger can be found at 
slouken@10486
   441
<https://msdn.microsoft.com/en-us/library/hh441469.aspx>.  Please note 
slouken@10486
   442
that separate versions of this debugger exist for different versions of Visual 
slouken@10486
   443
C++, one each for MSVC 2015, 2013, and 2012.
slouken@10486
   444
slouken@10486
   445
To setup Visual C++ to launch your app on an ARM device:
slouken@10486
   446
slouken@10486
   447
1. make sure the Remote Debugger is running on your ARM device, and that it's on 
slouken@10486
   448
   the same IP network as your development machine.
slouken@10486
   449
2. from Visual C++'s toolbar, find a drop-down menu that says, "Win32".  Click 
slouken@10486
   450
   it, then change the value to "ARM".
slouken@10486
   451
3. make sure Visual C++ knows the hostname or IP address of the ARM device.  To 
slouken@10486
   452
   do this:
slouken@10486
   453
    1. open the app project's properties
slouken@10486
   454
    2. select "Debugging"
slouken@10486
   455
    3. next to "Machine Name", enter the hostname or IP address of the ARM 
slouken@10486
   456
       device
slouken@10486
   457
    4. if, and only if, you've turned off authentication in the Remote Debugger,
slouken@10486
   458
       then change the setting for "Require Authentication" to No
slouken@10486
   459
    5. click "OK"
slouken@10486
   460
4. build and run the app (from Visual C++).  The first time you do this, a 
slouken@10486
   461
   prompt will show up on the ARM device, asking for a Microsoft Account.  You 
slouken@10486
   462
   do, unfortunately, need to log in here, and will need to follow the 
slouken@10486
   463
   subsequent registration steps in order to launch the app.  After you do so, 
slouken@10486
   464
   if the app didn't already launch, try relaunching it again from within Visual 
slouken@10486
   465
   C++.
slouken@10486
   466
slouken@10486
   467
slouken@10486
   468
Troubleshooting
slouken@10486
   469
---------------
slouken@10486
   470
slouken@10486
   471
#### Build fails with message, "error LNK2038: mismatch detected for 'vccorlib_lib_should_be_specified_before_msvcrt_lib_to_linker'"
slouken@10486
   472
slouken@10486
   473
Try adding the following to your linker flags.  In MSVC, this can be done by
slouken@10486
   474
right-clicking on the app project, navigating to Configuration Properties ->
slouken@10486
   475
Linker -> Command Line, then adding them to the Additional Options
slouken@10486
   476
section.
slouken@10486
   477
slouken@10486
   478
* For Release builds / MSVC-Configurations, add:
slouken@10486
   479
slouken@10486
   480
    /nodefaultlib:vccorlib /nodefaultlib:msvcrt vccorlib.lib msvcrt.lib
slouken@10486
   481
slouken@10486
   482
* For Debug builds / MSVC-Configurations, add:
slouken@10486
   483
slouken@10486
   484
    /nodefaultlib:vccorlibd /nodefaultlib:msvcrtd vccorlibd.lib msvcrtd.lib
slouken@10486
   485
slouken@10486
   486
slouken@10486
   487
#### Mouse-motion events fail to get sent, or SDL_GetMouseState() fails to return updated values
slouken@10486
   488
slouken@10486
   489
This may be caused by a bug in Windows itself, whereby hiding the mouse
slouken@10486
   490
cursor can cause mouse-position reporting to fail.
slouken@10486
   491
slouken@10486
   492
SDL provides a workaround for this, but it requires that an app links to a
slouken@10486
   493
set of Win32-style cursor image-resource files.  A copy of suitable resource
slouken@10486
   494
files can be found in `src/main/winrt/`.  Adding them to an app's Visual C++
slouken@10486
   495
project file should be sufficient to get the app to use them.
dludwig@11446
   496
dludwig@11446
   497
dludwig@11446
   498
#### SDL's Visual Studio project file fails to open, with message, "The system can't find the file specified."
dludwig@11446
   499
dludwig@11446
   500
This can be caused for any one of a few reasons, which Visual Studio can
dludwig@11446
   501
report, but won't always do so in an up-front manner.
dludwig@11446
   502
dludwig@11446
   503
To help determine why this error comes up:
dludwig@11446
   504
dludwig@11446
   505
1. open a copy of Visual Studio without opening a project file.  This can be
dludwig@11446
   506
   accomplished via Windows' Start Menu, among other means.
dludwig@11446
   507
2. show Visual Studio's Output window.  This can be done by going to VS'
dludwig@11446
   508
   menu bar, then to View, and then to Output.
dludwig@11446
   509
3. try opening the SDL project file directly by going to VS' menu bar, then
dludwig@11446
   510
   to File, then to Open, then to Project/Solution.  When a File-Open dialog
dludwig@11446
   511
   appears, open the SDL project (such as the one in SDL's source code, in its
dludwig@11446
   512
   directory, VisualC-WinRT/UWP_VS2015/).
dludwig@11446
   513
4. after attempting to open SDL's Visual Studio project file, additional error
dludwig@11446
   514
   information will be output to the Output window.
dludwig@11446
   515
dludwig@11446
   516
If Visual Studio reports (via its Output window) that the project:
dludwig@11446
   517
dludwig@11446
   518
"could not be loaded because it's missing install components. To fix this launch Visual Studio setup with the following selections:
dludwig@11446
   519
Microsoft.VisualStudio.ComponentGroup.UWP.VC"
dludwig@11446
   520
dludwig@11446
   521
... then you will need to re-launch Visual Studio's installer, and make sure that
dludwig@11446
   522
the workflow for "Universal Windows Platform development" is checked, and that its
dludwig@11446
   523
optional component, "C++ Universal Windows Platform tools" is also checked.  While
dludwig@11446
   524
you are there, if you are planning on targeting UWP / Windows 10, also make sure
dludwig@11446
   525
that you check the optional component, "Windows 10 SDK (10.0.10240.0)".  After
dludwig@11446
   526
making sure these items are checked as-appropriate, install them.
dludwig@11446
   527
dludwig@11446
   528
Once you install these components, try re-launching Visual Studio, and re-opening
dludwig@11446
   529
the SDL project file.  If you still get the error dialog, try using the Output
dludwig@11446
   530
window, again, seeing what Visual Studio says about it.
dludwig@11502
   531
dludwig@11503
   532
dludwig@11502
   533
#### Game controllers / joysticks aren't working!
dludwig@11502
   534
dludwig@11502
   535
Windows only permits certain game controllers and joysticks to work within
dludwig@11502
   536
WinRT / UWP apps.  Even if a game controller or joystick works in a Win32
dludwig@11502
   537
app, that device is not guaranteed to work inside a WinRT / UWP app.
dludwig@11502
   538
dludwig@11502
   539
According to Microsoft, "Xbox compatible controllers" should work inside
dludwig@11502
   540
UWP apps, potentially with more working in the future.  This includes, but
dludwig@11502
   541
may not be limited to, Microsoft-made Xbox controllers and USB adapters.
dludwig@11502
   542
(Source: https://social.msdn.microsoft.com/Forums/en-US/9064838b-e8c3-4c18-8a83-19bf0dfe150d/xinput-fails-to-detect-game-controllers?forum=wpdevelop)
dludwig@11502
   543
dludwig@11502
   544