include/SDL_surface.h
author Paul Hunkin <paul@bieh.net>
Mon, 17 May 2010 15:14:34 +1200
changeset 4695 b7918263da92
parent 4424 274743af0430
child 4929 aa8888658021
permissions -rw-r--r--
Initial commit, adding __ANDROID__ to the platform list
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 1997-2010 Sam Lantinga
     4 
     5     This library is free software; you can redistribute it and/or
     6     modify it under the terms of the GNU Lesser General Public
     7     License as published by the Free Software Foundation; either
     8     version 2.1 of the License, or (at your option) any later version.
     9 
    10     This library is distributed in the hope that it will be useful,
    11     but WITHOUT ANY WARRANTY; without even the implied warranty of
    12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    13     Lesser General Public License for more details.
    14 
    15     You should have received a copy of the GNU Lesser General Public
    16     License along with this library; if not, write to the Free Software
    17     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    18 
    19     Sam Lantinga
    20     slouken@libsdl.org
    21 */
    22 
    23 /**
    24  *  \file SDL_surface.h
    25  *  
    26  *  Header file for ::SDL_surface definition and management functions.
    27  */
    28 
    29 #ifndef _SDL_surface_h
    30 #define _SDL_surface_h
    31 
    32 #include "SDL_stdinc.h"
    33 #include "SDL_pixels.h"
    34 #include "SDL_rect.h"
    35 #include "SDL_rwops.h"
    36 
    37 #include "begin_code.h"
    38 /* Set up for C function definitions, even when using C++ */
    39 #ifdef __cplusplus
    40 /* *INDENT-OFF* */
    41 extern "C" {
    42 /* *INDENT-ON* */
    43 #endif
    44 
    45 /**
    46  *  \name Surface flags
    47  *  
    48  *  These are the currently supported flags for the ::SDL_surface.
    49  *  
    50  *  \internal
    51  *  Used internally (read-only).
    52  */
    53 /*@{*/
    54 #define SDL_PREALLOC        0x00000001  /**< Surface uses preallocated memory */
    55 #define SDL_RLEACCEL        0x00000002  /**< Surface is RLE encoded */
    56 /*@}*//*Surface flags*/
    57 
    58 /**
    59  *  Evaluates to true if the surface needs to be locked before access.
    60  */
    61 #define SDL_MUSTLOCK(S)	(((S)->flags & SDL_RLEACCEL) != 0)
    62 
    63 /**
    64  * \brief A collection of pixels used in software blitting.
    65  *
    66  * \note  This structure should be treated as read-only, except for \c pixels,
    67  *        which, if not NULL, contains the raw pixel data for the surface.
    68  */
    69 typedef struct SDL_Surface
    70 {
    71     Uint32 flags;               /**< Read-only */
    72     SDL_PixelFormat *format;    /**< Read-only */
    73     int w, h;                   /**< Read-only */
    74     int pitch;                  /**< Read-only */
    75     void *pixels;               /**< Read-write */
    76 
    77     /** Application data associated with the surface */
    78     void *userdata;             /**< Read-write */
    79 
    80     /** information needed for surfaces requiring locks */
    81     int locked;                 /**< Read-only */
    82     void *lock_data;            /**< Read-only */
    83 
    84     /** clipping information */
    85     SDL_Rect clip_rect;         /**< Read-only */
    86 
    87     /** info for fast blit mapping to other surfaces */
    88     struct SDL_BlitMap *map;    /**< Private */
    89 
    90     /** format version, bumped at every change to invalidate blit maps */
    91     unsigned int format_version;        /**< Private */
    92 
    93     /** Reference count -- used when freeing surface */
    94     int refcount;               /**< Read-mostly */
    95 } SDL_Surface;
    96 
    97 /**
    98  * \brief The type of function used for surface blitting functions.
    99  */
   100 typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
   101                          struct SDL_Surface * dst, SDL_Rect * dstrect);
   102 
   103 /**
   104  *  Allocate and free an RGB surface.
   105  *  
   106  *  If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
   107  *  If the depth is greater than 8 bits, the pixel format is set using the
   108  *  flags '[RGB]mask'.
   109  *  
   110  *  If the function runs out of memory, it will return NULL.
   111  *  
   112  *  \param flags The \c flags are obsolete and should be set to 0.
   113  */
   114 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
   115     (Uint32 flags, int width, int height, int depth,
   116      Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
   117 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
   118                                                               int width,
   119                                                               int height,
   120                                                               int depth,
   121                                                               int pitch,
   122                                                               Uint32 Rmask,
   123                                                               Uint32 Gmask,
   124                                                               Uint32 Bmask,
   125                                                               Uint32 Amask);
   126 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
   127 
   128 /**
   129  *  \brief Set the palette used by a surface.
   130  *  
   131  *  \return 0, or -1 if the surface format doesn't use a palette.
   132  *  
   133  *  \note A single palette can be shared with many surfaces.
   134  */
   135 extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
   136                                                   SDL_Palette * palette);
   137 
   138 /**
   139  *  \brief Sets up a surface for directly accessing the pixels.
   140  *  
   141  *  Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write
   142  *  to and read from \c surface->pixels, using the pixel format stored in 
   143  *  \c surface->format.  Once you are done accessing the surface, you should 
   144  *  use SDL_UnlockSurface() to release it.
   145  *  
   146  *  Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
   147  *  to 0, then you can read and write to the surface at any time, and the
   148  *  pixel format of the surface will not change.
   149  *  
   150  *  No operating system or library calls should be made between lock/unlock
   151  *  pairs, as critical system locks may be held during this time.
   152  *  
   153  *  SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
   154  *  
   155  *  \sa SDL_UnlockSurface()
   156  */
   157 extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
   158 /** \sa SDL_LockSurface() */
   159 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
   160 
   161 /**
   162  *  Load a surface from a seekable SDL data source (memory or file).
   163  *  
   164  *  If \c freesrc is non-zero, the source will be closed after being read.
   165  *  
   166  *  The new surface should be freed with SDL_FreeSurface().
   167  *  
   168  *  \return the new surface, or NULL if there was an error.
   169  */
   170 extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
   171                                                     int freesrc);
   172 
   173 /**
   174  *  Load a surface from a file.
   175  *  
   176  *  Convenience macro.
   177  */
   178 #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
   179 
   180 /**
   181  *  Save a surface to a seekable SDL data source (memory or file).
   182  *  
   183  *  If \c freedst is non-zero, the source will be closed after being written.
   184  *  
   185  *  \return 0 if successful or -1 if there was an error.
   186  */
   187 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
   188     (SDL_Surface * surface, SDL_RWops * dst, int freedst);
   189 
   190 /** 
   191  *  Save a surface to a file.
   192  *  
   193  *  Convenience macro.
   194  */
   195 #define SDL_SaveBMP(surface, file) \
   196 		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
   197 
   198 /**
   199  *  \brief Sets the RLE acceleration hint for a surface.
   200  *  
   201  *  \return 0 on success, or -1 if the surface is not valid
   202  *  
   203  *  \note If RLE is enabled, colorkey and alpha blending blits are much faster,
   204  *        but the surface must be locked before directly accessing the pixels.
   205  */
   206 extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface,
   207                                               int flag);
   208 
   209 /**
   210  *  \brief Sets the color key (transparent pixel) in a blittable surface.
   211  *  
   212  *  \param surface The surface to update
   213  *  \param flag Non-zero to enable colorkey and 0 to disable colorkey 
   214  *  \param key The transparent pixel in the native surface format
   215  *  
   216  *  \return 0 on success, or -1 if the surface is not valid
   217  */
   218 extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface,
   219                                             int flag, Uint32 key);
   220 
   221 /**
   222  *  \brief Gets the color key (transparent pixel) in a blittable surface.
   223  *  
   224  *  \param surface The surface to update
   225  *  \param key A pointer filled in with the transparent pixel in the native 
   226  *             surface format
   227  *  
   228  *  \return 0 on success, or -1 if the surface is not valid or colorkey is not 
   229  *          enabled.
   230  */
   231 extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface,
   232                                             Uint32 * key);
   233 
   234 /**
   235  *  \brief Set an additional color value used in blit operations.
   236  *  
   237  *  \param surface The surface to update.
   238  *  \param r The red source color value multiplied into blit operations.
   239  *  \param g The green source color value multiplied into blit operations.
   240  *  \param b The blue source color value multiplied into blit operations.
   241  *  
   242  *  \return 0 on success, or -1 if the surface is not valid.
   243  *  
   244  *  \sa SDL_GetSurfaceColorMod()
   245  */
   246 extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface,
   247                                                    Uint8 r, Uint8 g, Uint8 b);
   248 
   249 
   250 /**
   251  *  \brief Get the additional color value used in blit operations.
   252  *  
   253  *  \param surface The surface to query.
   254  *  \param r A pointer filled in with the source red color value.
   255  *  \param g A pointer filled in with the source green color value.
   256  *  \param b A pointer filled in with the source blue color value.
   257  *  
   258  *  \return 0 on success, or -1 if the surface is not valid.
   259  *  
   260  *  \sa SDL_SetSurfaceColorMod()
   261  */
   262 extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface,
   263                                                    Uint8 * r, Uint8 * g,
   264                                                    Uint8 * b);
   265 
   266 /**
   267  *  \brief Set an additional alpha value used in blit operations.
   268  *  
   269  *  \param surface The surface to update.
   270  *  \param alpha The source alpha value multiplied into blit operations.
   271  *  
   272  *  \return 0 on success, or -1 if the surface is not valid.
   273  *  
   274  *  \sa SDL_GetSurfaceAlphaMod()
   275  */
   276 extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface,
   277                                                    Uint8 alpha);
   278 
   279 /**
   280  *  \brief Get the additional alpha value used in blit operations.
   281  *  
   282  *  \param surface The surface to query.
   283  *  \param alpha A pointer filled in with the source alpha value.
   284  *  
   285  *  \return 0 on success, or -1 if the surface is not valid.
   286  *  
   287  *  \sa SDL_SetSurfaceAlphaMod()
   288  */
   289 extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface,
   290                                                    Uint8 * alpha);
   291 
   292 /**
   293  *  \brief Set the blend mode used for blit operations.
   294  *  
   295  *  \param surface The surface to update.
   296  *  \param blendMode ::SDL_BlendMode to use for blit blending.
   297  *  
   298  *  \return 0 on success, or -1 if the parameters are not valid.
   299  *  
   300  *  \sa SDL_GetSurfaceBlendMode()
   301  */
   302 extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface,
   303                                                     int blendMode);
   304 
   305 /**
   306  *  \brief Get the blend mode used for blit operations.
   307  *  
   308  *  \param surface   The surface to query.
   309  *  \param blendMode A pointer filled in with the current blend mode.
   310  *  
   311  *  \return 0 on success, or -1 if the surface is not valid.
   312  *  
   313  *  \sa SDL_SetSurfaceBlendMode()
   314  */
   315 extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
   316                                                     int *blendMode);
   317 
   318 /**
   319  *  \brief Set the scale mode used for blit operations.
   320  *  
   321  *  \param surface   The surface to update.
   322  *  \param scaleMode ::SDL_TextureScaleMode to use for blit scaling.
   323  *  
   324  *  \return 0 on success, or -1 if the surface is not valid or the scale mode is
   325  *          not supported.
   326  *  
   327  *  \note If the scale mode is not supported, the closest supported mode is 
   328  *        chosen.  Currently only ::SDL_TEXTURESCALEMODE_FAST is supported on 
   329  *        surfaces.
   330  *  
   331  *  \sa SDL_GetSurfaceScaleMode()
   332  */
   333 extern DECLSPEC int SDLCALL SDL_SetSurfaceScaleMode(SDL_Surface * surface,
   334                                                     int scaleMode);
   335 
   336 /**
   337  *  \brief Get the scale mode used for blit operations.
   338  *  
   339  *  \param surface   The surface to query.
   340  *  \param scaleMode A pointer filled in with the current scale mode.
   341  *  
   342  *  \return 0 on success, or -1 if the surface is not valid.
   343  *  
   344  *  \sa SDL_SetSurfaceScaleMode()
   345  */
   346 extern DECLSPEC int SDLCALL SDL_GetSurfaceScaleMode(SDL_Surface * surface,
   347                                                     int *scaleMode);
   348 
   349 /**
   350  *  Sets the clipping rectangle for the destination surface in a blit.
   351  *  
   352  *  If the clip rectangle is NULL, clipping will be disabled.
   353  *  
   354  *  If the clip rectangle doesn't intersect the surface, the function will
   355  *  return SDL_FALSE and blits will be completely clipped.  Otherwise the
   356  *  function returns SDL_TRUE and blits to the surface will be clipped to
   357  *  the intersection of the surface area and the clipping rectangle.
   358  *  
   359  *  Note that blits are automatically clipped to the edges of the source
   360  *  and destination surfaces.
   361  */
   362 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
   363                                                  const SDL_Rect * rect);
   364 
   365 /**
   366  *  Gets the clipping rectangle for the destination surface in a blit.
   367  *  
   368  *  \c rect must be a pointer to a valid rectangle which will be filled
   369  *  with the correct values.
   370  */
   371 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
   372                                              SDL_Rect * rect);
   373 
   374 /**
   375  *  Creates a new surface of the specified format, and then copies and maps 
   376  *  the given surface to it so the blit of the converted surface will be as 
   377  *  fast as possible.  If this function fails, it returns NULL.
   378  *  
   379  *  The \c flags parameter is passed to SDL_CreateRGBSurface() and has those 
   380  *  semantics.  You can also pass ::SDL_RLEACCEL in the flags parameter and
   381  *  SDL will try to RLE accelerate colorkey and alpha blits in the resulting
   382  *  surface.
   383  */
   384 extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
   385     (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags);
   386 
   387 /**
   388  * \brief Copy a block of pixels of one format to another format
   389  */
   390 extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
   391                                               Uint32 src_format,
   392                                               const void * src, int src_pitch,
   393                                               Uint32 dst_format,
   394                                               void * dst, int dst_pitch);
   395 
   396 /**
   397  *  Draws a point with \c color.
   398  *
   399  *  The color should be a pixel of the format used by the surface, and 
   400  *  can be generated by the SDL_MapRGB() function.
   401  *  
   402  *  \return 0 on success, or -1 on error.
   403  */
   404 extern DECLSPEC int SDLCALL SDL_DrawPoint
   405     (SDL_Surface * dst, int x, int y, Uint32 color);
   406 extern DECLSPEC int SDLCALL SDL_DrawPoints
   407     (SDL_Surface * dst, const SDL_Point * points, int count, Uint32 color);
   408 
   409 /**
   410  *  Blends a point with an RGBA value.
   411  *  
   412  *  \return 0 on success, or -1 on error.
   413  */
   414 extern DECLSPEC int SDLCALL SDL_BlendPoint
   415     (SDL_Surface * dst, int x, int y,
   416      int blendMode, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   417 extern DECLSPEC int SDLCALL SDL_BlendPoints
   418     (SDL_Surface * dst, const SDL_Point * points, int count,
   419      int blendMode, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   420 
   421 /**
   422  *  Draws a line with \c color.
   423  *  
   424  *  The color should be a pixel of the format used by the surface, and 
   425  *  can be generated by the SDL_MapRGB() function.
   426  *  
   427  *  \return 0 on success, or -1 on error.
   428  */
   429 extern DECLSPEC int SDLCALL SDL_DrawLine
   430     (SDL_Surface * dst, int x1, int y1, int x2, int y2, Uint32 color);
   431 extern DECLSPEC int SDLCALL SDL_DrawLines
   432     (SDL_Surface * dst, const SDL_Point * points, int count, Uint32 color);
   433 
   434 /**
   435  *  Blends an RGBA value along a line.
   436  *  
   437  *  \return 0 on success, or -1 on error.
   438  */
   439 extern DECLSPEC int SDLCALL SDL_BlendLine
   440     (SDL_Surface * dst, int x1, int y1, int x2, int y2,
   441      int blendMode, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   442 extern DECLSPEC int SDLCALL SDL_BlendLines
   443     (SDL_Surface * dst, const SDL_Point * points, int count,
   444      int blendMode, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   445 
   446 /**
   447  *  Draws the given rectangle with \c color.
   448  *  
   449  *  If \c rect is NULL, the whole surface will be outlined with \c color.
   450  *  
   451  *  The color should be a pixel of the format used by the surface, and 
   452  *  can be generated by the SDL_MapRGB() function.
   453  *  
   454  *  \return 0 on success, or -1 on error.
   455  */
   456 extern DECLSPEC int SDLCALL SDL_DrawRect
   457     (SDL_Surface * dst, const SDL_Rect * rect, Uint32 color);
   458 extern DECLSPEC int SDLCALL SDL_DrawRects
   459     (SDL_Surface * dst, const SDL_Rect ** rects, int count, Uint32 color);
   460 
   461 /**
   462  *  Blends an RGBA value into the outline of the given rectangle.
   463  *  
   464  *  If \c rect is NULL, the whole surface will have a blended outline.
   465  *  
   466  *  \return 0 on success, or -1 on error.
   467  */
   468 extern DECLSPEC int SDLCALL SDL_BlendRect
   469     (SDL_Surface * dst, const SDL_Rect * rect,
   470      int blendMode, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   471 extern DECLSPEC int SDLCALL SDL_BlendRects
   472     (SDL_Surface * dst, const SDL_Rect ** rects, int count,
   473      int blendMode, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   474 
   475 /**
   476  *  Performs a fast fill of the given rectangle with \c color.
   477  *  
   478  *  If \c rect is NULL, the whole surface will be filled with \c color.
   479  *  
   480  *  The color should be a pixel of the format used by the surface, and 
   481  *  can be generated by the SDL_MapRGB() function.
   482  *  
   483  *  \return 0 on success, or -1 on error.
   484  */
   485 extern DECLSPEC int SDLCALL SDL_FillRect
   486     (SDL_Surface * dst, const SDL_Rect * rect, Uint32 color);
   487 extern DECLSPEC int SDLCALL SDL_FillRects
   488     (SDL_Surface * dst, const SDL_Rect ** rects, int count, Uint32 color);
   489 
   490 /**
   491  *  Blends an RGBA value into the given rectangle.
   492  *  
   493  *  If \c rect is NULL, the whole surface will be blended with the color.
   494  *  
   495  *  \return This function returns 0 on success, or -1 on error.
   496  */
   497 extern DECLSPEC int SDLCALL SDL_BlendFillRect
   498     (SDL_Surface * dst, const SDL_Rect * rect,
   499      int blendMode, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   500 extern DECLSPEC int SDLCALL SDL_BlendFillRects
   501     (SDL_Surface * dst, const SDL_Rect ** rects, int count,
   502      int blendMode, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   503 
   504 #if 0
   505 /**
   506  *  Draws the given circle with \c color.
   507  *  
   508  *  The color should be a pixel of the format used by the surface, and 
   509  *  can be generated by the SDL_MapRGB() function.
   510  *  
   511  *  \return 0 on success, or -1 on error.
   512  */
   513 extern DECLSPEC int SDLCALL SDL_DrawCircle
   514     (SDL_Surface * dst, int x, int y, int radius, Uint32 color);
   515 
   516 /**
   517  *  Blends an RGBA value into the outline of the given circle.
   518  *  
   519  *  \return 0 on success, or -1 on error.
   520  */
   521 extern DECLSPEC int SDLCALL SDL_BlendCircle
   522     (SDL_Surface * dst, int x, int y, int radius,
   523      int blendMode, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   524 
   525 /**
   526  *  Fills the given circle with \c color.
   527  *  
   528  *  The color should be a pixel of the format used by the surface, and 
   529  *  can be generated by the SDL_MapRGB() function.
   530  *  
   531  *  \return 0 on success, or -1 on error.
   532  */
   533 extern DECLSPEC int SDLCALL SDL_FillCircle
   534     (SDL_Surface * dst, int x, int y, int radius, Uint32 color);
   535 
   536 /**
   537  *  Blends an RGBA value into the given circle.
   538  *  
   539  *  \return This function returns 0 on success, or -1 on error.
   540  */
   541 extern DECLSPEC int SDLCALL SDL_BlendFillCircle
   542     (SDL_Surface * dst, int x, int y, int radius,
   543      int blendMode, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   544 
   545 /**
   546  *  Draws the given ellipse with \c color.
   547  *  
   548  *  The color should be a pixel of the format used by the surface, and 
   549  *  can be generated by the SDL_MapRGB() function.
   550  *  
   551  *  \return 0 on success, or -1 on error.
   552  */
   553 extern DECLSPEC int SDLCALL SDL_DrawEllipse
   554     (SDL_Surface * dst, int x, int y, int w, int h, Uint32 color);
   555 
   556 /**
   557  *  Blends an RGBA value into the outline of the given ellipse.
   558  *  
   559  *  \return 0 on success, or -1 on error.
   560  */
   561 extern DECLSPEC int SDLCALL SDL_BlendEllipse
   562     (SDL_Surface * dst, int x, int y, int w, int h,
   563      int blendMode, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   564 
   565 /**
   566  *  Fills the given ellipse with \c color.
   567  *  
   568  *  The color should be a pixel of the format used by the surface, and 
   569  *  can be generated by the SDL_MapRGB() function.
   570  *  
   571  *  \return 0 on success, or -1 on error.
   572  */
   573 extern DECLSPEC int SDLCALL SDL_FillEllipse
   574     (SDL_Surface * dst, int x, int y, int w, int h, Uint32 color);
   575 
   576 /**
   577  *  Blends an RGBA value into the given ellipse.
   578  *  
   579  *  \return This function returns 0 on success, or -1 on error.
   580  */
   581 extern DECLSPEC int SDLCALL SDL_BlendFillEllipse
   582     (SDL_Surface * dst, int x, int y, int w, int h,
   583      int blendMode, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
   584 #endif // 0
   585 
   586 /**
   587  *  Performs a fast blit from the source surface to the destination surface.
   588  *  
   589  *  This assumes that the source and destination rectangles are
   590  *  the same size.  If either \c srcrect or \c dstrect are NULL, the entire
   591  *  surface (\c src or \c dst) is copied.  The final blit rectangles are saved
   592  *  in \c srcrect and \c dstrect after all clipping is performed.
   593  *  
   594  *  \return If the blit is successful, it returns 0, otherwise it returns -1.
   595  *
   596  *  The blit function should not be called on a locked surface.
   597  *
   598  *  The blit semantics for surfaces with and without alpha and colorkey
   599  *  are defined as follows:
   600  *  \verbatim
   601     RGBA->RGB:
   602       SDL_SRCALPHA set:
   603         alpha-blend (using alpha-channel).
   604         SDL_SRCCOLORKEY ignored.
   605       SDL_SRCALPHA not set:
   606         copy RGB.
   607         if SDL_SRCCOLORKEY set, only copy the pixels matching the
   608         RGB values of the source colour key, ignoring alpha in the
   609         comparison.
   610    
   611     RGB->RGBA:
   612       SDL_SRCALPHA set:
   613         alpha-blend (using the source per-surface alpha value);
   614         set destination alpha to opaque.
   615       SDL_SRCALPHA not set:
   616         copy RGB, set destination alpha to source per-surface alpha value.
   617       both:
   618         if SDL_SRCCOLORKEY set, only copy the pixels matching the
   619         source colour key.
   620    
   621     RGBA->RGBA:
   622       SDL_SRCALPHA set:
   623         alpha-blend (using the source alpha channel) the RGB values;
   624         leave destination alpha untouched. [Note: is this correct?]
   625         SDL_SRCCOLORKEY ignored.
   626       SDL_SRCALPHA not set:
   627         copy all of RGBA to the destination.
   628         if SDL_SRCCOLORKEY set, only copy the pixels matching the
   629         RGB values of the source colour key, ignoring alpha in the
   630        comparison.
   631    
   632     RGB->RGB: 
   633       SDL_SRCALPHA set:
   634         alpha-blend (using the source per-surface alpha value).
   635       SDL_SRCALPHA not set:
   636         copy RGB.
   637       both:
   638         if SDL_SRCCOLORKEY set, only copy the pixels matching the
   639         source colour key.
   640     \endverbatim
   641  *  
   642  *  If either of the surfaces were in video memory, and the blit returns -2,
   643  *  the video memory was lost, so it should be reloaded with artwork and 
   644  *  re-blitted:
   645  *  @code
   646  *  while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
   647  *      while ( SDL_LockSurface(image) < 0 )
   648  *          Sleep(10);
   649  *      -- Write image pixels to image->pixels --
   650  *      SDL_UnlockSurface(image);
   651  *  }
   652  *  @endcode
   653  *  
   654  *  This happens under DirectX 5.0 when the system switches away from your
   655  *  fullscreen application.  The lock will also fail until you have access
   656  *  to the video memory again.
   657  *  
   658  *  You should call SDL_BlitSurface() unless you know exactly how SDL
   659  *  blitting works internally and how to use the other blit functions.
   660  */
   661 #define SDL_BlitSurface SDL_UpperBlit
   662 
   663 /**
   664  *  This is the public blit function, SDL_BlitSurface(), and it performs
   665  *  rectangle validation and clipping before passing it to SDL_LowerBlit()
   666  */
   667 extern DECLSPEC int SDLCALL SDL_UpperBlit
   668     (SDL_Surface * src, SDL_Rect * srcrect,
   669      SDL_Surface * dst, SDL_Rect * dstrect);
   670 
   671 /**
   672  *  This is a semi-private blit function and it performs low-level surface
   673  *  blitting only.
   674  */
   675 extern DECLSPEC int SDLCALL SDL_LowerBlit
   676     (SDL_Surface * src, SDL_Rect * srcrect,
   677      SDL_Surface * dst, SDL_Rect * dstrect);
   678 
   679 /**
   680  *  \brief Perform a fast, low quality, stretch blit between two surfaces of the
   681  *         same pixel format.
   682  *  
   683  *  \note This function uses a static buffer, and is not thread-safe.
   684  */
   685 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
   686                                             const SDL_Rect * srcrect,
   687                                             SDL_Surface * dst,
   688                                             const SDL_Rect * dstrect);
   689 
   690 /* Ends C function definitions when using C++ */
   691 #ifdef __cplusplus
   692 /* *INDENT-OFF* */
   693 }
   694 /* *INDENT-ON* */
   695 #endif
   696 #include "close_code.h"
   697 
   698 #endif /* _SDL_surface_h */
   699 
   700 /* vi: set ts=4 sw=4 expandtab: */