docs/README-winrt.md
changeset 9139 b2231eba36f5
parent 9138 b513dc1f7dd5
child 9140 3d8e33a24c31
     1.1 --- a/docs/README-winrt.md	Sun Sep 14 10:31:18 2014 -0400
     1.2 +++ b/docs/README-winrt.md	Sun Sep 14 11:36:24 2014 -0400
     1.3 @@ -1,44 +1,337 @@
     1.4 -WinRT
     1.5 -=====
     1.6 -
     1.7 -SDL/WinRT layer allows SDL2-based applications to run on many of Microsoft's
     1.8 -platforms that utilize the "Windows Runtime" (aka "WinRT") APIs.  WinRT apps
     1.9 -are currently always full-screen apps, run in what Microsoft calls their
    1.10 -"Modern" environment (aka. "Metro"), and are distributed via Microsoft-run
    1.11 -online stores.  Some of the operating systems that support such apps include:
    1.12 -
    1.13 -* Windows 8.x
    1.14 -* Windows RT 8.x (aka. Windows 8.x for ARM processors)
    1.15 -* Windows Phone 8.x
    1.16 -
    1.17 -To note, WinRT applications that run on Windows 8.x and/or Windows RT are often
    1.18 -called "Windows Store" apps.
    1.19 -
    1.20 -
    1.21 -Requirements
    1.22 +WinRT
    1.23 +=====
    1.24 +
    1.25 +SDL/WinRT layer allows SDL2-based applications to run on many of Microsoft's
    1.26 +platforms that utilize the "Windows Runtime" (aka "WinRT") APIs.  WinRT apps
    1.27 +are currently always full-screen apps, run in what Microsoft calls their
    1.28 +"Modern" environment (aka. "Metro"), and are distributed via Microsoft-run
    1.29 +online stores.  Some of the operating systems that support such apps include:
    1.30 +
    1.31 +* Windows 8.x
    1.32 +* Windows RT 8.x (aka. Windows 8.x for ARM processors)
    1.33 +* Windows Phone 8.x
    1.34 +
    1.35 +To note, WinRT applications that run on Windows 8.x and/or Windows RT are often
    1.36 +called "Windows Store" apps.
    1.37 +
    1.38 +
    1.39 +Requirements
    1.40  ------------
    1.41 -
    1.42 -- Microsoft Visual C++ 2012 -- Free, "Express" editions may be used, so long
    1.43 -  as they include support for either "Windows Store" or "Windows Phone" apps.
    1.44 -  (NOTE: MSVC 2013 support is pending.  2012 projects may be converted to 2013
    1.45 -  projects by MSVC, in the meantime.)
    1.46 -- A valid Microsoft account -- This requirement is not imposed by SDL, but
    1.47 -  rather by Microsoft's Visual C++ toolchain.  This is required to debug apps.
    1.48 -
    1.49 -
    1.50 -TODO
    1.51 +
    1.52 +- Microsoft Visual C++ 2012 -- Free, "Express" editions may be used, so long
    1.53 +  as they include support for either "Windows Store" or "Windows Phone" apps.
    1.54 +  (NOTE: MSVC 2013 support is pending.  2012 projects may be converted to 2013
    1.55 +  projects by MSVC, in the meantime.)
    1.56 +- A valid Microsoft account -- This requirement is not imposed by SDL, but
    1.57 +  rather by Microsoft's Visual C++ toolchain.  This is required to debug apps.
    1.58 +
    1.59 +
    1.60 +Setup, High-Level Steps
    1.61 +-----------------------
    1.62 +
    1.63 +The steps for setting up a project for an SDL/WinRT app looks like the
    1.64 +following, at a high-level:
    1.65 +
    1.66 +1. create a new Visual C++ project using Microsoft's template for a,
    1.67 +   "Direct3D App".
    1.68 +2. remove most of the files from the project.
    1.69 +3. make your app's project directly reference SDL/WinRT's own Visual C++
    1.70 +   project file, via use of Visual C++'s "References" dialog.  This will setup
    1.71 +   the linker, and will copy SDL's .dll files to your app's final output.
    1.72 +4. adjust your app's build settings, at minimum, telling it where to find SDL's
    1.73 +   header files.
    1.74 +5. add a file that contains a WinRT-appropriate main function.
    1.75 +6. add SDL-specific app code.
    1.76 +7. build and run your app.
    1.77 +
    1.78 +
    1.79 +Setup, Detailed Steps
    1.80 +---------------------
    1.81 +
    1.82 +### 1. Create a new project ###
    1.83 +
    1.84 +Create a new project using one of Visual C++'s templates for a plain, non-XAML,
    1.85 +"Direct3D App" (XAML support for SDL/WinRT is not yet ready for use).  If you
    1.86 +don't see one of these templates, in Visual C++'s 'New Project' dialog, try
    1.87 +using the textbox titled, 'Search Installed Templates' to look for one.
    1.88 +
    1.89 +
    1.90 +### 2. Remove unneeded files from the project ###
    1.91 +
    1.92 +In the new project, delete any file that has one of the following extensions:
    1.93 +
    1.94 +- .cpp
    1.95 +- .h
    1.96 +- .hlsl
    1.97 +
    1.98 +When you are done, you should be left with a few files, each of which will be a
    1.99 +necessary part of your app's project.  These files will consist of:
   1.100 +
   1.101 +- an .appxmanifest file, which contains metadata on your WinRT app.  This is
   1.102 +  similar to an Info.plist file on iOS, or an AndroidManifest.xml on Android.
   1.103 +- a few .png files, one of which is a splash screen (displayed when your app
   1.104 +  launches), others are app icons.
   1.105 +- a .pfx file, used for code signing purposes.
   1.106 +
   1.107 +
   1.108 +### 3. Add references to SDL's project files ###
   1.109 +
   1.110 +SDL/WinRT can be built in multiple variations, spanning across three different
   1.111 +CPU architectures (x86, x64, and ARM) and two different configurations
   1.112 +(Debug and Release).  WinRT and Visual C++ do not currently provide a means
   1.113 +for combining multiple variations of one library into a single file.
   1.114 +Furthermore, it does not provide an easy means for copying pre-built .dll files
   1.115 +into your app's final output (via Post-Build steps, for example).  It does,
   1.116 +however, provide a system whereby an app can reference the MSVC projects of
   1.117 +libraries such that, when the app is built:
   1.118 +
   1.119 +1. each library gets built for the appropriate CPU architecture(s) and WinRT
   1.120 +   platform(s).
   1.121 +2. each library's output, such as .dll files, get copied to the app's build 
   1.122 +   output.
   1.123 +
   1.124 +To set this up for SDL/WinRT, you'll need to run through the following steps:
   1.125 +
   1.126 +1. open up the Solution Explorer inside Visual C++ (under the "View" menu, then
   1.127 +   "Solution Explorer")
   1.128 +2. right click on your app's solution.
   1.129 +3. navigate to "Add", then to "Existing Project..."
   1.130 +4. find SDL/WinRT's Visual C++ project file and open it.  Different project
   1.131 +   files exist for different WinRT platforms.  All of them are in SDL's
   1.132 +   source distribution, in the following directories:
   1.133 +    * `VisualC-WinRT/WinPhone80_VS2012/` - for Windows Phone 8.0 apps
   1.134 +    * `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
   1.135 +    * `VisualC-WinRT/WinRT80_VS2012/` - for Windows 8.0 apps
   1.136 +    * `VisualC-WinRT/WinRT81_VS2013/` - for Windows 8.1 apps
   1.137 +5. once the project has been added, right-click on your app's project and
   1.138 +   select, "References..."
   1.139 +6. click on the button titled, "Add New Reference..."
   1.140 +7. check the box next to SDL
   1.141 +8. click OK to close the dialog
   1.142 +9. SDL will now show up in the list of references.  Click OK to close that
   1.143 +   dialog.
   1.144 +
   1.145 +Your project is now linked to SDL's project, insofar that when the app is
   1.146 +built, SDL will be built as well, with its build output getting included with
   1.147 +your app.
   1.148 +
   1.149 +
   1.150 +### 4. Adjust Your App's Build Settings ###
   1.151 +
   1.152 +Some build settings need to be changed in your app's project.  This guide will
   1.153 +outline the following:
   1.154 +
   1.155 +- making sure that the compiler knows where to find SDL's header files
   1.156 +- **(optional for C++, but NECESSARY for compiling C code)** telling the
   1.157 +  compiler not to use Microsoft's C++ extensions for WinRT development.
   1.158 +- **(OPTIONAL)** telling the compiler not generate errors due to missing
   1.159 +  precompiled header files.
   1.160 +
   1.161 +To change these settings:
   1.162 +
   1.163 +1. right-click on the project
   1.164 +2. choose "Properties"
   1.165 +3. in the drop-down box next to "Configuration", choose, "All Configurations"
   1.166 +4. in the drop-down box next to "Platform", choose, "All Platforms"
   1.167 +5. in the left-hand list, expand the "C/C++" section
   1.168 +6. select "General"
   1.169 +7. edit the "Additional Include Directories" setting, and add a path to SDL's
   1.170 +   "include" directory
   1.171 +8. ***Optional: to enable compilation of C code:*** change the setting for
   1.172 +   "Consume Windows Runtime Extension" from "Yes (/ZW)" to "No".  If you're 
   1.173 +   working with a completely C++ based project, this step can usually be 
   1.174 +   omitted.
   1.175 +9. ***Optional: to disable precompiled headers (which can produce 
   1.176 +   'stdafx.h'-related build errors, if setup incorrectly:*** in the left-hand 
   1.177 +   list, select "Precompiled Headers", then change the setting for "Precompiled 
   1.178 +   Header" from "Use (/Yu)" to "Not Using Precompiled Headers".
   1.179 +10. close the dialog, saving settings, by clicking the "OK" button
   1.180 +
   1.181 +
   1.182 +### 5. Add a WinRT-appropriate main function to the app. ###
   1.183 +
   1.184 +C/C++-based WinRT apps do contain a `main` function that the OS will invoke when 
   1.185 +the app starts launching. The parameters of WinRT main functions are different 
   1.186 +than those found on other platforms, Win32 included.  SDL/WinRT provides a 
   1.187 +platform-appropriate main function that will perform these actions, setup key 
   1.188 +portions of the app, then invoke a classic, C/C++-style main function (that take 
   1.189 +in "argc" and "argv" parameters).  The code for this file is contained inside 
   1.190 +SDL's source distribution, under `src/main/winrt/SDL_winrt_main_NonXAML.cpp`.  
   1.191 +You'll need to add this file, or a copy of it, to your app's project, and make 
   1.192 +sure it gets compiled using a Microsoft-specific set of C++ extensions called 
   1.193 +C++/CX.
   1.194 +
   1.195 +***NOTE: C++/CX compilation is currently required in at least one file of your 
   1.196 +app's project.  This is to make sure that Visual C++'s linker builds a 'Windows 
   1.197 +Metadata' file (.winmd) for your app.  Not doing so can lead to build errors.***
   1.198 +
   1.199 +To include `SDL_winrt_main_NonXAML.cpp`:
   1.200 +
   1.201 +1. right-click on your project (again, in Visual C++'s Solution Explorer), 
   1.202 +   navigate to "Add", then choose "Existing Item...".
   1.203 +2. open `SDL_winrt_main_NonXAML.cpp`, which is found inside SDL's source 
   1.204 +   distribution, under `src/main/winrt/`.  Make sure that the open-file dialog 
   1.205 +   closes, either by double-clicking on the file, or single-clicking on it and 
   1.206 +   then clicking Add.
   1.207 +3. right-click on the file (as listed in your project), then click on 
   1.208 +   "Properties...".
   1.209 +4. in the drop-down box next to "Configuration", choose, "All Configurations"
   1.210 +5. in the drop-down box next to "Platform", choose, "All Platforms"
   1.211 +6. in the left-hand list, click on "C/C++"
   1.212 +7. change the setting for "Consume Windows Runtime Extension" to "Yes (/ZW)".
   1.213 +8. click the OK button.  This will close the dialog.
   1.214 +
   1.215 +
   1.216 +### 6. Add app code and assets ###
   1.217 +
   1.218 +At this point, you can add in SDL-specific source code.  Be sure to include a 
   1.219 +C-style main function (ie: `int main(int argc, char *argv[])`).  From there you 
   1.220 +should be able to create a single `SDL_Window` (WinRT apps can only have one 
   1.221 +window, at present), as well as an `SDL_Renderer`.  Direct3D will be used to 
   1.222 +draw content.  Events are received via SDL's usual event functions 
   1.223 +(`SDL_PollEvent`, etc.)  If you have a set of existing source files and assets, 
   1.224 +you can start adding them to the project now.  If not, or if you would like to 
   1.225 +make sure that you're setup correctly, some short and simple sample code is 
   1.226 +provided below.
   1.227 +
   1.228 +
   1.229 +#### 6.A. ... when creating a new app ####
   1.230 +
   1.231 +If you are creating a new app (rather than porting an existing SDL-based app), 
   1.232 +or if you would just like a simple app to test SDL/WinRT with before trying to 
   1.233 +get existing code working, some working SDL/WinRT code is provided below.  To 
   1.234 +set this up:
   1.235 +
   1.236 +1. right click on your app's project
   1.237 +2. select Add, then New Item.  An "Add New Item" dialog will show up.
   1.238 +3. from the left-hand list, choose "Visual C++"
   1.239 +4. from the middle/main list, choose "C++ File (.cpp)"
   1.240 +5. near the bottom of the dialog, next to "Name:", type in a name for your 
   1.241 +source file, such as, "main.cpp".
   1.242 +6. click on the Add button.  This will close the dialog, add the new file to 
   1.243 +your project, and open the file in Visual C++'s text editor.
   1.244 +7. Copy and paste the following code into the new file (minus the , then save 
   1.245 +it.
   1.246 +
   1.247 +```
   1.248 +#include <SDL.h>
   1.249 +
   1.250 +int main(int argc, char **argv)
   1.251 +{
   1.252 +    SDL_DisplayMode mode;
   1.253 +    SDL_Window * window = NULL;
   1.254 +    SDL_Renderer * renderer = NULL;
   1.255 +    SDL_Event evt;
   1.256 +    
   1.257 +    if (SDL_Init(SDL_INIT_VIDEO) != 0) {
   1.258 +        return 1;
   1.259 +    }
   1.260 +    
   1.261 +    if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
   1.262 +        return 1;
   1.263 +    }
   1.264 +    
   1.265 +    if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
   1.266 +        return 1;
   1.267 +    }
   1.268 +    
   1.269 +    while (1) {
   1.270 +        while (SDL_PollEvent(&evt)) {
   1.271 +        }
   1.272 +        
   1.273 +        SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
   1.274 +        SDL_RenderClear(renderer);
   1.275 +        SDL_RenderPresent(renderer);
   1.276 +    }
   1.277 +}
   1.278 +```
   1.279 +
   1.280 +
   1.281 +#### 6.B. Adding code and assets ####
   1.282 +
   1.283 +If you have existing code and assets that you'd like to add, you should be able 
   1.284 +to add them now.  The process for adding a set of files is as such.
   1.285 +
   1.286 +1. right click on the app's project
   1.287 +2. select Add, then click on "New Item..."
   1.288 +3. open any source, header, or asset files as appropriate.  Support for C and 
   1.289 +C++ is available.
   1.290 +
   1.291 +Do note that WinRT only supports a subset of the APIs that are available to 
   1.292 +Win32-based apps.  Many portions of the Win32 API and the C runtime are not 
   1.293 +available.
   1.294 +
   1.295 +A list of unsupported C APIs can be found at 
   1.296 +<http://msdn.microsoft.com/en-us/library/windows/apps/jj606124.aspx>
   1.297 +
   1.298 +General information on using the C runtime in WinRT can be found at 
   1.299 +<http://msdn.microsoft.com/en-us/LIBRARY/hh972425(v=vs.110).aspx>
   1.300 +
   1.301 +A list of supported Win32 APIs for Windows 8/RT apps can be found at 
   1.302 +<http://msdn.microsoft.com/en-us/library/windows/apps/br205757.aspx>.  To note, 
   1.303 +the list of supported Win32 APIs for Windows Phone 8 development is different.  
   1.304 +That list can be found at 
   1.305 +<http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj662956(v=vs.105).aspx>
   1.306 +
   1.307 +
   1.308 +### 7. Build and run your app ###
   1.309 +
   1.310 +Your app project should now be setup, and you should be ready to build your app.  
   1.311 +To run it on the local machine, open the Debug menu and choose "Start 
   1.312 +Debugging".  This will build your app, then run your app full-screen.  To switch 
   1.313 +out of your app, press the Windows key.  Alternatively, you can choose to run 
   1.314 +your app in a window.  To do this, before building and running your app, find 
   1.315 +the drop-down menu in Visual C++'s toolbar that says, "Local Machine".  Expand 
   1.316 +this by clicking on the arrow on the right side of the list, then click on 
   1.317 +Simulator.  Once you do that, any time you build and run the app, the app will 
   1.318 +launch in window, rather than full-screen.
   1.319 +
   1.320 +
   1.321 +#### 7.A. Running apps on ARM-based devices ####
   1.322 +
   1.323 +To build and run the app on ARM-based, "Windows RT" devices, you'll need to:
   1.324 +
   1.325 +- install Microsoft's "Remote Debugger" on the device.  Visual C++ installs and 
   1.326 +  debugs ARM-based apps via IP networks.
   1.327 +- change a few options on the development machine, both to make sure it builds 
   1.328 +  for ARM (rather than x86 or x64), and to make sure it knows how to find the 
   1.329 +  Windows RT device (on the network).
   1.330 +
   1.331 +Microsoft's Remote Debugger can be found at 
   1.332 +<http://msdn.microsoft.com/en-us/library/vstudio/bt727f1t.aspx>.  Please note 
   1.333 +that separate versions of this debugger exist for different versions of Visual 
   1.334 +C++, one for debugging with MSVC 2012, another for debugging with MSVC 2013.
   1.335 +
   1.336 +To setup Visual C++ to launch your app on an ARM device:
   1.337 +
   1.338 +1. make sure the Remote Debugger is running on your ARM device, and that it's on 
   1.339 +   the same IP network as your development machine.
   1.340 +2. from Visual C++'s toolbar, find a drop-down menu that says, "Win32".  Click 
   1.341 +   it, then change the value to "ARM".
   1.342 +3. make sure Visual C++ knows the hostname or IP address of the ARM device.  To 
   1.343 +   do this:
   1.344 +    1. open the app project's properties
   1.345 +    2. select "Debugging"
   1.346 +    3. next to "Machine Name", enter the hostname or IP address of the ARM 
   1.347 +       device
   1.348 +    4. if, and only if, you've turned off authentication in the Remote Debugger, then change the setting for "Require Authentication" to No
   1.349 +    5. click "OK"
   1.350 +4. build and run the app (from Visual C++).  The first time you do this, a 
   1.351 +   prompt will show up on the ARM device, asking for a Microsoft Account.  You 
   1.352 +   do, unfortunately, need to log in here, and will need to follow the 
   1.353 +   subsequent registration steps in order to launch the app.  After you do so, 
   1.354 +   if the app didn't already launch, try relaunching it again from within Visual 
   1.355 +   C++.
   1.356 +
   1.357 +
   1.358 +TODO
   1.359  ----
   1.360 -
   1.361 -- Finish adding support for MSVC 2013, and "Universal" WinRT apps, which
   1.362 -  support Windows 8.1, Windows Phone 8.1, and in the future, Xbox One and
   1.363 -  Windows Desktop.
   1.364 -- Finish adding support for the SDL satellite libraries (SDL_image, SDL_mixer,
   1.365 -  SDL_ttf, etc.)
   1.366 -- Create templates for both MSVC 2012 and MSVC 2013, and have the corresponding
   1.367 -  VSIX packages either include pre-built copies of SDL, or reference binaries
   1.368 -  available via MSVC's NuGet servers
   1.369 -- Write setup instructions that use MSVC 201x templates
   1.370 -- Write setup instructions that don't use MSVC 201x templates, and use
   1.371 -  MSVC project-to-project references, rather than pre-built binaries
   1.372 -- Write a list of caveats found in SDL/WinRT, such as APIs that don't work due
   1.373 -  to platform restrictions, or things that need further work
   1.374 +
   1.375 +- Document details of SDL satellite library support
   1.376 +- Make [NuGet](https://www.nuget.org) packages for SDL/WinRT
   1.377 +- Create templates for both MSVC 2012 and MSVC 2013, and have the corresponding
   1.378 +  VSIX packages either include pre-built copies of SDL, or reference binaries
   1.379 +  available via MSVC's NuGet servers
   1.380 +    - Write setup instructions that use MSVC 201x templates
   1.381 +- Write a list of caveats found in SDL/WinRT, such as APIs that don't work due
   1.382 +  to platform restrictions, or things that need further work