00001 /* 00002 SDL - Simple DirectMedia Layer 00003 Copyright (C) 1997-2009 Sam Lantinga 00004 00005 This library is free software; you can redistribute it and/or 00006 modify it under the terms of the GNU Lesser General Public 00007 License as published by the Free Software Foundation; either 00008 version 2.1 of the License, or (at your option) any later version. 00009 00010 This library is distributed in the hope that it will be useful, 00011 but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00013 Lesser General Public License for more details. 00014 00015 You should have received a copy of the GNU Lesser General Public 00016 License along with this library; if not, write to the Free Software 00017 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 00018 00019 Sam Lantinga 00020 slouken@libsdl.org 00021 */ 00022 00029 #ifndef _SDL_surface_h 00030 #define _SDL_surface_h 00031 00032 #include "SDL_stdinc.h" 00033 #include "SDL_pixels.h" 00034 #include "SDL_rect.h" 00035 #include "SDL_rwops.h" 00036 00037 #include "begin_code.h" 00038 /* Set up for C function definitions, even when using C++ */ 00039 #ifdef __cplusplus 00040 /* *INDENT-OFF* */ 00041 extern "C" { 00042 /* *INDENT-ON* */ 00043 #endif 00044 00045 /* These are the currently supported flags for the SDL_surface */ 00046 /* Used internally (read-only) */ 00047 #define SDL_PREALLOC 0x00000001 /* Surface uses preallocated memory */ 00048 #define SDL_RLEACCEL 0x00000002 /* Surface is RLE encoded */ 00049 00050 /* Evaluates to true if the surface needs to be locked before access */ 00051 #define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0) 00052 00061 typedef struct SDL_Surface 00062 { 00063 Uint32 flags; 00064 SDL_PixelFormat *format; 00065 int w, h; 00066 int pitch; 00067 void *pixels; 00069 /* Application data associated with the surfade */ 00070 void *userdata; 00072 /* information needed for surfaces requiring locks */ 00073 int locked; 00074 void *lock_data; 00076 /* clipping information */ 00077 SDL_Rect clip_rect; 00079 /* info for fast blit mapping to other surfaces */ 00080 struct SDL_BlitMap *map; 00082 /* format version, bumped at every change to invalidate blit maps */ 00083 unsigned int format_version; 00085 /* Reference count -- used when freeing surface */ 00086 int refcount; 00087 } SDL_Surface; 00088 00094 typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect, 00095 struct SDL_Surface * dst, SDL_Rect * dstrect); 00096 00097 /* 00098 * Allocate and free an RGB surface (must be called after SDL_SetVideoMode) 00099 * If the depth is 4 or 8 bits, an empty palette is allocated for the surface. 00100 * If the depth is greater than 8 bits, the pixel format is set using the 00101 * flags '[RGB]mask'. 00102 * If the function runs out of memory, it will return NULL. 00103 * 00104 * The 'flags' are obsolete and should be set to 0. 00105 */ 00106 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface 00107 (Uint32 flags, int width, int height, int depth, 00108 Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask); 00109 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels, 00110 int width, 00111 int height, 00112 int depth, 00113 int pitch, 00114 Uint32 Rmask, 00115 Uint32 Gmask, 00116 Uint32 Bmask, 00117 Uint32 Amask); 00118 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface); 00119 00129 extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface, 00130 SDL_Palette * palette); 00131 00132 /* 00133 * SDL_LockSurface() sets up a surface for directly accessing the pixels. 00134 * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write 00135 * to and read from 'surface->pixels', using the pixel format stored in 00136 * 'surface->format'. Once you are done accessing the surface, you should 00137 * use SDL_UnlockSurface() to release it. 00138 * 00139 * Not all surfaces require locking. If SDL_MUSTLOCK(surface) evaluates 00140 * to 0, then you can read and write to the surface at any time, and the 00141 * pixel format of the surface will not change. 00142 * 00143 * No operating system or library calls should be made between lock/unlock 00144 * pairs, as critical system locks may be held during this time. 00145 * 00146 * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked. 00147 */ 00148 extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface); 00149 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface); 00150 00151 /* 00152 * Load a surface from a seekable SDL data source (memory or file.) 00153 * If 'freesrc' is non-zero, the source will be closed after being read. 00154 * Returns the new surface, or NULL if there was an error. 00155 * The new surface should be freed with SDL_FreeSurface(). 00156 */ 00157 extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src, 00158 int freesrc); 00159 00160 /* Convenience macro -- load a surface from a file */ 00161 #define SDL_LoadBMP(file) SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1) 00162 00163 /* 00164 * Save a surface to a seekable SDL data source (memory or file.) 00165 * If 'freedst' is non-zero, the source will be closed after being written. 00166 * Returns 0 if successful or -1 if there was an error. 00167 */ 00168 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW 00169 (SDL_Surface * surface, SDL_RWops * dst, int freedst); 00170 00171 /* Convenience macro -- save a surface to a file */ 00172 #define SDL_SaveBMP(surface, file) \ 00173 SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1) 00174 00175 /* 00176 * \fn int SDL_SetSurfaceRLE(SDL_Surface *surface, int flag) 00177 * 00178 * \brief Sets the RLE acceleration hint for a surface. 00179 * 00180 * \return 0 on success, or -1 if the surface is not valid 00181 * 00182 * \note If RLE is enabled, colorkey and alpha blending blits are much faster, 00183 * but the surface must be locked before directly accessing the pixels. 00184 */ 00185 extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface, 00186 int flag); 00187 00188 /* 00189 * \fn int SDL_SetColorKey(SDL_Surface *surface, Uint32 flag, Uint32 key) 00190 * 00191 * \brief Sets the color key (transparent pixel) in a blittable surface. 00192 * 00193 * \param surface The surface to update 00194 * \param flag Non-zero to enable colorkey and 0 to disable colorkey 00195 * \param key The transparent pixel in the native surface format 00196 * 00197 * \return 0 on success, or -1 if the surface is not valid 00198 */ 00199 extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface, 00200 Uint32 flag, Uint32 key); 00201 00202 /* 00203 * \fn int SDL_GetColorKey(SDL_Surface *surface, Uint32 *key) 00204 * 00205 * \brief Sets the color key (transparent pixel) in a blittable surface. 00206 * 00207 * \param surface The surface to update 00208 * \param key A pointer filled in with the transparent pixel in the native surface format 00209 * 00210 * \return 0 on success, or -1 if the surface is not valid or colorkey is not enabled. 00211 */ 00212 extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface, 00213 Uint32 * key); 00214 00229 extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface, 00230 Uint8 r, Uint8 g, Uint8 b); 00231 00232 00247 extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface, 00248 Uint8 * r, Uint8 * g, 00249 Uint8 * b); 00250 00263 extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface, 00264 Uint8 alpha); 00265 00278 extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface, 00279 Uint8 * alpha); 00280 00293 extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface, 00294 int blendMode); 00295 00308 extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface, 00309 int *blendMode); 00310 00325 extern DECLSPEC int SDLCALL SDL_SetSurfaceScaleMode(SDL_Surface * surface, 00326 int scaleMode); 00327 00340 extern DECLSPEC int SDLCALL SDL_GetSurfaceScaleMode(SDL_Surface * surface, 00341 int *scaleMode); 00342 00343 /* 00344 * Sets the clipping rectangle for the destination surface in a blit. 00345 * 00346 * If the clip rectangle is NULL, clipping will be disabled. 00347 * If the clip rectangle doesn't intersect the surface, the function will 00348 * return SDL_FALSE and blits will be completely clipped. Otherwise the 00349 * function returns SDL_TRUE and blits to the surface will be clipped to 00350 * the intersection of the surface area and the clipping rectangle. 00351 * 00352 * Note that blits are automatically clipped to the edges of the source 00353 * and destination surfaces. 00354 */ 00355 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface, 00356 const SDL_Rect * rect); 00357 00358 /* 00359 * Gets the clipping rectangle for the destination surface in a blit. 00360 * 'rect' must be a pointer to a valid rectangle which will be filled 00361 * with the correct values. 00362 */ 00363 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface, 00364 SDL_Rect * rect); 00365 00366 /* 00367 * Creates a new surface of the specified format, and then copies and maps 00368 * the given surface to it so the blit of the converted surface will be as 00369 * fast as possible. If this function fails, it returns NULL. 00370 * 00371 * The 'flags' parameter is passed to SDL_CreateRGBSurface() and has those 00372 * semantics. You can also pass SDL_RLEACCEL in the flags parameter and 00373 * SDL will try to RLE accelerate colorkey and alpha blits in the resulting 00374 * surface. 00375 * 00376 * This function is used internally by SDL_DisplayFormat(). 00377 */ 00378 extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface 00379 (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags); 00380 00381 /* 00382 * This function draws a point with 'color' 00383 * The color should be a pixel of the format used by the surface, and 00384 * can be generated by the SDL_MapRGB() function. 00385 * This function returns 0 on success, or -1 on error. 00386 */ 00387 extern DECLSPEC int SDLCALL SDL_DrawPoint 00388 (SDL_Surface * dst, int x, int y, Uint32 color); 00389 00390 /* 00391 * This function blends a point with an RGBA value 00392 * The color should be a pixel of the format used by the surface, and 00393 * can be generated by the SDL_MapRGB() function. 00394 * This function returns 0 on success, or -1 on error. 00395 */ 00396 extern DECLSPEC int SDLCALL SDL_BlendPoint 00397 (SDL_Surface * dst, int x, int y, int blendMode, 00398 Uint8 r, Uint8 g, Uint8 b, Uint8 a); 00399 00400 /* 00401 * This function draws a line with 'color' 00402 * The color should be a pixel of the format used by the surface, and 00403 * can be generated by the SDL_MapRGB() function. 00404 * This function returns 0 on success, or -1 on error. 00405 */ 00406 extern DECLSPEC int SDLCALL SDL_DrawLine 00407 (SDL_Surface * dst, int x1, int y1, int x2, int y2, Uint32 color); 00408 00409 /* 00410 * This function blends an RGBA value along a line 00411 * This function returns 0 on success, or -1 on error. 00412 */ 00413 extern DECLSPEC int SDLCALL SDL_BlendLine 00414 (SDL_Surface * dst, int x1, int y1, int x2, int y2, int blendMode, 00415 Uint8 r, Uint8 g, Uint8 b, Uint8 a); 00416 00417 /* 00418 * This function performs a fast fill of the given rectangle with 'color' 00419 * The given rectangle is clipped to the destination surface clip area 00420 * and the final fill rectangle is saved in the passed in pointer. 00421 * If 'dstrect' is NULL, the whole surface will be filled with 'color' 00422 * The color should be a pixel of the format used by the surface, and 00423 * can be generated by the SDL_MapRGB() function. 00424 * This function returns 0 on success, or -1 on error. 00425 */ 00426 extern DECLSPEC int SDLCALL SDL_FillRect 00427 (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color); 00428 00429 /* 00430 * This function blends an RGBA value into the given rectangle. 00431 * The given rectangle is clipped to the destination surface clip area 00432 * and the final fill rectangle is saved in the passed in pointer. 00433 * If 'dstrect' is NULL, the whole surface will be filled with 'color' 00434 * This function returns 0 on success, or -1 on error. 00435 */ 00436 extern DECLSPEC int SDLCALL SDL_BlendRect 00437 (SDL_Surface * dst, SDL_Rect * dstrect, int blendMode, Uint8 r, Uint8 g, 00438 Uint8 b, Uint8 a); 00439 00440 /* 00441 * This performs a fast blit from the source surface to the destination 00442 * surface. It assumes that the source and destination rectangles are 00443 * the same size. If either 'srcrect' or 'dstrect' are NULL, the entire 00444 * surface (src or dst) is copied. The final blit rectangles are saved 00445 * in 'srcrect' and 'dstrect' after all clipping is performed. 00446 * If the blit is successful, it returns 0, otherwise it returns -1. 00447 * 00448 * The blit function should not be called on a locked surface. 00449 * 00450 * The blit semantics for surfaces with and without alpha and colorkey 00451 * are defined as follows: 00452 * 00453 * RGBA->RGB: 00454 * SDL_SRCALPHA set: 00455 * alpha-blend (using alpha-channel). 00456 * SDL_SRCCOLORKEY ignored. 00457 * SDL_SRCALPHA not set: 00458 * copy RGB. 00459 * if SDL_SRCCOLORKEY set, only copy the pixels matching the 00460 * RGB values of the source colour key, ignoring alpha in the 00461 * comparison. 00462 * 00463 * RGB->RGBA: 00464 * SDL_SRCALPHA set: 00465 * alpha-blend (using the source per-surface alpha value); 00466 * set destination alpha to opaque. 00467 * SDL_SRCALPHA not set: 00468 * copy RGB, set destination alpha to source per-surface alpha value. 00469 * both: 00470 * if SDL_SRCCOLORKEY set, only copy the pixels matching the 00471 * source colour key. 00472 * 00473 * RGBA->RGBA: 00474 * SDL_SRCALPHA set: 00475 * alpha-blend (using the source alpha channel) the RGB values; 00476 * leave destination alpha untouched. [Note: is this correct?] 00477 * SDL_SRCCOLORKEY ignored. 00478 * SDL_SRCALPHA not set: 00479 * copy all of RGBA to the destination. 00480 * if SDL_SRCCOLORKEY set, only copy the pixels matching the 00481 * RGB values of the source colour key, ignoring alpha in the 00482 * comparison. 00483 * 00484 * RGB->RGB: 00485 * SDL_SRCALPHA set: 00486 * alpha-blend (using the source per-surface alpha value). 00487 * SDL_SRCALPHA not set: 00488 * copy RGB. 00489 * both: 00490 * if SDL_SRCCOLORKEY set, only copy the pixels matching the 00491 * source colour key. 00492 * 00493 * If either of the surfaces were in video memory, and the blit returns -2, 00494 * the video memory was lost, so it should be reloaded with artwork and 00495 * re-blitted: 00496 while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) { 00497 while ( SDL_LockSurface(image) < 0 ) 00498 Sleep(10); 00499 -- Write image pixels to image->pixels -- 00500 SDL_UnlockSurface(image); 00501 } 00502 * This happens under DirectX 5.0 when the system switches away from your 00503 * fullscreen application. The lock will also fail until you have access 00504 * to the video memory again. 00505 */ 00506 /* You should call SDL_BlitSurface() unless you know exactly how SDL 00507 blitting works internally and how to use the other blit functions. 00508 */ 00509 #define SDL_BlitSurface SDL_UpperBlit 00510 00511 /* This is the public blit function, SDL_BlitSurface(), and it performs 00512 rectangle validation and clipping before passing it to SDL_LowerBlit() 00513 */ 00514 extern DECLSPEC int SDLCALL SDL_UpperBlit 00515 (SDL_Surface * src, SDL_Rect * srcrect, 00516 SDL_Surface * dst, SDL_Rect * dstrect); 00517 /* This is a semi-private blit function and it performs low-level surface 00518 blitting only. 00519 */ 00520 extern DECLSPEC int SDLCALL SDL_LowerBlit 00521 (SDL_Surface * src, SDL_Rect * srcrect, 00522 SDL_Surface * dst, SDL_Rect * dstrect); 00523 00531 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src, 00532 const SDL_Rect * srcrect, 00533 SDL_Surface * dst, 00534 const SDL_Rect * dstrect); 00535 00536 /* Ends C function definitions when using C++ */ 00537 #ifdef __cplusplus 00538 /* *INDENT-OFF* */ 00539 } 00540 /* *INDENT-ON* */ 00541 #endif 00542 #include "close_code.h" 00543 00544 #endif /* _SDL_surface_h */ 00545 00546 /* vi: set ts=4 sw=4 expandtab: */
1.5.8