include/SDL_video.h
author David Ludwig <dludwig@pobox.com>
Sat, 29 Nov 2014 10:09:30 -0500
changeset 9247 eddb899239fe
parent 8946 c9592936dffc
child 9412 8b1436ce1028
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).
slouken@0
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@8149
     3
  Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
slouken@0
     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.
slouken@0
     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:
slouken@0
    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.
slouken@0
    20
*/
slouken@0
    21
slouken@1895
    22
/**
slouken@3407
    23
 *  \file SDL_video.h
slouken@7191
    24
 *
slouken@3407
    25
 *  Header file for SDL video functions.
slouken@1895
    26
 */
slouken@0
    27
slouken@0
    28
#ifndef _SDL_video_h
slouken@0
    29
#define _SDL_video_h
slouken@0
    30
slouken@1356
    31
#include "SDL_stdinc.h"
slouken@1895
    32
#include "SDL_pixels.h"
slouken@2275
    33
#include "SDL_rect.h"
slouken@2275
    34
#include "SDL_surface.h"
slouken@0
    35
slouken@0
    36
#include "begin_code.h"
slouken@0
    37
/* Set up for C function definitions, even when using C++ */
slouken@0
    38
#ifdef __cplusplus
slouken@0
    39
extern "C" {
slouken@0
    40
#endif
slouken@0
    41
slouken@1895
    42
/**
slouken@3407
    43
 *  \brief  The structure that defines a display mode
slouken@7191
    44
 *
slouken@3407
    45
 *  \sa SDL_GetNumDisplayModes()
slouken@3407
    46
 *  \sa SDL_GetDisplayMode()
slouken@3407
    47
 *  \sa SDL_GetDesktopDisplayMode()
slouken@3407
    48
 *  \sa SDL_GetCurrentDisplayMode()
slouken@3407
    49
 *  \sa SDL_GetClosestDisplayMode()
slouken@3500
    50
 *  \sa SDL_SetWindowDisplayMode()
slouken@3500
    51
 *  \sa SDL_GetWindowDisplayMode()
slouken@1895
    52
 */
slouken@1895
    53
typedef struct
slouken@1895
    54
{
slouken@1895
    55
    Uint32 format;              /**< pixel format */
slouken@1895
    56
    int w;                      /**< width */
slouken@1895
    57
    int h;                      /**< height */
slouken@1895
    58
    int refresh_rate;           /**< refresh rate (or zero for unspecified) */
slouken@1895
    59
    void *driverdata;           /**< driver-specific data, initialize to 0 */
slouken@1895
    60
} SDL_DisplayMode;
slouken@0
    61
slouken@1895
    62
/**
slouken@3407
    63
 *  \brief The type used to identify a window
slouken@7191
    64
 *
slouken@3407
    65
 *  \sa SDL_CreateWindow()
slouken@3407
    66
 *  \sa SDL_CreateWindowFrom()
slouken@3407
    67
 *  \sa SDL_DestroyWindow()
slouken@3407
    68
 *  \sa SDL_GetWindowData()
slouken@3407
    69
 *  \sa SDL_GetWindowFlags()
slouken@3407
    70
 *  \sa SDL_GetWindowGrab()
slouken@3407
    71
 *  \sa SDL_GetWindowPosition()
slouken@3407
    72
 *  \sa SDL_GetWindowSize()
slouken@3407
    73
 *  \sa SDL_GetWindowTitle()
slouken@3407
    74
 *  \sa SDL_HideWindow()
slouken@3407
    75
 *  \sa SDL_MaximizeWindow()
slouken@3407
    76
 *  \sa SDL_MinimizeWindow()
slouken@3407
    77
 *  \sa SDL_RaiseWindow()
slouken@3407
    78
 *  \sa SDL_RestoreWindow()
slouken@3407
    79
 *  \sa SDL_SetWindowData()
slouken@3407
    80
 *  \sa SDL_SetWindowFullscreen()
slouken@3407
    81
 *  \sa SDL_SetWindowGrab()
slouken@3407
    82
 *  \sa SDL_SetWindowIcon()
slouken@3407
    83
 *  \sa SDL_SetWindowPosition()
slouken@3407
    84
 *  \sa SDL_SetWindowSize()
icculus@6429
    85
 *  \sa SDL_SetWindowBordered()
slouken@3407
    86
 *  \sa SDL_SetWindowTitle()
slouken@3407
    87
 *  \sa SDL_ShowWindow()
slouken@1895
    88
 */
slouken@3685
    89
typedef struct SDL_Window SDL_Window;
slouken@0
    90
slouken@1895
    91
/**
slouken@3407
    92
 *  \brief The flags on a window
slouken@7191
    93
 *
slouken@3407
    94
 *  \sa SDL_GetWindowFlags()
slouken@1895
    95
 */
slouken@1895
    96
typedef enum
slouken@1895
    97
{
slouken@5380
    98
    SDL_WINDOW_FULLSCREEN = 0x00000001,         /**< fullscreen window */
slouken@1895
    99
    SDL_WINDOW_OPENGL = 0x00000002,             /**< window usable with OpenGL context */
slouken@1895
   100
    SDL_WINDOW_SHOWN = 0x00000004,              /**< window is visible */
slouken@5380
   101
    SDL_WINDOW_HIDDEN = 0x00000008,             /**< window is not visible */
slouken@5380
   102
    SDL_WINDOW_BORDERLESS = 0x00000010,         /**< no window decoration */
slouken@5380
   103
    SDL_WINDOW_RESIZABLE = 0x00000020,          /**< window can be resized */
slouken@5380
   104
    SDL_WINDOW_MINIMIZED = 0x00000040,          /**< window is minimized */
slouken@5380
   105
    SDL_WINDOW_MAXIMIZED = 0x00000080,          /**< window is maximized */
slouken@1895
   106
    SDL_WINDOW_INPUT_GRABBED = 0x00000100,      /**< window has grabbed input focus */
slouken@1895
   107
    SDL_WINDOW_INPUT_FOCUS = 0x00000200,        /**< window has input focus */
slouken@3057
   108
    SDL_WINDOW_MOUSE_FOCUS = 0x00000400,        /**< window has mouse focus */
slouken@7191
   109
    SDL_WINDOW_FULLSCREEN_DESKTOP = ( SDL_WINDOW_FULLSCREEN | 0x00001000 ),
urkle@7746
   110
    SDL_WINDOW_FOREIGN = 0x00000800,            /**< window not created by SDL */
icculus@8927
   111
    SDL_WINDOW_ALLOW_HIGHDPI = 0x00002000,      /**< window should be created in high-DPI mode if supported */
icculus@8927
   112
    SDL_WINDOW_MOUSE_CAPTURE = 0x00004000       /**< window has mouse captured (unrelated to INPUT_GRABBED) */
slouken@1895
   113
} SDL_WindowFlags;
slouken@0
   114
slouken@1895
   115
/**
slouken@3407
   116
 *  \brief Used to indicate that you don't care what the window position is.
slouken@1895
   117
 */
slouken@5246
   118
#define SDL_WINDOWPOS_UNDEFINED_MASK    0x1FFF0000
slouken@5246
   119
#define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X)  (SDL_WINDOWPOS_UNDEFINED_MASK|(X))
slouken@5246
   120
#define SDL_WINDOWPOS_UNDEFINED         SDL_WINDOWPOS_UNDEFINED_DISPLAY(0)
slouken@5246
   121
#define SDL_WINDOWPOS_ISUNDEFINED(X)    \
slouken@5246
   122
            (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK)
slouken@3407
   123
slouken@1895
   124
/**
slouken@3407
   125
 *  \brief Used to indicate that the window position should be centered.
slouken@1895
   126
 */
slouken@5246
   127
#define SDL_WINDOWPOS_CENTERED_MASK    0x2FFF0000
slouken@5246
   128
#define SDL_WINDOWPOS_CENTERED_DISPLAY(X)  (SDL_WINDOWPOS_CENTERED_MASK|(X))
slouken@5246
   129
#define SDL_WINDOWPOS_CENTERED         SDL_WINDOWPOS_CENTERED_DISPLAY(0)
slouken@5246
   130
#define SDL_WINDOWPOS_ISCENTERED(X)    \
slouken@5246
   131
            (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK)
slouken@1895
   132
slouken@1895
   133
/**
slouken@3407
   134
 *  \brief Event subtype for window events
slouken@1895
   135
 */
slouken@1895
   136
typedef enum
slouken@1895
   137
{
slouken@3407
   138
    SDL_WINDOWEVENT_NONE,           /**< Never used */
slouken@3407
   139
    SDL_WINDOWEVENT_SHOWN,          /**< Window has been shown */
slouken@3407
   140
    SDL_WINDOWEVENT_HIDDEN,         /**< Window has been hidden */
slouken@7191
   141
    SDL_WINDOWEVENT_EXPOSED,        /**< Window has been exposed and should be
slouken@3407
   142
                                         redrawn */
slouken@7191
   143
    SDL_WINDOWEVENT_MOVED,          /**< Window has been moved to data1, data2
slouken@3407
   144
                                     */
slouken@5276
   145
    SDL_WINDOWEVENT_RESIZED,        /**< Window has been resized to data1xdata2 */
slouken@5276
   146
    SDL_WINDOWEVENT_SIZE_CHANGED,   /**< The window size has changed, either as a result of an API call or through the system or user changing the window size. */
slouken@3407
   147
    SDL_WINDOWEVENT_MINIMIZED,      /**< Window has been minimized */
slouken@3407
   148
    SDL_WINDOWEVENT_MAXIMIZED,      /**< Window has been maximized */
slouken@3407
   149
    SDL_WINDOWEVENT_RESTORED,       /**< Window has been restored to normal size
slouken@3407
   150
                                         and position */
slouken@3691
   151
    SDL_WINDOWEVENT_ENTER,          /**< Window has gained mouse focus */
slouken@3691
   152
    SDL_WINDOWEVENT_LEAVE,          /**< Window has lost mouse focus */
slouken@3691
   153
    SDL_WINDOWEVENT_FOCUS_GAINED,   /**< Window has gained keyboard focus */
slouken@3691
   154
    SDL_WINDOWEVENT_FOCUS_LOST,     /**< Window has lost keyboard focus */
slouken@7191
   155
    SDL_WINDOWEVENT_CLOSE           /**< The window manager requests that the
slouken@3407
   156
                                         window be closed */
slouken@1895
   157
} SDL_WindowEventID;
slouken@1895
   158
slouken@1895
   159
/**
slouken@3407
   160
 *  \brief An opaque handle to an OpenGL context.
slouken@1895
   161
 */
slouken@1895
   162
typedef void *SDL_GLContext;
slouken@1895
   163
slouken@1895
   164
/**
slouken@3407
   165
 *  \brief OpenGL configuration attributes
slouken@0
   166
 */
slouken@1895
   167
typedef enum
slouken@1895
   168
{
slouken@0
   169
    SDL_GL_RED_SIZE,
slouken@0
   170
    SDL_GL_GREEN_SIZE,
slouken@0
   171
    SDL_GL_BLUE_SIZE,
slouken@0
   172
    SDL_GL_ALPHA_SIZE,
slouken@0
   173
    SDL_GL_BUFFER_SIZE,
slouken@0
   174
    SDL_GL_DOUBLEBUFFER,
slouken@0
   175
    SDL_GL_DEPTH_SIZE,
slouken@0
   176
    SDL_GL_STENCIL_SIZE,
slouken@0
   177
    SDL_GL_ACCUM_RED_SIZE,
slouken@0
   178
    SDL_GL_ACCUM_GREEN_SIZE,
slouken@0
   179
    SDL_GL_ACCUM_BLUE_SIZE,
slouken@450
   180
    SDL_GL_ACCUM_ALPHA_SIZE,
slouken@655
   181
    SDL_GL_STEREO,
slouken@656
   182
    SDL_GL_MULTISAMPLEBUFFERS,
slouken@1736
   183
    SDL_GL_MULTISAMPLESAMPLES,
hfutrell@2747
   184
    SDL_GL_ACCELERATED_VISUAL,
slouken@3100
   185
    SDL_GL_RETAINED_BACKING,
slouken@3139
   186
    SDL_GL_CONTEXT_MAJOR_VERSION,
slouken@6296
   187
    SDL_GL_CONTEXT_MINOR_VERSION,
slouken@6370
   188
    SDL_GL_CONTEXT_EGL,
slouken@6296
   189
    SDL_GL_CONTEXT_FLAGS,
slouken@6393
   190
    SDL_GL_CONTEXT_PROFILE_MASK,
icculus@7853
   191
    SDL_GL_SHARE_WITH_CURRENT_CONTEXT,
icculus@7853
   192
    SDL_GL_FRAMEBUFFER_SRGB_CAPABLE
slouken@0
   193
} SDL_GLattr;
slouken@0
   194
slouken@6296
   195
typedef enum
slouken@6296
   196
{
slouken@6296
   197
    SDL_GL_CONTEXT_PROFILE_CORE           = 0x0001,
slouken@6296
   198
    SDL_GL_CONTEXT_PROFILE_COMPATIBILITY  = 0x0002,
gabomdq@7659
   199
    SDL_GL_CONTEXT_PROFILE_ES             = 0x0004 /* GLX_CONTEXT_ES2_PROFILE_BIT_EXT */
slouken@6296
   200
} SDL_GLprofile;
slouken@6296
   201
slouken@6296
   202
typedef enum
slouken@6296
   203
{
slouken@6296
   204
    SDL_GL_CONTEXT_DEBUG_FLAG              = 0x0001,
slouken@6296
   205
    SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG = 0x0002,
slouken@6393
   206
    SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG      = 0x0004,
slouken@6393
   207
    SDL_GL_CONTEXT_RESET_ISOLATION_FLAG    = 0x0008
slouken@6296
   208
} SDL_GLcontextFlag;
slouken@6296
   209
slouken@0
   210
slouken@0
   211
/* Function prototypes */
slouken@0
   212
slouken@1895
   213
/**
slouken@3407
   214
 *  \brief Get the number of video drivers compiled into SDL
slouken@7191
   215
 *
slouken@3407
   216
 *  \sa SDL_GetVideoDriver()
slouken@0
   217
 */
slouken@1895
   218
extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
slouken@1895
   219
slouken@1895
   220
/**
slouken@3407
   221
 *  \brief Get the name of a built in video driver.
slouken@7191
   222
 *
slouken@3407
   223
 *  \note The video drivers are presented in the order in which they are
slouken@3407
   224
 *        normally checked during initialization.
slouken@7191
   225
 *
slouken@3407
   226
 *  \sa SDL_GetNumVideoDrivers()
slouken@1895
   227
 */
slouken@1895
   228
extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
slouken@1895
   229
slouken@1895
   230
/**
slouken@3407
   231
 *  \brief Initialize the video subsystem, optionally specifying a video driver.
slouken@7191
   232
 *
slouken@7191
   233
 *  \param driver_name Initialize a specific driver by name, or NULL for the
slouken@3407
   234
 *                     default video driver.
slouken@7191
   235
 *
slouken@3407
   236
 *  \return 0 on success, -1 on error
slouken@7191
   237
 *
slouken@3407
   238
 *  This function initializes the video subsystem; setting up a connection
slouken@3407
   239
 *  to the window manager, etc, and determines the available display modes
slouken@3407
   240
 *  and pixel formats, but does not initialize a window or graphics mode.
slouken@7191
   241
 *
slouken@3407
   242
 *  \sa SDL_VideoQuit()
slouken@1895
   243
 */
slouken@5123
   244
extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name);
slouken@1895
   245
slouken@1895
   246
/**
slouken@3407
   247
 *  \brief Shuts down the video subsystem.
slouken@7191
   248
 *
slouken@3407
   249
 *  This function closes all windows, and restores the original video mode.
slouken@7191
   250
 *
slouken@3407
   251
 *  \sa SDL_VideoInit()
slouken@1895
   252
 */
slouken@337
   253
extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
slouken@0
   254
slouken@1895
   255
/**
slouken@3407
   256
 *  \brief Returns the name of the currently initialized video driver.
slouken@7191
   257
 *
slouken@3407
   258
 *  \return The name of the current video driver or NULL if no driver
slouken@3407
   259
 *          has been initialized
slouken@7191
   260
 *
slouken@3407
   261
 *  \sa SDL_GetNumVideoDrivers()
slouken@3407
   262
 *  \sa SDL_GetVideoDriver()
slouken@0
   263
 */
slouken@1895
   264
extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);
slouken@0
   265
slouken@1895
   266
/**
slouken@3407
   267
 *  \brief Returns the number of available video displays.
slouken@7191
   268
 *
slouken@3528
   269
 *  \sa SDL_GetDisplayBounds()
slouken@0
   270
 */
slouken@1895
   271
extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void);
slouken@0
   272
slouken@1895
   273
/**
slouken@6787
   274
 *  \brief Get the name of a display in UTF-8 encoding
slouken@7191
   275
 *
slouken@6787
   276
 *  \return The name of a display, or NULL for an invalid display index.
slouken@7191
   277
 *
slouken@6787
   278
 *  \sa SDL_GetNumVideoDisplays()
slouken@6787
   279
 */
slouken@6787
   280
extern DECLSPEC const char * SDLCALL SDL_GetDisplayName(int displayIndex);
slouken@6787
   281
slouken@6787
   282
/**
slouken@3528
   283
 *  \brief Get the desktop area represented by a display, with the primary
slouken@3528
   284
 *         display located at 0,0
slouken@7191
   285
 *
slouken@3528
   286
 *  \return 0 on success, or -1 if the index is out of range.
slouken@7191
   287
 *
slouken@3528
   288
 *  \sa SDL_GetNumVideoDisplays()
slouken@3528
   289
 */
slouken@5244
   290
extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect * rect);
slouken@3528
   291
slouken@3528
   292
/**
slouken@5244
   293
 *  \brief Returns the number of available display modes.
slouken@7191
   294
 *
slouken@3407
   295
 *  \sa SDL_GetDisplayMode()
slouken@0
   296
 */
slouken@5244
   297
extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex);
slouken@0
   298
slouken@1895
   299
/**
slouken@3407
   300
 *  \brief Fill in information about a specific display mode.
slouken@7191
   301
 *
slouken@3407
   302
 *  \note The display modes are sorted in this priority:
slouken@3407
   303
 *        \li bits per pixel -> more colors to fewer colors
slouken@3407
   304
 *        \li width -> largest to smallest
slouken@3407
   305
 *        \li height -> largest to smallest
slouken@3407
   306
 *        \li refresh rate -> highest to lowest
slouken@7191
   307
 *
slouken@3407
   308
 *  \sa SDL_GetNumDisplayModes()
slouken@0
   309
 */
slouken@5244
   310
extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex,
slouken@1967
   311
                                               SDL_DisplayMode * mode);
slouken@0
   312
slouken@1895
   313
/**
slouken@5244
   314
 *  \brief Fill in information about the desktop display mode.
slouken@1895
   315
 */
slouken@5244
   316
extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_DisplayMode * mode);
slouken@1895
   317
slouken@1895
   318
/**
slouken@3407
   319
 *  \brief Fill in information about the current display mode.
slouken@1895
   320
 */
slouken@5244
   321
extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_DisplayMode * mode);
slouken@1895
   322
slouken@3400
   323
slouken@1895
   324
/**
slouken@3407
   325
 *  \brief Get the closest match to the requested display mode.
slouken@7191
   326
 *
philipp@7188
   327
 *  \param displayIndex The index of display from which mode should be queried.
slouken@3407
   328
 *  \param mode The desired display mode
slouken@7191
   329
 *  \param closest A pointer to a display mode to be filled in with the closest
slouken@3407
   330
 *                 match of the available display modes.
slouken@7191
   331
 *
slouken@7191
   332
 *  \return The passed in value \c closest, or NULL if no matching video mode
slouken@3407
   333
 *          was available.
slouken@7191
   334
 *
slouken@3407
   335
 *  The available display modes are scanned, and \c closest is filled in with the
slouken@7191
   336
 *  closest mode matching the requested mode and returned.  The mode format and
slouken@7191
   337
 *  refresh_rate default to the desktop mode if they are 0.  The modes are
slouken@7191
   338
 *  scanned with size being first priority, format being second priority, and
slouken@7191
   339
 *  finally checking the refresh_rate.  If all the available modes are too
slouken@3407
   340
 *  small, then NULL is returned.
slouken@7191
   341
 *
slouken@3407
   342
 *  \sa SDL_GetNumDisplayModes()
slouken@3407
   343
 *  \sa SDL_GetDisplayMode()
slouken@1895
   344
 */
slouken@5244
   345
extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest);
slouken@1895
   346
slouken@1895
   347
/**
slouken@5246
   348
 *  \brief Get the display index associated with a window.
slouken@7191
   349
 *
slouken@5246
   350
 *  \return the display index of the display containing the center of the
slouken@5246
   351
 *          window, or -1 on error.
slouken@5246
   352
 */
slouken@6786
   353
extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window * window);
slouken@5246
   354
slouken@5246
   355
/**
slouken@5244
   356
 *  \brief Set the display mode used when a fullscreen window is visible.
slouken@5244
   357
 *
slouken@5244
   358
 *  By default the window's dimensions and the desktop format and refresh rate
slouken@5244
   359
 *  are used.
slouken@7191
   360
 *
philipp@7188
   361
 *  \param window The window for which the display mode should be set.
slouken@3500
   362
 *  \param mode The mode to use, or NULL for the default mode.
slouken@7191
   363
 *
slouken@3407
   364
 *  \return 0 on success, or -1 if setting the display mode failed.
slouken@7191
   365
 *
slouken@3522
   366
 *  \sa SDL_GetWindowDisplayMode()
slouken@3407
   367
 *  \sa SDL_SetWindowFullscreen()
slouken@0
   368
 */
slouken@3685
   369
extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window * window,
slouken@3500
   370
                                                     const SDL_DisplayMode
slouken@1895
   371
                                                         * mode);
slouken@0
   372
slouken@1895
   373
/**
slouken@3407
   374
 *  \brief Fill in information about the display mode used when a fullscreen
slouken@5244
   375
 *         window is visible.
slouken@3522
   376
 *
slouken@3522
   377
 *  \sa SDL_SetWindowDisplayMode()
slouken@3522
   378
 *  \sa SDL_SetWindowFullscreen()
slouken@0
   379
 */
slouken@3685
   380
extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window,
slouken@3500
   381
                                                     SDL_DisplayMode * mode);
slouken@0
   382
slouken@1895
   383
/**
slouken@5154
   384
 *  \brief Get the pixel format associated with the window.
slouken@5154
   385
 */
slouken@5154
   386
extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
slouken@5154
   387
slouken@5154
   388
/**
slouken@3407
   389
 *  \brief Create a window with the specified position, dimensions, and flags.
slouken@7191
   390
 *
slouken@3407
   391
 *  \param title The title of the window, in UTF-8 encoding.
slouken@7191
   392
 *  \param x     The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
slouken@3407
   393
 *               ::SDL_WINDOWPOS_UNDEFINED.
slouken@7191
   394
 *  \param y     The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
slouken@3407
   395
 *               ::SDL_WINDOWPOS_UNDEFINED.
slouken@3407
   396
 *  \param w     The width of the window.
slouken@3407
   397
 *  \param h     The height of the window.
slouken@7191
   398
 *  \param flags The flags for the window, a mask of any of the following:
urkle@7746
   399
 *               ::SDL_WINDOW_FULLSCREEN,    ::SDL_WINDOW_OPENGL,
urkle@7746
   400
 *               ::SDL_WINDOW_HIDDEN,        ::SDL_WINDOW_BORDERLESS,
urkle@7746
   401
 *               ::SDL_WINDOW_RESIZABLE,     ::SDL_WINDOW_MAXIMIZED,
urkle@7746
   402
 *               ::SDL_WINDOW_MINIMIZED,     ::SDL_WINDOW_INPUT_GRABBED,
urkle@7746
   403
 *               ::SDL_WINDOW_ALLOW_HIGHDPI.
slouken@7191
   404
 *
slouken@3407
   405
 *  \return The id of the window created, or zero if window creation failed.
slouken@7191
   406
 *
slouken@3407
   407
 *  \sa SDL_DestroyWindow()
slouken@0
   408
 */
slouken@3685
   409
extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title,
slouken@1895
   410
                                                      int x, int y, int w,
slouken@1895
   411
                                                      int h, Uint32 flags);
slouken@0
   412
slouken@1895
   413
/**
slouken@3493
   414
 *  \brief Create an SDL window from an existing native window.
slouken@7191
   415
 *
slouken@3407
   416
 *  \param data A pointer to driver-dependent window creation data
slouken@7191
   417
 *
slouken@3407
   418
 *  \return The id of the window created, or zero if window creation failed.
slouken@7191
   419
 *
slouken@3407
   420
 *  \sa SDL_DestroyWindow()
slouken@0
   421
 */
slouken@3685
   422
extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowFrom(const void *data);
slouken@3685
   423
slouken@3685
   424
/**
slouken@4883
   425
 *  \brief Get the numeric ID of a window, for logging purposes.
slouken@3685
   426
 */
slouken@3685
   427
extern DECLSPEC Uint32 SDLCALL SDL_GetWindowID(SDL_Window * window);
slouken@3685
   428
slouken@3685
   429
/**
slouken@3685
   430
 *  \brief Get a window from a stored ID, or NULL if it doesn't exist.
slouken@3685
   431
 */
slouken@3685
   432
extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(Uint32 id);
slouken@1895
   433
slouken@1895
   434
/**
slouken@3407
   435
 *  \brief Get the window flags.
slouken@1895
   436
 */
slouken@3685
   437
extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window);
slouken@1895
   438
slouken@1895
   439
/**
slouken@4883
   440
 *  \brief Set the title of a window, in UTF-8 format.
slouken@7191
   441
 *
slouken@3407
   442
 *  \sa SDL_GetWindowTitle()
slouken@1895
   443
 */
slouken@3685
   444
extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window,
slouken@1895
   445
                                                const char *title);
slouken@1895
   446
slouken@1895
   447
/**
slouken@4883
   448
 *  \brief Get the title of a window, in UTF-8 format.
slouken@7191
   449
 *
slouken@3407
   450
 *  \sa SDL_SetWindowTitle()
slouken@1895
   451
 */
slouken@3685
   452
extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window);
slouken@1895
   453
slouken@1895
   454
/**
slouken@4887
   455
 *  \brief Set the icon for a window.
slouken@7191
   456
 *
philipp@7188
   457
 *  \param window The window for which the icon should be set.
slouken@4887
   458
 *  \param icon The icon for the window.
slouken@1895
   459
 */
slouken@3685
   460
extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window,
slouken@2990
   461
                                               SDL_Surface * icon);
slouken@1895
   462
slouken@1895
   463
/**
slouken@5165
   464
 *  \brief Associate an arbitrary named pointer with a window.
slouken@7191
   465
 *
slouken@5165
   466
 *  \param window   The window to associate with the pointer.
slouken@5165
   467
 *  \param name     The name of the pointer.
slouken@5165
   468
 *  \param userdata The associated pointer.
slouken@5165
   469
 *
slouken@5165
   470
 *  \return The previous value associated with 'name'
slouken@5165
   471
 *
slouken@5165
   472
 *  \note The name is case-sensitive.
slouken@5165
   473
 *
slouken@3407
   474
 *  \sa SDL_GetWindowData()
slouken@1895
   475
 */
slouken@5165
   476
extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * window,
slouken@5165
   477
                                                const char *name,
slouken@5165
   478
                                                void *userdata);
slouken@1895
   479
slouken@1895
   480
/**
slouken@4883
   481
 *  \brief Retrieve the data pointer associated with a window.
slouken@7191
   482
 *
slouken@5165
   483
 *  \param window   The window to query.
slouken@5165
   484
 *  \param name     The name of the pointer.
slouken@5165
   485
 *
slouken@5165
   486
 *  \return The value associated with 'name'
slouken@7191
   487
 *
slouken@3407
   488
 *  \sa SDL_SetWindowData()
slouken@1895
   489
 */
slouken@5165
   490
extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window,
slouken@5165
   491
                                                const char *name);
slouken@1895
   492
slouken@1895
   493
/**
slouken@4883
   494
 *  \brief Set the position of a window.
slouken@7191
   495
 *
slouken@5165
   496
 *  \param window   The window to reposition.
slouken@3407
   497
 *  \param x        The x coordinate of the window, ::SDL_WINDOWPOS_CENTERED, or
slouken@3407
   498
                    ::SDL_WINDOWPOS_UNDEFINED.
slouken@3407
   499
 *  \param y        The y coordinate of the window, ::SDL_WINDOWPOS_CENTERED, or
slouken@3407
   500
                    ::SDL_WINDOWPOS_UNDEFINED.
slouken@7191
   501
 *
slouken@3407
   502
 *  \note The window coordinate origin is the upper left of the display.
slouken@7191
   503
 *
slouken@3407
   504
 *  \sa SDL_GetWindowPosition()
slouken@1895
   505
 */
slouken@3685
   506
extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window,
slouken@1895
   507
                                                   int x, int y);
slouken@1895
   508
slouken@1895
   509
/**
slouken@4883
   510
 *  \brief Get the position of a window.
slouken@7191
   511
 *
philipp@7175
   512
 *  \param window   The window to query.
aschiffler@6984
   513
 *  \param x        Pointer to variable for storing the x position, may be NULL
aschiffler@6984
   514
 *  \param y        Pointer to variable for storing the y position, may be NULL
aschiffler@6984
   515
 *
slouken@3407
   516
 *  \sa SDL_SetWindowPosition()
slouken@1895
   517
 */
slouken@3685
   518
extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window,
slouken@1895
   519
                                                   int *x, int *y);
slouken@1895
   520
slouken@1895
   521
/**
slouken@4883
   522
 *  \brief Set the size of a window's client area.
slouken@7191
   523
 *
philipp@7175
   524
 *  \param window   The window to resize.
aschiffler@6984
   525
 *  \param w        The width of the window, must be >0
aschiffler@6984
   526
 *  \param h        The height of the window, must be >0
aschiffler@6984
   527
 *
slouken@3407
   528
 *  \note You can't change the size of a fullscreen window, it automatically
slouken@3407
   529
 *        matches the size of the display mode.
slouken@7191
   530
 *
slouken@3407
   531
 *  \sa SDL_GetWindowSize()
slouken@1895
   532
 */
slouken@3685
   533
extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w,
slouken@1895
   534
                                               int h);
slouken@1895
   535
slouken@1895
   536
/**
slouken@4883
   537
 *  \brief Get the size of a window's client area.
slouken@7191
   538
 *
philipp@7175
   539
 *  \param window   The window to query.
aschiffler@6984
   540
 *  \param w        Pointer to variable for storing the width, may be NULL
aschiffler@6984
   541
 *  \param h        Pointer to variable for storing the height, may be NULL
slouken@7191
   542
 *
slouken@3407
   543
 *  \sa SDL_SetWindowSize()
slouken@1895
   544
 */
slouken@3685
   545
extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window * window, int *w,
slouken@1895
   546
                                               int *h);
slouken@7191
   547
stopiccot@6681
   548
/**
stopiccot@6681
   549
 *  \brief Set the minimum size of a window's client area.
slouken@7191
   550
 *
philipp@7175
   551
 *  \param window    The window to set a new minimum size.
aschiffler@6984
   552
 *  \param min_w     The minimum width of the window, must be >0
aschiffler@6984
   553
 *  \param min_h     The minimum height of the window, must be >0
stopiccot@6681
   554
 *
stopiccot@6681
   555
 *  \note You can't change the minimum size of a fullscreen window, it
stopiccot@6681
   556
 *        automatically matches the size of the display mode.
stopiccot@6681
   557
 *
stopiccot@6681
   558
 *  \sa SDL_GetWindowMinimumSize()
slouken@6788
   559
 *  \sa SDL_SetWindowMaximumSize()
stopiccot@6681
   560
 */
stopiccot@6681
   561
extern DECLSPEC void SDLCALL SDL_SetWindowMinimumSize(SDL_Window * window,
stopiccot@6681
   562
                                                      int min_w, int min_h);
slouken@7191
   563
stopiccot@6681
   564
/**
stopiccot@6681
   565
 *  \brief Get the minimum size of a window's client area.
slouken@7191
   566
 *
philipp@7175
   567
 *  \param window   The window to query.
aschiffler@6984
   568
 *  \param w        Pointer to variable for storing the minimum width, may be NULL
aschiffler@6984
   569
 *  \param h        Pointer to variable for storing the minimum height, may be NULL
slouken@7191
   570
 *
slouken@6788
   571
 *  \sa SDL_GetWindowMaximumSize()
stopiccot@6681
   572
 *  \sa SDL_SetWindowMinimumSize()
stopiccot@6681
   573
 */
stopiccot@6681
   574
extern DECLSPEC void SDLCALL SDL_GetWindowMinimumSize(SDL_Window * window,
stopiccot@6681
   575
                                                      int *w, int *h);
slouken@1895
   576
slouken@1895
   577
/**
slouken@6788
   578
 *  \brief Set the maximum size of a window's client area.
slouken@6788
   579
 *
philipp@7175
   580
 *  \param window    The window to set a new maximum size.
aschiffler@6984
   581
 *  \param max_w     The maximum width of the window, must be >0
aschiffler@6984
   582
 *  \param max_h     The maximum height of the window, must be >0
aschiffler@6984
   583
 *
slouken@6788
   584
 *  \note You can't change the maximum size of a fullscreen window, it
slouken@6788
   585
 *        automatically matches the size of the display mode.
slouken@6788
   586
 *
slouken@6788
   587
 *  \sa SDL_GetWindowMaximumSize()
slouken@6788
   588
 *  \sa SDL_SetWindowMinimumSize()
slouken@6788
   589
 */
slouken@6788
   590
extern DECLSPEC void SDLCALL SDL_SetWindowMaximumSize(SDL_Window * window,
slouken@6788
   591
                                                      int max_w, int max_h);
slouken@7191
   592
slouken@6788
   593
/**
slouken@6788
   594
 *  \brief Get the maximum size of a window's client area.
slouken@7191
   595
 *
philipp@7175
   596
 *  \param window   The window to query.
aschiffler@6984
   597
 *  \param w        Pointer to variable for storing the maximum width, may be NULL
aschiffler@6984
   598
 *  \param h        Pointer to variable for storing the maximum height, may be NULL
slouken@6788
   599
 *
slouken@6788
   600
 *  \sa SDL_GetWindowMinimumSize()
slouken@6788
   601
 *  \sa SDL_SetWindowMaximumSize()
slouken@6788
   602
 */
slouken@6788
   603
extern DECLSPEC void SDLCALL SDL_GetWindowMaximumSize(SDL_Window * window,
slouken@6788
   604
                                                      int *w, int *h);
slouken@6788
   605
slouken@6788
   606
/**
icculus@6422
   607
 *  \brief Set the border state of a window.
icculus@6422
   608
 *
icculus@6422
   609
 *  This will add or remove the window's SDL_WINDOW_BORDERLESS flag and
icculus@6422
   610
 *  add or remove the border from the actual window. This is a no-op if the
icculus@6422
   611
 *  window's border already matches the requested state.
icculus@6422
   612
 *
icculus@6422
   613
 *  \param window The window of which to change the border state.
icculus@6422
   614
 *  \param bordered SDL_FALSE to remove border, SDL_TRUE to add border.
icculus@6422
   615
 *
icculus@6422
   616
 *  \note You can't change the border state of a fullscreen window.
slouken@7191
   617
 *
icculus@6422
   618
 *  \sa SDL_GetWindowFlags()
icculus@6422
   619
 */
icculus@6422
   620
extern DECLSPEC void SDLCALL SDL_SetWindowBordered(SDL_Window * window,
icculus@6422
   621
                                                   SDL_bool bordered);
icculus@6422
   622
icculus@6422
   623
/**
slouken@4883
   624
 *  \brief Show a window.
slouken@7191
   625
 *
slouken@3407
   626
 *  \sa SDL_HideWindow()
slouken@1895
   627
 */
slouken@3685
   628
extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_Window * window);
slouken@1895
   629
slouken@1895
   630
/**
slouken@4883
   631
 *  \brief Hide a window.
slouken@7191
   632
 *
slouken@3407
   633
 *  \sa SDL_ShowWindow()
slouken@1895
   634
 */
slouken@3685
   635
extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_Window * window);
slouken@1895
   636
slouken@1895
   637
/**
slouken@4883
   638
 *  \brief Raise a window above other windows and set the input focus.
slouken@1895
   639
 */
slouken@3685
   640
extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_Window * window);
slouken@1895
   641
slouken@1895
   642
/**
slouken@4883
   643
 *  \brief Make a window as large as possible.
slouken@7191
   644
 *
slouken@3407
   645
 *  \sa SDL_RestoreWindow()
slouken@1895
   646
 */
slouken@3685
   647
extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_Window * window);
slouken@1895
   648
slouken@1895
   649
/**
slouken@4883
   650
 *  \brief Minimize a window to an iconic representation.
slouken@7191
   651
 *
slouken@3407
   652
 *  \sa SDL_RestoreWindow()
slouken@1895
   653
 */
slouken@3685
   654
extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window);
slouken@1895
   655
slouken@1895
   656
/**
slouken@3407
   657
 *  \brief Restore the size and position of a minimized or maximized window.
slouken@7191
   658
 *
slouken@3407
   659
 *  \sa SDL_MaximizeWindow()
slouken@3407
   660
 *  \sa SDL_MinimizeWindow()
slouken@1895
   661
 */
slouken@3685
   662
extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window);
slouken@1895
   663
slouken@1895
   664
/**
slouken@4883
   665
 *  \brief Set a window's fullscreen state.
slouken@7191
   666
 *
slouken@3407
   667
 *  \return 0 on success, or -1 if setting the display mode failed.
slouken@7191
   668
 *
slouken@3522
   669
 *  \sa SDL_SetWindowDisplayMode()
slouken@3522
   670
 *  \sa SDL_GetWindowDisplayMode()
slouken@1895
   671
 */
slouken@3685
   672
extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window * window,
slouken@6755
   673
                                                    Uint32 flags);
slouken@1895
   674
slouken@1895
   675
/**
slouken@5546
   676
 *  \brief Get the SDL surface associated with the window.
slouken@5166
   677
 *
slouken@7191
   678
 *  \return The window's framebuffer surface, or NULL on error.
slouken@5546
   679
 *
slouken@5546
   680
 *  A new surface will be created with the optimal format for the window,
slouken@5546
   681
 *  if necessary. This surface will be freed when the window is destroyed.
slouken@5166
   682
 *
slouken@5166
   683
 *  \note You may not combine this with 3D or the rendering API on this window.
slouken@5166
   684
 *
slouken@5166
   685
 *  \sa SDL_UpdateWindowSurface()
slouken@5166
   686
 *  \sa SDL_UpdateWindowSurfaceRects()
slouken@5166
   687
 */
slouken@5166
   688
extern DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window * window);
slouken@5166
   689
slouken@5166
   690
/**
slouken@5166
   691
 *  \brief Copy the window surface to the screen.
slouken@5166
   692
 *
slouken@5166
   693
 *  \return 0 on success, or -1 on error.
slouken@5166
   694
 *
slouken@5166
   695
 *  \sa SDL_GetWindowSurface()
slouken@5166
   696
 *  \sa SDL_UpdateWindowSurfaceRects()
slouken@5166
   697
 */
slouken@5166
   698
extern DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window * window);
slouken@5166
   699
slouken@5166
   700
/**
slouken@5166
   701
 *  \brief Copy a number of rectangles on the window surface to the screen.
slouken@5166
   702
 *
slouken@5166
   703
 *  \return 0 on success, or -1 on error.
slouken@5166
   704
 *
slouken@5166
   705
 *  \sa SDL_GetWindowSurface()
slouken@5166
   706
 *  \sa SDL_UpdateWindowSurfaceRect()
slouken@5166
   707
 */
slouken@5166
   708
extern DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window * window,
slouken@7014
   709
                                                         const SDL_Rect * rects,
slouken@5297
   710
                                                         int numrects);
slouken@5166
   711
slouken@5166
   712
/**
slouken@4883
   713
 *  \brief Set a window's input grab mode.
slouken@7191
   714
 *
philipp@7188
   715
 *  \param window The window for which the input grab mode should be set.
slouken@5403
   716
 *  \param grabbed This is SDL_TRUE to grab input, and SDL_FALSE to release input.
slouken@7191
   717
 *
slouken@3407
   718
 *  \sa SDL_GetWindowGrab()
slouken@1895
   719
 */
slouken@3685
   720
extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window,
slouken@5403
   721
                                               SDL_bool grabbed);
slouken@1895
   722
slouken@1895
   723
/**
slouken@4883
   724
 *  \brief Get a window's input grab mode.
slouken@7191
   725
 *
slouken@5403
   726
 *  \return This returns SDL_TRUE if input is grabbed, and SDL_FALSE otherwise.
slouken@7191
   727
 *
slouken@3407
   728
 *  \sa SDL_SetWindowGrab()
slouken@1895
   729
 */
slouken@5403
   730
extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window * window);
slouken@1895
   731
slouken@1895
   732
/**
slouken@5466
   733
 *  \brief Set the brightness (gamma correction) for a window.
slouken@7191
   734
 *
slouken@5466
   735
 *  \return 0 on success, or -1 if setting the brightness isn't supported.
slouken@7191
   736
 *
slouken@5466
   737
 *  \sa SDL_GetWindowBrightness()
slouken@5466
   738
 *  \sa SDL_SetWindowGammaRamp()
slouken@5466
   739
 */
slouken@5466
   740
extern DECLSPEC int SDLCALL SDL_SetWindowBrightness(SDL_Window * window, float brightness);
slouken@5466
   741
slouken@5466
   742
/**
slouken@5466
   743
 *  \brief Get the brightness (gamma correction) for a window.
slouken@7191
   744
 *
slouken@5466
   745
 *  \return The last brightness value passed to SDL_SetWindowBrightness()
slouken@7191
   746
 *
slouken@5466
   747
 *  \sa SDL_SetWindowBrightness()
slouken@5466
   748
 */
slouken@5466
   749
extern DECLSPEC float SDLCALL SDL_GetWindowBrightness(SDL_Window * window);
slouken@5466
   750
slouken@5466
   751
/**
slouken@5466
   752
 *  \brief Set the gamma ramp for a window.
slouken@7191
   753
 *
philipp@7188
   754
 *  \param window The window for which the gamma ramp should be set.
slouken@5466
   755
 *  \param red The translation table for the red channel, or NULL.
slouken@5466
   756
 *  \param green The translation table for the green channel, or NULL.
slouken@5466
   757
 *  \param blue The translation table for the blue channel, or NULL.
slouken@7191
   758
 *
slouken@5466
   759
 *  \return 0 on success, or -1 if gamma ramps are unsupported.
slouken@7191
   760
 *
slouken@5466
   761
 *  Set the gamma translation table for the red, green, and blue channels
slouken@5466
   762
 *  of the video hardware.  Each table is an array of 256 16-bit quantities,
slouken@5466
   763
 *  representing a mapping between the input and output for that channel.
slouken@5466
   764
 *  The input is the index into the array, and the output is the 16-bit
slouken@5466
   765
 *  gamma value at that index, scaled to the output color precision.
slouken@5466
   766
 *
slouken@5504
   767
 *  \sa SDL_GetWindowGammaRamp()
slouken@5466
   768
 */
slouken@5466
   769
extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window,
slouken@5466
   770
                                                   const Uint16 * red,
slouken@5466
   771
                                                   const Uint16 * green,
slouken@5466
   772
                                                   const Uint16 * blue);
slouken@5466
   773
slouken@5466
   774
/**
slouken@5466
   775
 *  \brief Get the gamma ramp for a window.
slouken@7191
   776
 *
philipp@7188
   777
 *  \param window The window from which the gamma ramp should be queried.
slouken@7191
   778
 *  \param red   A pointer to a 256 element array of 16-bit quantities to hold
slouken@5466
   779
 *               the translation table for the red channel, or NULL.
slouken@7191
   780
 *  \param green A pointer to a 256 element array of 16-bit quantities to hold
slouken@5466
   781
 *               the translation table for the green channel, or NULL.
slouken@7191
   782
 *  \param blue  A pointer to a 256 element array of 16-bit quantities to hold
slouken@5466
   783
 *               the translation table for the blue channel, or NULL.
slouken@7191
   784
 *
slouken@5466
   785
 *  \return 0 on success, or -1 if gamma ramps are unsupported.
slouken@7191
   786
 *
slouken@5466
   787
 *  \sa SDL_SetWindowGammaRamp()
slouken@5466
   788
 */
slouken@5466
   789
extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window,
slouken@5466
   790
                                                   Uint16 * red,
slouken@5466
   791
                                                   Uint16 * green,
slouken@5466
   792
                                                   Uint16 * blue);
slouken@5466
   793
icculus@8937
   794
/**
icculus@8937
   795
 *  \brief Possible return values from the SDL_HitTest callback.
icculus@8937
   796
 *
icculus@8937
   797
 *  \sa SDL_HitTest
icculus@8937
   798
 */
icculus@8935
   799
typedef enum
icculus@8935
   800
{
icculus@8935
   801
    SDL_HITTEST_NORMAL,  /**< Region is normal. No special properties. */
icculus@8935
   802
    SDL_HITTEST_DRAGGABLE,  /**< Region can drag entire window. */
ionut@8946
   803
    SDL_HITTEST_RESIZE_TOPLEFT,
ionut@8946
   804
    SDL_HITTEST_RESIZE_TOP,
ionut@8946
   805
    SDL_HITTEST_RESIZE_TOPRIGHT,
ionut@8946
   806
    SDL_HITTEST_RESIZE_RIGHT,
ionut@8946
   807
    SDL_HITTEST_RESIZE_BOTTOMRIGHT,
ionut@8946
   808
    SDL_HITTEST_RESIZE_BOTTOM,
ionut@8946
   809
    SDL_HITTEST_RESIZE_BOTTOMLEFT,
ionut@8946
   810
    SDL_HITTEST_RESIZE_LEFT
icculus@8935
   811
} SDL_HitTestResult;
icculus@8935
   812
icculus@8937
   813
/**
icculus@8937
   814
 *  \brief Callback used for hit-testing.
icculus@8937
   815
 *
icculus@8937
   816
 *  \sa SDL_SetWindowHitTest
icculus@8937
   817
 */
icculus@8935
   818
typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win,
icculus@8935
   819
                                                 const SDL_Point *area,
icculus@8935
   820
                                                 void *data);
icculus@8935
   821
slouken@5466
   822
/**
icculus@8935
   823
 *  \brief Provide a callback that decides if a window region has special properties.
icculus@8931
   824
 *
icculus@8935
   825
 *  Normally windows are dragged and resized by decorations provided by the
icculus@8935
   826
 *  system window manager (a title bar, borders, etc), but for some apps, it
icculus@8935
   827
 *  makes sense to drag them from somewhere else inside the window itself; for
icculus@8935
   828
 *  example, one might have a borderless window that wants to be draggable
icculus@8935
   829
 *  from any part, or simulate its own title bar, etc.
icculus@8931
   830
 *
icculus@8935
   831
 *  This function lets the app provide a callback that designates pieces of
icculus@8935
   832
 *  a given window as special. This callback is run during event processing
icculus@8935
   833
 *  if we need to tell the OS to treat a region of the window specially; the
icculus@8935
   834
 *  use of this callback is known as "hit testing."
icculus@8931
   835
 *
icculus@8931
   836
 *  Mouse input may not be delivered to your application if it is within
icculus@8935
   837
 *  a special area; the OS will often apply that input to moving the window or
icculus@8935
   838
 *  resizing the window and not deliver it to the application.
icculus@8935
   839
 *
icculus@8935
   840
 *  Specifying NULL for a callback disables hit-testing. Hit-testing is
icculus@8935
   841
 *  disabled by default.
icculus@8931
   842
 *
icculus@8931
   843
 *  Platforms that don't support this functionality will return -1
icculus@8935
   844
 *  unconditionally, even if you're attempting to disable hit-testing.
icculus@8931
   845
 *
icculus@8937
   846
 *  Your callback may fire at any time, and its firing does not indicate any
icculus@8937
   847
 *  specific behavior (for example, on Windows, this certainly might fire
icculus@8937
   848
 *  when the OS is deciding whether to drag your window, but it fires for lots
icculus@8937
   849
 *  of other reasons, too, some unrelated to anything you probably care about
icculus@8937
   850
 *  _and when the mouse isn't actually at the location it is testing_).
icculus@8937
   851
 *  Since this can fire at any time, you should try to keep your callback
icculus@8937
   852
 *  efficient, devoid of allocations, etc.
icculus@8935
   853
 *
icculus@8935
   854
 *  \param window The window to set hit-testing on.
icculus@8935
   855
 *  \param callback The callback to call when doing a hit-test.
icculus@8935
   856
 *  \param callback_data An app-defined void pointer passed to the callback.
icculus@8931
   857
 *  \return 0 on success, -1 on error (including unsupported).
icculus@8931
   858
 */
icculus@8935
   859
extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window,
icculus@8935
   860
                                                 SDL_HitTest callback,
icculus@8935
   861
                                                 void *callback_data);
icculus@8931
   862
icculus@8931
   863
/**
slouken@3407
   864
 *  \brief Destroy a window.
slouken@1895
   865
 */
slouken@3685
   866
extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window * window);
slouken@1895
   867
slouken@0
   868
slouken@3025
   869
/**
slouken@4875
   870
 *  \brief Returns whether the screensaver is currently enabled (default on).
slouken@7191
   871
 *
slouken@3407
   872
 *  \sa SDL_EnableScreenSaver()
slouken@3407
   873
 *  \sa SDL_DisableScreenSaver()
slouken@3025
   874
 */
couriersud@3033
   875
extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenSaverEnabled(void);
slouken@3025
   876
slouken@3025
   877
/**
slouken@3407
   878
 *  \brief Allow the screen to be blanked by a screensaver
slouken@7191
   879
 *
slouken@3407
   880
 *  \sa SDL_IsScreenSaverEnabled()
slouken@3407
   881
 *  \sa SDL_DisableScreenSaver()
slouken@3025
   882
 */
couriersud@3033
   883
extern DECLSPEC void SDLCALL SDL_EnableScreenSaver(void);
slouken@3025
   884
slouken@3025
   885
/**
slouken@3407
   886
 *  \brief Prevent the screen from being blanked by a screensaver
slouken@7191
   887
 *
slouken@3407
   888
 *  \sa SDL_IsScreenSaverEnabled()
slouken@3407
   889
 *  \sa SDL_EnableScreenSaver()
slouken@3025
   890
 */
couriersud@3033
   891
extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void);
slouken@3025
   892
slouken@0
   893
slouken@3407
   894
/**
slouken@3407
   895
 *  \name OpenGL support functions
slouken@3407
   896
 */
gabomdq@7678
   897
/* @{ */
slouken@0
   898
slouken@1895
   899
/**
slouken@3407
   900
 *  \brief Dynamically load an OpenGL library.
slouken@7191
   901
 *
slouken@7191
   902
 *  \param path The platform dependent OpenGL library name, or NULL to open the
slouken@3407
   903
 *              default OpenGL library.
slouken@7191
   904
 *
slouken@3407
   905
 *  \return 0 on success, or -1 if the library couldn't be loaded.
slouken@7191
   906
 *
slouken@3407
   907
 *  This should be done after initializing the video driver, but before
slouken@3407
   908
 *  creating any OpenGL windows.  If no OpenGL library is loaded, the default
slouken@3407
   909
 *  library will be loaded upon creation of the first OpenGL window.
slouken@7191
   910
 *
slouken@3407
   911
 *  \note If you do this, you need to retrieve all of the GL functions used in
slouken@3407
   912
 *        your program from the dynamic library using SDL_GL_GetProcAddress().
slouken@7191
   913
 *
slouken@3407
   914
 *  \sa SDL_GL_GetProcAddress()
slouken@3407
   915
 *  \sa SDL_GL_UnloadLibrary()
slouken@0
   916
 */
slouken@337
   917
extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
slouken@0
   918
slouken@1895
   919
/**
slouken@3407
   920
 *  \brief Get the address of an OpenGL function.
slouken@0
   921
 */
slouken@1895
   922
extern DECLSPEC void *SDLCALL SDL_GL_GetProcAddress(const char *proc);
slouken@0
   923
slouken@1895
   924
/**
slouken@3407
   925
 *  \brief Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary().
slouken@7191
   926
 *
slouken@3407
   927
 *  \sa SDL_GL_LoadLibrary()
slouken@3057
   928
 */
slouken@3057
   929
extern DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void);
slouken@3057
   930
slouken@3057
   931
/**
slouken@7191
   932
 *  \brief Return true if an OpenGL extension is supported for the current
slouken@3407
   933
 *         context.
slouken@1926
   934
 */
slouken@1926
   935
extern DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char
slouken@1926
   936
                                                           *extension);
slouken@1926
   937
slouken@1926
   938
/**
jorgen@8145
   939
 *  \brief Reset all previously set OpenGL context attributes to their default values
jorgen@8145
   940
 */
jorgen@8145
   941
extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void);
jorgen@8145
   942
jorgen@8145
   943
/**
slouken@3407
   944
 *  \brief Set an OpenGL window attribute before window creation.
slouken@0
   945
 */
slouken@337
   946
extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
slouken@0
   947
slouken@1895
   948
/**
slouken@3407
   949
 *  \brief Get the actual value for an attribute from the current context.
slouken@0
   950
 */
slouken@1936
   951
extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value);
slouken@0
   952
slouken@1895
   953
/**
slouken@7191
   954
 *  \brief Create an OpenGL context for use with an OpenGL window, and make it
slouken@3407
   955
 *         current.
slouken@7191
   956
 *
slouken@3407
   957
 *  \sa SDL_GL_DeleteContext()
slouken@1895
   958
 */
slouken@3685
   959
extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *
slouken@3685
   960
                                                           window);
slouken@1895
   961
slouken@1895
   962
/**
slouken@3407
   963
 *  \brief Set up an OpenGL context for rendering into an OpenGL window.
slouken@7191
   964
 *
slouken@3407
   965
 *  \note The context must have been created with a compatible window.
slouken@1895
   966
 */
slouken@3685
   967
extern DECLSPEC int SDLCALL SDL_GL_MakeCurrent(SDL_Window * window,
slouken@1895
   968
                                               SDL_GLContext context);
slouken@1895
   969
slouken@1895
   970
/**
slouken@7412
   971
 *  \brief Get the currently active OpenGL window.
slouken@7412
   972
 */
slouken@7412
   973
extern DECLSPEC SDL_Window* SDLCALL SDL_GL_GetCurrentWindow(void);
slouken@7412
   974
slouken@7412
   975
/**
slouken@7412
   976
 *  \brief Get the currently active OpenGL context.
slouken@7412
   977
 */
slouken@7412
   978
extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void);
slouken@7412
   979
slouken@7412
   980
/**
urkle@7746
   981
 *  \brief Get the size of a window's underlying drawable (for use with glViewport).
urkle@7746
   982
 *
philipp@7752
   983
 *  \param window   Window from which the drawable size should be queried
urkle@7746
   984
 *  \param w        Pointer to variable for storing the width, may be NULL
urkle@7746
   985
 *  \param h        Pointer to variable for storing the height, may be NULL
urkle@7746
   986
 *
philipp@8777
   987
 * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
urkle@7746
   988
 * drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a
urkle@7746
   989
 * platform with high-DPI support (Apple calls this "Retina"), and not disabled
urkle@7746
   990
 * by the SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
urkle@7746
   991
 *
urkle@7746
   992
 *  \sa SDL_GetWindowSize()
urkle@7746
   993
 *  \sa SDL_CreateWindow()
urkle@7746
   994
 */
urkle@7746
   995
extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w,
urkle@7746
   996
                                                    int *h);
urkle@7746
   997
urkle@7746
   998
/**
slouken@3407
   999
 *  \brief Set the swap interval for the current OpenGL context.
slouken@7191
  1000
 *
slouken@3407
  1001
 *  \param interval 0 for immediate updates, 1 for updates synchronized with the
icculus@6382
  1002
 *                  vertical retrace. If the system supports it, you may
icculus@6382
  1003
 *                  specify -1 to allow late swaps to happen immediately
icculus@6382
  1004
 *                  instead of waiting for the next retrace.
slouken@7191
  1005
 *
slouken@3407
  1006
 *  \return 0 on success, or -1 if setting the swap interval is not supported.
slouken@7191
  1007
 *
slouken@3407
  1008
 *  \sa SDL_GL_GetSwapInterval()
slouken@1895
  1009
 */
slouken@1895
  1010
extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval);
slouken@1895
  1011
slouken@1895
  1012
/**
slouken@3407
  1013
 *  \brief Get the swap interval for the current OpenGL context.
slouken@7191
  1014
 *
slouken@7191
  1015
 *  \return 0 if there is no vertical retrace synchronization, 1 if the buffer
icculus@6382
  1016
 *          swap is synchronized with the vertical retrace, and -1 if late
icculus@6382
  1017
 *          swaps happen immediately instead of waiting for the next retrace.
icculus@6382
  1018
 *          If the system can't determine the swap interval, or there isn't a
icculus@6382
  1019
 *          valid current context, this will return 0 as a safe default.
slouken@7191
  1020
 *
slouken@3407
  1021
 *  \sa SDL_GL_SetSwapInterval()
slouken@1895
  1022
 */
slouken@1895
  1023
extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void);
slouken@1895
  1024
slouken@1895
  1025
/**
slouken@7191
  1026
 * \brief Swap the OpenGL buffers for a window, if double-buffering is
slouken@3407
  1027
 *        supported.
slouken@0
  1028
 */
slouken@3685
  1029
extern DECLSPEC void SDLCALL SDL_GL_SwapWindow(SDL_Window * window);
slouken@0
  1030
slouken@1895
  1031
/**
slouken@3407
  1032
 *  \brief Delete an OpenGL context.
slouken@7191
  1033
 *
slouken@3407
  1034
 *  \sa SDL_GL_CreateContext()
slouken@0
  1035
 */
slouken@1895
  1036
extern DECLSPEC void SDLCALL SDL_GL_DeleteContext(SDL_GLContext context);
slouken@0
  1037
gabomdq@7678
  1038
/* @} *//* OpenGL support functions */
slouken@3407
  1039
slouken@0
  1040
slouken@0
  1041
/* Ends C function definitions when using C++ */
slouken@0
  1042
#ifdef __cplusplus
slouken@0
  1043
}
slouken@0
  1044
#endif
slouken@0
  1045
#include "close_code.h"
slouken@0
  1046
slouken@0
  1047
#endif /* _SDL_video_h */
slouken@1895
  1048
slouken@1895
  1049
/* vi: set ts=4 sw=4 expandtab: */