Mercurial > sdl-ios-xcode

comparison include/SDL_surface.h @ 3407:d3baf5ac4e37

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Partial fix for bug #859 Header file update from Ken for improved doxygen output
author Sam Lantinga <slouken@libsdl.org>
date Mon, 19 Oct 2009 13:31:58 +0000
parents 710139a1692d
children 147d6ef5be03
comparison
equal deleted inserted replaced
3406:8ae607392409 3407:d3baf5ac4e37
19 Sam Lantinga 19 Sam Lantinga
20 slouken@libsdl.org 20 slouken@libsdl.org
21 */ 21 */
22 22
23 /** 23 /**
24 * \file SDL_surface.h 24 * \file SDL_surface.h
25 * 25 *
26 * Header file for SDL_surface definition and management functions 26 * Header file for ::SDL_surface definition and management functions.
27 */ 27 */
28 28
29 #ifndef _SDL_surface_h 29 #ifndef _SDL_surface_h
30 #define _SDL_surface_h 30 #define _SDL_surface_h
31 31
40 /* *INDENT-OFF* */ 40 /* *INDENT-OFF* */
41 extern "C" { 41 extern "C" {
42 /* *INDENT-ON* */ 42 /* *INDENT-ON* */
43 #endif 43 #endif
44 44
45 /** These are the currently supported flags for the SDL_surface 45 /**
46 * \internal Used internally (read-only) 46 * \name Surface flags
47 *
48 * These are the currently supported flags for the ::SDL_surface.
49 *
50 * \internal
51 * Used internally (read-only).
47 */ 52 */
48 /*@{*/ 53 /*@{*/
49 #define SDL_PREALLOC 0x00000001 /**< Surface uses preallocated memory */ 54 #define SDL_PREALLOC 0x00000001 /**< Surface uses preallocated memory */
50 #define SDL_RLEACCEL 0x00000002 /**< Surface is RLE encoded */ 55 #define SDL_RLEACCEL 0x00000002 /**< Surface is RLE encoded */
51 /*@}*/ 56 /*@}*//*Surface flags*/
52 57
53 /** Evaluates to true if the surface needs to be locked before access */ 58 /**
59 * Evaluates to true if the surface needs to be locked before access.
60 */
54 #define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0) 61 #define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0)
55 62
56 /** 63 /**
57 * \brief A collection of pixels used in software blitting 64 * \brief A collection of pixels used in software blitting.
58 * 65 *
59 * \note This structure should be treated as read-only, except for 'pixels', 66 * \note This structure should be treated as read-only, except for \c pixels,
60 * which, if not NULL, contains the raw pixel data for the surface. 67 * which, if not NULL, contains the raw pixel data for the surface.
61 */ 68 */
62 typedef struct SDL_Surface 69 typedef struct SDL_Surface
63 { 70 {
64 Uint32 flags; /**< Read-only */ 71 Uint32 flags; /**< Read-only */
65 SDL_PixelFormat *format; /**< Read-only */ 72 SDL_PixelFormat *format; /**< Read-only */
66 int w, h; /**< Read-only */ 73 int w, h; /**< Read-only */
67 int pitch; /**< Read-only */ 74 int pitch; /**< Read-only */
68 void *pixels; /**< Read-write */ 75 void *pixels; /**< Read-write */
69 76
70 /* Application data associated with the surfade */ 77 /** Application data associated with the surfade */
71 void *userdata; /**< Read-write */ 78 void *userdata; /**< Read-write */
72 79
73 /* information needed for surfaces requiring locks */ 80 /** information needed for surfaces requiring locks */
74 int locked; /**< Read-only */ 81 int locked; /**< Read-only */
75 void *lock_data; /**< Read-only */ 82 void *lock_data; /**< Read-only */
76 83
77 /* clipping information */ 84 /** clipping information */
78 SDL_Rect clip_rect; /**< Read-only */ 85 SDL_Rect clip_rect; /**< Read-only */
79 86
80 /* info for fast blit mapping to other surfaces */ 87 /** info for fast blit mapping to other surfaces */
81 struct SDL_BlitMap *map; /**< Private */ 88 struct SDL_BlitMap *map; /**< Private */
82 89
83 /* format version, bumped at every change to invalidate blit maps */ 90 /** format version, bumped at every change to invalidate blit maps */
84 unsigned int format_version; /**< Private */ 91 unsigned int format_version; /**< Private */
85 92
86 /* Reference count -- used when freeing surface */ 93 /** Reference count -- used when freeing surface */
87 int refcount; /**< Read-mostly */ 94 int refcount; /**< Read-mostly */
88 } SDL_Surface; 95 } SDL_Surface;
89 96
90 /** 97 /**
91 * \brief The type of function used for surface blitting functions 98 * \brief The type of function used for surface blitting functions.
92 */ 99 */
93 typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect, 100 typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
94 struct SDL_Surface * dst, SDL_Rect * dstrect); 101 struct SDL_Surface * dst, SDL_Rect * dstrect);
95 102
96 /** 103 /**
97 * Allocate and free an RGB surface (must be called after SDL_SetVideoMode) 104 * Allocate and free an RGB surface (must be called after SDL_SetVideoMode).
98 * If the depth is 4 or 8 bits, an empty palette is allocated for the surface. 105 *
99 * If the depth is greater than 8 bits, the pixel format is set using the 106 * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
100 * flags '[RGB]mask'. 107 * If the depth is greater than 8 bits, the pixel format is set using the
101 * If the function runs out of memory, it will return NULL. 108 * flags '[RGB]mask'.
102 * 109 *
103 * \param flags The 'flags' are obsolete and should be set to 0. 110 * If the function runs out of memory, it will return NULL.
111 *
112 * \param flags The \c flags are obsolete and should be set to 0.
104 */ 113 */
105 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface 114 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
106 (Uint32 flags, int width, int height, int depth, 115 (Uint32 flags, int width, int height, int depth,
107 Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask); 116 Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
108 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels, 117 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
115 Uint32 Bmask, 124 Uint32 Bmask,
116 Uint32 Amask); 125 Uint32 Amask);
117 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface); 126 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
118 127
119 /** 128 /**
120 * \brief Set the palette used by a surface. 129 * \brief Set the palette used by a surface.
121 * 130 *
122 * \return 0, or -1 if the surface format doesn't use a palette. 131 * \return 0, or -1 if the surface format doesn't use a palette.
123 * 132 *
124 * \note A single palette can be shared with many surfaces. 133 * \note A single palette can be shared with many surfaces.
125 */ 134 */
126 extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface, 135 extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
127 SDL_Palette * palette); 136 SDL_Palette * palette);
128 137
129 /** 138 /**
130 * \brief Sets up a surface for directly accessing the pixels. 139 * \brief Sets up a surface for directly accessing the pixels.
131 * 140 *
132 * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write 141 * Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write
133 * to and read from 'surface->pixels', using the pixel format stored in 142 * to and read from \c surface->pixels, using the pixel format stored in
134 * 'surface->format'. Once you are done accessing the surface, you should 143 * \c surface->format. Once you are done accessing the surface, you should
135 * use SDL_UnlockSurface() to release it. 144 * use SDL_UnlockSurface() to release it.
136 * 145 *
137 * Not all surfaces require locking. If SDL_MUSTLOCK(surface) evaluates 146 * Not all surfaces require locking. If SDL_MUSTLOCK(surface) evaluates
138 * to 0, then you can read and write to the surface at any time, and the 147 * to 0, then you can read and write to the surface at any time, and the
139 * pixel format of the surface will not change. 148 * pixel format of the surface will not change.
140 * 149 *
141 * No operating system or library calls should be made between lock/unlock 150 * No operating system or library calls should be made between lock/unlock
142 * pairs, as critical system locks may be held during this time. 151 * pairs, as critical system locks may be held during this time.
143 * 152 *
144 * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked. 153 * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
145 * 154 *
146 * \sa SDL_UnlockSurface() 155 * \sa SDL_UnlockSurface()
147 */ 156 */
148 extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface); 157 extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
149 /** \sa SDL_LockSurface() */ 158 /** \sa SDL_LockSurface() */
150 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface); 159 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
151 160
152 /** 161 /**
153 * Load a surface from a seekable SDL data source (memory or file.) 162 * Load a surface from a seekable SDL data source (memory or file).
154 * If 'freesrc' is non-zero, the source will be closed after being read. 163 *
155 * Returns the new surface, or NULL if there was an error. 164 * If \c freesrc is non-zero, the source will be closed after being read.
156 * The new surface should be freed with SDL_FreeSurface(). 165 *
166 * The new surface should be freed with SDL_FreeSurface().
167 *
168 * \return the new surface, or NULL if there was an error.
157 */ 169 */
158 extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src, 170 extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
159 int freesrc); 171 int freesrc);
160 172
161 /** Convenience macro -- load a surface from a file */ 173 /**
174 * Load a surface from a file.
175 *
176 * Convenience macro.
177 */
162 #define SDL_LoadBMP(file) SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1) 178 #define SDL_LoadBMP(file) SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
163 179
164 /** 180 /**
165 * Save a surface to a seekable SDL data source (memory or file.) 181 * Save a surface to a seekable SDL data source (memory or file).
166 * If 'freedst' is non-zero, the source will be closed after being written. 182 *
167 * Returns 0 if successful or -1 if there was an error. 183 * If \c freedst is non-zero, the source will be closed after being written.
184 *
185 * \return 0 if successful or -1 if there was an error.
168 */ 186 */
169 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW 187 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
170 (SDL_Surface * surface, SDL_RWops * dst, int freedst); 188 (SDL_Surface * surface, SDL_RWops * dst, int freedst);
171 189
172 /** Convenience macro -- save a surface to a file */ 190 /**
191 * Save a surface to a file.
192 *
193 * Convenience macro.
194 */
173 #define SDL_SaveBMP(surface, file) \ 195 #define SDL_SaveBMP(surface, file) \
174 SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1) 196 SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
175 197
176 /** 198 /**
177 * \brief Sets the RLE acceleration hint for a surface. 199 * \brief Sets the RLE acceleration hint for a surface.
178 * 200 *
179 * \return 0 on success, or -1 if the surface is not valid 201 * \return 0 on success, or -1 if the surface is not valid
180 * 202 *
181 * \note If RLE is enabled, colorkey and alpha blending blits are much faster, 203 * \note If RLE is enabled, colorkey and alpha blending blits are much faster,
182 * but the surface must be locked before directly accessing the pixels. 204 * but the surface must be locked before directly accessing the pixels.
183 */ 205 */
184 extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface, 206 extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface,
185 int flag); 207 int flag);
186 208
187 /** 209 /**
188 * \brief Sets the color key (transparent pixel) in a blittable surface. 210 * \brief Sets the color key (transparent pixel) in a blittable surface.
189 * 211 *
190 * \param surface The surface to update 212 * \param surface The surface to update
191 * \param flag Non-zero to enable colorkey and 0 to disable colorkey 213 * \param flag Non-zero to enable colorkey and 0 to disable colorkey
192 * \param key The transparent pixel in the native surface format 214 * \param key The transparent pixel in the native surface format
193 * 215 *
194 * \return 0 on success, or -1 if the surface is not valid 216 * \return 0 on success, or -1 if the surface is not valid
195 */ 217 */
196 extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface, 218 extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface,
197 Uint32 flag, Uint32 key); 219 Uint32 flag, Uint32 key);
198 220
199 /** 221 /**
200 * \brief Sets the color key (transparent pixel) in a blittable surface. 222 * \brief Sets the color key (transparent pixel) in a blittable surface.
201 * 223 *
202 * \param surface The surface to update 224 * \param surface The surface to update
203 * \param key A pointer filled in with the transparent pixel in the native surface format 225 * \param key A pointer filled in with the transparent pixel in the native
204 * 226 * surface format
205 * \return 0 on success, or -1 if the surface is not valid or colorkey is not enabled. 227 *
228 * \return 0 on success, or -1 if the surface is not valid or colorkey is not
229 * enabled.
206 */ 230 */
207 extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface, 231 extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface,
208 Uint32 * key); 232 Uint32 * key);
209 233
210 /** 234 /**
211 * \brief Set an additional color value used in blit operations 235 * \brief Set an additional color value used in blit operations.
212 * 236 *
213 * \param surface The surface to update 237 * \param surface The surface to update.
214 * \param r The red source color value multiplied into blit operations 238 * \param r The red source color value multiplied into blit operations.
215 * \param g The green source color value multiplied into blit operations 239 * \param g The green source color value multiplied into blit operations.
216 * \param b The blue source color value multiplied into blit operations 240 * \param b The blue source color value multiplied into blit operations.
217 * 241 *
218 * \return 0 on success, or -1 if the surface is not valid 242 * \return 0 on success, or -1 if the surface is not valid.
219 * 243 *
220 * \sa SDL_GetSurfaceColorMod() 244 * \sa SDL_GetSurfaceColorMod()
221 */ 245 */
222 extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface, 246 extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface,
223 Uint8 r, Uint8 g, Uint8 b); 247 Uint8 r, Uint8 g, Uint8 b);
224 248
225 249
226 /** 250 /**
227 * \brief Get the additional color value used in blit operations 251 * \brief Get the additional color value used in blit operations.
228 * 252 *
229 * \param surface The surface to query 253 * \param surface The surface to query.
230 * \param r A pointer filled in with the source red color value 254 * \param r A pointer filled in with the source red color value.
231 * \param g A pointer filled in with the source green color value 255 * \param g A pointer filled in with the source green color value.
232 * \param b A pointer filled in with the source blue color value 256 * \param b A pointer filled in with the source blue color value.
233 * 257 *
234 * \return 0 on success, or -1 if the surface is not valid 258 * \return 0 on success, or -1 if the surface is not valid.
235 * 259 *
236 * \sa SDL_SetSurfaceColorMod() 260 * \sa SDL_SetSurfaceColorMod()
237 */ 261 */
238 extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface, 262 extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface,
239 Uint8 * r, Uint8 * g, 263 Uint8 * r, Uint8 * g,
240 Uint8 * b); 264 Uint8 * b);
241 265
242 /** 266 /**
243 * \brief Set an additional alpha value used in blit operations 267 * \brief Set an additional alpha value used in blit operations.
244 * 268 *
245 * \param surface The surface to update 269 * \param surface The surface to update.
246 * \param alpha The source alpha value multiplied into blit operations. 270 * \param alpha The source alpha value multiplied into blit operations.
247 * 271 *
248 * \return 0 on success, or -1 if the surface is not valid 272 * \return 0 on success, or -1 if the surface is not valid.
249 * 273 *
250 * \sa SDL_GetSurfaceAlphaMod() 274 * \sa SDL_GetSurfaceAlphaMod()
251 */ 275 */
252 extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface, 276 extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface,
253 Uint8 alpha); 277 Uint8 alpha);
254 278
255 /** 279 /**
256 * \brief Get the additional alpha value used in blit operations 280 * \brief Get the additional alpha value used in blit operations.
257 * 281 *
258 * \param surface The surface to query 282 * \param surface The surface to query.
259 * \param alpha A pointer filled in with the source alpha value 283 * \param alpha A pointer filled in with the source alpha value.
260 * 284 *
261 * \return 0 on success, or -1 if the surface is not valid 285 * \return 0 on success, or -1 if the surface is not valid.
262 * 286 *
263 * \sa SDL_SetSurfaceAlphaMod() 287 * \sa SDL_SetSurfaceAlphaMod()
264 */ 288 */
265 extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface, 289 extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface,
266 Uint8 * alpha); 290 Uint8 * alpha);
267 291
268 /** 292 /**
269 * \brief Set the blend mode used for blit operations 293 * \brief Set the blend mode used for blit operations.
270 * 294 *
271 * \param surface The surface to update 295 * \param surface The surface to update.
272 * \param blendMode SDL_TextureBlendMode to use for blit blending 296 * \param blendMode ::SDL_BlendMode to use for blit blending.
273 * 297 *
274 * \return 0 on success, or -1 if the parameters are not valid 298 * \return 0 on success, or -1 if the parameters are not valid.
275 * 299 *
276 * \sa SDL_GetSurfaceBlendMode() 300 * \sa SDL_GetSurfaceBlendMode()
277 */ 301 */
278 extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface, 302 extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface,
279 int blendMode); 303 int blendMode);
280 304
281 /** 305 /**
282 * \brief Get the blend mode used for blit operations 306 * \brief Get the blend mode used for blit operations.
283 * 307 *
284 * \param surface The surface to query 308 * \param surface The surface to query.
285 * \param blendMode A pointer filled in with the current blend mode 309 * \param blendMode A pointer filled in with the current blend mode.
286 * 310 *
287 * \return 0 on success, or -1 if the surface is not valid 311 * \return 0 on success, or -1 if the surface is not valid.
288 * 312 *
289 * \sa SDL_SetSurfaceBlendMode() 313 * \sa SDL_SetSurfaceBlendMode()
290 */ 314 */
291 extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface, 315 extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
292 int *blendMode); 316 int *blendMode);
293 317
294 /** 318 /**
295 * \brief Set the scale mode used for blit operations 319 * \brief Set the scale mode used for blit operations.
296 * 320 *
297 * \param surface The surface to update 321 * \param surface The surface to update.
298 * \param scaleMode SDL_TextureScaleMode to use for blit scaling 322 * \param scaleMode ::SDL_TextureScaleMode to use for blit scaling.
299 * 323 *
300 * \return 0 on success, or -1 if the surface is not valid or the scale mode is not supported 324 * \return 0 on success, or -1 if the surface is not valid or the scale mode is
301 * 325 * not supported.
302 * \note If the scale mode is not supported, the closest supported mode is chosen. Currently only SDL_TEXTURESCALEMODE_FAST is supported on surfaces. 326 *
303 * 327 * \note If the scale mode is not supported, the closest supported mode is
304 * \sa SDL_GetSurfaceScaleMode() 328 * chosen. Currently only ::SDL_TEXTURESCALEMODE_FAST is supported on
329 * surfaces.
330 *
331 * \sa SDL_GetSurfaceScaleMode()
305 */ 332 */
306 extern DECLSPEC int SDLCALL SDL_SetSurfaceScaleMode(SDL_Surface * surface, 333 extern DECLSPEC int SDLCALL SDL_SetSurfaceScaleMode(SDL_Surface * surface,
307 int scaleMode); 334 int scaleMode);
308 335
309 /** 336 /**
310 * \brief Get the scale mode used for blit operations 337 * \brief Get the scale mode used for blit operations.
311 * 338 *
312 * \param surface The surface to query 339 * \param surface The surface to query.
313 * \param scaleMode A pointer filled in with the current scale mode 340 * \param scaleMode A pointer filled in with the current scale mode.
314 * 341 *
315 * \return 0 on success, or -1 if the surface is not valid 342 * \return 0 on success, or -1 if the surface is not valid.
316 * 343 *
317 * \sa SDL_SetSurfaceScaleMode() 344 * \sa SDL_SetSurfaceScaleMode()
318 */ 345 */
319 extern DECLSPEC int SDLCALL SDL_GetSurfaceScaleMode(SDL_Surface * surface, 346 extern DECLSPEC int SDLCALL SDL_GetSurfaceScaleMode(SDL_Surface * surface,
320 int *scaleMode); 347 int *scaleMode);
321 348
322 /** 349 /**
323 * Sets the clipping rectangle for the destination surface in a blit. 350 * Sets the clipping rectangle for the destination surface in a blit.
324 * 351 *
325 * If the clip rectangle is NULL, clipping will be disabled. 352 * If the clip rectangle is NULL, clipping will be disabled.
326 * If the clip rectangle doesn't intersect the surface, the function will 353 *
327 * return SDL_FALSE and blits will be completely clipped. Otherwise the 354 * If the clip rectangle doesn't intersect the surface, the function will
328 * function returns SDL_TRUE and blits to the surface will be clipped to 355 * return SDL_FALSE and blits will be completely clipped. Otherwise the
329 * the intersection of the surface area and the clipping rectangle. 356 * function returns SDL_TRUE and blits to the surface will be clipped to
330 * 357 * the intersection of the surface area and the clipping rectangle.
331 * Note that blits are automatically clipped to the edges of the source 358 *
332 * and destination surfaces. 359 * Note that blits are automatically clipped to the edges of the source
360 * and destination surfaces.
333 */ 361 */
334 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface, 362 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
335 const SDL_Rect * rect); 363 const SDL_Rect * rect);
336 364
337 /** 365 /**
338 * Gets the clipping rectangle for the destination surface in a blit. 366 * Gets the clipping rectangle for the destination surface in a blit.
339 * 'rect' must be a pointer to a valid rectangle which will be filled 367 *
340 * with the correct values. 368 * \c rect must be a pointer to a valid rectangle which will be filled
369 * with the correct values.
341 */ 370 */
342 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface, 371 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
343 SDL_Rect * rect); 372 SDL_Rect * rect);
344 373
345 /** 374 /**
346 * Creates a new surface of the specified format, and then copies and maps 375 * Creates a new surface of the specified format, and then copies and maps
347 * the given surface to it so the blit of the converted surface will be as 376 * the given surface to it so the blit of the converted surface will be as
348 * fast as possible. If this function fails, it returns NULL. 377 * fast as possible. If this function fails, it returns NULL.
349 * 378 *
350 * The 'flags' parameter is passed to SDL_CreateRGBSurface() and has those 379 * The \c flags parameter is passed to SDL_CreateRGBSurface() and has those
351 * semantics. You can also pass SDL_RLEACCEL in the flags parameter and 380 * semantics. You can also pass ::SDL_RLEACCEL in the flags parameter and
352 * SDL will try to RLE accelerate colorkey and alpha blits in the resulting 381 * SDL will try to RLE accelerate colorkey and alpha blits in the resulting
353 * surface. 382 * surface.
354 * 383 *
355 * This function is used internally by SDL_DisplayFormat(). 384 * This function is used internally by SDL_DisplayFormat().
356 */ 385 */
357 extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface 386 extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
358 (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags); 387 (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags);
359 388
360 /** 389 /**
361 * This function draws a point with 'color' 390 * Draws a point with \c color.
362 * The color should be a pixel of the format used by the surface, and 391 *
363 * can be generated by the SDL_MapRGB() function. 392 * The color should be a pixel of the format used by the surface, and
364 * \return This function returns 0 on success, or -1 on error. 393 * can be generated by the SDL_MapRGB() function.
394 *
395 * \return 0 on success, or -1 on error.
365 */ 396 */
366 extern DECLSPEC int SDLCALL SDL_DrawPoint 397 extern DECLSPEC int SDLCALL SDL_DrawPoint
367 (SDL_Surface * dst, int x, int y, Uint32 color); 398 (SDL_Surface * dst, int x, int y, Uint32 color);
368 399
369 /** 400 /**
370 * This function blends a point with an RGBA value 401 * Blends a point with an RGBA value.
371 * The color should be a pixel of the format used by the surface, and 402 *
372 * can be generated by the SDL_MapRGB() function. 403 * The color should be a pixel of the format used by the surface, and
373 * \return This function returns 0 on success, or -1 on error. 404 * can be generated by the SDL_MapRGB() function.
405 *
406 * \return 0 on success, or -1 on error.
374 */ 407 */
375 extern DECLSPEC int SDLCALL SDL_BlendPoint 408 extern DECLSPEC int SDLCALL SDL_BlendPoint
376 (SDL_Surface * dst, int x, int y, int blendMode, 409 (SDL_Surface * dst, int x, int y, int blendMode,
377 Uint8 r, Uint8 g, Uint8 b, Uint8 a); 410 Uint8 r, Uint8 g, Uint8 b, Uint8 a);
378 411
379 /** 412 /**
380 * This function draws a line with 'color' 413 * Draws a line with \c color.
381 * The color should be a pixel of the format used by the surface, and 414 *
382 * can be generated by the SDL_MapRGB() function. 415 * The color should be a pixel of the format used by the surface, and
383 * \return This function returns 0 on success, or -1 on error. 416 * can be generated by the SDL_MapRGB() function.
417 *
418 * \return 0 on success, or -1 on error.
384 */ 419 */
385 extern DECLSPEC int SDLCALL SDL_DrawLine 420 extern DECLSPEC int SDLCALL SDL_DrawLine
386 (SDL_Surface * dst, int x1, int y1, int x2, int y2, Uint32 color); 421 (SDL_Surface * dst, int x1, int y1, int x2, int y2, Uint32 color);
387 422
388 /** 423 /**
389 * This function blends an RGBA value along a line 424 * Blends an RGBA value along a line.
390 * \return This function returns 0 on success, or -1 on error. 425 *
426 * \return 0 on success, or -1 on error.
391 */ 427 */
392 extern DECLSPEC int SDLCALL SDL_BlendLine 428 extern DECLSPEC int SDLCALL SDL_BlendLine
393 (SDL_Surface * dst, int x1, int y1, int x2, int y2, int blendMode, 429 (SDL_Surface * dst, int x1, int y1, int x2, int y2, int blendMode,
394 Uint8 r, Uint8 g, Uint8 b, Uint8 a); 430 Uint8 r, Uint8 g, Uint8 b, Uint8 a);
395 431
396 /** 432 /**
397 * This function performs a fast fill of the given rectangle with 'color' 433 * Performs a fast fill of the given rectangle with \c color.
398 * The given rectangle is clipped to the destination surface clip area 434 *
399 * and the final fill rectangle is saved in the passed in pointer. 435 * The given rectangle is clipped to the destination surface clip area
400 * If 'dstrect' is NULL, the whole surface will be filled with 'color' 436 * and the final fill rectangle is saved in the passed in pointer.
401 * The color should be a pixel of the format used by the surface, and 437 *
402 * can be generated by the SDL_MapRGB() function. 438 * If \c dstrect is NULL, the whole surface will be filled with \c color.
403 * \return This function returns 0 on success, or -1 on error. 439 *
440 * The color should be a pixel of the format used by the surface, and
441 * can be generated by the SDL_MapRGB() function.
442 *
443 * \return 0 on success, or -1 on error.
404 */ 444 */
405 extern DECLSPEC int SDLCALL SDL_FillRect 445 extern DECLSPEC int SDLCALL SDL_FillRect
406 (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color); 446 (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color);
407 447
408 /** 448 /**
409 * This function blends an RGBA value into the given rectangle. 449 * Blends an RGBA value into the given rectangle.
410 * The given rectangle is clipped to the destination surface clip area 450 *
411 * and the final fill rectangle is saved in the passed in pointer. 451 * The given rectangle is clipped to the destination surface clip area
412 * If 'dstrect' is NULL, the whole surface will be filled with 'color' 452 * and the final fill rectangle is saved in the passed in pointer.
413 * \return This function returns 0 on success, or -1 on error. 453 *
454 * If \c dstrect is NULL, the whole surface will be filled with \c color.
455 *
456 * \return This function returns 0 on success, or -1 on error.
414 */ 457 */
415 extern DECLSPEC int SDLCALL SDL_BlendRect 458 extern DECLSPEC int SDLCALL SDL_BlendRect
416 (SDL_Surface * dst, SDL_Rect * dstrect, int blendMode, Uint8 r, Uint8 g, 459 (SDL_Surface * dst, SDL_Rect * dstrect, int blendMode, Uint8 r, Uint8 g,
417 Uint8 b, Uint8 a); 460 Uint8 b, Uint8 a);
418 461
419 /** 462 /**
420 * This performs a fast blit from the source surface to the destination 463 * Performs a fast blit from the source surface to the destination surface.
421 * surface. It assumes that the source and destination rectangles are 464 *
422 * the same size. If either 'srcrect' or 'dstrect' are NULL, the entire 465 * This assumes that the source and destination rectangles are
423 * surface (src or dst) is copied. The final blit rectangles are saved 466 * the same size. If either \c srcrect or \c dstrect are NULL, the entire
424 * in 'srcrect' and 'dstrect' after all clipping is performed. 467 * surface (\c src or \c dst) is copied. The final blit rectangles are saved
425 * If the blit is successful, it returns 0, otherwise it returns -1. 468 * in \c srcrect and \c dstrect after all clipping is performed.
469 *
470 * \return If the blit is successful, it returns 0, otherwise it returns -1.
426 * 471 *
427 * The blit function should not be called on a locked surface. 472 * The blit function should not be called on a locked surface.
428 * 473 *
429 * The blit semantics for surfaces with and without alpha and colorkey 474 * The blit semantics for surfaces with and without alpha and colorkey
430 * are defined as follows: 475 * are defined as follows:
431 * 476 * \verbatim
432 * RGBA->RGB: 477 RGBA->RGB:
433 * SDL_SRCALPHA set: 478 SDL_SRCALPHA set:
434 * alpha-blend (using alpha-channel). 479 alpha-blend (using alpha-channel).
435 * SDL_SRCCOLORKEY ignored. 480 SDL_SRCCOLORKEY ignored.
436 * SDL_SRCALPHA not set: 481 SDL_SRCALPHA not set:
437 * copy RGB. 482 copy RGB.
438 * if SDL_SRCCOLORKEY set, only copy the pixels matching the 483 if SDL_SRCCOLORKEY set, only copy the pixels matching the
439 * RGB values of the source colour key, ignoring alpha in the 484 RGB values of the source colour key, ignoring alpha in the
440 * comparison. 485 comparison.
441 * 486
442 * RGB->RGBA: 487 RGB->RGBA:
443 * SDL_SRCALPHA set: 488 SDL_SRCALPHA set:
444 * alpha-blend (using the source per-surface alpha value); 489 alpha-blend (using the source per-surface alpha value);
445 * set destination alpha to opaque. 490 set destination alpha to opaque.
446 * SDL_SRCALPHA not set: 491 SDL_SRCALPHA not set:
447 * copy RGB, set destination alpha to source per-surface alpha value. 492 copy RGB, set destination alpha to source per-surface alpha value.
448 * both: 493 both:
449 * if SDL_SRCCOLORKEY set, only copy the pixels matching the 494 if SDL_SRCCOLORKEY set, only copy the pixels matching the
450 * source colour key. 495 source colour key.
451 * 496
452 * RGBA->RGBA: 497 RGBA->RGBA:
453 * SDL_SRCALPHA set: 498 SDL_SRCALPHA set:
454 * alpha-blend (using the source alpha channel) the RGB values; 499 alpha-blend (using the source alpha channel) the RGB values;
455 * leave destination alpha untouched. [Note: is this correct?] 500 leave destination alpha untouched. [Note: is this correct?]
456 * SDL_SRCCOLORKEY ignored. 501 SDL_SRCCOLORKEY ignored.
457 * SDL_SRCALPHA not set: 502 SDL_SRCALPHA not set:
458 * copy all of RGBA to the destination. 503 copy all of RGBA to the destination.
459 * if SDL_SRCCOLORKEY set, only copy the pixels matching the 504 if SDL_SRCCOLORKEY set, only copy the pixels matching the
460 * RGB values of the source colour key, ignoring alpha in the 505 RGB values of the source colour key, ignoring alpha in the
461 * comparison. 506 comparison.
462 * 507
463 * RGB->RGB: 508 RGB->RGB:
464 * SDL_SRCALPHA set: 509 SDL_SRCALPHA set:
465 * alpha-blend (using the source per-surface alpha value). 510 alpha-blend (using the source per-surface alpha value).
466 * SDL_SRCALPHA not set: 511 SDL_SRCALPHA not set:
467 * copy RGB. 512 copy RGB.
468 * both: 513 both:
469 * if SDL_SRCCOLORKEY set, only copy the pixels matching the 514 if SDL_SRCCOLORKEY set, only copy the pixels matching the
470 * source colour key. 515 source colour key.
471 * 516 \endverbatim
472 * If either of the surfaces were in video memory, and the blit returns -2, 517 *
473 * the video memory was lost, so it should be reloaded with artwork and 518 * If either of the surfaces were in video memory, and the blit returns -2,
474 * re-blitted: 519 * the video memory was lost, so it should be reloaded with artwork and
475 * @code 520 * re-blitted:
476 * while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) { 521 * @code
477 * while ( SDL_LockSurface(image) < 0 ) 522 * while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
478 * Sleep(10); 523 * while ( SDL_LockSurface(image) < 0 )
479 * -- Write image pixels to image->pixels -- 524 * Sleep(10);
480 * SDL_UnlockSurface(image); 525 * -- Write image pixels to image->pixels --
481 * } 526 * SDL_UnlockSurface(image);
482 * @endcode 527 * }
483 * 528 * @endcode
484 * This happens under DirectX 5.0 when the system switches away from your 529 *
485 * fullscreen application. The lock will also fail until you have access 530 * This happens under DirectX 5.0 when the system switches away from your
486 * to the video memory again. 531 * fullscreen application. The lock will also fail until you have access
487 * 532 * to the video memory again.
488 * You should call SDL_BlitSurface() unless you know exactly how SDL 533 *
489 * blitting works internally and how to use the other blit functions. 534 * You should call SDL_BlitSurface() unless you know exactly how SDL
535 * blitting works internally and how to use the other blit functions.
490 */ 536 */
491 #define SDL_BlitSurface SDL_UpperBlit 537 #define SDL_BlitSurface SDL_UpperBlit
492 538
493 /** This is the public blit function, SDL_BlitSurface(), and it performs 539 /**
540 * This is the public blit function, SDL_BlitSurface(), and it performs
494 * rectangle validation and clipping before passing it to SDL_LowerBlit() 541 * rectangle validation and clipping before passing it to SDL_LowerBlit()
495 */ 542 */
496 extern DECLSPEC int SDLCALL SDL_UpperBlit 543 extern DECLSPEC int SDLCALL SDL_UpperBlit
497 (SDL_Surface * src, SDL_Rect * srcrect, 544 (SDL_Surface * src, SDL_Rect * srcrect,
498 SDL_Surface * dst, SDL_Rect * dstrect); 545 SDL_Surface * dst, SDL_Rect * dstrect);
499 546
500 /** This is a semi-private blit function and it performs low-level surface 547 /**
548 * This is a semi-private blit function and it performs low-level surface
501 * blitting only. 549 * blitting only.
502 */ 550 */
503 extern DECLSPEC int SDLCALL SDL_LowerBlit 551 extern DECLSPEC int SDLCALL SDL_LowerBlit
504 (SDL_Surface * src, SDL_Rect * srcrect, 552 (SDL_Surface * src, SDL_Rect * srcrect,
505 SDL_Surface * dst, SDL_Rect * dstrect); 553 SDL_Surface * dst, SDL_Rect * dstrect);
506 554
507 /** 555 /**
508 * \brief Perform a fast, low quality, stretch blit between two surfaces of the same pixel format. 556 * \brief Perform a fast, low quality, stretch blit between two surfaces of the
509 * 557 * same pixel format.
510 * \note This function uses a static buffer, and is not thread-safe. 558 *
559 * \note This function uses a static buffer, and is not thread-safe.
511 */ 560 */
512 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src, 561 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
513 const SDL_Rect * srcrect, 562 const SDL_Rect * srcrect,
514 SDL_Surface * dst, 563 SDL_Surface * dst,
515 const SDL_Rect * dstrect); 564 const SDL_Rect * dstrect);