1 /* 2 SDL - Simple DirectMedia Layer 3 Copyright (C) 1997-2012 Sam Lantinga 4 5 This library is free software; you can redistribute it and/or 6 modify it under the terms of the GNU Lesser General Public 7 License as published by the Free Software Foundation; either 8 version 2.1 of the License, or (at your option) any later version. 9 10 This library is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Lesser General Public License for more details. 14 15 You should have received a copy of the GNU Lesser General Public 16 License along with this library; if not, write to the Free Software 17 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 18 19 Sam Lantinga 20 slouken@libsdl.org 21 */ 22 23 /** @file SDL_video.h 24 * Header file for access to the SDL raw framebuffer window 25 */ 26 27 #ifndef _LRSDL_video_h 28 #define _LRSDL_video_h 29 30 #include "LRSDL_stdinc.h" 31 #include "LRSDL_error.h" 32 #include "LRSDL_rwops.h" 33 34 #include "begin_code.h" 35 /* Set up for C function definitions, even when using C++ */ 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /** @name Transparency definitions 41 * These define alpha as the opacity of a surface 42 */ 43 /*@{*/ 44 #define SDL_ALPHA_OPAQUE 255 45 #define SDL_ALPHA_TRANSPARENT 0 46 /*@}*/ 47 48 /** @name Useful data types */ 49 /*@{*/ 50 typedef struct SDL_Rect { 51 Sint16 x, y; 52 Uint16 w, h; 53 } SDL_Rect; 54 55 typedef struct SDL_Color { 56 Uint8 r; 57 Uint8 g; 58 Uint8 b; 59 Uint8 unused; 60 } SDL_Color; 61 #define SDL_Colour SDL_Color 62 63 typedef struct SDL_Palette { 64 int ncolors; 65 SDL_Color *colors; 66 } SDL_Palette; 67 /*@}*/ 68 69 /** Everything in the pixel format structure is read-only */ 70 typedef struct SDL_PixelFormat { 71 SDL_Palette *palette; 72 Uint8 BitsPerPixel; 73 Uint8 BytesPerPixel; 74 Uint8 Rloss; 75 Uint8 Gloss; 76 Uint8 Bloss; 77 Uint8 Aloss; 78 Uint8 Rshift; 79 Uint8 Gshift; 80 Uint8 Bshift; 81 Uint8 Ashift; 82 Uint32 Rmask; 83 Uint32 Gmask; 84 Uint32 Bmask; 85 Uint32 Amask; 86 87 /** RGB color key information */ 88 Uint32 colorkey; 89 /** Alpha value information (per-surface alpha) */ 90 Uint8 alpha; 91 } SDL_PixelFormat; 92 93 /** This structure should be treated as read-only, except for 'pixels', 94 * which, if not NULL, contains the raw pixel data for the surface. 95 */ 96 typedef struct SDL_Surface { 97 Uint32 flags; /**< Read-only */ 98 SDL_PixelFormat *format; /**< Read-only */ 99 int w, h; /**< Read-only */ 100 Uint16 pitch; /**< Read-only */ 101 void *pixels; /**< Read-write */ 102 int offset; /**< Private */ 103 104 /** Hardware-specific surface info */ 105 struct private_hwdata *hwdata; 106 107 /** clipping information */ 108 SDL_Rect clip_rect; /**< Read-only */ 109 Uint32 unused1; /**< for binary compatibility */ 110 111 /** Allow recursive locks */ 112 Uint32 locked; /**< Private */ 113 114 /** info for fast blit mapping to other surfaces */ 115 struct SDL_BlitMap *map; /**< Private */ 116 117 /** format version, bumped at every change to invalidate blit maps */ 118 unsigned int format_version; /**< Private */ 119 120 /** Reference count -- used when freeing surface */ 121 int refcount; /**< Read-mostly */ 122 } SDL_Surface; 123 124 /** @name SDL_Surface Flags 125 * These are the currently supported flags for the SDL_surface 126 */ 127 /*@{*/ 128 129 /** Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */ 130 /*@{*/ 131 #define SDL_SWSURFACE 0x00000000 /**< Surface is in system memory */ 132 #define SDL_HWSURFACE 0x00000001 /**< Surface is in video memory */ 133 #define SDL_ASYNCBLIT 0x00000004 /**< Use asynchronous blits if possible */ 134 /*@}*/ 135 136 /** Available for SDL_SetVideoMode() */ 137 /*@{*/ 138 #define SDL_ANYFORMAT 0x10000000 /**< Allow any video depth/pixel-format */ 139 #define SDL_HWPALETTE 0x20000000 /**< Surface has exclusive palette */ 140 #define SDL_DOUBLEBUF 0x40000000 /**< Set up double-buffered video mode */ 141 #define SDL_FULLSCREEN 0x80000000 /**< Surface is a full screen display */ 142 #define SDL_OPENGL 0x00000002 /**< Create an OpenGL rendering context */ 143 #define SDL_OPENGLBLIT 0x0000000A /**< Create an OpenGL rendering context and use it for blitting */ 144 #define SDL_RESIZABLE 0x00000010 /**< This video mode may be resized */ 145 #define SDL_NOFRAME 0x00000020 /**< No window caption or edge frame */ 146 /*@}*/ 147 148 /** Used internally (read-only) */ 149 /*@{*/ 150 #define SDL_HWACCEL 0x00000100 /**< Blit uses hardware acceleration */ 151 #define SDL_SRCCOLORKEY 0x00001000 /**< Blit uses a source color key */ 152 #define SDL_RLEACCELOK 0x00002000 /**< Private flag */ 153 #define SDL_RLEACCEL 0x00004000 /**< Surface is RLE encoded */ 154 #define SDL_SRCALPHA 0x00010000 /**< Blit uses source alpha blending */ 155 #define SDL_PREALLOC 0x01000000 /**< Surface uses preallocated memory */ 156 /*@}*/ 157 158 /*@}*/ 159 160 /** Evaluates to true if the surface needs to be locked before access */ 161 #define SDL_MUSTLOCK(surface) \ 162 (surface->offset || \ 163 ((surface->flags & (SDL_HWSURFACE|SDL_ASYNCBLIT|SDL_RLEACCEL)) != 0)) 164 165 /** typedef for private surface blitting functions */ 166 typedef int (*SDL_blit)(struct SDL_Surface *src, SDL_Rect *srcrect, 167 struct SDL_Surface *dst, SDL_Rect *dstrect); 168 169 170 /** Useful for determining the video hardware capabilities */ 171 typedef struct SDL_VideoInfo { 172 Uint32 hw_available :1; /**< Flag: Can you create hardware surfaces? */ 173 Uint32 wm_available :1; /**< Flag: Can you talk to a window manager? */ 174 Uint32 UnusedBits1 :6; 175 Uint32 UnusedBits2 :1; 176 Uint32 blit_hw :1; /**< Flag: Accelerated blits HW --> HW */ 177 Uint32 blit_hw_CC :1; /**< Flag: Accelerated blits with Colorkey */ 178 Uint32 blit_hw_A :1; /**< Flag: Accelerated blits with Alpha */ 179 Uint32 blit_sw :1; /**< Flag: Accelerated blits SW --> HW */ 180 Uint32 blit_sw_CC :1; /**< Flag: Accelerated blits with Colorkey */ 181 Uint32 blit_sw_A :1; /**< Flag: Accelerated blits with Alpha */ 182 Uint32 blit_fill :1; /**< Flag: Accelerated color fill */ 183 Uint32 UnusedBits3 :16; 184 Uint32 video_mem; /**< The total amount of video memory (in K) */ 185 SDL_PixelFormat *vfmt; /**< Value: The format of the video surface */ 186 int current_w; /**< Value: The current video mode width */ 187 int current_h; /**< Value: The current video mode height */ 188 } SDL_VideoInfo; 189 190 191 /** @name Overlay Formats 192 * The most common video overlay formats. 193 * For an explanation of these pixel formats, see: 194 * http://www.webartz.com/fourcc/indexyuv.htm 195 * 196 * For information on the relationship between color spaces, see: 197 * http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html 198 */ 199 /*@{*/ 200 #define SDL_YV12_OVERLAY 0x32315659 /**< Planar mode: Y + V + U (3 planes) */ 201 #define SDL_IYUV_OVERLAY 0x56555949 /**< Planar mode: Y + U + V (3 planes) */ 202 #define SDL_YUY2_OVERLAY 0x32595559 /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */ 203 #define SDL_UYVY_OVERLAY 0x59565955 /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */ 204 #define SDL_YVYU_OVERLAY 0x55595659 /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */ 205 /*@}*/ 206 207 /** The YUV hardware video overlay */ 208 typedef struct SDL_Overlay { 209 Uint32 format; /**< Read-only */ 210 int w, h; /**< Read-only */ 211 int planes; /**< Read-only */ 212 Uint16 *pitches; /**< Read-only */ 213 Uint8 **pixels; /**< Read-write */ 214 215 /** @name Hardware-specific surface info */ 216 /*@{*/ 217 struct private_yuvhwfuncs *hwfuncs; 218 struct private_yuvhwdata *hwdata; 219 /*@{*/ 220 221 /** @name Special flags */ 222 /*@{*/ 223 Uint32 hw_overlay :1; /**< Flag: This overlay hardware accelerated? */ 224 Uint32 UnusedBits :31; 225 /*@}*/ 226 } SDL_Overlay; 227 228 229 /** @name flags for SDL_SetPalette() */ 230 /*@{*/ 231 #define SDL_LOGPAL 0x01 232 #define SDL_PHYSPAL 0x02 233 /*@}*/ 234 235 /* Function prototypes */ 236 237 /** @name SDL_Update Functions 238 * These functions should not be called while 'screen' is locked. 239 */ 240 /*@{*/ 241 /** 242 * Makes sure the given list of rectangles is updated on the given screen. 243 */ 244 extern DECLSPEC void SDLCALL LRSDL_UpdateRects 245 (SDL_Surface *screen, int numrects, SDL_Rect *rects); 246 /** 247 * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire 248 * screen. 249 */ 250 extern DECLSPEC void SDLCALL LRSDL_UpdateRect 251 (SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h); 252 /*@}*/ 253 254 /** 255 * On hardware that supports double-buffering, this function sets up a flip 256 * and returns. The hardware will wait for vertical retrace, and then swap 257 * video buffers before the next video surface blit or lock will return. 258 * On hardware that doesn not support double-buffering, this is equivalent 259 * to calling SDL_UpdateRect(screen, 0, 0, 0, 0); 260 * The SDL_DOUBLEBUF flag must have been passed to SDL_SetVideoMode() when 261 * setting the video mode for this function to perform hardware flipping. 262 * This function returns 0 if successful, or -1 if there was an error. 263 */ 264 extern DECLSPEC int SDLCALL LRSDL_Flip(SDL_Surface *screen); 265 266 /** 267 * Set the gamma correction for each of the color channels. 268 * The gamma values range (approximately) between 0.1 and 10.0 269 * 270 * If this function isn't supported directly by the hardware, it will 271 * be emulated using gamma ramps, if available. If successful, this 272 * function returns 0, otherwise it returns -1. 273 */ 274 extern DECLSPEC int SDLCALL LRSDL_SetGamma(float red, float green, float blue); 275 276 /** 277 * Sets a portion of the colormap for the given 8-bit surface. If 'surface' 278 * is not a palettized surface, this function does nothing, returning 0. 279 * If all of the colors were set as passed to SDL_SetColors(), it will 280 * return 1. If not all the color entries were set exactly as given, 281 * it will return 0, and you should look at the surface palette to 282 * determine the actual color palette. 283 * 284 * When 'surface' is the surface associated with the current display, the 285 * display colormap will be updated with the requested colors. If 286 * SDL_HWPALETTE was set in SDL_SetVideoMode() flags, SDL_SetColors() 287 * will always return 1, and the palette is guaranteed to be set the way 288 * you desire, even if the window colormap has to be warped or run under 289 * emulation. 290 */ 291 extern DECLSPEC int SDLCALL LRSDL_SetColors(SDL_Surface *surface, 292 SDL_Color *colors, int firstcolor, int ncolors); 293 294 /** 295 * Sets a portion of the colormap for a given 8-bit surface. 296 * 'flags' is one or both of: 297 * SDL_LOGPAL -- set logical palette, which controls how blits are mapped 298 * to/from the surface, 299 * SDL_PHYSPAL -- set physical palette, which controls how pixels look on 300 * the screen 301 * Only screens have physical palettes. Separate change of physical/logical 302 * palettes is only possible if the screen has SDL_HWPALETTE set. 303 * 304 * The return value is 1 if all colours could be set as requested, and 0 305 * otherwise. 306 * 307 * SDL_SetColors() is equivalent to calling this function with 308 * flags = (SDL_LOGPAL|SDL_PHYSPAL). 309 */ 310 extern DECLSPEC int SDLCALL LRSDL_SetPalette(SDL_Surface *surface, int flags, 311 SDL_Color *colors, int firstcolor, 312 int ncolors); 313 314 /** 315 * Maps an RGB triple to an opaque pixel value for a given pixel format 316 */ 317 extern DECLSPEC Uint32 SDLCALL LRSDL_MapRGB 318 (const SDL_PixelFormat * const format, 319 const Uint8 r, const Uint8 g, const Uint8 b); 320 321 /** 322 * Maps an RGBA quadruple to a pixel value for a given pixel format 323 */ 324 extern DECLSPEC Uint32 SDLCALL LRSDL_MapRGBA 325 (const SDL_PixelFormat * const format, 326 const Uint8 r, const Uint8 g, const Uint8 b, const Uint8 a); 327 328 /** 329 * Maps a pixel value into the RGB components for a given pixel format 330 */ 331 extern DECLSPEC void SDLCALL LRSDL_GetRGB(Uint32 pixel, 332 const SDL_PixelFormat * const fmt, 333 Uint8 *r, Uint8 *g, Uint8 *b); 334 335 /** 336 * Maps a pixel value into the RGBA components for a given pixel format 337 */ 338 extern DECLSPEC void SDLCALL LRSDL_GetRGBA(Uint32 pixel, 339 const SDL_PixelFormat * const fmt, 340 Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); 341 342 /** @sa SDL_CreateRGBSurface */ 343 #define LRSDL_AllocSurface LRSDL_CreateRGBSurface 344 /** 345 * Allocate and free an RGB surface (must be called after SDL_SetVideoMode) 346 * If the depth is 4 or 8 bits, an empty palette is allocated for the surface. 347 * If the depth is greater than 8 bits, the pixel format is set using the 348 * flags '[RGB]mask'. 349 * If the function runs out of memory, it will return NULL. 350 * 351 * The 'flags' tell what kind of surface to create. 352 * SDL_SWSURFACE means that the surface should be created in system memory. 353 * SDL_HWSURFACE means that the surface should be created in video memory, 354 * with the same format as the display surface. This is useful for surfaces 355 * that will not change much, to take advantage of hardware acceleration 356 * when being blitted to the display surface. 357 * SDL_ASYNCBLIT means that SDL will try to perform asynchronous blits with 358 * this surface, but you must always lock it before accessing the pixels. 359 * SDL will wait for current blits to finish before returning from the lock. 360 * SDL_SRCCOLORKEY indicates that the surface will be used for colorkey blits. 361 * If the hardware supports acceleration of colorkey blits between 362 * two surfaces in video memory, SDL will try to place the surface in 363 * video memory. If this isn't possible or if there is no hardware 364 * acceleration available, the surface will be placed in system memory. 365 * SDL_SRCALPHA means that the surface will be used for alpha blits and 366 * if the hardware supports hardware acceleration of alpha blits between 367 * two surfaces in video memory, to place the surface in video memory 368 * if possible, otherwise it will be placed in system memory. 369 * If the surface is created in video memory, blits will be _much_ faster, 370 * but the surface format must be identical to the video surface format, 371 * and the only way to access the pixels member of the surface is to use 372 * the SDL_LockSurface() and SDL_UnlockSurface() calls. 373 * If the requested surface actually resides in video memory, SDL_HWSURFACE 374 * will be set in the flags member of the returned surface. If for some 375 * reason the surface could not be placed in video memory, it will not have 376 * the SDL_HWSURFACE flag set, and will be created in system memory instead. 377 */ 378 extern DECLSPEC SDL_Surface * SDLCALL LRSDL_CreateRGBSurface 379 (Uint32 flags, int width, int height, int depth, 380 Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask); 381 /** @sa SDL_CreateRGBSurface */ 382 extern DECLSPEC SDL_Surface * SDLCALL LRSDL_CreateRGBSurfaceFrom(void *pixels, 383 int width, int height, int depth, int pitch, 384 Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask); 385 extern DECLSPEC void SDLCALL LRSDL_FreeSurface(SDL_Surface *surface); 386 387 /** 388 * SDL_LockSurface() sets up a surface for directly accessing the pixels. 389 * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write 390 * to and read from 'surface->pixels', using the pixel format stored in 391 * 'surface->format'. Once you are done accessing the surface, you should 392 * use SDL_UnlockSurface() to release it. 393 * 394 * Not all surfaces require locking. If SDL_MUSTLOCK(surface) evaluates 395 * to 0, then you can read and write to the surface at any time, and the 396 * pixel format of the surface will not change. In particular, if the 397 * SDL_HWSURFACE flag is not given when calling SDL_SetVideoMode(), you 398 * will not need to lock the display surface before accessing it. 399 * 400 * No operating system or library calls should be made between lock/unlock 401 * pairs, as critical system locks may be held during this time. 402 * 403 * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked. 404 */ 405 extern DECLSPEC int SDLCALL LRSDL_LockSurface(SDL_Surface *surface); 406 extern DECLSPEC void SDLCALL LRSDL_UnlockSurface(SDL_Surface *surface); 407 408 /* 409 * Convert a surface into the specified pixel format. 410 */ 411 extern DECLSPEC SDL_Surface * LRSDL_ConvertSurface (SDL_Surface *surface, 412 SDL_PixelFormat *format, Uint32 flags); 413 414 415 /** 416 * Load a surface from a seekable SDL data source (memory or file.) 417 * If 'freesrc' is non-zero, the source will be closed after being read. 418 * Returns the new surface, or NULL if there was an error. 419 * The new surface should be freed with SDL_FreeSurface(). 420 */ 421 extern DECLSPEC SDL_Surface * SDLCALL LRSDL_LoadBMP_RW(LRSDL_RWops *src, int freesrc); 422 423 /** Convenience macro -- load a surface from a file */ 424 #define LRSDL_LoadBMP(file) LRSDL_LoadBMP_RW(LRSDL_RWFromFile(file, "rb"), 1) 425 426 /** 427 * Save a surface to a seekable SDL data source (memory or file.) 428 * If 'freedst' is non-zero, the source will be closed after being written. 429 * Returns 0 if successful or -1 if there was an error. 430 */ 431 extern DECLSPEC int SDLCALL LRSDL_SaveBMP_RW 432 (SDL_Surface *surface, LRSDL_RWops *dst, int freedst); 433 434 /** Convenience macro -- save a surface to a file */ 435 #define LRSDL_SaveBMP(surface, file) \ 436 LRSDL_SaveBMP_RW(surface, LRSDL_RWFromFile(file, "wb"), 1) 437 438 /** 439 * Sets the color key (transparent pixel) in a blittable surface. 440 * If 'flag' is SDL_SRCCOLORKEY (optionally OR'd with SDL_RLEACCEL), 441 * 'key' will be the transparent pixel in the source image of a blit. 442 * SDL_RLEACCEL requests RLE acceleration for the surface if present, 443 * and removes RLE acceleration if absent. 444 * If 'flag' is 0, this function clears any current color key. 445 * This function returns 0, or -1 if there was an error. 446 */ 447 extern DECLSPEC int SDLCALL LRSDL_SetColorKey 448 (SDL_Surface *surface, Uint32 flag, Uint32 key); 449 450 /** 451 * This function sets the alpha value for the entire surface, as opposed to 452 * using the alpha component of each pixel. This value measures the range 453 * of transparency of the surface, 0 being completely transparent to 255 454 * being completely opaque. An 'alpha' value of 255 causes blits to be 455 * opaque, the source pixels copied to the destination (the default). Note 456 * that per-surface alpha can be combined with colorkey transparency. 457 * 458 * If 'flag' is 0, alpha blending is disabled for the surface. 459 * If 'flag' is SDL_SRCALPHA, alpha blending is enabled for the surface. 460 * OR:ing the flag with SDL_RLEACCEL requests RLE acceleration for the 461 * surface; if SDL_RLEACCEL is not specified, the RLE accel will be removed. 462 * 463 * The 'alpha' parameter is ignored for surfaces that have an alpha channel. 464 */ 465 extern DECLSPEC int SDLCALL LRSDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha); 466 467 /** 468 * Sets the clipping rectangle for the destination surface in a blit. 469 * 470 * If the clip rectangle is NULL, clipping will be disabled. 471 * If the clip rectangle doesn't intersect the surface, the function will 472 * return SDL_FALSE and blits will be completely clipped. Otherwise the 473 * function returns SDL_TRUE and blits to the surface will be clipped to 474 * the intersection of the surface area and the clipping rectangle. 475 * 476 * Note that blits are automatically clipped to the edges of the source 477 * and destination surfaces. 478 */ 479 extern DECLSPEC LRSDL_bool SDLCALL LRSDL_SetClipRect(SDL_Surface *surface, const SDL_Rect *rect); 480 481 /** 482 * This performs a fast blit from the source surface to the destination 483 * surface. It assumes that the source and destination rectangles are 484 * the same size. If either 'srcrect' or 'dstrect' are NULL, the entire 485 * surface (src or dst) is copied. The final blit rectangles are saved 486 * in 'srcrect' and 'dstrect' after all clipping is performed. 487 * If the blit is successful, it returns 0, otherwise it returns -1. 488 * 489 * The blit function should not be called on a locked surface. 490 * 491 * The blit semantics for surfaces with and without alpha and colorkey 492 * are defined as follows: 493 * 494 * RGBA->RGB: 495 * SDL_SRCALPHA set: 496 * alpha-blend (using alpha-channel). 497 * SDL_SRCCOLORKEY ignored. 498 * SDL_SRCALPHA not set: 499 * copy RGB. 500 * if SDL_SRCCOLORKEY set, only copy the pixels matching the 501 * RGB values of the source colour key, ignoring alpha in the 502 * comparison. 503 * 504 * RGB->RGBA: 505 * SDL_SRCALPHA set: 506 * alpha-blend (using the source per-surface alpha value); 507 * set destination alpha to opaque. 508 * SDL_SRCALPHA not set: 509 * copy RGB, set destination alpha to source per-surface alpha value. 510 * both: 511 * if SDL_SRCCOLORKEY set, only copy the pixels matching the 512 * source colour key. 513 * 514 * RGBA->RGBA: 515 * SDL_SRCALPHA set: 516 * alpha-blend (using the source alpha channel) the RGB values; 517 * leave destination alpha untouched. [Note: is this correct?] 518 * SDL_SRCCOLORKEY ignored. 519 * SDL_SRCALPHA not set: 520 * copy all of RGBA to the destination. 521 * if SDL_SRCCOLORKEY set, only copy the pixels matching the 522 * RGB values of the source colour key, ignoring alpha in the 523 * comparison. 524 * 525 * RGB->RGB: 526 * SDL_SRCALPHA set: 527 * alpha-blend (using the source per-surface alpha value). 528 * SDL_SRCALPHA not set: 529 * copy RGB. 530 * both: 531 * if SDL_SRCCOLORKEY set, only copy the pixels matching the 532 * source colour key. 533 * 534 * If either of the surfaces were in video memory, and the blit returns -2, 535 * the video memory was lost, so it should be reloaded with artwork and 536 * re-blitted: 537 * @code 538 * while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) { 539 * while ( SDL_LockSurface(image) < 0 ) 540 * Sleep(10); 541 * -- Write image pixels to image->pixels -- 542 * SDL_UnlockSurface(image); 543 * } 544 * @endcode 545 * 546 * This happens under DirectX 5.0 when the system switches away from your 547 * fullscreen application. The lock will also fail until you have access 548 * to the video memory again. 549 * 550 * You should call SDL_BlitSurface() unless you know exactly how SDL 551 * blitting works internally and how to use the other blit functions. 552 */ 553 554 /** This is the public blit function, SDL_BlitSurface(), and it performs 555 * rectangle validation and clipping before passing it to SDL_LowerBlit() 556 */ 557 extern DECLSPEC int SDLCALL LRSDL_UpperBlit 558 (SDL_Surface *src, SDL_Rect *srcrect, 559 SDL_Surface *dst, SDL_Rect *dstrect); 560 /** This is a semi-private blit function and it performs low-level surface 561 * blitting only. 562 */ 563 extern DECLSPEC int SDLCALL LRSDL_LowerBlit 564 (SDL_Surface *src, SDL_Rect *srcrect, 565 SDL_Surface *dst, SDL_Rect *dstrect); 566 567 /** 568 * This function performs a fast fill of the given rectangle with 'color' 569 * The given rectangle is clipped to the destination surface clip area 570 * and the final fill rectangle is saved in the passed in pointer. 571 * If 'dstrect' is NULL, the whole surface will be filled with 'color' 572 * The color should be a pixel of the format used by the surface, and 573 * can be generated by the SDL_MapRGB() function. 574 * This function returns 0 on success, or -1 on error. 575 */ 576 extern DECLSPEC int SDLCALL LRSDL_FillRect 577 (SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color); 578 579 /** 580 * This function takes a surface and copies it to a new surface of the 581 * pixel format and colors of the video framebuffer, suitable for fast 582 * blitting onto the display surface. It calls SDL_ConvertSurface() 583 * 584 * If you want to take advantage of hardware colorkey or alpha blit 585 * acceleration, you should set the colorkey and alpha value before 586 * calling this function. 587 * 588 * If the conversion fails or runs out of memory, it returns NULL 589 */ 590 extern DECLSPEC SDL_Surface * SDLCALL LRSDL_DisplayFormat(SDL_Surface *surface); 591 592 /** 593 * This function takes a surface and copies it to a new surface of the 594 * pixel format and colors of the video framebuffer (if possible), 595 * suitable for fast alpha blitting onto the display surface. 596 * The new surface will always have an alpha channel. 597 * 598 * If you want to take advantage of hardware colorkey or alpha blit 599 * acceleration, you should set the colorkey and alpha value before 600 * calling this function. 601 * 602 * If the conversion fails or runs out of memory, it returns NULL 603 */ 604 extern DECLSPEC SDL_Surface * SDLCALL LRSDL_DisplayFormatAlpha(SDL_Surface *surface); 605 606 /* Ends C function definitions when using C++ */ 607 #ifdef __cplusplus 608 } 609 #endif 610 #include "close_code.h" 611 612 #endif /* _SDL_video_h */ 613