More open bugs in SDL2 2.0.3.
[xonotic/xonotic.git] / misc / builddeps / win32 / sdl / include / SDL / SDL_video.h
1 /*
2     SDL - Simple DirectMedia Layer
3     Copyright (C) 1997-2009 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 _SDL_video_h
28 #define _SDL_video_h
29
30 #include "SDL_stdinc.h"
31 #include "SDL_error.h"
32 #include "SDL_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 /** Public enumeration for setting the OpenGL window attributes. */
230 typedef enum {
231     SDL_GL_RED_SIZE,
232     SDL_GL_GREEN_SIZE,
233     SDL_GL_BLUE_SIZE,
234     SDL_GL_ALPHA_SIZE,
235     SDL_GL_BUFFER_SIZE,
236     SDL_GL_DOUBLEBUFFER,
237     SDL_GL_DEPTH_SIZE,
238     SDL_GL_STENCIL_SIZE,
239     SDL_GL_ACCUM_RED_SIZE,
240     SDL_GL_ACCUM_GREEN_SIZE,
241     SDL_GL_ACCUM_BLUE_SIZE,
242     SDL_GL_ACCUM_ALPHA_SIZE,
243     SDL_GL_STEREO,
244     SDL_GL_MULTISAMPLEBUFFERS,
245     SDL_GL_MULTISAMPLESAMPLES,
246     SDL_GL_ACCELERATED_VISUAL,
247     SDL_GL_SWAP_CONTROL
248 } SDL_GLattr;
249
250 /** @name flags for SDL_SetPalette() */
251 /*@{*/
252 #define SDL_LOGPAL 0x01
253 #define SDL_PHYSPAL 0x02
254 /*@}*/
255
256 /* Function prototypes */
257
258 /**
259  * @name Video Init and Quit
260  * These functions are used internally, and should not be used unless you
261  * have a specific need to specify the video driver you want to use.
262  * You should normally use SDL_Init() or SDL_InitSubSystem().
263  */
264 /*@{*/
265 /**
266  * Initializes the video subsystem. Sets up a connection
267  * to the window manager, etc, and determines the current video mode and
268  * pixel format, but does not initialize a window or graphics mode.
269  * Note that event handling is activated by this routine.
270  *
271  * If you use both sound and video in your application, you need to call
272  * SDL_Init() before opening the sound device, otherwise under Win32 DirectX,
273  * you won't be able to set full-screen display modes.
274  */
275 extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name, Uint32 flags);
276 extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
277 /*@}*/
278
279 /**
280  * This function fills the given character buffer with the name of the
281  * video driver, and returns a pointer to it if the video driver has
282  * been initialized.  It returns NULL if no driver has been initialized.
283  */
284 extern DECLSPEC char * SDLCALL SDL_VideoDriverName(char *namebuf, int maxlen);
285
286 /**
287  * This function returns a pointer to the current display surface.
288  * If SDL is doing format conversion on the display surface, this
289  * function returns the publicly visible surface, not the real video
290  * surface.
291  */
292 extern DECLSPEC SDL_Surface * SDLCALL SDL_GetVideoSurface(void);
293
294 /**
295  * This function returns a read-only pointer to information about the
296  * video hardware.  If this is called before SDL_SetVideoMode(), the 'vfmt'
297  * member of the returned structure will contain the pixel format of the
298  * "best" video mode.
299  */
300 extern DECLSPEC const SDL_VideoInfo * SDLCALL SDL_GetVideoInfo(void);
301
302 /**
303  * Check to see if a particular video mode is supported.
304  * It returns 0 if the requested mode is not supported under any bit depth,
305  * or returns the bits-per-pixel of the closest available mode with the
306  * given width and height.  If this bits-per-pixel is different from the
307  * one used when setting the video mode, SDL_SetVideoMode() will succeed,
308  * but will emulate the requested bits-per-pixel with a shadow surface.
309  *
310  * The arguments to SDL_VideoModeOK() are the same ones you would pass to
311  * SDL_SetVideoMode()
312  */
313 extern DECLSPEC int SDLCALL SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags);
314
315 /**
316  * Return a pointer to an array of available screen dimensions for the
317  * given format and video flags, sorted largest to smallest.  Returns 
318  * NULL if there are no dimensions available for a particular format, 
319  * or (SDL_Rect **)-1 if any dimension is okay for the given format.
320  *
321  * If 'format' is NULL, the mode list will be for the format given 
322  * by SDL_GetVideoInfo()->vfmt
323  */
324 extern DECLSPEC SDL_Rect ** SDLCALL SDL_ListModes(SDL_PixelFormat *format, Uint32 flags);
325
326 /**
327  * Set up a video mode with the specified width, height and bits-per-pixel.
328  *
329  * If 'bpp' is 0, it is treated as the current display bits per pixel.
330  *
331  * If SDL_ANYFORMAT is set in 'flags', the SDL library will try to set the
332  * requested bits-per-pixel, but will return whatever video pixel format is
333  * available.  The default is to emulate the requested pixel format if it
334  * is not natively available.
335  *
336  * If SDL_HWSURFACE is set in 'flags', the video surface will be placed in
337  * video memory, if possible, and you may have to call SDL_LockSurface()
338  * in order to access the raw framebuffer.  Otherwise, the video surface
339  * will be created in system memory.
340  *
341  * If SDL_ASYNCBLIT is set in 'flags', SDL will try to perform rectangle
342  * updates asynchronously, but you must always lock before accessing pixels.
343  * SDL will wait for updates to complete before returning from the lock.
344  *
345  * If SDL_HWPALETTE is set in 'flags', the SDL library will guarantee
346  * that the colors set by SDL_SetColors() will be the colors you get.
347  * Otherwise, in 8-bit mode, SDL_SetColors() may not be able to set all
348  * of the colors exactly the way they are requested, and you should look
349  * at the video surface structure to determine the actual palette.
350  * If SDL cannot guarantee that the colors you request can be set, 
351  * i.e. if the colormap is shared, then the video surface may be created
352  * under emulation in system memory, overriding the SDL_HWSURFACE flag.
353  *
354  * If SDL_FULLSCREEN is set in 'flags', the SDL library will try to set
355  * a fullscreen video mode.  The default is to create a windowed mode
356  * if the current graphics system has a window manager.
357  * If the SDL library is able to set a fullscreen video mode, this flag 
358  * will be set in the surface that is returned.
359  *
360  * If SDL_DOUBLEBUF is set in 'flags', the SDL library will try to set up
361  * two surfaces in video memory and swap between them when you call 
362  * SDL_Flip().  This is usually slower than the normal single-buffering
363  * scheme, but prevents "tearing" artifacts caused by modifying video 
364  * memory while the monitor is refreshing.  It should only be used by 
365  * applications that redraw the entire screen on every update.
366  *
367  * If SDL_RESIZABLE is set in 'flags', the SDL library will allow the
368  * window manager, if any, to resize the window at runtime.  When this
369  * occurs, SDL will send a SDL_VIDEORESIZE event to you application,
370  * and you must respond to the event by re-calling SDL_SetVideoMode()
371  * with the requested size (or another size that suits the application).
372  *
373  * If SDL_NOFRAME is set in 'flags', the SDL library will create a window
374  * without any title bar or frame decoration.  Fullscreen video modes have
375  * this flag set automatically.
376  *
377  * This function returns the video framebuffer surface, or NULL if it fails.
378  *
379  * If you rely on functionality provided by certain video flags, check the
380  * flags of the returned surface to make sure that functionality is available.
381  * SDL will fall back to reduced functionality if the exact flags you wanted
382  * are not available.
383  */
384 extern DECLSPEC SDL_Surface * SDLCALL SDL_SetVideoMode
385                         (int width, int height, int bpp, Uint32 flags);
386
387 /** @name SDL_Update Functions
388  * These functions should not be called while 'screen' is locked.
389  */
390 /*@{*/
391 /**
392  * Makes sure the given list of rectangles is updated on the given screen.
393  */
394 extern DECLSPEC void SDLCALL SDL_UpdateRects
395                 (SDL_Surface *screen, int numrects, SDL_Rect *rects);
396 /**
397  * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
398  * screen.
399  */
400 extern DECLSPEC void SDLCALL SDL_UpdateRect
401                 (SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
402 /*@}*/
403
404 /**
405  * On hardware that supports double-buffering, this function sets up a flip
406  * and returns.  The hardware will wait for vertical retrace, and then swap
407  * video buffers before the next video surface blit or lock will return.
408  * On hardware that doesn not support double-buffering, this is equivalent
409  * to calling SDL_UpdateRect(screen, 0, 0, 0, 0);
410  * The SDL_DOUBLEBUF flag must have been passed to SDL_SetVideoMode() when
411  * setting the video mode for this function to perform hardware flipping.
412  * This function returns 0 if successful, or -1 if there was an error.
413  */
414 extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface *screen);
415
416 /**
417  * Set the gamma correction for each of the color channels.
418  * The gamma values range (approximately) between 0.1 and 10.0
419  * 
420  * If this function isn't supported directly by the hardware, it will
421  * be emulated using gamma ramps, if available.  If successful, this
422  * function returns 0, otherwise it returns -1.
423  */
424 extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
425
426 /**
427  * Set the gamma translation table for the red, green, and blue channels
428  * of the video hardware.  Each table is an array of 256 16-bit quantities,
429  * representing a mapping between the input and output for that channel.
430  * The input is the index into the array, and the output is the 16-bit
431  * gamma value at that index, scaled to the output color precision.
432  * 
433  * You may pass NULL for any of the channels to leave it unchanged.
434  * If the call succeeds, it will return 0.  If the display driver or
435  * hardware does not support gamma translation, or otherwise fails,
436  * this function will return -1.
437  */
438 extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 *red, const Uint16 *green, const Uint16 *blue);
439
440 /**
441  * Retrieve the current values of the gamma translation tables.
442  * 
443  * You must pass in valid pointers to arrays of 256 16-bit quantities.
444  * Any of the pointers may be NULL to ignore that channel.
445  * If the call succeeds, it will return 0.  If the display driver or
446  * hardware does not support gamma translation, or otherwise fails,
447  * this function will return -1.
448  */
449 extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
450
451 /**
452  * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
453  * is not a palettized surface, this function does nothing, returning 0.
454  * If all of the colors were set as passed to SDL_SetColors(), it will
455  * return 1.  If not all the color entries were set exactly as given,
456  * it will return 0, and you should look at the surface palette to
457  * determine the actual color palette.
458  *
459  * When 'surface' is the surface associated with the current display, the
460  * display colormap will be updated with the requested colors.  If 
461  * SDL_HWPALETTE was set in SDL_SetVideoMode() flags, SDL_SetColors()
462  * will always return 1, and the palette is guaranteed to be set the way
463  * you desire, even if the window colormap has to be warped or run under
464  * emulation.
465  */
466 extern DECLSPEC int SDLCALL SDL_SetColors(SDL_Surface *surface, 
467                         SDL_Color *colors, int firstcolor, int ncolors);
468
469 /**
470  * Sets a portion of the colormap for a given 8-bit surface.
471  * 'flags' is one or both of:
472  * SDL_LOGPAL  -- set logical palette, which controls how blits are mapped
473  *                to/from the surface,
474  * SDL_PHYSPAL -- set physical palette, which controls how pixels look on
475  *                the screen
476  * Only screens have physical palettes. Separate change of physical/logical
477  * palettes is only possible if the screen has SDL_HWPALETTE set.
478  *
479  * The return value is 1 if all colours could be set as requested, and 0
480  * otherwise.
481  *
482  * SDL_SetColors() is equivalent to calling this function with
483  *     flags = (SDL_LOGPAL|SDL_PHYSPAL).
484  */
485 extern DECLSPEC int SDLCALL SDL_SetPalette(SDL_Surface *surface, int flags,
486                                    SDL_Color *colors, int firstcolor,
487                                    int ncolors);
488
489 /**
490  * Maps an RGB triple to an opaque pixel value for a given pixel format
491  */
492 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB
493 (const SDL_PixelFormat * const format,
494  const Uint8 r, const Uint8 g, const Uint8 b);
495
496 /**
497  * Maps an RGBA quadruple to a pixel value for a given pixel format
498  */
499 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA
500 (const SDL_PixelFormat * const format,
501  const Uint8 r, const Uint8 g, const Uint8 b, const Uint8 a);
502
503 /**
504  * Maps a pixel value into the RGB components for a given pixel format
505  */
506 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
507                                 const SDL_PixelFormat * const fmt,
508                                 Uint8 *r, Uint8 *g, Uint8 *b);
509
510 /**
511  * Maps a pixel value into the RGBA components for a given pixel format
512  */
513 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
514                                 const SDL_PixelFormat * const fmt,
515                                 Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
516
517 /** @sa SDL_CreateRGBSurface */
518 #define SDL_AllocSurface    SDL_CreateRGBSurface
519 /**
520  * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
521  * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
522  * If the depth is greater than 8 bits, the pixel format is set using the
523  * flags '[RGB]mask'.
524  * If the function runs out of memory, it will return NULL.
525  *
526  * The 'flags' tell what kind of surface to create.
527  * SDL_SWSURFACE means that the surface should be created in system memory.
528  * SDL_HWSURFACE means that the surface should be created in video memory,
529  * with the same format as the display surface.  This is useful for surfaces
530  * that will not change much, to take advantage of hardware acceleration
531  * when being blitted to the display surface.
532  * SDL_ASYNCBLIT means that SDL will try to perform asynchronous blits with
533  * this surface, but you must always lock it before accessing the pixels.
534  * SDL will wait for current blits to finish before returning from the lock.
535  * SDL_SRCCOLORKEY indicates that the surface will be used for colorkey blits.
536  * If the hardware supports acceleration of colorkey blits between
537  * two surfaces in video memory, SDL will try to place the surface in
538  * video memory. If this isn't possible or if there is no hardware
539  * acceleration available, the surface will be placed in system memory.
540  * SDL_SRCALPHA means that the surface will be used for alpha blits and 
541  * if the hardware supports hardware acceleration of alpha blits between
542  * two surfaces in video memory, to place the surface in video memory
543  * if possible, otherwise it will be placed in system memory.
544  * If the surface is created in video memory, blits will be _much_ faster,
545  * but the surface format must be identical to the video surface format,
546  * and the only way to access the pixels member of the surface is to use
547  * the SDL_LockSurface() and SDL_UnlockSurface() calls.
548  * If the requested surface actually resides in video memory, SDL_HWSURFACE
549  * will be set in the flags member of the returned surface.  If for some
550  * reason the surface could not be placed in video memory, it will not have
551  * the SDL_HWSURFACE flag set, and will be created in system memory instead.
552  */
553 extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurface
554                         (Uint32 flags, int width, int height, int depth, 
555                         Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
556 /** @sa SDL_CreateRGBSurface */
557 extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
558                         int width, int height, int depth, int pitch,
559                         Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
560 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface *surface);
561
562 /**
563  * SDL_LockSurface() sets up a surface for directly accessing the pixels.
564  * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
565  * to and read from 'surface->pixels', using the pixel format stored in 
566  * 'surface->format'.  Once you are done accessing the surface, you should 
567  * use SDL_UnlockSurface() to release it.
568  *
569  * Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
570  * to 0, then you can read and write to the surface at any time, and the
571  * pixel format of the surface will not change.  In particular, if the
572  * SDL_HWSURFACE flag is not given when calling SDL_SetVideoMode(), you
573  * will not need to lock the display surface before accessing it.
574  * 
575  * No operating system or library calls should be made between lock/unlock
576  * pairs, as critical system locks may be held during this time.
577  *
578  * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
579  */
580 extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface);
581 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
582
583 /**
584  * Load a surface from a seekable SDL data source (memory or file.)
585  * If 'freesrc' is non-zero, the source will be closed after being read.
586  * Returns the new surface, or NULL if there was an error.
587  * The new surface should be freed with SDL_FreeSurface().
588  */
589 extern DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, int freesrc);
590
591 /** Convenience macro -- load a surface from a file */
592 #define SDL_LoadBMP(file)       SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
593
594 /**
595  * Save a surface to a seekable SDL data source (memory or file.)
596  * If 'freedst' is non-zero, the source will be closed after being written.
597  * Returns 0 if successful or -1 if there was an error.
598  */
599 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
600                 (SDL_Surface *surface, SDL_RWops *dst, int freedst);
601
602 /** Convenience macro -- save a surface to a file */
603 #define SDL_SaveBMP(surface, file) \
604                 SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
605
606 /**
607  * Sets the color key (transparent pixel) in a blittable surface.
608  * If 'flag' is SDL_SRCCOLORKEY (optionally OR'd with SDL_RLEACCEL), 
609  * 'key' will be the transparent pixel in the source image of a blit.
610  * SDL_RLEACCEL requests RLE acceleration for the surface if present,
611  * and removes RLE acceleration if absent.
612  * If 'flag' is 0, this function clears any current color key.
613  * This function returns 0, or -1 if there was an error.
614  */
615 extern DECLSPEC int SDLCALL SDL_SetColorKey
616                         (SDL_Surface *surface, Uint32 flag, Uint32 key);
617
618 /**
619  * This function sets the alpha value for the entire surface, as opposed to
620  * using the alpha component of each pixel. This value measures the range
621  * of transparency of the surface, 0 being completely transparent to 255
622  * being completely opaque. An 'alpha' value of 255 causes blits to be
623  * opaque, the source pixels copied to the destination (the default). Note
624  * that per-surface alpha can be combined with colorkey transparency.
625  *
626  * If 'flag' is 0, alpha blending is disabled for the surface.
627  * If 'flag' is SDL_SRCALPHA, alpha blending is enabled for the surface.
628  * OR:ing the flag with SDL_RLEACCEL requests RLE acceleration for the
629  * surface; if SDL_RLEACCEL is not specified, the RLE accel will be removed.
630  *
631  * The 'alpha' parameter is ignored for surfaces that have an alpha channel.
632  */
633 extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);
634
635 /**
636  * Sets the clipping rectangle for the destination surface in a blit.
637  *
638  * If the clip rectangle is NULL, clipping will be disabled.
639  * If the clip rectangle doesn't intersect the surface, the function will
640  * return SDL_FALSE and blits will be completely clipped.  Otherwise the
641  * function returns SDL_TRUE and blits to the surface will be clipped to
642  * the intersection of the surface area and the clipping rectangle.
643  *
644  * Note that blits are automatically clipped to the edges of the source
645  * and destination surfaces.
646  */
647 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface *surface, const SDL_Rect *rect);
648
649 /**
650  * Gets the clipping rectangle for the destination surface in a blit.
651  * 'rect' must be a pointer to a valid rectangle which will be filled
652  * with the correct values.
653  */
654 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rect);
655
656 /**
657  * Creates a new surface of the specified format, and then copies and maps 
658  * the given surface to it so the blit of the converted surface will be as 
659  * fast as possible.  If this function fails, it returns NULL.
660  *
661  * The 'flags' parameter is passed to SDL_CreateRGBSurface() and has those 
662  * semantics.  You can also pass SDL_RLEACCEL in the flags parameter and
663  * SDL will try to RLE accelerate colorkey and alpha blits in the resulting
664  * surface.
665  *
666  * This function is used internally by SDL_DisplayFormat().
667  */
668 extern DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface
669                         (SDL_Surface *src, SDL_PixelFormat *fmt, Uint32 flags);
670
671 /**
672  * This performs a fast blit from the source surface to the destination
673  * surface.  It assumes that the source and destination rectangles are
674  * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
675  * surface (src or dst) is copied.  The final blit rectangles are saved
676  * in 'srcrect' and 'dstrect' after all clipping is performed.
677  * If the blit is successful, it returns 0, otherwise it returns -1.
678  *
679  * The blit function should not be called on a locked surface.
680  *
681  * The blit semantics for surfaces with and without alpha and colorkey
682  * are defined as follows:
683  *
684  * RGBA->RGB:
685  *     SDL_SRCALPHA set:
686  *      alpha-blend (using alpha-channel).
687  *      SDL_SRCCOLORKEY ignored.
688  *     SDL_SRCALPHA not set:
689  *      copy RGB.
690  *      if SDL_SRCCOLORKEY set, only copy the pixels matching the
691  *      RGB values of the source colour key, ignoring alpha in the
692  *      comparison.
693  * 
694  * RGB->RGBA:
695  *     SDL_SRCALPHA set:
696  *      alpha-blend (using the source per-surface alpha value);
697  *      set destination alpha to opaque.
698  *     SDL_SRCALPHA not set:
699  *      copy RGB, set destination alpha to source per-surface alpha value.
700  *     both:
701  *      if SDL_SRCCOLORKEY set, only copy the pixels matching the
702  *      source colour key.
703  * 
704  * RGBA->RGBA:
705  *     SDL_SRCALPHA set:
706  *      alpha-blend (using the source alpha channel) the RGB values;
707  *      leave destination alpha untouched. [Note: is this correct?]
708  *      SDL_SRCCOLORKEY ignored.
709  *     SDL_SRCALPHA not set:
710  *      copy all of RGBA to the destination.
711  *      if SDL_SRCCOLORKEY set, only copy the pixels matching the
712  *      RGB values of the source colour key, ignoring alpha in the
713  *      comparison.
714  * 
715  * RGB->RGB: 
716  *     SDL_SRCALPHA set:
717  *      alpha-blend (using the source per-surface alpha value).
718  *     SDL_SRCALPHA not set:
719  *      copy RGB.
720  *     both:
721  *      if SDL_SRCCOLORKEY set, only copy the pixels matching the
722  *      source colour key.
723  *
724  * If either of the surfaces were in video memory, and the blit returns -2,
725  * the video memory was lost, so it should be reloaded with artwork and 
726  * re-blitted:
727  * @code
728  *      while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
729  *              while ( SDL_LockSurface(image) < 0 )
730  *                      Sleep(10);
731  *              -- Write image pixels to image->pixels --
732  *              SDL_UnlockSurface(image);
733  *      }
734  * @endcode
735  *
736  * This happens under DirectX 5.0 when the system switches away from your
737  * fullscreen application.  The lock will also fail until you have access
738  * to the video memory again.
739  *
740  * You should call SDL_BlitSurface() unless you know exactly how SDL
741  * blitting works internally and how to use the other blit functions.
742  */
743 #define SDL_BlitSurface SDL_UpperBlit
744
745 /** This is the public blit function, SDL_BlitSurface(), and it performs
746  *  rectangle validation and clipping before passing it to SDL_LowerBlit()
747  */
748 extern DECLSPEC int SDLCALL SDL_UpperBlit
749                         (SDL_Surface *src, SDL_Rect *srcrect,
750                          SDL_Surface *dst, SDL_Rect *dstrect);
751 /** This is a semi-private blit function and it performs low-level surface
752  *  blitting only.
753  */
754 extern DECLSPEC int SDLCALL SDL_LowerBlit
755                         (SDL_Surface *src, SDL_Rect *srcrect,
756                          SDL_Surface *dst, SDL_Rect *dstrect);
757
758 /**
759  * This function performs a fast fill of the given rectangle with 'color'
760  * The given rectangle is clipped to the destination surface clip area
761  * and the final fill rectangle is saved in the passed in pointer.
762  * If 'dstrect' is NULL, the whole surface will be filled with 'color'
763  * The color should be a pixel of the format used by the surface, and 
764  * can be generated by the SDL_MapRGB() function.
765  * This function returns 0 on success, or -1 on error.
766  */
767 extern DECLSPEC int SDLCALL SDL_FillRect
768                 (SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color);
769
770 /**
771  * This function takes a surface and copies it to a new surface of the
772  * pixel format and colors of the video framebuffer, suitable for fast
773  * blitting onto the display surface.  It calls SDL_ConvertSurface()
774  *
775  * If you want to take advantage of hardware colorkey or alpha blit
776  * acceleration, you should set the colorkey and alpha value before
777  * calling this function.
778  *
779  * If the conversion fails or runs out of memory, it returns NULL
780  */
781 extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormat(SDL_Surface *surface);
782
783 /**
784  * This function takes a surface and copies it to a new surface of the
785  * pixel format and colors of the video framebuffer (if possible),
786  * suitable for fast alpha blitting onto the display surface.
787  * The new surface will always have an alpha channel.
788  *
789  * If you want to take advantage of hardware colorkey or alpha blit
790  * acceleration, you should set the colorkey and alpha value before
791  * calling this function.
792  *
793  * If the conversion fails or runs out of memory, it returns NULL
794  */
795 extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormatAlpha(SDL_Surface *surface);
796
797
798 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
799 /** @name YUV video surface overlay functions                                */ /*@{*/
800 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
801
802 /** This function creates a video output overlay
803  *  Calling the returned surface an overlay is something of a misnomer because
804  *  the contents of the display surface underneath the area where the overlay
805  *  is shown is undefined - it may be overwritten with the converted YUV data.
806  */
807 extern DECLSPEC SDL_Overlay * SDLCALL SDL_CreateYUVOverlay(int width, int height,
808                                 Uint32 format, SDL_Surface *display);
809
810 /** Lock an overlay for direct access, and unlock it when you are done */
811 extern DECLSPEC int SDLCALL SDL_LockYUVOverlay(SDL_Overlay *overlay);
812 extern DECLSPEC void SDLCALL SDL_UnlockYUVOverlay(SDL_Overlay *overlay);
813
814 /** Blit a video overlay to the display surface.
815  *  The contents of the video surface underneath the blit destination are
816  *  not defined.  
817  *  The width and height of the destination rectangle may be different from
818  *  that of the overlay, but currently only 2x scaling is supported.
819  */
820 extern DECLSPEC int SDLCALL SDL_DisplayYUVOverlay(SDL_Overlay *overlay, SDL_Rect *dstrect);
821
822 /** Free a video overlay */
823 extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay(SDL_Overlay *overlay);
824
825 /*@}*/
826
827 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
828 /** @name OpenGL support functions.                                          */ /*@{*/
829 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
830
831 /**
832  * Dynamically load an OpenGL library, or the default one if path is NULL
833  *
834  * If you do this, you need to retrieve all of the GL functions used in
835  * your program from the dynamic library using SDL_GL_GetProcAddress().
836  */
837 extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
838
839 /**
840  * Get the address of a GL function
841  */
842 extern DECLSPEC void * SDLCALL SDL_GL_GetProcAddress(const char* proc);
843
844 /**
845  * Set an attribute of the OpenGL subsystem before intialization.
846  */
847 extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
848
849 /**
850  * Get an attribute of the OpenGL subsystem from the windowing
851  * interface, such as glX. This is of course different from getting
852  * the values from SDL's internal OpenGL subsystem, which only
853  * stores the values you request before initialization.
854  *
855  * Developers should track the values they pass into SDL_GL_SetAttribute
856  * themselves if they want to retrieve these values.
857  */
858 extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int* value);
859
860 /**
861  * Swap the OpenGL buffers, if double-buffering is supported.
862  */
863 extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers(void);
864
865 /** @name OpenGL Internal Functions
866  * Internal functions that should not be called unless you have read
867  * and understood the source code for these functions.
868  */
869 /*@{*/
870 extern DECLSPEC void SDLCALL SDL_GL_UpdateRects(int numrects, SDL_Rect* rects);
871 extern DECLSPEC void SDLCALL SDL_GL_Lock(void);
872 extern DECLSPEC void SDLCALL SDL_GL_Unlock(void);
873 /*@}*/
874
875 /*@}*/
876
877 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
878 /** @name Window Manager Functions                                           */
879 /** These functions allow interaction with the window manager, if any.       */ /*@{*/
880 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
881
882 /**
883  * Sets the title and icon text of the display window (UTF-8 encoded)
884  */
885 extern DECLSPEC void SDLCALL SDL_WM_SetCaption(const char *title, const char *icon);
886 /**
887  * Gets the title and icon text of the display window (UTF-8 encoded)
888  */
889 extern DECLSPEC void SDLCALL SDL_WM_GetCaption(char **title, char **icon);
890
891 /**
892  * Sets the icon for the display window.
893  * This function must be called before the first call to SDL_SetVideoMode().
894  * It takes an icon surface, and a mask in MSB format.
895  * If 'mask' is NULL, the entire icon surface will be used as the icon.
896  */
897 extern DECLSPEC void SDLCALL SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask);
898
899 /**
900  * This function iconifies the window, and returns 1 if it succeeded.
901  * If the function succeeds, it generates an SDL_APPACTIVE loss event.
902  * This function is a noop and returns 0 in non-windowed environments.
903  */
904 extern DECLSPEC int SDLCALL SDL_WM_IconifyWindow(void);
905
906 /**
907  * Toggle fullscreen mode without changing the contents of the screen.
908  * If the display surface does not require locking before accessing
909  * the pixel information, then the memory pointers will not change.
910  *
911  * If this function was able to toggle fullscreen mode (change from 
912  * running in a window to fullscreen, or vice-versa), it will return 1.
913  * If it is not implemented, or fails, it returns 0.
914  *
915  * The next call to SDL_SetVideoMode() will set the mode fullscreen
916  * attribute based on the flags parameter - if SDL_FULLSCREEN is not
917  * set, then the display will be windowed by default where supported.
918  *
919  * This is currently only implemented in the X11 video driver.
920  */
921 extern DECLSPEC int SDLCALL SDL_WM_ToggleFullScreen(SDL_Surface *surface);
922
923 typedef enum {
924         SDL_GRAB_QUERY = -1,
925         SDL_GRAB_OFF = 0,
926         SDL_GRAB_ON = 1,
927         SDL_GRAB_FULLSCREEN     /**< Used internally */
928 } SDL_GrabMode;
929 /**
930  * This function allows you to set and query the input grab state of
931  * the application.  It returns the new input grab state.
932  *
933  * Grabbing means that the mouse is confined to the application window,
934  * and nearly all keyboard input is passed directly to the application,
935  * and not interpreted by a window manager, if any.
936  */
937 extern DECLSPEC SDL_GrabMode SDLCALL SDL_WM_GrabInput(SDL_GrabMode mode);
938
939 /*@}*/
940
941 /** @internal Not in public API at the moment - do not use! */
942 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect,
943                                     SDL_Surface *dst, SDL_Rect *dstrect);
944                     
945 /* Ends C function definitions when using C++ */
946 #ifdef __cplusplus
947 }
948 #endif
949 #include "close_code.h"
950
951 #endif /* _SDL_video_h */