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