docs/README-winrt.md
author Sam Lantinga
Sun, 05 Apr 2020 08:58:47 -0700
changeset 13689 c3055b205671
parent 12810 77707a081153
permissions -rw-r--r--
Fixed bug 5015 - SDL_RenderReadPixels on DirectX 11.1 backend seems to be broken

Konrad

It appears that I cannot use SDL_RenderReadPixels on a bound framebuffer (SDL_Texture set as render target) as it simply results in gibberish data. However, drawing that framebuffer into the default target (window surface) does render it correctly. Other backends (OpenGL, software, Direct3D) do work fine.

It looks to me like D3D11_RenderReadPixels just gets the general backbuffer and not the current render target and its backbuffer.

Here is the patch which actually fetches the current render target and its underlying ID3D11Resource which is ID3D11Texture2D.
slouken@10486
     1
WinRT
slouken@10486
     2
=====
slouken@10486
     3
slouken@10486
     4
This port allows SDL applications to run on Microsoft's platforms that require
slouken@10486
     5
use of "Windows Runtime", aka. "WinRT", APIs.  Microsoft may, in some cases,
slouken@10486
     6
refer to them as either "Windows Store", or for Windows 10, "UWP" apps.
slouken@10486
     7
slouken@10486
     8
Some of the operating systems that include WinRT, are:
slouken@10486
     9
slouken@10486
    10
* Windows 10, via its Universal Windows Platform (UWP) APIs
slouken@10486
    11
* Windows 8.x
slouken@10486
    12
* Windows RT 8.x (aka. Windows 8.x for ARM processors)
slouken@10486
    13
* Windows Phone 8.x
slouken@10486
    14
slouken@10486
    15
slouken@10486
    16
Requirements
slouken@10486
    17
------------
slouken@10486
    18
dludwig@11446
    19
* Microsoft Visual C++ (aka Visual Studio), either 2017, 2015, 2013, or 2012
slouken@10486
    20
  - Free, "Community" or "Express" editions may be used, so long as they
slouken@10486
    21
    include  support for either "Windows Store" or "Windows Phone" apps.
slouken@10486
    22
    "Express" versions marked as supporting "Windows Desktop" development
slouken@10486
    23
    typically do not include support for creating WinRT apps, to note.
slouken@10486
    24
    (The "Community" editions of Visual C++ do, however, support both
slouken@10486
    25
    desktop/Win32 and WinRT development).
slouken@11720
    26
  - Visual Studio 2017 can be used, however it is recommended that you install
dludwig@11446
    27
    the Visual C++ 2015 build tools.  These build tools can be installed
dludwig@11446
    28
    using VS 2017's installer.  Be sure to also install the workload for
dludwig@11446
    29
    "Universal Windows Platform development", its optional component, the
dludwig@11446
    30
    "C++ Universal Windows Platform tools", and for UWP / Windows 10
dludwig@11446
    31
    development, the "Windows 10 SDK (10.0.10240.0)".  Please note that
dludwig@11446
    32
    targeting UWP / Windows 10 apps from development machine(s) running
dludwig@11446
    33
    earlier versions of Windows, such as Windows 7, is not always supported
dludwig@11446
    34
    by Visual Studio, and you may get error(s) when attempting to do so.
slouken@10486
    35
  - Visual C++ 2012 can only build apps that target versions 8.0 of Windows,
slouken@11720
    36
    or  Windows Phone.  8.0-targeted apps will run on devices running 8.1
slouken@10486
    37
    editions of Windows, however they will not be able to take advantage of
slouken@10486
    38
    8.1-specific features.
slouken@10486
    39
  - Visual C++ 2013 cannot create app projects that target Windows 8.0.
slouken@10486
    40
    Visual C++ 2013 Update 4, can create app projects for Windows Phone 8.0,
slouken@10486
    41
    Windows Phone 8.1, and Windows 8.1, but not Windows 8.0.  An optional
slouken@10486
    42
    Visual Studio add-in, "Tools for Maintaining Store apps for Windows 8",
slouken@10486
    43
    allows Visual C++ 2013 to load and build Windows 8.0 projects that were
slouken@10486
    44
    created with Visual C++ 2012, so long as Visual C++ 2012 is installed
slouken@10486
    45
    on the same machine.  More details on targeting different versions of
slouken@10486
    46
    Windows can found at the following web pages:
slouken@10486
    47
      - [Develop apps by using Visual Studio 2013](http://msdn.microsoft.com/en-us/library/windows/apps/br211384.aspx)
slouken@10486
    48
      - [To add the Tools for Maintaining Store apps for Windows 8](http://msdn.microsoft.com/en-us/library/windows/apps/dn263114.aspx#AddMaintenanceTools)
slouken@10486
    49
* A valid Microsoft account - This requirement is not imposed by SDL, but
slouken@10486
    50
  rather by Microsoft's Visual C++ toolchain.  This is required to launch or 
slouken@10486
    51
  debug apps.
slouken@10486
    52
slouken@10486
    53
slouken@10486
    54
Status
slouken@10486
    55
------
slouken@10486
    56
slouken@11720
    57
Here is a rough list of what works, and what doesn't:
slouken@10486
    58
slouken@10486
    59
* What works:
slouken@10486
    60
  * compilation via Visual C++ 2012 through 2015
slouken@10486
    61
  * compile-time platform detection for SDL programs.  The C/C++ #define,
slouken@10486
    62
    `__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
slouken@10486
    63
  * GPU-accelerated 2D rendering, via SDL_Renderer.
slouken@10486
    64
  * OpenGL ES 2, via the ANGLE library (included separately from SDL)
slouken@10486
    65
  * software rendering, via either SDL_Surface (optionally in conjunction with
slouken@10486
    66
    SDL_GetWindowSurface() and SDL_UpdateWindowSurface()) or via the
slouken@10486
    67
    SDL_Renderer APIs
slouken@10486
    68
  * threads
slouken@10486
    69
  * timers (via SDL_GetTicks(), SDL_AddTimer(), SDL_GetPerformanceCounter(),
slouken@10486
    70
    SDL_GetPerformanceFrequency(), etc.)
slouken@10486
    71
  * file I/O via SDL_RWops
slouken@10486
    72
  * mouse input  (unsupported on Windows Phone)
icculus@11726
    73
  * audio, via SDL's WASAPI backend (if you want to record, your app must 
icculus@11726
    74
    have "Microphone" capabilities enabled in its manifest, and the user must 
icculus@11726
    75
    not have blocked access. Otherwise, capture devices will fail to work,
icculus@11726
    76
    presenting as a device disconnect shortly after opening it.)
slouken@10486
    77
  * .DLL file loading.  Libraries *MUST* be packaged inside applications.  Loading
slouken@10486
    78
    anything outside of the app is not supported.
slouken@10486
    79
  * system path retrieval via SDL's filesystem APIs
slouken@10486
    80
  * game controllers.  Support is provided via the SDL_Joystick and
dludwig@11502
    81
    SDL_GameController APIs, and is backed by Microsoft's XInput API.  Please
dludwig@11502
    82
    note, however, that Windows limits game-controller support in UWP apps to,
dludwig@11502
    83
    "Xbox compatible controllers" (many controllers that work in Win32 apps,
dludwig@11502
    84
    do not work in UWP, due to restrictions in UWP itself.) 
slouken@10486
    85
  * multi-touch input
slouken@10486
    86
  * app events.  SDL_APP_WILLENTER* and SDL_APP_DIDENTER* events get sent out as
slouken@10486
    87
    appropriate.
slouken@10486
    88
  * window events
slouken@10486
    89
  * using Direct3D 11.x APIs outside of SDL.  Non-XAML / Direct3D-only apps can
slouken@10486
    90
    choose to render content directly via Direct3D, using SDL to manage the
slouken@10486
    91
    internal WinRT window, as well as input and audio.  (Use
slouken@10486
    92
    SDL_GetWindowWMInfo() to get the WinRT 'CoreWindow', and pass it into
slouken@10486
    93
    IDXGIFactory2::CreateSwapChainForCoreWindow() as appropriate.)
slouken@10486
    94
slouken@10486
    95
* What partially works:
slouken@10486
    96
  * keyboard input.  Most of WinRT's documented virtual keys are supported, as
slouken@10486
    97
    well as many keys with documented hardware scancodes.  Converting
slouken@10486
    98
    SDL_Scancodes to or from SDL_Keycodes may not work, due to missing APIs
philipp@10828
    99
    (MapVirtualKey()) in Microsoft's Windows Store / UWP APIs.
slouken@10486
   100
  * SDLmain.  WinRT uses a different signature for each app's main() function.
slouken@10486
   101
    SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
slouken@10486
   102
    (in `SDL\src\main\winrt\`) directly in order for their C-style main()
slouken@10486
   103
    functions to be called.
slouken@10486
   104
slouken@10486
   105
* What doesn't work:
slouken@10486
   106
  * compilation with anything other than Visual C++
slouken@10486
   107
  * programmatically-created custom cursors.  These don't appear to be supported
slouken@10486
   108
    by WinRT.  Different OS-provided cursors can, however, be created via
slouken@10486
   109
    SDL_CreateSystemCursor() (unsupported on Windows Phone)
slouken@10486
   110
  * SDL_WarpMouseInWindow() or SDL_WarpMouseGlobal().  This are not currently
slouken@10486
   111
    supported by WinRT itself.
dludwig@11502
   112
  * joysticks and game controllers that either are not supported by
dludwig@11502
   113
    Microsoft's XInput API, or are not supported within UWP apps (many
dludwig@11502
   114
    controllers that work in Win32, do not work in UWP, due to restrictions in
dludwig@11502
   115
    UWP itself).
slouken@10486
   116
  * turning off VSync when rendering on Windows Phone.  Attempts to turn VSync
slouken@10486
   117
    off on Windows Phone result either in Direct3D not drawing anything, or it
slouken@10486
   118
    forcing VSync back on.  As such, SDL_RENDERER_PRESENTVSYNC will always get
slouken@10486
   119
    turned-on on Windows Phone.  This limitation is not present in non-Phone
slouken@10486
   120
    WinRT (such as Windows 8.x), where turning off VSync appears to work.
slouken@10486
   121
  * probably anything else that's not listed as supported
slouken@10486
   122
slouken@10486
   123
slouken@10486
   124
slouken@10486
   125
Upgrade Notes
slouken@10486
   126
-------------
slouken@10486
   127
slouken@10486
   128
#### SDL_GetPrefPath() usage when upgrading WinRT apps from SDL 2.0.3
slouken@10486
   129
slouken@10486
   130
SDL 2.0.4 fixes two bugs found in the WinRT version of SDL_GetPrefPath().
slouken@10486
   131
The fixes may affect older, SDL 2.0.3-based apps' save data.  Please note
slouken@10486
   132
that these changes only apply to SDL-based WinRT apps, and not to apps for
slouken@10486
   133
any other platform.
slouken@10486
   134
slouken@10486
   135
1. SDL_GetPrefPath() would return an invalid path, one in which the path's
slouken@10486
   136
   directory had not been created.  Attempts to create files there
slouken@10486
   137
   (via fopen(), for example), would fail, unless that directory was
slouken@10486
   138
   explicitly created beforehand.
slouken@10486
   139
slouken@10486
   140
2. SDL_GetPrefPath(), for non-WinPhone-based apps, would return a path inside
slouken@10486
   141
   a WinRT 'Roaming' folder, the contents of which get automatically
slouken@10486
   142
   synchronized across multiple devices.  This process can occur while an
slouken@10486
   143
   application runs, and can cause existing save-data to be overwritten
slouken@10486
   144
   at unexpected times, with data from other devices.  (Windows Phone apps
slouken@10486
   145
   written with SDL 2.0.3 did not utilize a Roaming folder, due to API
slouken@10486
   146
   restrictions in Windows Phone 8.0).
slouken@10486
   147
slouken@10486
   148
slouken@10486
   149
SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
slouken@10486
   150
slouken@10486
   151
1. making sure that SDL_GetPrefPath() returns a directory in which data
slouken@10486
   152
   can be written to immediately, without first needing to create directories.
slouken@10486
   153
slouken@10486
   154
2. basing SDL_GetPrefPath() off of a different, non-Roaming folder, the
slouken@10486
   155
   contents of which do not automatically get synchronized across devices
slouken@10486
   156
   (and which require less work to use safely, in terms of data integrity).
slouken@10486
   157
slouken@10486
   158
Apps that wish to get their Roaming folder's path can do so either by using
slouken@10486
   159
SDL_WinRTGetFSPathUTF8(), SDL_WinRTGetFSPathUNICODE() (which returns a
slouken@10486
   160
UCS-2/wide-char string), or directly through the WinRT class,
slouken@10486
   161
Windows.Storage.ApplicationData.
slouken@10486
   162
slouken@10486
   163
slouken@10486
   164
slouken@10486
   165
Setup, High-Level Steps
slouken@10486
   166
-----------------------
slouken@10486
   167
slouken@10486
   168
The steps for setting up a project for an SDL/WinRT app looks like the
slouken@10486
   169
following, at a high-level:
slouken@10486
   170
slouken@10486
   171
1. create a new Visual C++ project using Microsoft's template for a,
slouken@10486
   172
   "Direct3D App".
slouken@10486
   173
2. remove most of the files from the project.
slouken@10486
   174
3. make your app's project directly reference SDL/WinRT's own Visual C++
slouken@10486
   175
   project file, via use of Visual C++'s "References" dialog.  This will setup
slouken@10486
   176
   the linker, and will copy SDL's .dll files to your app's final output.
slouken@10486
   177
4. adjust your app's build settings, at minimum, telling it where to find SDL's
slouken@10486
   178
   header files.
slouken@10486
   179
5. add files that contains a WinRT-appropriate main function, along with some
slouken@10486
   180
   data to make sure mouse-cursor-hiding (via SDL_ShowCursor(SDL_DISABLE) calls)
slouken@10486
   181
   work properly.
slouken@10486
   182
6. add SDL-specific app code.
slouken@10486
   183
7. build and run your app.
slouken@10486
   184
slouken@10486
   185
slouken@10486
   186
Setup, Detailed Steps
slouken@10486
   187
---------------------
slouken@10486
   188
slouken@10486
   189
### 1. Create a new project ###
slouken@10486
   190
slouken@10486
   191
Create a new project using one of Visual C++'s templates for a plain, non-XAML,
slouken@10486
   192
"Direct3D App" (XAML support for SDL/WinRT is not yet ready for use).  If you
slouken@10486
   193
don't see one of these templates, in Visual C++'s 'New Project' dialog, try
slouken@10486
   194
using the textbox titled, 'Search Installed Templates' to look for one.
slouken@10486
   195
slouken@10486
   196
slouken@10486
   197
### 2. Remove unneeded files from the project ###
slouken@10486
   198
slouken@10486
   199
In the new project, delete any file that has one of the following extensions:
slouken@10486
   200
slouken@10486
   201
- .cpp
slouken@10486
   202
- .h
slouken@10486
   203
- .hlsl
slouken@10486
   204
slouken@10486
   205
When you are done, you should be left with a few files, each of which will be a
slouken@10486
   206
necessary part of your app's project.  These files will consist of:
slouken@10486
   207
slouken@10486
   208
- an .appxmanifest file, which contains metadata on your WinRT app.  This is
slouken@10486
   209
  similar to an Info.plist file on iOS, or an AndroidManifest.xml on Android.
slouken@10486
   210
- a few .png files, one of which is a splash screen (displayed when your app
slouken@10486
   211
  launches), others are app icons.
slouken@10486
   212
- a .pfx file, used for code signing purposes.
slouken@10486
   213
slouken@10486
   214
slouken@10486
   215
### 3. Add references to SDL's project files ###
slouken@10486
   216
slouken@10486
   217
SDL/WinRT can be built in multiple variations, spanning across three different
slouken@10486
   218
CPU architectures (x86, x64, and ARM) and two different configurations
slouken@10486
   219
(Debug and Release).  WinRT and Visual C++ do not currently provide a means
slouken@10486
   220
for combining multiple variations of one library into a single file.
slouken@10486
   221
Furthermore, it does not provide an easy means for copying pre-built .dll files
slouken@10486
   222
into your app's final output (via Post-Build steps, for example).  It does,
slouken@10486
   223
however, provide a system whereby an app can reference the MSVC projects of
slouken@10486
   224
libraries such that, when the app is built:
slouken@10486
   225
slouken@10486
   226
1. each library gets built for the appropriate CPU architecture(s) and WinRT
slouken@10486
   227
   platform(s).
slouken@10486
   228
2. each library's output, such as .dll files, get copied to the app's build 
slouken@10486
   229
   output.
slouken@10486
   230
slouken@10486
   231
To set this up for SDL/WinRT, you'll need to run through the following steps:
slouken@10486
   232
slouken@10486
   233
1. open up the Solution Explorer inside Visual C++ (under the "View" menu, then
slouken@10486
   234
   "Solution Explorer")
slouken@10486
   235
2. right click on your app's solution.
slouken@10486
   236
3. navigate to "Add", then to "Existing Project..."
slouken@10486
   237
4. find SDL/WinRT's Visual C++ project file and open it.  Different project
slouken@10486
   238
   files exist for different WinRT platforms.  All of them are in SDL's
slouken@10486
   239
   source distribution, in the following directories:
slouken@10486
   240
    * `VisualC-WinRT/UWP_VS2015/`        - for Windows 10 / UWP apps
slouken@10486
   241
    * `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
slouken@10486
   242
    * `VisualC-WinRT/WinRT80_VS2012/`    - for Windows 8.0 apps
slouken@10486
   243
    * `VisualC-WinRT/WinRT81_VS2013/`    - for Windows 8.1 apps
slouken@10486
   244
5. once the project has been added, right-click on your app's project and
slouken@10486
   245
   select, "References..."
slouken@10486
   246
6. click on the button titled, "Add New Reference..."
slouken@10486
   247
7. check the box next to SDL
slouken@10486
   248
8. click OK to close the dialog
slouken@10486
   249
9. SDL will now show up in the list of references.  Click OK to close that
slouken@10486
   250
   dialog.
slouken@10486
   251
slouken@10486
   252
Your project is now linked to SDL's project, insofar that when the app is
slouken@10486
   253
built, SDL will be built as well, with its build output getting included with
slouken@10486
   254
your app.
slouken@10486
   255
slouken@10486
   256
slouken@10486
   257
### 4. Adjust Your App's Build Settings ###
slouken@10486
   258
slouken@10486
   259
Some build settings need to be changed in your app's project.  This guide will
slouken@10486
   260
outline the following:
slouken@10486
   261
slouken@10486
   262
- making sure that the compiler knows where to find SDL's header files
slouken@10486
   263
- **Optional for C++, but NECESSARY for compiling C code:** telling the
slouken@10486
   264
  compiler not to use Microsoft's C++ extensions for WinRT development.
slouken@10486
   265
- **Optional:** telling the compiler not generate errors due to missing
slouken@10486
   266
  precompiled header files.
slouken@10486
   267
slouken@10486
   268
To change these settings:
slouken@10486
   269
slouken@10486
   270
1. right-click on the project
slouken@10486
   271
2. choose "Properties"
slouken@10486
   272
3. in the drop-down box next to "Configuration", choose, "All Configurations"
slouken@10486
   273
4. in the drop-down box next to "Platform", choose, "All Platforms"
slouken@10486
   274
5. in the left-hand list, expand the "C/C++" section
slouken@10486
   275
6. select "General"
slouken@10486
   276
7. edit the "Additional Include Directories" setting, and add a path to SDL's
slouken@10486
   277
   "include" directory
slouken@10486
   278
8. **Optional: to enable compilation of C code:** change the setting for
slouken@10486
   279
   "Consume Windows Runtime Extension" from "Yes (/ZW)" to "No".  If you're 
slouken@10486
   280
   working with a completely C++ based project, this step can usually be 
slouken@10486
   281
   omitted.
slouken@10486
   282
9. **Optional: to disable precompiled headers (which can produce 
slouken@10486
   283
   'stdafx.h'-related build errors, if setup incorrectly:** in the left-hand 
slouken@10486
   284
   list, select "Precompiled Headers", then change the setting for "Precompiled 
slouken@10486
   285
   Header" from "Use (/Yu)" to "Not Using Precompiled Headers".
slouken@10486
   286
10. close the dialog, saving settings, by clicking the "OK" button
slouken@10486
   287
slouken@10486
   288
slouken@10486
   289
### 5. Add a WinRT-appropriate main function, and a blank-cursor image, to the app. ###
slouken@10486
   290
slouken@10486
   291
A few files should be included directly in your app's MSVC project, specifically:
slouken@10486
   292
1. a WinRT-appropriate main function (which is different than main() functions on
slouken@10486
   293
   other platforms)
slouken@10486
   294
2. a Win32-style cursor resource, used by SDL_ShowCursor() to hide the mouse cursor
slouken@10486
   295
   (if and when the app needs to do so).  *If this cursor resource is not
slouken@10486
   296
   included, mouse-position reporting may fail if and when the cursor is
slouken@10486
   297
   hidden, due to possible bugs/design-oddities in Windows itself.*
slouken@10486
   298
flibitijibibo@12810
   299
To include these files for C/C++ projects:
slouken@10486
   300
slouken@10486
   301
1. right-click on your project (again, in Visual C++'s Solution Explorer), 
slouken@10486
   302
   navigate to "Add", then choose "Existing Item...".
slouken@10486
   303
2. navigate to the directory containing SDL's source code, then into its
slouken@10486
   304
   subdirectory, 'src/main/winrt/'.  Select, then add, the following files:
slouken@10486
   305
   - `SDL_winrt_main_NonXAML.cpp`
slouken@10486
   306
   - `SDL2-WinRTResources.rc`
slouken@10486
   307
   - `SDL2-WinRTResource_BlankCursor.cur`
slouken@10486
   308
3. right-click on the file `SDL_winrt_main_NonXAML.cpp` (as listed in your
slouken@10486
   309
   project), then click on "Properties...".
slouken@10486
   310
4. in the drop-down box next to "Configuration", choose, "All Configurations"
slouken@10486
   311
5. in the drop-down box next to "Platform", choose, "All Platforms"
slouken@10486
   312
6. in the left-hand list, click on "C/C++"
slouken@10486
   313
7. change the setting for "Consume Windows Runtime Extension" to "Yes (/ZW)".
slouken@10486
   314
8. click the OK button.  This will close the dialog.
slouken@10486
   315
slouken@10486
   316
**NOTE: C++/CX compilation is currently required in at least one file of your 
slouken@10486
   317
app's project.  This is to make sure that Visual C++'s linker builds a 'Windows 
slouken@10486
   318
Metadata' file (.winmd) for your app.  Not doing so can lead to build errors.**
slouken@10486
   319
flibitijibibo@12810
   320
For non-C++ projects, you will need to call SDL_WinRTRunApp from your language's
flibitijibibo@12810
   321
main function, and generate SDL2-WinRTResources.res manually by using `rc` via
flibitijibibo@12810
   322
the Developer Command Prompt and including it as a <Win32Resource> within the
flibitijibibo@12810
   323
first <PropertyGroup> block in your Visual Studio project file.
slouken@10486
   324
slouken@10486
   325
### 6. Add app code and assets ###
slouken@10486
   326
slouken@10486
   327
At this point, you can add in SDL-specific source code.  Be sure to include a 
slouken@10486
   328
C-style main function (ie: `int main(int argc, char *argv[])`).  From there you 
slouken@10486
   329
should be able to create a single `SDL_Window` (WinRT apps can only have one 
slouken@10486
   330
window, at present), as well as an `SDL_Renderer`.  Direct3D will be used to 
slouken@10486
   331
draw content.  Events are received via SDL's usual event functions 
slouken@10486
   332
(`SDL_PollEvent`, etc.)  If you have a set of existing source files and assets, 
slouken@10486
   333
you can start adding them to the project now.  If not, or if you would like to 
slouken@10486
   334
make sure that you're setup correctly, some short and simple sample code is 
slouken@10486
   335
provided below.
slouken@10486
   336
slouken@10486
   337
slouken@10486
   338
#### 6.A. ... when creating a new app ####
slouken@10486
   339
slouken@10486
   340
If you are creating a new app (rather than porting an existing SDL-based app), 
slouken@10486
   341
or if you would just like a simple app to test SDL/WinRT with before trying to 
slouken@10486
   342
get existing code working, some working SDL/WinRT code is provided below.  To 
slouken@10486
   343
set this up:
slouken@10486
   344
slouken@10486
   345
1. right click on your app's project
slouken@10486
   346
2. select Add, then New Item.  An "Add New Item" dialog will show up.
slouken@10486
   347
3. from the left-hand list, choose "Visual C++"
slouken@10486
   348
4. from the middle/main list, choose "C++ File (.cpp)"
slouken@10486
   349
5. near the bottom of the dialog, next to "Name:", type in a name for your 
slouken@10486
   350
source file, such as, "main.cpp".
slouken@10486
   351
6. click on the Add button.  This will close the dialog, add the new file to 
slouken@10486
   352
your project, and open the file in Visual C++'s text editor.
slouken@10486
   353
7. Copy and paste the following code into the new file, then save it.
slouken@10486
   354
slouken@10486
   355
slouken@10486
   356
    #include <SDL.h>
slouken@10486
   357
    
slouken@10486
   358
    int main(int argc, char **argv)
slouken@10486
   359
    {
slouken@10486
   360
        SDL_DisplayMode mode;
slouken@10486
   361
        SDL_Window * window = NULL;
slouken@10486
   362
        SDL_Renderer * renderer = NULL;
slouken@10486
   363
        SDL_Event evt;
slouken@10486
   364
    
slouken@10486
   365
        if (SDL_Init(SDL_INIT_VIDEO) != 0) {
slouken@10486
   366
            return 1;
slouken@10486
   367
        }
slouken@10486
   368
    
slouken@10486
   369
        if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
slouken@10486
   370
            return 1;
slouken@10486
   371
        }
slouken@10486
   372
    
slouken@10486
   373
        if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
slouken@10486
   374
            return 1;
slouken@10486
   375
        }
slouken@10486
   376
    
slouken@10486
   377
        while (1) {
slouken@10486
   378
            while (SDL_PollEvent(&evt)) {
slouken@10486
   379
            }
slouken@10486
   380
    
slouken@10486
   381
            SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
slouken@10486
   382
            SDL_RenderClear(renderer);
slouken@10486
   383
            SDL_RenderPresent(renderer);
slouken@10486
   384
        }
slouken@10486
   385
    }
slouken@10486
   386
slouken@10486
   387
slouken@10486
   388
#### 6.B. Adding code and assets ####
slouken@10486
   389
slouken@10486
   390
If you have existing code and assets that you'd like to add, you should be able 
slouken@10486
   391
to add them now.  The process for adding a set of files is as such.
slouken@10486
   392
slouken@10486
   393
1. right click on the app's project
slouken@10486
   394
2. select Add, then click on "New Item..."
slouken@10486
   395
3. open any source, header, or asset files as appropriate.  Support for C and 
slouken@10486
   396
C++ is available.
slouken@10486
   397
slouken@10486
   398
Do note that WinRT only supports a subset of the APIs that are available to 
slouken@10486
   399
Win32-based apps.  Many portions of the Win32 API and the C runtime are not 
slouken@10486
   400
available.
slouken@10486
   401
slouken@10486
   402
A list of unsupported C APIs can be found at 
slouken@10486
   403
<http://msdn.microsoft.com/en-us/library/windows/apps/jj606124.aspx>
slouken@10486
   404
slouken@10486
   405
General information on using the C runtime in WinRT can be found at 
slouken@10486
   406
<https://msdn.microsoft.com/en-us/library/hh972425.aspx>
slouken@10486
   407
slouken@10486
   408
A list of supported Win32 APIs for WinRT apps can be found at 
slouken@10486
   409
<http://msdn.microsoft.com/en-us/library/windows/apps/br205757.aspx>.  To note, 
slouken@10486
   410
the list of supported Win32 APIs for Windows Phone 8.0 is different.  
slouken@10486
   411
That list can be found at 
slouken@10486
   412
<http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj662956(v=vs.105).aspx>
slouken@10486
   413
slouken@10486
   414
slouken@10486
   415
### 7. Build and run your app ###
slouken@10486
   416
slouken@10486
   417
Your app project should now be setup, and you should be ready to build your app.  
slouken@10486
   418
To run it on the local machine, open the Debug menu and choose "Start 
slouken@10486
   419
Debugging".  This will build your app, then run your app full-screen.  To switch 
slouken@10486
   420
out of your app, press the Windows key.  Alternatively, you can choose to run 
slouken@10486
   421
your app in a window.  To do this, before building and running your app, find 
slouken@10486
   422
the drop-down menu in Visual C++'s toolbar that says, "Local Machine".  Expand 
slouken@10486
   423
this by clicking on the arrow on the right side of the list, then click on 
slouken@10486
   424
Simulator.  Once you do that, any time you build and run the app, the app will 
slouken@10486
   425
launch in window, rather than full-screen.
slouken@10486
   426
slouken@10486
   427
slouken@10486
   428
#### 7.A. Running apps on older, ARM-based, "Windows RT" devices ####
slouken@10486
   429
slouken@10486
   430
**These instructions do not include Windows Phone, despite Windows Phone
slouken@10486
   431
typically running on ARM processors.**  They are specifically for devices
slouken@10486
   432
that use the "Windows RT" operating system, which was a modified version of
slouken@10486
   433
Windows 8.x that ran primarily on ARM-based tablet computers.
slouken@10486
   434
slouken@10486
   435
To build and run the app on ARM-based, "Windows RT" devices, you'll need to:
slouken@10486
   436
slouken@10486
   437
- install Microsoft's "Remote Debugger" on the device.  Visual C++ installs and 
slouken@10486
   438
  debugs ARM-based apps via IP networks.
slouken@10486
   439
- change a few options on the development machine, both to make sure it builds 
slouken@10486
   440
  for ARM (rather than x86 or x64), and to make sure it knows how to find the 
slouken@10486
   441
  Windows RT device (on the network).
slouken@10486
   442
slouken@10486
   443
Microsoft's Remote Debugger can be found at 
slouken@10486
   444
<https://msdn.microsoft.com/en-us/library/hh441469.aspx>.  Please note 
slouken@10486
   445
that separate versions of this debugger exist for different versions of Visual 
slouken@10486
   446
C++, one each for MSVC 2015, 2013, and 2012.
slouken@10486
   447
slouken@10486
   448
To setup Visual C++ to launch your app on an ARM device:
slouken@10486
   449
slouken@10486
   450
1. make sure the Remote Debugger is running on your ARM device, and that it's on 
slouken@10486
   451
   the same IP network as your development machine.
slouken@10486
   452
2. from Visual C++'s toolbar, find a drop-down menu that says, "Win32".  Click 
slouken@10486
   453
   it, then change the value to "ARM".
slouken@10486
   454
3. make sure Visual C++ knows the hostname or IP address of the ARM device.  To 
slouken@10486
   455
   do this:
slouken@10486
   456
    1. open the app project's properties
slouken@10486
   457
    2. select "Debugging"
slouken@10486
   458
    3. next to "Machine Name", enter the hostname or IP address of the ARM 
slouken@10486
   459
       device
slouken@10486
   460
    4. if, and only if, you've turned off authentication in the Remote Debugger,
slouken@10486
   461
       then change the setting for "Require Authentication" to No
slouken@10486
   462
    5. click "OK"
slouken@10486
   463
4. build and run the app (from Visual C++).  The first time you do this, a 
slouken@10486
   464
   prompt will show up on the ARM device, asking for a Microsoft Account.  You 
slouken@10486
   465
   do, unfortunately, need to log in here, and will need to follow the 
slouken@10486
   466
   subsequent registration steps in order to launch the app.  After you do so, 
slouken@10486
   467
   if the app didn't already launch, try relaunching it again from within Visual 
slouken@10486
   468
   C++.
slouken@10486
   469
slouken@10486
   470
slouken@10486
   471
Troubleshooting
slouken@10486
   472
---------------
slouken@10486
   473
slouken@10486
   474
#### Build fails with message, "error LNK2038: mismatch detected for 'vccorlib_lib_should_be_specified_before_msvcrt_lib_to_linker'"
slouken@10486
   475
slouken@10486
   476
Try adding the following to your linker flags.  In MSVC, this can be done by
slouken@10486
   477
right-clicking on the app project, navigating to Configuration Properties ->
slouken@10486
   478
Linker -> Command Line, then adding them to the Additional Options
slouken@10486
   479
section.
slouken@10486
   480
slouken@10486
   481
* For Release builds / MSVC-Configurations, add:
slouken@10486
   482
slouken@10486
   483
    /nodefaultlib:vccorlib /nodefaultlib:msvcrt vccorlib.lib msvcrt.lib
slouken@10486
   484
slouken@10486
   485
* For Debug builds / MSVC-Configurations, add:
slouken@10486
   486
slouken@10486
   487
    /nodefaultlib:vccorlibd /nodefaultlib:msvcrtd vccorlibd.lib msvcrtd.lib
slouken@10486
   488
slouken@10486
   489
slouken@10486
   490
#### Mouse-motion events fail to get sent, or SDL_GetMouseState() fails to return updated values
slouken@10486
   491
slouken@10486
   492
This may be caused by a bug in Windows itself, whereby hiding the mouse
slouken@10486
   493
cursor can cause mouse-position reporting to fail.
slouken@10486
   494
slouken@10486
   495
SDL provides a workaround for this, but it requires that an app links to a
slouken@10486
   496
set of Win32-style cursor image-resource files.  A copy of suitable resource
slouken@10486
   497
files can be found in `src/main/winrt/`.  Adding them to an app's Visual C++
slouken@10486
   498
project file should be sufficient to get the app to use them.
dludwig@11446
   499
dludwig@11446
   500
dludwig@11446
   501
#### SDL's Visual Studio project file fails to open, with message, "The system can't find the file specified."
dludwig@11446
   502
dludwig@11446
   503
This can be caused for any one of a few reasons, which Visual Studio can
dludwig@11446
   504
report, but won't always do so in an up-front manner.
dludwig@11446
   505
dludwig@11446
   506
To help determine why this error comes up:
dludwig@11446
   507
dludwig@11446
   508
1. open a copy of Visual Studio without opening a project file.  This can be
dludwig@11446
   509
   accomplished via Windows' Start Menu, among other means.
dludwig@11446
   510
2. show Visual Studio's Output window.  This can be done by going to VS'
dludwig@11446
   511
   menu bar, then to View, and then to Output.
dludwig@11446
   512
3. try opening the SDL project file directly by going to VS' menu bar, then
dludwig@11446
   513
   to File, then to Open, then to Project/Solution.  When a File-Open dialog
dludwig@11446
   514
   appears, open the SDL project (such as the one in SDL's source code, in its
dludwig@11446
   515
   directory, VisualC-WinRT/UWP_VS2015/).
dludwig@11446
   516
4. after attempting to open SDL's Visual Studio project file, additional error
dludwig@11446
   517
   information will be output to the Output window.
dludwig@11446
   518
dludwig@11446
   519
If Visual Studio reports (via its Output window) that the project:
dludwig@11446
   520
dludwig@11446
   521
"could not be loaded because it's missing install components. To fix this launch Visual Studio setup with the following selections:
dludwig@11446
   522
Microsoft.VisualStudio.ComponentGroup.UWP.VC"
dludwig@11446
   523
dludwig@11446
   524
... then you will need to re-launch Visual Studio's installer, and make sure that
dludwig@11446
   525
the workflow for "Universal Windows Platform development" is checked, and that its
dludwig@11446
   526
optional component, "C++ Universal Windows Platform tools" is also checked.  While
dludwig@11446
   527
you are there, if you are planning on targeting UWP / Windows 10, also make sure
dludwig@11446
   528
that you check the optional component, "Windows 10 SDK (10.0.10240.0)".  After
dludwig@11446
   529
making sure these items are checked as-appropriate, install them.
dludwig@11446
   530
dludwig@11446
   531
Once you install these components, try re-launching Visual Studio, and re-opening
dludwig@11446
   532
the SDL project file.  If you still get the error dialog, try using the Output
dludwig@11446
   533
window, again, seeing what Visual Studio says about it.
dludwig@11502
   534
dludwig@11503
   535
dludwig@11502
   536
#### Game controllers / joysticks aren't working!
dludwig@11502
   537
dludwig@11502
   538
Windows only permits certain game controllers and joysticks to work within
dludwig@11502
   539
WinRT / UWP apps.  Even if a game controller or joystick works in a Win32
dludwig@11502
   540
app, that device is not guaranteed to work inside a WinRT / UWP app.
dludwig@11502
   541
dludwig@11502
   542
According to Microsoft, "Xbox compatible controllers" should work inside
dludwig@11502
   543
UWP apps, potentially with more working in the future.  This includes, but
dludwig@11502
   544
may not be limited to, Microsoft-made Xbox controllers and USB adapters.
dludwig@11502
   545
(Source: https://social.msdn.microsoft.com/Forums/en-US/9064838b-e8c3-4c18-8a83-19bf0dfe150d/xinput-fails-to-detect-game-controllers?forum=wpdevelop)
dludwig@11502
   546
dludwig@11502
   547