docs/README-winrt.md
author Ryan C. Gordon <icculus@icculus.org>
Fri, 12 Aug 2016 19:59:00 -0400
changeset 10266 c09f06c4e8c8
parent 10171 5b61e12c0a30
permissions -rw-r--r--
emscripten: send fake mouse events for touches, like other targets do. (This really should be handled at the higher level and not in the individual targets, but this fixes the immediate bug.)
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
9150
5c42e467f6cd WinRT: cleaned up the opening section of the README
David Ludwig <dludwig@pobox.com>
parents: 9149
diff changeset
     4
This port allows SDL applications to run on Microsoft's platforms that require
10155
78685b1711c6 WinRT: README tweaks
David Ludwig <dludwig@pobox.com>
parents: 9931
diff changeset
     5
use of "Windows Runtime", aka. "WinRT", APIs.  Microsoft may, in some cases,
10156
80e408941b90 WinRT: another README tweak
David Ludwig <dludwig@pobox.com>
parents: 10155
diff changeset
     6
refer to them as either "Windows Store", or for Windows 10, "UWP" apps.
9150
5c42e467f6cd WinRT: cleaned up the opening section of the README
David Ludwig <dludwig@pobox.com>
parents: 9149
diff changeset
     7
5c42e467f6cd WinRT: cleaned up the opening section of the README
David Ludwig <dludwig@pobox.com>
parents: 9149
diff changeset
     8
Some of the operating systems that include WinRT, are:
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
     9
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
    10
* Windows 10, via its Universal Windows Platform (UWP) APIs
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
    11
* Windows 8.x
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
    12
* 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
    13
* Windows Phone 8.x
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
    14
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
    15
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
    16
Requirements
9137
b0b056a7b932 WinRT: cleaned up section headers
David Ludwig <dludwig@pobox.com>
parents: 9025
diff changeset
    17
------------
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
    18
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
    19
* Microsoft Visual C++ (aka Visual Studio), either 2015, 2013, or 2012
9224
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    20
  - Free, "Community" or "Express" editions may be used, so long as they
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    21
    include  support for either "Windows Store" or "Windows Phone" apps.
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    22
    "Express" versions marked as supporting "Windows Desktop" development
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    23
    typically do not include support for creating WinRT apps, to note.
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
    24
    (The "Community" editions of Visual C++ do, however, support both
9224
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    25
    desktop/Win32 and WinRT development).
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    26
  - Visual C++ 2012 can only build apps that target versions 8.0 of Windows,
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    27
    or  Windows Phone.  8.0-targetted apps will run on devices running 8.1
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    28
    editions of Windows, however they will not be able to take advantage of
9140
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.
9224
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    30
  - Visual C++ 2013 cannot create app projects that target Windows 8.0.
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    31
    Visual C++ 2013 Update 4, can create app projects for Windows Phone 8.0,
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    32
    Windows Phone 8.1, and Windows 8.1, but not Windows 8.0.  An optional
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    33
    Visual Studio add-in, "Tools for Maintaining Store apps for Windows 8",
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    34
    allows Visual C++ 2013 to load and build Windows 8.0 projects that were
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    35
    created with Visual C++ 2012, so long as Visual C++ 2012 is installed
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    36
    on the same machine.  More details on targeting different versions of
bc074eca6597 WinRT: updated README-winrt.md to detail Visual Studio 2013 Community support
David Ludwig <dludwig@pobox.com>
parents: 9215
diff changeset
    37
    Windows can found at the following web pages:
9140
3d8e33a24c31 WinRT: expanded and updated the README section on MSVC requirements
David Ludwig <dludwig@pobox.com>
parents: 9139
diff changeset
    38
      - [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
    39
      - [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
    40
* 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
    41
  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
    42
  debug apps.
9139
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
9208
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    45
Status
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    46
------
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    47
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    48
Here is a rough list of what works, and what doens't:
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    49
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    50
* What works:
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
    51
  * compilation via Visual C++ 2012 through 2015
9208
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    52
  * compile-time platform detection for SDL programs.  The C/C++ #define,
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    53
    `__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    54
  * GPU-accelerated 2D rendering, via SDL_Renderer.
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
    55
  * OpenGL ES 2, via the ANGLE library (included separately from SDL)
9208
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    56
  * software rendering, via either SDL_Surface (optionally in conjunction with
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    57
    SDL_GetWindowSurface() and SDL_UpdateWindowSurface()) or via the
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    58
    SDL_Renderer APIs
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
    59
  * threads
9208
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    60
  * timers (via SDL_GetTicks(), SDL_AddTimer(), SDL_GetPerformanceCounter(),
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    61
    SDL_GetPerformanceFrequency(), etc.)
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    62
  * file I/O via SDL_RWops
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    63
  * mouse input  (unsupported on Windows Phone)
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    64
  * audio, via a modified version of SDL's XAudio2 backend
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
    65
  * .DLL file loading.  Libraries *MUST* be packaged inside applications.  Loading
9208
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    66
    anything outside of the app is not supported.
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    67
  * system path retrieval via SDL's filesystem APIs
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    68
  * game controllers.  Support is provided via the SDL_Joystick and
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    69
    SDL_GameController APIs, and is backed by Microsoft's XInput API.
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    70
  * multi-touch input
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    71
  * app events.  SDL_APP_WILLENTER* and SDL_APP_DIDENTER* events get sent out as
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    72
    appropriate.
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
    73
  * window events
9208
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    74
  * using Direct3D 11.x APIs outside of SDL.  Non-XAML / Direct3D-only apps can
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    75
    choose to render content directly via Direct3D, using SDL to manage the
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    76
    internal WinRT window, as well as input and audio.  (Use
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    77
    SDL_GetWindowWMInfo() to get the WinRT 'CoreWindow', and pass it into
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    78
    IDXGIFactory2::CreateSwapChainForCoreWindow() as appropriate.)
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    79
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    80
* What partially works:
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    81
  * keyboard input.  Most of WinRT's documented virtual keys are supported, as
10155
78685b1711c6 WinRT: README tweaks
David Ludwig <dludwig@pobox.com>
parents: 9931
diff changeset
    82
    well as many keys with documented hardware scancodes.  Converting
78685b1711c6 WinRT: README tweaks
David Ludwig <dludwig@pobox.com>
parents: 9931
diff changeset
    83
    SDL_Scancodes to or from SDL_Keycodes may not work, due to missing APIs
78685b1711c6 WinRT: README tweaks
David Ludwig <dludwig@pobox.com>
parents: 9931
diff changeset
    84
    (MapVirualKey()) in Microsoft's Windows Store / UWP APIs.
9208
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    85
  * SDLmain.  WinRT uses a different signature for each app's main() function.
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    86
    SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    87
    (in `SDL\src\main\winrt\`) directly in order for their C-style main()
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    88
    functions to be called.
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    89
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    90
* What doesn't work:
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
    91
  * compilation with anything other than Visual C++
9208
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    92
  * programmatically-created custom cursors.  These don't appear to be supported
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    93
    by WinRT.  Different OS-provided cursors can, however, be created via
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    94
    SDL_CreateSystemCursor() (unsupported on Windows Phone)
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    95
  * SDL_WarpMouseInWindow() or SDL_WarpMouseGlobal().  This are not currently
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    96
    supported by WinRT itself.
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    97
  * joysticks and game controllers that aren't supported by Microsoft's XInput
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
    98
    API.
9335
3eb0896ecb91 WinRT: made note that VSync is always enabled on WinPhone, due to OS
David Ludwig <dludwig@pobox.com>
parents: 9255
diff changeset
    99
  * turning off VSync when rendering on Windows Phone.  Attempts to turn VSync
3eb0896ecb91 WinRT: made note that VSync is always enabled on WinPhone, due to OS
David Ludwig <dludwig@pobox.com>
parents: 9255
diff changeset
   100
    off on Windows Phone result either in Direct3D not drawing anything, or it
3eb0896ecb91 WinRT: made note that VSync is always enabled on WinPhone, due to OS
David Ludwig <dludwig@pobox.com>
parents: 9255
diff changeset
   101
    forcing VSync back on.  As such, SDL_RENDERER_PRESENTVSYNC will always get
3eb0896ecb91 WinRT: made note that VSync is always enabled on WinPhone, due to OS
David Ludwig <dludwig@pobox.com>
parents: 9255
diff changeset
   102
    turned-on on Windows Phone.  This limitation is not present in non-Phone
3eb0896ecb91 WinRT: made note that VSync is always enabled on WinPhone, due to OS
David Ludwig <dludwig@pobox.com>
parents: 9255
diff changeset
   103
    WinRT (such as Windows 8.x), where turning off VSync appears to work.
9208
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
   104
  * probably anything else that's not listed as supported
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
   105
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
   106
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
   107
9255
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   108
Upgrade Notes
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   109
-------------
9242
f4d353bd5d16 WinRT: added SDL_HINT_WINRT_PREF_PATH_ROOT
David Ludwig <dludwig@pobox.com>
parents: 9224
diff changeset
   110
9255
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   111
#### SDL_GetPrefPath() usage when upgrading WinRT apps from SDL 2.0.3
9247
eddb899239fe WinRT: bug and data-integrity fixes for SDL_GetPrefPath()
David Ludwig <dludwig@pobox.com>
parents: 9242
diff changeset
   112
9255
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   113
SDL 2.0.4 fixes two bugs found in the WinRT version of SDL_GetPrefPath().
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   114
The fixes may affect older, SDL 2.0.3-based apps' save data.  Please note
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   115
that these changes only apply to SDL-based WinRT apps, and not to apps for
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   116
any other platform.
9242
f4d353bd5d16 WinRT: added SDL_HINT_WINRT_PREF_PATH_ROOT
David Ludwig <dludwig@pobox.com>
parents: 9224
diff changeset
   117
9255
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   118
1. SDL_GetPrefPath() would return an invalid path, one in which the path's
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   119
   directory had not been created.  Attempts to create files there
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   120
   (via fopen(), for example), would fail, unless that directory was
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   121
   explicitly created beforehand.
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   122
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   123
2. SDL_GetPrefPath(), for non-WinPhone-based apps, would return a path inside
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   124
   a WinRT 'Roaming' folder, the contents of which get automatically
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   125
   synchronized across multiple devices.  This process can occur while an
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   126
   application runs, and can cause existing save-data to be overwritten
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   127
   at unexpected times, with data from other devices.  (Windows Phone apps
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   128
   written with SDL 2.0.3 did not utilize a Roaming folder, due to API
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   129
   restrictions in Windows Phone 8.0).
9247
eddb899239fe WinRT: bug and data-integrity fixes for SDL_GetPrefPath()
David Ludwig <dludwig@pobox.com>
parents: 9242
diff changeset
   130
eddb899239fe WinRT: bug and data-integrity fixes for SDL_GetPrefPath()
David Ludwig <dludwig@pobox.com>
parents: 9242
diff changeset
   131
eddb899239fe WinRT: bug and data-integrity fixes for SDL_GetPrefPath()
David Ludwig <dludwig@pobox.com>
parents: 9242
diff changeset
   132
SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
eddb899239fe WinRT: bug and data-integrity fixes for SDL_GetPrefPath()
David Ludwig <dludwig@pobox.com>
parents: 9242
diff changeset
   133
eddb899239fe WinRT: bug and data-integrity fixes for SDL_GetPrefPath()
David Ludwig <dludwig@pobox.com>
parents: 9242
diff changeset
   134
1. making sure that SDL_GetPrefPath() returns a directory in which data
eddb899239fe WinRT: bug and data-integrity fixes for SDL_GetPrefPath()
David Ludwig <dludwig@pobox.com>
parents: 9242
diff changeset
   135
   can be written to immediately, without first needing to create directories.
9242
f4d353bd5d16 WinRT: added SDL_HINT_WINRT_PREF_PATH_ROOT
David Ludwig <dludwig@pobox.com>
parents: 9224
diff changeset
   136
9255
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   137
2. basing SDL_GetPrefPath() off of a different, non-Roaming folder, the
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   138
   contents of which do not automatically get synchronized across devices
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   139
   (and which require less work to use safely, in terms of data integrity).
9242
f4d353bd5d16 WinRT: added SDL_HINT_WINRT_PREF_PATH_ROOT
David Ludwig <dludwig@pobox.com>
parents: 9224
diff changeset
   140
9255
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   141
Apps that wish to get their Roaming folder's path can do so either by using
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   142
SDL_WinRTGetFSPathUTF8(), SDL_WinRTGetFSPathUNICODE() (which returns a
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   143
UCS-2/wide-char string), or directly through the WinRT class,
c2ef0d8d6da0 WinRT: removed SDL_HINT_WINRT_PREF_PATH_ROOT (introduced post-2.0.3 & pre-2.0.4)
David Ludwig <dludwig@pobox.com>
parents: 9247
diff changeset
   144
Windows.Storage.ApplicationData.
9242
f4d353bd5d16 WinRT: added SDL_HINT_WINRT_PREF_PATH_ROOT
David Ludwig <dludwig@pobox.com>
parents: 9224
diff changeset
   145
f4d353bd5d16 WinRT: added SDL_HINT_WINRT_PREF_PATH_ROOT
David Ludwig <dludwig@pobox.com>
parents: 9224
diff changeset
   146
9208
a396a375e6c5 WinRT: added details of the port's status, to README-winrt.md
David Ludwig <dludwig@pobox.com>
parents: 9200
diff changeset
   147
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   148
Setup, High-Level Steps
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   149
-----------------------
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   150
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   151
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
   152
following, at a high-level:
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   153
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   154
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
   155
   "Direct3D App".
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   156
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
   157
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
   158
   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
   159
   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
   160
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
   161
   header files.
10171
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   162
5. add files that contains a WinRT-appropriate main function, along with some
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   163
   data to make sure mouse-cursor-hiding (via SDL_ShowCursor(SDL_DISABLE) calls)
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   164
   work properly.
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   165
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
   166
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
   167
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   168
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   169
Setup, Detailed Steps
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   170
---------------------
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   171
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   172
### 1. Create a new project ###
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   173
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   174
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
   175
"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
   176
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
   177
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
   178
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   179
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   180
### 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
   181
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   182
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
   183
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   184
- .cpp
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   185
- .h
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   186
- .hlsl
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   187
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   188
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
   189
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
   190
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   191
- 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
   192
  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
   193
- 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
   194
  launches), others are app icons.
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   195
- 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
   196
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   197
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   198
### 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
   199
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   200
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
   201
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
   202
(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
   203
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
   204
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
   205
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
   206
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
   207
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
   208
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   209
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
   210
   platform(s).
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   211
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
   212
   output.
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   213
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   214
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
   215
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   216
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
   217
   "Solution Explorer")
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   218
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
   219
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
   220
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
   221
   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
   222
   source distribution, in the following directories:
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   223
    * `VisualC-WinRT/UWP_VS2015/`        - for Windows 10 / UWP apps
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   224
    * `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   225
    * `VisualC-WinRT/WinRT80_VS2012/`    - for Windows 8.0 apps
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   226
    * `VisualC-WinRT/WinRT81_VS2013/`    - for Windows 8.1 apps
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   227
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
   228
   select, "References..."
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   229
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
   230
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
   231
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
   232
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
   233
   dialog.
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   234
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   235
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
   236
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
   237
your app.
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   238
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   239
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   240
### 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
   241
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   242
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
   243
outline the following:
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   244
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   245
- 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
   246
- **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
   247
  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
   248
- **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
   249
  precompiled header files.
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   250
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   251
To change these settings:
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   252
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   253
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
   254
2. choose "Properties"
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   255
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
   256
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
   257
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
   258
6. select "General"
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   259
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
   260
   "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
   261
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
   262
   "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
   263
   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
   264
   omitted.
9149
e910a192f68f WinRT: fixed broken emphasis formatting in README, when rendering it with Doxygen
David Ludwig <dludwig@pobox.com>
parents: 9143
diff changeset
   265
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
   266
   '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
   267
   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
   268
   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
   269
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
   270
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   271
10171
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   272
### 5. Add a WinRT-appropriate main function, and a blank-cursor image, to the app. ###
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   273
10171
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   274
A few files should be included directly in your app's MSVC project, specifically:
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   275
1. a WinRT-appropriate main function (which is different than main() functions on
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   276
   other platforms)
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   277
2. a Win32-style cursor resource, used by SDL_ShowCursor() to hide the mouse cursor
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   278
   (if and when the app needs to do so).  *If this cursor resource is not
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   279
   included, mouse-position reporting may fail if and when the cursor is
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   280
   hidden, due to possible bugs/design-oddities in Windows itself.*
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   281
10171
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   282
To include these files:
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   283
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   284
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
   285
   navigate to "Add", then choose "Existing Item...".
10171
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   286
2. navigate to the directory containing SDL's source code, then into its
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   287
   subdirectory, 'src/main/winrt/'.  Select, then add, the following files:
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   288
   - `SDL_winrt_main_NonXAML.cpp`
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   289
   - `SDL2-WinRTResources.rc`
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   290
   - `SDL2-WinRTResource_BlankCursor.cur`
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   291
3. right-click on the file `SDL_winrt_main_NonXAML.cpp` (as listed in your
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   292
   project), then click on "Properties...".
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   293
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
   294
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
   295
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
   296
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
   297
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
   298
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   299
10171
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   300
**NOTE: C++/CX compilation is currently required in at least one file of your 
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   301
app's project.  This is to make sure that Visual C++'s linker builds a 'Windows 
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   302
Metadata' file (.winmd) for your app.  Not doing so can lead to build errors.**
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   303
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   304
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   305
### 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
   306
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   307
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
   308
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
   309
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
   310
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
   311
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
   312
(`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
   313
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
   314
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
   315
provided below.
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   316
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
#### 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
   319
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   320
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
   321
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
   322
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
   323
set this up:
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   324
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   325
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
   326
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
   327
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
   328
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
   329
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
   330
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
   331
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
   332
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
   333
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
   334
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   335
9143
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   336
    #include <SDL.h>
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   337
    
9143
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   338
    int main(int argc, char **argv)
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   339
    {
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   340
        SDL_DisplayMode mode;
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   341
        SDL_Window * window = NULL;
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   342
        SDL_Renderer * renderer = NULL;
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   343
        SDL_Event evt;
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   344
    
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   345
        if (SDL_Init(SDL_INIT_VIDEO) != 0) {
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   346
            return 1;
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   347
        }
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   348
    
9143
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   349
        if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   350
            return 1;
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   351
        }
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   352
    
9143
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   353
        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
   354
            return 1;
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   355
        }
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   356
    
9143
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   357
        while (1) {
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   358
            while (SDL_PollEvent(&evt)) {
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   359
            }
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   360
    
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   361
            SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   362
            SDL_RenderClear(renderer);
b664273a455c Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9141
diff changeset
   363
            SDL_RenderPresent(renderer);
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   364
        }
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   365
    }
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   366
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   367
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   368
#### 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
   369
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   370
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
   371
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
   372
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   373
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
   374
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
   375
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
   376
C++ is available.
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   377
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   378
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
   379
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
   380
available.
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   381
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   382
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
   383
<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
   384
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   385
General information on using the C runtime in WinRT can be found at 
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   386
<https://msdn.microsoft.com/en-us/library/hh972425.aspx>
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   387
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   388
A list of supported Win32 APIs for WinRT apps can be found at 
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   389
<http://msdn.microsoft.com/en-us/library/windows/apps/br205757.aspx>.  To note, 
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   390
the list of supported Win32 APIs for Windows Phone 8.0 is different.  
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   391
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
   392
<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
   393
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   394
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   395
### 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
   396
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   397
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
   398
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
   399
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
   400
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
   401
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
   402
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
   403
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
   404
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
   405
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
   406
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   407
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   408
#### 7.A. Running apps on older, ARM-based, "Windows RT" devices ####
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   409
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   410
**These instructions do not include Windows Phone, despite Windows Phone
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   411
typically running on ARM processors.**  They are specifically for devices
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   412
that use the "Windows RT" operating system, which was a modified version of
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   413
Windows 8.x that ran primarily on ARM-based tablet computers.
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   414
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   415
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
   416
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   417
- 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
   418
  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
   419
- 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
   420
  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
   421
  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
   422
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   423
Microsoft's Remote Debugger can be found at 
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   424
<https://msdn.microsoft.com/en-us/library/hh441469.aspx>.  Please note 
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   425
that separate versions of this debugger exist for different versions of Visual 
9931
0bb3dd1c95f2 WinRT: added Win10/UWP (Universal Windows Platform) support
David Ludwig <dludwig@pobox.com>
parents: 9390
diff changeset
   426
C++, one each for MSVC 2015, 2013, and 2012.
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   427
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   428
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
   429
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   430
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
   431
   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
   432
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
   433
   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
   434
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
   435
   do this:
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   436
    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
   437
    2. select "Debugging"
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   438
    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
   439
       device
9209
e78fb0f4f9f9 WinRT: made README-winrt.md slightly easier to read in an 80-column text editor
David Ludwig <dludwig@pobox.com>
parents: 9208
diff changeset
   440
    4. if, and only if, you've turned off authentication in the Remote Debugger,
e78fb0f4f9f9 WinRT: made README-winrt.md slightly easier to read in an 80-column text editor
David Ludwig <dludwig@pobox.com>
parents: 9208
diff changeset
   441
       then change the setting for "Require Authentication" to No
9139
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   442
    5. click "OK"
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   443
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
   444
   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
   445
   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
   446
   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
   447
   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
   448
   C++.
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   449
b2231eba36f5 WinRT: added manual, app-setup instructions to the README
David Ludwig <dludwig@pobox.com>
parents: 9138
diff changeset
   450
9200
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   451
Troubleshooting
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   452
---------------
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   453
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   454
#### Build fails with message, "error LNK2038: mismatch detected for 'vccorlib_lib_should_be_specified_before_msvcrt_lib_to_linker'"
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   455
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   456
Try adding the following to your linker flags.  In MSVC, this can be done by
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   457
right-clicking on the app project, navigating to Configuration Properties ->
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   458
Linker -> Command Line, then adding them to the Additional Options
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   459
section.
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   460
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   461
* For Release builds / MSVC-Configurations, add:
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   462
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   463
    /nodefaultlib:vccorlib /nodefaultlib:msvcrt vccorlib.lib msvcrt.lib
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   464
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   465
* For Debug builds / MSVC-Configurations, add:
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   466
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   467
    /nodefaultlib:vccorlibd /nodefaultlib:msvcrtd vccorlibd.lib msvcrtd.lib
bfdc18891a60 WinRT: detailed steps, via the WinRT README, to fix a common build error
David Ludwig <dludwig@pobox.com>
parents: 9150
diff changeset
   468
10171
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   469
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   470
#### Mouse-motion events fail to get sent, or SDL_GetMouseState() fails to return updated values
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   471
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   472
This may be caused by a bug in Windows itself, whereby hiding the mouse
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   473
cursor can cause mouse-position reporting to fail.
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   474
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   475
SDL provides a workaround for this, but it requires that an app links to a
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   476
set of Win32-style cursor image-resource files.  A copy of suitable resource
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   477
files can be found in `src/main/winrt/`.  Adding them to an app's Visual C++
5b61e12c0a30 WinRT: workaround a possible Windows bug, whereby hiding cursors, disables mouse-moved events
David Ludwig <dludwig@pobox.com>
parents: 10156
diff changeset
   478
project file should be sufficient to get the app to use them.