include/SDL_video.h
changeset 1895 c121d94672cb
parent 1737 eacc5bc01d1c
child 1897 c2a27da60b18
     1.1 --- a/include/SDL_video.h	Thu Jul 06 18:01:37 2006 +0000
     1.2 +++ b/include/SDL_video.h	Mon Jul 10 21:04:37 2006 +0000
     1.3 @@ -20,185 +20,293 @@
     1.4      slouken@libsdl.org
     1.5  */
     1.6  
     1.7 -/* Header file for access to the SDL raw framebuffer window */
     1.8 +/**
     1.9 + * \file SDL_video.h
    1.10 + *
    1.11 + * Header file for access to the SDL raw framebuffer window
    1.12 + */
    1.13  
    1.14  #ifndef _SDL_video_h
    1.15  #define _SDL_video_h
    1.16  
    1.17  #include "SDL_stdinc.h"
    1.18  #include "SDL_error.h"
    1.19 +#include "SDL_pixels.h"
    1.20  #include "SDL_rwops.h"
    1.21  
    1.22  #include "begin_code.h"
    1.23  /* Set up for C function definitions, even when using C++ */
    1.24  #ifdef __cplusplus
    1.25 +/* *INDENT-OFF* */
    1.26  extern "C" {
    1.27 +/* *INDENT-ON* */
    1.28  #endif
    1.29  
    1.30  /* Transparency definitions: These define alpha as the opacity of a surface */
    1.31  #define SDL_ALPHA_OPAQUE 255
    1.32  #define SDL_ALPHA_TRANSPARENT 0
    1.33  
    1.34 -/* Useful data types */
    1.35 -typedef struct SDL_Rect {
    1.36 -	Sint16 x, y;
    1.37 -	Uint16 w, h;
    1.38 +/**
    1.39 + * \struct SDL_Rect
    1.40 + *
    1.41 + * \brief A rectangle, with the origin at the upper left.
    1.42 + */
    1.43 +typedef struct SDL_Rect
    1.44 +{
    1.45 +    int x, y;
    1.46 +    int w, h;
    1.47  } SDL_Rect;
    1.48  
    1.49 -typedef struct SDL_Color {
    1.50 -	Uint8 r;
    1.51 -	Uint8 g;
    1.52 -	Uint8 b;
    1.53 -	Uint8 unused;
    1.54 -} SDL_Color;
    1.55 -#define SDL_Colour SDL_Color
    1.56 +/**
    1.57 + * \struct SDL_DisplayMode
    1.58 + *
    1.59 + * \brief  The structure that defines a display mode
    1.60 + *
    1.61 + * \sa SDL_GetNumDisplayModes()
    1.62 + * \sa SDL_GetDisplayMode()
    1.63 + * \sa SDL_GetDesktopDisplayMode()
    1.64 + * \sa SDL_GetCurrentDisplayMode()
    1.65 + * \sa SDL_GetClosestDisplayMode()
    1.66 + * \sa SDL_SetDisplayMode()
    1.67 + */
    1.68 +typedef struct
    1.69 +{
    1.70 +    Uint32 format;              /**< pixel format */
    1.71 +    int w;                      /**< width */
    1.72 +    int h;                      /**< height */
    1.73 +    int refresh_rate;           /**< refresh rate (or zero for unspecified) */
    1.74 +    void *driverdata;           /**< driver-specific data, initialize to 0 */
    1.75 +} SDL_DisplayMode;
    1.76  
    1.77 -typedef struct SDL_Palette {
    1.78 -	int       ncolors;
    1.79 -	SDL_Color *colors;
    1.80 -} SDL_Palette;
    1.81 +/**
    1.82 + * \typedef SDL_WindowID
    1.83 + *
    1.84 + * \brief The type used to identify a window
    1.85 + *
    1.86 + * \sa SDL_CreateWindow()
    1.87 + * \sa SDL_CreateWindowFrom()
    1.88 + * \sa SDL_DestroyWindow()
    1.89 + * \sa SDL_GetWindowData()
    1.90 + * \sa SDL_GetWindowFlags()
    1.91 + * \sa SDL_GetWindowGrab()
    1.92 + * \sa SDL_GetWindowPosition()
    1.93 + * \sa SDL_GetWindowSize()
    1.94 + * \sa SDL_GetWindowTitle()
    1.95 + * \sa SDL_HideWindow()
    1.96 + * \sa SDL_MaximizeWindow()
    1.97 + * \sa SDL_MinimizeWindow()
    1.98 + * \sa SDL_RaiseWindow()
    1.99 + * \sa SDL_RestoreWindow()
   1.100 + * \sa SDL_SetWindowData()
   1.101 + * \sa SDL_SetWindowFullscreen()
   1.102 + * \sa SDL_SetWindowGrab()
   1.103 + * \sa SDL_SetWindowIcon()
   1.104 + * \sa SDL_SetWindowPosition()
   1.105 + * \sa SDL_SetWindowSize()
   1.106 + * \sa SDL_SetWindowTitle()
   1.107 + * \sa SDL_ShowWindow()
   1.108 + */
   1.109 +typedef Uint32 SDL_WindowID;
   1.110  
   1.111 -/* Everything in the pixel format structure is read-only */
   1.112 -typedef struct SDL_PixelFormat {
   1.113 -	SDL_Palette *palette;
   1.114 -	Uint8  BitsPerPixel;
   1.115 -	Uint8  BytesPerPixel;
   1.116 -	Uint8  Rloss;
   1.117 -	Uint8  Gloss;
   1.118 -	Uint8  Bloss;
   1.119 -	Uint8  Aloss;
   1.120 -	Uint8  Rshift;
   1.121 -	Uint8  Gshift;
   1.122 -	Uint8  Bshift;
   1.123 -	Uint8  Ashift;
   1.124 -	Uint32 Rmask;
   1.125 -	Uint32 Gmask;
   1.126 -	Uint32 Bmask;
   1.127 -	Uint32 Amask;
   1.128 +/**
   1.129 + * \enum SDL_WindowFlags
   1.130 + *
   1.131 + * \brief The flags on a window
   1.132 + *
   1.133 + * \sa SDL_GetWindowFlags()
   1.134 + */
   1.135 +typedef enum
   1.136 +{
   1.137 +    SDL_WINDOW_FULLSCREEN = 0x00000001,         /**< fullscreen window, implies borderless */
   1.138 +    SDL_WINDOW_OPENGL = 0x00000002,             /**< window usable with OpenGL context */
   1.139 +    SDL_WINDOW_SHOWN = 0x00000004,              /**< window is visible */
   1.140 +    SDL_WINDOW_BORDERLESS = 0x00000008,         /**< no window decoration */
   1.141 +    SDL_WINDOW_RESIZABLE = 0x00000010,          /**< window can be resized */
   1.142 +    SDL_WINDOW_MINIMIZED = 0x00000020,          /**< minimized */
   1.143 +    SDL_WINDOW_MAXIMIZED = 0x00000040,          /**< maximized */
   1.144 +    SDL_WINDOW_INPUT_GRABBED = 0x00000100,      /**< window has grabbed input focus */
   1.145 +    SDL_WINDOW_INPUT_FOCUS = 0x00000200,        /**< window has input focus */
   1.146 +    SDL_WINDOW_MOUSE_FOCUS = 0x00000400,        /**< window has mouse focus */
   1.147 +} SDL_WindowFlags;
   1.148  
   1.149 -	/* RGB color key information */
   1.150 -	Uint32 colorkey;
   1.151 -	/* Alpha value information (per-surface alpha) */
   1.152 -	Uint8  alpha;
   1.153 -} SDL_PixelFormat;
   1.154 +/**
   1.155 + * \def SDL_WINDOWPOS_UNDEFINED
   1.156 + * \brief Used to indicate that you don't care what the window position is.
   1.157 + */
   1.158 +#define SDL_WINDOWPOS_UNDEFINED 0x7FFFFFF
   1.159 +/**
   1.160 + * \def SDL_WINDOWPOS_CENTERED
   1.161 + * \brief Used to indicate that the window position should be centered.
   1.162 + */
   1.163 +#define SDL_WINDOWPOS_CENTERED  0x7FFFFFE
   1.164 +
   1.165 +/**
   1.166 + * \enum SDL_WindowEventID
   1.167 + *
   1.168 + * \brief Event subtype for window events
   1.169 + */
   1.170 +typedef enum
   1.171 +{
   1.172 +    SDL_WINDOWEVENT_NONE,               /**< Never used */
   1.173 +    SDL_WINDOWEVENT_SHOWN,              /**< Window has been shown */
   1.174 +    SDL_WINDOWEVENT_HIDDEN,             /**< Window has been hidden */
   1.175 +    SDL_WINDOWEVENT_EXPOSED,            /**< Window has been exposed and should be redrawn */
   1.176 +    SDL_WINDOWEVENT_MOVED,              /**< Window has been moved to data1,data2 */
   1.177 +    SDL_WINDOWEVENT_RESIZED,            /**< Window size changed to data1xdata2 */
   1.178 +    SDL_WINDOWEVENT_MINIMIZED,          /**< Window has been minimized */
   1.179 +    SDL_WINDOWEVENT_MAXIMIZED,          /**< Window has been maximized */
   1.180 +    SDL_WINDOWEVENT_RESTORED,           /**< Window has been restored to normal size and position */
   1.181 +    SDL_WINDOWEVENT_ENTER,              /**< The window has gained mouse focus */
   1.182 +    SDL_WINDOWEVENT_LEAVE,              /**< The window has lost mouse focus */
   1.183 +    SDL_WINDOWEVENT_FOCUS_GAINED,       /**< The window has gained keyboard focus */
   1.184 +    SDL_WINDOWEVENT_FOCUS_LOST,         /**< The window has lost keyboard focus */
   1.185 +    SDL_WINDOWEVENT_CLOSE,                              /**< The window manager requests that the window be closed */
   1.186 +} SDL_WindowEventID;
   1.187 +
   1.188 +/**
   1.189 + * \enum SDL_RendererFlags
   1.190 + *
   1.191 + * \brief Flags used when initializing a render manager.
   1.192 + */
   1.193 +typedef enum
   1.194 +{
   1.195 +    SDL_Renderer_PresentDiscard = 0x00000001,   /**< Present leaves the contents of the backbuffer undefined */
   1.196 +    SDL_Renderer_PresentCopy = 0x00000002,      /**< Present uses a copy from back buffer to the front buffer */
   1.197 +    SDL_Renderer_PresentFlip2 = 0x00000004,     /**< Present uses a flip, swapping back buffer and front buffer */
   1.198 +    SDL_Renderer_PresentFlip3 = 0x00000008,     /**< Present uses a flip, rotating between two back buffers and a front buffer */
   1.199 +    SDL_Renderer_PresentVSync = 0x00000010,     /**< Present is synchronized with the refresh rate */
   1.200 +    SDL_Renderer_RenderTarget = 0x00000020,     /**< The renderer can create texture render targets */
   1.201 +    SDL_Renderer_Accelerated = 0x00000040,      /**< The renderer uses hardware acceleration */
   1.202 +    SDL_Renderer_ = 0x00000080,      /**< The renderer uses hardware acceleration */
   1.203 +    SDL_Renderer_Minimal = 0x00000100,          /**< The renderer only supports the read/write pixel and present functions */
   1.204 +} SDL_RendererFlags;
   1.205 +
   1.206 +/**
   1.207 + * \struct SDL_RendererInfo
   1.208 + *
   1.209 + * \brief Information on the capabilities of a render manager.
   1.210 + */
   1.211 +typedef struct SDL_RendererInfo
   1.212 +{
   1.213 +    const char *name;           /**< The name of the renderer */
   1.214 +    Uint32 flags;               /**< Supported SDL_RendererFlags */
   1.215 +    Uint32 blend_modes;         /**< A mask of supported blend modes */
   1.216 +    Uint32 scale_modes;         /**< A mask of supported scale modes */
   1.217 +    Uint32 num_texture_formats; /**< The number of available texture formats */
   1.218 +    Uint32 texture_formats[32]; /**< The available texture formats */
   1.219 +    int max_texture_width;      /**< The maximimum texture width */
   1.220 +    int max_texture_height;     /**< The maximimum texture height */
   1.221 +} SDL_RendererInfo;
   1.222 +
   1.223 +/**
   1.224 + * \enum SDL_TextureAccess
   1.225 + *
   1.226 + * \brief The access pattern allowed for a texture
   1.227 + */
   1.228 +typedef enum
   1.229 +{
   1.230 +    SDL_TextureAccess_Render,   /**< Unlockable video memory, rendering allowed */
   1.231 +    SDL_TextureAccess_Remote,   /**< Unlockable video memory */
   1.232 +    SDL_TextureAccess_Local,    /**< Lockable system memory */
   1.233 +} SDL_TextureAccess;
   1.234 +
   1.235 +/**
   1.236 + * \enum SDL_TextureBlendMode
   1.237 + *
   1.238 + * \brief The blend mode used in SDL_RenderCopy()
   1.239 + */
   1.240 +typedef enum
   1.241 +{
   1.242 +    SDL_TextureBlendMode_None = 0x00000000,     /**< No blending */
   1.243 +    SDL_TextureBlendMode_Mask = 0x00000001,     /**< dst = A ? src : dst (alpha is mask) */
   1.244 +    SDL_TextureBlendMode_Blend = 0x00000002,    /**< dst = (src * A) + (dst * (1-A)) */
   1.245 +    SDL_TextureBlendMode_Add = 0x00000004,      /**< dst = (src * A) + dst */
   1.246 +    SDL_TextureBlendMode_Mod = 0x00000008,      /**< dst = src * dst */
   1.247 +} SDL_TextureBlendMode;
   1.248 +
   1.249 +/**
   1.250 + * \enum SDL_TextureScaleMode
   1.251 + *
   1.252 + * \brief The scale mode used in SDL_RenderCopy()
   1.253 + */
   1.254 +typedef enum
   1.255 +{
   1.256 +    SDL_TextureScaleMode_None = 0x00000000,     /**< No scaling, rectangles must match dimensions */
   1.257 +    SDL_TextureScaleMode_Fast = 0x00000001,     /**< Point sampling or equivalent algorithm */
   1.258 +    SDL_TextureScaleMode_Slow = 0x00000002,     /**< Linear filtering or equivalent algorithm */
   1.259 +    SDL_TextureScaleMode_Best = 0x00000004,     /**< Bicubic filtering or equivalent algorithm */
   1.260 +} SDL_TextureScaleMode;
   1.261 +
   1.262 +/**
   1.263 + * \typedef SDL_TextureID
   1.264 + *
   1.265 + * \brief An efficient driver-specific representation of pixel data
   1.266 + */
   1.267 +typedef Uint32 SDL_TextureID;
   1.268 +
   1.269 +/**
   1.270 + * \typedef SDL_GLContext
   1.271 + *
   1.272 + * \brief An opaque handle to an OpenGL context.
   1.273 + */
   1.274 +typedef void *SDL_GLContext;
   1.275 +
   1.276 +
   1.277 +/* These are the currently supported flags for the SDL_surface */
   1.278 +/* Used internally (read-only) */
   1.279 +#define SDL_HWSURFACE       0x00000001  /* Surface represents a texture */
   1.280 +#define SDL_PREALLOC        0x00000002  /* Surface uses preallocated memory */
   1.281 +#define SDL_SRCALPHA        0x00000004  /* Blit uses source alpha blending */
   1.282 +#define SDL_SRCCOLORKEY     0x00000008  /* Blit uses a source color key */
   1.283 +#define SDL_RLEACCELOK      0x00000010  /* Private flag */
   1.284 +#define SDL_RLEACCEL        0x00000020  /* Surface is RLE encoded */
   1.285 +
   1.286 +/* Evaluates to true if the surface needs to be locked before access */
   1.287 +#define SDL_MUSTLOCK(S)	(((S)->flags & (SDL_HWSURFACE|SDL_RLEACCEL)) != 0)
   1.288  
   1.289  /* This structure should be treated as read-only, except for 'pixels',
   1.290     which, if not NULL, contains the raw pixel data for the surface.
   1.291  */
   1.292 -typedef struct SDL_Surface {
   1.293 -	Uint32 flags;				/* Read-only */
   1.294 -	SDL_PixelFormat *format;		/* Read-only */
   1.295 -	int w, h;				/* Read-only */
   1.296 -	Uint16 pitch;				/* Read-only */
   1.297 -	void *pixels;				/* Read-write */
   1.298 -	int offset;				/* Private */
   1.299 +typedef struct SDL_Surface
   1.300 +{
   1.301 +    Uint32 flags;               /* Read-only */
   1.302 +    SDL_PixelFormat *format;    /* Read-only */
   1.303 +    int w, h;                   /* Read-only */
   1.304 +    int pitch;                  /* Read-only */
   1.305 +    void *pixels;               /* Read-write */
   1.306  
   1.307 -	/* Hardware-specific surface info */
   1.308 -	struct private_hwdata *hwdata;
   1.309 +    /* texture associated with the surface, if any */
   1.310 +    SDL_TextureID textureID;
   1.311  
   1.312 -	/* clipping information */
   1.313 -	SDL_Rect clip_rect;			/* Read-only */
   1.314 -	Uint32 unused1;				/* for binary compatibility */
   1.315 +    /* information needed for surfaces requiring locks */
   1.316 +    int locked;
   1.317 +    void *lock_data;
   1.318  
   1.319 -	/* Allow recursive locks */
   1.320 -	Uint32 locked;				/* Private */
   1.321 +    /* clipping information */
   1.322 +    SDL_Rect clip_rect;         /* Read-only */
   1.323  
   1.324 -	/* info for fast blit mapping to other surfaces */
   1.325 -	struct SDL_BlitMap *map;		/* Private */
   1.326 +    /* info for fast blit mapping to other surfaces */
   1.327 +    struct SDL_BlitMap *map;    /* Private */
   1.328  
   1.329 -	/* format version, bumped at every change to invalidate blit maps */
   1.330 -	unsigned int format_version;		/* Private */
   1.331 +    /* format version, bumped at every change to invalidate blit maps */
   1.332 +    unsigned int format_version;        /* Private */
   1.333  
   1.334 -	/* Reference count -- used when freeing surface */
   1.335 -	int refcount;				/* Read-mostly */
   1.336 +    /* Reference count -- used when freeing surface */
   1.337 +    int refcount;               /* Read-mostly */
   1.338  } SDL_Surface;
   1.339  
   1.340 -/* These are the currently supported flags for the SDL_surface */
   1.341 -/* Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
   1.342 -#define SDL_SWSURFACE	0x00000000	/* Surface is in system memory */
   1.343 -#define SDL_HWSURFACE	0x00000001	/* Surface is in video memory */
   1.344 -#define SDL_ASYNCBLIT	0x00000004	/* Use asynchronous blits if possible */
   1.345 -/* Available for SDL_SetVideoMode() */
   1.346 -#define SDL_ANYFORMAT	0x10000000	/* Allow any video depth/pixel-format */
   1.347 -#define SDL_HWPALETTE	0x20000000	/* Surface has exclusive palette */
   1.348 -#define SDL_DOUBLEBUF	0x40000000	/* Set up double-buffered video mode */
   1.349 -#define SDL_FULLSCREEN	0x80000000	/* Surface is a full screen display */
   1.350 -#define SDL_OPENGL      0x00000002      /* Create an OpenGL rendering context */
   1.351 -#define SDL_OPENGLBLIT	0x0000000A	/* Create an OpenGL rendering context and use it for blitting */
   1.352 -#define SDL_RESIZABLE	0x00000010	/* This video mode may be resized */
   1.353 -#define SDL_NOFRAME	0x00000020	/* No window caption or edge frame */
   1.354 -/* Used internally (read-only) */
   1.355 -#define SDL_HWACCEL	0x00000100	/* Blit uses hardware acceleration */
   1.356 -#define SDL_SRCCOLORKEY	0x00001000	/* Blit uses a source color key */
   1.357 -#define SDL_RLEACCELOK	0x00002000	/* Private flag */
   1.358 -#define SDL_RLEACCEL	0x00004000	/* Surface is RLE encoded */
   1.359 -#define SDL_SRCALPHA	0x00010000	/* Blit uses source alpha blending */
   1.360 -#define SDL_PREALLOC	0x01000000	/* Surface uses preallocated memory */
   1.361 +/* typedef for private surface blitting functions */
   1.362 +typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
   1.363 +                         struct SDL_Surface * dst, SDL_Rect * dstrect);
   1.364  
   1.365 -/* Evaluates to true if the surface needs to be locked before access */
   1.366 -#define SDL_MUSTLOCK(surface)	\
   1.367 -  (surface->offset ||		\
   1.368 -  ((surface->flags & (SDL_HWSURFACE|SDL_ASYNCBLIT|SDL_RLEACCEL)) != 0))
   1.369  
   1.370 -/* typedef for private surface blitting functions */
   1.371 -typedef int (*SDL_blit)(struct SDL_Surface *src, SDL_Rect *srcrect,
   1.372 -			struct SDL_Surface *dst, SDL_Rect *dstrect);
   1.373 -
   1.374 -
   1.375 -/* Useful for determining the video hardware capabilities */
   1.376 -typedef struct SDL_VideoInfo {
   1.377 -	Uint32 hw_available :1;	/* Flag: Can you create hardware surfaces? */
   1.378 -	Uint32 wm_available :1;	/* Flag: Can you talk to a window manager? */
   1.379 -	Uint32 UnusedBits1  :6;
   1.380 -	Uint32 UnusedBits2  :1;
   1.381 -	Uint32 blit_hw      :1;	/* Flag: Accelerated blits HW --> HW */
   1.382 -	Uint32 blit_hw_CC   :1;	/* Flag: Accelerated blits with Colorkey */
   1.383 -	Uint32 blit_hw_A    :1;	/* Flag: Accelerated blits with Alpha */
   1.384 -	Uint32 blit_sw      :1;	/* Flag: Accelerated blits SW --> HW */
   1.385 -	Uint32 blit_sw_CC   :1;	/* Flag: Accelerated blits with Colorkey */
   1.386 -	Uint32 blit_sw_A    :1;	/* Flag: Accelerated blits with Alpha */
   1.387 -	Uint32 blit_fill    :1;	/* Flag: Accelerated color fill */
   1.388 -	Uint32 UnusedBits3  :16;
   1.389 -	Uint32 video_mem;	/* The total amount of video memory (in K) */
   1.390 -	SDL_PixelFormat *vfmt;	/* Value: The format of the video surface */
   1.391 -	int    current_w;	/* Value: The current video mode width */
   1.392 -	int    current_h;	/* Value: The current video mode height */
   1.393 -} SDL_VideoInfo;
   1.394 -
   1.395 -
   1.396 -/* The most common video overlay formats.
   1.397 -   For an explanation of these pixel formats, see:
   1.398 -	http://www.webartz.com/fourcc/indexyuv.htm
   1.399 -
   1.400 -   For information on the relationship between color spaces, see:
   1.401 -   http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
   1.402 +/**
   1.403 + * \enum SDL_GLattr
   1.404 + *
   1.405 + * \brief OpenGL configuration attributes
   1.406   */
   1.407 -#define SDL_YV12_OVERLAY  0x32315659	/* Planar mode: Y + V + U  (3 planes) */
   1.408 -#define SDL_IYUV_OVERLAY  0x56555949	/* Planar mode: Y + U + V  (3 planes) */
   1.409 -#define SDL_YUY2_OVERLAY  0x32595559	/* Packed mode: Y0+U0+Y1+V0 (1 plane) */
   1.410 -#define SDL_UYVY_OVERLAY  0x59565955	/* Packed mode: U0+Y0+V0+Y1 (1 plane) */
   1.411 -#define SDL_YVYU_OVERLAY  0x55595659	/* Packed mode: Y0+V0+Y1+U0 (1 plane) */
   1.412 -
   1.413 -/* The YUV hardware video overlay */
   1.414 -typedef struct SDL_Overlay {
   1.415 -	Uint32 format;				/* Read-only */
   1.416 -	int w, h;				/* Read-only */
   1.417 -	int planes;				/* Read-only */
   1.418 -	Uint16 *pitches;			/* Read-only */
   1.419 -	Uint8 **pixels;				/* Read-write */
   1.420 -
   1.421 -	/* Hardware-specific surface info */
   1.422 -	struct private_yuvhwfuncs *hwfuncs;
   1.423 -	struct private_yuvhwdata *hwdata;
   1.424 -
   1.425 -	/* Special flags */
   1.426 -	Uint32 hw_overlay :1;	/* Flag: This overlay hardware accelerated? */
   1.427 -	Uint32 UnusedBits :31;
   1.428 -} SDL_Overlay;
   1.429 -
   1.430 -
   1.431 -/* Public enumeration for setting the OpenGL window attributes. */
   1.432 -typedef enum {
   1.433 +typedef enum
   1.434 +{
   1.435      SDL_GL_RED_SIZE,
   1.436      SDL_GL_GREEN_SIZE,
   1.437      SDL_GL_BLUE_SIZE,
   1.438 @@ -214,258 +322,854 @@
   1.439      SDL_GL_STEREO,
   1.440      SDL_GL_MULTISAMPLEBUFFERS,
   1.441      SDL_GL_MULTISAMPLESAMPLES,
   1.442 -    SDL_GL_ACCELERATED_VISUAL,
   1.443 -    SDL_GL_SWAP_CONTROL
   1.444 +    SDL_GL_ACCELERATED_VISUAL
   1.445  } SDL_GLattr;
   1.446  
   1.447 -/* flags for SDL_SetPalette() */
   1.448 -#define SDL_LOGPAL 0x01
   1.449 -#define SDL_PHYSPAL 0x02
   1.450  
   1.451  /* Function prototypes */
   1.452  
   1.453 -/* These functions are used internally, and should not be used unless you
   1.454 - * have a specific need to specify the video driver you want to use.
   1.455 - * You should normally use SDL_Init() or SDL_InitSubSystem().
   1.456 +/**
   1.457 + * \fn int SDL_GetNumVideoDrivers(void)
   1.458   *
   1.459 - * SDL_VideoInit() initializes the video subsystem -- sets up a connection
   1.460 - * to the window manager, etc, and determines the current video mode and
   1.461 - * pixel format, but does not initialize a window or graphics mode.
   1.462 - * Note that event handling is activated by this routine.
   1.463 + * \brief Get the number of video drivers compiled into SDL
   1.464   *
   1.465 - * If you use both sound and video in your application, you need to call
   1.466 - * SDL_Init() before opening the sound device, otherwise under Win32 DirectX,
   1.467 - * you won't be able to set full-screen display modes.
   1.468 + * \sa SDL_GetVideoDriver()
   1.469   */
   1.470 -extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name, Uint32 flags);
   1.471 +extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
   1.472 +
   1.473 +/**
   1.474 + * \fn const char *SDL_GetVideoDriver(int index)
   1.475 + *
   1.476 + * \brief Get the name of a built in video driver.
   1.477 + *
   1.478 + * \note The video drivers are presented in the order in which they are
   1.479 + * normally checked during initialization.
   1.480 + *
   1.481 + * \sa SDL_GetNumVideoDrivers()
   1.482 + */
   1.483 +extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
   1.484 +
   1.485 +/**
   1.486 + * \fn int SDL_VideoInit(const char *driver_name, Uint32 flags)
   1.487 + *
   1.488 + * \brief Initialize the video subsystem, optionally specifying a video driver.
   1.489 + *
   1.490 + * \param driver_name Initialize a specific driver by name, or NULL for the default video driver.
   1.491 + * \param flags FIXME: Still needed?
   1.492 + *
   1.493 + * \return 0 on success, -1 on error
   1.494 + *
   1.495 + * This function initializes the video subsystem; setting up a connection
   1.496 + * to the window manager, etc, and determines the available display modes
   1.497 + * and pixel formats, but does not initialize a window or graphics mode.
   1.498 + *
   1.499 + * \sa SDL_VideoQuit()
   1.500 + */
   1.501 +extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name,
   1.502 +                                          Uint32 flags);
   1.503 +
   1.504 +/**
   1.505 + * \fn void SDL_VideoQuit(void)
   1.506 + *
   1.507 + * \brief Shuts down the video subsystem.
   1.508 + *
   1.509 + * This function closes all windows, and restores the original video mode.
   1.510 + *
   1.511 + * \sa SDL_VideoInit()
   1.512 + */
   1.513  extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
   1.514  
   1.515 -/* This function fills the given character buffer with the name of the
   1.516 - * video driver, and returns a pointer to it if the video driver has
   1.517 - * been initialized.  It returns NULL if no driver has been initialized.
   1.518 +/**
   1.519 + * \fn const char *SDL_GetCurrentVideoDriver(void)
   1.520 + *
   1.521 + * \brief Returns the name of the currently initialized video driver.
   1.522 + *
   1.523 + * \return The name of the current video driver or NULL if no driver
   1.524 + *         has been initialized
   1.525 + *
   1.526 + * \sa SDL_GetNumVideoDrivers()
   1.527 + * \sa SDL_GetVideoDriver()
   1.528   */
   1.529 -extern DECLSPEC char * SDLCALL SDL_VideoDriverName(char *namebuf, int maxlen);
   1.530 +extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);
   1.531  
   1.532 -/*
   1.533 - * This function returns a pointer to the current display surface.
   1.534 - * If SDL is doing format conversion on the display surface, this
   1.535 - * function returns the publicly visible surface, not the real video
   1.536 - * surface.
   1.537 +/**
   1.538 + * \fn int SDL_GetNumVideoDisplays(void)
   1.539 + *
   1.540 + * \brief Returns the number of available video displays.
   1.541 + *
   1.542 + * \sa SDL_SelectVideoDisplay()
   1.543   */
   1.544 -extern DECLSPEC SDL_Surface * SDLCALL SDL_GetVideoSurface(void);
   1.545 +extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void);
   1.546  
   1.547 -/*
   1.548 - * This function returns a read-only pointer to information about the
   1.549 - * video hardware.  If this is called before SDL_SetVideoMode(), the 'vfmt'
   1.550 - * member of the returned structure will contain the pixel format of the
   1.551 - * "best" video mode.
   1.552 +/**
   1.553 + * \fn int SDL_SelectVideoDisplay(int index)
   1.554 + *
   1.555 + * \brief Set the index of the currently selected display.
   1.556 + *
   1.557 + * \return The index of the currently selected display.
   1.558 + *
   1.559 + * \note You can query the currently selected display by passing an index of -1.
   1.560 + *
   1.561 + * \sa SDL_GetNumVideoDisplays()
   1.562   */
   1.563 -extern DECLSPEC const SDL_VideoInfo * SDLCALL SDL_GetVideoInfo(void);
   1.564 +extern DECLSPEC int SDLCALL SDL_SelectVideoDisplay(int index);
   1.565  
   1.566 -/* 
   1.567 - * Check to see if a particular video mode is supported.
   1.568 - * It returns 0 if the requested mode is not supported under any bit depth,
   1.569 - * or returns the bits-per-pixel of the closest available mode with the
   1.570 - * given width and height.  If this bits-per-pixel is different from the
   1.571 - * one used when setting the video mode, SDL_SetVideoMode() will succeed,
   1.572 - * but will emulate the requested bits-per-pixel with a shadow surface.
   1.573 +/**
   1.574 + * \fn int SDL_GetNumDisplayModes(void)
   1.575   *
   1.576 - * The arguments to SDL_VideoModeOK() are the same ones you would pass to
   1.577 - * SDL_SetVideoMode()
   1.578 + * \brief Returns the number of available display modes for the current display.
   1.579 + *
   1.580 + * \sa SDL_GetDisplayMode()
   1.581   */
   1.582 -extern DECLSPEC int SDLCALL SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags);
   1.583 +extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(void);
   1.584  
   1.585 -/*
   1.586 - * Return a pointer to an array of available screen dimensions for the
   1.587 - * given format and video flags, sorted largest to smallest.  Returns 
   1.588 - * NULL if there are no dimensions available for a particular format, 
   1.589 - * or (SDL_Rect **)-1 if any dimension is okay for the given format.
   1.590 +/**
   1.591 + * \fn const SDL_DisplayMode *SDL_GetDisplayMode(int index)
   1.592   *
   1.593 - * If 'format' is NULL, the mode list will be for the format given 
   1.594 - * by SDL_GetVideoInfo()->vfmt
   1.595 + * \brief Retrieve information about a specific display mode.
   1.596 + *
   1.597 + * \note The display modes are sorted in this priority:
   1.598 + *       \li bits per pixel -> more colors to fewer colors
   1.599 + *       \li width -> largest to smallest
   1.600 + *       \li height -> largest to smallest
   1.601 + *       \li refresh rate -> highest to lowest
   1.602 + *
   1.603 + * \sa SDL_GetNumDisplayModes()
   1.604   */
   1.605 -extern DECLSPEC SDL_Rect ** SDLCALL SDL_ListModes(SDL_PixelFormat *format, Uint32 flags);
   1.606 +extern DECLSPEC const SDL_DisplayMode *SDLCALL SDL_GetDisplayMode(int index);
   1.607  
   1.608 -/*
   1.609 - * Set up a video mode with the specified width, height and bits-per-pixel.
   1.610 +/**
   1.611 + * \fn const SDL_DisplayMode *SDL_GetDesktopDisplayMode(void)
   1.612   *
   1.613 - * If 'bpp' is 0, it is treated as the current display bits per pixel.
   1.614 + * \brief Retrieve information about the desktop display mode for the current display.
   1.615 + */
   1.616 +extern DECLSPEC const SDL_DisplayMode *SDLCALL
   1.617 +SDL_GetDesktopDisplayMode(void);
   1.618 +
   1.619 +/**
   1.620 + * \fn const SDL_DisplayMode *SDL_GetCurrentDisplayMode(void)
   1.621   *
   1.622 - * If SDL_ANYFORMAT is set in 'flags', the SDL library will try to set the
   1.623 - * requested bits-per-pixel, but will return whatever video pixel format is
   1.624 - * available.  The default is to emulate the requested pixel format if it
   1.625 - * is not natively available.
   1.626 + * \brief Retrieve information about the current display mode.
   1.627 + */
   1.628 +extern DECLSPEC const SDL_DisplayMode *SDLCALL
   1.629 +SDL_GetCurrentDisplayMode(void);
   1.630 +
   1.631 +/**
   1.632 + * \fn SDL_DisplayMode *SDL_GetClosestDisplayMode(const SDL_DisplayMode *mode, SDL_DisplayMode *closest)
   1.633   *
   1.634 - * If SDL_HWSURFACE is set in 'flags', the video surface will be placed in
   1.635 - * video memory, if possible, and you may have to call SDL_LockSurface()
   1.636 - * in order to access the raw framebuffer.  Otherwise, the video surface
   1.637 - * will be created in system memory.
   1.638 + * \brief Get the closest match to the requested display mode.
   1.639   *
   1.640 - * If SDL_ASYNCBLIT is set in 'flags', SDL will try to perform rectangle
   1.641 - * updates asynchronously, but you must always lock before accessing pixels.
   1.642 - * SDL will wait for updates to complete before returning from the lock.
   1.643 + * \param mode The desired display mode
   1.644 + * \param closest A pointer to a display mode to be filled in with the closest match of the available display modes.
   1.645   *
   1.646 - * If SDL_HWPALETTE is set in 'flags', the SDL library will guarantee
   1.647 - * that the colors set by SDL_SetColors() will be the colors you get.
   1.648 - * Otherwise, in 8-bit mode, SDL_SetColors() may not be able to set all
   1.649 - * of the colors exactly the way they are requested, and you should look
   1.650 - * at the video surface structure to determine the actual palette.
   1.651 - * If SDL cannot guarantee that the colors you request can be set, 
   1.652 - * i.e. if the colormap is shared, then the video surface may be created
   1.653 - * under emulation in system memory, overriding the SDL_HWSURFACE flag.
   1.654 + * \return The passed in value 'closest', or NULL if no matching video mode was available.
   1.655   *
   1.656 - * If SDL_FULLSCREEN is set in 'flags', the SDL library will try to set
   1.657 - * a fullscreen video mode.  The default is to create a windowed mode
   1.658 - * if the current graphics system has a window manager.
   1.659 - * If the SDL library is able to set a fullscreen video mode, this flag 
   1.660 - * will be set in the surface that is returned.
   1.661 + * 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.
   1.662   *
   1.663 - * If SDL_DOUBLEBUF is set in 'flags', the SDL library will try to set up
   1.664 - * two surfaces in video memory and swap between them when you call 
   1.665 - * SDL_Flip().  This is usually slower than the normal single-buffering
   1.666 - * scheme, but prevents "tearing" artifacts caused by modifying video 
   1.667 - * memory while the monitor is refreshing.  It should only be used by 
   1.668 - * applications that redraw the entire screen on every update.
   1.669 + * \sa SDL_GetNumDisplayModes()
   1.670 + * \sa SDL_GetDisplayMode()
   1.671 + */
   1.672 +extern DECLSPEC SDL_DisplayMode *SDLCALL SDL_GetClosestDisplayMode(const
   1.673 +                                                                   SDL_DisplayMode
   1.674 +                                                                   * mode,
   1.675 +                                                                   SDL_DisplayMode
   1.676 +                                                                   * closest);
   1.677 +
   1.678 +/**
   1.679 + * \fn int SDL_SetFullscreenDisplayMode(const SDL_DisplayMode *mode)
   1.680   *
   1.681 - * If SDL_RESIZABLE is set in 'flags', the SDL library will allow the
   1.682 - * window manager, if any, to resize the window at runtime.  When this
   1.683 - * occurs, SDL will send a SDL_VIDEORESIZE event to you application,
   1.684 - * and you must respond to the event by re-calling SDL_SetVideoMode()
   1.685 - * with the requested size (or another size that suits the application).
   1.686 + * \brief Set the display mode used when a fullscreen window is visible
   1.687 + *        on the currently selected display.
   1.688   *
   1.689 - * If SDL_NOFRAME is set in 'flags', the SDL library will create a window
   1.690 - * without any title bar or frame decoration.  Fullscreen video modes have
   1.691 - * this flag set automatically.
   1.692 + * \param mode The mode to use, or NULL for the desktop mode.
   1.693   *
   1.694 - * This function returns the video framebuffer surface, or NULL if it fails.
   1.695 + * \return 0 on success, or -1 if setting the display mode failed.
   1.696   *
   1.697 - * If you rely on functionality provided by certain video flags, check the
   1.698 - * flags of the returned surface to make sure that functionality is available.
   1.699 - * SDL will fall back to reduced functionality if the exact flags you wanted
   1.700 - * are not available.
   1.701 + * \sa SDL_SetWindowFullscreen()
   1.702   */
   1.703 -extern DECLSPEC SDL_Surface * SDLCALL SDL_SetVideoMode
   1.704 -			(int width, int height, int bpp, Uint32 flags);
   1.705 +extern DECLSPEC int SDLCALL SDL_SetFullscreenDisplayMode(const SDL_DisplayMode
   1.706 +                                                         * mode);
   1.707  
   1.708 -/*
   1.709 - * Makes sure the given list of rectangles is updated on the given screen.
   1.710 - * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
   1.711 - * screen.
   1.712 - * These functions should not be called while 'screen' is locked.
   1.713 +/**
   1.714 + * \fn const SDL_DisplayMode *SDL_GetFullscreenDisplayMode(void)
   1.715 + *
   1.716 + * \brief Query the display mode used when a fullscreen window is visible
   1.717 + *        on the currently selected display.
   1.718   */
   1.719 -extern DECLSPEC void SDLCALL SDL_UpdateRects
   1.720 -		(SDL_Surface *screen, int numrects, SDL_Rect *rects);
   1.721 -extern DECLSPEC void SDLCALL SDL_UpdateRect
   1.722 -		(SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
   1.723 +extern DECLSPEC const SDL_DisplayMode *SDLCALL
   1.724 +SDL_GetFullscreenDisplayMode(void);
   1.725  
   1.726 -/*
   1.727 - * On hardware that supports double-buffering, this function sets up a flip
   1.728 - * and returns.  The hardware will wait for vertical retrace, and then swap
   1.729 - * video buffers before the next video surface blit or lock will return.
   1.730 - * On hardware that doesn not support double-buffering, this is equivalent
   1.731 - * to calling SDL_UpdateRect(screen, 0, 0, 0, 0);
   1.732 - * The SDL_DOUBLEBUF flag must have been passed to SDL_SetVideoMode() when
   1.733 - * setting the video mode for this function to perform hardware flipping.
   1.734 - * This function returns 0 if successful, or -1 if there was an error.
   1.735 +/**
   1.736 + * \fn int SDL_SetDisplayPalette(const SDL_Color *colors, int firstcolor, int ncolors)
   1.737 + *
   1.738 + * \brief Set the palette entries for indexed display modes.
   1.739 + *
   1.740 + * \return 0 on success, or -1 if the display mode isn't palettized or the colors couldn't be set.
   1.741   */
   1.742 -extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface *screen);
   1.743 +extern DECLSPEC int SDLCALL SDL_SetDisplayPalette(const SDL_Color * colors,
   1.744 +                                                  int firstcolor,
   1.745 +                                                  int ncolors);
   1.746  
   1.747 -/*
   1.748 - * Set the gamma correction for each of the color channels.
   1.749 - * The gamma values range (approximately) between 0.1 and 10.0
   1.750 - * 
   1.751 - * If this function isn't supported directly by the hardware, it will
   1.752 - * be emulated using gamma ramps, if available.  If successful, this
   1.753 - * function returns 0, otherwise it returns -1.
   1.754 +/**
   1.755 + * \fn int SDL_GetDisplayPalette(SDL_Color *colors, int firstcolor, int ncolors)
   1.756 + *
   1.757 + * \brief Gets the palette entries for indexed display modes.
   1.758 + *
   1.759 + * \return 0 on success, or -1 if the display mode isn't palettized
   1.760 + */
   1.761 +extern DECLSPEC int SDLCALL SDL_GetDisplayPalette(SDL_Color * colors,
   1.762 +                                                  int firstcolor,
   1.763 +                                                  int ncolors);
   1.764 +
   1.765 +/**
   1.766 + * \fn int SDL_SetGamma(float red, float green, float blue)
   1.767 + *
   1.768 + * \brief Set the gamma correction for each of the color channels on the currently selected display.
   1.769 + *
   1.770 + * \return 0 on success, or -1 if setting the gamma isn't supported.
   1.771 + *
   1.772 + * \sa SDL_SetGammaRamp()
   1.773   */
   1.774  extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
   1.775  
   1.776 -/*
   1.777 +/**
   1.778 + * \fn int SDL_SetGammaRamp(const Uint16 * red, const Uint16 * green, const Uint16 * blue)
   1.779 + *
   1.780 + * \brief Set the gamma ramp for the currently selected display.
   1.781 + *
   1.782 + * \param red The translation table for the red channel, or NULL
   1.783 + * \param green The translation table for the green channel, or NULL
   1.784 + * \param blue The translation table for the blue channel, or NULL
   1.785 + *
   1.786 + * \return 0 on success, or -1 if gamma ramps are unsupported.
   1.787 + *
   1.788   * Set the gamma translation table for the red, green, and blue channels
   1.789   * of the video hardware.  Each table is an array of 256 16-bit quantities,
   1.790   * representing a mapping between the input and output for that channel.
   1.791   * The input is the index into the array, and the output is the 16-bit
   1.792   * gamma value at that index, scaled to the output color precision.
   1.793   * 
   1.794 - * You may pass NULL for any of the channels to leave it unchanged.
   1.795 - * If the call succeeds, it will return 0.  If the display driver or
   1.796 - * hardware does not support gamma translation, or otherwise fails,
   1.797 - * this function will return -1.
   1.798 + * \sa SDL_GetGammaRamp()
   1.799   */
   1.800 -extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 *red, const Uint16 *green, const Uint16 *blue);
   1.801 +extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 * red,
   1.802 +                                             const Uint16 * green,
   1.803 +                                             const Uint16 * blue);
   1.804  
   1.805 -/*
   1.806 - * Retrieve the current values of the gamma translation tables.
   1.807 +/**
   1.808 + * \fn int SDL_GetGammaRamp(Uint16 * red, Uint16 * green, Uint16 * blue)
   1.809 + *
   1.810 + * \brief Get the gamma ramp for the currently selected display.
   1.811 + *
   1.812 + * \param red A pointer to a 256 element array of 16-bit quantities to hold the translation table for the red channel, or NULL.
   1.813 + * \param green A pointer to a 256 element array of 16-bit quantities to hold the translation table for the green channel, or NULL.
   1.814 + * \param blue A pointer to a 256 element array of 16-bit quantities to hold the translation table for the blue channel, or NULL.
   1.815   * 
   1.816 - * You must pass in valid pointers to arrays of 256 16-bit quantities.
   1.817 - * Any of the pointers may be NULL to ignore that channel.
   1.818 - * If the call succeeds, it will return 0.  If the display driver or
   1.819 - * hardware does not support gamma translation, or otherwise fails,
   1.820 - * this function will return -1.
   1.821 + * \return 0 on success, or -1 if gamma ramps are unsupported.
   1.822 + *
   1.823 + * \sa SDL_SetGammaRamp()
   1.824   */
   1.825 -extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
   1.826 +extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 * red, Uint16 * green,
   1.827 +                                             Uint16 * blue);
   1.828  
   1.829 -/*
   1.830 - * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
   1.831 - * is not a palettized surface, this function does nothing, returning 0.
   1.832 - * If all of the colors were set as passed to SDL_SetColors(), it will
   1.833 - * return 1.  If not all the color entries were set exactly as given,
   1.834 - * it will return 0, and you should look at the surface palette to
   1.835 - * determine the actual color palette.
   1.836 +
   1.837 +/**
   1.838 + * \fn SDL_WindowID SDL_CreateWindow(const char *title, int x, int y, int w, int h, Uint32 flags)
   1.839   *
   1.840 - * When 'surface' is the surface associated with the current display, the
   1.841 - * display colormap will be updated with the requested colors.  If 
   1.842 - * SDL_HWPALETTE was set in SDL_SetVideoMode() flags, SDL_SetColors()
   1.843 - * will always return 1, and the palette is guaranteed to be set the way
   1.844 - * you desire, even if the window colormap has to be warped or run under
   1.845 - * emulation.
   1.846 + * \brief Create a window with the specified position, dimensions, and flags.
   1.847 + *
   1.848 + * \param title The title of the window
   1.849 + * \param x The x position of the window
   1.850 + * \param y The y position of the window
   1.851 + * \param w The width of the window
   1.852 + * \param h The height of the window
   1.853 + * \param flags The flags for the window, a mask of any of the following: SDL_WINDOW_FULLSCREEN, SDL_WINDOW_OPENGL, SDL_WINDOW_SHOWN, SDL_WINDOW_BORDERLESS, SDL_WINDOW_RESIZABLE, SDL_WINDOW_MAXIMIZED, SDL_WINDOW_MINIMIZED, SDL_WINDOW_INPUT_GRABBED
   1.854 + *
   1.855 + * \return The id of the window created, or zero if window creation failed.
   1.856 + *
   1.857 + * \note Setting the position to -1, -1, indicates any position is fine.
   1.858 + *
   1.859 + * \sa SDL_DestroyWindow()
   1.860   */
   1.861 -extern DECLSPEC int SDLCALL SDL_SetColors(SDL_Surface *surface, 
   1.862 -			SDL_Color *colors, int firstcolor, int ncolors);
   1.863 +extern DECLSPEC SDL_WindowID SDLCALL SDL_CreateWindow(const char *title,
   1.864 +                                                      int x, int y, int w,
   1.865 +                                                      int h, Uint32 flags);
   1.866  
   1.867 -/*
   1.868 - * Sets a portion of the colormap for a given 8-bit surface.
   1.869 - * 'flags' is one or both of:
   1.870 - * SDL_LOGPAL  -- set logical palette, which controls how blits are mapped
   1.871 - *                to/from the surface,
   1.872 - * SDL_PHYSPAL -- set physical palette, which controls how pixels look on
   1.873 - *                the screen
   1.874 - * Only screens have physical palettes. Separate change of physical/logical
   1.875 - * palettes is only possible if the screen has SDL_HWPALETTE set.
   1.876 +/**
   1.877 + * \fn SDL_WindowID SDL_CreateWindowFrom(void *data)
   1.878   *
   1.879 - * The return value is 1 if all colours could be set as requested, and 0
   1.880 - * otherwise.
   1.881 + * \brief Create an SDL window struct from an existing native window.
   1.882   *
   1.883 - * SDL_SetColors() is equivalent to calling this function with
   1.884 - *     flags = (SDL_LOGPAL|SDL_PHYSPAL).
   1.885 + * \param data A pointer to driver-dependent window creation data
   1.886 + *
   1.887 + * \return The id of the window created, or zero if window creation failed.
   1.888 + *
   1.889 + * \warning This function is NOT SUPPORTED, use at your own risk!
   1.890 + *
   1.891 + * \sa SDL_DestroyWindow()
   1.892   */
   1.893 -extern DECLSPEC int SDLCALL SDL_SetPalette(SDL_Surface *surface, int flags,
   1.894 -				   SDL_Color *colors, int firstcolor,
   1.895 -				   int ncolors);
   1.896 +extern DECLSPEC SDL_WindowID SDLCALL SDL_CreateWindowFrom(const void *data);
   1.897 +
   1.898 +/**
   1.899 + * \fn Uint32 SDL_GetWindowFlags(SDL_WindowID windowID)
   1.900 + *
   1.901 + * \brief Get the window flags.
   1.902 + */
   1.903 +extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_WindowID windowID);
   1.904 +
   1.905 +/**
   1.906 + * \fn void SDL_SetWindowTitle(SDL_WindowID windowID, const char *title)
   1.907 + *
   1.908 + * \brief Set the title of the window, in UTF-8 format.
   1.909 + *
   1.910 + * \sa SDL_GetWindowTitle()
   1.911 + */
   1.912 +extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_WindowID windowID,
   1.913 +                                                const char *title);
   1.914 +
   1.915 +/**
   1.916 + * \fn const char *SDL_GetWindowTitle(SDL_WindowID windowID)
   1.917 + *
   1.918 + * \brief Get the title of the window, in UTF-8 format.
   1.919 + *
   1.920 + * \sa SDL_SetWindowTitle()
   1.921 + */
   1.922 +extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_WindowID windowID);
   1.923 +
   1.924 +/**
   1.925 + * \fn void SDL_SetWindowIcon(SDL_Surface *icon)
   1.926 + *
   1.927 + * \brief Set the icon of the window.
   1.928 + *
   1.929 + * \param icon The icon for the window
   1.930 + *
   1.931 + * FIXME: The icon needs to be set before the window is first shown.  Should some icon representation be part of the window creation data?
   1.932 + */
   1.933 +extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Surface * icon);
   1.934 +
   1.935 +/**
   1.936 + * \fn void SDL_SetWindowData(SDL_WindowID windowID, void *userdata)
   1.937 + *
   1.938 + * \brief Associate an arbitrary pointer with the window.
   1.939 + *
   1.940 + * \sa SDL_GetWindowData()
   1.941 + */
   1.942 +extern DECLSPEC void SDLCALL SDL_SetWindowData(SDL_WindowID windowID,
   1.943 +                                               void *userdata);
   1.944 +
   1.945 +/**
   1.946 + * \fn void *SDL_GetWindowData(SDL_WindowID windowID)
   1.947 + *
   1.948 + * \brief Retrieve the data pointer associated with the window.
   1.949 + *
   1.950 + * \sa SDL_SetWindowData()
   1.951 + */
   1.952 +extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_WindowID windowID);
   1.953 +
   1.954 +/**
   1.955 + * \fn void SDL_SetWindowPosition(SDL_WindowID windowID, int x, int y)
   1.956 + *
   1.957 + * \brief Set the position of the window.
   1.958 + *
   1.959 + * \param windowID The window to reposition
   1.960 + * \param x The x coordinate of the window, SDL_WINDOWPOS_CENTERED, or SDL_WINDOWPOS_UNDEFINED
   1.961 + * \param y The y coordinate of the window, SDL_WINDOWPOS_CENTERED, or SDL_WINDOWPOS_UNDEFINED
   1.962 + *
   1.963 + * \note The window coordinate origin is the upper left of the display.
   1.964 + *
   1.965 + * \sa SDL_GetWindowPosition()
   1.966 + */
   1.967 +extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_WindowID windowID,
   1.968 +                                                   int x, int y);
   1.969 +
   1.970 +/**
   1.971 + * \fn void SDL_GetWindowPosition(SDL_WindowID windowID, int *x, int *y)
   1.972 + *
   1.973 + * \brief Get the position of the window.
   1.974 + *
   1.975 + * \sa SDL_SetWindowPosition()
   1.976 + */
   1.977 +extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_WindowID windowID,
   1.978 +                                                   int *x, int *y);
   1.979 +
   1.980 +/**
   1.981 + * \fn void SDL_SetWindowSize(SDL_WindowID windowID, int w, int w)
   1.982 + *
   1.983 + * \brief Set the size of the window's client area.
   1.984 + *
   1.985 + * \note You can't change the size of a fullscreen window, it automatically
   1.986 + * matches the size of the display mode.
   1.987 + *
   1.988 + * \sa SDL_GetWindowSize()
   1.989 + */
   1.990 +extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_WindowID windowID, int w,
   1.991 +                                               int h);
   1.992 +
   1.993 +/**
   1.994 + * \fn void SDL_GetWindowSize(SDL_WindowID windowID, int *w, int *w)
   1.995 + *
   1.996 + * \brief Get the size of the window's client area.
   1.997 + *
   1.998 + * \sa SDL_SetWindowSize()
   1.999 + */
  1.1000 +extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_WindowID windowID, int *w,
  1.1001 +                                               int *h);
  1.1002 +
  1.1003 +/**
  1.1004 + * \fn void SDL_ShowWindow(SDL_WindowID windowID)
  1.1005 + *
  1.1006 + * \brief Show the window
  1.1007 + *
  1.1008 + * \sa SDL_HideWindow()
  1.1009 + */
  1.1010 +extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_WindowID windowID);
  1.1011 +
  1.1012 +/**
  1.1013 + * \fn void SDL_HideWindow(SDL_WindowID windowID)
  1.1014 + *
  1.1015 + * \brief Hide the window
  1.1016 + *
  1.1017 + * \sa SDL_ShowWindow()
  1.1018 + */
  1.1019 +extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_WindowID windowID);
  1.1020 +
  1.1021 +/**
  1.1022 + * \fn void SDL_RaiseWindow(SDL_WindowID windowID)
  1.1023 + *
  1.1024 + * \brief Raise the window above other windows and set the input focus.
  1.1025 + */
  1.1026 +extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_WindowID windowID);
  1.1027 +
  1.1028 +/**
  1.1029 + * \fn void SDL_MaximizeWindow(SDL_WindowID windowID)
  1.1030 + *
  1.1031 + * \brief Make the window as large as possible.
  1.1032 + *
  1.1033 + * \sa SDL_RestoreWindow()
  1.1034 + */
  1.1035 +extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_WindowID windowID);
  1.1036 +
  1.1037 +/**
  1.1038 + * \fn void SDL_MinimizeWindow(SDL_WindowID windowID)
  1.1039 + *
  1.1040 + * \brief Minimize the window to an iconic representation.
  1.1041 + *
  1.1042 + * \sa SDL_RestoreWindow()
  1.1043 + */
  1.1044 +extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_WindowID windowID);
  1.1045 +
  1.1046 +/**
  1.1047 + * \fn void SDL_RestoreWindow(SDL_WindowID windowID)
  1.1048 + *
  1.1049 + * \brief Restore the size and position of a minimized or maximized window.
  1.1050 + *
  1.1051 + * \sa SDL_MaximizeWindow()
  1.1052 + * \sa SDL_MinimizeWindow()
  1.1053 + */
  1.1054 +extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_WindowID windowID);
  1.1055 +
  1.1056 +/**
  1.1057 + * \fn int SDL_SetWindowFullscreen(SDL_WindowID windowID, int fullscreen)
  1.1058 + *
  1.1059 + * \brief Set the window's fullscreen state.
  1.1060 + *
  1.1061 + * \return 0 on success, or -1 if setting the display mode failed.
  1.1062 + *
  1.1063 + * \sa SDL_SetFullscreenDisplayMode()
  1.1064 + */
  1.1065 +extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_WindowID windowID,
  1.1066 +                                                    int fullscreen);
  1.1067 +
  1.1068 +/**
  1.1069 + * \fn void SDL_SetWindowGrab(SDL_WindowID windowID, int mode)
  1.1070 + *
  1.1071 + * \brief Set the window's input grab mode.
  1.1072 + *
  1.1073 + * \param mode This is 1 to grab input, and 0 to release input.
  1.1074 + *
  1.1075 + * \sa SDL_GetWindowGrab()
  1.1076 + */
  1.1077 +extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_WindowID windowID,
  1.1078 +                                               int mode);
  1.1079 +
  1.1080 +/**
  1.1081 + * \fn int SDL_GetWindowGrab(SDL_WindowID windowID)
  1.1082 + *
  1.1083 + * \brief Get the window's input grab mode.
  1.1084 + *
  1.1085 + * \return This returns 1 if input is grabbed, and 0 otherwise.
  1.1086 + *
  1.1087 + * \sa SDL_SetWindowGrab()
  1.1088 + */
  1.1089 +extern DECLSPEC int SDLCALL SDL_GetWindowGrab(SDL_WindowID windowID);
  1.1090 +
  1.1091 +/**
  1.1092 + * \fn SDL_bool SDL_GetWindowWMInfo(SDL_WindowID windowID, struct SDL_SysWMinfo * info)
  1.1093 + *
  1.1094 + * \brief Get driver specific information about a window.
  1.1095 + *
  1.1096 + * \note Include SDL_syswm.h for the declaration of SDL_SysWMinfo.
  1.1097 + */
  1.1098 +struct SDL_SysWMinfo;
  1.1099 +extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowWMInfo(SDL_WindowID windowID,
  1.1100 +                                                     struct SDL_SysWMinfo
  1.1101 +                                                     *info);
  1.1102 +
  1.1103 +/**
  1.1104 + * \fn void SDL_DestroyWindow(SDL_WindowID windowID)
  1.1105 + *
  1.1106 + * \brief Destroy a window.
  1.1107 + */
  1.1108 +extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_WindowID windowID);
  1.1109 +
  1.1110 +/**
  1.1111 + * \fn int SDL_GetNumRenderers(void)
  1.1112 + *
  1.1113 + * \brief Get the number of render managers on the current display.
  1.1114 + *
  1.1115 + * A render manager is a set of code that handles rendering and texture
  1.1116 + * management on a particular display.  Normally there is only one, but
  1.1117 + * some drivers may have several available with different capabilities.
  1.1118 + *
  1.1119 + * \sa SDL_GetRendererInfo()
  1.1120 + * \sa SDL_CreateRenderer()
  1.1121 + */
  1.1122 +extern DECLSPEC int SDLCALL SDL_GetNumRenderers(void);
  1.1123 +
  1.1124 +/**
  1.1125 + * \fn SDL_RendererInfo *SDL_GetRendererInfo(int index)
  1.1126 + *
  1.1127 + * \brief Get information about a specific render manager on the current
  1.1128 + *        display.
  1.1129 + *
  1.1130 + * \sa SDL_CreateRenderer()
  1.1131 + */
  1.1132 +extern DECLSPEC int SDLCALL SDL_GetRendererInfo(int index,
  1.1133 +                                                SDL_RendererInfo * info);
  1.1134 +
  1.1135 +/**
  1.1136 + * \fn int SDL_CreateRenderer(SDL_WindowID window, int index, Uint32 flags)
  1.1137 + *
  1.1138 + * \brief Create and make active a 2D rendering context for a window.
  1.1139 + *
  1.1140 + * \param windowID The window used for rendering
  1.1141 + * \param index The index of the render manager to initialize, or -1 to initialize the first one supporting the requested flags.
  1.1142 + * \param flags SDL_RendererFlags
  1.1143 + *
  1.1144 + * \return 0 on success, -1 if the flags were not supported, or -2 if
  1.1145 + *         there isn't enough memory to support the requested flags
  1.1146 + *
  1.1147 + * \sa SDL_SelectRenderer()
  1.1148 + * \sa SDL_DestroyRenderer()
  1.1149 + */
  1.1150 +extern DECLSPEC int SDLCALL SDL_CreateRenderer(SDL_WindowID windowID,
  1.1151 +                                               int index, Uint32 flags);
  1.1152 +
  1.1153 +/**
  1.1154 + * \fn int SDL_SelectRenderer(SDL_WindowID windowID)
  1.1155 + *
  1.1156 + * \brief Select the rendering context for a particular window.
  1.1157 + *
  1.1158 + * \return 0 on success, -1 if the selected window doesn't have a
  1.1159 + *         rendering context.
  1.1160 + */
  1.1161 +extern DECLSPEC int SDLCALL SDL_SelectRenderer(SDL_WindowID windowID);
  1.1162 +
  1.1163 +/**
  1.1164 + * \fn SDL_TextureID SDL_CreateTexture(Uint32 format, int access, int w, int h)
  1.1165 + *
  1.1166 + * \brief Create a texture for the current rendering context.
  1.1167 + *
  1.1168 + * \param format The format of the texture
  1.1169 + * \param access One of the enumerated values in SDL_TextureAccess
  1.1170 + * \param w The width of the texture in pixels
  1.1171 + * \param h The height of the texture in pixels
  1.1172 + *
  1.1173 + * \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.
  1.1174 + *
  1.1175 + * \sa SDL_QueryTexture()
  1.1176 + * \sa SDL_DestroyTexture()
  1.1177 + */
  1.1178 +extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTexture(Uint32 format,
  1.1179 +                                                        int access, int w,
  1.1180 +                                                        int h);
  1.1181 +
  1.1182 +/**
  1.1183 + * \fn SDL_TextureID SDL_CreateTextureFromSurface(Uint32 format, int access, SDL_Surface *surface)
  1.1184 + *
  1.1185 + * \brief Create a texture from an existing surface.
  1.1186 + *
  1.1187 + * \param format The format of the texture, or 0 to pick an appropriate format
  1.1188 + * \param access One of the enumerated values in SDL_TextureAccess
  1.1189 + * \param surface The surface containing pixel data used to fill the texture
  1.1190 + *
  1.1191 + * \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.
  1.1192 + *
  1.1193 + * \note The surface is not modified or freed by this function.
  1.1194 + *
  1.1195 + * \sa SDL_QueryTexture()
  1.1196 + * \sa SDL_DestroyTexture()
  1.1197 + */
  1.1198 +extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTextureFromSurface(Uint32
  1.1199 +                                                                   format,
  1.1200 +                                                                   int access,
  1.1201 +                                                                   SDL_Surface
  1.1202 +                                                                   * surface);
  1.1203 +
  1.1204 +/**
  1.1205 + * \fn int SDL_QueryTexture(SDL_TextureID textureID, Uint32 *format, int *access, int *w, int *h)
  1.1206 + *
  1.1207 + * \brief Query the attributes of a texture
  1.1208 + *
  1.1209 + * \param texture A texture to be queried
  1.1210 + * \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.
  1.1211 + * \param access A pointer filled in with the actual access to the texture.
  1.1212 + * \param w A pointer filled in with the width of the texture in pixels
  1.1213 + * \param h A pointer filled in with the height of the texture in pixels
  1.1214 + *
  1.1215 + * \return 0 on success, or -1 if the texture is not valid
  1.1216 + */
  1.1217 +extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_TextureID textureID,
  1.1218 +                                             Uint32 * format, int *access,
  1.1219 +                                             int *w, int *h);
  1.1220 +
  1.1221 +/**
  1.1222 + * \fn int SDL_QueryTexturePixels(SDL_TextureID textureID, void **pixels, int pitch)
  1.1223 + *
  1.1224 + * \brief Query the pixels of a texture, if the texture does not need to be locked for pixel access.
  1.1225 + *
  1.1226 + * \param texture A texture to be queried, which was created with SDL_TextureAccess_Local
  1.1227 + * \param pixels A pointer filled with a pointer to the pixels for the texture 
  1.1228 + * \param pitch A pointer filled in with the pitch of the pixel data
  1.1229 + *
  1.1230 + * \return 0 on success, or -1 if the texture is not valid, or must be locked for pixel access.
  1.1231 + */
  1.1232 +extern DECLSPEC int SDLCALL SDL_QueryTexturePixels(SDL_TextureID textureID,
  1.1233 +                                                   void **pixels, int *pitch);
  1.1234 +
  1.1235 +/**
  1.1236 + * \fn int SDL_SetTexturePalette(SDL_TextureID textureID, const SDL_Color * colors, int firstcolor, int ncolors)
  1.1237 + *
  1.1238 + * \brief Update an indexed texture with a color palette
  1.1239 + *
  1.1240 + * \param texture The texture to update
  1.1241 + * \param colors The array of RGB color data
  1.1242 + * \param firstcolor The first index to update
  1.1243 + * \param ncolors The number of palette entries to fill with the color data
  1.1244 + *
  1.1245 + * \return 0 on success, or -1 if the texture is not valid or not an indexed texture
  1.1246 + */
  1.1247 +extern DECLSPEC int SDLCALL SDL_SetTexturePalette(SDL_TextureID textureID,
  1.1248 +                                                  const SDL_Color * colors,
  1.1249 +                                                  int firstcolor,
  1.1250 +                                                  int ncolors);
  1.1251 +
  1.1252 +/**
  1.1253 + * \fn int SDL_GetTexturePalette(SDL_TextureID textureID, SDL_Color * colors, int firstcolor, int ncolors)
  1.1254 + *
  1.1255 + * \brief Update an indexed texture with a color palette
  1.1256 + *
  1.1257 + * \param texture The texture to update
  1.1258 + * \param colors The array to fill with RGB color data
  1.1259 + * \param firstcolor The first index to retrieve
  1.1260 + * \param ncolors The number of palette entries to retrieve
  1.1261 + *
  1.1262 + * \return 0 on success, or -1 if the texture is not valid or not an indexed texture
  1.1263 + */
  1.1264 +extern DECLSPEC int SDLCALL SDL_GetTexturePalette(SDL_TextureID textureID,
  1.1265 +                                                  SDL_Color * colors,
  1.1266 +                                                  int firstcolor,
  1.1267 +                                                  int ncolors);
  1.1268 +
  1.1269 +/**
  1.1270 + * \fn int SDL_UpdateTexture(SDL_TextureID textureID, const SDL_Rect *rect, const void *pixels, int pitch)
  1.1271 + *
  1.1272 + * \brief Update the given texture rectangle with new pixel data.
  1.1273 + *
  1.1274 + * \param texture The texture to update
  1.1275 + * \param rect A pointer to the rectangle of pixels to update, or NULL to update the entire texture.
  1.1276 + * \param pixels The raw pixel data
  1.1277 + * \param pitch The number of bytes between rows of pixel data
  1.1278 + *
  1.1279 + * \return 0 on success, or -1 if the texture is not valid
  1.1280 + *
  1.1281 + * \note This is a very slow function for textures not created with SDL_TextureAccess_Local.
  1.1282 + */
  1.1283 +extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_TextureID textureID,
  1.1284 +                                              const SDL_Rect * rect,
  1.1285 +                                              const void *pixels, int pitch);
  1.1286 +
  1.1287 +/**
  1.1288 + * \fn void SDL_LockTexture(SDL_TextureID textureID, const SDL_Rect *rect, int markDirty, void **pixels, int *pitch)
  1.1289 + *
  1.1290 + * \brief Lock a portion of the texture for pixel access.
  1.1291 + *
  1.1292 + * \param texture The texture to lock for access, which must have been created with SDL_TextureAccess_Local.
  1.1293 + * \param rect A pointer to the rectangle to lock for access. If the rect is NULL, the entire texture will be locked.
  1.1294 + * \param markDirty If this is nonzero, the locked area will be marked dirty when the texture is unlocked.
  1.1295 + * \param pixels This is filled in with a pointer to the locked pixels, appropriately offset by the locked area.
  1.1296 + * \param pitch This is filled in with the pitch of the locked pixels.
  1.1297 + *
  1.1298 + * \return 0 on success, or -1 if the texture is not valid or was created with SDL_TextureAccess_Remote
  1.1299 + *
  1.1300 + * \sa SDL_DirtyTexture()
  1.1301 + * \sa SDL_UnlockTexture()
  1.1302 + */
  1.1303 +extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_TextureID textureID,
  1.1304 +                                            const SDL_Rect * rect,
  1.1305 +                                            int markDirty, void **pixels,
  1.1306 +                                            int *pitch);
  1.1307 +
  1.1308 +/**
  1.1309 + * \fn void SDL_UnlockTexture(SDL_TextureID textureID)
  1.1310 + *
  1.1311 + * \brief Unlock a texture, uploading the changes to video memory, if needed.
  1.1312 + *
  1.1313 + * \sa SDL_LockTexture()
  1.1314 + * \sa SDL_DirtyTexture()
  1.1315 + */
  1.1316 +extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_TextureID textureID);
  1.1317 +
  1.1318 +/**
  1.1319 + * \fn void SDL_DirtyTexture(SDL_TextureID textureID, int numrects, const SDL_Rect * rects)
  1.1320 + *
  1.1321 + * \brief Mark the specified rectangles of the texture as dirty.
  1.1322 + *
  1.1323 + * \note The texture must have been created with SDL_TextureAccess_Local.
  1.1324 + *
  1.1325 + * \sa SDL_LockTexture()
  1.1326 + * \sa SDL_UnlockTexture()
  1.1327 + */
  1.1328 +extern DECLSPEC void SDLCALL SDL_DirtyTexture(SDL_TextureID textureID,
  1.1329 +                                              int numrects,
  1.1330 +                                              const SDL_Rect * rects);
  1.1331 +
  1.1332 +/**
  1.1333 + * \fn void SDL_SelectRenderTexture(SDL_TextureID textureID)
  1.1334 + *
  1.1335 + * \brief Select a texture as the rendering target, or 0 to reselect the current window.
  1.1336 + *
  1.1337 + * \note The texture must have been created with SDL_TextureAccess_Render.
  1.1338 + */
  1.1339 +extern DECLSPEC void SDLCALL SDL_SelectRenderTexture(SDL_TextureID textureID);
  1.1340 +
  1.1341 +/**
  1.1342 + * \fn void SDL_RenderFill(const SDL_Rect *rect, Uint32 color)
  1.1343 + *
  1.1344 + * \brief Fill the current rendering target with the specified color.
  1.1345 + *
  1.1346 + * \param rect A pointer to the destination rectangle, or NULL for the entire rendering target.
  1.1347 + * \param color An ARGB color value.
  1.1348 + *
  1.1349 + * \return 0 on success, or -1 if there is no renderer current
  1.1350 + */
  1.1351 +extern DECLSPEC int SDLCALL SDL_RenderFill(const SDL_Rect * rect,
  1.1352 +                                           Uint32 color);
  1.1353 +
  1.1354 +/**
  1.1355 + * \fn int SDL_RenderCopy(SDL_TextureID textureID, const SDL_Rect *srcrect, const SDL_Rect *dstrect, Uint32 blendMode, Uint32 scaleMode)
  1.1356 + *
  1.1357 + * \brief Copy a portion of the texture to the current rendering target.
  1.1358 + *
  1.1359 + * \param texture The source texture.
  1.1360 + * \param srcrect A pointer to the source rectangle, or NULL for the entire texture.
  1.1361 + * \param dstrect A pointer to the destination rectangle, or NULL for the entire rendering target.
  1.1362 + * \param blendMode SDL_TextureBlendMode to be used if the source texture has an alpha channel.
  1.1363 + * \param scaleMode SDL_TextureScaleMode to be used if the source and destination rectangles don't have the same width and height.
  1.1364 + *
  1.1365 + * \return 0 on success, or -1 if there is no renderer current, or the driver doesn't support the requested operation.
  1.1366 + *
  1.1367 + * \note You can check the video driver info to see what operations are supported.
  1.1368 + */
  1.1369 +extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_TextureID textureID,
  1.1370 +                                           const SDL_Rect * srcrect,
  1.1371 +                                           const SDL_Rect * dstrect,
  1.1372 +                                           int blendMode, int scaleMode);
  1.1373 +
  1.1374 +/**
  1.1375 + * \fn int SDL_RenderReadPixels(const SDL_Rect *rect, void *pixels, int pitch)
  1.1376 + *
  1.1377 + * \brief Read pixels from the current rendering target.
  1.1378 + *
  1.1379 + * \param rect A pointer to the rectangle to read, or NULL for the entire render target
  1.1380 + * \param pixels A pointer to be filled in with the pixel data
  1.1381 + * \param pitch The pitch of the pixels parameter
  1.1382 + *
  1.1383 + * \return 0 on success, or -1 if pixel reading is not supported.
  1.1384 + *
  1.1385 + * \warning This is a very slow operation, and should not be used frequently.
  1.1386 + */
  1.1387 +extern DECLSPEC int SDLCALL SDL_RenderReadPixels(const SDL_Rect * rect,
  1.1388 +                                                 void *pixels, int pitch);
  1.1389 +
  1.1390 +/**
  1.1391 + * \fn int SDL_RenderWritePixels(const SDL_Rect *rect, const void *pixels, int pitch)
  1.1392 + *
  1.1393 + * \brief Write pixels to the current rendering target.
  1.1394 + *
  1.1395 + * \param rect A pointer to the rectangle to write, or NULL for the entire render target
  1.1396 + * \param pixels A pointer to the pixel data to write
  1.1397 + * \param pitch The pitch of the pixels parameter
  1.1398 + *
  1.1399 + * \return 0 on success, or -1 if pixel writing is not supported.
  1.1400 + *
  1.1401 + * \warning This is a very slow operation, and should not be used frequently.
  1.1402 + */
  1.1403 +extern DECLSPEC int SDLCALL SDL_RenderWritePixels(const SDL_Rect * rect,
  1.1404 +                                                  const void *pixels,
  1.1405 +                                                  int pitch);
  1.1406 +
  1.1407 +/**
  1.1408 + * \fn void SDL_RenderPresent(void)
  1.1409 + *
  1.1410 + * \brief Update the screen with rendering performed.
  1.1411 + */
  1.1412 +extern DECLSPEC void SDLCALL SDL_RenderPresent(void);
  1.1413 +
  1.1414 +/**
  1.1415 + * \fn void SDL_DestroyTexture(SDL_TextureID textureID);
  1.1416 + *
  1.1417 + * \brief Destroy the specified texture.
  1.1418 + *
  1.1419 + * \sa SDL_CreateTexture()
  1.1420 + * \sa SDL_CreateTextureFromSurface()
  1.1421 + */
  1.1422 +extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_TextureID textureID);
  1.1423 +
  1.1424 +/**
  1.1425 + * \fn void SDL_DestroyRenderer(SDL_WindowID windowID);
  1.1426 + *
  1.1427 + * \brief Destroy the rendering context for a window and free associated
  1.1428 + *        textures.
  1.1429 + *
  1.1430 + * \sa SDL_CreateRenderer()
  1.1431 + */
  1.1432 +extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_WindowID windowID);
  1.1433  
  1.1434  /*
  1.1435   * Maps an RGB triple to an opaque pixel value for a given pixel format
  1.1436   */
  1.1437  extern DECLSPEC Uint32 SDLCALL SDL_MapRGB
  1.1438 -			(SDL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b);
  1.1439 +    (SDL_PixelFormat * format, Uint8 r, Uint8 g, Uint8 b);
  1.1440  
  1.1441  /*
  1.1442   * Maps an RGBA quadruple to a pixel value for a given pixel format
  1.1443   */
  1.1444 -extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(SDL_PixelFormat *format,
  1.1445 -				   Uint8 r, Uint8 g, Uint8 b, Uint8 a);
  1.1446 +extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(SDL_PixelFormat * format,
  1.1447 +                                           Uint8 r, Uint8 g, Uint8 b,
  1.1448 +                                           Uint8 a);
  1.1449  
  1.1450  /*
  1.1451   * Maps a pixel value into the RGB components for a given pixel format
  1.1452   */
  1.1453 -extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, SDL_PixelFormat *fmt,
  1.1454 -				Uint8 *r, Uint8 *g, Uint8 *b);
  1.1455 +extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, SDL_PixelFormat * fmt,
  1.1456 +                                        Uint8 * r, Uint8 * g, Uint8 * b);
  1.1457  
  1.1458  /*
  1.1459   * Maps a pixel value into the RGBA components for a given pixel format
  1.1460   */
  1.1461 -extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, SDL_PixelFormat *fmt,
  1.1462 -				 Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
  1.1463 +extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, SDL_PixelFormat * fmt,
  1.1464 +                                         Uint8 * r, Uint8 * g, Uint8 * b,
  1.1465 +                                         Uint8 * a);
  1.1466  
  1.1467  /*
  1.1468   * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
  1.1469 @@ -475,40 +1179,36 @@
  1.1470   * If the function runs out of memory, it will return NULL.
  1.1471   *
  1.1472   * The 'flags' tell what kind of surface to create.
  1.1473 - * SDL_SWSURFACE means that the surface should be created in system memory.
  1.1474 - * SDL_HWSURFACE means that the surface should be created in video memory,
  1.1475 - * with the same format as the display surface.  This is useful for surfaces
  1.1476 - * that will not change much, to take advantage of hardware acceleration
  1.1477 - * when being blitted to the display surface.
  1.1478 - * SDL_ASYNCBLIT means that SDL will try to perform asynchronous blits with
  1.1479 - * this surface, but you must always lock it before accessing the pixels.
  1.1480 - * SDL will wait for current blits to finish before returning from the lock.
  1.1481   * SDL_SRCCOLORKEY indicates that the surface will be used for colorkey blits.
  1.1482 - * If the hardware supports acceleration of colorkey blits between
  1.1483 - * two surfaces in video memory, SDL will try to place the surface in
  1.1484 - * video memory. If this isn't possible or if there is no hardware
  1.1485 - * acceleration available, the surface will be placed in system memory.
  1.1486 - * SDL_SRCALPHA means that the surface will be used for alpha blits and 
  1.1487 - * if the hardware supports hardware acceleration of alpha blits between
  1.1488 - * two surfaces in video memory, to place the surface in video memory
  1.1489 - * if possible, otherwise it will be placed in system memory.
  1.1490 - * If the surface is created in video memory, blits will be _much_ faster,
  1.1491 - * but the surface format must be identical to the video surface format,
  1.1492 - * and the only way to access the pixels member of the surface is to use
  1.1493 - * the SDL_LockSurface() and SDL_UnlockSurface() calls.
  1.1494 - * If the requested surface actually resides in video memory, SDL_HWSURFACE
  1.1495 - * will be set in the flags member of the returned surface.  If for some
  1.1496 - * reason the surface could not be placed in video memory, it will not have
  1.1497 - * the SDL_HWSURFACE flag set, and will be created in system memory instead.
  1.1498 + * SDL_SRCALPHA means that the surface will be used for alpha blits.
  1.1499   */
  1.1500 -#define SDL_AllocSurface    SDL_CreateRGBSurface
  1.1501 -extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurface
  1.1502 -			(Uint32 flags, int width, int height, int depth, 
  1.1503 -			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
  1.1504 -extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
  1.1505 -			int width, int height, int depth, int pitch,
  1.1506 -			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
  1.1507 -extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface *surface);
  1.1508 +extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
  1.1509 +    (Uint32 flags, int width, int height, int depth,
  1.1510 +     Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
  1.1511 +extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
  1.1512 +                                                              int width,
  1.1513 +                                                              int height,
  1.1514 +                                                              int depth,
  1.1515 +                                                              int pitch,
  1.1516 +                                                              Uint32 Rmask,
  1.1517 +                                                              Uint32 Gmask,
  1.1518 +                                                              Uint32 Bmask,
  1.1519 +                                                              Uint32 Amask);
  1.1520 +extern DECLSPEC SDL_Surface *SDLCALL
  1.1521 +SDL_CreateRGBSurfaceFromTexture(SDL_TextureID textureID);
  1.1522 +extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
  1.1523 +
  1.1524 +/**
  1.1525 + * \fn int SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette)
  1.1526 + *
  1.1527 + * \brief Set the palette used by a surface.
  1.1528 + *
  1.1529 + * \return 0, or -1 if the surface format doesn't use a palette.
  1.1530 + *
  1.1531 + * \note A single palette can be shared with many surfaces.
  1.1532 + */
  1.1533 +extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
  1.1534 +                                                  SDL_Palette * palette);
  1.1535  
  1.1536  /*
  1.1537   * SDL_LockSurface() sets up a surface for directly accessing the pixels.
  1.1538 @@ -519,17 +1219,15 @@
  1.1539   *
  1.1540   * Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
  1.1541   * to 0, then you can read and write to the surface at any time, and the
  1.1542 - * pixel format of the surface will not change.  In particular, if the
  1.1543 - * SDL_HWSURFACE flag is not given when calling SDL_SetVideoMode(), you
  1.1544 - * will not need to lock the display surface before accessing it.
  1.1545 + * pixel format of the surface will not change.
  1.1546   * 
  1.1547   * No operating system or library calls should be made between lock/unlock
  1.1548   * pairs, as critical system locks may be held during this time.
  1.1549   *
  1.1550   * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
  1.1551   */
  1.1552 -extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface);
  1.1553 -extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
  1.1554 +extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
  1.1555 +extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
  1.1556  
  1.1557  /*
  1.1558   * Load a surface from a seekable SDL data source (memory or file.)
  1.1559 @@ -537,7 +1235,8 @@
  1.1560   * Returns the new surface, or NULL if there was an error.
  1.1561   * The new surface should be freed with SDL_FreeSurface().
  1.1562   */
  1.1563 -extern DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, int freesrc);
  1.1564 +extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
  1.1565 +                                                    int freesrc);
  1.1566  
  1.1567  /* Convenience macro -- load a surface from a file */
  1.1568  #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
  1.1569 @@ -548,7 +1247,7 @@
  1.1570   * Returns 0 if successful or -1 if there was an error.
  1.1571   */
  1.1572  extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
  1.1573 -		(SDL_Surface *surface, SDL_RWops *dst, int freedst);
  1.1574 +    (SDL_Surface * surface, SDL_RWops * dst, int freedst);
  1.1575  
  1.1576  /* Convenience macro -- save a surface to a file */
  1.1577  #define SDL_SaveBMP(surface, file) \
  1.1578 @@ -564,7 +1263,7 @@
  1.1579   * This function returns 0, or -1 if there was an error.
  1.1580   */
  1.1581  extern DECLSPEC int SDLCALL SDL_SetColorKey
  1.1582 -			(SDL_Surface *surface, Uint32 flag, Uint32 key);
  1.1583 +    (SDL_Surface * surface, Uint32 flag, Uint32 key);
  1.1584  
  1.1585  /*
  1.1586   * This function sets the alpha value for the entire surface, as opposed to
  1.1587 @@ -581,7 +1280,8 @@
  1.1588   *
  1.1589   * The 'alpha' parameter is ignored for surfaces that have an alpha channel.
  1.1590   */
  1.1591 -extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);
  1.1592 +extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface * surface, Uint32 flag,
  1.1593 +                                         Uint8 alpha);
  1.1594  
  1.1595  /*
  1.1596   * Sets the clipping rectangle for the destination surface in a blit.
  1.1597 @@ -595,14 +1295,16 @@
  1.1598   * Note that blits are automatically clipped to the edges of the source
  1.1599   * and destination surfaces.
  1.1600   */
  1.1601 -extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface *surface, const SDL_Rect *rect);
  1.1602 +extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
  1.1603 +                                                 const SDL_Rect * rect);
  1.1604  
  1.1605  /*
  1.1606   * Gets the clipping rectangle for the destination surface in a blit.
  1.1607   * 'rect' must be a pointer to a valid rectangle which will be filled
  1.1608   * with the correct values.
  1.1609   */
  1.1610 -extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rect);
  1.1611 +extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
  1.1612 +                                             SDL_Rect * rect);
  1.1613  
  1.1614  /*
  1.1615   * Creates a new surface of the specified format, and then copies and maps 
  1.1616 @@ -616,8 +1318,20 @@
  1.1617   *
  1.1618   * This function is used internally by SDL_DisplayFormat().
  1.1619   */
  1.1620 -extern DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface
  1.1621 -			(SDL_Surface *src, SDL_PixelFormat *fmt, Uint32 flags);
  1.1622 +extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
  1.1623 +    (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags);
  1.1624 +
  1.1625 +/*
  1.1626 + * This function performs a fast fill of the given rectangle with 'color'
  1.1627 + * The given rectangle is clipped to the destination surface clip area
  1.1628 + * and the final fill rectangle is saved in the passed in pointer.
  1.1629 + * If 'dstrect' is NULL, the whole surface will be filled with 'color'
  1.1630 + * The color should be a pixel of the format used by the surface, and 
  1.1631 + * can be generated by the SDL_MapRGB() function.
  1.1632 + * This function returns 0 on success, or -1 on error.
  1.1633 + */
  1.1634 +extern DECLSPEC int SDLCALL SDL_FillRect
  1.1635 +    (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color);
  1.1636  
  1.1637  /*
  1.1638   * This performs a fast blit from the source surface to the destination
  1.1639 @@ -694,196 +1408,177 @@
  1.1640     rectangle validation and clipping before passing it to SDL_LowerBlit()
  1.1641  */
  1.1642  extern DECLSPEC int SDLCALL SDL_UpperBlit
  1.1643 -			(SDL_Surface *src, SDL_Rect *srcrect,
  1.1644 -			 SDL_Surface *dst, SDL_Rect *dstrect);
  1.1645 +    (SDL_Surface * src, SDL_Rect * srcrect,
  1.1646 +     SDL_Surface * dst, SDL_Rect * dstrect);
  1.1647  /* This is a semi-private blit function and it performs low-level surface
  1.1648     blitting only.
  1.1649  */
  1.1650  extern DECLSPEC int SDLCALL SDL_LowerBlit
  1.1651 -			(SDL_Surface *src, SDL_Rect *srcrect,
  1.1652 -			 SDL_Surface *dst, SDL_Rect *dstrect);
  1.1653 +    (SDL_Surface * src, SDL_Rect * srcrect,
  1.1654 +     SDL_Surface * dst, SDL_Rect * dstrect);
  1.1655  
  1.1656 -/*
  1.1657 - * This function performs a fast fill of the given rectangle with 'color'
  1.1658 - * The given rectangle is clipped to the destination surface clip area
  1.1659 - * and the final fill rectangle is saved in the passed in pointer.
  1.1660 - * If 'dstrect' is NULL, the whole surface will be filled with 'color'
  1.1661 - * The color should be a pixel of the format used by the surface, and 
  1.1662 - * can be generated by the SDL_MapRGB() function.
  1.1663 - * This function returns 0 on success, or -1 on error.
  1.1664 +/**
  1.1665 + * \fn int SDL_SoftStretch(SDL_Surface * src, SDL_Rect * srcrect, SDL_Surface * dst, SDL_Rect * dstrect)
  1.1666 + *
  1.1667 + * \brief Perform a fast, low quality, stretch blit between two surfaces of the same pixel format.
  1.1668 + *
  1.1669 + * \note This function uses a static buffer, and is not thread-safe.
  1.1670   */
  1.1671 -extern DECLSPEC int SDLCALL SDL_FillRect
  1.1672 -		(SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color);
  1.1673 -
  1.1674 -/* 
  1.1675 - * This function takes a surface and copies it to a new surface of the
  1.1676 - * pixel format and colors of the video framebuffer, suitable for fast
  1.1677 - * blitting onto the display surface.  It calls SDL_ConvertSurface()
  1.1678 - *
  1.1679 - * If you want to take advantage of hardware colorkey or alpha blit
  1.1680 - * acceleration, you should set the colorkey and alpha value before
  1.1681 - * calling this function.
  1.1682 - *
  1.1683 - * If the conversion fails or runs out of memory, it returns NULL
  1.1684 - */
  1.1685 -extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormat(SDL_Surface *surface);
  1.1686 -
  1.1687 -/* 
  1.1688 - * This function takes a surface and copies it to a new surface of the
  1.1689 - * pixel format and colors of the video framebuffer (if possible),
  1.1690 - * suitable for fast alpha blitting onto the display surface.
  1.1691 - * The new surface will always have an alpha channel.
  1.1692 - *
  1.1693 - * If you want to take advantage of hardware colorkey or alpha blit
  1.1694 - * acceleration, you should set the colorkey and alpha value before
  1.1695 - * calling this function.
  1.1696 - *
  1.1697 - * If the conversion fails or runs out of memory, it returns NULL
  1.1698 - */
  1.1699 -extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormatAlpha(SDL_Surface *surface);
  1.1700 -
  1.1701 -
  1.1702 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  1.1703 -/* YUV video surface overlay functions                                       */
  1.1704 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  1.1705 -
  1.1706 -/* This function creates a video output overlay
  1.1707 -   Calling the returned surface an overlay is something of a misnomer because
  1.1708 -   the contents of the display surface underneath the area where the overlay
  1.1709 -   is shown is undefined - it may be overwritten with the converted YUV data.
  1.1710 -*/
  1.1711 -extern DECLSPEC SDL_Overlay * SDLCALL SDL_CreateYUVOverlay(int width, int height,
  1.1712 -				Uint32 format, SDL_Surface *display);
  1.1713 -
  1.1714 -/* Lock an overlay for direct access, and unlock it when you are done */
  1.1715 -extern DECLSPEC int SDLCALL SDL_LockYUVOverlay(SDL_Overlay *overlay);
  1.1716 -extern DECLSPEC void SDLCALL SDL_UnlockYUVOverlay(SDL_Overlay *overlay);
  1.1717 -
  1.1718 -/* Blit a video overlay to the display surface.
  1.1719 -   The contents of the video surface underneath the blit destination are
  1.1720 -   not defined.  
  1.1721 -   The width and height of the destination rectangle may be different from
  1.1722 -   that of the overlay, but currently only 2x scaling is supported.
  1.1723 -*/
  1.1724 -extern DECLSPEC int SDLCALL SDL_DisplayYUVOverlay(SDL_Overlay *overlay, SDL_Rect *dstrect);
  1.1725 -
  1.1726 -/* Free a video overlay */
  1.1727 -extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay(SDL_Overlay *overlay);
  1.1728 -
  1.1729 +extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
  1.1730 +                                            SDL_Rect * srcrect,
  1.1731 +                                            SDL_Surface * dst,
  1.1732 +                                            SDL_Rect * dstrect);
  1.1733  
  1.1734  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  1.1735  /* OpenGL support functions.                                                 */
  1.1736  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  1.1737  
  1.1738 -/*
  1.1739 - * Dynamically load an OpenGL library, or the default one if path is NULL
  1.1740 +/**
  1.1741 + * \fn int SDL_GL_LoadLibrary(const char *path)
  1.1742   *
  1.1743 - * If you do this, you need to retrieve all of the GL functions used in
  1.1744 - * your program from the dynamic library using SDL_GL_GetProcAddress().
  1.1745 + * \brief Dynamically load an OpenGL library.
  1.1746 + *
  1.1747 + * \param path The platform dependent OpenGL library name, or NULL to open the default OpenGL library
  1.1748 + *
  1.1749 + * \return 0 on success, or -1 if the library couldn't be loaded
  1.1750 + *
  1.1751 + * \note If you do this, you need to retrieve all of the GL functions used in
  1.1752 + *       your program from the dynamic library using SDL_GL_GetProcAddress().
  1.1753 + *
  1.1754 + * \sa SDL_GL_GetProcAddress()
  1.1755   */
  1.1756  extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
  1.1757  
  1.1758 -/*
  1.1759 - * Get the address of a GL function
  1.1760 +/**
  1.1761 + * \fn void *SDL_GL_GetProcAddress(const char *proc)
  1.1762 + *
  1.1763 + * \brief Get the address of an OpenGL function.
  1.1764   */
  1.1765 -extern DECLSPEC void * SDLCALL SDL_GL_GetProcAddress(const char* proc);
  1.1766 +extern DECLSPEC void *SDLCALL SDL_GL_GetProcAddress(const char *proc);
  1.1767  
  1.1768 -/*
  1.1769 - * Set an attribute of the OpenGL subsystem before intialization.
  1.1770 +/**
  1.1771 + * \fn int SDL_GL_SetAttribute(SDL_GLattr attr, int value)
  1.1772 + *
  1.1773 + * \brief Set an OpenGL window attribute before window creation.
  1.1774   */
  1.1775  extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
  1.1776  
  1.1777 -/*
  1.1778 - * Get an attribute of the OpenGL subsystem from the windowing
  1.1779 - * interface, such as glX. This is of course different from getting
  1.1780 - * the values from SDL's internal OpenGL subsystem, which only
  1.1781 - * stores the values you request before initialization.
  1.1782 +/**
  1.1783 + * \fn int SDL_GL_GetWindowAttribute(SDL_WindowID windowID, SDL_GLattr attr, int *value)
  1.1784   *
  1.1785 - * Developers should track the values they pass into SDL_GL_SetAttribute
  1.1786 - * themselves if they want to retrieve these values.
  1.1787 + * \brief Get the actual value for an OpenGL window attribute.
  1.1788   */
  1.1789 -extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int* value);
  1.1790 +extern DECLSPEC int SDLCALL SDL_GL_GetWindowAttribute(SDL_WindowID windowID,
  1.1791 +                                                      SDL_GLattr attr,
  1.1792 +                                                      int *value);
  1.1793  
  1.1794 -/*
  1.1795 +/**
  1.1796 + * \fn SDL_GLContext SDL_GL_CreateContext(SDL_WindowID windowID)
  1.1797 + *
  1.1798 + * \brief Create an OpenGL context for use with an OpenGL window, and make it current.
  1.1799 + *
  1.1800 + * \sa SDL_GL_DeleteContext()
  1.1801 + */
  1.1802 +extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_WindowID
  1.1803 +                                                           windowID);
  1.1804 +
  1.1805 +/**
  1.1806 + * \fn int SDL_GL_MakeCurrent(SDL_WindowID windowID, SDL_GLContext context)
  1.1807 + *
  1.1808 + * \brief Set up an OpenGL context for rendering into an OpenGL window.
  1.1809 + *
  1.1810 + * \note The context must have been created with a compatible window.
  1.1811 + */
  1.1812 +extern DECLSPEC int SDLCALL SDL_GL_MakeCurrent(SDL_WindowID windowID,
  1.1813 +                                               SDL_GLContext context);
  1.1814 +
  1.1815 +/**
  1.1816 + * \fn int SDL_GL_SetSwapInterval(int interval)
  1.1817 + *
  1.1818 + * \brief Set the swap interval for the current OpenGL context.
  1.1819 + *
  1.1820 + * \sa SDL_GL_GetSwapInterval()
  1.1821 + */
  1.1822 +extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval);
  1.1823 +
  1.1824 +/**
  1.1825 + * \fn int SDL_GL_GetSwapInterval(void)
  1.1826 + *
  1.1827 + * \brief Get the swap interval for the current OpenGL context.
  1.1828 + *
  1.1829 + * \sa SDL_GL_SetSwapInterval()
  1.1830 + */
  1.1831 +extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void);
  1.1832 +
  1.1833 +/**
  1.1834 + * \fn void SDL_GL_SwapBuffers(void)
  1.1835 + *
  1.1836   * Swap the OpenGL buffers, if double-buffering is supported.
  1.1837   */
  1.1838  extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers(void);
  1.1839  
  1.1840 -/*
  1.1841 - * Internal functions that should not be called unless you have read
  1.1842 - * and understood the source code for these functions.
  1.1843 +/**
  1.1844 + * \fn void SDL_GL_DeleteContext(SDL_GLContext context)
  1.1845 + *
  1.1846 + * \brief Delete an OpenGL context.
  1.1847 + *
  1.1848 + * \sa SDL_GL_CreateContext()
  1.1849   */
  1.1850 -extern DECLSPEC void SDLCALL SDL_GL_UpdateRects(int numrects, SDL_Rect* rects);
  1.1851 -extern DECLSPEC void SDLCALL SDL_GL_Lock(void);
  1.1852 -extern DECLSPEC void SDLCALL SDL_GL_Unlock(void);
  1.1853 +extern DECLSPEC void SDLCALL SDL_GL_DeleteContext(SDL_GLContext context);
  1.1854  
  1.1855 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  1.1856 -/* These functions allow interaction with the window manager, if any.        */
  1.1857 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  1.1858 +/**
  1.1859 + * \def SDL_RectEmpty()
  1.1860 + *
  1.1861 + * \brief Returns true if the rectangle has no area.
  1.1862 + */
  1.1863 +#define SDL_RectEmpty(X)    (((X)->w <= 0) || ((X)->h <= 0))
  1.1864  
  1.1865 -/*
  1.1866 - * Sets/Gets the title and icon text of the display window (UTF-8 encoded)
  1.1867 +/**
  1.1868 + * \def SDL_RectEquals()
  1.1869 + *
  1.1870 + * \brief Returns true if the two rectangles are equal.
  1.1871   */
  1.1872 -extern DECLSPEC void SDLCALL SDL_WM_SetCaption(const char *title, const char *icon);
  1.1873 -extern DECLSPEC void SDLCALL SDL_WM_GetCaption(char **title, char **icon);
  1.1874 +#define SDL_RectEquals(A, B)   (((A)->x == (B)->x) && ((A)->y == (B)->y) && \
  1.1875 +                                ((A)->w == (B)->w) && ((A)->h == (B)->h))
  1.1876  
  1.1877 -/*
  1.1878 - * Sets the icon for the display window.
  1.1879 - * This function must be called before the first call to SDL_SetVideoMode().
  1.1880 - * It takes an icon surface, and a mask in MSB format.
  1.1881 - * If 'mask' is NULL, the entire icon surface will be used as the icon.
  1.1882 +/**
  1.1883 + * \fn SDL_bool SDL_HasIntersection(const SDL_Rect * A, const SDL_Rect * B);
  1.1884 + *
  1.1885 + * \brief Determine whether two rectangles intersect.
  1.1886 + *
  1.1887 + * \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
  1.1888   */
  1.1889 -extern DECLSPEC void SDLCALL SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask);
  1.1890 +extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A,
  1.1891 +                                                     const SDL_Rect * B);
  1.1892  
  1.1893 -/*
  1.1894 - * This function iconifies the window, and returns 1 if it succeeded.
  1.1895 - * If the function succeeds, it generates an SDL_APPACTIVE loss event.
  1.1896 - * This function is a noop and returns 0 in non-windowed environments.
  1.1897 +/**
  1.1898 + * \fn SDL_bool SDL_IntersectRect(const SDL_Rect * A, const SDL_Rect * B, SDL_Rect * result)
  1.1899 + *
  1.1900 + * \brief Calculate the intersection of two rectangles.
  1.1901 + *
  1.1902 + * \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
  1.1903   */
  1.1904 -extern DECLSPEC int SDLCALL SDL_WM_IconifyWindow(void);
  1.1905 +extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A,
  1.1906 +                                                   const SDL_Rect * B,
  1.1907 +                                                   SDL_Rect * result);
  1.1908  
  1.1909 -/*
  1.1910 - * Toggle fullscreen mode without changing the contents of the screen.
  1.1911 - * If the display surface does not require locking before accessing
  1.1912 - * the pixel information, then the memory pointers will not change.
  1.1913 +/**
  1.1914 + * \fn void SDL_UnionRect(const SDL_Rect * A, const SDL_Rect * B, SDL_Rect * result)
  1.1915   *
  1.1916 - * If this function was able to toggle fullscreen mode (change from 
  1.1917 - * running in a window to fullscreen, or vice-versa), it will return 1.
  1.1918 - * If it is not implemented, or fails, it returns 0.
  1.1919 - *
  1.1920 - * The next call to SDL_SetVideoMode() will set the mode fullscreen
  1.1921 - * attribute based on the flags parameter - if SDL_FULLSCREEN is not
  1.1922 - * set, then the display will be windowed by default where supported.
  1.1923 - *
  1.1924 - * This is currently only implemented in the X11 video driver.
  1.1925 + * \brief Calculate the union of two rectangles
  1.1926   */
  1.1927 -extern DECLSPEC int SDLCALL SDL_WM_ToggleFullScreen(SDL_Surface *surface);
  1.1928 +extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A,
  1.1929 +                                           const SDL_Rect * B,
  1.1930 +                                           SDL_Rect * result);
  1.1931  
  1.1932 -/*
  1.1933 - * This function allows you to set and query the input grab state of
  1.1934 - * the application.  It returns the new input grab state.
  1.1935 - */
  1.1936 -typedef enum {
  1.1937 -	SDL_GRAB_QUERY = -1,
  1.1938 -	SDL_GRAB_OFF = 0,
  1.1939 -	SDL_GRAB_ON = 1,
  1.1940 -	SDL_GRAB_FULLSCREEN	/* Used internally */
  1.1941 -} SDL_GrabMode;
  1.1942 -/*
  1.1943 - * Grabbing means that the mouse is confined to the application window,
  1.1944 - * and nearly all keyboard input is passed directly to the application,
  1.1945 - * and not interpreted by a window manager, if any.
  1.1946 - */
  1.1947 -extern DECLSPEC SDL_GrabMode SDLCALL SDL_WM_GrabInput(SDL_GrabMode mode);
  1.1948 -
  1.1949 -/* Not in public API at the moment - do not use! */
  1.1950 -extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect,
  1.1951 -                                    SDL_Surface *dst, SDL_Rect *dstrect);
  1.1952 -                    
  1.1953  /* Ends C function definitions when using C++ */
  1.1954  #ifdef __cplusplus
  1.1955 +/* *INDENT-OFF* */
  1.1956  }
  1.1957 +/* *INDENT-ON* */
  1.1958  #endif
  1.1959  #include "close_code.h"
  1.1960  
  1.1961  #endif /* _SDL_video_h */
  1.1962 +
  1.1963 +/* vi: set ts=4 sw=4 expandtab: */