include/SDL_shape.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).
eligottlieb@4766
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@8149
     3
  Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
eligottlieb@4766
     4
slouken@5535
     5
  This software is provided 'as-is', without any express or implied
slouken@5535
     6
  warranty.  In no event will the authors be held liable for any damages
slouken@5535
     7
  arising from the use of this software.
eligottlieb@4766
     8
slouken@5535
     9
  Permission is granted to anyone to use this software for any purpose,
slouken@5535
    10
  including commercial applications, and to alter it and redistribute it
slouken@5535
    11
  freely, subject to the following restrictions:
eligottlieb@4766
    12
slouken@5535
    13
  1. The origin of this software must not be misrepresented; you must not
slouken@5535
    14
     claim that you wrote the original software. If you use this software
slouken@5535
    15
     in a product, an acknowledgment in the product documentation would be
slouken@5535
    16
     appreciated but is not required.
slouken@5535
    17
  2. Altered source versions must be plainly marked as such, and must not be
slouken@5535
    18
     misrepresented as being the original software.
slouken@5535
    19
  3. This notice may not be removed or altered from any source distribution.
eligottlieb@4766
    20
*/
eligottlieb@4766
    21
eligottlieb@4769
    22
#ifndef _SDL_shape_h
eligottlieb@4769
    23
#define _SDL_shape_h
eligottlieb@4769
    24
eligottlieb@4769
    25
#include "SDL_stdinc.h"
eligottlieb@4769
    26
#include "SDL_pixels.h"
eligottlieb@4769
    27
#include "SDL_rect.h"
eligottlieb@4769
    28
#include "SDL_surface.h"
eligottlieb@4769
    29
#include "SDL_video.h"
eligottlieb@4769
    30
eligottlieb@4769
    31
#include "begin_code.h"
eligottlieb@4769
    32
/* Set up for C function definitions, even when using C++ */
eligottlieb@4769
    33
#ifdef __cplusplus
eligottlieb@4769
    34
extern "C" {
eligottlieb@4769
    35
#endif
eligottlieb@4766
    36
eligottlieb@4779
    37
/** \file SDL_shape.h
eligottlieb@4779
    38
 *
eligottlieb@4781
    39
 * Header file for the shaped window API.
eligottlieb@4779
    40
 */
eligottlieb@4779
    41
eligottlieb@4801
    42
#define SDL_NONSHAPEABLE_WINDOW -1
eligottlieb@4801
    43
#define SDL_INVALID_SHAPE_ARGUMENT -2
eligottlieb@4801
    44
#define SDL_WINDOW_LACKS_SHAPE -3
eligottlieb@4801
    45
eligottlieb@4766
    46
/**
eligottlieb@4781
    47
 *  \brief Create a window that can be shaped with the specified position, dimensions, and flags.
slouken@7191
    48
 *
eligottlieb@4766
    49
 *  \param title The title of the window, in UTF-8 encoding.
slouken@7191
    50
 *  \param x     The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
eligottlieb@4766
    51
 *               ::SDL_WINDOWPOS_UNDEFINED.
slouken@7191
    52
 *  \param y     The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
eligottlieb@4766
    53
 *               ::SDL_WINDOWPOS_UNDEFINED.
eligottlieb@4766
    54
 *  \param w     The width of the window.
eligottlieb@4766
    55
 *  \param h     The height of the window.
slouken@7191
    56
 *  \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with any of the following:
eligottlieb@4767
    57
 *               ::SDL_WINDOW_OPENGL,     ::SDL_WINDOW_INPUT_GRABBED,
philipp@7480
    58
 *               ::SDL_WINDOW_HIDDEN,     ::SDL_WINDOW_RESIZABLE,
eligottlieb@4766
    59
 *               ::SDL_WINDOW_MAXIMIZED,  ::SDL_WINDOW_MINIMIZED,
slouken@7191
    60
 *       ::SDL_WINDOW_BORDERLESS is always set, and ::SDL_WINDOW_FULLSCREEN is always unset.
slouken@7191
    61
 *
eligottlieb@4801
    62
 *  \return The window created, or NULL if window creation failed.
slouken@7191
    63
 *
eligottlieb@4766
    64
 *  \sa SDL_DestroyWindow()
eligottlieb@4766
    65
 */
eligottlieb@4768
    66
extern DECLSPEC SDL_Window * SDLCALL SDL_CreateShapedWindow(const char *title,unsigned int x,unsigned int y,unsigned int w,unsigned int h,Uint32 flags);
eligottlieb@4766
    67
eligottlieb@4778
    68
/**
slouken@7191
    69
 * \brief Return whether the given window is a shaped window.
eligottlieb@4778
    70
 *
eligottlieb@4778
    71
 * \param window The window to query for being shaped.
eligottlieb@4778
    72
 *
eligottlieb@4781
    73
 * \return SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if the window is unshaped or NULL.
eligottlieb@4778
    74
 * \sa SDL_CreateShapedWindow
eligottlieb@4778
    75
 */
eligottlieb@4781
    76
extern DECLSPEC SDL_bool SDLCALL SDL_IsShapedWindow(const SDL_Window *window);
eligottlieb@4778
    77
eligottlieb@4778
    78
/** \brief An enum denoting the specific type of contents present in an SDL_WindowShapeParams union. */
eligottlieb@4781
    79
typedef enum {
slouken@7191
    80
    /** \brief The default mode, a binarized alpha cutoff of 1. */
slouken@7191
    81
    ShapeModeDefault,
slouken@7191
    82
    /** \brief A binarized alpha cutoff with a given integer value. */
slouken@7191
    83
    ShapeModeBinarizeAlpha,
slouken@7191
    84
    /** \brief A binarized alpha cutoff with a given integer value, but with the opposite comparison. */
slouken@7191
    85
    ShapeModeReverseBinarizeAlpha,
slouken@7191
    86
    /** \brief A color key is applied. */
slouken@7191
    87
    ShapeModeColorKey
eligottlieb@4781
    88
} WindowShapeMode;
eligottlieb@4846
    89
eligottlieb@4846
    90
#define SDL_SHAPEMODEALPHA(mode) (mode == ShapeModeDefault || mode == ShapeModeBinarizeAlpha || mode == ShapeModeReverseBinarizeAlpha)
eligottlieb@4846
    91
eligottlieb@4778
    92
/** \brief A union containing parameters for shaped windows. */
eligottlieb@4778
    93
typedef union {
slouken@7191
    94
    /** \brief a cutoff alpha value for binarization of the window shape's alpha channel. */
slouken@7191
    95
    Uint8 binarizationCutoff;
slouken@7191
    96
    SDL_Color colorKey;
eligottlieb@4778
    97
} SDL_WindowShapeParams;
eligottlieb@4778
    98
eligottlieb@4778
    99
/** \brief A struct that tags the SDL_WindowShapeParams union with an enum describing the type of its contents. */
eligottlieb@4778
   100
typedef struct SDL_WindowShapeMode {
slouken@7191
   101
    /** \brief The mode of these window-shape parameters. */
slouken@7191
   102
    WindowShapeMode mode;
slouken@7191
   103
    /** \brief Window-shape parameters. */
slouken@7191
   104
    SDL_WindowShapeParams parameters;
eligottlieb@4778
   105
} SDL_WindowShapeMode;
eligottlieb@4778
   106
eligottlieb@4778
   107
/**
eligottlieb@4780
   108
 * \brief Set the shape and parameters of a shaped window.
eligottlieb@4778
   109
 *
eligottlieb@4778
   110
 * \param window The shaped window whose parameters should be set.
eligottlieb@4781
   111
 * \param shape A surface encoding the desired shape for the window.
egottlieb@4849
   112
 * \param shape_mode The parameters to set for the shaped window.
eligottlieb@4778
   113
 *
eligottlieb@4801
   114
 * \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on invalid an invalid shape argument, or SDL_NONSHAPEABLE_WINDOW
eligottlieb@4801
   115
 *           if the SDL_Window* given does not reference a valid shaped window.
eligottlieb@4778
   116
 *
eligottlieb@4778
   117
 * \sa SDL_WindowShapeMode
eligottlieb@4781
   118
 * \sa SDL_GetShapedWindowMode.
eligottlieb@4778
   119
 */
egottlieb@4849
   120
extern DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window,SDL_Surface *shape,SDL_WindowShapeMode *shape_mode);
eligottlieb@4778
   121
eligottlieb@4778
   122
/**
eligottlieb@4781
   123
 * \brief Get the shape parameters of a shaped window.
eligottlieb@4778
   124
 *
eligottlieb@4778
   125
 * \param window The shaped window whose parameters should be retrieved.
egottlieb@4849
   126
 * \param shape_mode An empty shape-mode structure to fill, or NULL to check whether the window has a shape.
eligottlieb@4778
   127
 *
egottlieb@4849
   128
 * \return 0 if the window has a shape and, provided shape_mode was not NULL, shape_mode has been filled with the mode
eligottlieb@4801
   129
 *           data, SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped window, or SDL_WINDOW_LACKS_SHAPE if
eligottlieb@4801
   130
 *           the SDL_Window* given is a shapeable window currently lacking a shape.
eligottlieb@4778
   131
 *
eligottlieb@4778
   132
 * \sa SDL_WindowShapeMode
eligottlieb@4781
   133
 * \sa SDL_SetWindowShape
eligottlieb@4778
   134
 */
egottlieb@4849
   135
extern DECLSPEC int SDLCALL SDL_GetShapedWindowMode(SDL_Window *window,SDL_WindowShapeMode *shape_mode);
eligottlieb@4778
   136
eligottlieb@4769
   137
/* Ends C function definitions when using C++ */
eligottlieb@4769
   138
#ifdef __cplusplus
eligottlieb@4769
   139
}
eligottlieb@4769
   140
#endif
eligottlieb@4769
   141
#include "close_code.h"
eligottlieb@4769
   142
eligottlieb@4769
   143
#endif /* _SDL_shape_h */