include/SDL_video.h
author Marc Di Luzio <mdiluzio@feralinteractive.com>
Fri, 06 Mar 2015 16:03:40 +0000
changeset 9412 8b1436ce1028
parent 8946 c9592936dffc
child 9447 728a4bf8e02f
permissions -rw-r--r--
Allow setting of GL_CONTEXT_RELEASE_BEHAVIOR when creating the GL context when GLX_ARB_context_flush_control is available.

This extension allows the user to specify whether a full flush is performed when making a context not current.
The only way to set this currently is at context creation, so this patch provides that functionality.
Defualt behaviour is set at FLUSH, as per the spec.

This patch does not contain the changes to WGL, appleGL or other platforms as I do not have access to GL 4.5 hardware on those platforms.

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