include/SDL_surface.h
author Sam Lantinga <slouken@libsdl.org>
Sun, 13 Feb 2011 13:46:10 -0800
changeset 5288 d4381f3b0d1e
parent 5262 b530ef003506
child 5292 22335352d750
permissions -rw-r--r--
A few fixes:
Fixed creating render texture framebuffer.
Removed the need for palette watch, added surface format caching.
Added an SDL_DONTFREE flag so you can't free the window and 1.2 shadow surfaces.
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 1997-2011 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_rwops.h"
    37 
    38 #include "begin_code.h"
    39 /* Set up for C function definitions, even when using C++ */
    40 #ifdef __cplusplus
    41 /* *INDENT-OFF* */
    42 extern "C" {
    43 /* *INDENT-ON* */
    44 #endif
    45 
    46 /**
    47  *  \name Surface flags
    48  *  
    49  *  These are the currently supported flags for the ::SDL_surface.
    50  *  
    51  *  \internal
    52  *  Used internally (read-only).
    53  */
    54 /*@{*/
    55 #define SDL_PREALLOC        0x00000001  /**< Surface uses preallocated memory */
    56 #define SDL_RLEACCEL        0x00000002  /**< Surface is RLE encoded */
    57 #define SDL_DONTFREE        0x00000004  /**< Surface is referenced internally */
    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  *  Sets the clipping rectangle for the destination surface in a blit.
   322  *  
   323  *  If the clip rectangle is NULL, clipping will be disabled.
   324  *  
   325  *  If the clip rectangle doesn't intersect the surface, the function will
   326  *  return SDL_FALSE and blits will be completely clipped.  Otherwise the
   327  *  function returns SDL_TRUE and blits to the surface will be clipped to
   328  *  the intersection of the surface area and the clipping rectangle.
   329  *  
   330  *  Note that blits are automatically clipped to the edges of the source
   331  *  and destination surfaces.
   332  */
   333 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
   334                                                  const SDL_Rect * rect);
   335 
   336 /**
   337  *  Gets the clipping rectangle for the destination surface in a blit.
   338  *  
   339  *  \c rect must be a pointer to a valid rectangle which will be filled
   340  *  with the correct values.
   341  */
   342 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
   343                                              SDL_Rect * rect);
   344 
   345 /**
   346  *  Creates a new surface of the specified format, and then copies and maps 
   347  *  the given surface to it so the blit of the converted surface will be as 
   348  *  fast as possible.  If this function fails, it returns NULL.
   349  *  
   350  *  The \c flags parameter is passed to SDL_CreateRGBSurface() and has those 
   351  *  semantics.  You can also pass ::SDL_RLEACCEL in the flags parameter and
   352  *  SDL will try to RLE accelerate colorkey and alpha blits in the resulting
   353  *  surface.
   354  */
   355 extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
   356     (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags);
   357 
   358 /**
   359  * \brief Copy a block of pixels of one format to another format
   360  */
   361 extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
   362                                               Uint32 src_format,
   363                                               const void * src, int src_pitch,
   364                                               Uint32 dst_format,
   365                                               void * dst, int dst_pitch);
   366 
   367 /**
   368  *  Performs a fast fill of the given rectangle with \c color.
   369  *  
   370  *  If \c rect is NULL, the whole surface will be filled with \c color.
   371  *  
   372  *  The color should be a pixel of the format used by the surface, and 
   373  *  can be generated by the SDL_MapRGB() function.
   374  *  
   375  *  \return 0 on success, or -1 on error.
   376  */
   377 extern DECLSPEC int SDLCALL SDL_FillRect
   378     (SDL_Surface * dst, const SDL_Rect * rect, Uint32 color);
   379 extern DECLSPEC int SDLCALL SDL_FillRects
   380     (SDL_Surface * dst, const SDL_Rect ** rects, int count, Uint32 color);
   381 
   382 /**
   383  *  Performs a fast blit from the source surface to the destination surface.
   384  *  
   385  *  This assumes that the source and destination rectangles are
   386  *  the same size.  If either \c srcrect or \c dstrect are NULL, the entire
   387  *  surface (\c src or \c dst) is copied.  The final blit rectangles are saved
   388  *  in \c srcrect and \c dstrect after all clipping is performed.
   389  *  
   390  *  \return If the blit is successful, it returns 0, otherwise it returns -1.
   391  *
   392  *  The blit function should not be called on a locked surface.
   393  *
   394  *  The blit semantics for surfaces with and without alpha and colorkey
   395  *  are defined as follows:
   396  *  \verbatim
   397     RGBA->RGB:
   398       SDL_SRCALPHA set:
   399         alpha-blend (using alpha-channel).
   400         SDL_SRCCOLORKEY ignored.
   401       SDL_SRCALPHA not set:
   402         copy RGB.
   403         if SDL_SRCCOLORKEY set, only copy the pixels matching the
   404         RGB values of the source colour key, ignoring alpha in the
   405         comparison.
   406    
   407     RGB->RGBA:
   408       SDL_SRCALPHA set:
   409         alpha-blend (using the source per-surface alpha value);
   410         set destination alpha to opaque.
   411       SDL_SRCALPHA not set:
   412         copy RGB, set destination alpha to source per-surface alpha value.
   413       both:
   414         if SDL_SRCCOLORKEY set, only copy the pixels matching the
   415         source colour key.
   416    
   417     RGBA->RGBA:
   418       SDL_SRCALPHA set:
   419         alpha-blend (using the source alpha channel) the RGB values;
   420         leave destination alpha untouched. [Note: is this correct?]
   421         SDL_SRCCOLORKEY ignored.
   422       SDL_SRCALPHA not set:
   423         copy all of RGBA to the destination.
   424         if SDL_SRCCOLORKEY set, only copy the pixels matching the
   425         RGB values of the source colour key, ignoring alpha in the
   426        comparison.
   427    
   428     RGB->RGB: 
   429       SDL_SRCALPHA set:
   430         alpha-blend (using the source per-surface alpha value).
   431       SDL_SRCALPHA not set:
   432         copy RGB.
   433       both:
   434         if SDL_SRCCOLORKEY set, only copy the pixels matching the
   435         source colour key.
   436     \endverbatim
   437  *  
   438  *  You should call SDL_BlitSurface() unless you know exactly how SDL
   439  *  blitting works internally and how to use the other blit functions.
   440  */
   441 #define SDL_BlitSurface SDL_UpperBlit
   442 
   443 /**
   444  *  This is the public blit function, SDL_BlitSurface(), and it performs
   445  *  rectangle validation and clipping before passing it to SDL_LowerBlit()
   446  */
   447 extern DECLSPEC int SDLCALL SDL_UpperBlit
   448     (SDL_Surface * src, const SDL_Rect * srcrect,
   449      SDL_Surface * dst, SDL_Rect * dstrect);
   450 
   451 /**
   452  *  This is a semi-private blit function and it performs low-level surface
   453  *  blitting only.
   454  */
   455 extern DECLSPEC int SDLCALL SDL_LowerBlit
   456     (SDL_Surface * src, SDL_Rect * srcrect,
   457      SDL_Surface * dst, SDL_Rect * dstrect);
   458 
   459 /**
   460  *  \brief Perform a fast, low quality, stretch blit between two surfaces of the
   461  *         same pixel format.
   462  *  
   463  *  \note This function uses a static buffer, and is not thread-safe.
   464  */
   465 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
   466                                             const SDL_Rect * srcrect,
   467                                             SDL_Surface * dst,
   468                                             const SDL_Rect * dstrect);
   469 
   470 /* Ends C function definitions when using C++ */
   471 #ifdef __cplusplus
   472 /* *INDENT-OFF* */
   473 }
   474 /* *INDENT-ON* */
   475 #endif
   476 #include "close_code.h"
   477 
   478 #endif /* _SDL_surface_h */
   479 
   480 /* vi: set ts=4 sw=4 expandtab: */