include/SDL_surface.h
changeset 3407 d3baf5ac4e37
parent 3341 710139a1692d
child 3434 147d6ef5be03
     1.1 --- a/include/SDL_surface.h	Sun Oct 18 23:21:15 2009 +0000
     1.2 +++ b/include/SDL_surface.h	Mon Oct 19 13:31:58 2009 +0000
     1.3 @@ -21,9 +21,9 @@
     1.4  */
     1.5  
     1.6  /**
     1.7 - * \file SDL_surface.h
     1.8 - *
     1.9 - * Header file for SDL_surface definition and management functions
    1.10 + *  \file SDL_surface.h
    1.11 + *  
    1.12 + *  Header file for ::SDL_surface definition and management functions.
    1.13   */
    1.14  
    1.15  #ifndef _SDL_surface_h
    1.16 @@ -42,21 +42,28 @@
    1.17  /* *INDENT-ON* */
    1.18  #endif
    1.19  
    1.20 -/** These are the currently supported flags for the SDL_surface
    1.21 - *  \internal Used internally (read-only) 
    1.22 +/**
    1.23 + *  \name Surface flags
    1.24 + *  
    1.25 + *  These are the currently supported flags for the ::SDL_surface.
    1.26 + *  
    1.27 + *  \internal
    1.28 + *  Used internally (read-only).
    1.29   */
    1.30  /*@{*/
    1.31  #define SDL_PREALLOC        0x00000001  /**< Surface uses preallocated memory */
    1.32  #define SDL_RLEACCEL        0x00000002  /**< Surface is RLE encoded */
    1.33 -/*@}*/
    1.34 +/*@}*//*Surface flags*/
    1.35  
    1.36 -/** Evaluates to true if the surface needs to be locked before access */
    1.37 +/**
    1.38 + *  Evaluates to true if the surface needs to be locked before access.
    1.39 + */
    1.40  #define SDL_MUSTLOCK(S)	(((S)->flags & SDL_RLEACCEL) != 0)
    1.41  
    1.42  /**
    1.43 - * \brief A collection of pixels used in software blitting
    1.44 + * \brief A collection of pixels used in software blitting.
    1.45   *
    1.46 - * \note  This structure should be treated as read-only, except for 'pixels',
    1.47 + * \note  This structure should be treated as read-only, except for \c pixels,
    1.48   *        which, if not NULL, contains the raw pixel data for the surface.
    1.49   */
    1.50  typedef struct SDL_Surface
    1.51 @@ -67,40 +74,42 @@
    1.52      int pitch;                  /**< Read-only */
    1.53      void *pixels;               /**< Read-write */
    1.54  
    1.55 -    /* Application data associated with the surfade */
    1.56 +    /** Application data associated with the surfade */
    1.57      void *userdata;             /**< Read-write */
    1.58  
    1.59 -    /* information needed for surfaces requiring locks */
    1.60 +    /** information needed for surfaces requiring locks */
    1.61      int locked;                 /**< Read-only */
    1.62      void *lock_data;            /**< Read-only */
    1.63  
    1.64 -    /* clipping information */
    1.65 +    /** clipping information */
    1.66      SDL_Rect clip_rect;         /**< Read-only */
    1.67  
    1.68 -    /* info for fast blit mapping to other surfaces */
    1.69 +    /** info for fast blit mapping to other surfaces */
    1.70      struct SDL_BlitMap *map;    /**< Private */
    1.71  
    1.72 -    /* format version, bumped at every change to invalidate blit maps */
    1.73 +    /** format version, bumped at every change to invalidate blit maps */
    1.74      unsigned int format_version;        /**< Private */
    1.75  
    1.76 -    /* Reference count -- used when freeing surface */
    1.77 +    /** Reference count -- used when freeing surface */
    1.78      int refcount;               /**< Read-mostly */
    1.79  } SDL_Surface;
    1.80  
    1.81  /**
    1.82 - * \brief The type of function used for surface blitting functions
    1.83 + * \brief The type of function used for surface blitting functions.
    1.84   */
    1.85  typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
    1.86                           struct SDL_Surface * dst, SDL_Rect * dstrect);
    1.87  
    1.88  /**
    1.89 - * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
    1.90 - * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
    1.91 - * If the depth is greater than 8 bits, the pixel format is set using the
    1.92 - * flags '[RGB]mask'.
    1.93 - * If the function runs out of memory, it will return NULL.
    1.94 - *
    1.95 - * \param flags The 'flags' are obsolete and should be set to 0.
    1.96 + *  Allocate and free an RGB surface (must be called after SDL_SetVideoMode).
    1.97 + *  
    1.98 + *  If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
    1.99 + *  If the depth is greater than 8 bits, the pixel format is set using the
   1.100 + *  flags '[RGB]mask'.
   1.101 + *  
   1.102 + *  If the function runs out of memory, it will return NULL.
   1.103 + *  
   1.104 + *  \param flags The \c flags are obsolete and should be set to 0.
   1.105   */
   1.106  extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
   1.107      (Uint32 flags, int width, int height, int depth,
   1.108 @@ -117,387 +126,426 @@
   1.109  extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
   1.110  
   1.111  /**
   1.112 - * \brief Set the palette used by a surface.
   1.113 - *
   1.114 - * \return 0, or -1 if the surface format doesn't use a palette.
   1.115 - *
   1.116 - * \note A single palette can be shared with many surfaces.
   1.117 + *  \brief Set the palette used by a surface.
   1.118 + *  
   1.119 + *  \return 0, or -1 if the surface format doesn't use a palette.
   1.120 + *  
   1.121 + *  \note A single palette can be shared with many surfaces.
   1.122   */
   1.123  extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
   1.124                                                    SDL_Palette * palette);
   1.125  
   1.126  /**
   1.127 - * \brief Sets up a surface for directly accessing the pixels.
   1.128 - *
   1.129 - * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
   1.130 - * to and read from 'surface->pixels', using the pixel format stored in 
   1.131 - * 'surface->format'.  Once you are done accessing the surface, you should 
   1.132 - * use SDL_UnlockSurface() to release it.
   1.133 - *
   1.134 - * Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
   1.135 - * to 0, then you can read and write to the surface at any time, and the
   1.136 - * pixel format of the surface will not change.
   1.137 - * 
   1.138 - * No operating system or library calls should be made between lock/unlock
   1.139 - * pairs, as critical system locks may be held during this time.
   1.140 - *
   1.141 - * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
   1.142 - * 
   1.143 - * \sa SDL_UnlockSurface()
   1.144 + *  \brief Sets up a surface for directly accessing the pixels.
   1.145 + *  
   1.146 + *  Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write
   1.147 + *  to and read from \c surface->pixels, using the pixel format stored in 
   1.148 + *  \c surface->format.  Once you are done accessing the surface, you should 
   1.149 + *  use SDL_UnlockSurface() to release it.
   1.150 + *  
   1.151 + *  Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
   1.152 + *  to 0, then you can read and write to the surface at any time, and the
   1.153 + *  pixel format of the surface will not change.
   1.154 + *  
   1.155 + *  No operating system or library calls should be made between lock/unlock
   1.156 + *  pairs, as critical system locks may be held during this time.
   1.157 + *  
   1.158 + *  SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
   1.159 + *  
   1.160 + *  \sa SDL_UnlockSurface()
   1.161   */
   1.162  extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
   1.163  /** \sa SDL_LockSurface() */
   1.164  extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
   1.165  
   1.166  /**
   1.167 - * Load a surface from a seekable SDL data source (memory or file.)
   1.168 - * If 'freesrc' is non-zero, the source will be closed after being read.
   1.169 - * Returns the new surface, or NULL if there was an error.
   1.170 - * The new surface should be freed with SDL_FreeSurface().
   1.171 + *  Load a surface from a seekable SDL data source (memory or file).
   1.172 + *  
   1.173 + *  If \c freesrc is non-zero, the source will be closed after being read.
   1.174 + *  
   1.175 + *  The new surface should be freed with SDL_FreeSurface().
   1.176 + *  
   1.177 + *  \return the new surface, or NULL if there was an error.
   1.178   */
   1.179  extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
   1.180                                                      int freesrc);
   1.181  
   1.182 -/** Convenience macro -- load a surface from a file */
   1.183 +/**
   1.184 + *  Load a surface from a file.
   1.185 + *  
   1.186 + *  Convenience macro.
   1.187 + */
   1.188  #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
   1.189  
   1.190  /**
   1.191 - * Save a surface to a seekable SDL data source (memory or file.)
   1.192 - * If 'freedst' is non-zero, the source will be closed after being written.
   1.193 - * Returns 0 if successful or -1 if there was an error.
   1.194 + *  Save a surface to a seekable SDL data source (memory or file).
   1.195 + *  
   1.196 + *  If \c freedst is non-zero, the source will be closed after being written.
   1.197 + *  
   1.198 + *  \return 0 if successful or -1 if there was an error.
   1.199   */
   1.200  extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
   1.201      (SDL_Surface * surface, SDL_RWops * dst, int freedst);
   1.202  
   1.203 -/** Convenience macro -- save a surface to a file */
   1.204 +/** 
   1.205 + *  Save a surface to a file.
   1.206 + *  
   1.207 + *  Convenience macro.
   1.208 + */
   1.209  #define SDL_SaveBMP(surface, file) \
   1.210  		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
   1.211  
   1.212  /**
   1.213 - * \brief Sets the RLE acceleration hint for a surface.
   1.214 - *
   1.215 - * \return 0 on success, or -1 if the surface is not valid
   1.216 - *
   1.217 - * \note If RLE is enabled, colorkey and alpha blending blits are much faster,
   1.218 - *       but the surface must be locked before directly accessing the pixels.
   1.219 + *  \brief Sets the RLE acceleration hint for a surface.
   1.220 + *  
   1.221 + *  \return 0 on success, or -1 if the surface is not valid
   1.222 + *  
   1.223 + *  \note If RLE is enabled, colorkey and alpha blending blits are much faster,
   1.224 + *        but the surface must be locked before directly accessing the pixels.
   1.225   */
   1.226  extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface,
   1.227                                                int flag);
   1.228  
   1.229  /**
   1.230 - * \brief Sets the color key (transparent pixel) in a blittable surface.
   1.231 - *
   1.232 - * \param surface The surface to update
   1.233 - * \param flag Non-zero to enable colorkey and 0 to disable colorkey 
   1.234 - * \param key The transparent pixel in the native surface format
   1.235 - *
   1.236 - * \return 0 on success, or -1 if the surface is not valid
   1.237 + *  \brief Sets the color key (transparent pixel) in a blittable surface.
   1.238 + *  
   1.239 + *  \param surface The surface to update
   1.240 + *  \param flag Non-zero to enable colorkey and 0 to disable colorkey 
   1.241 + *  \param key The transparent pixel in the native surface format
   1.242 + *  
   1.243 + *  \return 0 on success, or -1 if the surface is not valid
   1.244   */
   1.245  extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface,
   1.246                                              Uint32 flag, Uint32 key);
   1.247  
   1.248  /**
   1.249 - * \brief Sets the color key (transparent pixel) in a blittable surface.
   1.250 - *
   1.251 - * \param surface The surface to update
   1.252 - * \param key A pointer filled in with the transparent pixel in the native surface format
   1.253 - *
   1.254 - * \return 0 on success, or -1 if the surface is not valid or colorkey is not enabled.
   1.255 + *  \brief Sets the color key (transparent pixel) in a blittable surface.
   1.256 + *  
   1.257 + *  \param surface The surface to update
   1.258 + *  \param key A pointer filled in with the transparent pixel in the native 
   1.259 + *             surface format
   1.260 + *  
   1.261 + *  \return 0 on success, or -1 if the surface is not valid or colorkey is not 
   1.262 + *          enabled.
   1.263   */
   1.264  extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface,
   1.265                                              Uint32 * key);
   1.266  
   1.267  /**
   1.268 - * \brief Set an additional color value used in blit operations
   1.269 - *
   1.270 - * \param surface The surface to update
   1.271 - * \param r The red source color value multiplied into blit operations
   1.272 - * \param g The green source color value multiplied into blit operations
   1.273 - * \param b The blue source color value multiplied into blit operations
   1.274 - *
   1.275 - * \return 0 on success, or -1 if the surface is not valid
   1.276 - *
   1.277 - * \sa SDL_GetSurfaceColorMod()
   1.278 + *  \brief Set an additional color value used in blit operations.
   1.279 + *  
   1.280 + *  \param surface The surface to update.
   1.281 + *  \param r The red source color value multiplied into blit operations.
   1.282 + *  \param g The green source color value multiplied into blit operations.
   1.283 + *  \param b The blue source color value multiplied into blit operations.
   1.284 + *  
   1.285 + *  \return 0 on success, or -1 if the surface is not valid.
   1.286 + *  
   1.287 + *  \sa SDL_GetSurfaceColorMod()
   1.288   */
   1.289  extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface,
   1.290                                                     Uint8 r, Uint8 g, Uint8 b);
   1.291  
   1.292  
   1.293  /**
   1.294 - * \brief Get the additional color value used in blit operations
   1.295 - *
   1.296 - * \param surface The surface to query
   1.297 - * \param r A pointer filled in with the source red color value
   1.298 - * \param g A pointer filled in with the source green color value
   1.299 - * \param b A pointer filled in with the source blue color value
   1.300 - *
   1.301 - * \return 0 on success, or -1 if the surface is not valid
   1.302 - *
   1.303 - * \sa SDL_SetSurfaceColorMod()
   1.304 + *  \brief Get the additional color value used in blit operations.
   1.305 + *  
   1.306 + *  \param surface The surface to query.
   1.307 + *  \param r A pointer filled in with the source red color value.
   1.308 + *  \param g A pointer filled in with the source green color value.
   1.309 + *  \param b A pointer filled in with the source blue color value.
   1.310 + *  
   1.311 + *  \return 0 on success, or -1 if the surface is not valid.
   1.312 + *  
   1.313 + *  \sa SDL_SetSurfaceColorMod()
   1.314   */
   1.315  extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface,
   1.316                                                     Uint8 * r, Uint8 * g,
   1.317                                                     Uint8 * b);
   1.318  
   1.319  /**
   1.320 - * \brief Set an additional alpha value used in blit operations
   1.321 - *
   1.322 - * \param surface The surface to update
   1.323 - * \param alpha The source alpha value multiplied into blit operations.
   1.324 - *
   1.325 - * \return 0 on success, or -1 if the surface is not valid
   1.326 - *
   1.327 - * \sa SDL_GetSurfaceAlphaMod()
   1.328 + *  \brief Set an additional alpha value used in blit operations.
   1.329 + *  
   1.330 + *  \param surface The surface to update.
   1.331 + *  \param alpha The source alpha value multiplied into blit operations.
   1.332 + *  
   1.333 + *  \return 0 on success, or -1 if the surface is not valid.
   1.334 + *  
   1.335 + *  \sa SDL_GetSurfaceAlphaMod()
   1.336   */
   1.337  extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface,
   1.338                                                     Uint8 alpha);
   1.339  
   1.340  /**
   1.341 - * \brief Get the additional alpha value used in blit operations
   1.342 - *
   1.343 - * \param surface The surface to query
   1.344 - * \param alpha A pointer filled in with the source alpha value
   1.345 - *
   1.346 - * \return 0 on success, or -1 if the surface is not valid
   1.347 - *
   1.348 - * \sa SDL_SetSurfaceAlphaMod()
   1.349 + *  \brief Get the additional alpha value used in blit operations.
   1.350 + *  
   1.351 + *  \param surface The surface to query.
   1.352 + *  \param alpha A pointer filled in with the source alpha value.
   1.353 + *  
   1.354 + *  \return 0 on success, or -1 if the surface is not valid.
   1.355 + *  
   1.356 + *  \sa SDL_SetSurfaceAlphaMod()
   1.357   */
   1.358  extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface,
   1.359                                                     Uint8 * alpha);
   1.360  
   1.361  /**
   1.362 - * \brief Set the blend mode used for blit operations
   1.363 - *
   1.364 - * \param surface The surface to update
   1.365 - * \param blendMode SDL_TextureBlendMode to use for blit blending
   1.366 - *
   1.367 - * \return 0 on success, or -1 if the parameters are not valid
   1.368 - *
   1.369 - * \sa SDL_GetSurfaceBlendMode()
   1.370 + *  \brief Set the blend mode used for blit operations.
   1.371 + *  
   1.372 + *  \param surface The surface to update.
   1.373 + *  \param blendMode ::SDL_BlendMode to use for blit blending.
   1.374 + *  
   1.375 + *  \return 0 on success, or -1 if the parameters are not valid.
   1.376 + *  
   1.377 + *  \sa SDL_GetSurfaceBlendMode()
   1.378   */
   1.379  extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface,
   1.380                                                      int blendMode);
   1.381  
   1.382  /**
   1.383 - * \brief Get the blend mode used for blit operations
   1.384 - *
   1.385 - * \param surface The surface to query
   1.386 - * \param blendMode A pointer filled in with the current blend mode
   1.387 - *
   1.388 - * \return 0 on success, or -1 if the surface is not valid
   1.389 - *
   1.390 - * \sa SDL_SetSurfaceBlendMode()
   1.391 + *  \brief Get the blend mode used for blit operations.
   1.392 + *  
   1.393 + *  \param surface   The surface to query.
   1.394 + *  \param blendMode A pointer filled in with the current blend mode.
   1.395 + *  
   1.396 + *  \return 0 on success, or -1 if the surface is not valid.
   1.397 + *  
   1.398 + *  \sa SDL_SetSurfaceBlendMode()
   1.399   */
   1.400  extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
   1.401                                                      int *blendMode);
   1.402  
   1.403  /**
   1.404 - * \brief Set the scale mode used for blit operations
   1.405 - *
   1.406 - * \param surface The surface to update
   1.407 - * \param scaleMode SDL_TextureScaleMode to use for blit scaling
   1.408 - *
   1.409 - * \return 0 on success, or -1 if the surface is not valid or the scale mode is not supported
   1.410 - *
   1.411 - * \note If the scale mode is not supported, the closest supported mode is chosen.  Currently only SDL_TEXTURESCALEMODE_FAST is supported on surfaces.
   1.412 - *
   1.413 - * \sa SDL_GetSurfaceScaleMode()
   1.414 + *  \brief Set the scale mode used for blit operations.
   1.415 + *  
   1.416 + *  \param surface   The surface to update.
   1.417 + *  \param scaleMode ::SDL_TextureScaleMode to use for blit scaling.
   1.418 + *  
   1.419 + *  \return 0 on success, or -1 if the surface is not valid or the scale mode is
   1.420 + *          not supported.
   1.421 + *  
   1.422 + *  \note If the scale mode is not supported, the closest supported mode is 
   1.423 + *        chosen.  Currently only ::SDL_TEXTURESCALEMODE_FAST is supported on 
   1.424 + *        surfaces.
   1.425 + *  
   1.426 + *  \sa SDL_GetSurfaceScaleMode()
   1.427   */
   1.428  extern DECLSPEC int SDLCALL SDL_SetSurfaceScaleMode(SDL_Surface * surface,
   1.429                                                      int scaleMode);
   1.430  
   1.431  /**
   1.432 - * \brief Get the scale mode used for blit operations
   1.433 - *
   1.434 - * \param surface The surface to query
   1.435 - * \param scaleMode A pointer filled in with the current scale mode
   1.436 - *
   1.437 - * \return 0 on success, or -1 if the surface is not valid
   1.438 - *
   1.439 - * \sa SDL_SetSurfaceScaleMode()
   1.440 + *  \brief Get the scale mode used for blit operations.
   1.441 + *  
   1.442 + *  \param surface   The surface to query.
   1.443 + *  \param scaleMode A pointer filled in with the current scale mode.
   1.444 + *  
   1.445 + *  \return 0 on success, or -1 if the surface is not valid.
   1.446 + *  
   1.447 + *  \sa SDL_SetSurfaceScaleMode()
   1.448   */
   1.449  extern DECLSPEC int SDLCALL SDL_GetSurfaceScaleMode(SDL_Surface * surface,
   1.450                                                      int *scaleMode);
   1.451  
   1.452  /**
   1.453 - * Sets the clipping rectangle for the destination surface in a blit.
   1.454 - *
   1.455 - * If the clip rectangle is NULL, clipping will be disabled.
   1.456 - * If the clip rectangle doesn't intersect the surface, the function will
   1.457 - * return SDL_FALSE and blits will be completely clipped.  Otherwise the
   1.458 - * function returns SDL_TRUE and blits to the surface will be clipped to
   1.459 - * the intersection of the surface area and the clipping rectangle.
   1.460 - *
   1.461 - * Note that blits are automatically clipped to the edges of the source
   1.462 - * and destination surfaces.
   1.463 + *  Sets the clipping rectangle for the destination surface in a blit.
   1.464 + *  
   1.465 + *  If the clip rectangle is NULL, clipping will be disabled.
   1.466 + *  
   1.467 + *  If the clip rectangle doesn't intersect the surface, the function will
   1.468 + *  return SDL_FALSE and blits will be completely clipped.  Otherwise the
   1.469 + *  function returns SDL_TRUE and blits to the surface will be clipped to
   1.470 + *  the intersection of the surface area and the clipping rectangle.
   1.471 + *  
   1.472 + *  Note that blits are automatically clipped to the edges of the source
   1.473 + *  and destination surfaces.
   1.474   */
   1.475  extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
   1.476                                                   const SDL_Rect * rect);
   1.477  
   1.478  /**
   1.479 - * Gets the clipping rectangle for the destination surface in a blit.
   1.480 - * 'rect' must be a pointer to a valid rectangle which will be filled
   1.481 - * with the correct values.
   1.482 + *  Gets the clipping rectangle for the destination surface in a blit.
   1.483 + *  
   1.484 + *  \c rect must be a pointer to a valid rectangle which will be filled
   1.485 + *  with the correct values.
   1.486   */
   1.487  extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
   1.488                                               SDL_Rect * rect);
   1.489  
   1.490  /**
   1.491 - * Creates a new surface of the specified format, and then copies and maps 
   1.492 - * the given surface to it so the blit of the converted surface will be as 
   1.493 - * fast as possible.  If this function fails, it returns NULL.
   1.494 - *
   1.495 - * The 'flags' parameter is passed to SDL_CreateRGBSurface() and has those 
   1.496 - * semantics.  You can also pass SDL_RLEACCEL in the flags parameter and
   1.497 - * SDL will try to RLE accelerate colorkey and alpha blits in the resulting
   1.498 - * surface.
   1.499 - *
   1.500 - * This function is used internally by SDL_DisplayFormat().
   1.501 + *  Creates a new surface of the specified format, and then copies and maps 
   1.502 + *  the given surface to it so the blit of the converted surface will be as 
   1.503 + *  fast as possible.  If this function fails, it returns NULL.
   1.504 + *  
   1.505 + *  The \c flags parameter is passed to SDL_CreateRGBSurface() and has those 
   1.506 + *  semantics.  You can also pass ::SDL_RLEACCEL in the flags parameter and
   1.507 + *  SDL will try to RLE accelerate colorkey and alpha blits in the resulting
   1.508 + *  surface.
   1.509 + *  
   1.510 + *  This function is used internally by SDL_DisplayFormat().
   1.511   */
   1.512  extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
   1.513      (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags);
   1.514  
   1.515  /**
   1.516 - * This function draws a point with 'color'
   1.517 - * The color should be a pixel of the format used by the surface, and 
   1.518 - * can be generated by the SDL_MapRGB() function.
   1.519 - * \return This function returns 0 on success, or -1 on error.
   1.520 + *  Draws a point with \c color.
   1.521 + *
   1.522 + *  The color should be a pixel of the format used by the surface, and 
   1.523 + *  can be generated by the SDL_MapRGB() function.
   1.524 + *  
   1.525 + *  \return 0 on success, or -1 on error.
   1.526   */
   1.527  extern DECLSPEC int SDLCALL SDL_DrawPoint
   1.528      (SDL_Surface * dst, int x, int y, Uint32 color);
   1.529  
   1.530  /**
   1.531 - * This function blends a point with an RGBA value
   1.532 - * The color should be a pixel of the format used by the surface, and 
   1.533 - * can be generated by the SDL_MapRGB() function.
   1.534 - * \return This function returns 0 on success, or -1 on error.
   1.535 + *  Blends a point with an RGBA value.
   1.536 + *  
   1.537 + *  The color should be a pixel of the format used by the surface, and 
   1.538 + *  can be generated by the SDL_MapRGB() function.
   1.539 + *  
   1.540 + *  \return 0 on success, or -1 on error.
   1.541   */
   1.542  extern DECLSPEC int SDLCALL SDL_BlendPoint
   1.543      (SDL_Surface * dst, int x, int y, int blendMode,
   1.544       Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   1.545  
   1.546  /**
   1.547 - * This function draws a line with 'color'
   1.548 - * The color should be a pixel of the format used by the surface, and 
   1.549 - * can be generated by the SDL_MapRGB() function.
   1.550 - * \return This function returns 0 on success, or -1 on error.
   1.551 + *  Draws a line with \c color.
   1.552 + *  
   1.553 + *  The color should be a pixel of the format used by the surface, and 
   1.554 + *  can be generated by the SDL_MapRGB() function.
   1.555 + *  
   1.556 + *  \return 0 on success, or -1 on error.
   1.557   */
   1.558  extern DECLSPEC int SDLCALL SDL_DrawLine
   1.559      (SDL_Surface * dst, int x1, int y1, int x2, int y2, Uint32 color);
   1.560  
   1.561  /**
   1.562 - * This function blends an RGBA value along a line
   1.563 - * \return This function returns 0 on success, or -1 on error.
   1.564 + *  Blends an RGBA value along a line.
   1.565 + *  
   1.566 + *  \return 0 on success, or -1 on error.
   1.567   */
   1.568  extern DECLSPEC int SDLCALL SDL_BlendLine
   1.569      (SDL_Surface * dst, int x1, int y1, int x2, int y2, int blendMode,
   1.570       Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   1.571  
   1.572  /**
   1.573 - * This function performs a fast fill of the given rectangle with 'color'
   1.574 - * The given rectangle is clipped to the destination surface clip area
   1.575 - * and the final fill rectangle is saved in the passed in pointer.
   1.576 - * If 'dstrect' is NULL, the whole surface will be filled with 'color'
   1.577 - * The color should be a pixel of the format used by the surface, and 
   1.578 - * can be generated by the SDL_MapRGB() function.
   1.579 - * \return This function returns 0 on success, or -1 on error.
   1.580 + *  Performs a fast fill of the given rectangle with \c color.
   1.581 + *  
   1.582 + *  The given rectangle is clipped to the destination surface clip area
   1.583 + *  and the final fill rectangle is saved in the passed in pointer.
   1.584 + *  
   1.585 + *  If \c dstrect is NULL, the whole surface will be filled with \c color.
   1.586 + *  
   1.587 + *  The color should be a pixel of the format used by the surface, and 
   1.588 + *  can be generated by the SDL_MapRGB() function.
   1.589 + *  
   1.590 + *  \return 0 on success, or -1 on error.
   1.591   */
   1.592  extern DECLSPEC int SDLCALL SDL_FillRect
   1.593      (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color);
   1.594  
   1.595  /**
   1.596 - * This function blends an RGBA value into the given rectangle.
   1.597 - * The given rectangle is clipped to the destination surface clip area
   1.598 - * and the final fill rectangle is saved in the passed in pointer.
   1.599 - * If 'dstrect' is NULL, the whole surface will be filled with 'color'
   1.600 - * \return This function returns 0 on success, or -1 on error.
   1.601 + *  Blends an RGBA value into the given rectangle.
   1.602 + *  
   1.603 + *  The given rectangle is clipped to the destination surface clip area
   1.604 + *  and the final fill rectangle is saved in the passed in pointer.
   1.605 + *  
   1.606 + *  If \c dstrect is NULL, the whole surface will be filled with \c color.
   1.607 + *  
   1.608 + *  \return This function returns 0 on success, or -1 on error.
   1.609   */
   1.610  extern DECLSPEC int SDLCALL SDL_BlendRect
   1.611      (SDL_Surface * dst, SDL_Rect * dstrect, int blendMode, Uint8 r, Uint8 g,
   1.612       Uint8 b, Uint8 a);
   1.613  
   1.614  /**
   1.615 - * This performs a fast blit from the source surface to the destination
   1.616 - * surface.  It assumes that the source and destination rectangles are
   1.617 - * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
   1.618 - * surface (src or dst) is copied.  The final blit rectangles are saved
   1.619 - * in 'srcrect' and 'dstrect' after all clipping is performed.
   1.620 - * If the blit is successful, it returns 0, otherwise it returns -1.
   1.621 + *  Performs a fast blit from the source surface to the destination surface.
   1.622 + *  
   1.623 + *  This assumes that the source and destination rectangles are
   1.624 + *  the same size.  If either \c srcrect or \c dstrect are NULL, the entire
   1.625 + *  surface (\c src or \c dst) is copied.  The final blit rectangles are saved
   1.626 + *  in \c srcrect and \c dstrect after all clipping is performed.
   1.627 + *  
   1.628 + *  \return If the blit is successful, it returns 0, otherwise it returns -1.
   1.629   *
   1.630 - * The blit function should not be called on a locked surface.
   1.631 + *  The blit function should not be called on a locked surface.
   1.632   *
   1.633 - * The blit semantics for surfaces with and without alpha and colorkey
   1.634 - * are defined as follows:
   1.635 - *
   1.636 - * RGBA->RGB:
   1.637 - *     SDL_SRCALPHA set:
   1.638 - * 	alpha-blend (using alpha-channel).
   1.639 - * 	SDL_SRCCOLORKEY ignored.
   1.640 - *     SDL_SRCALPHA not set:
   1.641 - * 	copy RGB.
   1.642 - * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
   1.643 - * 	RGB values of the source colour key, ignoring alpha in the
   1.644 - * 	comparison.
   1.645 - * 
   1.646 - * RGB->RGBA:
   1.647 - *     SDL_SRCALPHA set:
   1.648 - * 	alpha-blend (using the source per-surface alpha value);
   1.649 - * 	set destination alpha to opaque.
   1.650 - *     SDL_SRCALPHA not set:
   1.651 - * 	copy RGB, set destination alpha to source per-surface alpha value.
   1.652 - *     both:
   1.653 - * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
   1.654 - * 	source colour key.
   1.655 - * 
   1.656 - * RGBA->RGBA:
   1.657 - *     SDL_SRCALPHA set:
   1.658 - * 	alpha-blend (using the source alpha channel) the RGB values;
   1.659 - * 	leave destination alpha untouched. [Note: is this correct?]
   1.660 - * 	SDL_SRCCOLORKEY ignored.
   1.661 - *     SDL_SRCALPHA not set:
   1.662 - * 	copy all of RGBA to the destination.
   1.663 - * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
   1.664 - * 	RGB values of the source colour key, ignoring alpha in the
   1.665 - * 	comparison.
   1.666 - * 
   1.667 - * RGB->RGB: 
   1.668 - *     SDL_SRCALPHA set:
   1.669 - * 	alpha-blend (using the source per-surface alpha value).
   1.670 - *     SDL_SRCALPHA not set:
   1.671 - * 	copy RGB.
   1.672 - *     both:
   1.673 - * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
   1.674 - * 	source colour key.
   1.675 - *
   1.676 - * If either of the surfaces were in video memory, and the blit returns -2,
   1.677 - * the video memory was lost, so it should be reloaded with artwork and 
   1.678 - * re-blitted:
   1.679 - * @code
   1.680 - *	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
   1.681 - *		while ( SDL_LockSurface(image) < 0 )
   1.682 - *			Sleep(10);
   1.683 - *		-- Write image pixels to image->pixels --
   1.684 - *		SDL_UnlockSurface(image);
   1.685 - *	}
   1.686 - * @endcode
   1.687 - *
   1.688 - * This happens under DirectX 5.0 when the system switches away from your
   1.689 - * fullscreen application.  The lock will also fail until you have access
   1.690 - * to the video memory again.
   1.691 - *
   1.692 - * You should call SDL_BlitSurface() unless you know exactly how SDL
   1.693 - * blitting works internally and how to use the other blit functions.
   1.694 + *  The blit semantics for surfaces with and without alpha and colorkey
   1.695 + *  are defined as follows:
   1.696 + *  \verbatim
   1.697 +    RGBA->RGB:
   1.698 +      SDL_SRCALPHA set:
   1.699 +        alpha-blend (using alpha-channel).
   1.700 +        SDL_SRCCOLORKEY ignored.
   1.701 +      SDL_SRCALPHA not set:
   1.702 +        copy RGB.
   1.703 +        if SDL_SRCCOLORKEY set, only copy the pixels matching the
   1.704 +        RGB values of the source colour key, ignoring alpha in the
   1.705 +        comparison.
   1.706 +   
   1.707 +    RGB->RGBA:
   1.708 +      SDL_SRCALPHA set:
   1.709 +        alpha-blend (using the source per-surface alpha value);
   1.710 +        set destination alpha to opaque.
   1.711 +      SDL_SRCALPHA not set:
   1.712 +        copy RGB, set destination alpha to source per-surface alpha value.
   1.713 +      both:
   1.714 +        if SDL_SRCCOLORKEY set, only copy the pixels matching the
   1.715 +        source colour key.
   1.716 +   
   1.717 +    RGBA->RGBA:
   1.718 +      SDL_SRCALPHA set:
   1.719 +        alpha-blend (using the source alpha channel) the RGB values;
   1.720 +        leave destination alpha untouched. [Note: is this correct?]
   1.721 +        SDL_SRCCOLORKEY ignored.
   1.722 +      SDL_SRCALPHA not set:
   1.723 +        copy all of RGBA to the destination.
   1.724 +        if SDL_SRCCOLORKEY set, only copy the pixels matching the
   1.725 +        RGB values of the source colour key, ignoring alpha in the
   1.726 +       comparison.
   1.727 +   
   1.728 +    RGB->RGB: 
   1.729 +      SDL_SRCALPHA set:
   1.730 +        alpha-blend (using the source per-surface alpha value).
   1.731 +      SDL_SRCALPHA not set:
   1.732 +        copy RGB.
   1.733 +      both:
   1.734 +        if SDL_SRCCOLORKEY set, only copy the pixels matching the
   1.735 +        source colour key.
   1.736 +    \endverbatim
   1.737 + *  
   1.738 + *  If either of the surfaces were in video memory, and the blit returns -2,
   1.739 + *  the video memory was lost, so it should be reloaded with artwork and 
   1.740 + *  re-blitted:
   1.741 + *  @code
   1.742 + *  while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
   1.743 + *      while ( SDL_LockSurface(image) < 0 )
   1.744 + *          Sleep(10);
   1.745 + *      -- Write image pixels to image->pixels --
   1.746 + *      SDL_UnlockSurface(image);
   1.747 + *  }
   1.748 + *  @endcode
   1.749 + *  
   1.750 + *  This happens under DirectX 5.0 when the system switches away from your
   1.751 + *  fullscreen application.  The lock will also fail until you have access
   1.752 + *  to the video memory again.
   1.753 + *  
   1.754 + *  You should call SDL_BlitSurface() unless you know exactly how SDL
   1.755 + *  blitting works internally and how to use the other blit functions.
   1.756   */
   1.757  #define SDL_BlitSurface SDL_UpperBlit
   1.758  
   1.759 -/** This is the public blit function, SDL_BlitSurface(), and it performs
   1.760 +/**
   1.761 + *  This is the public blit function, SDL_BlitSurface(), and it performs
   1.762   *  rectangle validation and clipping before passing it to SDL_LowerBlit()
   1.763   */
   1.764  extern DECLSPEC int SDLCALL SDL_UpperBlit
   1.765      (SDL_Surface * src, SDL_Rect * srcrect,
   1.766       SDL_Surface * dst, SDL_Rect * dstrect);
   1.767  
   1.768 -/** This is a semi-private blit function and it performs low-level surface
   1.769 +/**
   1.770 + *  This is a semi-private blit function and it performs low-level surface
   1.771   *  blitting only.
   1.772   */
   1.773  extern DECLSPEC int SDLCALL SDL_LowerBlit
   1.774 @@ -505,9 +553,10 @@
   1.775       SDL_Surface * dst, SDL_Rect * dstrect);
   1.776  
   1.777  /**
   1.778 - * \brief Perform a fast, low quality, stretch blit between two surfaces of the same pixel format.
   1.779 - *
   1.780 - * \note This function uses a static buffer, and is not thread-safe.
   1.781 + *  \brief Perform a fast, low quality, stretch blit between two surfaces of the
   1.782 + *         same pixel format.
   1.783 + *  
   1.784 + *  \note This function uses a static buffer, and is not thread-safe.
   1.785   */
   1.786  extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
   1.787                                              const SDL_Rect * srcrect,