docs/README-winrt.md
author David Ludwig
Sat, 29 Nov 2014 10:09:30 -0500
changeset 9247 eddb899239fe
parent 9242 f4d353bd5d16
child 9255 c2ef0d8d6da0
permissions -rw-r--r--
WinRT: bug and data-integrity fixes for SDL_GetPrefPath()

This change does a few things, all with regards to the WinRT implementation of
SDL_GetPrefPath():

1. it fixes a bug whereby SDL_GetPrefPath() did not create the directory it
returned. On other SDL platforms, SDL_GetPrefPath() will create separate
directories for its 'org' and 'app' folders. Without this, attempts to create
files in the pref-path would fail, unless those directories were first created
by the app, or by some other library the app used. This change makes sure
that these directories get created, before SDL_GetPrefPath() returns to its
caller(s).


2. it defaults to having SDL_GetPrefPath() return a WinRT 'Local' folder
on all platforms. Previously, for Windows Store apps, it would have used a
different, 'Roaming' folder. Files in Roaming folders can be automatically,
and synchronized across multiple devices by Windows. This synchronization can
happen while the app runs, with new files being copied into a running app's
pref-path. Unless an app is specifically designed to handle this scenario,
there is a chance that save-data could be overwritten in unwanted or
unexpected ways.

The default is now to use a Local folder, which does not get synchronized, and
which is arguably a bit safer to use. Apps that wish to use Roaming folders
can do so by setting SDL_HINT_WINRT_PREF_PATH_ROOT to "roaming", however it
is recommended that one first read Microsoft's documentation for Roaming
files, a link to which is provided in README-winrt.md.

To preserve older pref-path selection behavior (found in SDL 2.0.3, as well as
many pre-2.0.4 versions of SDL from hg.libsdl.org), which uses a Roaming path
in Windows Store apps, and a Local path in Windows Phone, set
SDL_HINT_WINRT_PREF_PATH_ROOT to "old".

Please note that Roaming paths are not supported on Windows Phone 8.0, due to
limitations in the OS itself. Attempts to use this will fail.
(Windows Phone 8.1 does not have this limitation, however.)


3. It makes SDL_GetPrefPath(), when on Windows Phone 8.0, and when
SDL_HINT_WINRT_PREF_PATH_ROOT is set to "roaming", return NULL, rather than
silently defaulting to a Local path (then switching to a Roaming path if and
when the user upgraded to Windows Phone 8.1).
dludwig@9139
     1
WinRT
dludwig@9139
     2
=====
dludwig@9139
     3
dludwig@9150
     4
This port allows SDL applications to run on Microsoft's platforms that require
dludwig@9150
     5
use of "Windows Runtime", aka. "WinRT", APIs.  WinRT apps are currently
dludwig@9150
     6
full-screen only, and run in what Microsoft sometimes refers to as their
dludwig@9150
     7
"Modern" (formerly, "Metro"), environment.  For Windows 8.x, Microsoft may also
dludwig@9150
     8
refer to them as "Windows Store" apps, due to them being distributed,
dludwig@9150
     9
primarily, via a Microsoft-run online store (of the same name).
dludwig@9150
    10
dludwig@9150
    11
Some of the operating systems that include WinRT, are:
dludwig@9139
    12
dludwig@9139
    13
* Windows 8.x
dludwig@9139
    14
* Windows RT 8.x (aka. Windows 8.x for ARM processors)
dludwig@9139
    15
* Windows Phone 8.x
dludwig@9139
    16
dludwig@9139
    17
dludwig@9139
    18
Requirements
dludwig@9137
    19
------------
dludwig@9139
    20
dludwig@9140
    21
* Microsoft Visual C++ (aka Visual Studio), either 2013 or 2012 versions
dludwig@9224
    22
  - Free, "Community" or "Express" editions may be used, so long as they
dludwig@9224
    23
    include  support for either "Windows Store" or "Windows Phone" apps.
dludwig@9224
    24
    "Express" versions marked as supporting "Windows Desktop" development
dludwig@9224
    25
    typically do not include support for creating WinRT apps, to note.
dludwig@9224
    26
    (The "Community" edition of Visual C++ 2013 does, however, support both
dludwig@9224
    27
    desktop/Win32 and WinRT development).
dludwig@9224
    28
  - Visual C++ 2012 can only build apps that target versions 8.0 of Windows,
dludwig@9224
    29
    or  Windows Phone.  8.0-targetted apps will run on devices running 8.1
dludwig@9224
    30
    editions of Windows, however they will not be able to take advantage of
dludwig@9140
    31
    8.1-specific features.
dludwig@9224
    32
  - Visual C++ 2013 cannot create app projects that target Windows 8.0.
dludwig@9224
    33
    Visual C++ 2013 Update 4, can create app projects for Windows Phone 8.0,
dludwig@9224
    34
    Windows Phone 8.1, and Windows 8.1, but not Windows 8.0.  An optional
dludwig@9224
    35
    Visual Studio add-in, "Tools for Maintaining Store apps for Windows 8",
dludwig@9224
    36
    allows Visual C++ 2013 to load and build Windows 8.0 projects that were
dludwig@9224
    37
    created with Visual C++ 2012, so long as Visual C++ 2012 is installed
dludwig@9224
    38
    on the same machine.  More details on targeting different versions of
dludwig@9224
    39
    Windows can found at the following web pages:
dludwig@9140
    40
      - [Develop apps by using Visual Studio 2013](http://msdn.microsoft.com/en-us/library/windows/apps/br211384.aspx)
dludwig@9140
    41
      - [To add the Tools for Maintaining Store apps for Windows 8](http://msdn.microsoft.com/en-us/library/windows/apps/dn263114.aspx#AddMaintenanceTools)
dludwig@9140
    42
* A valid Microsoft account - This requirement is not imposed by SDL, but
dludwig@9140
    43
  rather by Microsoft's Visual C++ toolchain.  This is required to launch or 
dludwig@9140
    44
  debug apps.
dludwig@9139
    45
dludwig@9139
    46
dludwig@9208
    47
Status
dludwig@9208
    48
------
dludwig@9208
    49
dludwig@9208
    50
Here is a rough list of what works, and what doens't:
dludwig@9208
    51
dludwig@9208
    52
* What works:
dludwig@9208
    53
  * compilation via Visual C++ 2012 and 2013
dludwig@9208
    54
  * compile-time platform detection for SDL programs.  The C/C++ #define,
dludwig@9208
    55
    `__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
dludwig@9208
    56
  * GPU-accelerated 2D rendering, via SDL_Renderer.
dludwig@9208
    57
  * software rendering, via either SDL_Surface (optionally in conjunction with
dludwig@9208
    58
    SDL_GetWindowSurface() and SDL_UpdateWindowSurface()) or via the
dludwig@9208
    59
    SDL_Renderer APIs
dludwig@9208
    60
  * threads.  Significant chunks of Win32's threading APIs are not available in
dludwig@9208
    61
    WinRT.  A new, SDL threading backend was built using C++11's threading APIs
dludwig@9208
    62
    (std::thread, std::mutex, std::condition_variable, etc.), which C or C++
dludwig@9208
    63
    programs alike can access via SDL's threading APIs.  Support for thread
dludwig@9208
    64
    priorities is not, however, currently available, due to restrictions in
dludwig@9208
    65
    WinRT's own API set.
dludwig@9208
    66
  * timers (via SDL_GetTicks(), SDL_AddTimer(), SDL_GetPerformanceCounter(),
dludwig@9208
    67
    SDL_GetPerformanceFrequency(), etc.)
dludwig@9208
    68
  * file I/O via SDL_RWops
dludwig@9208
    69
  * mouse input  (unsupported on Windows Phone)
dludwig@9208
    70
  * audio, via a modified version of SDL's XAudio2 backend
dludwig@9208
    71
  * .DLL file loading.  Libraries must be packaged inside applications.  Loading
dludwig@9208
    72
    anything outside of the app is not supported.
dludwig@9208
    73
  * system path retrieval via SDL's filesystem APIs
dludwig@9208
    74
  * game controllers.  Support is provided via the SDL_Joystick and
dludwig@9208
    75
    SDL_GameController APIs, and is backed by Microsoft's XInput API.
dludwig@9208
    76
  * multi-touch input
dludwig@9208
    77
  * app events.  SDL_APP_WILLENTER* and SDL_APP_DIDENTER* events get sent out as
dludwig@9208
    78
    appropriate.
dludwig@9208
    79
  * window events.  SDL_WINDOWEVENT_MINIMIZED and SDL_WINDOWEVENT_RESTORED are
dludwig@9208
    80
    sent out on app suspend and resume, respectively.  SDL_WINDOWEVENT_SHOWN and
dludwig@9208
    81
    SDL_WINDOWEVENT_HIDDEN are also sent, but not necessarily on app suspend or
dludwig@9208
    82
    resume, as WinRT treats these two concepts differently..
dludwig@9208
    83
  * using Direct3D 11.x APIs outside of SDL.  Non-XAML / Direct3D-only apps can
dludwig@9208
    84
    choose to render content directly via Direct3D, using SDL to manage the
dludwig@9208
    85
    internal WinRT window, as well as input and audio.  (Use
dludwig@9208
    86
    SDL_GetWindowWMInfo() to get the WinRT 'CoreWindow', and pass it into
dludwig@9208
    87
    IDXGIFactory2::CreateSwapChainForCoreWindow() as appropriate.)
dludwig@9208
    88
dludwig@9208
    89
* What partially works:
dludwig@9208
    90
  * keyboard input.  Most of WinRT's documented virtual keys are supported, as
dludwig@9208
    91
    well as many keys with documented hardware scancodes.
dludwig@9215
    92
  * OpenGL.  Experimental support for OpenGL ES 2 is available via the ANGLE
dludwig@9215
    93
    project, using either MS Open Technologies' repository, at 
dludwig@9215
    94
    https://github.com/msopentech/angle (both the "winrt" and "future-dev"
dludwig@9215
    95
    branches are supported), or the official ANGLE repository, at
dludwig@9215
    96
    https://chromium.googlesource.com/angle/angle
dludwig@9208
    97
  * SDLmain.  WinRT uses a different signature for each app's main() function.
dludwig@9208
    98
    SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
dludwig@9208
    99
    (in `SDL\src\main\winrt\`) directly in order for their C-style main()
dludwig@9208
   100
    functions to be called.
dludwig@9208
   101
  * XAML interoperability.  This feature is currently experimental (there are
dludwig@9208
   102
    **many** known bugs in this, at present!), preliminary, and only for
dludwig@9208
   103
    Windows 8.x/RT at the moment.  Windows Phone + XAML support is still
dludwig@9208
   104
    pending.
dludwig@9208
   105
dludwig@9208
   106
* What doesn't work:
dludwig@9208
   107
  * compilation with anything other than Visual C++ 2012 or 2013
dludwig@9208
   108
  * programmatically-created custom cursors.  These don't appear to be supported
dludwig@9208
   109
    by WinRT.  Different OS-provided cursors can, however, be created via
dludwig@9208
   110
    SDL_CreateSystemCursor() (unsupported on Windows Phone)
dludwig@9208
   111
  * SDL_WarpMouseInWindow() or SDL_WarpMouseGlobal().  This are not currently
dludwig@9208
   112
    supported by WinRT itself.
dludwig@9208
   113
  * joysticks and game controllers that aren't supported by Microsoft's XInput
dludwig@9208
   114
    API.
dludwig@9208
   115
  * probably anything else that's not listed as supported
dludwig@9208
   116
dludwig@9208
   117
dludwig@9208
   118
dludwig@9242
   119
Caveats
dludwig@9242
   120
-------
dludwig@9242
   121
dludwig@9247
   122
#### SDL_GetPrefPath() usage when upgrading existing WinRT apps to SDL 2.0.4
dludwig@9247
   123
dludwig@9247
   124
SDL 2.0.4 fixes two bugs found in SDL_GetPrefPath() which can affect
dludwig@9247
   125
an app's save data.  These bugs only apply to WinRT apps (and not
dludwig@9247
   126
Windows Desktop / Win32 apps, or to apps on any other SDL platform).
dludwig@9247
   127
In particular, for older versions of SDL (anything before 2.0.4):
dludwig@9242
   128
dludwig@9247
   129
1. SDL_GetPrefPath() would return an invalid path, one in which attempts
dludwig@9247
   130
   to write files to would fail, in many cases.  Some of the path elements
dludwig@9247
   131
   returned by SDL_GetPrefPath() would not get created (as done on other
dludwig@9247
   132
   SDL platforms).  Files could be written to this path, however apps would
dludwig@9247
   133
   need to explicitly create the missing directories first.
dludwig@9247
   134
   
dludwig@9247
   135
2. SDL_GetPrefPath() would return a path inside a WinRT 'Roaming' folder,
dludwig@9247
   136
   the contents of which could get automatically synchronized across multiple
dludwig@9247
   137
   devices, by Windows.  This process could occur while an app was running.
dludwig@9247
   138
   Apps which were not explicitly built to handle this scenario could
dludwig@9247
   139
   have their SDL_GetPrefPath-backed save data swapped out by Windows at
dludwig@9247
   140
   unexpected times, which raised potential for data-loss (if apps weren't
dludwig@9247
   141
   designed to support live file-synchronization.)
dludwig@9247
   142
dludwig@9247
   143
dludwig@9247
   144
SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
dludwig@9247
   145
dludwig@9247
   146
1. making sure that SDL_GetPrefPath() returns a directory in which data
dludwig@9247
   147
   can be written to immediately, without first needing to create directories.
dludwig@9242
   148
dludwig@9247
   149
2. basing SDL_GetPrefPath() off of a non-Roaming / 'Local' folder, the
dludwig@9247
   150
   contents of which do not get automatically synchronized across devices,
dludwig@9247
   151
   and which may be safer in terms of data-integrity.
dludwig@9247
   152
   
dludwig@9247
   153
   Apps can, at their discretion, choose to utilize WinRT's Roaming
dludwig@9247
   154
   functionality by calling the following before calling SDL_GetPrefPath():
dludwig@9247
   155
   
dludwig@9247
   156
       SDL_SetHint(SDL_HINT_WINRT_PREF_PATH_ROOT, "roaming");
dludwig@9242
   157
dludwig@9247
   158
   Alternatively, to restore SDL_GetPrefPath()'s old behavior (found in
dludwig@9247
   159
   SDL 2.0.3, and in many pre-2.0.4 versions of SDL found on hg.libsdl.org),
dludwig@9247
   160
   whereby a Roaming path is returned for Windows Store apps, and a Local
dludwig@9247
   161
   folder is returned for Windows Phone apps, use the following code:
dludwig@9247
   162
   
dludwig@9247
   163
       SDL_SetHint(SDL_HINT_WINRT_PREF_PATH_ROOT, "old");
dludwig@9247
   164
   
dludwig@9247
   165
   Before using Roaming data in any capacity, it is highly recommended that
dludwig@9247
   166
   one read the following:
dludwig@9247
   167
   
dludwig@9247
   168
   1. Microsoft's documentation on the Roaming data.  Details on this can be
dludwig@9247
   169
      found on MSDN, at:
dludwig@9247
   170
      [Guidelines for roaming app data](http://msdn.microsoft.com/en-us/library/windows/apps/hh465094.aspx).
dludwig@9247
   171
   
dludwig@9247
   172
   2. the SDL documentation for SDL_HINT_WINRT_PREF_PATH_ROOT, which is
dludwig@9247
   173
      listed inside SDL_hints.h.
dludwig@9242
   174
dludwig@9247
   175
   Please note that Roaming support is not available on Windows Phone 8.0,
dludwig@9247
   176
   due to limitations in the OS itself.  Attempts to use it will fail, with
dludwig@9247
   177
   SDL_GetPrefPath() returning NULL (if SDL_HINT_WINRT_PREF_PATH_ROOT is
dludwig@9247
   178
   set to "roaming" on that platform).  Windows Phone 8.1 does not have this
dludwig@9247
   179
   limitation, and does support Roaming data.
dludwig@9242
   180
dludwig@9242
   181
dludwig@9208
   182
dludwig@9139
   183
Setup, High-Level Steps
dludwig@9139
   184
-----------------------
dludwig@9139
   185
dludwig@9139
   186
The steps for setting up a project for an SDL/WinRT app looks like the
dludwig@9139
   187
following, at a high-level:
dludwig@9139
   188
dludwig@9139
   189
1. create a new Visual C++ project using Microsoft's template for a,
dludwig@9139
   190
   "Direct3D App".
dludwig@9139
   191
2. remove most of the files from the project.
dludwig@9139
   192
3. make your app's project directly reference SDL/WinRT's own Visual C++
dludwig@9139
   193
   project file, via use of Visual C++'s "References" dialog.  This will setup
dludwig@9139
   194
   the linker, and will copy SDL's .dll files to your app's final output.
dludwig@9139
   195
4. adjust your app's build settings, at minimum, telling it where to find SDL's
dludwig@9139
   196
   header files.
dludwig@9139
   197
5. add a file that contains a WinRT-appropriate main function.
dludwig@9139
   198
6. add SDL-specific app code.
dludwig@9139
   199
7. build and run your app.
dludwig@9139
   200
dludwig@9139
   201
dludwig@9139
   202
Setup, Detailed Steps
dludwig@9139
   203
---------------------
dludwig@9139
   204
dludwig@9139
   205
### 1. Create a new project ###
dludwig@9139
   206
dludwig@9139
   207
Create a new project using one of Visual C++'s templates for a plain, non-XAML,
dludwig@9139
   208
"Direct3D App" (XAML support for SDL/WinRT is not yet ready for use).  If you
dludwig@9139
   209
don't see one of these templates, in Visual C++'s 'New Project' dialog, try
dludwig@9139
   210
using the textbox titled, 'Search Installed Templates' to look for one.
dludwig@9139
   211
dludwig@9139
   212
dludwig@9139
   213
### 2. Remove unneeded files from the project ###
dludwig@9139
   214
dludwig@9139
   215
In the new project, delete any file that has one of the following extensions:
dludwig@9139
   216
dludwig@9139
   217
- .cpp
dludwig@9139
   218
- .h
dludwig@9139
   219
- .hlsl
dludwig@9139
   220
dludwig@9139
   221
When you are done, you should be left with a few files, each of which will be a
dludwig@9139
   222
necessary part of your app's project.  These files will consist of:
dludwig@9139
   223
dludwig@9139
   224
- an .appxmanifest file, which contains metadata on your WinRT app.  This is
dludwig@9139
   225
  similar to an Info.plist file on iOS, or an AndroidManifest.xml on Android.
dludwig@9139
   226
- a few .png files, one of which is a splash screen (displayed when your app
dludwig@9139
   227
  launches), others are app icons.
dludwig@9139
   228
- a .pfx file, used for code signing purposes.
dludwig@9139
   229
dludwig@9139
   230
dludwig@9139
   231
### 3. Add references to SDL's project files ###
dludwig@9139
   232
dludwig@9139
   233
SDL/WinRT can be built in multiple variations, spanning across three different
dludwig@9139
   234
CPU architectures (x86, x64, and ARM) and two different configurations
dludwig@9139
   235
(Debug and Release).  WinRT and Visual C++ do not currently provide a means
dludwig@9139
   236
for combining multiple variations of one library into a single file.
dludwig@9139
   237
Furthermore, it does not provide an easy means for copying pre-built .dll files
dludwig@9139
   238
into your app's final output (via Post-Build steps, for example).  It does,
dludwig@9139
   239
however, provide a system whereby an app can reference the MSVC projects of
dludwig@9139
   240
libraries such that, when the app is built:
dludwig@9139
   241
dludwig@9139
   242
1. each library gets built for the appropriate CPU architecture(s) and WinRT
dludwig@9139
   243
   platform(s).
dludwig@9139
   244
2. each library's output, such as .dll files, get copied to the app's build 
dludwig@9139
   245
   output.
dludwig@9139
   246
dludwig@9139
   247
To set this up for SDL/WinRT, you'll need to run through the following steps:
dludwig@9139
   248
dludwig@9139
   249
1. open up the Solution Explorer inside Visual C++ (under the "View" menu, then
dludwig@9139
   250
   "Solution Explorer")
dludwig@9139
   251
2. right click on your app's solution.
dludwig@9139
   252
3. navigate to "Add", then to "Existing Project..."
dludwig@9139
   253
4. find SDL/WinRT's Visual C++ project file and open it.  Different project
dludwig@9139
   254
   files exist for different WinRT platforms.  All of them are in SDL's
dludwig@9139
   255
   source distribution, in the following directories:
dludwig@9139
   256
    * `VisualC-WinRT/WinPhone80_VS2012/` - for Windows Phone 8.0 apps
dludwig@9139
   257
    * `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
dludwig@9139
   258
    * `VisualC-WinRT/WinRT80_VS2012/` - for Windows 8.0 apps
dludwig@9139
   259
    * `VisualC-WinRT/WinRT81_VS2013/` - for Windows 8.1 apps
dludwig@9139
   260
5. once the project has been added, right-click on your app's project and
dludwig@9139
   261
   select, "References..."
dludwig@9139
   262
6. click on the button titled, "Add New Reference..."
dludwig@9139
   263
7. check the box next to SDL
dludwig@9139
   264
8. click OK to close the dialog
dludwig@9139
   265
9. SDL will now show up in the list of references.  Click OK to close that
dludwig@9139
   266
   dialog.
dludwig@9139
   267
dludwig@9139
   268
Your project is now linked to SDL's project, insofar that when the app is
dludwig@9139
   269
built, SDL will be built as well, with its build output getting included with
dludwig@9139
   270
your app.
dludwig@9139
   271
dludwig@9139
   272
dludwig@9139
   273
### 4. Adjust Your App's Build Settings ###
dludwig@9139
   274
dludwig@9139
   275
Some build settings need to be changed in your app's project.  This guide will
dludwig@9139
   276
outline the following:
dludwig@9139
   277
dludwig@9139
   278
- making sure that the compiler knows where to find SDL's header files
dludwig@9149
   279
- **Optional for C++, but NECESSARY for compiling C code:** telling the
dludwig@9139
   280
  compiler not to use Microsoft's C++ extensions for WinRT development.
dludwig@9149
   281
- **Optional:** telling the compiler not generate errors due to missing
dludwig@9139
   282
  precompiled header files.
dludwig@9139
   283
dludwig@9139
   284
To change these settings:
dludwig@9139
   285
dludwig@9139
   286
1. right-click on the project
dludwig@9139
   287
2. choose "Properties"
dludwig@9139
   288
3. in the drop-down box next to "Configuration", choose, "All Configurations"
dludwig@9139
   289
4. in the drop-down box next to "Platform", choose, "All Platforms"
dludwig@9139
   290
5. in the left-hand list, expand the "C/C++" section
dludwig@9139
   291
6. select "General"
dludwig@9139
   292
7. edit the "Additional Include Directories" setting, and add a path to SDL's
dludwig@9139
   293
   "include" directory
dludwig@9149
   294
8. **Optional: to enable compilation of C code:** change the setting for
dludwig@9139
   295
   "Consume Windows Runtime Extension" from "Yes (/ZW)" to "No".  If you're 
dludwig@9139
   296
   working with a completely C++ based project, this step can usually be 
dludwig@9139
   297
   omitted.
dludwig@9149
   298
9. **Optional: to disable precompiled headers (which can produce 
dludwig@9149
   299
   'stdafx.h'-related build errors, if setup incorrectly:** in the left-hand 
dludwig@9139
   300
   list, select "Precompiled Headers", then change the setting for "Precompiled 
dludwig@9139
   301
   Header" from "Use (/Yu)" to "Not Using Precompiled Headers".
dludwig@9139
   302
10. close the dialog, saving settings, by clicking the "OK" button
dludwig@9139
   303
dludwig@9139
   304
dludwig@9139
   305
### 5. Add a WinRT-appropriate main function to the app. ###
dludwig@9139
   306
dludwig@9139
   307
C/C++-based WinRT apps do contain a `main` function that the OS will invoke when 
dludwig@9139
   308
the app starts launching. The parameters of WinRT main functions are different 
dludwig@9139
   309
than those found on other platforms, Win32 included.  SDL/WinRT provides a 
dludwig@9139
   310
platform-appropriate main function that will perform these actions, setup key 
dludwig@9139
   311
portions of the app, then invoke a classic, C/C++-style main function (that take 
dludwig@9139
   312
in "argc" and "argv" parameters).  The code for this file is contained inside 
dludwig@9139
   313
SDL's source distribution, under `src/main/winrt/SDL_winrt_main_NonXAML.cpp`.  
dludwig@9139
   314
You'll need to add this file, or a copy of it, to your app's project, and make 
dludwig@9139
   315
sure it gets compiled using a Microsoft-specific set of C++ extensions called 
dludwig@9139
   316
C++/CX.
dludwig@9139
   317
dludwig@9149
   318
**NOTE: C++/CX compilation is currently required in at least one file of your 
dludwig@9139
   319
app's project.  This is to make sure that Visual C++'s linker builds a 'Windows 
dludwig@9149
   320
Metadata' file (.winmd) for your app.  Not doing so can lead to build errors.**
dludwig@9139
   321
dludwig@9139
   322
To include `SDL_winrt_main_NonXAML.cpp`:
dludwig@9139
   323
dludwig@9139
   324
1. right-click on your project (again, in Visual C++'s Solution Explorer), 
dludwig@9139
   325
   navigate to "Add", then choose "Existing Item...".
dludwig@9139
   326
2. open `SDL_winrt_main_NonXAML.cpp`, which is found inside SDL's source 
dludwig@9139
   327
   distribution, under `src/main/winrt/`.  Make sure that the open-file dialog 
dludwig@9139
   328
   closes, either by double-clicking on the file, or single-clicking on it and 
dludwig@9139
   329
   then clicking Add.
dludwig@9139
   330
3. right-click on the file (as listed in your project), then click on 
dludwig@9139
   331
   "Properties...".
dludwig@9139
   332
4. in the drop-down box next to "Configuration", choose, "All Configurations"
dludwig@9139
   333
5. in the drop-down box next to "Platform", choose, "All Platforms"
dludwig@9139
   334
6. in the left-hand list, click on "C/C++"
dludwig@9139
   335
7. change the setting for "Consume Windows Runtime Extension" to "Yes (/ZW)".
dludwig@9139
   336
8. click the OK button.  This will close the dialog.
dludwig@9139
   337
dludwig@9139
   338
dludwig@9139
   339
### 6. Add app code and assets ###
dludwig@9139
   340
dludwig@9139
   341
At this point, you can add in SDL-specific source code.  Be sure to include a 
dludwig@9139
   342
C-style main function (ie: `int main(int argc, char *argv[])`).  From there you 
dludwig@9139
   343
should be able to create a single `SDL_Window` (WinRT apps can only have one 
dludwig@9139
   344
window, at present), as well as an `SDL_Renderer`.  Direct3D will be used to 
dludwig@9139
   345
draw content.  Events are received via SDL's usual event functions 
dludwig@9139
   346
(`SDL_PollEvent`, etc.)  If you have a set of existing source files and assets, 
dludwig@9139
   347
you can start adding them to the project now.  If not, or if you would like to 
dludwig@9139
   348
make sure that you're setup correctly, some short and simple sample code is 
dludwig@9139
   349
provided below.
dludwig@9139
   350
dludwig@9139
   351
dludwig@9139
   352
#### 6.A. ... when creating a new app ####
dludwig@9139
   353
dludwig@9139
   354
If you are creating a new app (rather than porting an existing SDL-based app), 
dludwig@9139
   355
or if you would just like a simple app to test SDL/WinRT with before trying to 
dludwig@9139
   356
get existing code working, some working SDL/WinRT code is provided below.  To 
dludwig@9139
   357
set this up:
dludwig@9139
   358
dludwig@9139
   359
1. right click on your app's project
dludwig@9139
   360
2. select Add, then New Item.  An "Add New Item" dialog will show up.
dludwig@9139
   361
3. from the left-hand list, choose "Visual C++"
dludwig@9139
   362
4. from the middle/main list, choose "C++ File (.cpp)"
dludwig@9139
   363
5. near the bottom of the dialog, next to "Name:", type in a name for your 
dludwig@9139
   364
source file, such as, "main.cpp".
dludwig@9139
   365
6. click on the Add button.  This will close the dialog, add the new file to 
dludwig@9139
   366
your project, and open the file in Visual C++'s text editor.
philipp@9143
   367
7. Copy and paste the following code into the new file, then save it.
dludwig@9139
   368
dludwig@9139
   369
philipp@9143
   370
    #include <SDL.h>
dludwig@9139
   371
    
philipp@9143
   372
    int main(int argc, char **argv)
philipp@9143
   373
    {
philipp@9143
   374
        SDL_DisplayMode mode;
philipp@9143
   375
        SDL_Window * window = NULL;
philipp@9143
   376
        SDL_Renderer * renderer = NULL;
philipp@9143
   377
        SDL_Event evt;
philipp@9143
   378
    
philipp@9143
   379
        if (SDL_Init(SDL_INIT_VIDEO) != 0) {
philipp@9143
   380
            return 1;
philipp@9143
   381
        }
dludwig@9139
   382
    
philipp@9143
   383
        if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
philipp@9143
   384
            return 1;
philipp@9143
   385
        }
dludwig@9139
   386
    
philipp@9143
   387
        if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
philipp@9143
   388
            return 1;
philipp@9143
   389
        }
dludwig@9139
   390
    
philipp@9143
   391
        while (1) {
philipp@9143
   392
            while (SDL_PollEvent(&evt)) {
philipp@9143
   393
            }
philipp@9143
   394
    
philipp@9143
   395
            SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
philipp@9143
   396
            SDL_RenderClear(renderer);
philipp@9143
   397
            SDL_RenderPresent(renderer);
dludwig@9139
   398
        }
dludwig@9139
   399
    }
dludwig@9139
   400
dludwig@9139
   401
dludwig@9139
   402
#### 6.B. Adding code and assets ####
dludwig@9139
   403
dludwig@9139
   404
If you have existing code and assets that you'd like to add, you should be able 
dludwig@9139
   405
to add them now.  The process for adding a set of files is as such.
dludwig@9139
   406
dludwig@9139
   407
1. right click on the app's project
dludwig@9139
   408
2. select Add, then click on "New Item..."
dludwig@9139
   409
3. open any source, header, or asset files as appropriate.  Support for C and 
dludwig@9139
   410
C++ is available.
dludwig@9139
   411
dludwig@9139
   412
Do note that WinRT only supports a subset of the APIs that are available to 
dludwig@9139
   413
Win32-based apps.  Many portions of the Win32 API and the C runtime are not 
dludwig@9139
   414
available.
dludwig@9139
   415
dludwig@9139
   416
A list of unsupported C APIs can be found at 
dludwig@9139
   417
<http://msdn.microsoft.com/en-us/library/windows/apps/jj606124.aspx>
dludwig@9139
   418
dludwig@9139
   419
General information on using the C runtime in WinRT can be found at 
dludwig@9139
   420
<http://msdn.microsoft.com/en-us/LIBRARY/hh972425(v=vs.110).aspx>
dludwig@9139
   421
dludwig@9139
   422
A list of supported Win32 APIs for Windows 8/RT apps can be found at 
dludwig@9139
   423
<http://msdn.microsoft.com/en-us/library/windows/apps/br205757.aspx>.  To note, 
dludwig@9139
   424
the list of supported Win32 APIs for Windows Phone 8 development is different.  
dludwig@9139
   425
That list can be found at 
dludwig@9139
   426
<http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj662956(v=vs.105).aspx>
dludwig@9139
   427
dludwig@9139
   428
dludwig@9139
   429
### 7. Build and run your app ###
dludwig@9139
   430
dludwig@9139
   431
Your app project should now be setup, and you should be ready to build your app.  
dludwig@9139
   432
To run it on the local machine, open the Debug menu and choose "Start 
dludwig@9139
   433
Debugging".  This will build your app, then run your app full-screen.  To switch 
dludwig@9139
   434
out of your app, press the Windows key.  Alternatively, you can choose to run 
dludwig@9139
   435
your app in a window.  To do this, before building and running your app, find 
dludwig@9139
   436
the drop-down menu in Visual C++'s toolbar that says, "Local Machine".  Expand 
dludwig@9139
   437
this by clicking on the arrow on the right side of the list, then click on 
dludwig@9139
   438
Simulator.  Once you do that, any time you build and run the app, the app will 
dludwig@9139
   439
launch in window, rather than full-screen.
dludwig@9139
   440
dludwig@9139
   441
dludwig@9139
   442
#### 7.A. Running apps on ARM-based devices ####
dludwig@9139
   443
dludwig@9139
   444
To build and run the app on ARM-based, "Windows RT" devices, you'll need to:
dludwig@9139
   445
dludwig@9139
   446
- install Microsoft's "Remote Debugger" on the device.  Visual C++ installs and 
dludwig@9139
   447
  debugs ARM-based apps via IP networks.
dludwig@9139
   448
- change a few options on the development machine, both to make sure it builds 
dludwig@9139
   449
  for ARM (rather than x86 or x64), and to make sure it knows how to find the 
dludwig@9139
   450
  Windows RT device (on the network).
dludwig@9139
   451
dludwig@9139
   452
Microsoft's Remote Debugger can be found at 
dludwig@9139
   453
<http://msdn.microsoft.com/en-us/library/vstudio/bt727f1t.aspx>.  Please note 
dludwig@9139
   454
that separate versions of this debugger exist for different versions of Visual 
dludwig@9139
   455
C++, one for debugging with MSVC 2012, another for debugging with MSVC 2013.
dludwig@9139
   456
dludwig@9139
   457
To setup Visual C++ to launch your app on an ARM device:
dludwig@9139
   458
dludwig@9139
   459
1. make sure the Remote Debugger is running on your ARM device, and that it's on 
dludwig@9139
   460
   the same IP network as your development machine.
dludwig@9139
   461
2. from Visual C++'s toolbar, find a drop-down menu that says, "Win32".  Click 
dludwig@9139
   462
   it, then change the value to "ARM".
dludwig@9139
   463
3. make sure Visual C++ knows the hostname or IP address of the ARM device.  To 
dludwig@9139
   464
   do this:
dludwig@9139
   465
    1. open the app project's properties
dludwig@9139
   466
    2. select "Debugging"
dludwig@9139
   467
    3. next to "Machine Name", enter the hostname or IP address of the ARM 
dludwig@9139
   468
       device
dludwig@9209
   469
    4. if, and only if, you've turned off authentication in the Remote Debugger,
dludwig@9209
   470
       then change the setting for "Require Authentication" to No
dludwig@9139
   471
    5. click "OK"
dludwig@9139
   472
4. build and run the app (from Visual C++).  The first time you do this, a 
dludwig@9139
   473
   prompt will show up on the ARM device, asking for a Microsoft Account.  You 
dludwig@9139
   474
   do, unfortunately, need to log in here, and will need to follow the 
dludwig@9139
   475
   subsequent registration steps in order to launch the app.  After you do so, 
dludwig@9139
   476
   if the app didn't already launch, try relaunching it again from within Visual 
dludwig@9139
   477
   C++.
dludwig@9139
   478
dludwig@9139
   479
dludwig@9200
   480
Troubleshooting
dludwig@9200
   481
---------------
dludwig@9200
   482
dludwig@9200
   483
#### Build fails with message, "error LNK2038: mismatch detected for 'vccorlib_lib_should_be_specified_before_msvcrt_lib_to_linker'"
dludwig@9200
   484
dludwig@9200
   485
Try adding the following to your linker flags.  In MSVC, this can be done by
dludwig@9200
   486
right-clicking on the app project, navigating to Configuration Properties ->
dludwig@9200
   487
Linker -> Command Line, then adding them to the Additional Options
dludwig@9200
   488
section.
dludwig@9200
   489
dludwig@9200
   490
* For Release builds / MSVC-Configurations, add:
dludwig@9200
   491
dludwig@9200
   492
    /nodefaultlib:vccorlib /nodefaultlib:msvcrt vccorlib.lib msvcrt.lib
dludwig@9200
   493
dludwig@9200
   494
* For Debug builds / MSVC-Configurations, add:
dludwig@9200
   495
dludwig@9200
   496
    /nodefaultlib:vccorlibd /nodefaultlib:msvcrtd vccorlibd.lib msvcrtd.lib
dludwig@9200
   497