1.1 --- a/docs/README-winrt.md	Thu Nov 27 08:50:11 2014 -0500
     1.2 +++ b/docs/README-winrt.md	Thu Nov 27 09:55:34 2014 -0500
     1.3 @@ -116,6 +116,32 @@
     1.4  
     1.5  
     1.6  
     1.7 +Caveats
     1.8 +-------
     1.9 +
    1.10 +#### SDL_GetPrefPath() usage
    1.11 +
    1.12 +SDL_GetPrefPath() is available for use in WinRT apps, however the following
    1.13 +should be noted:
    1.14 +
    1.15 +1. It will return different path types, by default, depending on the WinRT
    1.16 +   platform.  Windows Phone apps will default to using the app's "local" path,
    1.17 +   whereas Windows Store (i.e. non-Phone) apps will default to using the app's
    1.18 +   "roaming" path.  This behavior can be changed by calling SDL_SetHint() with
    1.19 +   the key, SDL_HINT_WINRT_PREF_PATH_ROOT, and a value of either "local" or
    1.20 +   "roaming".
    1.21 +
    1.22 +2. Windows Phone 8.0 does not provide apps access to a "roaming" folder.
    1.23 +   Attempts to make SDL_GetPrefPath() return a roaming folder on Windows
    1.24 +   Phone 8.0 will be ignored (and a path inside the "local" folder will be
    1.25 +   used instead).
    1.26 +
    1.27 +Further details on this can be found in the documentation for
    1.28 +SDL_HINT_WINRT_PREF_PATH_ROOT, in SDL_hints.h, as well as the docs for
    1.29 +SDL_WinRT_Path, SDL_WinRTGetFSPathUNICODE, and SDL_WinRTGetFSPathUTF8,
    1.30 +in SDL_system.h.
    1.31 +
    1.32 +
    1.33  
    1.34  Setup, High-Level Steps
    1.35  -----------------------

     2.1 --- a/include/SDL_hints.h	Thu Nov 27 08:50:11 2014 -0500
     2.2 +++ b/include/SDL_hints.h	Thu Nov 27 09:55:34 2014 -0500
     2.3 @@ -492,6 +492,27 @@
     2.4  #define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON"
     2.5  
     2.6  /**
     2.7 + *  \brief  A variable that dictates what SDL_GetPrefPath() returns in WinRT apps.
     2.8 + *
     2.9 + *  The variable can be set to the following values:
    2.10 + *    "local"   - Use the app's 'local' folder to store data; default for
    2.11 + *                Windows Phone apps.
    2.12 + *    "roaming" - Use the app's 'roaming' folder to store data; default for
    2.13 + *                Windows Store (non-Phone) apps.  On Windows Phone 8.0, this
    2.14 + *                setting will be ignored (and the 'local' folder will be used
    2.15 + *                instead), as the OS does not support roaming folders.
    2.16 + *
    2.17 + *  Details on 'local' verses 'roaming' folders can be found on MSDN, in the
    2.18 + *  documentation for WinRT's Windows.Storage.ApplicationData class, which is
    2.19 + *  available at http://msdn.microsoft.com/en-us/library/windows/apps/windows.storage.applicationdata
    2.20 + *
    2.21 + *  The application's local and roaming paths may, alternatively, be retrieved
    2.22 + *  via the SDL_WinRTGetFSPathUTF8() and SDL_WinRTGetFSPathUNICODE() functions,
    2.23 + *  which are defined in SDL_system.h.
    2.24 + */
    2.25 +#define SDL_HINT_WINRT_PREF_PATH_ROOT "SDL_WINRT_PREF_PATH_ROOT"
    2.26 +
    2.27 +/**
    2.28   *  \brief  A variable that dictates policy for fullscreen Spaces on Mac OS X.
    2.29   *
    2.30   *  This hint only applies to Mac OS X.

     3.1 --- a/src/filesystem/winrt/SDL_sysfilesystem.cpp	Thu Nov 27 08:50:11 2014 -0500
     3.2 +++ b/src/filesystem/winrt/SDL_sysfilesystem.cpp	Thu Nov 27 09:55:34 2014 -0500
     3.3 @@ -28,6 +28,7 @@
     3.4  extern "C" {
     3.5  #include "SDL_filesystem.h"
     3.6  #include "SDL_error.h"
     3.7 +#include "SDL_hints.h"
     3.8  #include "SDL_stdinc.h"
     3.9  #include "SDL_system.h"
    3.10  #include "../../core/windows/SDL_windows.h"
    3.11 @@ -149,13 +150,26 @@
    3.12       * compatibility with Windows Phone 8.0, and with app-installs that have
    3.13       * been updated from 8.0-based, to 8.1-based apps.
    3.14       */
    3.15 -    const char * srcPath = SDL_WinRTGetFSPathUTF8(SDL_WINRT_PATH_LOCAL_FOLDER);
    3.16 +    SDL_WinRT_Path pathType = SDL_WINRT_PATH_LOCAL_FOLDER;
    3.17  #else
    3.18      /* A 'Roaming' folder is available on Windows 8 and 8.1.  Use that.
    3.19       */
    3.20 -    const char * srcPath = SDL_WinRTGetFSPathUTF8(SDL_WINRT_PATH_ROAMING_FOLDER);
    3.21 +    SDL_WinRT_Path pathType = SDL_WINRT_PATH_ROAMING_FOLDER;
    3.22  #endif
    3.23  
    3.24 +    const char * hint = SDL_GetHint(SDL_HINT_WINRT_PREF_PATH_ROOT);
    3.25 +    if (hint) {
    3.26 +        if (SDL_strcasecmp(hint, "local") == 0) {
    3.27 +            pathType = SDL_WINRT_PATH_LOCAL_FOLDER;
    3.28 +        }
    3.29 +#if (WINAPI_FAMILY != WINAPI_FAMILY_PHONE_APP) || (NTDDI_VERSION > NTDDI_WIN8)
    3.30 +        else if (SDL_strcasecmp(hint, "roaming") == 0) {
    3.31 +            pathType = SDL_WINRT_PATH_ROAMING_FOLDER;
    3.32 +        }
    3.33 +#endif
    3.34 +    }
    3.35 +
    3.36 +    const char * srcPath = SDL_WinRTGetFSPathUTF8(pathType);
    3.37      size_t destPathLen;
    3.38      char * destPath = NULL;
    3.39