include/SDL_video.h
author Ryan C. Gordon <icculus@icculus.org>
Tue, 15 Oct 2019 14:17:32 -0400
changeset 13128 ae02830ea4f3
parent 12503 806492103856
permissions -rw-r--r--
include: Removed a FIXME comment.

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