docs/README-winrt.md
changeset 9931 0bb3dd1c95f2
parent 9390 afd88e715bd7
child 10155 78685b1711c6
     1.1 --- a/docs/README-winrt.md	Thu Nov 26 13:51:03 2015 -0500
     1.2 +++ b/docs/README-winrt.md	Sun Nov 29 19:33:11 2015 -0500
     1.3 @@ -10,6 +10,7 @@
     1.4  
     1.5  Some of the operating systems that include WinRT, are:
     1.6  
     1.7 +* Windows 10, via its Universal Windows Platform (UWP) APIs
     1.8  * Windows 8.x
     1.9  * Windows RT 8.x (aka. Windows 8.x for ARM processors)
    1.10  * Windows Phone 8.x
    1.11 @@ -18,12 +19,12 @@
    1.12  Requirements
    1.13  ------------
    1.14  
    1.15 -* Microsoft Visual C++ (aka Visual Studio), either 2013 or 2012 versions
    1.16 +* Microsoft Visual C++ (aka Visual Studio), either 2015, 2013, or 2012
    1.17    - Free, "Community" or "Express" editions may be used, so long as they
    1.18      include  support for either "Windows Store" or "Windows Phone" apps.
    1.19      "Express" versions marked as supporting "Windows Desktop" development
    1.20      typically do not include support for creating WinRT apps, to note.
    1.21 -    (The "Community" edition of Visual C++ 2013 does, however, support both
    1.22 +    (The "Community" editions of Visual C++ do, however, support both
    1.23      desktop/Win32 and WinRT development).
    1.24    - Visual C++ 2012 can only build apps that target versions 8.0 of Windows,
    1.25      or  Windows Phone.  8.0-targetted apps will run on devices running 8.1
    1.26 @@ -50,25 +51,21 @@
    1.27  Here is a rough list of what works, and what doens't:
    1.28  
    1.29  * What works:
    1.30 -  * compilation via Visual C++ 2012 and 2013
    1.31 +  * compilation via Visual C++ 2012 through 2015
    1.32    * compile-time platform detection for SDL programs.  The C/C++ #define,
    1.33      `__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
    1.34    * GPU-accelerated 2D rendering, via SDL_Renderer.
    1.35 +  * OpenGL ES 2, via the ANGLE library (included separately from SDL)
    1.36    * software rendering, via either SDL_Surface (optionally in conjunction with
    1.37      SDL_GetWindowSurface() and SDL_UpdateWindowSurface()) or via the
    1.38      SDL_Renderer APIs
    1.39 -  * threads.  Significant chunks of Win32's threading APIs are not available in
    1.40 -    WinRT.  A new, SDL threading backend was built using C++11's threading APIs
    1.41 -    (std::thread, std::mutex, std::condition_variable, etc.), which C or C++
    1.42 -    programs alike can access via SDL's threading APIs.  Support for thread
    1.43 -    priorities is not, however, currently available, due to restrictions in
    1.44 -    WinRT's own API set.
    1.45 +  * threads
    1.46    * timers (via SDL_GetTicks(), SDL_AddTimer(), SDL_GetPerformanceCounter(),
    1.47      SDL_GetPerformanceFrequency(), etc.)
    1.48    * file I/O via SDL_RWops
    1.49    * mouse input  (unsupported on Windows Phone)
    1.50    * audio, via a modified version of SDL's XAudio2 backend
    1.51 -  * .DLL file loading.  Libraries must be packaged inside applications.  Loading
    1.52 +  * .DLL file loading.  Libraries *MUST* be packaged inside applications.  Loading
    1.53      anything outside of the app is not supported.
    1.54    * system path retrieval via SDL's filesystem APIs
    1.55    * game controllers.  Support is provided via the SDL_Joystick and
    1.56 @@ -76,10 +73,7 @@
    1.57    * multi-touch input
    1.58    * app events.  SDL_APP_WILLENTER* and SDL_APP_DIDENTER* events get sent out as
    1.59      appropriate.
    1.60 -  * window events.  SDL_WINDOWEVENT_MINIMIZED and SDL_WINDOWEVENT_RESTORED are
    1.61 -    sent out on app suspend and resume, respectively.  SDL_WINDOWEVENT_SHOWN and
    1.62 -    SDL_WINDOWEVENT_HIDDEN are also sent, but not necessarily on app suspend or
    1.63 -    resume, as WinRT treats these two concepts differently..
    1.64 +  * window events
    1.65    * using Direct3D 11.x APIs outside of SDL.  Non-XAML / Direct3D-only apps can
    1.66      choose to render content directly via Direct3D, using SDL to manage the
    1.67      internal WinRT window, as well as input and audio.  (Use
    1.68 @@ -89,24 +83,13 @@
    1.69  * What partially works:
    1.70    * keyboard input.  Most of WinRT's documented virtual keys are supported, as
    1.71      well as many keys with documented hardware scancodes.
    1.72 -  * OpenGL.  Experimental support for OpenGL ES 2 is available via the ANGLE
    1.73 -    project, using either:
    1.74 -    * MS Open Technologies' "ms-master" repository, at https://github.com/MSOpenTech/angle
    1.75 -      (for use with Windows 8.1+ or Windows Phone 8.1+)
    1.76 -    * MS Open Technologies' "angle-win8.0" repository, at https://github.com/MSOpenTech/angle-win8.0
    1.77 -      (for Windows 8.0 only!)
    1.78 -    * Google's main ANGLE repository, at https://chromium.googlesource.com/angle/angle
    1.79    * SDLmain.  WinRT uses a different signature for each app's main() function.
    1.80      SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
    1.81      (in `SDL\src\main\winrt\`) directly in order for their C-style main()
    1.82      functions to be called.
    1.83 -  * XAML interoperability.  This feature is currently experimental (there are
    1.84 -    **many** known bugs in this, at present!), preliminary, and only for
    1.85 -    Windows 8.x/RT at the moment.  Windows Phone + XAML support is still
    1.86 -    pending.
    1.87  
    1.88  * What doesn't work:
    1.89 -  * compilation with anything other than Visual C++ 2012 or 2013
    1.90 +  * compilation with anything other than Visual C++
    1.91    * programmatically-created custom cursors.  These don't appear to be supported
    1.92      by WinRT.  Different OS-provided cursors can, however, be created via
    1.93      SDL_CreateSystemCursor() (unsupported on Windows Phone)
    1.94 @@ -236,10 +219,10 @@
    1.95  4. find SDL/WinRT's Visual C++ project file and open it.  Different project
    1.96     files exist for different WinRT platforms.  All of them are in SDL's
    1.97     source distribution, in the following directories:
    1.98 -    * `VisualC-WinRT/WinPhone80_VS2012/` - for Windows Phone 8.0 apps
    1.99 +    * `VisualC-WinRT/UWP_VS2015/`        - for Windows 10 / UWP apps
   1.100      * `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
   1.101 -    * `VisualC-WinRT/WinRT80_VS2012/` - for Windows 8.0 apps
   1.102 -    * `VisualC-WinRT/WinRT81_VS2013/` - for Windows 8.1 apps
   1.103 +    * `VisualC-WinRT/WinRT80_VS2012/`    - for Windows 8.0 apps
   1.104 +    * `VisualC-WinRT/WinRT81_VS2013/`    - for Windows 8.1 apps
   1.105  5. once the project has been added, right-click on your app's project and
   1.106     select, "References..."
   1.107  6. click on the button titled, "Add New Reference..."
   1.108 @@ -400,11 +383,11 @@
   1.109  <http://msdn.microsoft.com/en-us/library/windows/apps/jj606124.aspx>
   1.110  
   1.111  General information on using the C runtime in WinRT can be found at 
   1.112 -<http://msdn.microsoft.com/en-us/LIBRARY/hh972425(v=vs.110).aspx>
   1.113 +<https://msdn.microsoft.com/en-us/library/hh972425.aspx>
   1.114  
   1.115 -A list of supported Win32 APIs for Windows 8/RT apps can be found at 
   1.116 +A list of supported Win32 APIs for WinRT apps can be found at 
   1.117  <http://msdn.microsoft.com/en-us/library/windows/apps/br205757.aspx>.  To note, 
   1.118 -the list of supported Win32 APIs for Windows Phone 8 development is different.  
   1.119 +the list of supported Win32 APIs for Windows Phone 8.0 is different.  
   1.120  That list can be found at 
   1.121  <http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj662956(v=vs.105).aspx>
   1.122  
   1.123 @@ -422,7 +405,12 @@
   1.124  launch in window, rather than full-screen.
   1.125  
   1.126  
   1.127 -#### 7.A. Running apps on ARM-based devices ####
   1.128 +#### 7.A. Running apps on older, ARM-based, "Windows RT" devices ####
   1.129 +
   1.130 +**These instructions do not include Windows Phone, despite Windows Phone
   1.131 +typically running on ARM processors.**  They are specifically for devices
   1.132 +that use the "Windows RT" operating system, which was a modified version of
   1.133 +Windows 8.x that ran primarily on ARM-based tablet computers.
   1.134  
   1.135  To build and run the app on ARM-based, "Windows RT" devices, you'll need to:
   1.136  
   1.137 @@ -433,9 +421,9 @@
   1.138    Windows RT device (on the network).
   1.139  
   1.140  Microsoft's Remote Debugger can be found at 
   1.141 -<http://msdn.microsoft.com/en-us/library/vstudio/bt727f1t.aspx>.  Please note 
   1.142 +<https://msdn.microsoft.com/en-us/library/hh441469.aspx>.  Please note 
   1.143  that separate versions of this debugger exist for different versions of Visual 
   1.144 -C++, one for debugging with MSVC 2012, another for debugging with MSVC 2013.
   1.145 +C++, one each for MSVC 2015, 2013, and 2012.
   1.146  
   1.147  To setup Visual C++ to launch your app on an ARM device:
   1.148