docs/README-winrt.md
author Philipp Wiesemann <philipp.wiesemann@arcor.de>
Wed, 17 Aug 2016 21:04:50 +0200
changeset 10275 ba7dc3ebb81e
parent 10171 5b61e12c0a30
permissions -rw-r--r--
Emscripten: Fixed opening previously closed joystick.
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.