docs/README-winrt.md
author Philipp Wiesemann <philipp.wiesemann@arcor.de>
Thu, 21 May 2015 21:25:14 +0200
changeset 9609 897b25f560d0
parent 9390 afd88e715bd7
child 9931 0bb3dd1c95f2
permissions -rw-r--r--
Fixed undefined key access in test program.
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@9390
    93
    project, using either:
dludwig@9390
    94
    * MS Open Technologies' "ms-master" repository, at https://github.com/MSOpenTech/angle
dludwig@9390
    95
      (for use with Windows 8.1+ or Windows Phone 8.1+)
dludwig@9390
    96
    * MS Open Technologies' "angle-win8.0" repository, at https://github.com/MSOpenTech/angle-win8.0
dludwig@9390
    97
      (for Windows 8.0 only!)
dludwig@9390
    98
    * Google's main ANGLE repository, at https://chromium.googlesource.com/angle/angle
dludwig@9208
    99
  * SDLmain.  WinRT uses a different signature for each app's main() function.
dludwig@9208
   100
    SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
dludwig@9208
   101
    (in `SDL\src\main\winrt\`) directly in order for their C-style main()
dludwig@9208
   102
    functions to be called.
dludwig@9208
   103
  * XAML interoperability.  This feature is currently experimental (there are
dludwig@9208
   104
    **many** known bugs in this, at present!), preliminary, and only for
dludwig@9208
   105
    Windows 8.x/RT at the moment.  Windows Phone + XAML support is still
dludwig@9208
   106
    pending.
dludwig@9208
   107
dludwig@9208
   108
* What doesn't work:
dludwig@9208
   109
  * compilation with anything other than Visual C++ 2012 or 2013
dludwig@9208
   110
  * programmatically-created custom cursors.  These don't appear to be supported
dludwig@9208
   111
    by WinRT.  Different OS-provided cursors can, however, be created via
dludwig@9208
   112
    SDL_CreateSystemCursor() (unsupported on Windows Phone)
dludwig@9208
   113
  * SDL_WarpMouseInWindow() or SDL_WarpMouseGlobal().  This are not currently
dludwig@9208
   114
    supported by WinRT itself.
dludwig@9208
   115
  * joysticks and game controllers that aren't supported by Microsoft's XInput
dludwig@9208
   116
    API.
dludwig@9335
   117
  * turning off VSync when rendering on Windows Phone.  Attempts to turn VSync
dludwig@9335
   118
    off on Windows Phone result either in Direct3D not drawing anything, or it
dludwig@9335
   119
    forcing VSync back on.  As such, SDL_RENDERER_PRESENTVSYNC will always get
dludwig@9335
   120
    turned-on on Windows Phone.  This limitation is not present in non-Phone
dludwig@9335
   121
    WinRT (such as Windows 8.x), where turning off VSync appears to work.
dludwig@9208
   122
  * probably anything else that's not listed as supported
dludwig@9208
   123
dludwig@9208
   124
dludwig@9208
   125
dludwig@9255
   126
Upgrade Notes
dludwig@9255
   127
-------------
dludwig@9242
   128
dludwig@9255
   129
#### SDL_GetPrefPath() usage when upgrading WinRT apps from SDL 2.0.3
dludwig@9242
   130
dludwig@9255
   131
SDL 2.0.4 fixes two bugs found in the WinRT version of SDL_GetPrefPath().
dludwig@9255
   132
The fixes may affect older, SDL 2.0.3-based apps' save data.  Please note
dludwig@9255
   133
that these changes only apply to SDL-based WinRT apps, and not to apps for
dludwig@9255
   134
any other platform.
dludwig@9242
   135
dludwig@9255
   136
1. SDL_GetPrefPath() would return an invalid path, one in which the path's
dludwig@9255
   137
   directory had not been created.  Attempts to create files there
dludwig@9255
   138
   (via fopen(), for example), would fail, unless that directory was
dludwig@9255
   139
   explicitly created beforehand.
dludwig@9255
   140
dludwig@9255
   141
2. SDL_GetPrefPath(), for non-WinPhone-based apps, would return a path inside
dludwig@9255
   142
   a WinRT 'Roaming' folder, the contents of which get automatically
dludwig@9255
   143
   synchronized across multiple devices.  This process can occur while an
dludwig@9255
   144
   application runs, and can cause existing save-data to be overwritten
dludwig@9255
   145
   at unexpected times, with data from other devices.  (Windows Phone apps
dludwig@9255
   146
   written with SDL 2.0.3 did not utilize a Roaming folder, due to API
dludwig@9255
   147
   restrictions in Windows Phone 8.0).
dludwig@9242
   148
dludwig@9242
   149
dludwig@9247
   150
SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
dludwig@9247
   151
dludwig@9247
   152
1. making sure that SDL_GetPrefPath() returns a directory in which data
dludwig@9247
   153
   can be written to immediately, without first needing to create directories.
dludwig@9247
   154
dludwig@9255
   155
2. basing SDL_GetPrefPath() off of a different, non-Roaming folder, the
dludwig@9255
   156
   contents of which do not automatically get synchronized across devices
dludwig@9255
   157
   (and which require less work to use safely, in terms of data integrity).
dludwig@9247
   158
dludwig@9255
   159
Apps that wish to get their Roaming folder's path can do so either by using
dludwig@9255
   160
SDL_WinRTGetFSPathUTF8(), SDL_WinRTGetFSPathUNICODE() (which returns a
dludwig@9255
   161
UCS-2/wide-char string), or directly through the WinRT class,
dludwig@9255
   162
Windows.Storage.ApplicationData.
dludwig@9242
   163
dludwig@9242
   164
dludwig@9208
   165
dludwig@9139
   166
Setup, High-Level Steps
dludwig@9139
   167
-----------------------
dludwig@9139
   168
dludwig@9139
   169
The steps for setting up a project for an SDL/WinRT app looks like the
dludwig@9139
   170
following, at a high-level:
dludwig@9139
   171
dludwig@9139
   172
1. create a new Visual C++ project using Microsoft's template for a,
dludwig@9139
   173
   "Direct3D App".
dludwig@9139
   174
2. remove most of the files from the project.
dludwig@9139
   175
3. make your app's project directly reference SDL/WinRT's own Visual C++
dludwig@9139
   176
   project file, via use of Visual C++'s "References" dialog.  This will setup
dludwig@9139
   177
   the linker, and will copy SDL's .dll files to your app's final output.
dludwig@9139
   178
4. adjust your app's build settings, at minimum, telling it where to find SDL's
dludwig@9139
   179
   header files.
dludwig@9139
   180
5. add a file that contains a WinRT-appropriate main function.
dludwig@9139
   181
6. add SDL-specific app code.
dludwig@9139
   182
7. build and run your app.
dludwig@9139
   183
dludwig@9139
   184
dludwig@9139
   185
Setup, Detailed Steps
dludwig@9139
   186
---------------------
dludwig@9139
   187
dludwig@9139
   188
### 1. Create a new project ###
dludwig@9139
   189
dludwig@9139
   190
Create a new project using one of Visual C++'s templates for a plain, non-XAML,
dludwig@9139
   191
"Direct3D App" (XAML support for SDL/WinRT is not yet ready for use).  If you
dludwig@9139
   192
don't see one of these templates, in Visual C++'s 'New Project' dialog, try
dludwig@9139
   193
using the textbox titled, 'Search Installed Templates' to look for one.
dludwig@9139
   194
dludwig@9139
   195
dludwig@9139
   196
### 2. Remove unneeded files from the project ###
dludwig@9139
   197
dludwig@9139
   198
In the new project, delete any file that has one of the following extensions:
dludwig@9139
   199
dludwig@9139
   200
- .cpp
dludwig@9139
   201
- .h
dludwig@9139
   202
- .hlsl
dludwig@9139
   203
dludwig@9139
   204
When you are done, you should be left with a few files, each of which will be a
dludwig@9139
   205
necessary part of your app's project.  These files will consist of:
dludwig@9139
   206
dludwig@9139
   207
- an .appxmanifest file, which contains metadata on your WinRT app.  This is
dludwig@9139
   208
  similar to an Info.plist file on iOS, or an AndroidManifest.xml on Android.
dludwig@9139
   209
- a few .png files, one of which is a splash screen (displayed when your app
dludwig@9139
   210
  launches), others are app icons.
dludwig@9139
   211
- a .pfx file, used for code signing purposes.
dludwig@9139
   212
dludwig@9139
   213
dludwig@9139
   214
### 3. Add references to SDL's project files ###
dludwig@9139
   215
dludwig@9139
   216
SDL/WinRT can be built in multiple variations, spanning across three different
dludwig@9139
   217
CPU architectures (x86, x64, and ARM) and two different configurations
dludwig@9139
   218
(Debug and Release).  WinRT and Visual C++ do not currently provide a means
dludwig@9139
   219
for combining multiple variations of one library into a single file.
dludwig@9139
   220
Furthermore, it does not provide an easy means for copying pre-built .dll files
dludwig@9139
   221
into your app's final output (via Post-Build steps, for example).  It does,
dludwig@9139
   222
however, provide a system whereby an app can reference the MSVC projects of
dludwig@9139
   223
libraries such that, when the app is built:
dludwig@9139
   224
dludwig@9139
   225
1. each library gets built for the appropriate CPU architecture(s) and WinRT
dludwig@9139
   226
   platform(s).
dludwig@9139
   227
2. each library's output, such as .dll files, get copied to the app's build 
dludwig@9139
   228
   output.
dludwig@9139
   229
dludwig@9139
   230
To set this up for SDL/WinRT, you'll need to run through the following steps:
dludwig@9139
   231
dludwig@9139
   232
1. open up the Solution Explorer inside Visual C++ (under the "View" menu, then
dludwig@9139
   233
   "Solution Explorer")
dludwig@9139
   234
2. right click on your app's solution.
dludwig@9139
   235
3. navigate to "Add", then to "Existing Project..."
dludwig@9139
   236
4. find SDL/WinRT's Visual C++ project file and open it.  Different project
dludwig@9139
   237
   files exist for different WinRT platforms.  All of them are in SDL's
dludwig@9139
   238
   source distribution, in the following directories:
dludwig@9139
   239
    * `VisualC-WinRT/WinPhone80_VS2012/` - for Windows Phone 8.0 apps
dludwig@9139
   240
    * `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
dludwig@9139
   241
    * `VisualC-WinRT/WinRT80_VS2012/` - for Windows 8.0 apps
dludwig@9139
   242
    * `VisualC-WinRT/WinRT81_VS2013/` - for Windows 8.1 apps
dludwig@9139
   243
5. once the project has been added, right-click on your app's project and
dludwig@9139
   244
   select, "References..."
dludwig@9139
   245
6. click on the button titled, "Add New Reference..."
dludwig@9139
   246
7. check the box next to SDL
dludwig@9139
   247
8. click OK to close the dialog
dludwig@9139
   248
9. SDL will now show up in the list of references.  Click OK to close that
dludwig@9139
   249
   dialog.
dludwig@9139
   250
dludwig@9139
   251
Your project is now linked to SDL's project, insofar that when the app is
dludwig@9139
   252
built, SDL will be built as well, with its build output getting included with
dludwig@9139
   253
your app.
dludwig@9139
   254
dludwig@9139
   255
dludwig@9139
   256
### 4. Adjust Your App's Build Settings ###
dludwig@9139
   257
dludwig@9139
   258
Some build settings need to be changed in your app's project.  This guide will
dludwig@9139
   259
outline the following:
dludwig@9139
   260
dludwig@9139
   261
- making sure that the compiler knows where to find SDL's header files
dludwig@9149
   262
- **Optional for C++, but NECESSARY for compiling C code:** telling the
dludwig@9139
   263
  compiler not to use Microsoft's C++ extensions for WinRT development.
dludwig@9149
   264
- **Optional:** telling the compiler not generate errors due to missing
dludwig@9139
   265
  precompiled header files.
dludwig@9139
   266
dludwig@9139
   267
To change these settings:
dludwig@9139
   268
dludwig@9139
   269
1. right-click on the project
dludwig@9139
   270
2. choose "Properties"
dludwig@9139
   271
3. in the drop-down box next to "Configuration", choose, "All Configurations"
dludwig@9139
   272
4. in the drop-down box next to "Platform", choose, "All Platforms"
dludwig@9139
   273
5. in the left-hand list, expand the "C/C++" section
dludwig@9139
   274
6. select "General"
dludwig@9139
   275
7. edit the "Additional Include Directories" setting, and add a path to SDL's
dludwig@9139
   276
   "include" directory
dludwig@9149
   277
8. **Optional: to enable compilation of C code:** change the setting for
dludwig@9139
   278
   "Consume Windows Runtime Extension" from "Yes (/ZW)" to "No".  If you're 
dludwig@9139
   279
   working with a completely C++ based project, this step can usually be 
dludwig@9139
   280
   omitted.
dludwig@9149
   281
9. **Optional: to disable precompiled headers (which can produce 
dludwig@9149
   282
   'stdafx.h'-related build errors, if setup incorrectly:** in the left-hand 
dludwig@9139
   283
   list, select "Precompiled Headers", then change the setting for "Precompiled 
dludwig@9139
   284
   Header" from "Use (/Yu)" to "Not Using Precompiled Headers".
dludwig@9139
   285
10. close the dialog, saving settings, by clicking the "OK" button
dludwig@9139
   286
dludwig@9139
   287
dludwig@9139
   288
### 5. Add a WinRT-appropriate main function to the app. ###
dludwig@9139
   289
dludwig@9139
   290
C/C++-based WinRT apps do contain a `main` function that the OS will invoke when 
dludwig@9139
   291
the app starts launching. The parameters of WinRT main functions are different 
dludwig@9139
   292
than those found on other platforms, Win32 included.  SDL/WinRT provides a 
dludwig@9139
   293
platform-appropriate main function that will perform these actions, setup key 
dludwig@9139
   294
portions of the app, then invoke a classic, C/C++-style main function (that take 
dludwig@9139
   295
in "argc" and "argv" parameters).  The code for this file is contained inside 
dludwig@9139
   296
SDL's source distribution, under `src/main/winrt/SDL_winrt_main_NonXAML.cpp`.  
dludwig@9139
   297
You'll need to add this file, or a copy of it, to your app's project, and make 
dludwig@9139
   298
sure it gets compiled using a Microsoft-specific set of C++ extensions called 
dludwig@9139
   299
C++/CX.
dludwig@9139
   300
dludwig@9149
   301
**NOTE: C++/CX compilation is currently required in at least one file of your 
dludwig@9139
   302
app's project.  This is to make sure that Visual C++'s linker builds a 'Windows 
dludwig@9149
   303
Metadata' file (.winmd) for your app.  Not doing so can lead to build errors.**
dludwig@9139
   304
dludwig@9139
   305
To include `SDL_winrt_main_NonXAML.cpp`:
dludwig@9139
   306
dludwig@9139
   307
1. right-click on your project (again, in Visual C++'s Solution Explorer), 
dludwig@9139
   308
   navigate to "Add", then choose "Existing Item...".
dludwig@9139
   309
2. open `SDL_winrt_main_NonXAML.cpp`, which is found inside SDL's source 
dludwig@9139
   310
   distribution, under `src/main/winrt/`.  Make sure that the open-file dialog 
dludwig@9139
   311
   closes, either by double-clicking on the file, or single-clicking on it and 
dludwig@9139
   312
   then clicking Add.
dludwig@9139
   313
3. right-click on the file (as listed in your project), then click on 
dludwig@9139
   314
   "Properties...".
dludwig@9139
   315
4. in the drop-down box next to "Configuration", choose, "All Configurations"
dludwig@9139
   316
5. in the drop-down box next to "Platform", choose, "All Platforms"
dludwig@9139
   317
6. in the left-hand list, click on "C/C++"
dludwig@9139
   318
7. change the setting for "Consume Windows Runtime Extension" to "Yes (/ZW)".
dludwig@9139
   319
8. click the OK button.  This will close the dialog.
dludwig@9139
   320
dludwig@9139
   321
dludwig@9139
   322
### 6. Add app code and assets ###
dludwig@9139
   323
dludwig@9139
   324
At this point, you can add in SDL-specific source code.  Be sure to include a 
dludwig@9139
   325
C-style main function (ie: `int main(int argc, char *argv[])`).  From there you 
dludwig@9139
   326
should be able to create a single `SDL_Window` (WinRT apps can only have one 
dludwig@9139
   327
window, at present), as well as an `SDL_Renderer`.  Direct3D will be used to 
dludwig@9139
   328
draw content.  Events are received via SDL's usual event functions 
dludwig@9139
   329
(`SDL_PollEvent`, etc.)  If you have a set of existing source files and assets, 
dludwig@9139
   330
you can start adding them to the project now.  If not, or if you would like to 
dludwig@9139
   331
make sure that you're setup correctly, some short and simple sample code is 
dludwig@9139
   332
provided below.
dludwig@9139
   333
dludwig@9139
   334
dludwig@9139
   335
#### 6.A. ... when creating a new app ####
dludwig@9139
   336
dludwig@9139
   337
If you are creating a new app (rather than porting an existing SDL-based app), 
dludwig@9139
   338
or if you would just like a simple app to test SDL/WinRT with before trying to 
dludwig@9139
   339
get existing code working, some working SDL/WinRT code is provided below.  To 
dludwig@9139
   340
set this up:
dludwig@9139
   341
dludwig@9139
   342
1. right click on your app's project
dludwig@9139
   343
2. select Add, then New Item.  An "Add New Item" dialog will show up.
dludwig@9139
   344
3. from the left-hand list, choose "Visual C++"
dludwig@9139
   345
4. from the middle/main list, choose "C++ File (.cpp)"
dludwig@9139
   346
5. near the bottom of the dialog, next to "Name:", type in a name for your 
dludwig@9139
   347
source file, such as, "main.cpp".
dludwig@9139
   348
6. click on the Add button.  This will close the dialog, add the new file to 
dludwig@9139
   349
your project, and open the file in Visual C++'s text editor.
philipp@9143
   350
7. Copy and paste the following code into the new file, then save it.
dludwig@9139
   351
dludwig@9139
   352
philipp@9143
   353
    #include <SDL.h>
dludwig@9139
   354
    
philipp@9143
   355
    int main(int argc, char **argv)
philipp@9143
   356
    {
philipp@9143
   357
        SDL_DisplayMode mode;
philipp@9143
   358
        SDL_Window * window = NULL;
philipp@9143
   359
        SDL_Renderer * renderer = NULL;
philipp@9143
   360
        SDL_Event evt;
philipp@9143
   361
    
philipp@9143
   362
        if (SDL_Init(SDL_INIT_VIDEO) != 0) {
philipp@9143
   363
            return 1;
philipp@9143
   364
        }
philipp@9143
   365
    
philipp@9143
   366
        if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
philipp@9143
   367
            return 1;
philipp@9143
   368
        }
philipp@9143
   369
    
philipp@9143
   370
        if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
philipp@9143
   371
            return 1;
philipp@9143
   372
        }
philipp@9143
   373
    
philipp@9143
   374
        while (1) {
philipp@9143
   375
            while (SDL_PollEvent(&evt)) {
philipp@9143
   376
            }
philipp@9143
   377
    
philipp@9143
   378
            SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
philipp@9143
   379
            SDL_RenderClear(renderer);
philipp@9143
   380
            SDL_RenderPresent(renderer);
philipp@9143
   381
        }
dludwig@9139
   382
    }
dludwig@9139
   383
dludwig@9139
   384
dludwig@9139
   385
#### 6.B. Adding code and assets ####
dludwig@9139
   386
dludwig@9139
   387
If you have existing code and assets that you'd like to add, you should be able 
dludwig@9139
   388
to add them now.  The process for adding a set of files is as such.
dludwig@9139
   389
dludwig@9139
   390
1. right click on the app's project
dludwig@9139
   391
2. select Add, then click on "New Item..."
dludwig@9139
   392
3. open any source, header, or asset files as appropriate.  Support for C and 
dludwig@9139
   393
C++ is available.
dludwig@9139
   394
dludwig@9139
   395
Do note that WinRT only supports a subset of the APIs that are available to 
dludwig@9139
   396
Win32-based apps.  Many portions of the Win32 API and the C runtime are not 
dludwig@9139
   397
available.
dludwig@9139
   398
dludwig@9139
   399
A list of unsupported C APIs can be found at 
dludwig@9139
   400
<http://msdn.microsoft.com/en-us/library/windows/apps/jj606124.aspx>
dludwig@9139
   401
dludwig@9139
   402
General information on using the C runtime in WinRT can be found at 
dludwig@9139
   403
<http://msdn.microsoft.com/en-us/LIBRARY/hh972425(v=vs.110).aspx>
dludwig@9139
   404
dludwig@9139
   405
A list of supported Win32 APIs for Windows 8/RT apps can be found at 
dludwig@9139
   406
<http://msdn.microsoft.com/en-us/library/windows/apps/br205757.aspx>.  To note, 
dludwig@9139
   407
the list of supported Win32 APIs for Windows Phone 8 development is different.  
dludwig@9139
   408
That list can be found at 
dludwig@9139
   409
<http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj662956(v=vs.105).aspx>
dludwig@9139
   410
dludwig@9139
   411
dludwig@9139
   412
### 7. Build and run your app ###
dludwig@9139
   413
dludwig@9139
   414
Your app project should now be setup, and you should be ready to build your app.  
dludwig@9139
   415
To run it on the local machine, open the Debug menu and choose "Start 
dludwig@9139
   416
Debugging".  This will build your app, then run your app full-screen.  To switch 
dludwig@9139
   417
out of your app, press the Windows key.  Alternatively, you can choose to run 
dludwig@9139
   418
your app in a window.  To do this, before building and running your app, find 
dludwig@9139
   419
the drop-down menu in Visual C++'s toolbar that says, "Local Machine".  Expand 
dludwig@9139
   420
this by clicking on the arrow on the right side of the list, then click on 
dludwig@9139
   421
Simulator.  Once you do that, any time you build and run the app, the app will 
dludwig@9139
   422
launch in window, rather than full-screen.
dludwig@9139
   423
dludwig@9139
   424
dludwig@9139
   425
#### 7.A. Running apps on ARM-based devices ####
dludwig@9139
   426
dludwig@9139
   427
To build and run the app on ARM-based, "Windows RT" devices, you'll need to:
dludwig@9139
   428
dludwig@9139
   429
- install Microsoft's "Remote Debugger" on the device.  Visual C++ installs and 
dludwig@9139
   430
  debugs ARM-based apps via IP networks.
dludwig@9139
   431
- change a few options on the development machine, both to make sure it builds 
dludwig@9139
   432
  for ARM (rather than x86 or x64), and to make sure it knows how to find the 
dludwig@9139
   433
  Windows RT device (on the network).
dludwig@9139
   434
dludwig@9139
   435
Microsoft's Remote Debugger can be found at 
dludwig@9139
   436
<http://msdn.microsoft.com/en-us/library/vstudio/bt727f1t.aspx>.  Please note 
dludwig@9139
   437
that separate versions of this debugger exist for different versions of Visual 
dludwig@9139
   438
C++, one for debugging with MSVC 2012, another for debugging with MSVC 2013.
dludwig@9139
   439
dludwig@9139
   440
To setup Visual C++ to launch your app on an ARM device:
dludwig@9139
   441
dludwig@9139
   442
1. make sure the Remote Debugger is running on your ARM device, and that it's on 
dludwig@9139
   443
   the same IP network as your development machine.
dludwig@9139
   444
2. from Visual C++'s toolbar, find a drop-down menu that says, "Win32".  Click 
dludwig@9139
   445
   it, then change the value to "ARM".
dludwig@9139
   446
3. make sure Visual C++ knows the hostname or IP address of the ARM device.  To 
dludwig@9139
   447
   do this:
dludwig@9139
   448
    1. open the app project's properties
dludwig@9139
   449
    2. select "Debugging"
dludwig@9139
   450
    3. next to "Machine Name", enter the hostname or IP address of the ARM 
dludwig@9139
   451
       device
dludwig@9209
   452
    4. if, and only if, you've turned off authentication in the Remote Debugger,
dludwig@9209
   453
       then change the setting for "Require Authentication" to No
dludwig@9139
   454
    5. click "OK"
dludwig@9139
   455
4. build and run the app (from Visual C++).  The first time you do this, a 
dludwig@9139
   456
   prompt will show up on the ARM device, asking for a Microsoft Account.  You 
dludwig@9139
   457
   do, unfortunately, need to log in here, and will need to follow the 
dludwig@9139
   458
   subsequent registration steps in order to launch the app.  After you do so, 
dludwig@9139
   459
   if the app didn't already launch, try relaunching it again from within Visual 
dludwig@9139
   460
   C++.
dludwig@9139
   461
dludwig@9139
   462
dludwig@9200
   463
Troubleshooting
dludwig@9200
   464
---------------
dludwig@9200
   465
dludwig@9200
   466
#### Build fails with message, "error LNK2038: mismatch detected for 'vccorlib_lib_should_be_specified_before_msvcrt_lib_to_linker'"
dludwig@9200
   467
dludwig@9200
   468
Try adding the following to your linker flags.  In MSVC, this can be done by
dludwig@9200
   469
right-clicking on the app project, navigating to Configuration Properties ->
dludwig@9200
   470
Linker -> Command Line, then adding them to the Additional Options
dludwig@9200
   471
section.
dludwig@9200
   472
dludwig@9200
   473
* For Release builds / MSVC-Configurations, add:
dludwig@9200
   474
dludwig@9200
   475
    /nodefaultlib:vccorlib /nodefaultlib:msvcrt vccorlib.lib msvcrt.lib
dludwig@9200
   476
dludwig@9200
   477
* For Debug builds / MSVC-Configurations, add:
dludwig@9200
   478
dludwig@9200
   479
    /nodefaultlib:vccorlibd /nodefaultlib:msvcrtd vccorlibd.lib msvcrtd.lib
dludwig@9200
   480