include/SDL_video.h
author Sam Lantinga <slouken@libsdl.org>
Sun, 28 May 2006 13:04:16 +0000
branchSDL-1.3
changeset 1662 782fd950bd46
parent 1660 8b9d79e7eacf
child 1668 4da1ee79c9af
permissions -rw-r--r--
Revamp of the video system in progress - adding support for multiple displays, multiple windows, and a full video mode selection API.

WARNING: None of the video drivers have been updated for the new API yet! The API is still under design and very fluid.

The code is now run through a consistent indent format:
indent -i4 -nut -nsc -br -ce

The headers are being converted to automatically generate doxygen documentation.
     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 /* Useful data types */
    50 typedef struct SDL_Rect
    51 {
    52     Sint16 x, y;
    53     Uint16 w, h;
    54 } SDL_Rect;
    55 
    56 /* This structure should be treated as read-only, except for 'pixels',
    57    which, if not NULL, contains the raw pixel data for the surface.
    58 */
    59 typedef struct SDL_Surface
    60 {
    61     Uint32 flags;               /* Read-only */
    62     SDL_PixelFormat *format;    /* Read-only */
    63     int w, h;                   /* Read-only */
    64     Uint16 pitch;               /* Read-only */
    65     void *pixels;               /* Read-write */
    66     int offset;                 /* Private */
    67 
    68     /* Hardware-specific surface info */
    69     struct private_hwdata *hwdata;
    70 
    71     /* clipping information */
    72     SDL_Rect clip_rect;         /* Read-only */
    73     Uint32 unused1;             /* for binary compatibility */
    74 
    75     /* Allow recursive locks */
    76     Uint32 locked;              /* Private */
    77 
    78     /* info for fast blit mapping to other surfaces */
    79     struct SDL_BlitMap *map;    /* Private */
    80 
    81     /* format version, bumped at every change to invalidate blit maps */
    82     unsigned int format_version;        /* Private */
    83 
    84     /* Reference count -- used when freeing surface */
    85     int refcount;               /* Read-mostly */
    86 } SDL_Surface;
    87 
    88 /* The most common video overlay formats.
    89    For an explanation of these pixel formats, see:
    90 	http://www.webartz.com/fourcc/indexyuv.htm
    91 
    92    For information on the relationship between color spaces, see:
    93    http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
    94  */
    95 #define SDL_YV12_OVERLAY  0x32315659    /* Planar mode: Y + V + U  (3 planes) */
    96 #define SDL_IYUV_OVERLAY  0x56555949    /* Planar mode: Y + U + V  (3 planes) */
    97 #define SDL_YUY2_OVERLAY  0x32595559    /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
    98 #define SDL_UYVY_OVERLAY  0x59565955    /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
    99 #define SDL_YVYU_OVERLAY  0x55595659    /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
   100 
   101 /* The YUV hardware video overlay */
   102 typedef struct SDL_Overlay
   103 {
   104     Uint32 format;              /* Read-only */
   105     int w, h;                   /* Read-only */
   106     int planes;                 /* Read-only */
   107     Uint16 *pitches;            /* Read-only */
   108     Uint8 **pixels;             /* Read-write */
   109 
   110     /* Hardware-specific surface info */
   111     struct private_yuvhwfuncs *hwfuncs;
   112     struct private_yuvhwdata *hwdata;
   113 
   114     /* Special flags */
   115     Uint32 hw_overlay:1;        /* Flag: This overlay hardware accelerated? */
   116     Uint32 UnusedBits:31;
   117 } SDL_Overlay;
   118 
   119 /* Evaluates to true if the surface needs to be locked before access */
   120 #define SDL_MUSTLOCK(surface)	\
   121   (surface->offset ||		\
   122   ((surface->flags & (SDL_HWSURFACE|SDL_RLEACCEL)) != 0))
   123 
   124 /* typedef for private surface blitting functions */
   125 typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
   126                          struct SDL_Surface * dst, SDL_Rect * dstrect);
   127 
   128 
   129 /* Useful for determining the video hardware capabilities */
   130 typedef struct SDL_VideoInfo
   131 {
   132     Uint32 hw_available:1;      /* Flag: Can you create hardware surfaces? */
   133     Uint32 wm_available:1;      /* Flag: Can you talk to a window manager? */
   134     Uint32 UnusedBits1:6;
   135     Uint32 UnusedBits2:1;
   136     Uint32 blit_hw:1;           /* Flag: Accelerated blits HW --> HW */
   137     Uint32 blit_hw_CC:1;        /* Flag: Accelerated blits with Colorkey */
   138     Uint32 blit_hw_A:1;         /* Flag: Accelerated blits with Alpha */
   139     Uint32 blit_sw:1;           /* Flag: Accelerated blits SW --> HW */
   140     Uint32 blit_sw_CC:1;        /* Flag: Accelerated blits with Colorkey */
   141     Uint32 blit_sw_A:1;         /* Flag: Accelerated blits with Alpha */
   142     Uint32 blit_fill:1;         /* Flag: Accelerated color fill */
   143     Uint32 UnusedBits3:16;
   144     Uint32 video_mem;           /* The total amount of video memory (in K) */
   145 } SDL_VideoInfo;
   146 
   147 /**
   148  * \struct SDL_DisplayMode
   149  *
   150  * \brief  The structure that defines a display mode
   151  *
   152  * \sa SDL_GetNumDisplayModes()
   153  * \sa SDL_GetDisplayMode()
   154  * \sa SDL_GetDesktopDisplayMode()
   155  * \sa SDL_GetCurrentDisplayMode()
   156  * \sa SDL_GetClosestDisplayMode()
   157  * \sa SDL_SetDisplayMode()
   158  */
   159 typedef struct
   160 {
   161     Uint32 format;              /**< pixel format */
   162     int w;                      /**< width */
   163     int h;                      /**< height */
   164     int refresh_rate;           /**< refresh rate (or zero for unspecified) */
   165 } SDL_DisplayMode;
   166 
   167 /**
   168  * \typedef SDL_WindowID
   169  *
   170  * \brief The type used to identify a window
   171  *
   172  * \sa SDL_CreateWindow()
   173  * \sa SDL_CreateWindowFrom()
   174  * \sa SDL_DestroyWindow()
   175  * \sa SDL_GetWindowData()
   176  * \sa SDL_GetWindowFlags()
   177  * \sa SDL_GetWindowGrab()
   178  * \sa SDL_GetWindowPosition()
   179  * \sa SDL_GetWindowSize()
   180  * \sa SDL_GetWindowTitle()
   181  * \sa SDL_HideWindow()
   182  * \sa SDL_MaximizeWindow()
   183  * \sa SDL_MinimizeWindow()
   184  * \sa SDL_RaiseWindow()
   185  * \sa SDL_RestoreWindow()
   186  * \sa SDL_SetWindowData()
   187  * \sa SDL_SetWindowGrab()
   188  * \sa SDL_SetWindowIcon()
   189  * \sa SDL_SetWindowPosition()
   190  * \sa SDL_SetWindowSize()
   191  * \sa SDL_SetWindowTitle()
   192  * \sa SDL_ShowWindow()
   193  */
   194 typedef Uint32 SDL_WindowID;
   195 
   196 /**
   197  * \enum SDL_WindowFlags
   198  *
   199  * \brief The flags on a window
   200  */
   201 typedef enum
   202 {
   203     SDL_WINDOW_FULLSCREEN = 0x00000001,         /**< fullscreen window, implies borderless */
   204     SDL_WINDOW_BORDERLESS = 0x00000002,         /**< no window decoration */
   205     SDL_WINDOW_SHOWN = 0x00000004,              /**< window is visible */
   206     SDL_WINDOW_OPENGL = 0x00000008,             /**< window usable with OpenGL context */
   207     SDL_WINDOW_RESIZABLE = 0x00000010,          /**< window can be resized */
   208     SDL_WINDOW_MAXIMIZED = 0x00000020,          /**< maximized */
   209     SDL_WINDOW_MINIMIZED = 0x00000040,          /**< minimized */
   210     SDL_WINDOW_INPUT_GRABBED = 0x00000080,      /**< window has grabbed input focus */
   211     SDL_WINDOW_KEYBOARD_FOCUS = 0x00000100,     /**< window has keyboard focus */
   212     SDL_WINDOW_MOUSE_FOCUS = 0x00000200,        /**< window has mouse focus */
   213 } SDL_WindowFlags;
   214 
   215 /**
   216  * \enum SDL_WindowEventID
   217  *
   218  * \brief Event subtype for window events
   219  */
   220 typedef enum
   221 {
   222     SDL_WINDOWEVENT_NONE,               /**< Never used */
   223     SDL_WINDOWEVENT_SHOWN,              /**< Window has been shown */
   224     SDL_WINDOWEVENT_HIDDEN,             /**< Window has been hidden */
   225     SDL_WINDOWEVENT_MOVED,              /**< Window has been moved to data1,data2 */
   226     SDL_WINDOWEVENT_RESIZED,            /**< Window size changed to data1xdata2 */
   227     SDL_WINDOWEVENT_MINIMIZED,          /**< Window has been minimized */
   228     SDL_WINDOWEVENT_MAXIMIZED,          /**< Window has been maximized */
   229     SDL_WINDOWEVENT_RESTORED,           /**< Window has been restored to normal size and position */
   230     SDL_WINDOWEVENT_ENTER,              /**< The window has gained mouse focus */
   231     SDL_WINDOWEVENT_LEAVE,              /**< The window has lost mouse focus */
   232     SDL_WINDOWEVENT_FOCUS_GAINED,       /**< The window has gained keyboard focus */
   233     SDL_WINDOWEVENT_FOCUS_LOST,         /**< The window has lost keyboard focus */
   234 } SDL_WindowEventID;
   235 
   236 /**
   237  * \enum SDL_GLattr
   238  *
   239  * \brief OpenGL configuration attributes
   240  */
   241 typedef enum
   242 {
   243     SDL_GL_RED_SIZE,
   244     SDL_GL_GREEN_SIZE,
   245     SDL_GL_BLUE_SIZE,
   246     SDL_GL_ALPHA_SIZE,
   247     SDL_GL_BUFFER_SIZE,
   248     SDL_GL_DOUBLEBUFFER,
   249     SDL_GL_DEPTH_SIZE,
   250     SDL_GL_STENCIL_SIZE,
   251     SDL_GL_ACCUM_RED_SIZE,
   252     SDL_GL_ACCUM_GREEN_SIZE,
   253     SDL_GL_ACCUM_BLUE_SIZE,
   254     SDL_GL_ACCUM_ALPHA_SIZE,
   255     SDL_GL_STEREO,
   256     SDL_GL_MULTISAMPLEBUFFERS,
   257     SDL_GL_MULTISAMPLESAMPLES,
   258     SDL_GL_ACCELERATED_VISUAL,
   259     SDL_GL_SWAP_CONTROL
   260 } SDL_GLattr;
   261 
   262 /* These are the currently supported flags for the SDL_surface */
   263 #define SDL_SWSURFACE	0x00000000      /* Surface is in system memory */
   264 #define SDL_HWSURFACE	0x00000001      /* Surface is in video memory */
   265 /* Available for SDL_CreateWindowSurface() */
   266 #define SDL_ANYFORMAT	0x10000000      /* Allow any video depth/pixel-format */
   267 #define SDL_HWPALETTE	0x20000000      /* Surface has exclusive palette */
   268 #define SDL_DOUBLEBUF	0x40000000      /* Set up double-buffered surface */
   269 /* Used internally (read-only) */
   270 #define SDL_HWACCEL	0x00000100      /* Blit uses hardware acceleration */
   271 #define SDL_SRCCOLORKEY	0x00001000      /* Blit uses a source color key */
   272 #define SDL_RLEACCELOK	0x00002000      /* Private flag */
   273 #define SDL_RLEACCEL	0x00004000      /* Surface is RLE encoded */
   274 #define SDL_SRCALPHA	0x00010000      /* Blit uses source alpha blending */
   275 #define SDL_PREALLOC	0x00100000      /* Surface uses preallocated memory */
   276 #define SDL_SCREEN_SURFACE 0x01000000   /* Surface is a window screen surface */
   277 #define SDL_SHADOW_SURFACE 0x02000000   /* Surface is a window shadow surface */
   278 
   279 /* Function prototypes */
   280 
   281 /**
   282  * \fn int SDL_GetNumVideoDrivers(void)
   283  *
   284  * \brief Get the number of video drivers compiled into SDL
   285  *
   286  * \sa SDL_GetVideoDriver()
   287  */
   288 extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers (void);
   289 
   290 /**
   291  * \fn const char *SDL_GetVideoDriver(int index)
   292  *
   293  * \brief Get the name of a built in video driver.
   294  *
   295  * \note The video drivers are presented in the order in which they are
   296  * normally checked during initialization.
   297  *
   298  * \sa SDL_GetNumVideoDrivers()
   299  */
   300 extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver (int index);
   301 
   302 /**
   303  * \fn int SDL_VideoInit(const char *driver_name, Uint32 flags)
   304  *
   305  * \brief Initialize the video subsystem, optionally specifying a video driver.
   306  *
   307  * \param driver_name Initialize a specific driver by name, or NULL for the default video driver.
   308  * \param flags FIXME: Still needed?
   309  *
   310  * \return 0 on success, -1 on error
   311  *
   312  * This function initializes the video subsystem; setting up a connection
   313  * to the window manager, etc, and determines the available display modes
   314  * and pixel formats, but does not initialize a window or graphics mode.
   315  *
   316  * \sa SDL_VideoQuit()
   317  */
   318 extern DECLSPEC int SDLCALL SDL_VideoInit (const char *driver_name,
   319                                            Uint32 flags);
   320 
   321 /**
   322  * \fn void SDL_VideoQuit(void)
   323  *
   324  * \brief Shuts down the video subsystem.
   325  *
   326  * This function closes all windows, and restores the original video mode.
   327  *
   328  * \sa SDL_VideoInit()
   329  */
   330 extern DECLSPEC void SDLCALL SDL_VideoQuit (void);
   331 
   332 /**
   333  * \fn const char *SDL_GetCurrentVideoDriver(void)
   334  *
   335  * \brief Returns the name of the currently initialized video driver.
   336  *
   337  * \return The name of the current video driver or NULL if no driver
   338  *         has been initialized
   339  *
   340  * \sa SDL_GetNumVideoDrivers()
   341  * \sa SDL_GetVideoDriver()
   342  */
   343 extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver (void);
   344 
   345 /**
   346  * \fn const SDL_VideoInfo *SDL_GetVideoInfo(void)
   347  *
   348  * \brief Returns information about the currently initialized video driver.
   349  *
   350  * \return A read-only pointer to information about the video hardware,
   351  *         or NULL if no video driver has been initialized.
   352  */
   353 extern DECLSPEC const SDL_VideoInfo *SDLCALL SDL_GetVideoInfo (void);
   354 
   355 /**
   356  * \fn int SDL_GetNumVideoDisplays(void)
   357  *
   358  * \brief Returns the number of available video displays.
   359  *
   360  * \sa SDL_SelectVideoDisplay()
   361  */
   362 extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays (void);
   363 
   364 /**
   365  * \fn int SDL_SelectVideoDisplay(int index)
   366  *
   367  * \brief Set the index of the currently selected display.
   368  *
   369  * \note You can query the currently selected display by passing an index of -1.
   370  *
   371  * \sa SDL_GetNumVideoDisplays()
   372  */
   373 extern DECLSPEC int SDLCALL SDL_SelectVideoDisplay (int index);
   374 
   375 /**
   376  * \fn int SDL_GetNumDisplayModes(void)
   377  *
   378  * \brief Returns the number of available display modes for the current display.
   379  *
   380  * \sa SDL_GetDisplayMode()
   381  */
   382 extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes (void);
   383 
   384 /**
   385  * \fn const SDL_DisplayMode *SDL_GetDisplayMode(int index)
   386  *
   387  * \brief Retrieve information about a specific display mode.
   388  *
   389  * \note The display modes are sorted in this priority:
   390  *       \li bits per pixel -> more colors to fewer colors
   391  *       \li width -> largest to smallest
   392  *       \li height -> largest to smallest
   393  *       \li refresh rate -> highest to lowest
   394  *
   395  * \sa SDL_GetNumDisplayModes()
   396  */
   397 extern DECLSPEC const SDL_DisplayMode *SDLCALL SDL_GetDisplayMode (int index);
   398 
   399 /**
   400  * \fn const SDL_DisplayMode *SDL_GetDesktopDisplayMode(void)
   401  *
   402  * \brief Retrieve information about the desktop display mode for the current display.
   403  */
   404 extern DECLSPEC const SDL_DisplayMode *SDLCALL
   405 SDL_GetDesktopDisplayMode (void);
   406 
   407 /**
   408  * \fn const SDL_DisplayMode *SDL_GetCurrentDisplayMode(void)
   409  *
   410  * \brief Retrieve information about the current display mode.
   411  */
   412 extern DECLSPEC const SDL_DisplayMode *SDLCALL
   413 SDL_GetCurrentDisplayMode (void);
   414 
   415 /**
   416  * \fn SDL_DisplayMode *SDL_GetClosestDisplayMode(const SDL_DisplayMode *mode, SDL_DisplayMode *closest)
   417  *
   418  * \brief Get the closest match to the requested display mode.
   419  *
   420  * \param mode The desired display mode
   421  * \param closest A pointer to a display mode to be filled in with the closest match of the available display modes.
   422  *
   423  * \return The passed in value 'closest', or NULL if no matching video mode was available.
   424  *
   425  * 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.
   426  *
   427  * \sa SDL_GetNumDisplayModes()
   428  * \sa SDL_GetDisplayMode()
   429  */
   430 extern DECLSPEC SDL_DisplayMode *SDLCALL SDL_GetClosestDisplayMode (const
   431                                                                     SDL_DisplayMode
   432                                                                     * mode,
   433                                                                     SDL_DisplayMode
   434                                                                     *
   435                                                                     closest);
   436 
   437 /**
   438  * \fn int SDL_SetDisplayMode(const SDL_DisplayMode *mode)
   439  *
   440  * \brief Set up the closest available mode on the current display.
   441  *
   442  * \param mode The desired display mode
   443  *
   444  * \return 0 on success, or -1 if setting the display mode failed.
   445  */
   446 extern DECLSPEC int SDLCALL SDL_SetDisplayMode (const SDL_DisplayMode * mode);
   447 
   448 /**
   449  * \fn SDL_WindowID SDL_CreateWindow(const char *title, int x, int y, int w, int h, Uint32 flags)
   450  *
   451  * \brief Create a window with the specified position, dimensions, and flags.
   452  *
   453  * \param title The title of the window
   454  * \param x The x position of the window
   455  * \param y The y position of the window
   456  * \param w The width of the window
   457  * \param h The height of the window
   458  * \param flags The flags for the window
   459  *
   460  * \return The id of the window created, or zero if window creation failed.
   461  *
   462  * \note Setting the position to -1, -1, indicates any position is fine.
   463  *
   464  * \sa SDL_DestroyWindow()
   465  */
   466 extern DECLSPEC SDL_WindowID SDLCALL SDL_CreateWindow (const char *title,
   467                                                        int x, int y, int w,
   468                                                        int h, Uint32 flags);
   469 
   470 /**
   471  * \fn SDL_WindowID SDL_CreateWindowFrom(void *data)
   472  *
   473  * \brief Create an SDL window struct from an existing native window.
   474  *
   475  * \param data A pointer to driver-dependent window creation data
   476  *
   477  * \return The id of the window created, or zero if window creation failed.
   478  *
   479  * \warning This function is NOT SUPPORTED, use at your own risk!
   480  *
   481  * \sa SDL_DestroyWindow()
   482  */
   483 extern DECLSPEC SDL_WindowID SDLCALL SDL_CreateWindowFrom (void *data);
   484 
   485 /**
   486  * \fn Uint32 SDL_GetWindowFlags(SDL_WindowID windowID)
   487  *
   488  * \brief Get the window flags.
   489  */
   490 extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags (SDL_WindowID windowID);
   491 
   492 /**
   493  * \fn void SDL_SetWindowTitle(SDL_WindowID windowID, const char *title)
   494  *
   495  * \brief Set the title of the window, in UTF-8 format.
   496  *
   497  * \sa SDL_GetWindowTitle()
   498  */
   499 extern DECLSPEC void SDLCALL SDL_SetWindowTitle (SDL_WindowID windowID,
   500                                                  const char *title);
   501 
   502 /**
   503  * \fn const char *SDL_GetWindowTitle(SDL_WindowID windowID)
   504  *
   505  * \brief Get the title of the window, in UTF-8 format.
   506  *
   507  * \sa SDL_SetWindowTitle()
   508  */
   509 extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle (SDL_WindowID
   510                                                         windowID);
   511 
   512 /**
   513  * \fn void SDL_SetWindowIcon(SDL_Surface *icon)
   514  *
   515  * \brief Set the icon of the window.
   516  *
   517  * \param icon The icon for the window
   518  *
   519  * FIXME: The icon needs to be set before the window is first shown.  Should some icon representation be part of the window creation data?
   520  */
   521 extern DECLSPEC void SDLCALL SDL_SetWindowIcon (SDL_Surface * icon);
   522 
   523 /**
   524  * \fn void SDL_SetWindowData(SDL_WindowID windowID, void *userdata)
   525  *
   526  * \brief Associate an arbitrary pointer with the window.
   527  *
   528  * \sa SDL_GetWindowData()
   529  */
   530 extern DECLSPEC void SDLCALL SDL_SetWindowData (SDL_WindowID windowID,
   531                                                 void *userdata);
   532 
   533 /**
   534  * \fn void *SDL_GetWindowData(SDL_WindowID windowID)
   535  *
   536  * \brief Retrieve the data pointer associated with the window.
   537  *
   538  * \sa SDL_SetWindowData()
   539  */
   540 extern DECLSPEC void *SDLCALL SDL_GetWindowData (SDL_WindowID windowID);
   541 
   542 /**
   543  * \fn void SDL_SetWindowPosition(SDL_WindowID windowID, int x, int y)
   544  *
   545  * \brief Set the position of the window.
   546  *
   547  * \sa SDL_GetWindowPosition()
   548  */
   549 extern DECLSPEC void SDLCALL SDL_SetWindowPosition (SDL_WindowID windowID,
   550                                                     int x, int y);
   551 
   552 /**
   553  * \fn void SDL_GetWindowPosition(SDL_WindowID windowID, int *x, int *y)
   554  *
   555  * \brief Get the position of the window.
   556  *
   557  * \sa SDL_SetWindowPosition()
   558  */
   559 extern DECLSPEC void SDLCALL SDL_GetWindowPosition (SDL_WindowID windowID,
   560                                                     int *x, int *y);
   561 
   562 /**
   563  * \fn void SDL_SetWindowSize(SDL_WindowID windowID, int w, int w)
   564  *
   565  * \brief Set the size of the window's client area.
   566  *
   567  * \note You can't change the size of a fullscreen window, it automatically
   568  * matches the size of the display mode.
   569  *
   570  * \sa SDL_GetWindowSize()
   571  */
   572 extern DECLSPEC void SDLCALL SDL_SetWindowSize (SDL_WindowID windowID, int w,
   573                                                 int h);
   574 
   575 /**
   576  * \fn void SDL_GetWindowSize(SDL_WindowID windowID, int *w, int *w)
   577  *
   578  * \brief Get the size of the window's client area.
   579  *
   580  * \sa SDL_SetWindowSize()
   581  */
   582 extern DECLSPEC void SDLCALL SDL_GetWindowSize (SDL_WindowID windowID, int *w,
   583                                                 int *h);
   584 
   585 /**
   586  * \fn void SDL_ShowWindow(SDL_WindowID windowID)
   587  *
   588  * \brief Show the window
   589  *
   590  * \sa SDL_HideWindow()
   591  */
   592 extern DECLSPEC void SDLCALL SDL_ShowWindow (SDL_WindowID windowID);
   593 
   594 /**
   595  * \fn void SDL_HideWindow(SDL_WindowID windowID)
   596  *
   597  * \brief Hide the window
   598  *
   599  * \sa SDL_ShowWindow()
   600  */
   601 extern DECLSPEC void SDLCALL SDL_HideWindow (SDL_WindowID windowID);
   602 
   603 /**
   604  * \fn void SDL_RaiseWindow(SDL_WindowID windowID)
   605  *
   606  * \brief Raise the window so it's above other windows.
   607  */
   608 extern DECLSPEC void SDLCALL SDL_RaiseWindow (SDL_WindowID windowID);
   609 
   610 /**
   611  * \fn void SDL_MaximizeWindow(SDL_WindowID windowID)
   612  *
   613  * \brief Make the window as large as possible.
   614  *
   615  * \sa SDL_RestoreWindow()
   616  */
   617 extern DECLSPEC void SDLCALL SDL_MaximizeWindow (SDL_WindowID windowID);
   618 
   619 /**
   620  * \fn void SDL_MinimizeWindow(SDL_WindowID windowID)
   621  *
   622  * \brief Minimize the window to an iconic representation.
   623  *
   624  * \sa SDL_RestoreWindow()
   625  */
   626 extern DECLSPEC void SDLCALL SDL_MinimizeWindow (SDL_WindowID windowID);
   627 
   628 /**
   629  * \fn void SDL_RestoreWindow(SDL_WindowID windowID)
   630  *
   631  * \brief Restore the size and position of a minimized or maximized window.
   632  *
   633  * \sa SDL_MaximizeWindow()
   634  * \sa SDL_MinimizeWindow()
   635  */
   636 extern DECLSPEC void SDLCALL SDL_RestoreWindow (SDL_WindowID windowID);
   637 
   638 /**
   639  * \fn void SDL_SetWindowGrab(SDL_WindowID windowID, int mode)
   640  *
   641  * \brief Set the window's input grab mode.
   642  *
   643  * \param mode This is 1 to grab input, and 0 to release input.
   644  *
   645  * \sa SDL_GrabMode
   646  * \sa SDL_GetWindowGrab()
   647  */
   648 extern DECLSPEC void SDLCALL SDL_SetWindowGrab (SDL_WindowID windowID,
   649                                                 int mode);
   650 
   651 /**
   652  * \fn int SDL_GetWindowGrab(SDL_WindowID windowID)
   653  *
   654  * \brief Get the window's input grab mode.
   655  *
   656  * \return This returns 1 if input is grabbed, and 0 otherwise.
   657  *
   658  * \sa SDL_GrabMode
   659  * \sa SDL_SetWindowGrab()
   660  */
   661 extern DECLSPEC int SDLCALL SDL_GetWindowGrab (SDL_WindowID windowID);
   662 
   663 /**
   664  * \fn void SDL_DestroyWindow(SDL_WindowID windowID)
   665  *
   666  * \brief Destroy a window.
   667  */
   668 extern DECLSPEC void SDLCALL SDL_DestroyWindow (SDL_WindowID windowID);
   669 
   670 /**
   671  * \fn SDL_Surface *SDL_CreateWindowSurface (SDL_WindowID windowID, Uint32 format, Uint32 flags)
   672  *
   673  * \brief Create an SDL_Surface representing the drawing area of the window.
   674  */
   675 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateWindowSurface (SDL_WindowID
   676                                                               windowID,
   677                                                               Uint32 format,
   678                                                               Uint32 flags);
   679 
   680 /*
   681  * Makes sure the given list of rectangles is updated on the given screen.
   682  * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
   683  * screen.
   684  * These functions should not be called while 'screen' is locked.
   685  */
   686 extern DECLSPEC void SDLCALL SDL_UpdateRects
   687     (SDL_Surface * screen, int numrects, SDL_Rect * rects);
   688 extern DECLSPEC void SDLCALL SDL_UpdateRect
   689     (SDL_Surface * screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
   690 
   691 /*
   692  * On hardware that supports double-buffering, this function sets up a flip
   693  * and returns.  The hardware will wait for vertical retrace, and then swap
   694  * video buffers before the next video surface blit or lock will return.
   695  * On hardware that doesn not support double-buffering, this is equivalent
   696  * to calling SDL_UpdateRect(screen, 0, 0, 0, 0);
   697  * The SDL_DOUBLEBUF flag must have been passed to SDL_SetVideoMode() when
   698  * setting the video mode for this function to perform hardware flipping.
   699  * This function returns 0 if successful, or -1 if there was an error.
   700  */
   701 extern DECLSPEC int SDLCALL SDL_Flip (SDL_Surface * screen);
   702 
   703 /*
   704  * Set the gamma correction for each of the color channels.
   705  * The gamma values range (approximately) between 0.1 and 10.0
   706  * 
   707  * If this function isn't supported directly by the hardware, it will
   708  * be emulated using gamma ramps, if available.  If successful, this
   709  * function returns 0, otherwise it returns -1.
   710  */
   711 extern DECLSPEC int SDLCALL SDL_SetGamma (float red, float green, float blue);
   712 
   713 /*
   714  * Set the gamma translation table for the red, green, and blue channels
   715  * of the video hardware.  Each table is an array of 256 16-bit quantities,
   716  * representing a mapping between the input and output for that channel.
   717  * The input is the index into the array, and the output is the 16-bit
   718  * gamma value at that index, scaled to the output color precision.
   719  * 
   720  * You may pass NULL for any of the channels to leave it unchanged.
   721  * If the call succeeds, it will return 0.  If the display driver or
   722  * hardware does not support gamma translation, or otherwise fails,
   723  * this function will return -1.
   724  */
   725 extern DECLSPEC int SDLCALL SDL_SetGammaRamp (const Uint16 * red,
   726                                               const Uint16 * green,
   727                                               const Uint16 * blue);
   728 
   729 /*
   730  * Retrieve the current values of the gamma translation tables.
   731  * 
   732  * You must pass in valid pointers to arrays of 256 16-bit quantities.
   733  * Any of the pointers may be NULL to ignore that channel.
   734  * If the call succeeds, it will return 0.  If the display driver or
   735  * hardware does not support gamma translation, or otherwise fails,
   736  * this function will return -1.
   737  */
   738 extern DECLSPEC int SDLCALL SDL_GetGammaRamp (Uint16 * red, Uint16 * green,
   739                                               Uint16 * blue);
   740 
   741 /*
   742  * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
   743  * is not a palettized surface, this function does nothing, returning 0.
   744  * If all of the colors were set as passed to SDL_SetColors(), it will
   745  * return 1.  If not all the color entries were set exactly as given,
   746  * it will return 0, and you should look at the surface palette to
   747  * determine the actual color palette.
   748  *
   749  * When 'surface' is the surface associated with the current display, the
   750  * display colormap will be updated with the requested colors.  If 
   751  * SDL_HWPALETTE was set in SDL_SetVideoMode() flags, SDL_SetColors()
   752  * will always return 1, and the palette is guaranteed to be set the way
   753  * you desire, even if the window colormap has to be warped or run under
   754  * emulation.
   755  */
   756 extern DECLSPEC int SDLCALL SDL_SetColors (SDL_Surface * surface,
   757                                            SDL_Color * colors, int firstcolor,
   758                                            int ncolors);
   759 
   760 /*
   761  * Maps an RGB triple to an opaque pixel value for a given pixel format
   762  */
   763 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB
   764     (SDL_PixelFormat * format, Uint8 r, Uint8 g, Uint8 b);
   765 
   766 /*
   767  * Maps an RGBA quadruple to a pixel value for a given pixel format
   768  */
   769 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA (SDL_PixelFormat * format,
   770                                             Uint8 r, Uint8 g, Uint8 b,
   771                                             Uint8 a);
   772 
   773 /*
   774  * Maps a pixel value into the RGB components for a given pixel format
   775  */
   776 extern DECLSPEC void SDLCALL SDL_GetRGB (Uint32 pixel, SDL_PixelFormat * fmt,
   777                                          Uint8 * r, Uint8 * g, Uint8 * b);
   778 
   779 /*
   780  * Maps a pixel value into the RGBA components for a given pixel format
   781  */
   782 extern DECLSPEC void SDLCALL SDL_GetRGBA (Uint32 pixel, SDL_PixelFormat * fmt,
   783                                           Uint8 * r, Uint8 * g, Uint8 * b,
   784                                           Uint8 * a);
   785 
   786 /*
   787  * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
   788  * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
   789  * If the depth is greater than 8 bits, the pixel format is set using the
   790  * flags '[RGB]mask'.
   791  * If the function runs out of memory, it will return NULL.
   792  *
   793  * The 'flags' tell what kind of surface to create.
   794  * SDL_SWSURFACE means that the surface should be created in system memory.
   795  * SDL_HWSURFACE means that the surface should be created in video memory,
   796  * with the same format as the display surface.  This is useful for surfaces
   797  * that will not change much, to take advantage of hardware acceleration
   798  * when being blitted to the display surface.
   799  * SDL_ASYNCBLIT means that SDL will try to perform asynchronous blits with
   800  * this surface, but you must always lock it before accessing the pixels.
   801  * SDL will wait for current blits to finish before returning from the lock.
   802  * SDL_SRCCOLORKEY indicates that the surface will be used for colorkey blits.
   803  * If the hardware supports acceleration of colorkey blits between
   804  * two surfaces in video memory, SDL will try to place the surface in
   805  * video memory. If this isn't possible or if there is no hardware
   806  * acceleration available, the surface will be placed in system memory.
   807  * SDL_SRCALPHA means that the surface will be used for alpha blits and 
   808  * if the hardware supports hardware acceleration of alpha blits between
   809  * two surfaces in video memory, to place the surface in video memory
   810  * if possible, otherwise it will be placed in system memory.
   811  * If the surface is created in video memory, blits will be _much_ faster,
   812  * but the surface format must be identical to the video surface format,
   813  * and the only way to access the pixels member of the surface is to use
   814  * the SDL_LockSurface() and SDL_UnlockSurface() calls.
   815  * If the requested surface actually resides in video memory, SDL_HWSURFACE
   816  * will be set in the flags member of the returned surface.  If for some
   817  * reason the surface could not be placed in video memory, it will not have
   818  * the SDL_HWSURFACE flag set, and will be created in system memory instead.
   819  */
   820 #define SDL_AllocSurface    SDL_CreateRGBSurface
   821 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
   822     (Uint32 flags, int width, int height, int depth,
   823      Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
   824 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom (void *pixels,
   825                                                                int width,
   826                                                                int height,
   827                                                                int depth,
   828                                                                int pitch,
   829                                                                Uint32 Rmask,
   830                                                                Uint32 Gmask,
   831                                                                Uint32 Bmask,
   832                                                                Uint32 Amask);
   833 extern DECLSPEC void SDLCALL SDL_FreeSurface (SDL_Surface * surface);
   834 
   835 /*
   836  * SDL_LockSurface() sets up a surface for directly accessing the pixels.
   837  * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
   838  * to and read from 'surface->pixels', using the pixel format stored in 
   839  * 'surface->format'.  Once you are done accessing the surface, you should 
   840  * use SDL_UnlockSurface() to release it.
   841  *
   842  * Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
   843  * to 0, then you can read and write to the surface at any time, and the
   844  * pixel format of the surface will not change.  In particular, if the
   845  * SDL_HWSURFACE flag is not given when calling SDL_SetVideoMode(), you
   846  * will not need to lock the display surface before accessing it.
   847  * 
   848  * No operating system or library calls should be made between lock/unlock
   849  * pairs, as critical system locks may be held during this time.
   850  *
   851  * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
   852  */
   853 extern DECLSPEC int SDLCALL SDL_LockSurface (SDL_Surface * surface);
   854 extern DECLSPEC void SDLCALL SDL_UnlockSurface (SDL_Surface * surface);
   855 
   856 /*
   857  * Load a surface from a seekable SDL data source (memory or file.)
   858  * If 'freesrc' is non-zero, the source will be closed after being read.
   859  * Returns the new surface, or NULL if there was an error.
   860  * The new surface should be freed with SDL_FreeSurface().
   861  */
   862 extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW (SDL_RWops * src,
   863                                                      int freesrc);
   864 
   865 /* Convenience macro -- load a surface from a file */
   866 #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
   867 
   868 /*
   869  * Save a surface to a seekable SDL data source (memory or file.)
   870  * If 'freedst' is non-zero, the source will be closed after being written.
   871  * Returns 0 if successful or -1 if there was an error.
   872  */
   873 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
   874     (SDL_Surface * surface, SDL_RWops * dst, int freedst);
   875 
   876 /* Convenience macro -- save a surface to a file */
   877 #define SDL_SaveBMP(surface, file) \
   878 		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
   879 
   880 /*
   881  * Sets the color key (transparent pixel) in a blittable surface.
   882  * If 'flag' is SDL_SRCCOLORKEY (optionally OR'd with SDL_RLEACCEL), 
   883  * 'key' will be the transparent pixel in the source image of a blit.
   884  * SDL_RLEACCEL requests RLE acceleration for the surface if present,
   885  * and removes RLE acceleration if absent.
   886  * If 'flag' is 0, this function clears any current color key.
   887  * This function returns 0, or -1 if there was an error.
   888  */
   889 extern DECLSPEC int SDLCALL SDL_SetColorKey
   890     (SDL_Surface * surface, Uint32 flag, Uint32 key);
   891 
   892 /*
   893  * This function sets the alpha value for the entire surface, as opposed to
   894  * using the alpha component of each pixel. This value measures the range
   895  * of transparency of the surface, 0 being completely transparent to 255
   896  * being completely opaque. An 'alpha' value of 255 causes blits to be
   897  * opaque, the source pixels copied to the destination (the default). Note
   898  * that per-surface alpha can be combined with colorkey transparency.
   899  *
   900  * If 'flag' is 0, alpha blending is disabled for the surface.
   901  * If 'flag' is SDL_SRCALPHA, alpha blending is enabled for the surface.
   902  * OR:ing the flag with SDL_RLEACCEL requests RLE acceleration for the
   903  * surface; if SDL_RLEACCEL is not specified, the RLE accel will be removed.
   904  *
   905  * The 'alpha' parameter is ignored for surfaces that have an alpha channel.
   906  */
   907 extern DECLSPEC int SDLCALL SDL_SetAlpha (SDL_Surface * surface, Uint32 flag,
   908                                           Uint8 alpha);
   909 
   910 /*
   911  * Sets the clipping rectangle for the destination surface in a blit.
   912  *
   913  * If the clip rectangle is NULL, clipping will be disabled.
   914  * If the clip rectangle doesn't intersect the surface, the function will
   915  * return SDL_FALSE and blits will be completely clipped.  Otherwise the
   916  * function returns SDL_TRUE and blits to the surface will be clipped to
   917  * the intersection of the surface area and the clipping rectangle.
   918  *
   919  * Note that blits are automatically clipped to the edges of the source
   920  * and destination surfaces.
   921  */
   922 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect (SDL_Surface * surface,
   923                                                   const SDL_Rect * rect);
   924 
   925 /*
   926  * Gets the clipping rectangle for the destination surface in a blit.
   927  * 'rect' must be a pointer to a valid rectangle which will be filled
   928  * with the correct values.
   929  */
   930 extern DECLSPEC void SDLCALL SDL_GetClipRect (SDL_Surface * surface,
   931                                               SDL_Rect * rect);
   932 
   933 /*
   934  * Creates a new surface of the specified format, and then copies and maps 
   935  * the given surface to it so the blit of the converted surface will be as 
   936  * fast as possible.  If this function fails, it returns NULL.
   937  *
   938  * The 'flags' parameter is passed to SDL_CreateRGBSurface() and has those 
   939  * semantics.  You can also pass SDL_RLEACCEL in the flags parameter and
   940  * SDL will try to RLE accelerate colorkey and alpha blits in the resulting
   941  * surface.
   942  *
   943  * This function is used internally by SDL_DisplayFormat().
   944  */
   945 extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
   946     (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags);
   947 
   948 /*
   949  * This performs a fast blit from the source surface to the destination
   950  * surface.  It assumes that the source and destination rectangles are
   951  * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
   952  * surface (src or dst) is copied.  The final blit rectangles are saved
   953  * in 'srcrect' and 'dstrect' after all clipping is performed.
   954  * If the blit is successful, it returns 0, otherwise it returns -1.
   955  *
   956  * The blit function should not be called on a locked surface.
   957  *
   958  * The blit semantics for surfaces with and without alpha and colorkey
   959  * are defined as follows:
   960  *
   961  * RGBA->RGB:
   962  *     SDL_SRCALPHA set:
   963  * 	alpha-blend (using alpha-channel).
   964  * 	SDL_SRCCOLORKEY ignored.
   965  *     SDL_SRCALPHA not set:
   966  * 	copy RGB.
   967  * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
   968  * 	RGB values of the source colour key, ignoring alpha in the
   969  * 	comparison.
   970  * 
   971  * RGB->RGBA:
   972  *     SDL_SRCALPHA set:
   973  * 	alpha-blend (using the source per-surface alpha value);
   974  * 	set destination alpha to opaque.
   975  *     SDL_SRCALPHA not set:
   976  * 	copy RGB, set destination alpha to source per-surface alpha value.
   977  *     both:
   978  * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
   979  * 	source colour key.
   980  * 
   981  * RGBA->RGBA:
   982  *     SDL_SRCALPHA set:
   983  * 	alpha-blend (using the source alpha channel) the RGB values;
   984  * 	leave destination alpha untouched. [Note: is this correct?]
   985  * 	SDL_SRCCOLORKEY ignored.
   986  *     SDL_SRCALPHA not set:
   987  * 	copy all of RGBA to the destination.
   988  * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
   989  * 	RGB values of the source colour key, ignoring alpha in the
   990  * 	comparison.
   991  * 
   992  * RGB->RGB: 
   993  *     SDL_SRCALPHA set:
   994  * 	alpha-blend (using the source per-surface alpha value).
   995  *     SDL_SRCALPHA not set:
   996  * 	copy RGB.
   997  *     both:
   998  * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
   999  * 	source colour key.
  1000  *
  1001  * If either of the surfaces were in video memory, and the blit returns -2,
  1002  * the video memory was lost, so it should be reloaded with artwork and 
  1003  * re-blitted:
  1004 	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
  1005 		while ( SDL_LockSurface(image) < 0 )
  1006 			Sleep(10);
  1007 		-- Write image pixels to image->pixels --
  1008 		SDL_UnlockSurface(image);
  1009 	}
  1010  * This happens under DirectX 5.0 when the system switches away from your
  1011  * fullscreen application.  The lock will also fail until you have access
  1012  * to the video memory again.
  1013  */
  1014 /* You should call SDL_BlitSurface() unless you know exactly how SDL
  1015    blitting works internally and how to use the other blit functions.
  1016 */
  1017 #define SDL_BlitSurface SDL_UpperBlit
  1018 
  1019 /* This is the public blit function, SDL_BlitSurface(), and it performs
  1020    rectangle validation and clipping before passing it to SDL_LowerBlit()
  1021 */
  1022 extern DECLSPEC int SDLCALL SDL_UpperBlit
  1023     (SDL_Surface * src, SDL_Rect * srcrect,
  1024      SDL_Surface * dst, SDL_Rect * dstrect);
  1025 /* This is a semi-private blit function and it performs low-level surface
  1026    blitting only.
  1027 */
  1028 extern DECLSPEC int SDLCALL SDL_LowerBlit
  1029     (SDL_Surface * src, SDL_Rect * srcrect,
  1030      SDL_Surface * dst, SDL_Rect * dstrect);
  1031 
  1032 /*
  1033  * This function performs a fast fill of the given rectangle with 'color'
  1034  * The given rectangle is clipped to the destination surface clip area
  1035  * and the final fill rectangle is saved in the passed in pointer.
  1036  * If 'dstrect' is NULL, the whole surface will be filled with 'color'
  1037  * The color should be a pixel of the format used by the surface, and 
  1038  * can be generated by the SDL_MapRGB() function.
  1039  * This function returns 0 on success, or -1 on error.
  1040  */
  1041 extern DECLSPEC int SDLCALL SDL_FillRect
  1042     (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color);
  1043 
  1044 /* 
  1045  * This function takes a surface and copies it to a new surface of the
  1046  * pixel format and colors of the video framebuffer, suitable for fast
  1047  * blitting onto the display surface.  It calls SDL_ConvertSurface()
  1048  *
  1049  * If you want to take advantage of hardware colorkey or alpha blit
  1050  * acceleration, you should set the colorkey and alpha value before
  1051  * calling this function.
  1052  *
  1053  * If the conversion fails or runs out of memory, it returns NULL
  1054  */
  1055 extern DECLSPEC SDL_Surface *SDLCALL SDL_DisplayFormat (SDL_Surface *
  1056                                                         surface);
  1057 
  1058 /* 
  1059  * This function takes a surface and copies it to a new surface of the
  1060  * pixel format and colors of the video framebuffer (if possible),
  1061  * suitable for fast alpha blitting onto the display surface.
  1062  * The new surface will always have an alpha channel.
  1063  *
  1064  * If you want to take advantage of hardware colorkey or alpha blit
  1065  * acceleration, you should set the colorkey and alpha value before
  1066  * calling this function.
  1067  *
  1068  * If the conversion fails or runs out of memory, it returns NULL
  1069  */
  1070 extern DECLSPEC SDL_Surface *SDLCALL SDL_DisplayFormatAlpha (SDL_Surface *
  1071                                                              surface);
  1072 
  1073 
  1074 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  1075 /* YUV video surface overlay functions                                       */
  1076 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  1077 
  1078 /* This function creates a video output overlay
  1079    Calling the returned surface an overlay is something of a misnomer because
  1080    the contents of the display surface underneath the area where the overlay
  1081    is shown is undefined - it may be overwritten with the converted YUV data.
  1082 */
  1083 extern DECLSPEC SDL_Overlay *SDLCALL SDL_CreateYUVOverlay (int width,
  1084                                                            int height,
  1085                                                            Uint32 format,
  1086                                                            SDL_Surface *
  1087                                                            display);
  1088 
  1089 /* Lock an overlay for direct access, and unlock it when you are done */
  1090 extern DECLSPEC int SDLCALL SDL_LockYUVOverlay (SDL_Overlay * overlay);
  1091 extern DECLSPEC void SDLCALL SDL_UnlockYUVOverlay (SDL_Overlay * overlay);
  1092 
  1093 /* Blit a video overlay to the display surface.
  1094    The contents of the video surface underneath the blit destination are
  1095    not defined.  
  1096    The width and height of the destination rectangle may be different from
  1097    that of the overlay, but currently only 2x scaling is supported.
  1098 */
  1099 extern DECLSPEC int SDLCALL SDL_DisplayYUVOverlay (SDL_Overlay * overlay,
  1100                                                    SDL_Rect * dstrect);
  1101 
  1102 /* Free a video overlay */
  1103 extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay (SDL_Overlay * overlay);
  1104 
  1105 
  1106 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  1107 /* OpenGL support functions.                                                 */
  1108 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  1109 
  1110 /*
  1111  * Dynamically load an OpenGL library, or the default one if path is NULL
  1112  *
  1113  * If you do this, you need to retrieve all of the GL functions used in
  1114  * your program from the dynamic library using SDL_GL_GetProcAddress().
  1115  */
  1116 extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary (const char *path);
  1117 
  1118 /*
  1119  * Get the address of a GL function
  1120  */
  1121 extern DECLSPEC void *SDLCALL SDL_GL_GetProcAddress (const char *proc);
  1122 
  1123 /*
  1124  * Set an attribute of the OpenGL subsystem before window creation.
  1125  */
  1126 extern DECLSPEC int SDLCALL SDL_GL_SetAttribute (SDL_GLattr attr, int value);
  1127 
  1128 /*
  1129  * Get an attribute of the OpenGL subsystem from the windowing
  1130  * interface, such as glX. This is of course different from getting
  1131  * the values from SDL's internal OpenGL subsystem, which only
  1132  * stores the values you request before initialization.
  1133  *
  1134  * Developers should track the values they pass into SDL_GL_SetAttribute
  1135  * themselves if they want to retrieve these values.
  1136  */
  1137 extern DECLSPEC int SDLCALL SDL_GL_GetAttribute (SDL_GLattr attr, int *value);
  1138 
  1139 /*
  1140  * Swap the OpenGL buffers, if double-buffering is supported.
  1141  */
  1142 extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers (void);
  1143 
  1144 /* Not in public API at the moment - do not use! */
  1145 extern DECLSPEC int SDLCALL SDL_SoftStretch (SDL_Surface * src,
  1146                                              SDL_Rect * srcrect,
  1147                                              SDL_Surface * dst,
  1148                                              SDL_Rect * dstrect);
  1149 
  1150 /* Ends C function definitions when using C++ */
  1151 #ifdef __cplusplus
  1152 /* *INDENT-OFF* */
  1153 }
  1154 /* *INDENT-ON* */
  1155 #endif
  1156 #include "close_code.h"
  1157 
  1158 #endif /* _SDL_video_h */
  1159 
  1160 /* vi: set ts=4 sw=4 expandtab: */