include/SDL_surface.h
changeset 3341 710139a1692d
parent 3103 7be21a78777e
child 3407 d3baf5ac4e37
     1.1 --- a/include/SDL_surface.h	Sun Oct 04 18:09:12 2009 +0000
     1.2 +++ b/include/SDL_surface.h	Sun Oct 04 19:14:30 2009 +0000
     1.3 @@ -42,17 +42,18 @@
     1.4  /* *INDENT-ON* */
     1.5  #endif
     1.6  
     1.7 -/* These are the currently supported flags for the SDL_surface */
     1.8 -/* Used internally (read-only) */
     1.9 -#define SDL_PREALLOC        0x00000001  /* Surface uses preallocated memory */
    1.10 -#define SDL_RLEACCEL        0x00000002  /* Surface is RLE encoded */
    1.11 +/** These are the currently supported flags for the SDL_surface
    1.12 + *  \internal Used internally (read-only) 
    1.13 + */
    1.14 +/*@{*/
    1.15 +#define SDL_PREALLOC        0x00000001  /**< Surface uses preallocated memory */
    1.16 +#define SDL_RLEACCEL        0x00000002  /**< Surface is RLE encoded */
    1.17 +/*@}*/
    1.18  
    1.19 -/* Evaluates to true if the surface needs to be locked before access */
    1.20 +/** Evaluates to true if the surface needs to be locked before access */
    1.21  #define SDL_MUSTLOCK(S)	(((S)->flags & SDL_RLEACCEL) != 0)
    1.22  
    1.23  /**
    1.24 - * \struct SDL_Surface
    1.25 - *
    1.26   * \brief A collection of pixels used in software blitting
    1.27   *
    1.28   * \note  This structure should be treated as read-only, except for 'pixels',
    1.29 @@ -87,21 +88,19 @@
    1.30  } SDL_Surface;
    1.31  
    1.32  /**
    1.33 - * \typedef SDL_blit
    1.34 - *
    1.35   * \brief The type of function used for surface blitting functions
    1.36   */
    1.37  typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
    1.38                           struct SDL_Surface * dst, SDL_Rect * dstrect);
    1.39  
    1.40 -/*
    1.41 +/**
    1.42   * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
    1.43   * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
    1.44   * If the depth is greater than 8 bits, the pixel format is set using the
    1.45   * flags '[RGB]mask'.
    1.46   * If the function runs out of memory, it will return NULL.
    1.47   *
    1.48 - * The 'flags' are obsolete and should be set to 0.
    1.49 + * \param flags The 'flags' are obsolete and should be set to 0.
    1.50   */
    1.51  extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
    1.52      (Uint32 flags, int width, int height, int depth,
    1.53 @@ -118,8 +117,6 @@
    1.54  extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
    1.55  
    1.56  /**
    1.57 - * \fn int SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette)
    1.58 - *
    1.59   * \brief Set the palette used by a surface.
    1.60   *
    1.61   * \return 0, or -1 if the surface format doesn't use a palette.
    1.62 @@ -129,8 +126,9 @@
    1.63  extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
    1.64                                                    SDL_Palette * palette);
    1.65  
    1.66 -/*
    1.67 - * SDL_LockSurface() sets up a surface for directly accessing the pixels.
    1.68 +/**
    1.69 + * \brief Sets up a surface for directly accessing the pixels.
    1.70 + *
    1.71   * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
    1.72   * to and read from 'surface->pixels', using the pixel format stored in 
    1.73   * 'surface->format'.  Once you are done accessing the surface, you should 
    1.74 @@ -144,11 +142,14 @@
    1.75   * pairs, as critical system locks may be held during this time.
    1.76   *
    1.77   * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
    1.78 + * 
    1.79 + * \sa SDL_UnlockSurface()
    1.80   */
    1.81  extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
    1.82 +/** \sa SDL_LockSurface() */
    1.83  extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
    1.84  
    1.85 -/*
    1.86 +/**
    1.87   * Load a surface from a seekable SDL data source (memory or file.)
    1.88   * If 'freesrc' is non-zero, the source will be closed after being read.
    1.89   * Returns the new surface, or NULL if there was an error.
    1.90 @@ -157,10 +158,10 @@
    1.91  extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
    1.92                                                      int freesrc);
    1.93  
    1.94 -/* Convenience macro -- load a surface from a file */
    1.95 +/** Convenience macro -- load a surface from a file */
    1.96  #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
    1.97  
    1.98 -/*
    1.99 +/**
   1.100   * Save a surface to a seekable SDL data source (memory or file.)
   1.101   * If 'freedst' is non-zero, the source will be closed after being written.
   1.102   * Returns 0 if successful or -1 if there was an error.
   1.103 @@ -168,13 +169,11 @@
   1.104  extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
   1.105      (SDL_Surface * surface, SDL_RWops * dst, int freedst);
   1.106  
   1.107 -/* Convenience macro -- save a surface to a file */
   1.108 +/** Convenience macro -- save a surface to a file */
   1.109  #define SDL_SaveBMP(surface, file) \
   1.110  		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
   1.111  
   1.112 -/*
   1.113 - * \fn int SDL_SetSurfaceRLE(SDL_Surface *surface, int flag)
   1.114 - *
   1.115 +/**
   1.116   * \brief Sets the RLE acceleration hint for a surface.
   1.117   *
   1.118   * \return 0 on success, or -1 if the surface is not valid
   1.119 @@ -185,9 +184,7 @@
   1.120  extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface,
   1.121                                                int flag);
   1.122  
   1.123 -/*
   1.124 - * \fn int SDL_SetColorKey(SDL_Surface *surface, Uint32 flag, Uint32 key)
   1.125 - *
   1.126 +/**
   1.127   * \brief Sets the color key (transparent pixel) in a blittable surface.
   1.128   *
   1.129   * \param surface The surface to update
   1.130 @@ -199,9 +196,7 @@
   1.131  extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface,
   1.132                                              Uint32 flag, Uint32 key);
   1.133  
   1.134 -/*
   1.135 - * \fn int SDL_GetColorKey(SDL_Surface *surface, Uint32 *key)
   1.136 - *
   1.137 +/**
   1.138   * \brief Sets the color key (transparent pixel) in a blittable surface.
   1.139   *
   1.140   * \param surface The surface to update
   1.141 @@ -213,8 +208,6 @@
   1.142                                              Uint32 * key);
   1.143  
   1.144  /**
   1.145 - * \fn int SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b)
   1.146 - *
   1.147   * \brief Set an additional color value used in blit operations
   1.148   *
   1.149   * \param surface The surface to update
   1.150 @@ -231,8 +224,6 @@
   1.151  
   1.152  
   1.153  /**
   1.154 - * \fn int SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b)
   1.155 - *
   1.156   * \brief Get the additional color value used in blit operations
   1.157   *
   1.158   * \param surface The surface to query
   1.159 @@ -249,8 +240,6 @@
   1.160                                                     Uint8 * b);
   1.161  
   1.162  /**
   1.163 - * \fn int SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha)
   1.164 - *
   1.165   * \brief Set an additional alpha value used in blit operations
   1.166   *
   1.167   * \param surface The surface to update
   1.168 @@ -264,8 +253,6 @@
   1.169                                                     Uint8 alpha);
   1.170  
   1.171  /**
   1.172 - * \fn int SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha)
   1.173 - *
   1.174   * \brief Get the additional alpha value used in blit operations
   1.175   *
   1.176   * \param surface The surface to query
   1.177 @@ -279,8 +266,6 @@
   1.178                                                     Uint8 * alpha);
   1.179  
   1.180  /**
   1.181 - * \fn int SDL_SetSurfaceBlendMode(SDL_Surface *surface, int blendMode)
   1.182 - *
   1.183   * \brief Set the blend mode used for blit operations
   1.184   *
   1.185   * \param surface The surface to update
   1.186 @@ -294,8 +279,6 @@
   1.187                                                      int blendMode);
   1.188  
   1.189  /**
   1.190 - * \fn int SDL_GetSurfaceBlendMode(SDL_Surface *surface, int *blendMode)
   1.191 - *
   1.192   * \brief Get the blend mode used for blit operations
   1.193   *
   1.194   * \param surface The surface to query
   1.195 @@ -309,8 +292,6 @@
   1.196                                                      int *blendMode);
   1.197  
   1.198  /**
   1.199 - * \fn int SDL_SetSurfaceScaleMode(SDL_Surface *surface, int scaleMode)
   1.200 - *
   1.201   * \brief Set the scale mode used for blit operations
   1.202   *
   1.203   * \param surface The surface to update
   1.204 @@ -326,8 +307,6 @@
   1.205                                                      int scaleMode);
   1.206  
   1.207  /**
   1.208 - * \fn int SDL_GetSurfaceScaleMode(SDL_Surface *surface, int *scaleMode)
   1.209 - *
   1.210   * \brief Get the scale mode used for blit operations
   1.211   *
   1.212   * \param surface The surface to query
   1.213 @@ -340,7 +319,7 @@
   1.214  extern DECLSPEC int SDLCALL SDL_GetSurfaceScaleMode(SDL_Surface * surface,
   1.215                                                      int *scaleMode);
   1.216  
   1.217 -/*
   1.218 +/**
   1.219   * Sets the clipping rectangle for the destination surface in a blit.
   1.220   *
   1.221   * If the clip rectangle is NULL, clipping will be disabled.
   1.222 @@ -355,7 +334,7 @@
   1.223  extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
   1.224                                                   const SDL_Rect * rect);
   1.225  
   1.226 -/*
   1.227 +/**
   1.228   * Gets the clipping rectangle for the destination surface in a blit.
   1.229   * 'rect' must be a pointer to a valid rectangle which will be filled
   1.230   * with the correct values.
   1.231 @@ -363,7 +342,7 @@
   1.232  extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
   1.233                                               SDL_Rect * rect);
   1.234  
   1.235 -/*
   1.236 +/**
   1.237   * Creates a new surface of the specified format, and then copies and maps 
   1.238   * the given surface to it so the blit of the converted surface will be as 
   1.239   * fast as possible.  If this function fails, it returns NULL.
   1.240 @@ -378,66 +357,66 @@
   1.241  extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
   1.242      (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags);
   1.243  
   1.244 -/*
   1.245 +/**
   1.246   * This function draws a point with 'color'
   1.247   * The color should be a pixel of the format used by the surface, and 
   1.248   * can be generated by the SDL_MapRGB() function.
   1.249 - * This function returns 0 on success, or -1 on error.
   1.250 + * \return This function returns 0 on success, or -1 on error.
   1.251   */
   1.252  extern DECLSPEC int SDLCALL SDL_DrawPoint
   1.253      (SDL_Surface * dst, int x, int y, Uint32 color);
   1.254  
   1.255 -/*
   1.256 +/**
   1.257   * This function blends a point with an RGBA value
   1.258   * The color should be a pixel of the format used by the surface, and 
   1.259   * can be generated by the SDL_MapRGB() function.
   1.260 - * This function returns 0 on success, or -1 on error.
   1.261 + * \return This function returns 0 on success, or -1 on error.
   1.262   */
   1.263  extern DECLSPEC int SDLCALL SDL_BlendPoint
   1.264      (SDL_Surface * dst, int x, int y, int blendMode,
   1.265       Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   1.266  
   1.267 -/*
   1.268 +/**
   1.269   * This function draws a line with 'color'
   1.270   * The color should be a pixel of the format used by the surface, and 
   1.271   * can be generated by the SDL_MapRGB() function.
   1.272 - * This function returns 0 on success, or -1 on error.
   1.273 + * \return This function returns 0 on success, or -1 on error.
   1.274   */
   1.275  extern DECLSPEC int SDLCALL SDL_DrawLine
   1.276      (SDL_Surface * dst, int x1, int y1, int x2, int y2, Uint32 color);
   1.277  
   1.278 -/*
   1.279 +/**
   1.280   * This function blends an RGBA value along a line
   1.281 - * This function returns 0 on success, or -1 on error.
   1.282 + * \return This function returns 0 on success, or -1 on error.
   1.283   */
   1.284  extern DECLSPEC int SDLCALL SDL_BlendLine
   1.285      (SDL_Surface * dst, int x1, int y1, int x2, int y2, int blendMode,
   1.286       Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   1.287  
   1.288 -/*
   1.289 +/**
   1.290   * This function performs a fast fill of the given rectangle with 'color'
   1.291   * The given rectangle is clipped to the destination surface clip area
   1.292   * and the final fill rectangle is saved in the passed in pointer.
   1.293   * If 'dstrect' is NULL, the whole surface will be filled with 'color'
   1.294   * The color should be a pixel of the format used by the surface, and 
   1.295   * can be generated by the SDL_MapRGB() function.
   1.296 - * This function returns 0 on success, or -1 on error.
   1.297 + * \return This function returns 0 on success, or -1 on error.
   1.298   */
   1.299  extern DECLSPEC int SDLCALL SDL_FillRect
   1.300      (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color);
   1.301  
   1.302 -/*
   1.303 +/**
   1.304   * This function blends an RGBA value into the given rectangle.
   1.305   * The given rectangle is clipped to the destination surface clip area
   1.306   * and the final fill rectangle is saved in the passed in pointer.
   1.307   * If 'dstrect' is NULL, the whole surface will be filled with 'color'
   1.308 - * This function returns 0 on success, or -1 on error.
   1.309 + * \return This function returns 0 on success, or -1 on error.
   1.310   */
   1.311  extern DECLSPEC int SDLCALL SDL_BlendRect
   1.312      (SDL_Surface * dst, SDL_Rect * dstrect, int blendMode, Uint8 r, Uint8 g,
   1.313       Uint8 b, Uint8 a);
   1.314  
   1.315 -/*
   1.316 +/**
   1.317   * This performs a fast blit from the source surface to the destination
   1.318   * surface.  It assumes that the source and destination rectangles are
   1.319   * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
   1.320 @@ -493,37 +472,39 @@
   1.321   * If either of the surfaces were in video memory, and the blit returns -2,
   1.322   * the video memory was lost, so it should be reloaded with artwork and 
   1.323   * re-blitted:
   1.324 -	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
   1.325 -		while ( SDL_LockSurface(image) < 0 )
   1.326 -			Sleep(10);
   1.327 -		-- Write image pixels to image->pixels --
   1.328 -		SDL_UnlockSurface(image);
   1.329 -	}
   1.330 + * @code
   1.331 + *	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
   1.332 + *		while ( SDL_LockSurface(image) < 0 )
   1.333 + *			Sleep(10);
   1.334 + *		-- Write image pixels to image->pixels --
   1.335 + *		SDL_UnlockSurface(image);
   1.336 + *	}
   1.337 + * @endcode
   1.338 + *
   1.339   * This happens under DirectX 5.0 when the system switches away from your
   1.340   * fullscreen application.  The lock will also fail until you have access
   1.341   * to the video memory again.
   1.342 + *
   1.343 + * You should call SDL_BlitSurface() unless you know exactly how SDL
   1.344 + * blitting works internally and how to use the other blit functions.
   1.345   */
   1.346 -/* You should call SDL_BlitSurface() unless you know exactly how SDL
   1.347 -   blitting works internally and how to use the other blit functions.
   1.348 -*/
   1.349  #define SDL_BlitSurface SDL_UpperBlit
   1.350  
   1.351 -/* This is the public blit function, SDL_BlitSurface(), and it performs
   1.352 -   rectangle validation and clipping before passing it to SDL_LowerBlit()
   1.353 -*/
   1.354 +/** This is the public blit function, SDL_BlitSurface(), and it performs
   1.355 + *  rectangle validation and clipping before passing it to SDL_LowerBlit()
   1.356 + */
   1.357  extern DECLSPEC int SDLCALL SDL_UpperBlit
   1.358      (SDL_Surface * src, SDL_Rect * srcrect,
   1.359       SDL_Surface * dst, SDL_Rect * dstrect);
   1.360 -/* This is a semi-private blit function and it performs low-level surface
   1.361 -   blitting only.
   1.362 -*/
   1.363 +
   1.364 +/** This is a semi-private blit function and it performs low-level surface
   1.365 + *  blitting only.
   1.366 + */
   1.367  extern DECLSPEC int SDLCALL SDL_LowerBlit
   1.368      (SDL_Surface * src, SDL_Rect * srcrect,
   1.369       SDL_Surface * dst, SDL_Rect * dstrect);
   1.370  
   1.371  /**
   1.372 - * \fn int SDL_SoftStretch(SDL_Surface * src, const SDL_Rect * srcrect, SDL_Surface * dst, const SDL_Rect * dstrect)
   1.373 - *
   1.374   * \brief Perform a fast, low quality, stretch blit between two surfaces of the same pixel format.
   1.375   *
   1.376   * \note This function uses a static buffer, and is not thread-safe.