include/SDL_test_common.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).
aschiffler@6727
     1
/*
aschiffler@6727
     2
  Simple DirectMedia Layer
slouken@8149
     3
  Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
aschiffler@6727
     4
aschiffler@6727
     5
  This software is provided 'as-is', without any express or implied
aschiffler@6727
     6
  warranty.  In no event will the authors be held liable for any damages
aschiffler@6727
     7
  arising from the use of this software.
aschiffler@6727
     8
aschiffler@6727
     9
  Permission is granted to anyone to use this software for any purpose,
aschiffler@6727
    10
  including commercial applications, and to alter it and redistribute it
aschiffler@6727
    11
  freely, subject to the following restrictions:
aschiffler@6727
    12
aschiffler@6727
    13
  1. The origin of this software must not be misrepresented; you must not
aschiffler@6727
    14
     claim that you wrote the original software. If you use this software
aschiffler@6727
    15
     in a product, an acknowledgment in the product documentation would be
aschiffler@6727
    16
     appreciated but is not required.
aschiffler@6727
    17
  2. Altered source versions must be plainly marked as such, and must not be
aschiffler@6727
    18
     misrepresented as being the original software.
aschiffler@6727
    19
  3. This notice may not be removed or altered from any source distribution.
aschiffler@6727
    20
*/
aschiffler@6727
    21
aschiffler@6727
    22
/**
aschiffler@6727
    23
 *  \file SDL_test_common.h
slouken@7191
    24
 *
aschiffler@6727
    25
 *  Include file for SDL test framework.
aschiffler@6727
    26
 *
aschiffler@6727
    27
 *  This code is a part of the SDL2_test library, not the main SDL library.
aschiffler@6727
    28
 */
aschiffler@6727
    29
aschiffler@6727
    30
/* Ported from original test\common.h file. */
aschiffler@6727
    31
aschiffler@6727
    32
#ifndef _SDL_test_common_h
aschiffler@6727
    33
#define _SDL_test_common_h
aschiffler@6727
    34
aschiffler@6727
    35
#include "SDL.h"
aschiffler@6727
    36
slouken@7011
    37
#if defined(__PSP__)
kimonline@7009
    38
#define DEFAULT_WINDOW_WIDTH  480
kimonline@7009
    39
#define DEFAULT_WINDOW_HEIGHT 272
aschiffler@6727
    40
#else
aschiffler@6727
    41
#define DEFAULT_WINDOW_WIDTH  640
aschiffler@6727
    42
#define DEFAULT_WINDOW_HEIGHT 480
aschiffler@6727
    43
#endif
aschiffler@6727
    44
aschiffler@6727
    45
#define VERBOSE_VIDEO   0x00000001
aschiffler@6727
    46
#define VERBOSE_MODES   0x00000002
aschiffler@6727
    47
#define VERBOSE_RENDER  0x00000004
aschiffler@6727
    48
#define VERBOSE_EVENT   0x00000008
aschiffler@6727
    49
#define VERBOSE_AUDIO   0x00000010
aschiffler@6727
    50
aschiffler@6727
    51
typedef struct
aschiffler@6727
    52
{
aschiffler@6727
    53
    /* SDL init flags */
aschiffler@6727
    54
    char **argv;
aschiffler@6727
    55
    Uint32 flags;
aschiffler@6727
    56
    Uint32 verbose;
aschiffler@6727
    57
aschiffler@6727
    58
    /* Video info */
aschiffler@6727
    59
    const char *videodriver;
aschiffler@6727
    60
    int display;
aschiffler@6727
    61
    const char *window_title;
aschiffler@6727
    62
    const char *window_icon;
aschiffler@6727
    63
    Uint32 window_flags;
aschiffler@6727
    64
    int window_x;
aschiffler@6727
    65
    int window_y;
aschiffler@6727
    66
    int window_w;
aschiffler@6727
    67
    int window_h;
slouken@6788
    68
    int window_minW;
slouken@6788
    69
    int window_minH;
slouken@6788
    70
    int window_maxW;
slouken@6788
    71
    int window_maxH;
slouken@7240
    72
    int logical_w;
slouken@7240
    73
    int logical_h;
slouken@7240
    74
    float scale;
aschiffler@6727
    75
    int depth;
aschiffler@6727
    76
    int refresh_rate;
aschiffler@6727
    77
    int num_windows;
aschiffler@6727
    78
    SDL_Window **windows;
aschiffler@6727
    79
aschiffler@6727
    80
    /* Renderer info */
aschiffler@6727
    81
    const char *renderdriver;
aschiffler@6727
    82
    Uint32 render_flags;
aschiffler@6727
    83
    SDL_bool skip_renderer;
aschiffler@6727
    84
    SDL_Renderer **renderers;
slouken@7993
    85
    SDL_Texture **targets;
aschiffler@6727
    86
aschiffler@6727
    87
    /* Audio info */
aschiffler@6727
    88
    const char *audiodriver;
aschiffler@6727
    89
    SDL_AudioSpec audiospec;
aschiffler@6727
    90
aschiffler@6727
    91
    /* GL settings */
aschiffler@6727
    92
    int gl_red_size;
aschiffler@6727
    93
    int gl_green_size;
aschiffler@6727
    94
    int gl_blue_size;
aschiffler@6727
    95
    int gl_alpha_size;
aschiffler@6727
    96
    int gl_buffer_size;
aschiffler@6727
    97
    int gl_depth_size;
aschiffler@6727
    98
    int gl_stencil_size;
aschiffler@6727
    99
    int gl_double_buffer;
aschiffler@6727
   100
    int gl_accum_red_size;
aschiffler@6727
   101
    int gl_accum_green_size;
aschiffler@6727
   102
    int gl_accum_blue_size;
aschiffler@6727
   103
    int gl_accum_alpha_size;
aschiffler@6727
   104
    int gl_stereo;
aschiffler@6727
   105
    int gl_multisamplebuffers;
aschiffler@6727
   106
    int gl_multisamplesamples;
aschiffler@6727
   107
    int gl_retained_backing;
aschiffler@6727
   108
    int gl_accelerated;
aschiffler@6727
   109
    int gl_major_version;
aschiffler@6727
   110
    int gl_minor_version;
slouken@7194
   111
    int gl_debug;
gabomdq@7796
   112
    int gl_profile_mask;
aschiffler@6727
   113
} SDLTest_CommonState;
aschiffler@6727
   114
aschiffler@6727
   115
#include "begin_code.h"
aschiffler@6727
   116
/* Set up for C function definitions, even when using C++ */
aschiffler@6727
   117
#ifdef __cplusplus
aschiffler@6727
   118
extern "C" {
aschiffler@6727
   119
#endif
aschiffler@6727
   120
aschiffler@6727
   121
/* Function prototypes */
aschiffler@6727
   122
aschiffler@6727
   123
/**
aschiffler@6727
   124
 * \brief Parse command line parameters and create common state.
aschiffler@6727
   125
 *
aschiffler@6727
   126
 * \param argv Array of command line parameters
aschiffler@6727
   127
 * \param flags Flags indicating which subsystem to initialize (i.e. SDL_INIT_VIDEO | SDL_INIT_AUDIO)
aschiffler@6727
   128
 *
aschiffler@6727
   129
 * \returns Returns a newly allocated common state object.
aschiffler@6727
   130
 */
aschiffler@6727
   131
SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
aschiffler@6727
   132
aschiffler@6727
   133
/**
aschiffler@6727
   134
 * \brief Process one common argument.
aschiffler@6727
   135
 *
aschiffler@6727
   136
 * \param state The common state describing the test window to create.
aschiffler@6727
   137
 * \param index The index of the argument to process in argv[].
aschiffler@6727
   138
 *
aschiffler@6727
   139
 * \returns The number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error.
aschiffler@6727
   140
 */
aschiffler@6727
   141
int SDLTest_CommonArg(SDLTest_CommonState * state, int index);
aschiffler@6727
   142
aschiffler@6727
   143
/**
aschiffler@6727
   144
 * \brief Returns common usage information
aschiffler@6727
   145
 *
aschiffler@6727
   146
 * \param state The common state describing the test window to create.
aschiffler@6727
   147
 *
aschiffler@6727
   148
 * \returns String with usage information
aschiffler@6727
   149
 */
aschiffler@6727
   150
const char *SDLTest_CommonUsage(SDLTest_CommonState * state);
aschiffler@6727
   151
aschiffler@6727
   152
/**
aschiffler@6727
   153
 * \brief Open test window.
aschiffler@6727
   154
 *
aschiffler@6727
   155
 * \param state The common state describing the test window to create.
aschiffler@6727
   156
 *
aschiffler@6727
   157
 * \returns True if initialization succeeded, false otherwise
aschiffler@6727
   158
 */
aschiffler@6727
   159
SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state);
aschiffler@6727
   160
aschiffler@6727
   161
/**
aschiffler@6727
   162
 * \brief Common event handler for test windows.
aschiffler@6727
   163
 *
aschiffler@6727
   164
 * \param state The common state used to create test window.
aschiffler@6727
   165
 * \param event The event to handle.
aschiffler@6727
   166
 * \param done Flag indicating we are done.
aschiffler@6727
   167
 *
aschiffler@6727
   168
 */
aschiffler@6727
   169
void SDLTest_CommonEvent(SDLTest_CommonState * state, SDL_Event * event, int *done);
aschiffler@6727
   170
aschiffler@6727
   171
/**
aschiffler@6727
   172
 * \brief Close test window.
aschiffler@6727
   173
 *
aschiffler@6727
   174
 * \param state The common state used to create test window.
aschiffler@6727
   175
 *
aschiffler@6727
   176
 */
aschiffler@6727
   177
void SDLTest_CommonQuit(SDLTest_CommonState * state);
aschiffler@6727
   178
aschiffler@6727
   179
aschiffler@6727
   180
/* Ends C function definitions when using C++ */
aschiffler@6727
   181
#ifdef __cplusplus
aschiffler@6727
   182
}
aschiffler@6727
   183
#endif
aschiffler@6727
   184
#include "close_code.h"
aschiffler@6727
   185
aschiffler@6727
   186
#endif /* _SDL_test_common_h */
aschiffler@6727
   187
aschiffler@6727
   188
/* vi: set ts=4 sw=4 expandtab: */