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