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