]>
Commit | Line | Data |
---|---|---|
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 | /* Not in public API at the moment - do not use! */ | |
882 | extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect, | |
883 | SDL_Surface *dst, SDL_Rect *dstrect); | |
884 | ||
885 | /* Ends C function definitions when using C++ */ | |
886 | #ifdef __cplusplus | |
887 | } | |
888 | #endif | |
889 | #include "close_code.h" | |
890 | ||
891 | #endif /* _SDL_video_h */ |