docs/README-winrt.md
author David Ludwig <dludwig@pobox.com>
Sun, 14 Sep 2014 11:36:24 -0400
changeset 9139 b2231eba36f5
parent 9138 b513dc1f7dd5
child 9140 3d8e33a24c31
permissions -rw-r--r--
WinRT: added manual, app-setup instructions to the README

A number of other parts of the WinRT README were edited, either for clarity, or to help with Markdown rendering.
dludwig@9139
     1
WinRT
dludwig@9139
     2
=====
dludwig@9139
     3
dludwig@9139
     4
SDL/WinRT layer allows SDL2-based applications to run on many of Microsoft's
dludwig@9139
     5
platforms that utilize the "Windows Runtime" (aka "WinRT") APIs.  WinRT apps
dludwig@9139
     6
are currently always full-screen apps, run in what Microsoft calls their
dludwig@9139
     7
"Modern" environment (aka. "Metro"), and are distributed via Microsoft-run
dludwig@9139
     8
online stores.  Some of the operating systems that support such apps include:
dludwig@9139
     9
dludwig@9139
    10
* Windows 8.x
dludwig@9139
    11
* Windows RT 8.x (aka. Windows 8.x for ARM processors)
dludwig@9139
    12
* Windows Phone 8.x
dludwig@9139
    13
dludwig@9139
    14
To note, WinRT applications that run on Windows 8.x and/or Windows RT are often
dludwig@9139
    15
called "Windows Store" apps.
dludwig@9139
    16
dludwig@9139
    17
dludwig@9139
    18
Requirements
dludwig@9137
    19
------------
dludwig@9139
    20
dludwig@9139
    21
- Microsoft Visual C++ 2012 -- Free, "Express" editions may be used, so long
dludwig@9139
    22
  as they include support for either "Windows Store" or "Windows Phone" apps.
dludwig@9139
    23
  (NOTE: MSVC 2013 support is pending.  2012 projects may be converted to 2013
dludwig@9139
    24
  projects by MSVC, in the meantime.)
dludwig@9139
    25
- A valid Microsoft account -- This requirement is not imposed by SDL, but
dludwig@9139
    26
  rather by Microsoft's Visual C++ toolchain.  This is required to debug apps.
dludwig@9139
    27
dludwig@9139
    28
dludwig@9139
    29
Setup, High-Level Steps
dludwig@9139
    30
-----------------------
dludwig@9139
    31
dludwig@9139
    32
The steps for setting up a project for an SDL/WinRT app looks like the
dludwig@9139
    33
following, at a high-level:
dludwig@9139
    34
dludwig@9139
    35
1. create a new Visual C++ project using Microsoft's template for a,
dludwig@9139
    36
   "Direct3D App".
dludwig@9139
    37
2. remove most of the files from the project.
dludwig@9139
    38
3. make your app's project directly reference SDL/WinRT's own Visual C++
dludwig@9139
    39
   project file, via use of Visual C++'s "References" dialog.  This will setup
dludwig@9139
    40
   the linker, and will copy SDL's .dll files to your app's final output.
dludwig@9139
    41
4. adjust your app's build settings, at minimum, telling it where to find SDL's
dludwig@9139
    42
   header files.
dludwig@9139
    43
5. add a file that contains a WinRT-appropriate main function.
dludwig@9139
    44
6. add SDL-specific app code.
dludwig@9139
    45
7. build and run your app.
dludwig@9139
    46
dludwig@9139
    47
dludwig@9139
    48
Setup, Detailed Steps
dludwig@9139
    49
---------------------
dludwig@9139
    50
dludwig@9139
    51
### 1. Create a new project ###
dludwig@9139
    52
dludwig@9139
    53
Create a new project using one of Visual C++'s templates for a plain, non-XAML,
dludwig@9139
    54
"Direct3D App" (XAML support for SDL/WinRT is not yet ready for use).  If you
dludwig@9139
    55
don't see one of these templates, in Visual C++'s 'New Project' dialog, try
dludwig@9139
    56
using the textbox titled, 'Search Installed Templates' to look for one.
dludwig@9139
    57
dludwig@9139
    58
dludwig@9139
    59
### 2. Remove unneeded files from the project ###
dludwig@9139
    60
dludwig@9139
    61
In the new project, delete any file that has one of the following extensions:
dludwig@9139
    62
dludwig@9139
    63
- .cpp
dludwig@9139
    64
- .h
dludwig@9139
    65
- .hlsl
dludwig@9139
    66
dludwig@9139
    67
When you are done, you should be left with a few files, each of which will be a
dludwig@9139
    68
necessary part of your app's project.  These files will consist of:
dludwig@9139
    69
dludwig@9139
    70
- an .appxmanifest file, which contains metadata on your WinRT app.  This is
dludwig@9139
    71
  similar to an Info.plist file on iOS, or an AndroidManifest.xml on Android.
dludwig@9139
    72
- a few .png files, one of which is a splash screen (displayed when your app
dludwig@9139
    73
  launches), others are app icons.
dludwig@9139
    74
- a .pfx file, used for code signing purposes.
dludwig@9139
    75
dludwig@9139
    76
dludwig@9139
    77
### 3. Add references to SDL's project files ###
dludwig@9139
    78
dludwig@9139
    79
SDL/WinRT can be built in multiple variations, spanning across three different
dludwig@9139
    80
CPU architectures (x86, x64, and ARM) and two different configurations
dludwig@9139
    81
(Debug and Release).  WinRT and Visual C++ do not currently provide a means
dludwig@9139
    82
for combining multiple variations of one library into a single file.
dludwig@9139
    83
Furthermore, it does not provide an easy means for copying pre-built .dll files
dludwig@9139
    84
into your app's final output (via Post-Build steps, for example).  It does,
dludwig@9139
    85
however, provide a system whereby an app can reference the MSVC projects of
dludwig@9139
    86
libraries such that, when the app is built:
dludwig@9139
    87
dludwig@9139
    88
1. each library gets built for the appropriate CPU architecture(s) and WinRT
dludwig@9139
    89
   platform(s).
dludwig@9139
    90
2. each library's output, such as .dll files, get copied to the app's build 
dludwig@9139
    91
   output.
dludwig@9139
    92
dludwig@9139
    93
To set this up for SDL/WinRT, you'll need to run through the following steps:
dludwig@9139
    94
dludwig@9139
    95
1. open up the Solution Explorer inside Visual C++ (under the "View" menu, then
dludwig@9139
    96
   "Solution Explorer")
dludwig@9139
    97
2. right click on your app's solution.
dludwig@9139
    98
3. navigate to "Add", then to "Existing Project..."
dludwig@9139
    99
4. find SDL/WinRT's Visual C++ project file and open it.  Different project
dludwig@9139
   100
   files exist for different WinRT platforms.  All of them are in SDL's
dludwig@9139
   101
   source distribution, in the following directories:
dludwig@9139
   102
    * `VisualC-WinRT/WinPhone80_VS2012/` - for Windows Phone 8.0 apps
dludwig@9139
   103
    * `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
dludwig@9139
   104
    * `VisualC-WinRT/WinRT80_VS2012/` - for Windows 8.0 apps
dludwig@9139
   105
    * `VisualC-WinRT/WinRT81_VS2013/` - for Windows 8.1 apps
dludwig@9139
   106
5. once the project has been added, right-click on your app's project and
dludwig@9139
   107
   select, "References..."
dludwig@9139
   108
6. click on the button titled, "Add New Reference..."
dludwig@9139
   109
7. check the box next to SDL
dludwig@9139
   110
8. click OK to close the dialog
dludwig@9139
   111
9. SDL will now show up in the list of references.  Click OK to close that
dludwig@9139
   112
   dialog.
dludwig@9139
   113
dludwig@9139
   114
Your project is now linked to SDL's project, insofar that when the app is
dludwig@9139
   115
built, SDL will be built as well, with its build output getting included with
dludwig@9139
   116
your app.
dludwig@9139
   117
dludwig@9139
   118
dludwig@9139
   119
### 4. Adjust Your App's Build Settings ###
dludwig@9139
   120
dludwig@9139
   121
Some build settings need to be changed in your app's project.  This guide will
dludwig@9139
   122
outline the following:
dludwig@9139
   123
dludwig@9139
   124
- making sure that the compiler knows where to find SDL's header files
dludwig@9139
   125
- **(optional for C++, but NECESSARY for compiling C code)** telling the
dludwig@9139
   126
  compiler not to use Microsoft's C++ extensions for WinRT development.
dludwig@9139
   127
- **(OPTIONAL)** telling the compiler not generate errors due to missing
dludwig@9139
   128
  precompiled header files.
dludwig@9139
   129
dludwig@9139
   130
To change these settings:
dludwig@9139
   131
dludwig@9139
   132
1. right-click on the project
dludwig@9139
   133
2. choose "Properties"
dludwig@9139
   134
3. in the drop-down box next to "Configuration", choose, "All Configurations"
dludwig@9139
   135
4. in the drop-down box next to "Platform", choose, "All Platforms"
dludwig@9139
   136
5. in the left-hand list, expand the "C/C++" section
dludwig@9139
   137
6. select "General"
dludwig@9139
   138
7. edit the "Additional Include Directories" setting, and add a path to SDL's
dludwig@9139
   139
   "include" directory
dludwig@9139
   140
8. ***Optional: to enable compilation of C code:*** change the setting for
dludwig@9139
   141
   "Consume Windows Runtime Extension" from "Yes (/ZW)" to "No".  If you're 
dludwig@9139
   142
   working with a completely C++ based project, this step can usually be 
dludwig@9139
   143
   omitted.
dludwig@9139
   144
9. ***Optional: to disable precompiled headers (which can produce 
dludwig@9139
   145
   'stdafx.h'-related build errors, if setup incorrectly:*** in the left-hand 
dludwig@9139
   146
   list, select "Precompiled Headers", then change the setting for "Precompiled 
dludwig@9139
   147
   Header" from "Use (/Yu)" to "Not Using Precompiled Headers".
dludwig@9139
   148
10. close the dialog, saving settings, by clicking the "OK" button
dludwig@9139
   149
dludwig@9139
   150
dludwig@9139
   151
### 5. Add a WinRT-appropriate main function to the app. ###
dludwig@9139
   152
dludwig@9139
   153
C/C++-based WinRT apps do contain a `main` function that the OS will invoke when 
dludwig@9139
   154
the app starts launching. The parameters of WinRT main functions are different 
dludwig@9139
   155
than those found on other platforms, Win32 included.  SDL/WinRT provides a 
dludwig@9139
   156
platform-appropriate main function that will perform these actions, setup key 
dludwig@9139
   157
portions of the app, then invoke a classic, C/C++-style main function (that take 
dludwig@9139
   158
in "argc" and "argv" parameters).  The code for this file is contained inside 
dludwig@9139
   159
SDL's source distribution, under `src/main/winrt/SDL_winrt_main_NonXAML.cpp`.  
dludwig@9139
   160
You'll need to add this file, or a copy of it, to your app's project, and make 
dludwig@9139
   161
sure it gets compiled using a Microsoft-specific set of C++ extensions called 
dludwig@9139
   162
C++/CX.
dludwig@9139
   163
dludwig@9139
   164
***NOTE: C++/CX compilation is currently required in at least one file of your 
dludwig@9139
   165
app's project.  This is to make sure that Visual C++'s linker builds a 'Windows 
dludwig@9139
   166
Metadata' file (.winmd) for your app.  Not doing so can lead to build errors.***
dludwig@9139
   167
dludwig@9139
   168
To include `SDL_winrt_main_NonXAML.cpp`:
dludwig@9139
   169
dludwig@9139
   170
1. right-click on your project (again, in Visual C++'s Solution Explorer), 
dludwig@9139
   171
   navigate to "Add", then choose "Existing Item...".
dludwig@9139
   172
2. open `SDL_winrt_main_NonXAML.cpp`, which is found inside SDL's source 
dludwig@9139
   173
   distribution, under `src/main/winrt/`.  Make sure that the open-file dialog 
dludwig@9139
   174
   closes, either by double-clicking on the file, or single-clicking on it and 
dludwig@9139
   175
   then clicking Add.
dludwig@9139
   176
3. right-click on the file (as listed in your project), then click on 
dludwig@9139
   177
   "Properties...".
dludwig@9139
   178
4. in the drop-down box next to "Configuration", choose, "All Configurations"
dludwig@9139
   179
5. in the drop-down box next to "Platform", choose, "All Platforms"
dludwig@9139
   180
6. in the left-hand list, click on "C/C++"
dludwig@9139
   181
7. change the setting for "Consume Windows Runtime Extension" to "Yes (/ZW)".
dludwig@9139
   182
8. click the OK button.  This will close the dialog.
dludwig@9139
   183
dludwig@9139
   184
dludwig@9139
   185
### 6. Add app code and assets ###
dludwig@9139
   186
dludwig@9139
   187
At this point, you can add in SDL-specific source code.  Be sure to include a 
dludwig@9139
   188
C-style main function (ie: `int main(int argc, char *argv[])`).  From there you 
dludwig@9139
   189
should be able to create a single `SDL_Window` (WinRT apps can only have one 
dludwig@9139
   190
window, at present), as well as an `SDL_Renderer`.  Direct3D will be used to 
dludwig@9139
   191
draw content.  Events are received via SDL's usual event functions 
dludwig@9139
   192
(`SDL_PollEvent`, etc.)  If you have a set of existing source files and assets, 
dludwig@9139
   193
you can start adding them to the project now.  If not, or if you would like to 
dludwig@9139
   194
make sure that you're setup correctly, some short and simple sample code is 
dludwig@9139
   195
provided below.
dludwig@9139
   196
dludwig@9139
   197
dludwig@9139
   198
#### 6.A. ... when creating a new app ####
dludwig@9139
   199
dludwig@9139
   200
If you are creating a new app (rather than porting an existing SDL-based app), 
dludwig@9139
   201
or if you would just like a simple app to test SDL/WinRT with before trying to 
dludwig@9139
   202
get existing code working, some working SDL/WinRT code is provided below.  To 
dludwig@9139
   203
set this up:
dludwig@9139
   204
dludwig@9139
   205
1. right click on your app's project
dludwig@9139
   206
2. select Add, then New Item.  An "Add New Item" dialog will show up.
dludwig@9139
   207
3. from the left-hand list, choose "Visual C++"
dludwig@9139
   208
4. from the middle/main list, choose "C++ File (.cpp)"
dludwig@9139
   209
5. near the bottom of the dialog, next to "Name:", type in a name for your 
dludwig@9139
   210
source file, such as, "main.cpp".
dludwig@9139
   211
6. click on the Add button.  This will close the dialog, add the new file to 
dludwig@9139
   212
your project, and open the file in Visual C++'s text editor.
dludwig@9139
   213
7. Copy and paste the following code into the new file (minus the , then save 
dludwig@9139
   214
it.
dludwig@9139
   215
dludwig@9139
   216
```
dludwig@9139
   217
#include <SDL.h>
dludwig@9139
   218
dludwig@9139
   219
int main(int argc, char **argv)
dludwig@9139
   220
{
dludwig@9139
   221
    SDL_DisplayMode mode;
dludwig@9139
   222
    SDL_Window * window = NULL;
dludwig@9139
   223
    SDL_Renderer * renderer = NULL;
dludwig@9139
   224
    SDL_Event evt;
dludwig@9139
   225
    
dludwig@9139
   226
    if (SDL_Init(SDL_INIT_VIDEO) != 0) {
dludwig@9139
   227
        return 1;
dludwig@9139
   228
    }
dludwig@9139
   229
    
dludwig@9139
   230
    if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
dludwig@9139
   231
        return 1;
dludwig@9139
   232
    }
dludwig@9139
   233
    
dludwig@9139
   234
    if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
dludwig@9139
   235
        return 1;
dludwig@9139
   236
    }
dludwig@9139
   237
    
dludwig@9139
   238
    while (1) {
dludwig@9139
   239
        while (SDL_PollEvent(&evt)) {
dludwig@9139
   240
        }
dludwig@9139
   241
        
dludwig@9139
   242
        SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
dludwig@9139
   243
        SDL_RenderClear(renderer);
dludwig@9139
   244
        SDL_RenderPresent(renderer);
dludwig@9139
   245
    }
dludwig@9139
   246
}
dludwig@9139
   247
```
dludwig@9139
   248
dludwig@9139
   249
dludwig@9139
   250
#### 6.B. Adding code and assets ####
dludwig@9139
   251
dludwig@9139
   252
If you have existing code and assets that you'd like to add, you should be able 
dludwig@9139
   253
to add them now.  The process for adding a set of files is as such.
dludwig@9139
   254
dludwig@9139
   255
1. right click on the app's project
dludwig@9139
   256
2. select Add, then click on "New Item..."
dludwig@9139
   257
3. open any source, header, or asset files as appropriate.  Support for C and 
dludwig@9139
   258
C++ is available.
dludwig@9139
   259
dludwig@9139
   260
Do note that WinRT only supports a subset of the APIs that are available to 
dludwig@9139
   261
Win32-based apps.  Many portions of the Win32 API and the C runtime are not 
dludwig@9139
   262
available.
dludwig@9139
   263
dludwig@9139
   264
A list of unsupported C APIs can be found at 
dludwig@9139
   265
<http://msdn.microsoft.com/en-us/library/windows/apps/jj606124.aspx>
dludwig@9139
   266
dludwig@9139
   267
General information on using the C runtime in WinRT can be found at 
dludwig@9139
   268
<http://msdn.microsoft.com/en-us/LIBRARY/hh972425(v=vs.110).aspx>
dludwig@9139
   269
dludwig@9139
   270
A list of supported Win32 APIs for Windows 8/RT apps can be found at 
dludwig@9139
   271
<http://msdn.microsoft.com/en-us/library/windows/apps/br205757.aspx>.  To note, 
dludwig@9139
   272
the list of supported Win32 APIs for Windows Phone 8 development is different.  
dludwig@9139
   273
That list can be found at 
dludwig@9139
   274
<http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj662956(v=vs.105).aspx>
dludwig@9139
   275
dludwig@9139
   276
dludwig@9139
   277
### 7. Build and run your app ###
dludwig@9139
   278
dludwig@9139
   279
Your app project should now be setup, and you should be ready to build your app.  
dludwig@9139
   280
To run it on the local machine, open the Debug menu and choose "Start 
dludwig@9139
   281
Debugging".  This will build your app, then run your app full-screen.  To switch 
dludwig@9139
   282
out of your app, press the Windows key.  Alternatively, you can choose to run 
dludwig@9139
   283
your app in a window.  To do this, before building and running your app, find 
dludwig@9139
   284
the drop-down menu in Visual C++'s toolbar that says, "Local Machine".  Expand 
dludwig@9139
   285
this by clicking on the arrow on the right side of the list, then click on 
dludwig@9139
   286
Simulator.  Once you do that, any time you build and run the app, the app will 
dludwig@9139
   287
launch in window, rather than full-screen.
dludwig@9139
   288
dludwig@9139
   289
dludwig@9139
   290
#### 7.A. Running apps on ARM-based devices ####
dludwig@9139
   291
dludwig@9139
   292
To build and run the app on ARM-based, "Windows RT" devices, you'll need to:
dludwig@9139
   293
dludwig@9139
   294
- install Microsoft's "Remote Debugger" on the device.  Visual C++ installs and 
dludwig@9139
   295
  debugs ARM-based apps via IP networks.
dludwig@9139
   296
- change a few options on the development machine, both to make sure it builds 
dludwig@9139
   297
  for ARM (rather than x86 or x64), and to make sure it knows how to find the 
dludwig@9139
   298
  Windows RT device (on the network).
dludwig@9139
   299
dludwig@9139
   300
Microsoft's Remote Debugger can be found at 
dludwig@9139
   301
<http://msdn.microsoft.com/en-us/library/vstudio/bt727f1t.aspx>.  Please note 
dludwig@9139
   302
that separate versions of this debugger exist for different versions of Visual 
dludwig@9139
   303
C++, one for debugging with MSVC 2012, another for debugging with MSVC 2013.
dludwig@9139
   304
dludwig@9139
   305
To setup Visual C++ to launch your app on an ARM device:
dludwig@9139
   306
dludwig@9139
   307
1. make sure the Remote Debugger is running on your ARM device, and that it's on 
dludwig@9139
   308
   the same IP network as your development machine.
dludwig@9139
   309
2. from Visual C++'s toolbar, find a drop-down menu that says, "Win32".  Click 
dludwig@9139
   310
   it, then change the value to "ARM".
dludwig@9139
   311
3. make sure Visual C++ knows the hostname or IP address of the ARM device.  To 
dludwig@9139
   312
   do this:
dludwig@9139
   313
    1. open the app project's properties
dludwig@9139
   314
    2. select "Debugging"
dludwig@9139
   315
    3. next to "Machine Name", enter the hostname or IP address of the ARM 
dludwig@9139
   316
       device
dludwig@9139
   317
    4. if, and only if, you've turned off authentication in the Remote Debugger, then change the setting for "Require Authentication" to No
dludwig@9139
   318
    5. click "OK"
dludwig@9139
   319
4. build and run the app (from Visual C++).  The first time you do this, a 
dludwig@9139
   320
   prompt will show up on the ARM device, asking for a Microsoft Account.  You 
dludwig@9139
   321
   do, unfortunately, need to log in here, and will need to follow the 
dludwig@9139
   322
   subsequent registration steps in order to launch the app.  After you do so, 
dludwig@9139
   323
   if the app didn't already launch, try relaunching it again from within Visual 
dludwig@9139
   324
   C++.
dludwig@9139
   325
dludwig@9139
   326
dludwig@9139
   327
TODO
dludwig@9137
   328
----
dludwig@9139
   329
dludwig@9139
   330
- Document details of SDL satellite library support
dludwig@9139
   331
- Make [NuGet](https://www.nuget.org) packages for SDL/WinRT
dludwig@9139
   332
- Create templates for both MSVC 2012 and MSVC 2013, and have the corresponding
dludwig@9139
   333
  VSIX packages either include pre-built copies of SDL, or reference binaries
dludwig@9139
   334
  available via MSVC's NuGet servers
dludwig@9139
   335
    - Write setup instructions that use MSVC 201x templates
dludwig@9139
   336
- Write a list of caveats found in SDL/WinRT, such as APIs that don't work due
dludwig@9139
   337
  to platform restrictions, or things that need further work