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