include/SDL_surface.h
changeset 7191 75360622e65f
parent 7188 20bd120bf7e4
child 7278 fc8b57a2a541
     1.1 --- a/include/SDL_surface.h	Sat May 18 12:48:50 2013 -0700
     1.2 +++ b/include/SDL_surface.h	Sat May 18 14:17:52 2013 -0700
     1.3 @@ -21,7 +21,7 @@
     1.4  
     1.5  /**
     1.6   *  \file SDL_surface.h
     1.7 - *  
     1.8 + *
     1.9   *  Header file for ::SDL_surface definition and management functions.
    1.10   */
    1.11  
    1.12 @@ -37,16 +37,14 @@
    1.13  #include "begin_code.h"
    1.14  /* Set up for C function definitions, even when using C++ */
    1.15  #ifdef __cplusplus
    1.16 -/* *INDENT-OFF* */
    1.17  extern "C" {
    1.18 -/* *INDENT-ON* */
    1.19  #endif
    1.20  
    1.21  /**
    1.22   *  \name Surface flags
    1.23 - *  
    1.24 + *
    1.25   *  These are the currently supported flags for the ::SDL_surface.
    1.26 - *  
    1.27 + *
    1.28   *  \internal
    1.29   *  Used internally (read-only).
    1.30   */
    1.31 @@ -60,7 +58,7 @@
    1.32  /**
    1.33   *  Evaluates to true if the surface needs to be locked before access.
    1.34   */
    1.35 -#define SDL_MUSTLOCK(S)	(((S)->flags & SDL_RLEACCEL) != 0)
    1.36 +#define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0)
    1.37  
    1.38  /**
    1.39   * \brief A collection of pixels used in software blitting.
    1.40 @@ -101,13 +99,13 @@
    1.41  
    1.42  /**
    1.43   *  Allocate and free an RGB surface.
    1.44 - *  
    1.45 + *
    1.46   *  If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
    1.47   *  If the depth is greater than 8 bits, the pixel format is set using the
    1.48   *  flags '[RGB]mask'.
    1.49 - *  
    1.50 + *
    1.51   *  If the function runs out of memory, it will return NULL.
    1.52 - *  
    1.53 + *
    1.54   *  \param flags The \c flags are obsolete and should be set to 0.
    1.55   *  \param width The width in pixels of the surface to create.
    1.56   *  \param height The height in pixels of the surface to create.
    1.57 @@ -133,9 +131,9 @@
    1.58  
    1.59  /**
    1.60   *  \brief Set the palette used by a surface.
    1.61 - *  
    1.62 + *
    1.63   *  \return 0, or -1 if the surface format doesn't use a palette.
    1.64 - *  
    1.65 + *
    1.66   *  \note A single palette can be shared with many surfaces.
    1.67   */
    1.68  extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
    1.69 @@ -143,21 +141,21 @@
    1.70  
    1.71  /**
    1.72   *  \brief Sets up a surface for directly accessing the pixels.
    1.73 - *  
    1.74 + *
    1.75   *  Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write
    1.76 - *  to and read from \c surface->pixels, using the pixel format stored in 
    1.77 - *  \c surface->format.  Once you are done accessing the surface, you should 
    1.78 + *  to and read from \c surface->pixels, using the pixel format stored in
    1.79 + *  \c surface->format.  Once you are done accessing the surface, you should
    1.80   *  use SDL_UnlockSurface() to release it.
    1.81 - *  
    1.82 + *
    1.83   *  Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
    1.84   *  to 0, then you can read and write to the surface at any time, and the
    1.85   *  pixel format of the surface will not change.
    1.86 - *  
    1.87 + *
    1.88   *  No operating system or library calls should be made between lock/unlock
    1.89   *  pairs, as critical system locks may be held during this time.
    1.90 - *  
    1.91 + *
    1.92   *  SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
    1.93 - *  
    1.94 + *
    1.95   *  \sa SDL_UnlockSurface()
    1.96   */
    1.97  extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
    1.98 @@ -166,11 +164,11 @@
    1.99  
   1.100  /**
   1.101   *  Load a surface from a seekable SDL data stream (memory or file).
   1.102 - *  
   1.103 + *
   1.104   *  If \c freesrc is non-zero, the stream will be closed after being read.
   1.105 - *  
   1.106 + *
   1.107   *  The new surface should be freed with SDL_FreeSurface().
   1.108 - *  
   1.109 + *
   1.110   *  \return the new surface, or NULL if there was an error.
   1.111   */
   1.112  extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
   1.113 @@ -178,34 +176,34 @@
   1.114  
   1.115  /**
   1.116   *  Load a surface from a file.
   1.117 - *  
   1.118 + *
   1.119   *  Convenience macro.
   1.120   */
   1.121 -#define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
   1.122 +#define SDL_LoadBMP(file)   SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
   1.123  
   1.124  /**
   1.125   *  Save a surface to a seekable SDL data stream (memory or file).
   1.126 - *  
   1.127 + *
   1.128   *  If \c freedst is non-zero, the stream will be closed after being written.
   1.129 - *  
   1.130 + *
   1.131   *  \return 0 if successful or -1 if there was an error.
   1.132   */
   1.133  extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
   1.134      (SDL_Surface * surface, SDL_RWops * dst, int freedst);
   1.135  
   1.136 -/** 
   1.137 +/**
   1.138   *  Save a surface to a file.
   1.139 - *  
   1.140 + *
   1.141   *  Convenience macro.
   1.142   */
   1.143  #define SDL_SaveBMP(surface, file) \
   1.144 -		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
   1.145 +        SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
   1.146  
   1.147  /**
   1.148   *  \brief Sets the RLE acceleration hint for a surface.
   1.149 - *  
   1.150 + *
   1.151   *  \return 0 on success, or -1 if the surface is not valid
   1.152 - *  
   1.153 + *
   1.154   *  \note If RLE is enabled, colorkey and alpha blending blits are much faster,
   1.155   *        but the surface must be locked before directly accessing the pixels.
   1.156   */
   1.157 @@ -214,11 +212,11 @@
   1.158  
   1.159  /**
   1.160   *  \brief Sets the color key (transparent pixel) in a blittable surface.
   1.161 - *  
   1.162 + *
   1.163   *  \param surface The surface to update
   1.164   *  \param flag Non-zero to enable colorkey and 0 to disable colorkey
   1.165   *  \param key The transparent pixel in the native surface format
   1.166 - *  
   1.167 + *
   1.168   *  \return 0 on success, or -1 if the surface is not valid
   1.169   *
   1.170   *  You can pass SDL_RLEACCEL to enable RLE accelerated blits.
   1.171 @@ -228,12 +226,12 @@
   1.172  
   1.173  /**
   1.174   *  \brief Gets the color key (transparent pixel) in a blittable surface.
   1.175 - *  
   1.176 + *
   1.177   *  \param surface The surface to update
   1.178 - *  \param key A pointer filled in with the transparent pixel in the native 
   1.179 + *  \param key A pointer filled in with the transparent pixel in the native
   1.180   *             surface format
   1.181 - *  
   1.182 - *  \return 0 on success, or -1 if the surface is not valid or colorkey is not 
   1.183 + *
   1.184 + *  \return 0 on success, or -1 if the surface is not valid or colorkey is not
   1.185   *          enabled.
   1.186   */
   1.187  extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface,
   1.188 @@ -241,14 +239,14 @@
   1.189  
   1.190  /**
   1.191   *  \brief Set an additional color value used in blit operations.
   1.192 - *  
   1.193 + *
   1.194   *  \param surface The surface to update.
   1.195   *  \param r The red color value multiplied into blit operations.
   1.196   *  \param g The green color value multiplied into blit operations.
   1.197   *  \param b The blue color value multiplied into blit operations.
   1.198 - *  
   1.199 + *
   1.200   *  \return 0 on success, or -1 if the surface is not valid.
   1.201 - *  
   1.202 + *
   1.203   *  \sa SDL_GetSurfaceColorMod()
   1.204   */
   1.205  extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface,
   1.206 @@ -257,14 +255,14 @@
   1.207  
   1.208  /**
   1.209   *  \brief Get the additional color value used in blit operations.
   1.210 - *  
   1.211 + *
   1.212   *  \param surface The surface to query.
   1.213   *  \param r A pointer filled in with the current red color value.
   1.214   *  \param g A pointer filled in with the current green color value.
   1.215   *  \param b A pointer filled in with the current blue color value.
   1.216 - *  
   1.217 + *
   1.218   *  \return 0 on success, or -1 if the surface is not valid.
   1.219 - *  
   1.220 + *
   1.221   *  \sa SDL_SetSurfaceColorMod()
   1.222   */
   1.223  extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface,
   1.224 @@ -273,12 +271,12 @@
   1.225  
   1.226  /**
   1.227   *  \brief Set an additional alpha value used in blit operations.
   1.228 - *  
   1.229 + *
   1.230   *  \param surface The surface to update.
   1.231   *  \param alpha The alpha value multiplied into blit operations.
   1.232 - *  
   1.233 + *
   1.234   *  \return 0 on success, or -1 if the surface is not valid.
   1.235 - *  
   1.236 + *
   1.237   *  \sa SDL_GetSurfaceAlphaMod()
   1.238   */
   1.239  extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface,
   1.240 @@ -286,12 +284,12 @@
   1.241  
   1.242  /**
   1.243   *  \brief Get the additional alpha value used in blit operations.
   1.244 - *  
   1.245 + *
   1.246   *  \param surface The surface to query.
   1.247   *  \param alpha A pointer filled in with the current alpha value.
   1.248 - *  
   1.249 + *
   1.250   *  \return 0 on success, or -1 if the surface is not valid.
   1.251 - *  
   1.252 + *
   1.253   *  \sa SDL_SetSurfaceAlphaMod()
   1.254   */
   1.255  extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface,
   1.256 @@ -299,12 +297,12 @@
   1.257  
   1.258  /**
   1.259   *  \brief Set the blend mode used for blit operations.
   1.260 - *  
   1.261 + *
   1.262   *  \param surface The surface to update.
   1.263   *  \param blendMode ::SDL_BlendMode to use for blit blending.
   1.264 - *  
   1.265 + *
   1.266   *  \return 0 on success, or -1 if the parameters are not valid.
   1.267 - *  
   1.268 + *
   1.269   *  \sa SDL_GetSurfaceBlendMode()
   1.270   */
   1.271  extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface,
   1.272 @@ -312,12 +310,12 @@
   1.273  
   1.274  /**
   1.275   *  \brief Get the blend mode used for blit operations.
   1.276 - *  
   1.277 + *
   1.278   *  \param surface   The surface to query.
   1.279   *  \param blendMode A pointer filled in with the current blend mode.
   1.280 - *  
   1.281 + *
   1.282   *  \return 0 on success, or -1 if the surface is not valid.
   1.283 - *  
   1.284 + *
   1.285   *  \sa SDL_SetSurfaceBlendMode()
   1.286   */
   1.287  extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
   1.288 @@ -325,14 +323,14 @@
   1.289  
   1.290  /**
   1.291   *  Sets the clipping rectangle for the destination surface in a blit.
   1.292 - *  
   1.293 + *
   1.294   *  If the clip rectangle is NULL, clipping will be disabled.
   1.295 - *  
   1.296 + *
   1.297   *  If the clip rectangle doesn't intersect the surface, the function will
   1.298   *  return SDL_FALSE and blits will be completely clipped.  Otherwise the
   1.299   *  function returns SDL_TRUE and blits to the surface will be clipped to
   1.300   *  the intersection of the surface area and the clipping rectangle.
   1.301 - *  
   1.302 + *
   1.303   *  Note that blits are automatically clipped to the edges of the source
   1.304   *  and destination surfaces.
   1.305   */
   1.306 @@ -341,7 +339,7 @@
   1.307  
   1.308  /**
   1.309   *  Gets the clipping rectangle for the destination surface in a blit.
   1.310 - *  
   1.311 + *
   1.312   *  \c rect must be a pointer to a valid rectangle which will be filled
   1.313   *  with the correct values.
   1.314   */
   1.315 @@ -349,11 +347,11 @@
   1.316                                               SDL_Rect * rect);
   1.317  
   1.318  /**
   1.319 - *  Creates a new surface of the specified format, and then copies and maps 
   1.320 - *  the given surface to it so the blit of the converted surface will be as 
   1.321 + *  Creates a new surface of the specified format, and then copies and maps
   1.322 + *  the given surface to it so the blit of the converted surface will be as
   1.323   *  fast as possible.  If this function fails, it returns NULL.
   1.324 - *  
   1.325 - *  The \c flags parameter is passed to SDL_CreateRGBSurface() and has those 
   1.326 + *
   1.327 + *  The \c flags parameter is passed to SDL_CreateRGBSurface() and has those
   1.328   *  semantics.  You can also pass ::SDL_RLEACCEL in the flags parameter and
   1.329   *  SDL will try to RLE accelerate colorkey and alpha blits in the resulting
   1.330   *  surface.
   1.331 @@ -365,7 +363,7 @@
   1.332  
   1.333  /**
   1.334   * \brief Copy a block of pixels of one format to another format
   1.335 - *  
   1.336 + *
   1.337   *  \return 0 on success, or -1 if there was an error
   1.338   */
   1.339  extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
   1.340 @@ -376,12 +374,12 @@
   1.341  
   1.342  /**
   1.343   *  Performs a fast fill of the given rectangle with \c color.
   1.344 - *  
   1.345 + *
   1.346   *  If \c rect is NULL, the whole surface will be filled with \c color.
   1.347 - *  
   1.348 - *  The color should be a pixel of the format used by the surface, and 
   1.349 + *
   1.350 + *  The color should be a pixel of the format used by the surface, and
   1.351   *  can be generated by the SDL_MapRGB() function.
   1.352 - *  
   1.353 + *
   1.354   *  \return 0 on success, or -1 on error.
   1.355   */
   1.356  extern DECLSPEC int SDLCALL SDL_FillRect
   1.357 @@ -391,12 +389,12 @@
   1.358  
   1.359  /**
   1.360   *  Performs a fast blit from the source surface to the destination surface.
   1.361 - *  
   1.362 + *
   1.363   *  This assumes that the source and destination rectangles are
   1.364   *  the same size.  If either \c srcrect or \c dstrect are NULL, the entire
   1.365   *  surface (\c src or \c dst) is copied.  The final blit rectangles are saved
   1.366   *  in \c srcrect and \c dstrect after all clipping is performed.
   1.367 - *  
   1.368 + *
   1.369   *  \return If the blit is successful, it returns 0, otherwise it returns -1.
   1.370   *
   1.371   *  The blit function should not be called on a locked surface.
   1.372 @@ -413,7 +411,7 @@
   1.373          if SDL_SRCCOLORKEY set, only copy the pixels matching the
   1.374          RGB values of the source color key, ignoring alpha in the
   1.375          comparison.
   1.376 -   
   1.377 +
   1.378      RGB->RGBA:
   1.379        SDL_SRCALPHA set:
   1.380          alpha-blend (using the source per-surface alpha value);
   1.381 @@ -423,7 +421,7 @@
   1.382        both:
   1.383          if SDL_SRCCOLORKEY set, only copy the pixels matching the
   1.384          source color key.
   1.385 -   
   1.386 +
   1.387      RGBA->RGBA:
   1.388        SDL_SRCALPHA set:
   1.389          alpha-blend (using the source alpha channel) the RGB values;
   1.390 @@ -434,8 +432,8 @@
   1.391          if SDL_SRCCOLORKEY set, only copy the pixels matching the
   1.392          RGB values of the source color key, ignoring alpha in the
   1.393         comparison.
   1.394 -   
   1.395 -    RGB->RGB: 
   1.396 +
   1.397 +    RGB->RGB:
   1.398        SDL_SRCALPHA set:
   1.399          alpha-blend (using the source per-surface alpha value).
   1.400        SDL_SRCALPHA not set:
   1.401 @@ -444,7 +442,7 @@
   1.402          if SDL_SRCCOLORKEY set, only copy the pixels matching the
   1.403          source color key.
   1.404      \endverbatim
   1.405 - *  
   1.406 + *
   1.407   *  You should call SDL_BlitSurface() unless you know exactly how SDL
   1.408   *  blitting works internally and how to use the other blit functions.
   1.409   */
   1.410 @@ -469,7 +467,7 @@
   1.411  /**
   1.412   *  \brief Perform a fast, low quality, stretch blit between two surfaces of the
   1.413   *         same pixel format.
   1.414 - *  
   1.415 + *
   1.416   *  \note This function uses a static buffer, and is not thread-safe.
   1.417   */
   1.418  extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
   1.419 @@ -498,9 +496,7 @@
   1.420  
   1.421  /* Ends C function definitions when using C++ */
   1.422  #ifdef __cplusplus
   1.423 -/* *INDENT-OFF* */
   1.424  }
   1.425 -/* *INDENT-ON* */
   1.426  #endif
   1.427  #include "close_code.h"
   1.428