include/SDL_video.h
author Sam Lantinga <slouken@libsdl.org>
Sun, 11 Jun 2006 07:30:16 +0000
branchSDL-1.3
changeset 1675 d33dcfc3fde7
parent 1670 eef792d31de8
child 1676 e136f3ffdc1b
permissions -rw-r--r--
Overlay functions are being replaced by YUV textures.
If the driver doesn't support YUV textures, they can be emulated by backing
the texture with an RGB texture and using the software conversion routines.

Note that it doesn't make sense to lock a portion of a YV12 texture, since
you'd need to return three pixel pointers and pitch values instead of the
one that's available through the API. I'm guessing that's one of the reasons
DirectX 9 doesn't support this format at all.
slouken@0
     1
/*
slouken@0
     2
    SDL - Simple DirectMedia Layer
slouken@1312
     3
    Copyright (C) 1997-2006 Sam Lantinga
slouken@0
     4
slouken@0
     5
    This library is free software; you can redistribute it and/or
slouken@1312
     6
    modify it under the terms of the GNU Lesser General Public
slouken@0
     7
    License as published by the Free Software Foundation; either
slouken@1312
     8
    version 2.1 of the License, or (at your option) any later version.
slouken@0
     9
slouken@0
    10
    This library is distributed in the hope that it will be useful,
slouken@0
    11
    but WITHOUT ANY WARRANTY; without even the implied warranty of
slouken@0
    12
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
slouken@1312
    13
    Lesser General Public License for more details.
slouken@0
    14
slouken@1312
    15
    You should have received a copy of the GNU Lesser General Public
slouken@1312
    16
    License along with this library; if not, write to the Free Software
slouken@1312
    17
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
slouken@0
    18
slouken@0
    19
    Sam Lantinga
slouken@251
    20
    slouken@libsdl.org
slouken@0
    21
*/
slouken@0
    22
slouken@1662
    23
/**
slouken@1662
    24
 * \file SDL_video.h
slouken@1662
    25
 *
slouken@1662
    26
 * Header file for access to the SDL raw framebuffer window
slouken@1662
    27
 */
slouken@0
    28
slouken@0
    29
#ifndef _SDL_video_h
slouken@0
    30
#define _SDL_video_h
slouken@0
    31
slouken@1356
    32
#include "SDL_stdinc.h"
slouken@1358
    33
#include "SDL_error.h"
slouken@1662
    34
#include "SDL_pixels.h"
slouken@0
    35
#include "SDL_rwops.h"
slouken@0
    36
slouken@0
    37
#include "begin_code.h"
slouken@0
    38
/* Set up for C function definitions, even when using C++ */
slouken@0
    39
#ifdef __cplusplus
slouken@1662
    40
/* *INDENT-OFF* */
slouken@0
    41
extern "C" {
slouken@1662
    42
/* *INDENT-ON* */
slouken@0
    43
#endif
slouken@0
    44
slouken@0
    45
/* Transparency definitions: These define alpha as the opacity of a surface */
slouken@0
    46
#define SDL_ALPHA_OPAQUE 255
slouken@0
    47
#define SDL_ALPHA_TRANSPARENT 0
slouken@0
    48
slouken@1670
    49
/**
slouken@1670
    50
 * \struct SDL_Rect
slouken@1670
    51
 *
slouken@1670
    52
 * \brief A rectangle, with the origin at the upper left.
slouken@1670
    53
 */
slouken@1662
    54
typedef struct SDL_Rect
slouken@1662
    55
{
slouken@1662
    56
    Sint16 x, y;
slouken@1662
    57
    Uint16 w, h;
slouken@0
    58
} SDL_Rect;
slouken@0
    59
slouken@1662
    60
/**
slouken@1662
    61
 * \struct SDL_DisplayMode
slouken@1662
    62
 *
slouken@1662
    63
 * \brief  The structure that defines a display mode
slouken@1662
    64
 *
slouken@1662
    65
 * \sa SDL_GetNumDisplayModes()
slouken@1662
    66
 * \sa SDL_GetDisplayMode()
slouken@1662
    67
 * \sa SDL_GetDesktopDisplayMode()
slouken@1662
    68
 * \sa SDL_GetCurrentDisplayMode()
slouken@1662
    69
 * \sa SDL_GetClosestDisplayMode()
slouken@1662
    70
 * \sa SDL_SetDisplayMode()
slouken@1662
    71
 */
slouken@1662
    72
typedef struct
slouken@1662
    73
{
slouken@1662
    74
    Uint32 format;              /**< pixel format */
slouken@1662
    75
    int w;                      /**< width */
slouken@1662
    76
    int h;                      /**< height */
slouken@1662
    77
    int refresh_rate;           /**< refresh rate (or zero for unspecified) */
slouken@1662
    78
} SDL_DisplayMode;
slouken@1662
    79
slouken@1662
    80
/**
slouken@1662
    81
 * \typedef SDL_WindowID
slouken@1662
    82
 *
slouken@1662
    83
 * \brief The type used to identify a window
slouken@1662
    84
 *
slouken@1662
    85
 * \sa SDL_CreateWindow()
slouken@1662
    86
 * \sa SDL_CreateWindowFrom()
slouken@1662
    87
 * \sa SDL_DestroyWindow()
slouken@1662
    88
 * \sa SDL_GetWindowData()
slouken@1662
    89
 * \sa SDL_GetWindowFlags()
slouken@1662
    90
 * \sa SDL_GetWindowGrab()
slouken@1662
    91
 * \sa SDL_GetWindowPosition()
slouken@1662
    92
 * \sa SDL_GetWindowSize()
slouken@1662
    93
 * \sa SDL_GetWindowTitle()
slouken@1662
    94
 * \sa SDL_HideWindow()
slouken@1662
    95
 * \sa SDL_MaximizeWindow()
slouken@1662
    96
 * \sa SDL_MinimizeWindow()
slouken@1662
    97
 * \sa SDL_RaiseWindow()
slouken@1662
    98
 * \sa SDL_RestoreWindow()
slouken@1662
    99
 * \sa SDL_SetWindowData()
slouken@1662
   100
 * \sa SDL_SetWindowGrab()
slouken@1662
   101
 * \sa SDL_SetWindowIcon()
slouken@1662
   102
 * \sa SDL_SetWindowPosition()
slouken@1662
   103
 * \sa SDL_SetWindowSize()
slouken@1662
   104
 * \sa SDL_SetWindowTitle()
slouken@1662
   105
 * \sa SDL_ShowWindow()
slouken@1662
   106
 */
slouken@1662
   107
typedef Uint32 SDL_WindowID;
slouken@1662
   108
slouken@1662
   109
/**
slouken@1662
   110
 * \enum SDL_WindowFlags
slouken@1662
   111
 *
slouken@1662
   112
 * \brief The flags on a window
slouken@1670
   113
 *
slouken@1670
   114
 * \sa SDL_GetWindowFlags()
slouken@1662
   115
 */
slouken@1662
   116
typedef enum
slouken@1662
   117
{
slouken@1662
   118
    SDL_WINDOW_FULLSCREEN = 0x00000001,         /**< fullscreen window, implies borderless */
slouken@1662
   119
    SDL_WINDOW_BORDERLESS = 0x00000002,         /**< no window decoration */
slouken@1662
   120
    SDL_WINDOW_SHOWN = 0x00000004,              /**< window is visible */
slouken@1662
   121
    SDL_WINDOW_OPENGL = 0x00000008,             /**< window usable with OpenGL context */
slouken@1662
   122
    SDL_WINDOW_RESIZABLE = 0x00000010,          /**< window can be resized */
slouken@1662
   123
    SDL_WINDOW_MAXIMIZED = 0x00000020,          /**< maximized */
slouken@1662
   124
    SDL_WINDOW_MINIMIZED = 0x00000040,          /**< minimized */
slouken@1662
   125
    SDL_WINDOW_INPUT_GRABBED = 0x00000080,      /**< window has grabbed input focus */
slouken@1662
   126
    SDL_WINDOW_KEYBOARD_FOCUS = 0x00000100,     /**< window has keyboard focus */
slouken@1662
   127
    SDL_WINDOW_MOUSE_FOCUS = 0x00000200,        /**< window has mouse focus */
slouken@1662
   128
} SDL_WindowFlags;
slouken@1662
   129
slouken@1662
   130
/**
slouken@1662
   131
 * \enum SDL_WindowEventID
slouken@1662
   132
 *
slouken@1662
   133
 * \brief Event subtype for window events
slouken@1662
   134
 */
slouken@1662
   135
typedef enum
slouken@1662
   136
{
slouken@1662
   137
    SDL_WINDOWEVENT_NONE,               /**< Never used */
slouken@1662
   138
    SDL_WINDOWEVENT_SHOWN,              /**< Window has been shown */
slouken@1662
   139
    SDL_WINDOWEVENT_HIDDEN,             /**< Window has been hidden */
slouken@1662
   140
    SDL_WINDOWEVENT_MOVED,              /**< Window has been moved to data1,data2 */
slouken@1662
   141
    SDL_WINDOWEVENT_RESIZED,            /**< Window size changed to data1xdata2 */
slouken@1662
   142
    SDL_WINDOWEVENT_MINIMIZED,          /**< Window has been minimized */
slouken@1662
   143
    SDL_WINDOWEVENT_MAXIMIZED,          /**< Window has been maximized */
slouken@1662
   144
    SDL_WINDOWEVENT_RESTORED,           /**< Window has been restored to normal size and position */
slouken@1662
   145
    SDL_WINDOWEVENT_ENTER,              /**< The window has gained mouse focus */
slouken@1662
   146
    SDL_WINDOWEVENT_LEAVE,              /**< The window has lost mouse focus */
slouken@1662
   147
    SDL_WINDOWEVENT_FOCUS_GAINED,       /**< The window has gained keyboard focus */
slouken@1662
   148
    SDL_WINDOWEVENT_FOCUS_LOST,         /**< The window has lost keyboard focus */
slouken@1662
   149
} SDL_WindowEventID;
slouken@1662
   150
slouken@1662
   151
/**
slouken@1670
   152
 * \enum SDL_RendererFlags
slouken@1670
   153
 *
slouken@1670
   154
 * \brief Flags used when initializing a render manager.
slouken@1670
   155
 */
slouken@1670
   156
typedef enum
slouken@1670
   157
{
slouken@1670
   158
    SDL_Renderer_PresentDiscard = 0x00000001,   /**< Present leaves the contents of the backbuffer undefined */
slouken@1670
   159
    SDL_Renderer_PresentCopy = 0x00000002,      /**< Present uses a copy from back buffer to the front buffer */
slouken@1670
   160
    SDL_Renderer_PresentFlip2 = 0x00000004,     /**< Present uses a flip, swapping back buffer and front buffer */
slouken@1670
   161
    SDL_Renderer_PresentFlip3 = 0x00000008,     /**< Present uses a flip, rotating between two back buffers and a front buffer */
slouken@1670
   162
    SDL_Renderer_PresentVSync = 0x00000010,     /**< Present is synchronized with the refresh rate */
slouken@1670
   163
    SDL_Renderer_RenderTarget = 0x00000020,     /**< The renderer can create texture render targets */
slouken@1670
   164
    SDL_Renderer_Accelerated = 0x00000040,      /**< The renderer uses hardware acceleration */
slouken@1670
   165
    SDL_Renderer_Minimal = 0x00000080,          /**< The renderer only supports the read/write pixel and present functions */
slouken@1670
   166
} SDL_RendererFlags;
slouken@1670
   167
slouken@1670
   168
/**
slouken@1670
   169
 * \struct SDL_RendererInfo
slouken@1670
   170
 *
slouken@1670
   171
 * \brief Information on the capabilities of a render manager.
slouken@1670
   172
 */
slouken@1670
   173
typedef struct SDL_RendererInfo
slouken@1670
   174
{
slouken@1670
   175
    const char *name;           /**< The name of the renderer */
slouken@1670
   176
    Uint32 flags;               /**< Supported SDL_RendererFlags */
slouken@1670
   177
    Uint32 blend_modes;         /**< A mask of supported blend modes */
slouken@1670
   178
    Uint32 scale_modes;         /**< A mask of supported scale modes */
slouken@1670
   179
    Uint32 num_texture_formats; /**< The number of available texture formats */
slouken@1670
   180
    Uint32 texture_formats[32]; /**< The available texture formats */
slouken@1670
   181
    int max_texture_width;      /**< The maximimum texture width */
slouken@1670
   182
    int max_texture_height;     /**< The maximimum texture height */
slouken@1670
   183
} SDL_RendererInfo;
slouken@1670
   184
slouken@1670
   185
/**
slouken@1670
   186
 * \enum SDL_TextureAccess
slouken@1670
   187
 *
slouken@1670
   188
 * \brief The access pattern allowed for a texture
slouken@1670
   189
 */
slouken@1670
   190
typedef enum
slouken@1670
   191
{
slouken@1670
   192
    SDL_TextureAccess_Render,   /**< Unlockable video memory, rendering allowed */
slouken@1670
   193
    SDL_TextureAccess_Remote,   /**< Unlockable video memory */
slouken@1670
   194
    SDL_TextureAccess_Local,    /**< Lockable system memory */
slouken@1670
   195
} SDL_TextureAccess;
slouken@1670
   196
slouken@1670
   197
/**
slouken@1670
   198
 * \enum SDL_TextureBlendMode
slouken@1670
   199
 *
slouken@1670
   200
 * \brief The blend mode used in SDL_RenderCopy()
slouken@1670
   201
 */
slouken@1670
   202
typedef enum
slouken@1670
   203
{
slouken@1670
   204
    SDL_TextureBlendMode_None,  /**< No blending */
slouken@1670
   205
    SDL_TextureBlendMode_Mask,  /**< dst = A ? src : dst (alpha is mask) */
slouken@1670
   206
    SDL_TextureBlendMode_Blend, /**< dst = (src * A) + (dst * (1-A)) */
slouken@1670
   207
    SDL_TextureBlendMode_Add,   /**< dst = (src * A) + dst */
slouken@1670
   208
    SDL_TextureBlendMode_Mod,   /**< dst = src * dst */
slouken@1670
   209
} SDL_TextureBlendMode;
slouken@1670
   210
slouken@1670
   211
/**
slouken@1670
   212
 * \enum SDL_TextureScaleMode
slouken@1670
   213
 *
slouken@1670
   214
 * \brief The scale mode used in SDL_RenderCopy()
slouken@1670
   215
 */
slouken@1670
   216
typedef enum
slouken@1670
   217
{
slouken@1670
   218
    SDL_TextureScaleMode_None,  /**< No scaling, rectangles must match dimensions */
slouken@1670
   219
    SDL_TextureScaleMode_Fast,  /**< Point sampling or equivalent algorithm */
slouken@1670
   220
    SDL_TextureScaleMode_Slow,  /**< Linear filtering or equivalent algorithm */
slouken@1670
   221
    SDL_TextureScaleMode_Best,  /**< Bicubic filtering or equivalent algorithm */
slouken@1670
   222
} SDL_TextureScaleMode;
slouken@1670
   223
slouken@1670
   224
/**
slouken@1670
   225
 * \typedef SDL_TextureID
slouken@1670
   226
 *
slouken@1670
   227
 * \brief An efficient driver-specific representation of pixel data
slouken@1670
   228
 */
slouken@1670
   229
typedef Uint32 SDL_TextureID;
slouken@1670
   230
slouken@1670
   231
slouken@1670
   232
/* These are the currently supported flags for the SDL_surface */
slouken@1670
   233
/* Used internally (read-only) */
slouken@1670
   234
#define SDL_HWSURFACE       0x00000001  /* Surface represents a texture */
slouken@1670
   235
#define SDL_PREALLOC        0x00000002  /* Surface uses preallocated memory */
slouken@1670
   236
#define SDL_SRCALPHA        0x00000004  /* Blit uses source alpha blending */
slouken@1670
   237
#define SDL_SRCCOLORKEY     0x00000008  /* Blit uses a source color key */
slouken@1670
   238
#define SDL_RLEACCELOK      0x00000010  /* Private flag */
slouken@1670
   239
#define SDL_RLEACCEL        0x00000020  /* Surface is RLE encoded */
slouken@1670
   240
slouken@1670
   241
/* Evaluates to true if the surface needs to be locked before access */
slouken@1670
   242
#define SDL_MUSTLOCK(S)	(((S)->flags & (SDL_HWSURFACE|SDL_RLEACCEL)) != 0)
slouken@1670
   243
slouken@1670
   244
/* This structure should be treated as read-only, except for 'pixels',
slouken@1670
   245
   which, if not NULL, contains the raw pixel data for the surface.
slouken@1670
   246
*/
slouken@1670
   247
typedef struct SDL_Surface
slouken@1670
   248
{
slouken@1670
   249
    Uint32 flags;               /* Read-only */
slouken@1670
   250
    SDL_PixelFormat *format;    /* Read-only */
slouken@1670
   251
    int w, h;                   /* Read-only */
slouken@1670
   252
    int pitch;                  /* Read-only */
slouken@1670
   253
    void *pixels;               /* Read-write */
slouken@1670
   254
slouken@1670
   255
    /* information needed for surfaces requiring locks */
slouken@1670
   256
    int locked;
slouken@1670
   257
    void *lock_data;
slouken@1670
   258
slouken@1670
   259
    /* clipping information */
slouken@1670
   260
    SDL_Rect clip_rect;         /* Read-only */
slouken@1670
   261
slouken@1670
   262
    /* info for fast blit mapping to other surfaces */
slouken@1670
   263
    struct SDL_BlitMap *map;    /* Private */
slouken@1670
   264
slouken@1670
   265
    /* format version, bumped at every change to invalidate blit maps */
slouken@1670
   266
    unsigned int format_version;        /* Private */
slouken@1670
   267
slouken@1670
   268
    /* Reference count -- used when freeing surface */
slouken@1670
   269
    int refcount;               /* Read-mostly */
slouken@1670
   270
} SDL_Surface;
slouken@1670
   271
slouken@1670
   272
/* typedef for private surface blitting functions */
slouken@1670
   273
typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
slouken@1670
   274
                         struct SDL_Surface * dst, SDL_Rect * dstrect);
slouken@1670
   275
slouken@1670
   276
slouken@1670
   277
/**
slouken@1662
   278
 * \enum SDL_GLattr
slouken@1662
   279
 *
slouken@1662
   280
 * \brief OpenGL configuration attributes
slouken@1662
   281
 */
slouken@1662
   282
typedef enum
slouken@1662
   283
{
slouken@0
   284
    SDL_GL_RED_SIZE,
slouken@0
   285
    SDL_GL_GREEN_SIZE,
slouken@0
   286
    SDL_GL_BLUE_SIZE,
slouken@0
   287
    SDL_GL_ALPHA_SIZE,
slouken@0
   288
    SDL_GL_BUFFER_SIZE,
slouken@0
   289
    SDL_GL_DOUBLEBUFFER,
slouken@0
   290
    SDL_GL_DEPTH_SIZE,
slouken@0
   291
    SDL_GL_STENCIL_SIZE,
slouken@0
   292
    SDL_GL_ACCUM_RED_SIZE,
slouken@0
   293
    SDL_GL_ACCUM_GREEN_SIZE,
slouken@0
   294
    SDL_GL_ACCUM_BLUE_SIZE,
slouken@450
   295
    SDL_GL_ACCUM_ALPHA_SIZE,
slouken@655
   296
    SDL_GL_STEREO,
slouken@656
   297
    SDL_GL_MULTISAMPLEBUFFERS,
slouken@1656
   298
    SDL_GL_MULTISAMPLESAMPLES,
slouken@1656
   299
    SDL_GL_ACCELERATED_VISUAL,
slouken@1656
   300
    SDL_GL_SWAP_CONTROL
slouken@0
   301
} SDL_GLattr;
slouken@0
   302
slouken@0
   303
slouken@0
   304
/* Function prototypes */
slouken@0
   305
slouken@1662
   306
/**
slouken@1662
   307
 * \fn int SDL_GetNumVideoDrivers(void)
slouken@1662
   308
 *
slouken@1662
   309
 * \brief Get the number of video drivers compiled into SDL
slouken@1662
   310
 *
slouken@1662
   311
 * \sa SDL_GetVideoDriver()
slouken@1662
   312
 */
slouken@1668
   313
extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
slouken@1662
   314
slouken@1662
   315
/**
slouken@1662
   316
 * \fn const char *SDL_GetVideoDriver(int index)
slouken@1662
   317
 *
slouken@1662
   318
 * \brief Get the name of a built in video driver.
slouken@1662
   319
 *
slouken@1662
   320
 * \note The video drivers are presented in the order in which they are
slouken@1662
   321
 * normally checked during initialization.
slouken@1662
   322
 *
slouken@1662
   323
 * \sa SDL_GetNumVideoDrivers()
slouken@1660
   324
 */
slouken@1668
   325
extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
slouken@1660
   326
slouken@1662
   327
/**
slouken@1662
   328
 * \fn int SDL_VideoInit(const char *driver_name, Uint32 flags)
slouken@1662
   329
 *
slouken@1662
   330
 * \brief Initialize the video subsystem, optionally specifying a video driver.
slouken@1662
   331
 *
slouken@1662
   332
 * \param driver_name Initialize a specific driver by name, or NULL for the default video driver.
slouken@1662
   333
 * \param flags FIXME: Still needed?
slouken@1662
   334
 *
slouken@1662
   335
 * \return 0 on success, -1 on error
slouken@1662
   336
 *
slouken@1662
   337
 * This function initializes the video subsystem; setting up a connection
slouken@1662
   338
 * to the window manager, etc, and determines the available display modes
slouken@1662
   339
 * and pixel formats, but does not initialize a window or graphics mode.
slouken@1662
   340
 *
slouken@1662
   341
 * \sa SDL_VideoQuit()
slouken@1662
   342
 */
slouken@1668
   343
extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name,
slouken@1668
   344
                                          Uint32 flags);
slouken@1662
   345
slouken@1662
   346
/**
slouken@1662
   347
 * \fn void SDL_VideoQuit(void)
slouken@1662
   348
 *
slouken@1662
   349
 * \brief Shuts down the video subsystem.
slouken@1662
   350
 *
slouken@1662
   351
 * This function closes all windows, and restores the original video mode.
slouken@0
   352
 *
slouken@1662
   353
 * \sa SDL_VideoInit()
slouken@1662
   354
 */
slouken@1668
   355
extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
slouken@1662
   356
slouken@1662
   357
/**
slouken@1662
   358
 * \fn const char *SDL_GetCurrentVideoDriver(void)
slouken@1662
   359
 *
slouken@1662
   360
 * \brief Returns the name of the currently initialized video driver.
slouken@1662
   361
 *
slouken@1662
   362
 * \return The name of the current video driver or NULL if no driver
slouken@1662
   363
 *         has been initialized
slouken@1662
   364
 *
slouken@1662
   365
 * \sa SDL_GetNumVideoDrivers()
slouken@1662
   366
 * \sa SDL_GetVideoDriver()
slouken@1662
   367
 */
slouken@1668
   368
extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);
slouken@1662
   369
slouken@1662
   370
/**
slouken@1662
   371
 * \fn int SDL_GetNumVideoDisplays(void)
slouken@1662
   372
 *
slouken@1662
   373
 * \brief Returns the number of available video displays.
slouken@1662
   374
 *
slouken@1662
   375
 * \sa SDL_SelectVideoDisplay()
slouken@0
   376
 */
slouken@1668
   377
extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void);
slouken@0
   378
slouken@1662
   379
/**
slouken@1662
   380
 * \fn int SDL_SelectVideoDisplay(int index)
slouken@1662
   381
 *
slouken@1662
   382
 * \brief Set the index of the currently selected display.
slouken@1662
   383
 *
slouken@1670
   384
 * \return The index of the currently selected display.
slouken@1670
   385
 *
slouken@1662
   386
 * \note You can query the currently selected display by passing an index of -1.
slouken@1662
   387
 *
slouken@1662
   388
 * \sa SDL_GetNumVideoDisplays()
slouken@0
   389
 */
slouken@1668
   390
extern DECLSPEC int SDLCALL SDL_SelectVideoDisplay(int index);
slouken@0
   391
slouken@1662
   392
/**
slouken@1662
   393
 * \fn int SDL_GetNumDisplayModes(void)
slouken@1662
   394
 *
slouken@1662
   395
 * \brief Returns the number of available display modes for the current display.
slouken@1662
   396
 *
slouken@1662
   397
 * \sa SDL_GetDisplayMode()
slouken@0
   398
 */
slouken@1668
   399
extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(void);
slouken@0
   400
slouken@1662
   401
/**
slouken@1662
   402
 * \fn const SDL_DisplayMode *SDL_GetDisplayMode(int index)
slouken@1662
   403
 *
slouken@1662
   404
 * \brief Retrieve information about a specific display mode.
slouken@1662
   405
 *
slouken@1662
   406
 * \note The display modes are sorted in this priority:
slouken@1662
   407
 *       \li bits per pixel -> more colors to fewer colors
slouken@1662
   408
 *       \li width -> largest to smallest
slouken@1662
   409
 *       \li height -> largest to smallest
slouken@1662
   410
 *       \li refresh rate -> highest to lowest
slouken@1662
   411
 *
slouken@1662
   412
 * \sa SDL_GetNumDisplayModes()
slouken@0
   413
 */
slouken@1668
   414
extern DECLSPEC const SDL_DisplayMode *SDLCALL SDL_GetDisplayMode(int index);
slouken@1662
   415
slouken@1662
   416
/**
slouken@1662
   417
 * \fn const SDL_DisplayMode *SDL_GetDesktopDisplayMode(void)
slouken@1662
   418
 *
slouken@1662
   419
 * \brief Retrieve information about the desktop display mode for the current display.
slouken@1662
   420
 */
slouken@1662
   421
extern DECLSPEC const SDL_DisplayMode *SDLCALL
slouken@1668
   422
SDL_GetDesktopDisplayMode(void);
slouken@1662
   423
slouken@1662
   424
/**
slouken@1662
   425
 * \fn const SDL_DisplayMode *SDL_GetCurrentDisplayMode(void)
slouken@1662
   426
 *
slouken@1662
   427
 * \brief Retrieve information about the current display mode.
slouken@1662
   428
 */
slouken@1662
   429
extern DECLSPEC const SDL_DisplayMode *SDLCALL
slouken@1668
   430
SDL_GetCurrentDisplayMode(void);
slouken@0
   431
slouken@1662
   432
/**
slouken@1662
   433
 * \fn SDL_DisplayMode *SDL_GetClosestDisplayMode(const SDL_DisplayMode *mode, SDL_DisplayMode *closest)
slouken@1662
   434
 *
slouken@1662
   435
 * \brief Get the closest match to the requested display mode.
slouken@1662
   436
 *
slouken@1662
   437
 * \param mode The desired display mode
slouken@1662
   438
 * \param closest A pointer to a display mode to be filled in with the closest match of the available display modes.
slouken@1662
   439
 *
slouken@1662
   440
 * \return The passed in value 'closest', or NULL if no matching video mode was available.
slouken@1662
   441
 *
slouken@1662
   442
 * The available display modes are scanned, and 'closest' is filled in with the closest mode matching the requested mode and returned.  The mode format and refresh_rate default to the desktop mode if they are 0.  The modes are scanned with size being first priority, format being second priority, and finally checking the refresh_rate.  If all the available modes are too small, then NULL is returned.
slouken@1662
   443
 *
slouken@1662
   444
 * \sa SDL_GetNumDisplayModes()
slouken@1662
   445
 * \sa SDL_GetDisplayMode()
slouken@1662
   446
 */
slouken@1668
   447
extern DECLSPEC SDL_DisplayMode *SDLCALL SDL_GetClosestDisplayMode(const
slouken@1668
   448
                                                                   SDL_DisplayMode
slouken@1668
   449
                                                                   * mode,
slouken@1668
   450
                                                                   SDL_DisplayMode
slouken@1668
   451
                                                                   * closest);
slouken@1662
   452
slouken@1662
   453
/**
slouken@1662
   454
 * \fn int SDL_SetDisplayMode(const SDL_DisplayMode *mode)
slouken@1662
   455
 *
slouken@1662
   456
 * \brief Set up the closest available mode on the current display.
slouken@1662
   457
 *
slouken@1662
   458
 * \param mode The desired display mode
slouken@0
   459
 *
slouken@1662
   460
 * \return 0 on success, or -1 if setting the display mode failed.
slouken@0
   461
 */
slouken@1668
   462
extern DECLSPEC int SDLCALL SDL_SetDisplayMode(const SDL_DisplayMode * mode);
slouken@0
   463
slouken@1662
   464
/**
slouken@1670
   465
 * \fn int SDL_SetDisplayColormap(SDL_Color *colors, int firstcolor, int ncolors)
slouken@1670
   466
 *
slouken@1670
   467
 * \brief Set the colormap for indexed display modes.
slouken@1670
   468
 *
slouken@1670
   469
 * \return 0 on success, or -1 if not all the colors could be set.
slouken@1670
   470
 */
slouken@1670
   471
extern DECLSPEC int SDLCALL SDL_SetDisplayColors(SDL_Color * colors,
slouken@1670
   472
                                                 int firstcolor, int ncolors);
slouken@1670
   473
slouken@1670
   474
/**
slouken@1662
   475
 * \fn SDL_WindowID SDL_CreateWindow(const char *title, int x, int y, int w, int h, Uint32 flags)
slouken@1662
   476
 *
slouken@1662
   477
 * \brief Create a window with the specified position, dimensions, and flags.
slouken@1662
   478
 *
slouken@1662
   479
 * \param title The title of the window
slouken@1662
   480
 * \param x The x position of the window
slouken@1662
   481
 * \param y The y position of the window
slouken@1662
   482
 * \param w The width of the window
slouken@1662
   483
 * \param h The height of the window
slouken@1662
   484
 * \param flags The flags for the window
slouken@1662
   485
 *
slouken@1662
   486
 * \return The id of the window created, or zero if window creation failed.
slouken@1662
   487
 *
slouken@1662
   488
 * \note Setting the position to -1, -1, indicates any position is fine.
slouken@1662
   489
 *
slouken@1662
   490
 * \sa SDL_DestroyWindow()
slouken@1662
   491
 */
slouken@1668
   492
extern DECLSPEC SDL_WindowID SDLCALL SDL_CreateWindow(const char *title,
slouken@1668
   493
                                                      int x, int y, int w,
slouken@1668
   494
                                                      int h, Uint32 flags);
slouken@1662
   495
slouken@1662
   496
/**
slouken@1662
   497
 * \fn SDL_WindowID SDL_CreateWindowFrom(void *data)
slouken@1662
   498
 *
slouken@1662
   499
 * \brief Create an SDL window struct from an existing native window.
slouken@1662
   500
 *
slouken@1662
   501
 * \param data A pointer to driver-dependent window creation data
slouken@1662
   502
 *
slouken@1662
   503
 * \return The id of the window created, or zero if window creation failed.
slouken@0
   504
 *
slouken@1662
   505
 * \warning This function is NOT SUPPORTED, use at your own risk!
slouken@1662
   506
 *
slouken@1662
   507
 * \sa SDL_DestroyWindow()
slouken@1662
   508
 */
slouken@1668
   509
extern DECLSPEC SDL_WindowID SDLCALL SDL_CreateWindowFrom(void *data);
slouken@1662
   510
slouken@1662
   511
/**
slouken@1662
   512
 * \fn Uint32 SDL_GetWindowFlags(SDL_WindowID windowID)
slouken@1662
   513
 *
slouken@1662
   514
 * \brief Get the window flags.
slouken@0
   515
 */
slouken@1668
   516
extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_WindowID windowID);
slouken@1662
   517
slouken@1662
   518
/**
slouken@1662
   519
 * \fn void SDL_SetWindowTitle(SDL_WindowID windowID, const char *title)
slouken@1662
   520
 *
slouken@1662
   521
 * \brief Set the title of the window, in UTF-8 format.
slouken@1662
   522
 *
slouken@1662
   523
 * \sa SDL_GetWindowTitle()
slouken@1662
   524
 */
slouken@1668
   525
extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_WindowID windowID,
slouken@1668
   526
                                                const char *title);
slouken@0
   527
slouken@1662
   528
/**
slouken@1662
   529
 * \fn const char *SDL_GetWindowTitle(SDL_WindowID windowID)
slouken@1662
   530
 *
slouken@1662
   531
 * \brief Get the title of the window, in UTF-8 format.
slouken@0
   532
 *
slouken@1662
   533
 * \sa SDL_SetWindowTitle()
slouken@1662
   534
 */
slouken@1668
   535
extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_WindowID windowID);
slouken@1662
   536
slouken@1662
   537
/**
slouken@1662
   538
 * \fn void SDL_SetWindowIcon(SDL_Surface *icon)
slouken@0
   539
 *
slouken@1662
   540
 * \brief Set the icon of the window.
slouken@1662
   541
 *
slouken@1662
   542
 * \param icon The icon for the window
slouken@1662
   543
 *
slouken@1662
   544
 * FIXME: The icon needs to be set before the window is first shown.  Should some icon representation be part of the window creation data?
slouken@1662
   545
 */
slouken@1668
   546
extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Surface * icon);
slouken@1662
   547
slouken@1662
   548
/**
slouken@1662
   549
 * \fn void SDL_SetWindowData(SDL_WindowID windowID, void *userdata)
slouken@1662
   550
 *
slouken@1662
   551
 * \brief Associate an arbitrary pointer with the window.
slouken@0
   552
 *
slouken@1662
   553
 * \sa SDL_GetWindowData()
slouken@1662
   554
 */
slouken@1668
   555
extern DECLSPEC void SDLCALL SDL_SetWindowData(SDL_WindowID windowID,
slouken@1668
   556
                                               void *userdata);
slouken@1662
   557
slouken@1662
   558
/**
slouken@1662
   559
 * \fn void *SDL_GetWindowData(SDL_WindowID windowID)
slouken@0
   560
 *
slouken@1662
   561
 * \brief Retrieve the data pointer associated with the window.
slouken@1662
   562
 *
slouken@1662
   563
 * \sa SDL_SetWindowData()
slouken@1662
   564
 */
slouken@1668
   565
extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_WindowID windowID);
slouken@1662
   566
slouken@1662
   567
/**
slouken@1662
   568
 * \fn void SDL_SetWindowPosition(SDL_WindowID windowID, int x, int y)
slouken@1662
   569
 *
slouken@1662
   570
 * \brief Set the position of the window.
slouken@0
   571
 *
slouken@1662
   572
 * \sa SDL_GetWindowPosition()
slouken@1662
   573
 */
slouken@1668
   574
extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_WindowID windowID,
slouken@1668
   575
                                                   int x, int y);
slouken@1662
   576
slouken@1662
   577
/**
slouken@1662
   578
 * \fn void SDL_GetWindowPosition(SDL_WindowID windowID, int *x, int *y)
slouken@1662
   579
 *
slouken@1662
   580
 * \brief Get the position of the window.
slouken@1662
   581
 *
slouken@1662
   582
 * \sa SDL_SetWindowPosition()
slouken@1662
   583
 */
slouken@1668
   584
extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_WindowID windowID,
slouken@1668
   585
                                                   int *x, int *y);
slouken@1662
   586
slouken@1662
   587
/**
slouken@1662
   588
 * \fn void SDL_SetWindowSize(SDL_WindowID windowID, int w, int w)
slouken@1662
   589
 *
slouken@1662
   590
 * \brief Set the size of the window's client area.
slouken@1662
   591
 *
slouken@1662
   592
 * \note You can't change the size of a fullscreen window, it automatically
slouken@1662
   593
 * matches the size of the display mode.
slouken@1662
   594
 *
slouken@1662
   595
 * \sa SDL_GetWindowSize()
slouken@1662
   596
 */
slouken@1668
   597
extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_WindowID windowID, int w,
slouken@1668
   598
                                               int h);
slouken@1662
   599
slouken@1662
   600
/**
slouken@1662
   601
 * \fn void SDL_GetWindowSize(SDL_WindowID windowID, int *w, int *w)
slouken@0
   602
 *
slouken@1662
   603
 * \brief Get the size of the window's client area.
slouken@1662
   604
 *
slouken@1662
   605
 * \sa SDL_SetWindowSize()
slouken@1662
   606
 */
slouken@1668
   607
extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_WindowID windowID, int *w,
slouken@1668
   608
                                               int *h);
slouken@1662
   609
slouken@1662
   610
/**
slouken@1662
   611
 * \fn void SDL_ShowWindow(SDL_WindowID windowID)
slouken@1662
   612
 *
slouken@1662
   613
 * \brief Show the window
slouken@1662
   614
 *
slouken@1662
   615
 * \sa SDL_HideWindow()
slouken@1662
   616
 */
slouken@1668
   617
extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_WindowID windowID);
slouken@1662
   618
slouken@1662
   619
/**
slouken@1662
   620
 * \fn void SDL_HideWindow(SDL_WindowID windowID)
slouken@1662
   621
 *
slouken@1662
   622
 * \brief Hide the window
slouken@0
   623
 *
slouken@1662
   624
 * \sa SDL_ShowWindow()
slouken@1662
   625
 */
slouken@1668
   626
extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_WindowID windowID);
slouken@1662
   627
slouken@1662
   628
/**
slouken@1662
   629
 * \fn void SDL_RaiseWindow(SDL_WindowID windowID)
slouken@1662
   630
 *
slouken@1662
   631
 * \brief Raise the window so it's above other windows.
slouken@1662
   632
 */
slouken@1668
   633
extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_WindowID windowID);
slouken@1662
   634
slouken@1662
   635
/**
slouken@1662
   636
 * \fn void SDL_MaximizeWindow(SDL_WindowID windowID)
slouken@1662
   637
 *
slouken@1662
   638
 * \brief Make the window as large as possible.
slouken@1662
   639
 *
slouken@1662
   640
 * \sa SDL_RestoreWindow()
slouken@1662
   641
 */
slouken@1668
   642
extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_WindowID windowID);
slouken@1662
   643
slouken@1662
   644
/**
slouken@1662
   645
 * \fn void SDL_MinimizeWindow(SDL_WindowID windowID)
slouken@1662
   646
 *
slouken@1662
   647
 * \brief Minimize the window to an iconic representation.
slouken@0
   648
 *
slouken@1662
   649
 * \sa SDL_RestoreWindow()
slouken@1662
   650
 */
slouken@1668
   651
extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_WindowID windowID);
slouken@1662
   652
slouken@1662
   653
/**
slouken@1662
   654
 * \fn void SDL_RestoreWindow(SDL_WindowID windowID)
slouken@1662
   655
 *
slouken@1662
   656
 * \brief Restore the size and position of a minimized or maximized window.
slouken@0
   657
 *
slouken@1662
   658
 * \sa SDL_MaximizeWindow()
slouken@1662
   659
 * \sa SDL_MinimizeWindow()
slouken@1662
   660
 */
slouken@1668
   661
extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_WindowID windowID);
slouken@1662
   662
slouken@1662
   663
/**
slouken@1662
   664
 * \fn void SDL_SetWindowGrab(SDL_WindowID windowID, int mode)
slouken@1662
   665
 *
slouken@1662
   666
 * \brief Set the window's input grab mode.
slouken@1662
   667
 *
slouken@1662
   668
 * \param mode This is 1 to grab input, and 0 to release input.
slouken@0
   669
 *
slouken@1662
   670
 * \sa SDL_GrabMode
slouken@1662
   671
 * \sa SDL_GetWindowGrab()
slouken@1662
   672
 */
slouken@1668
   673
extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_WindowID windowID,
slouken@1668
   674
                                               int mode);
slouken@1662
   675
slouken@1662
   676
/**
slouken@1662
   677
 * \fn int SDL_GetWindowGrab(SDL_WindowID windowID)
slouken@1662
   678
 *
slouken@1662
   679
 * \brief Get the window's input grab mode.
slouken@1662
   680
 *
slouken@1662
   681
 * \return This returns 1 if input is grabbed, and 0 otherwise.
slouken@0
   682
 *
slouken@1662
   683
 * \sa SDL_GrabMode
slouken@1662
   684
 * \sa SDL_SetWindowGrab()
slouken@1662
   685
 */
slouken@1668
   686
extern DECLSPEC int SDLCALL SDL_GetWindowGrab(SDL_WindowID windowID);
slouken@1662
   687
slouken@1662
   688
/**
slouken@1662
   689
 * \fn void SDL_DestroyWindow(SDL_WindowID windowID)
slouken@1662
   690
 *
slouken@1662
   691
 * \brief Destroy a window.
slouken@0
   692
 */
slouken@1668
   693
extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_WindowID windowID);
slouken@1662
   694
slouken@1662
   695
/**
slouken@1670
   696
 * \fn int SDL_GetNumRenderers(void)
slouken@1670
   697
 *
slouken@1670
   698
 * \brief Get the number of render managers on the current display.
slouken@1670
   699
 *
slouken@1670
   700
 * A render manager is a set of code that handles rendering and texture
slouken@1670
   701
 * management on a particular display.  Normally there is only one, but
slouken@1670
   702
 * some drivers may have several available with different capabilities.
slouken@1670
   703
 *
slouken@1670
   704
 * \sa SDL_GetRendererInfo()
slouken@1670
   705
 * \sa SDL_CreateRenderer()
slouken@1670
   706
 */
slouken@1670
   707
extern DECLSPEC int SDLCALL SDL_GetNumRenderers(void);
slouken@1670
   708
slouken@1670
   709
/**
slouken@1670
   710
 * \fn SDL_RendererInfo *SDL_GetRendererInfo(int index)
slouken@1670
   711
 *
slouken@1670
   712
 * \brief Get information about a specific render manager on the current
slouken@1670
   713
 *        display.
slouken@1670
   714
 *
slouken@1670
   715
 * \sa SDL_CreateRenderer()
slouken@1670
   716
 */
slouken@1670
   717
extern DECLSPEC int SDLCALL SDL_GetRendererInfo(int index,
slouken@1670
   718
                                                SDL_RendererInfo * info);
slouken@1670
   719
slouken@1670
   720
/**
slouken@1670
   721
 * \fn int SDL_CreateRenderer(SDL_WindowID window, int index, Uint32 flags)
slouken@1670
   722
 *
slouken@1670
   723
 * \brief Create and make active a 2D rendering context for a window.
slouken@1670
   724
 *
slouken@1670
   725
 * \param windowID The window used for rendering.
slouken@1670
   726
 * \param index The index of the render manager to initialize, or -1 to initialize the first one supporting the requested flags.
slouken@1670
   727
 * \param flags SDL_RendererFlags
slouken@1662
   728
 *
slouken@1670
   729
 * \return 0 on success, -1 if the flags were not supported, or -2 if
slouken@1670
   730
 *         there isn't enough memory to support the requested flags
slouken@1670
   731
 *
slouken@1670
   732
 * \sa SDL_SelectRenderer()
slouken@1670
   733
 * \sa SDL_DestroyRenderer()
slouken@1670
   734
 */
slouken@1670
   735
extern DECLSPEC int SDLCALL SDL_CreateRenderer(SDL_WindowID windowID,
slouken@1670
   736
                                               int index, Uint32 flags);
slouken@1670
   737
slouken@1670
   738
/**
slouken@1670
   739
 * \fn int SDL_SelectRenderer(SDL_WindowID windowID)
slouken@1670
   740
 *
slouken@1670
   741
 * \brief Select the rendering context for a particular window.
slouken@1670
   742
 *
slouken@1670
   743
 * \return 0 on success, -1 if the selected window doesn't have a
slouken@1670
   744
 *         rendering context.
slouken@1670
   745
 */
slouken@1670
   746
extern DECLSPEC int SDLCALL SDL_SelectRenderer(SDL_WindowID windowID);
slouken@1670
   747
slouken@1670
   748
/**
slouken@1670
   749
 * \fn SDL_TextureID SDL_CreateTexture(Uint32 format, int access, int w, int h)
slouken@1670
   750
 *
slouken@1670
   751
 * \brief Create a texture
slouken@1670
   752
 *
slouken@1670
   753
 * \param format The format of the texture
slouken@1670
   754
 * \param access One of the enumerated values in SDL_TextureAccess
slouken@1670
   755
 * \param w The width of the texture in pixels
slouken@1670
   756
 * \param h The height of the texture in pixels
slouken@1670
   757
 *
slouken@1670
   758
 * \return The created texture is returned, or 0 if no render manager was active,  the format was unsupported, or the width or height were out of range.
slouken@1670
   759
 *
slouken@1670
   760
 * \sa SDL_QueryTexture()
slouken@1670
   761
 * \sa SDL_DestroyTexture()
slouken@1662
   762
 */
slouken@1670
   763
extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTexture(Uint32 format,
slouken@1670
   764
                                                        int access, int w,
slouken@1670
   765
                                                        int h);
slouken@1670
   766
slouken@1670
   767
/**
slouken@1670
   768
 * \fn SDL_TextureID SDL_CreateTextureFromSurface(Uint32 format, int access, SDL_Surface *surface)
slouken@1670
   769
 *
slouken@1670
   770
 * \brief Create a texture from an existing surface
slouken@1670
   771
 *
slouken@1670
   772
 * \param format The format of the texture, or 0 to pick an appropriate format
slouken@1670
   773
 * \param access One of the enumerated values in SDL_TextureAccess
slouken@1670
   774
 * \param surface The surface containing pixel data used to fill the texture
slouken@1670
   775
 *
slouken@1670
   776
 * \return The created texture is returned, or 0 if no render manager was active,  the format was unsupported, or the surface width or height were out of range.
slouken@1670
   777
 *
slouken@1670
   778
 * \note The surface is not modified or freed by this function.
slouken@1670
   779
 *
slouken@1670
   780
 * \sa SDL_QueryTexture()
slouken@1670
   781
 * \sa SDL_DestroyTexture()
slouken@1670
   782
 */
slouken@1670
   783
extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTextureFromSurface(Uint32
slouken@1670
   784
                                                                   format,
slouken@1670
   785
                                                                   int access,
slouken@1670
   786
                                                                   SDL_Surface
slouken@1670
   787
                                                                   * surface);
slouken@0
   788
slouken@1670
   789
/**
slouken@1670
   790
 * \fn int SDL_QueryTexture(SDL_TextureID textureID, Uint32 *format, int *access, int *w, int *h)
slouken@1670
   791
 *
slouken@1670
   792
 * \brief Query the attributes of a texture
slouken@1670
   793
 *
slouken@1670
   794
 * \param texture A texture to be queried
slouken@1670
   795
 * \param format A pointer filled in with the raw format of the texture.  The actual format may differ, but pixel transfers will use this format.
slouken@1670
   796
 * \param access A pointer filled in with the actual access to the texture.
slouken@1670
   797
 * \param w A pointer filled in with the width of the texture in pixels
slouken@1670
   798
 * \param h A pointer filled in with the height of the texture in pixels
slouken@1670
   799
 *
slouken@1670
   800
 * \return 0 on success, or -1 if the texture is not valid
slouken@1670
   801
 */
slouken@1670
   802
extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_TextureID textureID,
slouken@1670
   803
                                             Uint32 * format, int *access,
slouken@1670
   804
                                             int *w, int *h);
slouken@1670
   805
slouken@1670
   806
/**
slouken@1670
   807
 * \fn int SDL_SetTexturePalette(SDL_TextureID textureID, SDL_Color * colors, int firstcolor, int ncolors)
slouken@1670
   808
 *
slouken@1670
   809
 * \brief Update an indexed texture with a color palette
slouken@1670
   810
 *
slouken@1670
   811
 * \param texture The texture to update
slouken@1670
   812
 * \param colors The array of RGB color data
slouken@1670
   813
 * \param firstcolor The first index to update
slouken@1670
   814
 * \param ncolors The number of palette entries to fill with the color data
slouken@1670
   815
 *
slouken@1670
   816
 * \return 0 on success, or -1 if the texture is not valid or not an indexed texture
slouken@1670
   817
 */
slouken@1670
   818
extern DECLSPEC int SDLCALL SDL_SetTexturePalette(SDL_TextureID textureID,
slouken@1670
   819
                                                  SDL_Color * colors,
slouken@1670
   820
                                                  int firstcolor,
slouken@1670
   821
                                                  int ncolors);
slouken@1670
   822
slouken@1670
   823
/**
slouken@1670
   824
 * \fn int SDL_UpdateTexture(SDL_TextureID textureID, SDL_Rect *rect, const void *pixels, int pitch)
slouken@1670
   825
 *
slouken@1670
   826
 * \brief Update the given texture rectangle with new pixel data.
slouken@1670
   827
 *
slouken@1670
   828
 * \param texture The texture to update
slouken@1670
   829
 * \param rect A pointer to the rectangle of pixels to update, or NULL to update the entire texture.
slouken@1670
   830
 * \param pixels The raw pixel data
slouken@1670
   831
 * \param pitch The number of bytes between rows of pixel data
slouken@1670
   832
 *
slouken@1670
   833
 * \return 0 on success, or -1 if the texture is not valid
slouken@1670
   834
 *
slouken@1670
   835
 * \note This is a very slow function for textures not created with SDL_TextureAccess_Local.
slouken@0
   836
 */
slouken@1670
   837
extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_TextureID textureID,
slouken@1670
   838
                                              SDL_Rect * rect,
slouken@1670
   839
                                              const void *pixels, int pitch);
slouken@1670
   840
slouken@1670
   841
/**
slouken@1670
   842
 * \fn void SDL_LockTexture(SDL_TextureID textureID, SDL_Rect *rect, int markDirty, void **pixels, int *pitch)
slouken@1670
   843
 *
slouken@1670
   844
 * \brief Lock a portion of the texture for pixel access.
slouken@1670
   845
 *
slouken@1670
   846
 * \param texture The texture to lock for access, which must have been created with SDL_TextureAccess_Local.
slouken@1670
   847
 * \param rect A pointer to the rectangle to lock for access. If the rect is NULL, the entire texture will be locked.
slouken@1670
   848
 * \param markDirty If this is nonzero, the locked area will be marked dirty when the texture is unlocked.
slouken@1670
   849
 * \param pixels This is filled in with a pointer to the locked pixels, appropriately offset by the locked area.
slouken@1670
   850
 * \param pitch This is filled in with the pitch of the locked pixels.
slouken@1670
   851
 *
slouken@1670
   852
 * \return 0 on success, or -1 if the texture is not valid or was created with SDL_TextureAccess_Remote
slouken@1670
   853
 *
slouken@1670
   854
 * \sa SDL_DirtyTexture()
slouken@1670
   855
 * \sa SDL_UnlockTexture()
slouken@1670
   856
 */
slouken@1670
   857
extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_TextureID textureID,
slouken@1670
   858
                                            SDL_Rect * rect, int markDirty,
slouken@1670
   859
                                            void **pixels, int *pitch);
slouken@1670
   860
slouken@1670
   861
/**
slouken@1670
   862
 * \fn void SDL_UnlockTexture(SDL_TextureID textureID)
slouken@1670
   863
 *
slouken@1670
   864
 * \brief Unlock a texture, uploading the changes to video memory, if needed.
slouken@1670
   865
 *
slouken@1670
   866
 * \sa SDL_LockTexture()
slouken@1670
   867
 * \sa SDL_DirtyTexture()
slouken@1670
   868
 */
slouken@1670
   869
extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_TextureID textureID);
slouken@1670
   870
slouken@1670
   871
/**
slouken@1670
   872
 * \fn void SDL_DirtyTexture(SDL_TextureID textureID, int numrects, SDL_Rect * rects)
slouken@1670
   873
 *
slouken@1670
   874
 * \brief Mark the specified rectangles of the texture as dirty.
slouken@1670
   875
 *
slouken@1670
   876
 * \note The texture must have been created with SDL_TextureAccess_Local.
slouken@1670
   877
 *
slouken@1670
   878
 * \sa SDL_LockTexture()
slouken@1670
   879
 * \sa SDL_UnlockTexture()
slouken@1670
   880
 */
slouken@1670
   881
extern DECLSPEC void SDLCALL SDL_DirtyTexture(SDL_TextureID textureID,
slouken@1670
   882
                                              int numrects, SDL_Rect * rects);
slouken@1670
   883
slouken@1670
   884
/**
slouken@1670
   885
 * \fn void SDL_SelectRenderTexture(SDL_TextureID textureID)
slouken@1670
   886
 *
slouken@1670
   887
 * \brief Select a texture as the rendering target, or 0 to reselect the current window.
slouken@1670
   888
 *
slouken@1670
   889
 * \note The texture must have been created with SDL_TextureAccess_Render.
slouken@1670
   890
 */
slouken@1670
   891
extern DECLSPEC void SDLCALL SDL_SelectRenderTexture(SDL_TextureID textureID);
slouken@1670
   892
slouken@1670
   893
/**
slouken@1670
   894
 * \fn void SDL_RenderFill(SDL_Rect *rect, Uint32 color)
slouken@1670
   895
 *
slouken@1670
   896
 * \brief Fill the current rendering target with the specified color.
slouken@1670
   897
 *
slouken@1670
   898
 * \param rect A pointer to the destination rectangle, or NULL for the entire rendering target.
slouken@1670
   899
 * \param color An ARGB color value.
slouken@1670
   900
 *
slouken@1670
   901
 * \return 0 on success, or -1 if there is no renderer current
slouken@1670
   902
 */
slouken@1670
   903
extern DECLSPEC int SDLCALL SDL_RenderFill(SDL_Rect * rect, Uint32 color);
slouken@0
   904
slouken@1670
   905
/**
slouken@1670
   906
 * \fn int SDL_RenderCopy(SDL_TextureID textureID, SDL_Rect *srcrect, SDL_Rect *dstrect, Uint32 blendMode, Uint32 scaleMode)
slouken@1670
   907
 *
slouken@1670
   908
 * \brief Copy a portion of the texture to the current rendering target.
slouken@1670
   909
 *
slouken@1670
   910
 * \param texture The source texture.
slouken@1670
   911
 * \param srcrect A pointer to the source rectangle, or NULL for the entire texture.
slouken@1670
   912
 * \param dstrect A pointer to the destination rectangle, or NULL for the entire rendering target.
slouken@1670
   913
 * \param blendMode SDL_TextureBlendMode to be used if the source texture has an alpha channel.
slouken@1670
   914
 * \param scaleMode SDL_TextureScaleMode to be used if the source and destination rectangles don't have the same width and height.
slouken@1670
   915
 *
slouken@1670
   916
 * \return 0 on success, or -1 if there is no renderer current, or the driver doesn't support the requested operation.
slouken@1670
   917
 *
slouken@1670
   918
 * \note You can check the video driver info to see what operations are supported.
slouken@1670
   919
 */
slouken@1670
   920
extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_TextureID textureID,
slouken@1670
   921
                                           SDL_Rect * srcrect,
slouken@1670
   922
                                           SDL_Rect * dstrect, int blendMode,
slouken@1670
   923
                                           int scaleMode);
slouken@1670
   924
slouken@1670
   925
/**
slouken@1670
   926
 * \fn int SDL_RenderReadPixels(SDL_Rect *rect, void *pixels, int pitch)
slouken@1670
   927
 *
slouken@1670
   928
 * \brief Read pixels from the current rendering target.
slouken@1670
   929
 *
slouken@1670
   930
 * \param rect A pointer to the rectangle to read, or NULL for the entire render target
slouken@1670
   931
 * \param pixels A pointer to be filled in with the pixel data
slouken@1670
   932
 * \param pitch The pitch of the pixels parameter
slouken@1670
   933
 *
slouken@1670
   934
 * \return 0 on success, or -1 if pixel reading is not supported.
slouken@1670
   935
 *
slouken@1670
   936
 * \warning This is a very slow operation, and should not be used frequently.
slouken@0
   937
 */
slouken@1670
   938
extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Rect * rect,
slouken@1670
   939
                                                 void *pixels, int pitch);
slouken@1670
   940
slouken@1670
   941
/**
slouken@1670
   942
 * \fn int SDL_RenderWritePixels(SDL_Rect *rect, const void *pixels, int pitch)
slouken@1670
   943
 *
slouken@1670
   944
 * \brief Write pixels to the current rendering target.
slouken@1670
   945
 *
slouken@1670
   946
 * \param rect A pointer to the rectangle to write, or NULL for the entire render target
slouken@1670
   947
 * \param pixels A pointer to the pixel data to write
slouken@1670
   948
 * \param pitch The pitch of the pixels parameter
slouken@1670
   949
 *
slouken@1670
   950
 * \return 0 on success, or -1 if pixel writing is not supported.
slouken@1670
   951
 *
slouken@1670
   952
 * \warning This is a very slow operation, and should not be used frequently.
slouken@1670
   953
 */
slouken@1670
   954
extern DECLSPEC int SDLCALL SDL_RenderWritePixels(SDL_Rect * rect,
slouken@1670
   955
                                                  const void *pixels,
slouken@1670
   956
                                                  int pitch);
slouken@1670
   957
slouken@1670
   958
/**
slouken@1670
   959
 * \fn void SDL_RenderPresent(void)
slouken@1670
   960
 *
slouken@1670
   961
 * \brief Update the screen with rendering performed.
slouken@1670
   962
 */
slouken@1670
   963
extern DECLSPEC void SDLCALL SDL_RenderPresent(void);
slouken@1670
   964
slouken@1670
   965
/**
slouken@1670
   966
 * \fn void SDL_DestroyTexture(SDL_TextureID textureID);
slouken@1670
   967
 *
slouken@1670
   968
 * \brief Destroy the specified texture.
slouken@1670
   969
 *
slouken@1670
   970
 * \sa SDL_CreateTexture()
slouken@1670
   971
 * \sa SDL_CreateTextureFromSurface()
slouken@1670
   972
 */
slouken@1670
   973
extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_TextureID textureID);
slouken@1670
   974
slouken@1670
   975
/**
slouken@1670
   976
 * \fn void SDL_DestroyRenderer(SDL_WindowID windowID);
slouken@1670
   977
 *
slouken@1670
   978
 * \brief Destroy the rendering context for a window and free associated
slouken@1670
   979
 *        textures.
slouken@1670
   980
 *
slouken@1670
   981
 * \sa SDL_CreateRenderer()
slouken@1670
   982
 */
slouken@1670
   983
extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_WindowID windowID);
slouken@0
   984
slouken@0
   985
/*
slouken@0
   986
 * Set the gamma correction for each of the color channels.
slouken@0
   987
 * The gamma values range (approximately) between 0.1 and 10.0
slouken@0
   988
 * 
slouken@0
   989
 * If this function isn't supported directly by the hardware, it will
slouken@0
   990
 * be emulated using gamma ramps, if available.  If successful, this
slouken@0
   991
 * function returns 0, otherwise it returns -1.
slouken@0
   992
 */
slouken@1668
   993
extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
slouken@0
   994
slouken@0
   995
/*
slouken@0
   996
 * Set the gamma translation table for the red, green, and blue channels
slouken@0
   997
 * of the video hardware.  Each table is an array of 256 16-bit quantities,
slouken@0
   998
 * representing a mapping between the input and output for that channel.
slouken@0
   999
 * The input is the index into the array, and the output is the 16-bit
slouken@0
  1000
 * gamma value at that index, scaled to the output color precision.
slouken@0
  1001
 * 
slouken@0
  1002
 * You may pass NULL for any of the channels to leave it unchanged.
slouken@0
  1003
 * If the call succeeds, it will return 0.  If the display driver or
slouken@0
  1004
 * hardware does not support gamma translation, or otherwise fails,
slouken@0
  1005
 * this function will return -1.
slouken@0
  1006
 */
slouken@1668
  1007
extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 * red,
slouken@1668
  1008
                                             const Uint16 * green,
slouken@1668
  1009
                                             const Uint16 * blue);
slouken@0
  1010
slouken@0
  1011
/*
slouken@0
  1012
 * Retrieve the current values of the gamma translation tables.
slouken@0
  1013
 * 
slouken@0
  1014
 * You must pass in valid pointers to arrays of 256 16-bit quantities.
slouken@0
  1015
 * Any of the pointers may be NULL to ignore that channel.
slouken@0
  1016
 * If the call succeeds, it will return 0.  If the display driver or
slouken@0
  1017
 * hardware does not support gamma translation, or otherwise fails,
slouken@0
  1018
 * this function will return -1.
slouken@0
  1019
 */
slouken@1668
  1020
extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 * red, Uint16 * green,
slouken@1668
  1021
                                             Uint16 * blue);
slouken@0
  1022
slouken@0
  1023
/*
slouken@0
  1024
 * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
slouken@0
  1025
 * is not a palettized surface, this function does nothing, returning 0.
slouken@0
  1026
 * If all of the colors were set as passed to SDL_SetColors(), it will
slouken@0
  1027
 * return 1.  If not all the color entries were set exactly as given,
slouken@0
  1028
 * it will return 0, and you should look at the surface palette to
slouken@0
  1029
 * determine the actual color palette.
slouken@0
  1030
 *
slouken@0
  1031
 * When 'surface' is the surface associated with the current display, the
slouken@0
  1032
 * display colormap will be updated with the requested colors.  If 
slouken@0
  1033
 * SDL_HWPALETTE was set in SDL_SetVideoMode() flags, SDL_SetColors()
slouken@0
  1034
 * will always return 1, and the palette is guaranteed to be set the way
slouken@0
  1035
 * you desire, even if the window colormap has to be warped or run under
slouken@0
  1036
 * emulation.
slouken@0
  1037
 */
slouken@1668
  1038
extern DECLSPEC int SDLCALL SDL_SetColors(SDL_Surface * surface,
slouken@1668
  1039
                                          SDL_Color * colors, int firstcolor,
slouken@1668
  1040
                                          int ncolors);
slouken@0
  1041
slouken@0
  1042
/*
slouken@0
  1043
 * Maps an RGB triple to an opaque pixel value for a given pixel format
slouken@0
  1044
 */
slouken@337
  1045
extern DECLSPEC Uint32 SDLCALL SDL_MapRGB
slouken@1662
  1046
    (SDL_PixelFormat * format, Uint8 r, Uint8 g, Uint8 b);
slouken@0
  1047
slouken@0
  1048
/*
slouken@0
  1049
 * Maps an RGBA quadruple to a pixel value for a given pixel format
slouken@0
  1050
 */
slouken@1668
  1051
extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(SDL_PixelFormat * format,
slouken@1668
  1052
                                           Uint8 r, Uint8 g, Uint8 b,
slouken@1668
  1053
                                           Uint8 a);
slouken@0
  1054
slouken@0
  1055
/*
slouken@0
  1056
 * Maps a pixel value into the RGB components for a given pixel format
slouken@0
  1057
 */
slouken@1668
  1058
extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, SDL_PixelFormat * fmt,
slouken@1668
  1059
                                        Uint8 * r, Uint8 * g, Uint8 * b);
slouken@0
  1060
slouken@0
  1061
/*
slouken@0
  1062
 * Maps a pixel value into the RGBA components for a given pixel format
slouken@0
  1063
 */
slouken@1668
  1064
extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, SDL_PixelFormat * fmt,
slouken@1668
  1065
                                         Uint8 * r, Uint8 * g, Uint8 * b,
slouken@1668
  1066
                                         Uint8 * a);
slouken@0
  1067
slouken@0
  1068
/*
slouken@0
  1069
 * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
slouken@0
  1070
 * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
slouken@0
  1071
 * If the depth is greater than 8 bits, the pixel format is set using the
slouken@0
  1072
 * flags '[RGB]mask'.
slouken@0
  1073
 * If the function runs out of memory, it will return NULL.
slouken@0
  1074
 *
slouken@0
  1075
 * The 'flags' tell what kind of surface to create.
slouken@0
  1076
 * SDL_SRCCOLORKEY indicates that the surface will be used for colorkey blits.
slouken@1670
  1077
 * SDL_SRCALPHA means that the surface will be used for alpha blits.
slouken@0
  1078
 */
slouken@1662
  1079
extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
slouken@1662
  1080
    (Uint32 flags, int width, int height, int depth,
slouken@1662
  1081
     Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
slouken@1668
  1082
extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
slouken@1668
  1083
                                                              int width,
slouken@1668
  1084
                                                              int height,
slouken@1668
  1085
                                                              int depth,
slouken@1668
  1086
                                                              int pitch,
slouken@1668
  1087
                                                              Uint32 Rmask,
slouken@1668
  1088
                                                              Uint32 Gmask,
slouken@1668
  1089
                                                              Uint32 Bmask,
slouken@1668
  1090
                                                              Uint32 Amask);
slouken@1670
  1091
extern DECLSPEC SDL_Surface *SDLCALL
slouken@1670
  1092
SDL_CreateRGBSurfaceFromTexture(SDL_TextureID textureID);
slouken@1668
  1093
extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
slouken@0
  1094
slouken@0
  1095
/*
slouken@0
  1096
 * SDL_LockSurface() sets up a surface for directly accessing the pixels.
slouken@0
  1097
 * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
slouken@0
  1098
 * to and read from 'surface->pixels', using the pixel format stored in 
slouken@0
  1099
 * 'surface->format'.  Once you are done accessing the surface, you should 
slouken@0
  1100
 * use SDL_UnlockSurface() to release it.
slouken@0
  1101
 *
slouken@0
  1102
 * Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
slouken@0
  1103
 * to 0, then you can read and write to the surface at any time, and the
slouken@1670
  1104
 * pixel format of the surface will not change.
slouken@0
  1105
 * 
slouken@0
  1106
 * No operating system or library calls should be made between lock/unlock
slouken@0
  1107
 * pairs, as critical system locks may be held during this time.
slouken@0
  1108
 *
slouken@0
  1109
 * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
slouken@0
  1110
 */
slouken@1668
  1111
extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
slouken@1668
  1112
extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
slouken@0
  1113
slouken@0
  1114
/*
slouken@0
  1115
 * Load a surface from a seekable SDL data source (memory or file.)
slouken@0
  1116
 * If 'freesrc' is non-zero, the source will be closed after being read.
slouken@0
  1117
 * Returns the new surface, or NULL if there was an error.
slouken@0
  1118
 * The new surface should be freed with SDL_FreeSurface().
slouken@0
  1119
 */
slouken@1668
  1120
extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
slouken@1668
  1121
                                                    int freesrc);
slouken@0
  1122
slouken@0
  1123
/* Convenience macro -- load a surface from a file */
slouken@0
  1124
#define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
slouken@0
  1125
slouken@0
  1126
/*
slouken@0
  1127
 * Save a surface to a seekable SDL data source (memory or file.)
slouken@0
  1128
 * If 'freedst' is non-zero, the source will be closed after being written.
slouken@0
  1129
 * Returns 0 if successful or -1 if there was an error.
slouken@0
  1130
 */
slouken@337
  1131
extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
slouken@1662
  1132
    (SDL_Surface * surface, SDL_RWops * dst, int freedst);
slouken@0
  1133
slouken@0
  1134
/* Convenience macro -- save a surface to a file */
slouken@0
  1135
#define SDL_SaveBMP(surface, file) \
slouken@0
  1136
		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
slouken@0
  1137
slouken@0
  1138
/*
slouken@0
  1139
 * Sets the color key (transparent pixel) in a blittable surface.
slouken@0
  1140
 * If 'flag' is SDL_SRCCOLORKEY (optionally OR'd with SDL_RLEACCEL), 
slouken@0
  1141
 * 'key' will be the transparent pixel in the source image of a blit.
slouken@0
  1142
 * SDL_RLEACCEL requests RLE acceleration for the surface if present,
slouken@0
  1143
 * and removes RLE acceleration if absent.
slouken@0
  1144
 * If 'flag' is 0, this function clears any current color key.
slouken@0
  1145
 * This function returns 0, or -1 if there was an error.
slouken@0
  1146
 */
slouken@337
  1147
extern DECLSPEC int SDLCALL SDL_SetColorKey
slouken@1662
  1148
    (SDL_Surface * surface, Uint32 flag, Uint32 key);
slouken@0
  1149
slouken@0
  1150
/*
slouken@0
  1151
 * This function sets the alpha value for the entire surface, as opposed to
slouken@0
  1152
 * using the alpha component of each pixel. This value measures the range
slouken@0
  1153
 * of transparency of the surface, 0 being completely transparent to 255
slouken@0
  1154
 * being completely opaque. An 'alpha' value of 255 causes blits to be
slouken@0
  1155
 * opaque, the source pixels copied to the destination (the default). Note
slouken@0
  1156
 * that per-surface alpha can be combined with colorkey transparency.
slouken@0
  1157
 *
slouken@0
  1158
 * If 'flag' is 0, alpha blending is disabled for the surface.
slouken@0
  1159
 * If 'flag' is SDL_SRCALPHA, alpha blending is enabled for the surface.
slouken@0
  1160
 * OR:ing the flag with SDL_RLEACCEL requests RLE acceleration for the
slouken@0
  1161
 * surface; if SDL_RLEACCEL is not specified, the RLE accel will be removed.
slouken@432
  1162
 *
slouken@432
  1163
 * The 'alpha' parameter is ignored for surfaces that have an alpha channel.
slouken@0
  1164
 */
slouken@1668
  1165
extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface * surface, Uint32 flag,
slouken@1668
  1166
                                         Uint8 alpha);
slouken@0
  1167
slouken@0
  1168
/*
slouken@0
  1169
 * Sets the clipping rectangle for the destination surface in a blit.
slouken@0
  1170
 *
slouken@0
  1171
 * If the clip rectangle is NULL, clipping will be disabled.
slouken@0
  1172
 * If the clip rectangle doesn't intersect the surface, the function will
slouken@0
  1173
 * return SDL_FALSE and blits will be completely clipped.  Otherwise the
slouken@0
  1174
 * function returns SDL_TRUE and blits to the surface will be clipped to
slouken@0
  1175
 * the intersection of the surface area and the clipping rectangle.
slouken@0
  1176
 *
slouken@0
  1177
 * Note that blits are automatically clipped to the edges of the source
slouken@0
  1178
 * and destination surfaces.
slouken@0
  1179
 */
slouken@1668
  1180
extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
slouken@1668
  1181
                                                 const SDL_Rect * rect);
slouken@0
  1182
slouken@0
  1183
/*
slouken@0
  1184
 * Gets the clipping rectangle for the destination surface in a blit.
slouken@0
  1185
 * 'rect' must be a pointer to a valid rectangle which will be filled
slouken@0
  1186
 * with the correct values.
slouken@0
  1187
 */
slouken@1668
  1188
extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
slouken@1668
  1189
                                             SDL_Rect * rect);
slouken@0
  1190
slouken@0
  1191
/*
slouken@0
  1192
 * Creates a new surface of the specified format, and then copies and maps 
slouken@0
  1193
 * the given surface to it so the blit of the converted surface will be as 
slouken@0
  1194
 * fast as possible.  If this function fails, it returns NULL.
slouken@0
  1195
 *
slouken@0
  1196
 * The 'flags' parameter is passed to SDL_CreateRGBSurface() and has those 
slouken@0
  1197
 * semantics.  You can also pass SDL_RLEACCEL in the flags parameter and
slouken@0
  1198
 * SDL will try to RLE accelerate colorkey and alpha blits in the resulting
slouken@0
  1199
 * surface.
slouken@0
  1200
 *
slouken@0
  1201
 * This function is used internally by SDL_DisplayFormat().
slouken@0
  1202
 */
slouken@1662
  1203
extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
slouken@1662
  1204
    (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags);
slouken@0
  1205
slouken@0
  1206
/*
slouken@1670
  1207
 * This function performs a fast fill of the given rectangle with 'color'
slouken@1670
  1208
 * The given rectangle is clipped to the destination surface clip area
slouken@1670
  1209
 * and the final fill rectangle is saved in the passed in pointer.
slouken@1670
  1210
 * If 'dstrect' is NULL, the whole surface will be filled with 'color'
slouken@1670
  1211
 * The color should be a pixel of the format used by the surface, and 
slouken@1670
  1212
 * can be generated by the SDL_MapRGB() function.
slouken@1670
  1213
 * This function returns 0 on success, or -1 on error.
slouken@1670
  1214
 */
slouken@1670
  1215
extern DECLSPEC int SDLCALL SDL_FillRect
slouken@1670
  1216
    (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color);
slouken@1670
  1217
slouken@1670
  1218
/*
slouken@0
  1219
 * This performs a fast blit from the source surface to the destination
slouken@0
  1220
 * surface.  It assumes that the source and destination rectangles are
slouken@0
  1221
 * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
slouken@0
  1222
 * surface (src or dst) is copied.  The final blit rectangles are saved
slouken@0
  1223
 * in 'srcrect' and 'dstrect' after all clipping is performed.
slouken@0
  1224
 * If the blit is successful, it returns 0, otherwise it returns -1.
slouken@0
  1225
 *
slouken@0
  1226
 * The blit function should not be called on a locked surface.
slouken@0
  1227
 *
slouken@0
  1228
 * The blit semantics for surfaces with and without alpha and colorkey
slouken@0
  1229
 * are defined as follows:
slouken@0
  1230
 *
slouken@0
  1231
 * RGBA->RGB:
slouken@0
  1232
 *     SDL_SRCALPHA set:
slouken@0
  1233
 * 	alpha-blend (using alpha-channel).
slouken@0
  1234
 * 	SDL_SRCCOLORKEY ignored.
slouken@0
  1235
 *     SDL_SRCALPHA not set:
slouken@0
  1236
 * 	copy RGB.
slouken@0
  1237
 * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
slouken@0
  1238
 * 	RGB values of the source colour key, ignoring alpha in the
slouken@0
  1239
 * 	comparison.
slouken@0
  1240
 * 
slouken@0
  1241
 * RGB->RGBA:
slouken@0
  1242
 *     SDL_SRCALPHA set:
slouken@0
  1243
 * 	alpha-blend (using the source per-surface alpha value);
slouken@0
  1244
 * 	set destination alpha to opaque.
slouken@0
  1245
 *     SDL_SRCALPHA not set:
slouken@431
  1246
 * 	copy RGB, set destination alpha to source per-surface alpha value.
slouken@0
  1247
 *     both:
slouken@0
  1248
 * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
slouken@0
  1249
 * 	source colour key.
slouken@0
  1250
 * 
slouken@0
  1251
 * RGBA->RGBA:
slouken@0
  1252
 *     SDL_SRCALPHA set:
slouken@0
  1253
 * 	alpha-blend (using the source alpha channel) the RGB values;
slouken@0
  1254
 * 	leave destination alpha untouched. [Note: is this correct?]
slouken@0
  1255
 * 	SDL_SRCCOLORKEY ignored.
slouken@0
  1256
 *     SDL_SRCALPHA not set:
slouken@0
  1257
 * 	copy all of RGBA to the destination.
slouken@0
  1258
 * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
slouken@0
  1259
 * 	RGB values of the source colour key, ignoring alpha in the
slouken@0
  1260
 * 	comparison.
slouken@0
  1261
 * 
slouken@0
  1262
 * RGB->RGB: 
slouken@0
  1263
 *     SDL_SRCALPHA set:
slouken@0
  1264
 * 	alpha-blend (using the source per-surface alpha value).
slouken@0
  1265
 *     SDL_SRCALPHA not set:
slouken@0
  1266
 * 	copy RGB.
slouken@0
  1267
 *     both:
slouken@0
  1268
 * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
slouken@0
  1269
 * 	source colour key.
slouken@0
  1270
 *
slouken@0
  1271
 * If either of the surfaces were in video memory, and the blit returns -2,
slouken@0
  1272
 * the video memory was lost, so it should be reloaded with artwork and 
slouken@0
  1273
 * re-blitted:
slouken@0
  1274
	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
slouken@0
  1275
		while ( SDL_LockSurface(image) < 0 )
slouken@0
  1276
			Sleep(10);
slouken@0
  1277
		-- Write image pixels to image->pixels --
slouken@0
  1278
		SDL_UnlockSurface(image);
slouken@0
  1279
	}
slouken@0
  1280
 * This happens under DirectX 5.0 when the system switches away from your
slouken@0
  1281
 * fullscreen application.  The lock will also fail until you have access
slouken@0
  1282
 * to the video memory again.
slouken@0
  1283
 */
slouken@0
  1284
/* You should call SDL_BlitSurface() unless you know exactly how SDL
slouken@0
  1285
   blitting works internally and how to use the other blit functions.
slouken@0
  1286
*/
slouken@0
  1287
#define SDL_BlitSurface SDL_UpperBlit
slouken@0
  1288
slouken@0
  1289
/* This is the public blit function, SDL_BlitSurface(), and it performs
slouken@0
  1290
   rectangle validation and clipping before passing it to SDL_LowerBlit()
slouken@0
  1291
*/
slouken@337
  1292
extern DECLSPEC int SDLCALL SDL_UpperBlit
slouken@1662
  1293
    (SDL_Surface * src, SDL_Rect * srcrect,
slouken@1662
  1294
     SDL_Surface * dst, SDL_Rect * dstrect);
slouken@0
  1295
/* This is a semi-private blit function and it performs low-level surface
slouken@0
  1296
   blitting only.
slouken@0
  1297
*/
slouken@337
  1298
extern DECLSPEC int SDLCALL SDL_LowerBlit
slouken@1662
  1299
    (SDL_Surface * src, SDL_Rect * srcrect,
slouken@1662
  1300
     SDL_Surface * dst, SDL_Rect * dstrect);
slouken@0
  1301
slouken@1670
  1302
/**
slouken@1670
  1303
 * \fn int SDL_SoftStretch(SDL_Surface * src, SDL_Rect * srcrect, SDL_Surface * dst, SDL_Rect * dstrect)
slouken@0
  1304
 *
slouken@1670
  1305
 * \brief Perform a fast, low quality, stretch blit between two surfaces of the same pixel format.
slouken@1670
  1306
 * \note This function uses a static buffer, and is not thread-safe.
slouken@0
  1307
 */
slouken@1670
  1308
extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
slouken@1670
  1309
                                            SDL_Rect * srcrect,
slouken@1670
  1310
                                            SDL_Surface * dst,
slouken@1670
  1311
                                            SDL_Rect * dstrect);
slouken@0
  1312
slouken@0
  1313
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
slouken@0
  1314
/* OpenGL support functions.                                                 */
slouken@0
  1315
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
slouken@0
  1316
slouken@0
  1317
/*
slouken@1490
  1318
 * Dynamically load an OpenGL library, or the default one if path is NULL
slouken@0
  1319
 *
slouken@0
  1320
 * If you do this, you need to retrieve all of the GL functions used in
slouken@0
  1321
 * your program from the dynamic library using SDL_GL_GetProcAddress().
slouken@0
  1322
 */
slouken@1668
  1323
extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
slouken@0
  1324
slouken@0
  1325
/*
slouken@1490
  1326
 * Get the address of a GL function
slouken@0
  1327
 */
slouken@1668
  1328
extern DECLSPEC void *SDLCALL SDL_GL_GetProcAddress(const char *proc);
slouken@0
  1329
slouken@0
  1330
/*
slouken@1662
  1331
 * Set an attribute of the OpenGL subsystem before window creation.
slouken@0
  1332
 */
slouken@1668
  1333
extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
slouken@0
  1334
slouken@0
  1335
/*
slouken@0
  1336
 * Get an attribute of the OpenGL subsystem from the windowing
slouken@0
  1337
 * interface, such as glX. This is of course different from getting
slouken@0
  1338
 * the values from SDL's internal OpenGL subsystem, which only
slouken@0
  1339
 * stores the values you request before initialization.
slouken@0
  1340
 *
slouken@0
  1341
 * Developers should track the values they pass into SDL_GL_SetAttribute
slouken@0
  1342
 * themselves if they want to retrieve these values.
slouken@0
  1343
 */
slouken@1668
  1344
extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value);
slouken@0
  1345
slouken@0
  1346
/*
slouken@0
  1347
 * Swap the OpenGL buffers, if double-buffering is supported.
slouken@0
  1348
 */
slouken@1668
  1349
extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers(void);
slouken@0
  1350
slouken@0
  1351
/* Ends C function definitions when using C++ */
slouken@0
  1352
#ifdef __cplusplus
slouken@1662
  1353
/* *INDENT-OFF* */
slouken@0
  1354
}
slouken@1662
  1355
/* *INDENT-ON* */
slouken@0
  1356
#endif
slouken@0
  1357
#include "close_code.h"
slouken@0
  1358
slouken@0
  1359
#endif /* _SDL_video_h */
slouken@1662
  1360
slouken@1662
  1361
/* vi: set ts=4 sw=4 expandtab: */