include/SDL_video.h
changeset 337 9154ec9ca3d2
parent 297 f6ffac90895c
child 431 41cadcba32e8
equal deleted inserted replaced
336:745873ea091f 337:9154ec9ca3d2
   235  *
   235  *
   236  * If you use both sound and video in your application, you need to call
   236  * If you use both sound and video in your application, you need to call
   237  * SDL_Init() before opening the sound device, otherwise under Win32 DirectX,
   237  * SDL_Init() before opening the sound device, otherwise under Win32 DirectX,
   238  * you won't be able to set full-screen display modes.
   238  * you won't be able to set full-screen display modes.
   239  */
   239  */
   240 extern DECLSPEC int SDL_VideoInit(const char *driver_name, Uint32 flags);
   240 extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name, Uint32 flags);
   241 extern DECLSPEC void SDL_VideoQuit(void);
   241 extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
   242 
   242 
   243 /* This function fills the given character buffer with the name of the
   243 /* This function fills the given character buffer with the name of the
   244  * video driver, and returns a pointer to it if the video driver has
   244  * video driver, and returns a pointer to it if the video driver has
   245  * been initialized.  It returns NULL if no driver has been initialized.
   245  * been initialized.  It returns NULL if no driver has been initialized.
   246  */
   246  */
   247 extern DECLSPEC char *SDL_VideoDriverName(char *namebuf, int maxlen);
   247 extern DECLSPEC char * SDLCALL SDL_VideoDriverName(char *namebuf, int maxlen);
   248 
   248 
   249 /*
   249 /*
   250  * This function returns a pointer to the current display surface.
   250  * This function returns a pointer to the current display surface.
   251  * If SDL is doing format conversion on the display surface, this
   251  * If SDL is doing format conversion on the display surface, this
   252  * function returns the publicly visible surface, not the real video
   252  * function returns the publicly visible surface, not the real video
   253  * surface.
   253  * surface.
   254  */
   254  */
   255 extern DECLSPEC SDL_Surface * SDL_GetVideoSurface(void);
   255 extern DECLSPEC SDL_Surface * SDLCALL SDL_GetVideoSurface(void);
   256 
   256 
   257 /*
   257 /*
   258  * This function returns a read-only pointer to information about the
   258  * This function returns a read-only pointer to information about the
   259  * video hardware.  If this is called before SDL_SetVideoMode(), the 'vfmt'
   259  * video hardware.  If this is called before SDL_SetVideoMode(), the 'vfmt'
   260  * member of the returned structure will contain the pixel format of the
   260  * member of the returned structure will contain the pixel format of the
   261  * "best" video mode.
   261  * "best" video mode.
   262  */
   262  */
   263 extern DECLSPEC const SDL_VideoInfo * SDL_GetVideoInfo(void);
   263 extern DECLSPEC const SDL_VideoInfo * SDLCALL SDL_GetVideoInfo(void);
   264 
   264 
   265 /* 
   265 /* 
   266  * Check to see if a particular video mode is supported.
   266  * Check to see if a particular video mode is supported.
   267  * It returns 0 if the requested mode is not supported under any bit depth,
   267  * It returns 0 if the requested mode is not supported under any bit depth,
   268  * or returns the bits-per-pixel of the closest available mode with the
   268  * or returns the bits-per-pixel of the closest available mode with the
   271  * but will emulate the requested bits-per-pixel with a shadow surface.
   271  * but will emulate the requested bits-per-pixel with a shadow surface.
   272  *
   272  *
   273  * The arguments to SDL_VideoModeOK() are the same ones you would pass to
   273  * The arguments to SDL_VideoModeOK() are the same ones you would pass to
   274  * SDL_SetVideoMode()
   274  * SDL_SetVideoMode()
   275  */
   275  */
   276 extern DECLSPEC int SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags);
   276 extern DECLSPEC int SDLCALL SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags);
   277 
   277 
   278 /*
   278 /*
   279  * Return a pointer to an array of available screen dimensions for the
   279  * Return a pointer to an array of available screen dimensions for the
   280  * given format and video flags, sorted largest to smallest.  Returns 
   280  * given format and video flags, sorted largest to smallest.  Returns 
   281  * NULL if there are no dimensions available for a particular format, 
   281  * NULL if there are no dimensions available for a particular format, 
   282  * or (SDL_Rect **)-1 if any dimension is okay for the given format.
   282  * or (SDL_Rect **)-1 if any dimension is okay for the given format.
   283  *
   283  *
   284  * If 'format' is NULL, the mode list will be for the format given 
   284  * If 'format' is NULL, the mode list will be for the format given 
   285  * by SDL_GetVideoInfo()->vfmt
   285  * by SDL_GetVideoInfo()->vfmt
   286  */
   286  */
   287 extern DECLSPEC SDL_Rect ** SDL_ListModes(SDL_PixelFormat *format, Uint32 flags);
   287 extern DECLSPEC SDL_Rect ** SDLCALL SDL_ListModes(SDL_PixelFormat *format, Uint32 flags);
   288 
   288 
   289 /*
   289 /*
   290  * Set up a video mode with the specified width, height and bits-per-pixel.
   290  * Set up a video mode with the specified width, height and bits-per-pixel.
   291  *
   291  *
   292  * If 'bpp' is 0, it is treated as the current display bits per pixel.
   292  * If 'bpp' is 0, it is treated as the current display bits per pixel.
   342  * If you rely on functionality provided by certain video flags, check the
   342  * If you rely on functionality provided by certain video flags, check the
   343  * flags of the returned surface to make sure that functionality is available.
   343  * flags of the returned surface to make sure that functionality is available.
   344  * SDL will fall back to reduced functionality if the exact flags you wanted
   344  * SDL will fall back to reduced functionality if the exact flags you wanted
   345  * are not available.
   345  * are not available.
   346  */
   346  */
   347 extern DECLSPEC SDL_Surface *SDL_SetVideoMode
   347 extern DECLSPEC SDL_Surface * SDLCALL SDL_SetVideoMode
   348 			(int width, int height, int bpp, Uint32 flags);
   348 			(int width, int height, int bpp, Uint32 flags);
   349 
   349 
   350 /*
   350 /*
   351  * Makes sure the given list of rectangles is updated on the given screen.
   351  * Makes sure the given list of rectangles is updated on the given screen.
   352  * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
   352  * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
   353  * screen.
   353  * screen.
   354  * These functions should not be called while 'screen' is locked.
   354  * These functions should not be called while 'screen' is locked.
   355  */
   355  */
   356 extern DECLSPEC void SDL_UpdateRects
   356 extern DECLSPEC void SDLCALL SDL_UpdateRects
   357 		(SDL_Surface *screen, int numrects, SDL_Rect *rects);
   357 		(SDL_Surface *screen, int numrects, SDL_Rect *rects);
   358 extern DECLSPEC void SDL_UpdateRect
   358 extern DECLSPEC void SDLCALL SDL_UpdateRect
   359 		(SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
   359 		(SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
   360 
   360 
   361 /*
   361 /*
   362  * On hardware that supports double-buffering, this function sets up a flip
   362  * On hardware that supports double-buffering, this function sets up a flip
   363  * and returns.  The hardware will wait for vertical retrace, and then swap
   363  * and returns.  The hardware will wait for vertical retrace, and then swap
   366  * to calling SDL_UpdateRect(screen, 0, 0, 0, 0);
   366  * to calling SDL_UpdateRect(screen, 0, 0, 0, 0);
   367  * The SDL_DOUBLEBUF flag must have been passed to SDL_SetVideoMode() when
   367  * The SDL_DOUBLEBUF flag must have been passed to SDL_SetVideoMode() when
   368  * setting the video mode for this function to perform hardware flipping.
   368  * setting the video mode for this function to perform hardware flipping.
   369  * This function returns 0 if successful, or -1 if there was an error.
   369  * This function returns 0 if successful, or -1 if there was an error.
   370  */
   370  */
   371 extern DECLSPEC int SDL_Flip(SDL_Surface *screen);
   371 extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface *screen);
   372 
   372 
   373 /*
   373 /*
   374  * Set the gamma correction for each of the color channels.
   374  * Set the gamma correction for each of the color channels.
   375  * The gamma values range (approximately) between 0.1 and 10.0
   375  * The gamma values range (approximately) between 0.1 and 10.0
   376  * 
   376  * 
   377  * If this function isn't supported directly by the hardware, it will
   377  * If this function isn't supported directly by the hardware, it will
   378  * be emulated using gamma ramps, if available.  If successful, this
   378  * be emulated using gamma ramps, if available.  If successful, this
   379  * function returns 0, otherwise it returns -1.
   379  * function returns 0, otherwise it returns -1.
   380  */
   380  */
   381 extern DECLSPEC int SDL_SetGamma(float red, float green, float blue);
   381 extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
   382 
   382 
   383 /*
   383 /*
   384  * Set the gamma translation table for the red, green, and blue channels
   384  * Set the gamma translation table for the red, green, and blue channels
   385  * of the video hardware.  Each table is an array of 256 16-bit quantities,
   385  * of the video hardware.  Each table is an array of 256 16-bit quantities,
   386  * representing a mapping between the input and output for that channel.
   386  * representing a mapping between the input and output for that channel.
   390  * You may pass NULL for any of the channels to leave it unchanged.
   390  * You may pass NULL for any of the channels to leave it unchanged.
   391  * If the call succeeds, it will return 0.  If the display driver or
   391  * If the call succeeds, it will return 0.  If the display driver or
   392  * hardware does not support gamma translation, or otherwise fails,
   392  * hardware does not support gamma translation, or otherwise fails,
   393  * this function will return -1.
   393  * this function will return -1.
   394  */
   394  */
   395 extern DECLSPEC int SDL_SetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
   395 extern DECLSPEC int SDLCALL SDL_SetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
   396 
   396 
   397 /*
   397 /*
   398  * Retrieve the current values of the gamma translation tables.
   398  * Retrieve the current values of the gamma translation tables.
   399  * 
   399  * 
   400  * You must pass in valid pointers to arrays of 256 16-bit quantities.
   400  * You must pass in valid pointers to arrays of 256 16-bit quantities.
   401  * Any of the pointers may be NULL to ignore that channel.
   401  * Any of the pointers may be NULL to ignore that channel.
   402  * If the call succeeds, it will return 0.  If the display driver or
   402  * If the call succeeds, it will return 0.  If the display driver or
   403  * hardware does not support gamma translation, or otherwise fails,
   403  * hardware does not support gamma translation, or otherwise fails,
   404  * this function will return -1.
   404  * this function will return -1.
   405  */
   405  */
   406 extern DECLSPEC int SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
   406 extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
   407 
   407 
   408 /*
   408 /*
   409  * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
   409  * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
   410  * is not a palettized surface, this function does nothing, returning 0.
   410  * is not a palettized surface, this function does nothing, returning 0.
   411  * If all of the colors were set as passed to SDL_SetColors(), it will
   411  * If all of the colors were set as passed to SDL_SetColors(), it will
   418  * SDL_HWPALETTE was set in SDL_SetVideoMode() flags, SDL_SetColors()
   418  * SDL_HWPALETTE was set in SDL_SetVideoMode() flags, SDL_SetColors()
   419  * will always return 1, and the palette is guaranteed to be set the way
   419  * will always return 1, and the palette is guaranteed to be set the way
   420  * you desire, even if the window colormap has to be warped or run under
   420  * you desire, even if the window colormap has to be warped or run under
   421  * emulation.
   421  * emulation.
   422  */
   422  */
   423 extern DECLSPEC int SDL_SetColors(SDL_Surface *surface, 
   423 extern DECLSPEC int SDLCALL SDL_SetColors(SDL_Surface *surface, 
   424 			SDL_Color *colors, int firstcolor, int ncolors);
   424 			SDL_Color *colors, int firstcolor, int ncolors);
   425 
   425 
   426 /*
   426 /*
   427  * Sets a portion of the colormap for a given 8-bit surface.
   427  * Sets a portion of the colormap for a given 8-bit surface.
   428  * 'flags' is one or both of:
   428  * 'flags' is one or both of:
   437  * otherwise.
   437  * otherwise.
   438  *
   438  *
   439  * SDL_SetColors() is equivalent to calling this function with
   439  * SDL_SetColors() is equivalent to calling this function with
   440  *     flags = (SDL_LOGPAL|SDL_PHYSPAL).
   440  *     flags = (SDL_LOGPAL|SDL_PHYSPAL).
   441  */
   441  */
   442 extern DECLSPEC int SDL_SetPalette(SDL_Surface *surface, int flags,
   442 extern DECLSPEC int SDLCALL SDL_SetPalette(SDL_Surface *surface, int flags,
   443 				   SDL_Color *colors, int firstcolor,
   443 				   SDL_Color *colors, int firstcolor,
   444 				   int ncolors);
   444 				   int ncolors);
   445 
   445 
   446 /*
   446 /*
   447  * Maps an RGB triple to an opaque pixel value for a given pixel format
   447  * Maps an RGB triple to an opaque pixel value for a given pixel format
   448  */
   448  */
   449 extern DECLSPEC Uint32 SDL_MapRGB
   449 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB
   450 			(SDL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b);
   450 			(SDL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b);
   451 
   451 
   452 /*
   452 /*
   453  * Maps an RGBA quadruple to a pixel value for a given pixel format
   453  * Maps an RGBA quadruple to a pixel value for a given pixel format
   454  */
   454  */
   455 extern DECLSPEC Uint32 SDL_MapRGBA(SDL_PixelFormat *format,
   455 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(SDL_PixelFormat *format,
   456 				   Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   456 				   Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   457 
   457 
   458 /*
   458 /*
   459  * Maps a pixel value into the RGB components for a given pixel format
   459  * Maps a pixel value into the RGB components for a given pixel format
   460  */
   460  */
   461 extern DECLSPEC void SDL_GetRGB(Uint32 pixel, SDL_PixelFormat *fmt,
   461 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, SDL_PixelFormat *fmt,
   462 				Uint8 *r, Uint8 *g, Uint8 *b);
   462 				Uint8 *r, Uint8 *g, Uint8 *b);
   463 
   463 
   464 /*
   464 /*
   465  * Maps a pixel value into the RGBA components for a given pixel format
   465  * Maps a pixel value into the RGBA components for a given pixel format
   466  */
   466  */
   467 extern DECLSPEC void SDL_GetRGBA(Uint32 pixel, SDL_PixelFormat *fmt,
   467 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, SDL_PixelFormat *fmt,
   468 				 Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
   468 				 Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
   469 
   469 
   470 /*
   470 /*
   471  * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
   471  * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
   472  * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
   472  * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
   500  * will be set in the flags member of the returned surface.  If for some
   500  * will be set in the flags member of the returned surface.  If for some
   501  * reason the surface could not be placed in video memory, it will not have
   501  * reason the surface could not be placed in video memory, it will not have
   502  * the SDL_HWSURFACE flag set, and will be created in system memory instead.
   502  * the SDL_HWSURFACE flag set, and will be created in system memory instead.
   503  */
   503  */
   504 #define SDL_AllocSurface    SDL_CreateRGBSurface
   504 #define SDL_AllocSurface    SDL_CreateRGBSurface
   505 extern DECLSPEC SDL_Surface *SDL_CreateRGBSurface
   505 extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurface
   506 			(Uint32 flags, int width, int height, int depth, 
   506 			(Uint32 flags, int width, int height, int depth, 
   507 			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
   507 			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
   508 extern DECLSPEC SDL_Surface *SDL_CreateRGBSurfaceFrom(void *pixels,
   508 extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
   509 			int width, int height, int depth, int pitch,
   509 			int width, int height, int depth, int pitch,
   510 			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
   510 			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
   511 extern DECLSPEC void SDL_FreeSurface(SDL_Surface *surface);
   511 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface *surface);
   512 
   512 
   513 /*
   513 /*
   514  * SDL_LockSurface() sets up a surface for directly accessing the pixels.
   514  * SDL_LockSurface() sets up a surface for directly accessing the pixels.
   515  * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
   515  * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
   516  * to and read from 'surface->pixels', using the pixel format stored in 
   516  * to and read from 'surface->pixels', using the pixel format stored in 
   526  * No operating system or library calls should be made between lock/unlock
   526  * No operating system or library calls should be made between lock/unlock
   527  * pairs, as critical system locks may be held during this time.
   527  * pairs, as critical system locks may be held during this time.
   528  *
   528  *
   529  * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
   529  * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
   530  */
   530  */
   531 extern DECLSPEC int SDL_LockSurface(SDL_Surface *surface);
   531 extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface);
   532 extern DECLSPEC void SDL_UnlockSurface(SDL_Surface *surface);
   532 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
   533 
   533 
   534 /*
   534 /*
   535  * Load a surface from a seekable SDL data source (memory or file.)
   535  * Load a surface from a seekable SDL data source (memory or file.)
   536  * If 'freesrc' is non-zero, the source will be closed after being read.
   536  * If 'freesrc' is non-zero, the source will be closed after being read.
   537  * Returns the new surface, or NULL if there was an error.
   537  * Returns the new surface, or NULL if there was an error.
   538  * The new surface should be freed with SDL_FreeSurface().
   538  * The new surface should be freed with SDL_FreeSurface().
   539  */
   539  */
   540 extern DECLSPEC SDL_Surface * SDL_LoadBMP_RW(SDL_RWops *src, int freesrc);
   540 extern DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, int freesrc);
   541 
   541 
   542 /* Convenience macro -- load a surface from a file */
   542 /* Convenience macro -- load a surface from a file */
   543 #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
   543 #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
   544 
   544 
   545 /*
   545 /*
   546  * Save a surface to a seekable SDL data source (memory or file.)
   546  * Save a surface to a seekable SDL data source (memory or file.)
   547  * If 'freedst' is non-zero, the source will be closed after being written.
   547  * If 'freedst' is non-zero, the source will be closed after being written.
   548  * Returns 0 if successful or -1 if there was an error.
   548  * Returns 0 if successful or -1 if there was an error.
   549  */
   549  */
   550 extern DECLSPEC int SDL_SaveBMP_RW
   550 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
   551 		(SDL_Surface *surface, SDL_RWops *dst, int freedst);
   551 		(SDL_Surface *surface, SDL_RWops *dst, int freedst);
   552 
   552 
   553 /* Convenience macro -- save a surface to a file */
   553 /* Convenience macro -- save a surface to a file */
   554 #define SDL_SaveBMP(surface, file) \
   554 #define SDL_SaveBMP(surface, file) \
   555 		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
   555 		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
   561  * SDL_RLEACCEL requests RLE acceleration for the surface if present,
   561  * SDL_RLEACCEL requests RLE acceleration for the surface if present,
   562  * and removes RLE acceleration if absent.
   562  * and removes RLE acceleration if absent.
   563  * If 'flag' is 0, this function clears any current color key.
   563  * If 'flag' is 0, this function clears any current color key.
   564  * This function returns 0, or -1 if there was an error.
   564  * This function returns 0, or -1 if there was an error.
   565  */
   565  */
   566 extern DECLSPEC int SDL_SetColorKey
   566 extern DECLSPEC int SDLCALL SDL_SetColorKey
   567 			(SDL_Surface *surface, Uint32 flag, Uint32 key);
   567 			(SDL_Surface *surface, Uint32 flag, Uint32 key);
   568 
   568 
   569 /*
   569 /*
   570  * This function sets the alpha value for the entire surface, as opposed to
   570  * This function sets the alpha value for the entire surface, as opposed to
   571  * using the alpha component of each pixel. This value measures the range
   571  * using the alpha component of each pixel. This value measures the range
   577  * If 'flag' is 0, alpha blending is disabled for the surface.
   577  * If 'flag' is 0, alpha blending is disabled for the surface.
   578  * If 'flag' is SDL_SRCALPHA, alpha blending is enabled for the surface.
   578  * If 'flag' is SDL_SRCALPHA, alpha blending is enabled for the surface.
   579  * OR:ing the flag with SDL_RLEACCEL requests RLE acceleration for the
   579  * OR:ing the flag with SDL_RLEACCEL requests RLE acceleration for the
   580  * surface; if SDL_RLEACCEL is not specified, the RLE accel will be removed.
   580  * surface; if SDL_RLEACCEL is not specified, the RLE accel will be removed.
   581  */
   581  */
   582 extern DECLSPEC int SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);
   582 extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);
   583 
   583 
   584 /*
   584 /*
   585  * Sets the clipping rectangle for the destination surface in a blit.
   585  * Sets the clipping rectangle for the destination surface in a blit.
   586  *
   586  *
   587  * If the clip rectangle is NULL, clipping will be disabled.
   587  * If the clip rectangle is NULL, clipping will be disabled.
   591  * the intersection of the surface area and the clipping rectangle.
   591  * the intersection of the surface area and the clipping rectangle.
   592  *
   592  *
   593  * Note that blits are automatically clipped to the edges of the source
   593  * Note that blits are automatically clipped to the edges of the source
   594  * and destination surfaces.
   594  * and destination surfaces.
   595  */
   595  */
   596 extern DECLSPEC SDL_bool SDL_SetClipRect(SDL_Surface *surface, const SDL_Rect *rect);
   596 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface *surface, const SDL_Rect *rect);
   597 
   597 
   598 /*
   598 /*
   599  * Gets the clipping rectangle for the destination surface in a blit.
   599  * Gets the clipping rectangle for the destination surface in a blit.
   600  * 'rect' must be a pointer to a valid rectangle which will be filled
   600  * 'rect' must be a pointer to a valid rectangle which will be filled
   601  * with the correct values.
   601  * with the correct values.
   602  */
   602  */
   603 extern DECLSPEC void SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rect);
   603 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rect);
   604 
   604 
   605 /*
   605 /*
   606  * Creates a new surface of the specified format, and then copies and maps 
   606  * Creates a new surface of the specified format, and then copies and maps 
   607  * the given surface to it so the blit of the converted surface will be as 
   607  * the given surface to it so the blit of the converted surface will be as 
   608  * fast as possible.  If this function fails, it returns NULL.
   608  * fast as possible.  If this function fails, it returns NULL.
   612  * SDL will try to RLE accelerate colorkey and alpha blits in the resulting
   612  * SDL will try to RLE accelerate colorkey and alpha blits in the resulting
   613  * surface.
   613  * surface.
   614  *
   614  *
   615  * This function is used internally by SDL_DisplayFormat().
   615  * This function is used internally by SDL_DisplayFormat().
   616  */
   616  */
   617 extern DECLSPEC SDL_Surface *SDL_ConvertSurface
   617 extern DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface
   618 			(SDL_Surface *src, SDL_PixelFormat *fmt, Uint32 flags);
   618 			(SDL_Surface *src, SDL_PixelFormat *fmt, Uint32 flags);
   619 
   619 
   620 /*
   620 /*
   621  * This performs a fast blit from the source surface to the destination
   621  * This performs a fast blit from the source surface to the destination
   622  * surface.  It assumes that the source and destination rectangles are
   622  * surface.  It assumes that the source and destination rectangles are
   689 #define SDL_BlitSurface SDL_UpperBlit
   689 #define SDL_BlitSurface SDL_UpperBlit
   690 
   690 
   691 /* This is the public blit function, SDL_BlitSurface(), and it performs
   691 /* This is the public blit function, SDL_BlitSurface(), and it performs
   692    rectangle validation and clipping before passing it to SDL_LowerBlit()
   692    rectangle validation and clipping before passing it to SDL_LowerBlit()
   693 */
   693 */
   694 extern DECLSPEC int SDL_UpperBlit
   694 extern DECLSPEC int SDLCALL SDL_UpperBlit
   695 			(SDL_Surface *src, SDL_Rect *srcrect,
   695 			(SDL_Surface *src, SDL_Rect *srcrect,
   696 			 SDL_Surface *dst, SDL_Rect *dstrect);
   696 			 SDL_Surface *dst, SDL_Rect *dstrect);
   697 /* This is a semi-private blit function and it performs low-level surface
   697 /* This is a semi-private blit function and it performs low-level surface
   698    blitting only.
   698    blitting only.
   699 */
   699 */
   700 extern DECLSPEC int SDL_LowerBlit
   700 extern DECLSPEC int SDLCALL SDL_LowerBlit
   701 			(SDL_Surface *src, SDL_Rect *srcrect,
   701 			(SDL_Surface *src, SDL_Rect *srcrect,
   702 			 SDL_Surface *dst, SDL_Rect *dstrect);
   702 			 SDL_Surface *dst, SDL_Rect *dstrect);
   703 
   703 
   704 /*
   704 /*
   705  * This function performs a fast fill of the given rectangle with 'color'
   705  * This function performs a fast fill of the given rectangle with 'color'
   708  * If 'dstrect' is NULL, the whole surface will be filled with 'color'
   708  * If 'dstrect' is NULL, the whole surface will be filled with 'color'
   709  * The color should be a pixel of the format used by the surface, and 
   709  * The color should be a pixel of the format used by the surface, and 
   710  * can be generated by the SDL_MapRGB() function.
   710  * can be generated by the SDL_MapRGB() function.
   711  * This function returns 0 on success, or -1 on error.
   711  * This function returns 0 on success, or -1 on error.
   712  */
   712  */
   713 extern DECLSPEC int SDL_FillRect
   713 extern DECLSPEC int SDLCALL SDL_FillRect
   714 		(SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color);
   714 		(SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color);
   715 
   715 
   716 /* 
   716 /* 
   717  * This function takes a surface and copies it to a new surface of the
   717  * This function takes a surface and copies it to a new surface of the
   718  * pixel format and colors of the video framebuffer, suitable for fast
   718  * pixel format and colors of the video framebuffer, suitable for fast
   722  * acceleration, you should set the colorkey and alpha value before
   722  * acceleration, you should set the colorkey and alpha value before
   723  * calling this function.
   723  * calling this function.
   724  *
   724  *
   725  * If the conversion fails or runs out of memory, it returns NULL
   725  * If the conversion fails or runs out of memory, it returns NULL
   726  */
   726  */
   727 extern DECLSPEC SDL_Surface * SDL_DisplayFormat(SDL_Surface *surface);
   727 extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormat(SDL_Surface *surface);
   728 
   728 
   729 /* 
   729 /* 
   730  * This function takes a surface and copies it to a new surface of the
   730  * This function takes a surface and copies it to a new surface of the
   731  * pixel format and colors of the video framebuffer (if possible),
   731  * pixel format and colors of the video framebuffer (if possible),
   732  * suitable for fast alpha blitting onto the display surface.
   732  * suitable for fast alpha blitting onto the display surface.
   736  * acceleration, you should set the colorkey and alpha value before
   736  * acceleration, you should set the colorkey and alpha value before
   737  * calling this function.
   737  * calling this function.
   738  *
   738  *
   739  * If the conversion fails or runs out of memory, it returns NULL
   739  * If the conversion fails or runs out of memory, it returns NULL
   740  */
   740  */
   741 extern DECLSPEC SDL_Surface * SDL_DisplayFormatAlpha(SDL_Surface *surface);
   741 extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormatAlpha(SDL_Surface *surface);
   742 
   742 
   743 
   743 
   744 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   744 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   745 /* YUV video surface overlay functions                                       */
   745 /* YUV video surface overlay functions                                       */
   746 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   746 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   748 /* This function creates a video output overlay
   748 /* This function creates a video output overlay
   749    Calling the returned surface an overlay is something of a misnomer because
   749    Calling the returned surface an overlay is something of a misnomer because
   750    the contents of the display surface underneath the area where the overlay
   750    the contents of the display surface underneath the area where the overlay
   751    is shown is undefined - it may be overwritten with the converted YUV data.
   751    is shown is undefined - it may be overwritten with the converted YUV data.
   752 */
   752 */
   753 extern DECLSPEC SDL_Overlay *SDL_CreateYUVOverlay(int width, int height,
   753 extern DECLSPEC SDL_Overlay * SDLCALL SDL_CreateYUVOverlay(int width, int height,
   754 				Uint32 format, SDL_Surface *display);
   754 				Uint32 format, SDL_Surface *display);
   755 
   755 
   756 /* Lock an overlay for direct access, and unlock it when you are done */
   756 /* Lock an overlay for direct access, and unlock it when you are done */
   757 extern DECLSPEC int SDL_LockYUVOverlay(SDL_Overlay *overlay);
   757 extern DECLSPEC int SDLCALL SDL_LockYUVOverlay(SDL_Overlay *overlay);
   758 extern DECLSPEC void SDL_UnlockYUVOverlay(SDL_Overlay *overlay);
   758 extern DECLSPEC void SDLCALL SDL_UnlockYUVOverlay(SDL_Overlay *overlay);
   759 
   759 
   760 /* Blit a video overlay to the display surface.
   760 /* Blit a video overlay to the display surface.
   761    The contents of the video surface underneath the blit destination are
   761    The contents of the video surface underneath the blit destination are
   762    not defined.  
   762    not defined.  
   763    The width and height of the destination rectangle may be different from
   763    The width and height of the destination rectangle may be different from
   764    that of the overlay, but currently only 2x scaling is supported.
   764    that of the overlay, but currently only 2x scaling is supported.
   765 */
   765 */
   766 extern DECLSPEC int SDL_DisplayYUVOverlay(SDL_Overlay *overlay, SDL_Rect *dstrect);
   766 extern DECLSPEC int SDLCALL SDL_DisplayYUVOverlay(SDL_Overlay *overlay, SDL_Rect *dstrect);
   767 
   767 
   768 /* Free a video overlay */
   768 /* Free a video overlay */
   769 extern DECLSPEC void SDL_FreeYUVOverlay(SDL_Overlay *overlay);
   769 extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay(SDL_Overlay *overlay);
   770 
   770 
   771 
   771 
   772 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   772 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   773 /* OpenGL support functions.                                                 */
   773 /* OpenGL support functions.                                                 */
   774 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   774 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   781  * If you do this, you need to retrieve all of the GL functions used in
   781  * If you do this, you need to retrieve all of the GL functions used in
   782  * your program from the dynamic library using SDL_GL_GetProcAddress().
   782  * your program from the dynamic library using SDL_GL_GetProcAddress().
   783  *
   783  *
   784  * This is disabled in default builds of SDL.
   784  * This is disabled in default builds of SDL.
   785  */
   785  */
   786 extern DECLSPEC int SDL_GL_LoadLibrary(const char *path);
   786 extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
   787 
   787 
   788 /*
   788 /*
   789  * Get the address of a GL function (for extension functions)
   789  * Get the address of a GL function (for extension functions)
   790  */
   790  */
   791 extern DECLSPEC void *SDL_GL_GetProcAddress(const char* proc);
   791 extern DECLSPEC void * SDLCALL SDL_GL_GetProcAddress(const char* proc);
   792 
   792 
   793 /*
   793 /*
   794  * Set an attribute of the OpenGL subsystem before intialization.
   794  * Set an attribute of the OpenGL subsystem before intialization.
   795  */
   795  */
   796 extern DECLSPEC int SDL_GL_SetAttribute(SDL_GLattr attr, int value);
   796 extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
   797 
   797 
   798 /*
   798 /*
   799  * Get an attribute of the OpenGL subsystem from the windowing
   799  * Get an attribute of the OpenGL subsystem from the windowing
   800  * interface, such as glX. This is of course different from getting
   800  * interface, such as glX. This is of course different from getting
   801  * the values from SDL's internal OpenGL subsystem, which only
   801  * the values from SDL's internal OpenGL subsystem, which only
   802  * stores the values you request before initialization.
   802  * stores the values you request before initialization.
   803  *
   803  *
   804  * Developers should track the values they pass into SDL_GL_SetAttribute
   804  * Developers should track the values they pass into SDL_GL_SetAttribute
   805  * themselves if they want to retrieve these values.
   805  * themselves if they want to retrieve these values.
   806  */
   806  */
   807 extern DECLSPEC int SDL_GL_GetAttribute(SDL_GLattr attr, int* value);
   807 extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int* value);
   808 
   808 
   809 /*
   809 /*
   810  * Swap the OpenGL buffers, if double-buffering is supported.
   810  * Swap the OpenGL buffers, if double-buffering is supported.
   811  */
   811  */
   812 extern DECLSPEC void SDL_GL_SwapBuffers(void);
   812 extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers(void);
   813 
   813 
   814 /*
   814 /*
   815  * Internal functions that should not be called unless you have read
   815  * Internal functions that should not be called unless you have read
   816  * and understood the source code for these functions.
   816  * and understood the source code for these functions.
   817  */
   817  */
   818 extern DECLSPEC void SDL_GL_UpdateRects(int numrects, SDL_Rect* rects);
   818 extern DECLSPEC void SDLCALL SDL_GL_UpdateRects(int numrects, SDL_Rect* rects);
   819 extern DECLSPEC void SDL_GL_Lock(void);
   819 extern DECLSPEC void SDLCALL SDL_GL_Lock(void);
   820 extern DECLSPEC void SDL_GL_Unlock(void);
   820 extern DECLSPEC void SDLCALL SDL_GL_Unlock(void);
   821 
   821 
   822 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   822 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   823 /* These functions allow interaction with the window manager, if any.        */
   823 /* These functions allow interaction with the window manager, if any.        */
   824 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   824 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   825 
   825 
   826 /*
   826 /*
   827  * Sets/Gets the title and icon text of the display window
   827  * Sets/Gets the title and icon text of the display window
   828  */
   828  */
   829 extern DECLSPEC void SDL_WM_SetCaption(const char *title, const char *icon);
   829 extern DECLSPEC void SDLCALL SDL_WM_SetCaption(const char *title, const char *icon);
   830 extern DECLSPEC void SDL_WM_GetCaption(char **title, char **icon);
   830 extern DECLSPEC void SDLCALL SDL_WM_GetCaption(char **title, char **icon);
   831 
   831 
   832 /*
   832 /*
   833  * Sets the icon for the display window.
   833  * Sets the icon for the display window.
   834  * This function must be called before the first call to SDL_SetVideoMode().
   834  * This function must be called before the first call to SDL_SetVideoMode().
   835  * It takes an icon surface, and a mask in MSB format.
   835  * It takes an icon surface, and a mask in MSB format.
   836  * If 'mask' is NULL, the entire icon surface will be used as the icon.
   836  * If 'mask' is NULL, the entire icon surface will be used as the icon.
   837  */
   837  */
   838 extern DECLSPEC void SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask);
   838 extern DECLSPEC void SDLCALL SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask);
   839 
   839 
   840 /*
   840 /*
   841  * This function iconifies the window, and returns 1 if it succeeded.
   841  * This function iconifies the window, and returns 1 if it succeeded.
   842  * If the function succeeds, it generates an SDL_APPACTIVE loss event.
   842  * If the function succeeds, it generates an SDL_APPACTIVE loss event.
   843  * This function is a noop and returns 0 in non-windowed environments.
   843  * This function is a noop and returns 0 in non-windowed environments.
   844  */
   844  */
   845 extern DECLSPEC int SDL_WM_IconifyWindow(void);
   845 extern DECLSPEC int SDLCALL SDL_WM_IconifyWindow(void);
   846 
   846 
   847 /*
   847 /*
   848  * Toggle fullscreen mode without changing the contents of the screen.
   848  * Toggle fullscreen mode without changing the contents of the screen.
   849  * If the display surface does not require locking before accessing
   849  * If the display surface does not require locking before accessing
   850  * the pixel information, then the memory pointers will not change.
   850  * the pixel information, then the memory pointers will not change.
   857  * attribute based on the flags parameter - if SDL_FULLSCREEN is not
   857  * attribute based on the flags parameter - if SDL_FULLSCREEN is not
   858  * set, then the display will be windowed by default where supported.
   858  * set, then the display will be windowed by default where supported.
   859  *
   859  *
   860  * This is currently only implemented in the X11 video driver.
   860  * This is currently only implemented in the X11 video driver.
   861  */
   861  */
   862 extern DECLSPEC int SDL_WM_ToggleFullScreen(SDL_Surface *surface);
   862 extern DECLSPEC int SDLCALL SDL_WM_ToggleFullScreen(SDL_Surface *surface);
   863 
   863 
   864 /*
   864 /*
   865  * This function allows you to set and query the input grab state of
   865  * This function allows you to set and query the input grab state of
   866  * the application.  It returns the new input grab state.
   866  * the application.  It returns the new input grab state.
   867  */
   867  */
   874 /*
   874 /*
   875  * Grabbing means that the mouse is confined to the application window,
   875  * Grabbing means that the mouse is confined to the application window,
   876  * and nearly all keyboard input is passed directly to the application,
   876  * and nearly all keyboard input is passed directly to the application,
   877  * and not interpreted by a window manager, if any.
   877  * and not interpreted by a window manager, if any.
   878  */
   878  */
   879 extern DECLSPEC SDL_GrabMode SDL_WM_GrabInput(SDL_GrabMode mode);
   879 extern DECLSPEC SDL_GrabMode SDLCALL SDL_WM_GrabInput(SDL_GrabMode mode);
   880 
   880 
   881 /* Not in public API at the moment - do not use! */
   881 /* Not in public API at the moment - do not use! */
   882 extern DECLSPEC int SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect,
   882 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect,
   883                                     SDL_Surface *dst, SDL_Rect *dstrect);
   883                                     SDL_Surface *dst, SDL_Rect *dstrect);
   884                     
   884                     
   885 /* Ends C function definitions when using C++ */
   885 /* Ends C function definitions when using C++ */
   886 #ifdef __cplusplus
   886 #ifdef __cplusplus
   887 }
   887 }