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