include/SDL_bits.h
author David Ludwig <dludwig@pobox.com>
Sat, 29 Nov 2014 10:09:30 -0500
changeset 9247 eddb899239fe
parent 8149 681eb46b8ac4
child 9619 b94b6d0bff0f
permissions -rw-r--r--
WinRT: bug and data-integrity fixes for SDL_GetPrefPath()

This change does a few things, all with regards to the WinRT implementation of
SDL_GetPrefPath():

1. it fixes a bug whereby SDL_GetPrefPath() did not create the directory it
returned. On other SDL platforms, SDL_GetPrefPath() will create separate
directories for its 'org' and 'app' folders. Without this, attempts to create
files in the pref-path would fail, unless those directories were first created
by the app, or by some other library the app used. This change makes sure
that these directories get created, before SDL_GetPrefPath() returns to its
caller(s).


2. it defaults to having SDL_GetPrefPath() return a WinRT 'Local' folder
on all platforms. Previously, for Windows Store apps, it would have used a
different, 'Roaming' folder. Files in Roaming folders can be automatically,
and synchronized across multiple devices by Windows. This synchronization can
happen while the app runs, with new files being copied into a running app's
pref-path. Unless an app is specifically designed to handle this scenario,
there is a chance that save-data could be overwritten in unwanted or
unexpected ways.

The default is now to use a Local folder, which does not get synchronized, and
which is arguably a bit safer to use. Apps that wish to use Roaming folders
can do so by setting SDL_HINT_WINRT_PREF_PATH_ROOT to "roaming", however it
is recommended that one first read Microsoft's documentation for Roaming
files, a link to which is provided in README-winrt.md.

To preserve older pref-path selection behavior (found in SDL 2.0.3, as well as
many pre-2.0.4 versions of SDL from hg.libsdl.org), which uses a Roaming path
in Windows Store apps, and a Local path in Windows Phone, set
SDL_HINT_WINRT_PREF_PATH_ROOT to "old".

Please note that Roaming paths are not supported on Windows Phone 8.0, due to
limitations in the OS itself. Attempts to use this will fail.
(Windows Phone 8.1 does not have this limitation, however.)


3. It makes SDL_GetPrefPath(), when on Windows Phone 8.0, and when
SDL_HINT_WINRT_PREF_PATH_ROOT is set to "roaming", return NULL, rather than
silently defaulting to a Local path (then switching to a Roaming path if and
when the user upgraded to Windows Phone 8.1).
jorgen@6866
     1
/*
jorgen@6866
     2
  Simple DirectMedia Layer
slouken@8149
     3
  Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
jorgen@6866
     4
jorgen@6866
     5
  This software is provided 'as-is', without any express or implied
jorgen@6866
     6
  warranty.  In no event will the authors be held liable for any damages
jorgen@6866
     7
  arising from the use of this software.
jorgen@6866
     8
jorgen@6866
     9
  Permission is granted to anyone to use this software for any purpose,
jorgen@6866
    10
  including commercial applications, and to alter it and redistribute it
jorgen@6866
    11
  freely, subject to the following restrictions:
jorgen@6866
    12
jorgen@6866
    13
  1. The origin of this software must not be misrepresented; you must not
jorgen@6866
    14
     claim that you wrote the original software. If you use this software
jorgen@6866
    15
     in a product, an acknowledgment in the product documentation would be
jorgen@6866
    16
     appreciated but is not required.
jorgen@6866
    17
  2. Altered source versions must be plainly marked as such, and must not be
jorgen@6866
    18
     misrepresented as being the original software.
jorgen@6866
    19
  3. This notice may not be removed or altered from any source distribution.
jorgen@6866
    20
*/
jorgen@6866
    21
jorgen@6866
    22
/**
jorgen@6866
    23
 *  \file SDL_bits.h
jorgen@6866
    24
 *
jorgen@6866
    25
 *  Functions for fiddling with bits and bitmasks.
jorgen@6866
    26
 */
jorgen@6866
    27
jorgen@6866
    28
#ifndef _SDL_bits_h
jorgen@6866
    29
#define _SDL_bits_h
jorgen@6866
    30
jorgen@6866
    31
#include "SDL_stdinc.h"
jorgen@6866
    32
jorgen@6866
    33
#include "begin_code.h"
jorgen@6866
    34
/* Set up for C function definitions, even when using C++ */
jorgen@6866
    35
#ifdef __cplusplus
jorgen@6866
    36
extern "C" {
jorgen@6866
    37
#endif
jorgen@6866
    38
jorgen@6866
    39
/**
jorgen@6866
    40
 *  \file SDL_bits.h
jorgen@6866
    41
 */
jorgen@6866
    42
jorgen@6866
    43
/**
jorgen@6866
    44
 *  Get the index of the most significant bit. Result is undefined when called
jorgen@6866
    45
 *  with 0. This operation can also be stated as "count leading zeroes" and
jorgen@6866
    46
 *  "log base 2".
jorgen@6866
    47
 *
slouken@7597
    48
 *  \return Index of the most significant bit, or -1 if the value is 0.
jorgen@6866
    49
 */
slouken@7597
    50
SDL_FORCE_INLINE int
jorgen@6866
    51
SDL_MostSignificantBitIndex32(Uint32 x)
jorgen@6866
    52
{
icculus@7033
    53
#if defined(__GNUC__) && __GNUC__ >= 4
jorgen@6866
    54
    /* Count Leading Zeroes builtin in GCC.
jorgen@6866
    55
     * http://gcc.gnu.org/onlinedocs/gcc-4.3.4/gcc/Other-Builtins.html
slouken@7605
    56
     */
slouken@7605
    57
    if (x == 0) {
slouken@7605
    58
        return -1;
slouken@7605
    59
    }
jorgen@6866
    60
    return 31 - __builtin_clz(x);
jorgen@6866
    61
#else
jorgen@6866
    62
    /* Based off of Bit Twiddling Hacks by Sean Eron Anderson
jorgen@6866
    63
     * <seander@cs.stanford.edu>, released in the public domain.
jorgen@6873
    64
     * http://graphics.stanford.edu/~seander/bithacks.html#IntegerLog
jorgen@6866
    65
     */
jorgen@6873
    66
    const Uint32 b[] = {0x2, 0xC, 0xF0, 0xFF00, 0xFFFF0000};
slouken@7597
    67
    const int    S[] = {1, 2, 4, 8, 16};
jorgen@6873
    68
slouken@7597
    69
    int msbIndex = 0;
slouken@7605
    70
    int i;
slouken@7597
    71
slouken@7605
    72
    if (x == 0) {
slouken@7605
    73
        return -1;
slouken@7605
    74
    }
jorgen@6873
    75
jorgen@6873
    76
    for (i = 4; i >= 0; i--)
jorgen@6866
    77
    {
jorgen@6873
    78
        if (x & b[i])
jorgen@6873
    79
        {
jorgen@6873
    80
            x >>= S[i];
jorgen@6873
    81
            msbIndex |= S[i];
jorgen@6873
    82
        }
jorgen@6873
    83
    }
jorgen@6866
    84
jorgen@6873
    85
    return msbIndex;
jorgen@6866
    86
#endif
jorgen@6866
    87
}
jorgen@6866
    88
jorgen@6866
    89
/* Ends C function definitions when using C++ */
jorgen@6866
    90
#ifdef __cplusplus
jorgen@6866
    91
}
jorgen@6866
    92
#endif
jorgen@6866
    93
#include "close_code.h"
jorgen@6866
    94
jorgen@6866
    95
#endif /* _SDL_bits_h */
jorgen@6866
    96
jorgen@6866
    97
/* vi: set ts=4 sw=4 expandtab: */