docs/README-winrt.md
changeset 9208 a396a375e6c5
parent 9200 bfdc18891a60
child 9209 e78fb0f4f9f9
equal deleted inserted replaced
9207:10f4459a8b9a 9208:a396a375e6c5
    39 * A valid Microsoft account - This requirement is not imposed by SDL, but
    39 * A valid Microsoft account - This requirement is not imposed by SDL, but
    40   rather by Microsoft's Visual C++ toolchain.  This is required to launch or 
    40   rather by Microsoft's Visual C++ toolchain.  This is required to launch or 
    41   debug apps.
    41   debug apps.
    42 
    42 
    43 
    43 
       
    44 Status
       
    45 ------
       
    46 
       
    47 Here is a rough list of what works, and what doens't:
       
    48 
       
    49 * What works:
       
    50   * compilation via Visual C++ 2012 and 2013
       
    51   * compile-time platform detection for SDL programs.  The C/C++ #define,
       
    52     `__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
       
    53   * GPU-accelerated 2D rendering, via SDL_Renderer.
       
    54   * software rendering, via either SDL_Surface (optionally in conjunction with
       
    55     SDL_GetWindowSurface() and SDL_UpdateWindowSurface()) or via the
       
    56     SDL_Renderer APIs
       
    57   * threads.  Significant chunks of Win32's threading APIs are not available in
       
    58     WinRT.  A new, SDL threading backend was built using C++11's threading APIs
       
    59     (std::thread, std::mutex, std::condition_variable, etc.), which C or C++
       
    60     programs alike can access via SDL's threading APIs.  Support for thread
       
    61     priorities is not, however, currently available, due to restrictions in
       
    62     WinRT's own API set.
       
    63   * timers (via SDL_GetTicks(), SDL_AddTimer(), SDL_GetPerformanceCounter(),
       
    64     SDL_GetPerformanceFrequency(), etc.)
       
    65   * file I/O via SDL_RWops
       
    66   * mouse input  (unsupported on Windows Phone)
       
    67   * audio, via a modified version of SDL's XAudio2 backend
       
    68   * .DLL file loading.  Libraries must be packaged inside applications.  Loading
       
    69     anything outside of the app is not supported.
       
    70   * system path retrieval via SDL's filesystem APIs
       
    71   * game controllers.  Support is provided via the SDL_Joystick and
       
    72     SDL_GameController APIs, and is backed by Microsoft's XInput API.
       
    73   * multi-touch input
       
    74   * app events.  SDL_APP_WILLENTER* and SDL_APP_DIDENTER* events get sent out as
       
    75     appropriate.
       
    76   * window events.  SDL_WINDOWEVENT_MINIMIZED and SDL_WINDOWEVENT_RESTORED are
       
    77     sent out on app suspend and resume, respectively.  SDL_WINDOWEVENT_SHOWN and
       
    78     SDL_WINDOWEVENT_HIDDEN are also sent, but not necessarily on app suspend or
       
    79     resume, as WinRT treats these two concepts differently..
       
    80   * using Direct3D 11.x APIs outside of SDL.  Non-XAML / Direct3D-only apps can
       
    81     choose to render content directly via Direct3D, using SDL to manage the
       
    82     internal WinRT window, as well as input and audio.  (Use
       
    83     SDL_GetWindowWMInfo() to get the WinRT 'CoreWindow', and pass it into
       
    84     IDXGIFactory2::CreateSwapChainForCoreWindow() as appropriate.)
       
    85 
       
    86 * What partially works:
       
    87   * keyboard input.  Most of WinRT's documented virtual keys are supported, as
       
    88     well as many keys with documented hardware scancodes.
       
    89   * OpenGL.  Experimental support for OpenGL ES 2 is available via a
       
    90     Microsoft-modified version of the ANGLE project, as available at
       
    91     https://github.com/msopentech/angle .  Support is currently limited to the
       
    92     "winrt" branch, however support for the "future-dev" branch is planned.
       
    93   * SDLmain.  WinRT uses a different signature for each app's main() function.
       
    94     SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
       
    95     (in `SDL\src\main\winrt\`) directly in order for their C-style main()
       
    96     functions to be called.
       
    97   * XAML interoperability.  This feature is currently experimental (there are
       
    98     **many** known bugs in this, at present!), preliminary, and only for
       
    99     Windows 8.x/RT at the moment.  Windows Phone + XAML support is still
       
   100     pending.
       
   101 
       
   102 * What doesn't work:
       
   103   * compilation with anything other than Visual C++ 2012 or 2013
       
   104   * programmatically-created custom cursors.  These don't appear to be supported
       
   105     by WinRT.  Different OS-provided cursors can, however, be created via
       
   106     SDL_CreateSystemCursor() (unsupported on Windows Phone)
       
   107   * SDL_WarpMouseInWindow() or SDL_WarpMouseGlobal().  This are not currently
       
   108     supported by WinRT itself.
       
   109   * joysticks and game controllers that aren't supported by Microsoft's XInput
       
   110     API.
       
   111   * probably anything else that's not listed as supported
       
   112 
       
   113 
       
   114 
       
   115 
    44 Setup, High-Level Steps
   116 Setup, High-Level Steps
    45 -----------------------
   117 -----------------------
    46 
   118 
    47 The steps for setting up a project for an SDL/WinRT app looks like the
   119 The steps for setting up a project for an SDL/WinRT app looks like the
    48 following, at a high-level:
   120 following, at a high-level: