Mercurial > sdl-ios-xcode

comparison include/SDL_surface.h @ 3341:710139a1692d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fixed bug #826 Ken Bull 2009-10-04 09:51:30 PDT 2009/10/4 E. Wing <ewmailing@gmail.com>: > Hi Kenneth, > I noticed that SDL_SetColorKey and SDL_GetColorKey start with > /* > instead of > /** > in SDL_Surface.h in SDL 1.3. > > I haven't scrutinized the headers and I don't know if you had an > automated process to add these, but I thought I would let you know in > case there might be others that have the same problem. > > Thanks, > Eric > The attached patch corrects this and other documentation errors in SDL_surface.h
author Sam Lantinga <slouken@libsdl.org>
date Sun, 04 Oct 2009 19:14:30 +0000
parents 7be21a78777e
children d3baf5ac4e37
comparison
equal deleted inserted replaced
3340:3d75acd08339 3341:710139a1692d
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 /** These are the currently supported flags for the SDL_surface
46 /* Used internally (read-only) */ 46 * \internal Used internally (read-only)
47 #define SDL_PREALLOC 0x00000001 /* Surface uses preallocated memory */ 47 */
48 #define SDL_RLEACCEL 0x00000002 /* Surface is RLE encoded */ 48 /*@{*/
49 49 #define SDL_PREALLOC 0x00000001 /**< Surface uses preallocated memory */
50 /* Evaluates to true if the surface needs to be locked before access */ 50 #define SDL_RLEACCEL 0x00000002 /**< Surface is RLE encoded */
51 /*@}*/
52
53 /** Evaluates to true if the surface needs to be locked before access */
51 #define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0) 54 #define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0)
52 55
53 /** 56 /**
54 * \struct SDL_Surface
55 *
56 * \brief A collection of pixels used in software blitting 57 * \brief A collection of pixels used in software blitting
57 * 58 *
58 * \note This structure should be treated as read-only, except for 'pixels', 59 * \note This structure should be treated as read-only, except for 'pixels',
59 * which, if not NULL, contains the raw pixel data for the surface. 60 * which, if not NULL, contains the raw pixel data for the surface.
60 */ 61 */
85 /* Reference count -- used when freeing surface */ 86 /* Reference count -- used when freeing surface */
86 int refcount; /**< Read-mostly */ 87 int refcount; /**< Read-mostly */
87 } SDL_Surface; 88 } SDL_Surface;
88 89
89 /** 90 /**
90 * \typedef SDL_blit
91 *
92 * \brief The type of function used for surface blitting functions 91 * \brief The type of function used for surface blitting functions
93 */ 92 */
94 typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect, 93 typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
95 struct SDL_Surface * dst, SDL_Rect * dstrect); 94 struct SDL_Surface * dst, SDL_Rect * dstrect);
96 95
97 /* 96 /**
98 * Allocate and free an RGB surface (must be called after SDL_SetVideoMode) 97 * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
99 * If the depth is 4 or 8 bits, an empty palette is allocated for the surface. 98 * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
100 * If the depth is greater than 8 bits, the pixel format is set using the 99 * If the depth is greater than 8 bits, the pixel format is set using the
101 * flags '[RGB]mask'. 100 * flags '[RGB]mask'.
102 * If the function runs out of memory, it will return NULL. 101 * If the function runs out of memory, it will return NULL.
103 * 102 *
104 * The 'flags' are obsolete and should be set to 0. 103 * \param flags The 'flags' are obsolete and should be set to 0.
105 */ 104 */
106 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface 105 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
107 (Uint32 flags, int width, int height, int depth, 106 (Uint32 flags, int width, int height, int depth,
108 Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask); 107 Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
109 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels, 108 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
116 Uint32 Bmask, 115 Uint32 Bmask,
117 Uint32 Amask); 116 Uint32 Amask);
118 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface); 117 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
119 118
120 /** 119 /**
121 * \fn int SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette)
122 *
123 * \brief Set the palette used by a surface. 120 * \brief Set the palette used by a surface.
124 * 121 *
125 * \return 0, or -1 if the surface format doesn't use a palette. 122 * \return 0, or -1 if the surface format doesn't use a palette.
126 * 123 *
127 * \note A single palette can be shared with many surfaces. 124 * \note A single palette can be shared with many surfaces.
128 */ 125 */
129 extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface, 126 extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
130 SDL_Palette * palette); 127 SDL_Palette * palette);
131 128
132 /* 129 /**
133 * SDL_LockSurface() sets up a surface for directly accessing the pixels. 130 * \brief Sets up a surface for directly accessing the pixels.
131 *
134 * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write 132 * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
135 * to and read from 'surface->pixels', using the pixel format stored in 133 * to and read from 'surface->pixels', using the pixel format stored in
136 * 'surface->format'. Once you are done accessing the surface, you should 134 * 'surface->format'. Once you are done accessing the surface, you should
137 * use SDL_UnlockSurface() to release it. 135 * use SDL_UnlockSurface() to release it.
138 * 136 *
142 * 140 *
143 * No operating system or library calls should be made between lock/unlock 141 * No operating system or library calls should be made between lock/unlock
144 * pairs, as critical system locks may be held during this time. 142 * pairs, as critical system locks may be held during this time.
145 * 143 *
146 * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked. 144 * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
145 *
146 * \sa SDL_UnlockSurface()
147 */ 147 */
148 extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface); 148 extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
149 /** \sa SDL_LockSurface() */
149 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface); 150 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
150 151
151 /* 152 /**
152 * Load a surface from a seekable SDL data source (memory or file.) 153 * Load a surface from a seekable SDL data source (memory or file.)
153 * If 'freesrc' is non-zero, the source will be closed after being read. 154 * If 'freesrc' is non-zero, the source will be closed after being read.
154 * Returns the new surface, or NULL if there was an error. 155 * Returns the new surface, or NULL if there was an error.
155 * The new surface should be freed with SDL_FreeSurface(). 156 * The new surface should be freed with SDL_FreeSurface().
156 */ 157 */
157 extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src, 158 extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
158 int freesrc); 159 int freesrc);
159 160
160 /* Convenience macro -- load a surface from a file */ 161 /** Convenience macro -- load a surface from a file */
161 #define SDL_LoadBMP(file) SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1) 162 #define SDL_LoadBMP(file) SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
162 163
163 /* 164 /**
164 * Save a surface to a seekable SDL data source (memory or file.) 165 * Save a surface to a seekable SDL data source (memory or file.)
165 * If 'freedst' is non-zero, the source will be closed after being written. 166 * If 'freedst' is non-zero, the source will be closed after being written.
166 * Returns 0 if successful or -1 if there was an error. 167 * Returns 0 if successful or -1 if there was an error.
167 */ 168 */
168 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW 169 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
169 (SDL_Surface * surface, SDL_RWops * dst, int freedst); 170 (SDL_Surface * surface, SDL_RWops * dst, int freedst);
170 171
171 /* Convenience macro -- save a surface to a file */ 172 /** Convenience macro -- save a surface to a file */
172 #define SDL_SaveBMP(surface, file) \ 173 #define SDL_SaveBMP(surface, file) \
173 SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1) 174 SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
174 175
175 /* 176 /**
176 * \fn int SDL_SetSurfaceRLE(SDL_Surface *surface, int flag)
177 *
178 * \brief Sets the RLE acceleration hint for a surface. 177 * \brief Sets the RLE acceleration hint for a surface.
179 * 178 *
180 * \return 0 on success, or -1 if the surface is not valid 179 * \return 0 on success, or -1 if the surface is not valid
181 * 180 *
182 * \note If RLE is enabled, colorkey and alpha blending blits are much faster, 181 * \note If RLE is enabled, colorkey and alpha blending blits are much faster,
183 * but the surface must be locked before directly accessing the pixels. 182 * but the surface must be locked before directly accessing the pixels.
184 */ 183 */
185 extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface, 184 extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface,
186 int flag); 185 int flag);
187 186
188 /* 187 /**
189 * \fn int SDL_SetColorKey(SDL_Surface *surface, Uint32 flag, Uint32 key)
190 *
191 * \brief Sets the color key (transparent pixel) in a blittable surface. 188 * \brief Sets the color key (transparent pixel) in a blittable surface.
192 * 189 *
193 * \param surface The surface to update 190 * \param surface The surface to update
194 * \param flag Non-zero to enable colorkey and 0 to disable colorkey 191 * \param flag Non-zero to enable colorkey and 0 to disable colorkey
195 * \param key The transparent pixel in the native surface format 192 * \param key The transparent pixel in the native surface format
197 * \return 0 on success, or -1 if the surface is not valid 194 * \return 0 on success, or -1 if the surface is not valid
198 */ 195 */
199 extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface, 196 extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface,
200 Uint32 flag, Uint32 key); 197 Uint32 flag, Uint32 key);
201 198
202 /* 199 /**
203 * \fn int SDL_GetColorKey(SDL_Surface *surface, Uint32 *key)
204 *
205 * \brief Sets the color key (transparent pixel) in a blittable surface. 200 * \brief Sets the color key (transparent pixel) in a blittable surface.
206 * 201 *
207 * \param surface The surface to update 202 * \param surface The surface to update
208 * \param key A pointer filled in with the transparent pixel in the native surface format 203 * \param key A pointer filled in with the transparent pixel in the native surface format
209 * 204 *
211 */ 206 */
212 extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface, 207 extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface,
213 Uint32 * key); 208 Uint32 * key);
214 209
215 /** 210 /**
216 * \fn int SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b)
217 *
218 * \brief Set an additional color value used in blit operations 211 * \brief Set an additional color value used in blit operations
219 * 212 *
220 * \param surface The surface to update 213 * \param surface The surface to update
221 * \param r The red source color value multiplied into blit operations 214 * \param r The red source color value multiplied into blit operations
222 * \param g The green source color value multiplied into blit operations 215 * \param g The green source color value multiplied into blit operations
229 extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface, 222 extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface,
230 Uint8 r, Uint8 g, Uint8 b); 223 Uint8 r, Uint8 g, Uint8 b);
231 224
232 225
233 /** 226 /**
234 * \fn int SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b)
235 *
236 * \brief Get the additional color value used in blit operations 227 * \brief Get the additional color value used in blit operations
237 * 228 *
238 * \param surface The surface to query 229 * \param surface The surface to query
239 * \param r A pointer filled in with the source red color value 230 * \param r A pointer filled in with the source red color value
240 * \param g A pointer filled in with the source green color value 231 * \param g A pointer filled in with the source green color value
247 extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface, 238 extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface,
248 Uint8 * r, Uint8 * g, 239 Uint8 * r, Uint8 * g,
249 Uint8 * b); 240 Uint8 * b);
250 241
251 /** 242 /**
252 * \fn int SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha)
253 *
254 * \brief Set an additional alpha value used in blit operations 243 * \brief Set an additional alpha value used in blit operations
255 * 244 *
256 * \param surface The surface to update 245 * \param surface The surface to update
257 * \param alpha The source alpha value multiplied into blit operations. 246 * \param alpha The source alpha value multiplied into blit operations.
258 * 247 *
262 */ 251 */
263 extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface, 252 extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface,
264 Uint8 alpha); 253 Uint8 alpha);
265 254
266 /** 255 /**
267 * \fn int SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha)
268 *
269 * \brief Get the additional alpha value used in blit operations 256 * \brief Get the additional alpha value used in blit operations
270 * 257 *
271 * \param surface The surface to query 258 * \param surface The surface to query
272 * \param alpha A pointer filled in with the source alpha value 259 * \param alpha A pointer filled in with the source alpha value
273 * 260 *
277 */ 264 */
278 extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface, 265 extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface,
279 Uint8 * alpha); 266 Uint8 * alpha);
280 267
281 /** 268 /**
282 * \fn int SDL_SetSurfaceBlendMode(SDL_Surface *surface, int blendMode)
283 *
284 * \brief Set the blend mode used for blit operations 269 * \brief Set the blend mode used for blit operations
285 * 270 *
286 * \param surface The surface to update 271 * \param surface The surface to update
287 * \param blendMode SDL_TextureBlendMode to use for blit blending 272 * \param blendMode SDL_TextureBlendMode to use for blit blending
288 * 273 *
292 */ 277 */
293 extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface, 278 extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface,
294 int blendMode); 279 int blendMode);
295 280
296 /** 281 /**
297 * \fn int SDL_GetSurfaceBlendMode(SDL_Surface *surface, int *blendMode)
298 *
299 * \brief Get the blend mode used for blit operations 282 * \brief Get the blend mode used for blit operations
300 * 283 *
301 * \param surface The surface to query 284 * \param surface The surface to query
302 * \param blendMode A pointer filled in with the current blend mode 285 * \param blendMode A pointer filled in with the current blend mode
303 * 286 *
307 */ 290 */
308 extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface, 291 extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
309 int *blendMode); 292 int *blendMode);
310 293
311 /** 294 /**
312 * \fn int SDL_SetSurfaceScaleMode(SDL_Surface *surface, int scaleMode)
313 *
314 * \brief Set the scale mode used for blit operations 295 * \brief Set the scale mode used for blit operations
315 * 296 *
316 * \param surface The surface to update 297 * \param surface The surface to update
317 * \param scaleMode SDL_TextureScaleMode to use for blit scaling 298 * \param scaleMode SDL_TextureScaleMode to use for blit scaling
318 * 299 *
324 */ 305 */
325 extern DECLSPEC int SDLCALL SDL_SetSurfaceScaleMode(SDL_Surface * surface, 306 extern DECLSPEC int SDLCALL SDL_SetSurfaceScaleMode(SDL_Surface * surface,
326 int scaleMode); 307 int scaleMode);
327 308
328 /** 309 /**
329 * \fn int SDL_GetSurfaceScaleMode(SDL_Surface *surface, int *scaleMode)
330 *
331 * \brief Get the scale mode used for blit operations 310 * \brief Get the scale mode used for blit operations
332 * 311 *
333 * \param surface The surface to query 312 * \param surface The surface to query
334 * \param scaleMode A pointer filled in with the current scale mode 313 * \param scaleMode A pointer filled in with the current scale mode
335 * 314 *
338 * \sa SDL_SetSurfaceScaleMode() 317 * \sa SDL_SetSurfaceScaleMode()
339 */ 318 */
340 extern DECLSPEC int SDLCALL SDL_GetSurfaceScaleMode(SDL_Surface * surface, 319 extern DECLSPEC int SDLCALL SDL_GetSurfaceScaleMode(SDL_Surface * surface,
341 int *scaleMode); 320 int *scaleMode);
342 321
343 /* 322 /**
344 * Sets the clipping rectangle for the destination surface in a blit. 323 * Sets the clipping rectangle for the destination surface in a blit.
345 * 324 *
346 * If the clip rectangle is NULL, clipping will be disabled. 325 * If the clip rectangle is NULL, clipping will be disabled.
347 * If the clip rectangle doesn't intersect the surface, the function will 326 * If the clip rectangle doesn't intersect the surface, the function will
348 * return SDL_FALSE and blits will be completely clipped. Otherwise the 327 * return SDL_FALSE and blits will be completely clipped. Otherwise the
353 * and destination surfaces. 332 * and destination surfaces.
354 */ 333 */
355 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface, 334 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
356 const SDL_Rect * rect); 335 const SDL_Rect * rect);
357 336
358 /* 337 /**
359 * Gets the clipping rectangle for the destination surface in a blit. 338 * Gets the clipping rectangle for the destination surface in a blit.
360 * 'rect' must be a pointer to a valid rectangle which will be filled 339 * 'rect' must be a pointer to a valid rectangle which will be filled
361 * with the correct values. 340 * with the correct values.
362 */ 341 */
363 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface, 342 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
364 SDL_Rect * rect); 343 SDL_Rect * rect);
365 344
366 /* 345 /**
367 * Creates a new surface of the specified format, and then copies and maps 346 * Creates a new surface of the specified format, and then copies and maps
368 * the given surface to it so the blit of the converted surface will be as 347 * the given surface to it so the blit of the converted surface will be as
369 * fast as possible. If this function fails, it returns NULL. 348 * fast as possible. If this function fails, it returns NULL.
370 * 349 *
371 * The 'flags' parameter is passed to SDL_CreateRGBSurface() and has those 350 * The 'flags' parameter is passed to SDL_CreateRGBSurface() and has those
376 * This function is used internally by SDL_DisplayFormat(). 355 * This function is used internally by SDL_DisplayFormat().
377 */ 356 */
378 extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface 357 extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
379 (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags); 358 (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags);
380 359
381 /* 360 /**
382 * This function draws a point with 'color' 361 * This function draws a point with 'color'
383 * The color should be a pixel of the format used by the surface, and 362 * The color should be a pixel of the format used by the surface, and
384 * can be generated by the SDL_MapRGB() function. 363 * can be generated by the SDL_MapRGB() function.
385 * This function returns 0 on success, or -1 on error. 364 * \return This function returns 0 on success, or -1 on error.
386 */ 365 */
387 extern DECLSPEC int SDLCALL SDL_DrawPoint 366 extern DECLSPEC int SDLCALL SDL_DrawPoint
388 (SDL_Surface * dst, int x, int y, Uint32 color); 367 (SDL_Surface * dst, int x, int y, Uint32 color);
389 368
390 /* 369 /**
391 * This function blends a point with an RGBA value 370 * This function blends a point with an RGBA value
392 * The color should be a pixel of the format used by the surface, and 371 * The color should be a pixel of the format used by the surface, and
393 * can be generated by the SDL_MapRGB() function. 372 * can be generated by the SDL_MapRGB() function.
394 * This function returns 0 on success, or -1 on error. 373 * \return This function returns 0 on success, or -1 on error.
395 */ 374 */
396 extern DECLSPEC int SDLCALL SDL_BlendPoint 375 extern DECLSPEC int SDLCALL SDL_BlendPoint
397 (SDL_Surface * dst, int x, int y, int blendMode, 376 (SDL_Surface * dst, int x, int y, int blendMode,
398 Uint8 r, Uint8 g, Uint8 b, Uint8 a); 377 Uint8 r, Uint8 g, Uint8 b, Uint8 a);
399 378
400 /* 379 /**
401 * This function draws a line with 'color' 380 * This function draws a line with 'color'
402 * The color should be a pixel of the format used by the surface, and 381 * The color should be a pixel of the format used by the surface, and
403 * can be generated by the SDL_MapRGB() function. 382 * can be generated by the SDL_MapRGB() function.
404 * This function returns 0 on success, or -1 on error. 383 * \return This function returns 0 on success, or -1 on error.
405 */ 384 */
406 extern DECLSPEC int SDLCALL SDL_DrawLine 385 extern DECLSPEC int SDLCALL SDL_DrawLine
407 (SDL_Surface * dst, int x1, int y1, int x2, int y2, Uint32 color); 386 (SDL_Surface * dst, int x1, int y1, int x2, int y2, Uint32 color);
408 387
409 /* 388 /**
410 * This function blends an RGBA value along a line 389 * This function blends an RGBA value along a line
411 * This function returns 0 on success, or -1 on error. 390 * \return This function returns 0 on success, or -1 on error.
412 */ 391 */
413 extern DECLSPEC int SDLCALL SDL_BlendLine 392 extern DECLSPEC int SDLCALL SDL_BlendLine
414 (SDL_Surface * dst, int x1, int y1, int x2, int y2, int blendMode, 393 (SDL_Surface * dst, int x1, int y1, int x2, int y2, int blendMode,
415 Uint8 r, Uint8 g, Uint8 b, Uint8 a); 394 Uint8 r, Uint8 g, Uint8 b, Uint8 a);
416 395
417 /* 396 /**
418 * This function performs a fast fill of the given rectangle with 'color' 397 * This function performs a fast fill of the given rectangle with 'color'
419 * The given rectangle is clipped to the destination surface clip area 398 * The given rectangle is clipped to the destination surface clip area
420 * and the final fill rectangle is saved in the passed in pointer. 399 * and the final fill rectangle is saved in the passed in pointer.
421 * If 'dstrect' is NULL, the whole surface will be filled with 'color' 400 * If 'dstrect' is NULL, the whole surface will be filled with 'color'
422 * The color should be a pixel of the format used by the surface, and 401 * The color should be a pixel of the format used by the surface, and
423 * can be generated by the SDL_MapRGB() function. 402 * can be generated by the SDL_MapRGB() function.
424 * This function returns 0 on success, or -1 on error. 403 * \return This function returns 0 on success, or -1 on error.
425 */ 404 */
426 extern DECLSPEC int SDLCALL SDL_FillRect 405 extern DECLSPEC int SDLCALL SDL_FillRect
427 (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color); 406 (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color);
428 407
429 /* 408 /**
430 * This function blends an RGBA value into the given rectangle. 409 * This function blends an RGBA value into the given rectangle.
431 * The given rectangle is clipped to the destination surface clip area 410 * The given rectangle is clipped to the destination surface clip area
432 * and the final fill rectangle is saved in the passed in pointer. 411 * and the final fill rectangle is saved in the passed in pointer.
433 * If 'dstrect' is NULL, the whole surface will be filled with 'color' 412 * If 'dstrect' is NULL, the whole surface will be filled with 'color'
434 * This function returns 0 on success, or -1 on error. 413 * \return This function returns 0 on success, or -1 on error.
435 */ 414 */
436 extern DECLSPEC int SDLCALL SDL_BlendRect 415 extern DECLSPEC int SDLCALL SDL_BlendRect
437 (SDL_Surface * dst, SDL_Rect * dstrect, int blendMode, Uint8 r, Uint8 g, 416 (SDL_Surface * dst, SDL_Rect * dstrect, int blendMode, Uint8 r, Uint8 g,
438 Uint8 b, Uint8 a); 417 Uint8 b, Uint8 a);
439 418
440 /* 419 /**
441 * This performs a fast blit from the source surface to the destination 420 * This performs a fast blit from the source surface to the destination
442 * surface. It assumes that the source and destination rectangles are 421 * surface. It assumes that the source and destination rectangles are
443 * the same size. If either 'srcrect' or 'dstrect' are NULL, the entire 422 * the same size. If either 'srcrect' or 'dstrect' are NULL, the entire
444 * surface (src or dst) is copied. The final blit rectangles are saved 423 * surface (src or dst) is copied. The final blit rectangles are saved
445 * in 'srcrect' and 'dstrect' after all clipping is performed. 424 * in 'srcrect' and 'dstrect' after all clipping is performed.
491 * source colour key. 470 * source colour key.
492 * 471 *
493 * If either of the surfaces were in video memory, and the blit returns -2, 472 * If either of the surfaces were in video memory, and the blit returns -2,
494 * the video memory was lost, so it should be reloaded with artwork and 473 * the video memory was lost, so it should be reloaded with artwork and
495 * re-blitted: 474 * re-blitted:
496 while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) { 475 * @code
497 while ( SDL_LockSurface(image) < 0 ) 476 * while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
498 Sleep(10); 477 * while ( SDL_LockSurface(image) < 0 )
499 -- Write image pixels to image->pixels -- 478 * Sleep(10);
500 SDL_UnlockSurface(image); 479 * -- Write image pixels to image->pixels --
501 } 480 * SDL_UnlockSurface(image);
481 * }
482 * @endcode
483 *
502 * This happens under DirectX 5.0 when the system switches away from your 484 * This happens under DirectX 5.0 when the system switches away from your
503 * fullscreen application. The lock will also fail until you have access 485 * fullscreen application. The lock will also fail until you have access
504 * to the video memory again. 486 * to the video memory again.
505 */ 487 *
506 /* You should call SDL_BlitSurface() unless you know exactly how SDL 488 * You should call SDL_BlitSurface() unless you know exactly how SDL
507 blitting works internally and how to use the other blit functions. 489 * blitting works internally and how to use the other blit functions.
508 */ 490 */
509 #define SDL_BlitSurface SDL_UpperBlit 491 #define SDL_BlitSurface SDL_UpperBlit
510 492
511 /* This is the public blit function, SDL_BlitSurface(), and it performs 493 /** This is the public blit function, SDL_BlitSurface(), and it performs
512 rectangle validation and clipping before passing it to SDL_LowerBlit() 494 * rectangle validation and clipping before passing it to SDL_LowerBlit()
513 */ 495 */
514 extern DECLSPEC int SDLCALL SDL_UpperBlit 496 extern DECLSPEC int SDLCALL SDL_UpperBlit
515 (SDL_Surface * src, SDL_Rect * srcrect, 497 (SDL_Surface * src, SDL_Rect * srcrect,
516 SDL_Surface * dst, SDL_Rect * dstrect); 498 SDL_Surface * dst, SDL_Rect * dstrect);
517 /* This is a semi-private blit function and it performs low-level surface 499
518 blitting only. 500 /** This is a semi-private blit function and it performs low-level surface
519 */ 501 * blitting only.
502 */
520 extern DECLSPEC int SDLCALL SDL_LowerBlit 503 extern DECLSPEC int SDLCALL SDL_LowerBlit
521 (SDL_Surface * src, SDL_Rect * srcrect, 504 (SDL_Surface * src, SDL_Rect * srcrect,
522 SDL_Surface * dst, SDL_Rect * dstrect); 505 SDL_Surface * dst, SDL_Rect * dstrect);
523 506
524 /** 507 /**
525 * \fn int SDL_SoftStretch(SDL_Surface * src, const SDL_Rect * srcrect, SDL_Surface * dst, const SDL_Rect * dstrect)
526 *
527 * \brief Perform a fast, low quality, stretch blit between two surfaces of the same pixel format. 508 * \brief Perform a fast, low quality, stretch blit between two surfaces of the same pixel format.
528 * 509 *
529 * \note This function uses a static buffer, and is not thread-safe. 510 * \note This function uses a static buffer, and is not thread-safe.
530 */ 511 */
531 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src, 512 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,