include/SDL_video.h
author Ryan C. Gordon <icculus@icculus.org>
Tue, 05 Jan 2016 01:30:40 -0500
changeset 10021 3beca914a2ad
parent 10019 36f7e8084508
child 10024 9a1189c7b891
permissions -rw-r--r--
Added special window type flags.

Specifically: always on top, skip taskbar, tooltip, utility, and popup menu.

This is currently only implemented for X11.

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