include/SDL_video.h
author Ozkan Sezer <sezeroz@gmail.com>
Sun, 14 Oct 2018 15:25:04 +0300
branchSDL-1.2
changeset 12325 c4f2eeda176f
parent 6137 4720145f848b
permissions -rw-r--r--
remove symlink for libSDL-1.0.so.0 from the rpm spec file.

also fix a changelog date.
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 1997-2012 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 /** @file SDL_video.h
    24  *  Header file for access to the SDL raw framebuffer window
    25  */
    26 
    27 #ifndef _SDL_video_h
    28 #define _SDL_video_h
    29 
    30 #include "SDL_stdinc.h"
    31 #include "SDL_error.h"
    32 #include "SDL_rwops.h"
    33 
    34 #include "begin_code.h"
    35 /* Set up for C function definitions, even when using C++ */
    36 #ifdef __cplusplus
    37 extern "C" {
    38 #endif
    39 
    40 /** @name Transparency definitions
    41  *  These define alpha as the opacity of a surface
    42  */
    43 /*@{*/
    44 #define SDL_ALPHA_OPAQUE 255
    45 #define SDL_ALPHA_TRANSPARENT 0
    46 /*@}*/
    47 
    48 /** @name Useful data types */
    49 /*@{*/
    50 typedef struct SDL_Rect {
    51 	Sint16 x, y;
    52 	Uint16 w, h;
    53 } SDL_Rect;
    54 
    55 typedef struct SDL_Color {
    56 	Uint8 r;
    57 	Uint8 g;
    58 	Uint8 b;
    59 	Uint8 unused;
    60 } SDL_Color;
    61 #define SDL_Colour SDL_Color
    62 
    63 typedef struct SDL_Palette {
    64 	int       ncolors;
    65 	SDL_Color *colors;
    66 } SDL_Palette;
    67 /*@}*/
    68 
    69 /** Everything in the pixel format structure is read-only */
    70 typedef struct SDL_PixelFormat {
    71 	SDL_Palette *palette;
    72 	Uint8  BitsPerPixel;
    73 	Uint8  BytesPerPixel;
    74 	Uint8  Rloss;
    75 	Uint8  Gloss;
    76 	Uint8  Bloss;
    77 	Uint8  Aloss;
    78 	Uint8  Rshift;
    79 	Uint8  Gshift;
    80 	Uint8  Bshift;
    81 	Uint8  Ashift;
    82 	Uint32 Rmask;
    83 	Uint32 Gmask;
    84 	Uint32 Bmask;
    85 	Uint32 Amask;
    86 
    87 	/** RGB color key information */
    88 	Uint32 colorkey;
    89 	/** Alpha value information (per-surface alpha) */
    90 	Uint8  alpha;
    91 } SDL_PixelFormat;
    92 
    93 /** This structure should be treated as read-only, except for 'pixels',
    94  *  which, if not NULL, contains the raw pixel data for the surface.
    95  */
    96 typedef struct SDL_Surface {
    97 	Uint32 flags;				/**< Read-only */
    98 	SDL_PixelFormat *format;		/**< Read-only */
    99 	int w, h;				/**< Read-only */
   100 	Uint16 pitch;				/**< Read-only */
   101 	void *pixels;				/**< Read-write */
   102 	int offset;				/**< Private */
   103 
   104 	/** Hardware-specific surface info */
   105 	struct private_hwdata *hwdata;
   106 
   107 	/** clipping information */
   108 	SDL_Rect clip_rect;			/**< Read-only */
   109 	Uint32 unused1;				/**< for binary compatibility */
   110 
   111 	/** Allow recursive locks */
   112 	Uint32 locked;				/**< Private */
   113 
   114 	/** info for fast blit mapping to other surfaces */
   115 	struct SDL_BlitMap *map;		/**< Private */
   116 
   117 	/** format version, bumped at every change to invalidate blit maps */
   118 	unsigned int format_version;		/**< Private */
   119 
   120 	/** Reference count -- used when freeing surface */
   121 	int refcount;				/**< Read-mostly */
   122 } SDL_Surface;
   123 
   124 /** @name SDL_Surface Flags
   125  *  These are the currently supported flags for the SDL_surface
   126  */
   127 /*@{*/
   128 
   129 /** Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
   130 /*@{*/
   131 #define SDL_SWSURFACE	0x00000000	/**< Surface is in system memory */
   132 #define SDL_HWSURFACE	0x00000001	/**< Surface is in video memory */
   133 #define SDL_ASYNCBLIT	0x00000004	/**< Use asynchronous blits if possible */
   134 /*@}*/
   135 
   136 /** Available for SDL_SetVideoMode() */
   137 /*@{*/
   138 #define SDL_ANYFORMAT	0x10000000	/**< Allow any video depth/pixel-format */
   139 #define SDL_HWPALETTE	0x20000000	/**< Surface has exclusive palette */
   140 #define SDL_DOUBLEBUF	0x40000000	/**< Set up double-buffered video mode */
   141 #define SDL_FULLSCREEN	0x80000000	/**< Surface is a full screen display */
   142 #define SDL_OPENGL      0x00000002      /**< Create an OpenGL rendering context */
   143 #define SDL_OPENGLBLIT	0x0000000A	/**< Create an OpenGL rendering context and use it for blitting */
   144 #define SDL_RESIZABLE	0x00000010	/**< This video mode may be resized */
   145 #define SDL_NOFRAME	0x00000020	/**< No window caption or edge frame */
   146 /*@}*/
   147 
   148 /** Used internally (read-only) */
   149 /*@{*/
   150 #define SDL_HWACCEL	0x00000100	/**< Blit uses hardware acceleration */
   151 #define SDL_SRCCOLORKEY	0x00001000	/**< Blit uses a source color key */
   152 #define SDL_RLEACCELOK	0x00002000	/**< Private flag */
   153 #define SDL_RLEACCEL	0x00004000	/**< Surface is RLE encoded */
   154 #define SDL_SRCALPHA	0x00010000	/**< Blit uses source alpha blending */
   155 #define SDL_PREALLOC	0x01000000	/**< Surface uses preallocated memory */
   156 /*@}*/
   157 
   158 /*@}*/
   159 
   160 /** Evaluates to true if the surface needs to be locked before access */
   161 #define SDL_MUSTLOCK(surface)	\
   162   (surface->offset ||		\
   163   ((surface->flags & (SDL_HWSURFACE|SDL_ASYNCBLIT|SDL_RLEACCEL)) != 0))
   164 
   165 /** typedef for private surface blitting functions */
   166 typedef int (*SDL_blit)(struct SDL_Surface *src, SDL_Rect *srcrect,
   167 			struct SDL_Surface *dst, SDL_Rect *dstrect);
   168 
   169 
   170 /** Useful for determining the video hardware capabilities */
   171 typedef struct SDL_VideoInfo {
   172 	Uint32 hw_available :1;	/**< Flag: Can you create hardware surfaces? */
   173 	Uint32 wm_available :1;	/**< Flag: Can you talk to a window manager? */
   174 	Uint32 UnusedBits1  :6;
   175 	Uint32 UnusedBits2  :1;
   176 	Uint32 blit_hw      :1;	/**< Flag: Accelerated blits HW --> HW */
   177 	Uint32 blit_hw_CC   :1;	/**< Flag: Accelerated blits with Colorkey */
   178 	Uint32 blit_hw_A    :1;	/**< Flag: Accelerated blits with Alpha */
   179 	Uint32 blit_sw      :1;	/**< Flag: Accelerated blits SW --> HW */
   180 	Uint32 blit_sw_CC   :1;	/**< Flag: Accelerated blits with Colorkey */
   181 	Uint32 blit_sw_A    :1;	/**< Flag: Accelerated blits with Alpha */
   182 	Uint32 blit_fill    :1;	/**< Flag: Accelerated color fill */
   183 	Uint32 UnusedBits3  :16;
   184 	Uint32 video_mem;	/**< The total amount of video memory (in K) */
   185 	SDL_PixelFormat *vfmt;	/**< Value: The format of the video surface */
   186 	int    current_w;	/**< Value: The current video mode width */
   187 	int    current_h;	/**< Value: The current video mode height */
   188 } SDL_VideoInfo;
   189 
   190 
   191 /** @name Overlay Formats
   192  *  The most common video overlay formats.
   193  *  For an explanation of these pixel formats, see:
   194  *	http://www.webartz.com/fourcc/indexyuv.htm
   195  *
   196  *  For information on the relationship between color spaces, see:
   197  *  http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
   198  */
   199 /*@{*/
   200 #define SDL_YV12_OVERLAY  0x32315659	/**< Planar mode: Y + V + U  (3 planes) */
   201 #define SDL_IYUV_OVERLAY  0x56555949	/**< Planar mode: Y + U + V  (3 planes) */
   202 #define SDL_YUY2_OVERLAY  0x32595559	/**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
   203 #define SDL_UYVY_OVERLAY  0x59565955	/**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
   204 #define SDL_YVYU_OVERLAY  0x55595659	/**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
   205 /*@}*/
   206 
   207 /** The YUV hardware video overlay */
   208 typedef struct SDL_Overlay {
   209 	Uint32 format;				/**< Read-only */
   210 	int w, h;				/**< Read-only */
   211 	int planes;				/**< Read-only */
   212 	Uint16 *pitches;			/**< Read-only */
   213 	Uint8 **pixels;				/**< Read-write */
   214 
   215 	/** @name Hardware-specific surface info */
   216         /*@{*/
   217 	struct private_yuvhwfuncs *hwfuncs;
   218 	struct private_yuvhwdata *hwdata;
   219         /*@{*/
   220 
   221 	/** @name Special flags */
   222         /*@{*/
   223 	Uint32 hw_overlay :1;	/**< Flag: This overlay hardware accelerated? */
   224 	Uint32 UnusedBits :31;
   225         /*@}*/
   226 } SDL_Overlay;
   227 
   228 
   229 /** Public enumeration for setting the OpenGL window attributes. */
   230 typedef enum {
   231     SDL_GL_RED_SIZE,
   232     SDL_GL_GREEN_SIZE,
   233     SDL_GL_BLUE_SIZE,
   234     SDL_GL_ALPHA_SIZE,
   235     SDL_GL_BUFFER_SIZE,
   236     SDL_GL_DOUBLEBUFFER,
   237     SDL_GL_DEPTH_SIZE,
   238     SDL_GL_STENCIL_SIZE,
   239     SDL_GL_ACCUM_RED_SIZE,
   240     SDL_GL_ACCUM_GREEN_SIZE,
   241     SDL_GL_ACCUM_BLUE_SIZE,
   242     SDL_GL_ACCUM_ALPHA_SIZE,
   243     SDL_GL_STEREO,
   244     SDL_GL_MULTISAMPLEBUFFERS,
   245     SDL_GL_MULTISAMPLESAMPLES,
   246     SDL_GL_ACCELERATED_VISUAL,
   247     SDL_GL_SWAP_CONTROL
   248 } SDL_GLattr;
   249 
   250 /** @name flags for SDL_SetPalette() */
   251 /*@{*/
   252 #define SDL_LOGPAL 0x01
   253 #define SDL_PHYSPAL 0x02
   254 /*@}*/
   255 
   256 /* Function prototypes */
   257 
   258 /**
   259  * @name Video Init and Quit
   260  * These functions are used internally, and should not be used unless you
   261  * have a specific need to specify the video driver you want to use.
   262  * You should normally use SDL_Init() or SDL_InitSubSystem().
   263  */
   264 /*@{*/
   265 /**
   266  * Initializes the video subsystem. Sets up a connection
   267  * to the window manager, etc, and determines the current video mode and
   268  * pixel format, but does not initialize a window or graphics mode.
   269  * Note that event handling is activated by this routine.
   270  *
   271  * If you use both sound and video in your application, you need to call
   272  * SDL_Init() before opening the sound device, otherwise under Win32 DirectX,
   273  * you won't be able to set full-screen display modes.
   274  */
   275 extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name, Uint32 flags);
   276 extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
   277 /*@}*/
   278 
   279 /**
   280  * This function fills the given character buffer with the name of the
   281  * video driver, and returns a pointer to it if the video driver has
   282  * been initialized.  It returns NULL if no driver has been initialized.
   283  */
   284 extern DECLSPEC char * SDLCALL SDL_VideoDriverName(char *namebuf, int maxlen);
   285 
   286 /**
   287  * This function returns a pointer to the current display surface.
   288  * If SDL is doing format conversion on the display surface, this
   289  * function returns the publicly visible surface, not the real video
   290  * surface.
   291  */
   292 extern DECLSPEC SDL_Surface * SDLCALL SDL_GetVideoSurface(void);
   293 
   294 /**
   295  * This function returns a read-only pointer to information about the
   296  * video hardware.  If this is called before SDL_SetVideoMode(), the 'vfmt'
   297  * member of the returned structure will contain the pixel format of the
   298  * "best" video mode.
   299  */
   300 extern DECLSPEC const SDL_VideoInfo * SDLCALL SDL_GetVideoInfo(void);
   301 
   302 /**
   303  * Check to see if a particular video mode is supported.
   304  * It returns 0 if the requested mode is not supported under any bit depth,
   305  * or returns the bits-per-pixel of the closest available mode with the
   306  * given width and height.  If this bits-per-pixel is different from the
   307  * one used when setting the video mode, SDL_SetVideoMode() will succeed,
   308  * but will emulate the requested bits-per-pixel with a shadow surface.
   309  *
   310  * The arguments to SDL_VideoModeOK() are the same ones you would pass to
   311  * SDL_SetVideoMode()
   312  */
   313 extern DECLSPEC int SDLCALL SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags);
   314 
   315 /**
   316  * Return a pointer to an array of available screen dimensions for the
   317  * given format and video flags, sorted largest to smallest.  Returns 
   318  * NULL if there are no dimensions available for a particular format, 
   319  * or (SDL_Rect **)-1 if any dimension is okay for the given format.
   320  *
   321  * If 'format' is NULL, the mode list will be for the format given 
   322  * by SDL_GetVideoInfo()->vfmt
   323  */
   324 extern DECLSPEC SDL_Rect ** SDLCALL SDL_ListModes(SDL_PixelFormat *format, Uint32 flags);
   325 
   326 /**
   327  * Set up a video mode with the specified width, height and bits-per-pixel.
   328  *
   329  * If 'bpp' is 0, it is treated as the current display bits per pixel.
   330  *
   331  * If SDL_ANYFORMAT is set in 'flags', the SDL library will try to set the
   332  * requested bits-per-pixel, but will return whatever video pixel format is
   333  * available.  The default is to emulate the requested pixel format if it
   334  * is not natively available.
   335  *
   336  * If SDL_HWSURFACE is set in 'flags', the video surface will be placed in
   337  * video memory, if possible, and you may have to call SDL_LockSurface()
   338  * in order to access the raw framebuffer.  Otherwise, the video surface
   339  * will be created in system memory.
   340  *
   341  * If SDL_ASYNCBLIT is set in 'flags', SDL will try to perform rectangle
   342  * updates asynchronously, but you must always lock before accessing pixels.
   343  * SDL will wait for updates to complete before returning from the lock.
   344  *
   345  * If SDL_HWPALETTE is set in 'flags', the SDL library will guarantee
   346  * that the colors set by SDL_SetColors() will be the colors you get.
   347  * Otherwise, in 8-bit mode, SDL_SetColors() may not be able to set all
   348  * of the colors exactly the way they are requested, and you should look
   349  * at the video surface structure to determine the actual palette.
   350  * If SDL cannot guarantee that the colors you request can be set, 
   351  * i.e. if the colormap is shared, then the video surface may be created
   352  * under emulation in system memory, overriding the SDL_HWSURFACE flag.
   353  *
   354  * If SDL_FULLSCREEN is set in 'flags', the SDL library will try to set
   355  * a fullscreen video mode.  The default is to create a windowed mode
   356  * if the current graphics system has a window manager.
   357  * If the SDL library is able to set a fullscreen video mode, this flag 
   358  * will be set in the surface that is returned.
   359  *
   360  * If SDL_DOUBLEBUF is set in 'flags', the SDL library will try to set up
   361  * two surfaces in video memory and swap between them when you call 
   362  * SDL_Flip().  This is usually slower than the normal single-buffering
   363  * scheme, but prevents "tearing" artifacts caused by modifying video 
   364  * memory while the monitor is refreshing.  It should only be used by 
   365  * applications that redraw the entire screen on every update.
   366  *
   367  * If SDL_RESIZABLE is set in 'flags', the SDL library will allow the
   368  * window manager, if any, to resize the window at runtime.  When this
   369  * occurs, SDL will send a SDL_VIDEORESIZE event to you application,
   370  * and you must respond to the event by re-calling SDL_SetVideoMode()
   371  * with the requested size (or another size that suits the application).
   372  *
   373  * If SDL_NOFRAME is set in 'flags', the SDL library will create a window
   374  * without any title bar or frame decoration.  Fullscreen video modes have
   375  * this flag set automatically.
   376  *
   377  * This function returns the video framebuffer surface, or NULL if it fails.
   378  *
   379  * If you rely on functionality provided by certain video flags, check the
   380  * flags of the returned surface to make sure that functionality is available.
   381  * SDL will fall back to reduced functionality if the exact flags you wanted
   382  * are not available.
   383  */
   384 extern DECLSPEC SDL_Surface * SDLCALL SDL_SetVideoMode
   385 			(int width, int height, int bpp, Uint32 flags);
   386 
   387 /** @name SDL_Update Functions
   388  * These functions should not be called while 'screen' is locked.
   389  */
   390 /*@{*/
   391 /**
   392  * Makes sure the given list of rectangles is updated on the given screen.
   393  */
   394 extern DECLSPEC void SDLCALL SDL_UpdateRects
   395 		(SDL_Surface *screen, int numrects, SDL_Rect *rects);
   396 /**
   397  * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
   398  * screen.
   399  */
   400 extern DECLSPEC void SDLCALL SDL_UpdateRect
   401 		(SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
   402 /*@}*/
   403 
   404 /**
   405  * On hardware that supports double-buffering, this function sets up a flip
   406  * and returns.  The hardware will wait for vertical retrace, and then swap
   407  * video buffers before the next video surface blit or lock will return.
   408  * On hardware that doesn not support double-buffering, this is equivalent
   409  * to calling SDL_UpdateRect(screen, 0, 0, 0, 0);
   410  * The SDL_DOUBLEBUF flag must have been passed to SDL_SetVideoMode() when
   411  * setting the video mode for this function to perform hardware flipping.
   412  * This function returns 0 if successful, or -1 if there was an error.
   413  */
   414 extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface *screen);
   415 
   416 /**
   417  * Set the gamma correction for each of the color channels.
   418  * The gamma values range (approximately) between 0.1 and 10.0
   419  * 
   420  * If this function isn't supported directly by the hardware, it will
   421  * be emulated using gamma ramps, if available.  If successful, this
   422  * function returns 0, otherwise it returns -1.
   423  */
   424 extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
   425 
   426 /**
   427  * Set the gamma translation table for the red, green, and blue channels
   428  * of the video hardware.  Each table is an array of 256 16-bit quantities,
   429  * representing a mapping between the input and output for that channel.
   430  * The input is the index into the array, and the output is the 16-bit
   431  * gamma value at that index, scaled to the output color precision.
   432  * 
   433  * You may pass NULL for any of the channels to leave it unchanged.
   434  * If the call succeeds, it will return 0.  If the display driver or
   435  * hardware does not support gamma translation, or otherwise fails,
   436  * this function will return -1.
   437  */
   438 extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 *red, const Uint16 *green, const Uint16 *blue);
   439 
   440 /**
   441  * Retrieve the current values of the gamma translation tables.
   442  * 
   443  * You must pass in valid pointers to arrays of 256 16-bit quantities.
   444  * Any of the pointers may be NULL to ignore that channel.
   445  * If the call succeeds, it will return 0.  If the display driver or
   446  * hardware does not support gamma translation, or otherwise fails,
   447  * this function will return -1.
   448  */
   449 extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
   450 
   451 /**
   452  * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
   453  * is not a palettized surface, this function does nothing, returning 0.
   454  * If all of the colors were set as passed to SDL_SetColors(), it will
   455  * return 1.  If not all the color entries were set exactly as given,
   456  * it will return 0, and you should look at the surface palette to
   457  * determine the actual color palette.
   458  *
   459  * When 'surface' is the surface associated with the current display, the
   460  * display colormap will be updated with the requested colors.  If 
   461  * SDL_HWPALETTE was set in SDL_SetVideoMode() flags, SDL_SetColors()
   462  * will always return 1, and the palette is guaranteed to be set the way
   463  * you desire, even if the window colormap has to be warped or run under
   464  * emulation.
   465  */
   466 extern DECLSPEC int SDLCALL SDL_SetColors(SDL_Surface *surface, 
   467 			SDL_Color *colors, int firstcolor, int ncolors);
   468 
   469 /**
   470  * Sets a portion of the colormap for a given 8-bit surface.
   471  * 'flags' is one or both of:
   472  * SDL_LOGPAL  -- set logical palette, which controls how blits are mapped
   473  *                to/from the surface,
   474  * SDL_PHYSPAL -- set physical palette, which controls how pixels look on
   475  *                the screen
   476  * Only screens have physical palettes. Separate change of physical/logical
   477  * palettes is only possible if the screen has SDL_HWPALETTE set.
   478  *
   479  * The return value is 1 if all colours could be set as requested, and 0
   480  * otherwise.
   481  *
   482  * SDL_SetColors() is equivalent to calling this function with
   483  *     flags = (SDL_LOGPAL|SDL_PHYSPAL).
   484  */
   485 extern DECLSPEC int SDLCALL SDL_SetPalette(SDL_Surface *surface, int flags,
   486 				   SDL_Color *colors, int firstcolor,
   487 				   int ncolors);
   488 
   489 /**
   490  * Maps an RGB triple to an opaque pixel value for a given pixel format
   491  */
   492 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB
   493 (const SDL_PixelFormat * const format,
   494  const Uint8 r, const Uint8 g, const Uint8 b);
   495 
   496 /**
   497  * Maps an RGBA quadruple to a pixel value for a given pixel format
   498  */
   499 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA
   500 (const SDL_PixelFormat * const format,
   501  const Uint8 r, const Uint8 g, const Uint8 b, const Uint8 a);
   502 
   503 /**
   504  * Maps a pixel value into the RGB components for a given pixel format
   505  */
   506 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
   507 				const SDL_PixelFormat * const fmt,
   508 				Uint8 *r, Uint8 *g, Uint8 *b);
   509 
   510 /**
   511  * Maps a pixel value into the RGBA components for a given pixel format
   512  */
   513 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
   514 				const SDL_PixelFormat * const fmt,
   515 				Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
   516 
   517 /** @sa SDL_CreateRGBSurface */
   518 #define SDL_AllocSurface    SDL_CreateRGBSurface
   519 /**
   520  * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
   521  * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
   522  * If the depth is greater than 8 bits, the pixel format is set using the
   523  * flags '[RGB]mask'.
   524  * If the function runs out of memory, it will return NULL.
   525  *
   526  * The 'flags' tell what kind of surface to create.
   527  * SDL_SWSURFACE means that the surface should be created in system memory.
   528  * SDL_HWSURFACE means that the surface should be created in video memory,
   529  * with the same format as the display surface.  This is useful for surfaces
   530  * that will not change much, to take advantage of hardware acceleration
   531  * when being blitted to the display surface.
   532  * SDL_ASYNCBLIT means that SDL will try to perform asynchronous blits with
   533  * this surface, but you must always lock it before accessing the pixels.
   534  * SDL will wait for current blits to finish before returning from the lock.
   535  * SDL_SRCCOLORKEY indicates that the surface will be used for colorkey blits.
   536  * If the hardware supports acceleration of colorkey blits between
   537  * two surfaces in video memory, SDL will try to place the surface in
   538  * video memory. If this isn't possible or if there is no hardware
   539  * acceleration available, the surface will be placed in system memory.
   540  * SDL_SRCALPHA means that the surface will be used for alpha blits and 
   541  * if the hardware supports hardware acceleration of alpha blits between
   542  * two surfaces in video memory, to place the surface in video memory
   543  * if possible, otherwise it will be placed in system memory.
   544  * If the surface is created in video memory, blits will be _much_ faster,
   545  * but the surface format must be identical to the video surface format,
   546  * and the only way to access the pixels member of the surface is to use
   547  * the SDL_LockSurface() and SDL_UnlockSurface() calls.
   548  * If the requested surface actually resides in video memory, SDL_HWSURFACE
   549  * will be set in the flags member of the returned surface.  If for some
   550  * reason the surface could not be placed in video memory, it will not have
   551  * the SDL_HWSURFACE flag set, and will be created in system memory instead.
   552  */
   553 extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurface
   554 			(Uint32 flags, int width, int height, int depth, 
   555 			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
   556 /** @sa SDL_CreateRGBSurface */
   557 extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
   558 			int width, int height, int depth, int pitch,
   559 			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
   560 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface *surface);
   561 
   562 /**
   563  * SDL_LockSurface() sets up a surface for directly accessing the pixels.
   564  * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
   565  * to and read from 'surface->pixels', using the pixel format stored in 
   566  * 'surface->format'.  Once you are done accessing the surface, you should 
   567  * use SDL_UnlockSurface() to release it.
   568  *
   569  * Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
   570  * to 0, then you can read and write to the surface at any time, and the
   571  * pixel format of the surface will not change.  In particular, if the
   572  * SDL_HWSURFACE flag is not given when calling SDL_SetVideoMode(), you
   573  * will not need to lock the display surface before accessing it.
   574  * 
   575  * No operating system or library calls should be made between lock/unlock
   576  * pairs, as critical system locks may be held during this time.
   577  *
   578  * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
   579  */
   580 extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface);
   581 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
   582 
   583 /**
   584  * Load a surface from a seekable SDL data source (memory or file.)
   585  * If 'freesrc' is non-zero, the source will be closed after being read.
   586  * Returns the new surface, or NULL if there was an error.
   587  * The new surface should be freed with SDL_FreeSurface().
   588  */
   589 extern DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, int freesrc);
   590 
   591 /** Convenience macro -- load a surface from a file */
   592 #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
   593 
   594 /**
   595  * Save a surface to a seekable SDL data source (memory or file.)
   596  * If 'freedst' is non-zero, the source will be closed after being written.
   597  * Returns 0 if successful or -1 if there was an error.
   598  */
   599 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
   600 		(SDL_Surface *surface, SDL_RWops *dst, int freedst);
   601 
   602 /** Convenience macro -- save a surface to a file */
   603 #define SDL_SaveBMP(surface, file) \
   604 		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
   605 
   606 /**
   607  * Sets the color key (transparent pixel) in a blittable surface.
   608  * If 'flag' is SDL_SRCCOLORKEY (optionally OR'd with SDL_RLEACCEL), 
   609  * 'key' will be the transparent pixel in the source image of a blit.
   610  * SDL_RLEACCEL requests RLE acceleration for the surface if present,
   611  * and removes RLE acceleration if absent.
   612  * If 'flag' is 0, this function clears any current color key.
   613  * This function returns 0, or -1 if there was an error.
   614  */
   615 extern DECLSPEC int SDLCALL SDL_SetColorKey
   616 			(SDL_Surface *surface, Uint32 flag, Uint32 key);
   617 
   618 /**
   619  * This function sets the alpha value for the entire surface, as opposed to
   620  * using the alpha component of each pixel. This value measures the range
   621  * of transparency of the surface, 0 being completely transparent to 255
   622  * being completely opaque. An 'alpha' value of 255 causes blits to be
   623  * opaque, the source pixels copied to the destination (the default). Note
   624  * that per-surface alpha can be combined with colorkey transparency.
   625  *
   626  * If 'flag' is 0, alpha blending is disabled for the surface.
   627  * If 'flag' is SDL_SRCALPHA, alpha blending is enabled for the surface.
   628  * OR:ing the flag with SDL_RLEACCEL requests RLE acceleration for the
   629  * surface; if SDL_RLEACCEL is not specified, the RLE accel will be removed.
   630  *
   631  * The 'alpha' parameter is ignored for surfaces that have an alpha channel.
   632  */
   633 extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);
   634 
   635 /**
   636  * Sets the clipping rectangle for the destination surface in a blit.
   637  *
   638  * If the clip rectangle is NULL, clipping will be disabled.
   639  * If the clip rectangle doesn't intersect the surface, the function will
   640  * return SDL_FALSE and blits will be completely clipped.  Otherwise the
   641  * function returns SDL_TRUE and blits to the surface will be clipped to
   642  * the intersection of the surface area and the clipping rectangle.
   643  *
   644  * Note that blits are automatically clipped to the edges of the source
   645  * and destination surfaces.
   646  */
   647 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface *surface, const SDL_Rect *rect);
   648 
   649 /**
   650  * Gets the clipping rectangle for the destination surface in a blit.
   651  * 'rect' must be a pointer to a valid rectangle which will be filled
   652  * with the correct values.
   653  */
   654 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rect);
   655 
   656 /**
   657  * Creates a new surface of the specified format, and then copies and maps 
   658  * the given surface to it so the blit of the converted surface will be as 
   659  * fast as possible.  If this function fails, it returns NULL.
   660  *
   661  * The 'flags' parameter is passed to SDL_CreateRGBSurface() and has those 
   662  * semantics.  You can also pass SDL_RLEACCEL in the flags parameter and
   663  * SDL will try to RLE accelerate colorkey and alpha blits in the resulting
   664  * surface.
   665  *
   666  * This function is used internally by SDL_DisplayFormat().
   667  */
   668 extern DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface
   669 			(SDL_Surface *src, SDL_PixelFormat *fmt, Uint32 flags);
   670 
   671 /**
   672  * This performs a fast blit from the source surface to the destination
   673  * surface.  It assumes that the source and destination rectangles are
   674  * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
   675  * surface (src or dst) is copied.  The final blit rectangles are saved
   676  * in 'srcrect' and 'dstrect' after all clipping is performed.
   677  * If the blit is successful, it returns 0, otherwise it returns -1.
   678  *
   679  * The blit function should not be called on a locked surface.
   680  *
   681  * The blit semantics for surfaces with and without alpha and colorkey
   682  * are defined as follows:
   683  *
   684  * RGBA->RGB:
   685  *     SDL_SRCALPHA set:
   686  * 	alpha-blend (using alpha-channel).
   687  * 	SDL_SRCCOLORKEY ignored.
   688  *     SDL_SRCALPHA not set:
   689  * 	copy RGB.
   690  * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
   691  * 	RGB values of the source colour key, ignoring alpha in the
   692  * 	comparison.
   693  * 
   694  * RGB->RGBA:
   695  *     SDL_SRCALPHA set:
   696  * 	alpha-blend (using the source per-surface alpha value);
   697  * 	set destination alpha to opaque.
   698  *     SDL_SRCALPHA not set:
   699  * 	copy RGB, set destination alpha to source per-surface alpha value.
   700  *     both:
   701  * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
   702  * 	source colour key.
   703  * 
   704  * RGBA->RGBA:
   705  *     SDL_SRCALPHA set:
   706  * 	alpha-blend (using the source alpha channel) the RGB values;
   707  * 	leave destination alpha untouched. [Note: is this correct?]
   708  * 	SDL_SRCCOLORKEY ignored.
   709  *     SDL_SRCALPHA not set:
   710  * 	copy all of RGBA to the destination.
   711  * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
   712  * 	RGB values of the source colour key, ignoring alpha in the
   713  * 	comparison.
   714  * 
   715  * RGB->RGB: 
   716  *     SDL_SRCALPHA set:
   717  * 	alpha-blend (using the source per-surface alpha value).
   718  *     SDL_SRCALPHA not set:
   719  * 	copy RGB.
   720  *     both:
   721  * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
   722  * 	source colour key.
   723  *
   724  * If either of the surfaces were in video memory, and the blit returns -2,
   725  * the video memory was lost, so it should be reloaded with artwork and 
   726  * re-blitted:
   727  * @code
   728  *	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
   729  *		while ( SDL_LockSurface(image) < 0 )
   730  *			Sleep(10);
   731  *		-- Write image pixels to image->pixels --
   732  *		SDL_UnlockSurface(image);
   733  *	}
   734  * @endcode
   735  *
   736  * This happens under DirectX 5.0 when the system switches away from your
   737  * fullscreen application.  The lock will also fail until you have access
   738  * to the video memory again.
   739  *
   740  * You should call SDL_BlitSurface() unless you know exactly how SDL
   741  * blitting works internally and how to use the other blit functions.
   742  */
   743 #define SDL_BlitSurface SDL_UpperBlit
   744 
   745 /** This is the public blit function, SDL_BlitSurface(), and it performs
   746  *  rectangle validation and clipping before passing it to SDL_LowerBlit()
   747  */
   748 extern DECLSPEC int SDLCALL SDL_UpperBlit
   749 			(SDL_Surface *src, SDL_Rect *srcrect,
   750 			 SDL_Surface *dst, SDL_Rect *dstrect);
   751 /** This is a semi-private blit function and it performs low-level surface
   752  *  blitting only.
   753  */
   754 extern DECLSPEC int SDLCALL SDL_LowerBlit
   755 			(SDL_Surface *src, SDL_Rect *srcrect,
   756 			 SDL_Surface *dst, SDL_Rect *dstrect);
   757 
   758 /**
   759  * This function performs a fast fill of the given rectangle with 'color'
   760  * The given rectangle is clipped to the destination surface clip area
   761  * and the final fill rectangle is saved in the passed in pointer.
   762  * If 'dstrect' is NULL, the whole surface will be filled with 'color'
   763  * The color should be a pixel of the format used by the surface, and 
   764  * can be generated by the SDL_MapRGB() function.
   765  * This function returns 0 on success, or -1 on error.
   766  */
   767 extern DECLSPEC int SDLCALL SDL_FillRect
   768 		(SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color);
   769 
   770 /**
   771  * This function takes a surface and copies it to a new surface of the
   772  * pixel format and colors of the video framebuffer, suitable for fast
   773  * blitting onto the display surface.  It calls SDL_ConvertSurface()
   774  *
   775  * If you want to take advantage of hardware colorkey or alpha blit
   776  * acceleration, you should set the colorkey and alpha value before
   777  * calling this function.
   778  *
   779  * If the conversion fails or runs out of memory, it returns NULL
   780  */
   781 extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormat(SDL_Surface *surface);
   782 
   783 /**
   784  * This function takes a surface and copies it to a new surface of the
   785  * pixel format and colors of the video framebuffer (if possible),
   786  * suitable for fast alpha blitting onto the display surface.
   787  * The new surface will always have an alpha channel.
   788  *
   789  * If you want to take advantage of hardware colorkey or alpha blit
   790  * acceleration, you should set the colorkey and alpha value before
   791  * calling this function.
   792  *
   793  * If the conversion fails or runs out of memory, it returns NULL
   794  */
   795 extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormatAlpha(SDL_Surface *surface);
   796 
   797 
   798 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   799 /** @name YUV video surface overlay functions                                */ /*@{*/
   800 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   801 
   802 /** This function creates a video output overlay
   803  *  Calling the returned surface an overlay is something of a misnomer because
   804  *  the contents of the display surface underneath the area where the overlay
   805  *  is shown is undefined - it may be overwritten with the converted YUV data.
   806  */
   807 extern DECLSPEC SDL_Overlay * SDLCALL SDL_CreateYUVOverlay(int width, int height,
   808 				Uint32 format, SDL_Surface *display);
   809 
   810 /** Lock an overlay for direct access, and unlock it when you are done */
   811 extern DECLSPEC int SDLCALL SDL_LockYUVOverlay(SDL_Overlay *overlay);
   812 extern DECLSPEC void SDLCALL SDL_UnlockYUVOverlay(SDL_Overlay *overlay);
   813 
   814 /** Blit a video overlay to the display surface.
   815  *  The contents of the video surface underneath the blit destination are
   816  *  not defined.  
   817  *  The width and height of the destination rectangle may be different from
   818  *  that of the overlay, but currently only 2x scaling is supported.
   819  */
   820 extern DECLSPEC int SDLCALL SDL_DisplayYUVOverlay(SDL_Overlay *overlay, SDL_Rect *dstrect);
   821 
   822 /** Free a video overlay */
   823 extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay(SDL_Overlay *overlay);
   824 
   825 /*@}*/
   826 
   827 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   828 /** @name OpenGL support functions.                                          */ /*@{*/
   829 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   830 
   831 /**
   832  * Dynamically load an OpenGL library, or the default one if path is NULL
   833  *
   834  * If you do this, you need to retrieve all of the GL functions used in
   835  * your program from the dynamic library using SDL_GL_GetProcAddress().
   836  */
   837 extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
   838 
   839 /**
   840  * Get the address of a GL function
   841  */
   842 extern DECLSPEC void * SDLCALL SDL_GL_GetProcAddress(const char* proc);
   843 
   844 /**
   845  * Set an attribute of the OpenGL subsystem before intialization.
   846  */
   847 extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
   848 
   849 /**
   850  * Get an attribute of the OpenGL subsystem from the windowing
   851  * interface, such as glX. This is of course different from getting
   852  * the values from SDL's internal OpenGL subsystem, which only
   853  * stores the values you request before initialization.
   854  *
   855  * Developers should track the values they pass into SDL_GL_SetAttribute
   856  * themselves if they want to retrieve these values.
   857  */
   858 extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int* value);
   859 
   860 /**
   861  * Swap the OpenGL buffers, if double-buffering is supported.
   862  */
   863 extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers(void);
   864 
   865 /** @name OpenGL Internal Functions
   866  * Internal functions that should not be called unless you have read
   867  * and understood the source code for these functions.
   868  */
   869 /*@{*/
   870 extern DECLSPEC void SDLCALL SDL_GL_UpdateRects(int numrects, SDL_Rect* rects);
   871 extern DECLSPEC void SDLCALL SDL_GL_Lock(void);
   872 extern DECLSPEC void SDLCALL SDL_GL_Unlock(void);
   873 /*@}*/
   874 
   875 /*@}*/
   876 
   877 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   878 /** @name Window Manager Functions                                           */
   879 /** These functions allow interaction with the window manager, if any.       */ /*@{*/
   880 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   881 
   882 /**
   883  * Sets the title and icon text of the display window (UTF-8 encoded)
   884  */
   885 extern DECLSPEC void SDLCALL SDL_WM_SetCaption(const char *title, const char *icon);
   886 /**
   887  * Gets the title and icon text of the display window (UTF-8 encoded)
   888  */
   889 extern DECLSPEC void SDLCALL SDL_WM_GetCaption(char **title, char **icon);
   890 
   891 /**
   892  * Sets the icon for the display window.
   893  * This function must be called before the first call to SDL_SetVideoMode().
   894  * It takes an icon surface, and a mask in MSB format.
   895  * If 'mask' is NULL, the entire icon surface will be used as the icon.
   896  */
   897 extern DECLSPEC void SDLCALL SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask);
   898 
   899 /**
   900  * This function iconifies the window, and returns 1 if it succeeded.
   901  * If the function succeeds, it generates an SDL_APPACTIVE loss event.
   902  * This function is a noop and returns 0 in non-windowed environments.
   903  */
   904 extern DECLSPEC int SDLCALL SDL_WM_IconifyWindow(void);
   905 
   906 /**
   907  * Toggle fullscreen mode without changing the contents of the screen.
   908  * If the display surface does not require locking before accessing
   909  * the pixel information, then the memory pointers will not change.
   910  *
   911  * If this function was able to toggle fullscreen mode (change from 
   912  * running in a window to fullscreen, or vice-versa), it will return 1.
   913  * If it is not implemented, or fails, it returns 0.
   914  *
   915  * The next call to SDL_SetVideoMode() will set the mode fullscreen
   916  * attribute based on the flags parameter - if SDL_FULLSCREEN is not
   917  * set, then the display will be windowed by default where supported.
   918  *
   919  * This is currently only implemented in the X11 video driver.
   920  */
   921 extern DECLSPEC int SDLCALL SDL_WM_ToggleFullScreen(SDL_Surface *surface);
   922 
   923 typedef enum {
   924 	SDL_GRAB_QUERY = -1,
   925 	SDL_GRAB_OFF = 0,
   926 	SDL_GRAB_ON = 1,
   927 	SDL_GRAB_FULLSCREEN	/**< Used internally */
   928 } SDL_GrabMode;
   929 /**
   930  * This function allows you to set and query the input grab state of
   931  * the application.  It returns the new input grab state.
   932  *
   933  * Grabbing means that the mouse is confined to the application window,
   934  * and nearly all keyboard input is passed directly to the application,
   935  * and not interpreted by a window manager, if any.
   936  */
   937 extern DECLSPEC SDL_GrabMode SDLCALL SDL_WM_GrabInput(SDL_GrabMode mode);
   938 
   939 /*@}*/
   940 
   941 /** @internal Not in public API at the moment - do not use! */
   942 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect,
   943                                     SDL_Surface *dst, SDL_Rect *dstrect);
   944                     
   945 /* Ends C function definitions when using C++ */
   946 #ifdef __cplusplus
   947 }
   948 #endif
   949 #include "close_code.h"
   950 
   951 #endif /* _SDL_video_h */