include/SDL_surface.h
author Sam Lantinga <slouken@libsdl.org>
Sat, 01 Oct 2016 11:29:13 -0700
changeset 10404 a990b0da18cc
parent 9998 f67cf37e9cd4
child 10482 f99f58ef8363
permissions -rw-r--r--
Fixed bug 3352 - Adding alpha mask support to SDL_SaveBMP_RW

Simon Hug

The current SDL_SaveBMP_RW function that saves surfaces to a BMP uses an old bitmap header which doesn't officially support alpha channels. Applications just ignore the byte where the alpha is stored. This can easily be extended by using a newer header version and setting the alpha mask.

The attached patch has these changes:

- Extending the description of the function in the SDL_surface.h header with the supported formats.
- Refining when surfaces get stored to a 32-bit BMP. (Must have bit depth of 8 or higher and must have an alpha mask or colorkey.)
- Fixing a small bug that saves 24-bit BGR surfaces with a colorkey in a 24-bit BMP.
- Adding code that switches to the bitmap header version 4 if the surface has an alpha mask or colorkey. (I chose version 4 because Microsoft didn't lose its documentation behind a file cabinet like they did with version 3.)
- Adding a hint that can disable the use of the version 4 header. This is for people that need the legacy header or like the old behavior better. (I'm not sure about the hint name, though. May need changing if there are any rules to that.)
slouken@2275
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@9998
     3
  Copyright (C) 1997-2016 Sam Lantinga <slouken@libsdl.org>
slouken@2275
     4
slouken@5535
     5
  This software is provided 'as-is', without any express or implied
slouken@5535
     6
  warranty.  In no event will the authors be held liable for any damages
slouken@5535
     7
  arising from the use of this software.
slouken@2275
     8
slouken@5535
     9
  Permission is granted to anyone to use this software for any purpose,
slouken@5535
    10
  including commercial applications, and to alter it and redistribute it
slouken@5535
    11
  freely, subject to the following restrictions:
slouken@2275
    12
slouken@5535
    13
  1. The origin of this software must not be misrepresented; you must not
slouken@5535
    14
     claim that you wrote the original software. If you use this software
slouken@5535
    15
     in a product, an acknowledgment in the product documentation would be
slouken@5535
    16
     appreciated but is not required.
slouken@5535
    17
  2. Altered source versions must be plainly marked as such, and must not be
slouken@5535
    18
     misrepresented as being the original software.
slouken@5535
    19
  3. This notice may not be removed or altered from any source distribution.
slouken@2275
    20
*/
slouken@2275
    21
slouken@2275
    22
/**
slouken@3407
    23
 *  \file SDL_surface.h
slouken@7191
    24
 *
philipp@7278
    25
 *  Header file for ::SDL_Surface definition and management functions.
slouken@2275
    26
 */
slouken@2275
    27
slouken@2275
    28
#ifndef _SDL_surface_h
slouken@2275
    29
#define _SDL_surface_h
slouken@2275
    30
slouken@2275
    31
#include "SDL_stdinc.h"
slouken@2275
    32
#include "SDL_pixels.h"
slouken@2275
    33
#include "SDL_rect.h"
slouken@4929
    34
#include "SDL_blendmode.h"
slouken@2275
    35
#include "SDL_rwops.h"
slouken@2275
    36
slouken@2275
    37
#include "begin_code.h"
slouken@2275
    38
/* Set up for C function definitions, even when using C++ */
slouken@2275
    39
#ifdef __cplusplus
slouken@2275
    40
extern "C" {
slouken@2275
    41
#endif
slouken@2275
    42
slouken@3407
    43
/**
slouken@3407
    44
 *  \name Surface flags
slouken@7191
    45
 *
philipp@7278
    46
 *  These are the currently supported flags for the ::SDL_Surface.
slouken@7191
    47
 *
slouken@3407
    48
 *  \internal
slouken@3407
    49
 *  Used internally (read-only).
slouken@3341
    50
 */
gabomdq@7678
    51
/* @{ */
slouken@6257
    52
#define SDL_SWSURFACE       0           /**< Just here for compatibility */
slouken@3341
    53
#define SDL_PREALLOC        0x00000001  /**< Surface uses preallocated memory */
slouken@3341
    54
#define SDL_RLEACCEL        0x00000002  /**< Surface is RLE encoded */
slouken@5288
    55
#define SDL_DONTFREE        0x00000004  /**< Surface is referenced internally */
gabomdq@7678
    56
/* @} *//* Surface flags */
slouken@2275
    57
slouken@3407
    58
/**
slouken@3407
    59
 *  Evaluates to true if the surface needs to be locked before access.
slouken@3407
    60
 */
slouken@7191
    61
#define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0)
slouken@2275
    62
slouken@2275
    63
/**
slouken@3407
    64
 * \brief A collection of pixels used in software blitting.
slouken@2275
    65
 *
slouken@3407
    66
 * \note  This structure should be treated as read-only, except for \c pixels,
slouken@2275
    67
 *        which, if not NULL, contains the raw pixel data for the surface.
slouken@2275
    68
 */
slouken@2275
    69
typedef struct SDL_Surface
slouken@2275
    70
{
slouken@2275
    71
    Uint32 flags;               /**< Read-only */
slouken@2275
    72
    SDL_PixelFormat *format;    /**< Read-only */
slouken@2275
    73
    int w, h;                   /**< Read-only */
slouken@2275
    74
    int pitch;                  /**< Read-only */
slouken@2275
    75
    void *pixels;               /**< Read-write */
slouken@2275
    76
slouken@3708
    77
    /** Application data associated with the surface */
slouken@2275
    78
    void *userdata;             /**< Read-write */
slouken@2275
    79
slouken@3407
    80
    /** information needed for surfaces requiring locks */
slouken@2275
    81
    int locked;                 /**< Read-only */
slouken@2275
    82
    void *lock_data;            /**< Read-only */
slouken@2275
    83
slouken@3407
    84
    /** clipping information */
slouken@2275
    85
    SDL_Rect clip_rect;         /**< Read-only */
slouken@2275
    86
slouken@3407
    87
    /** info for fast blit mapping to other surfaces */
slouken@2275
    88
    struct SDL_BlitMap *map;    /**< Private */
slouken@2275
    89
slouken@3407
    90
    /** Reference count -- used when freeing surface */
slouken@2275
    91
    int refcount;               /**< Read-mostly */
slouken@2275
    92
} SDL_Surface;
slouken@2275
    93
slouken@2275
    94
/**
slouken@3407
    95
 * \brief The type of function used for surface blitting functions.
slouken@2275
    96
 */
slouken@2275
    97
typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
slouken@2275
    98
                         struct SDL_Surface * dst, SDL_Rect * dstrect);
slouken@2275
    99
slouken@3341
   100
/**
slouken@4424
   101
 *  Allocate and free an RGB surface.
slouken@7191
   102
 *
slouken@3407
   103
 *  If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
slouken@3407
   104
 *  If the depth is greater than 8 bits, the pixel format is set using the
slouken@3407
   105
 *  flags '[RGB]mask'.
slouken@7191
   106
 *
slouken@3407
   107
 *  If the function runs out of memory, it will return NULL.
slouken@7191
   108
 *
slouken@3407
   109
 *  \param flags The \c flags are obsolete and should be set to 0.
philipp@7188
   110
 *  \param width The width in pixels of the surface to create.
philipp@7188
   111
 *  \param height The height in pixels of the surface to create.
philipp@7188
   112
 *  \param depth The depth in bits of the surface to create.
philipp@7188
   113
 *  \param Rmask The red mask of the surface to create.
philipp@7188
   114
 *  \param Gmask The green mask of the surface to create.
philipp@7188
   115
 *  \param Bmask The blue mask of the surface to create.
philipp@7188
   116
 *  \param Amask The alpha mask of the surface to create.
slouken@2275
   117
 */
slouken@2275
   118
extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
slouken@2275
   119
    (Uint32 flags, int width, int height, int depth,
slouken@2275
   120
     Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
slouken@2275
   121
extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
slouken@2275
   122
                                                              int width,
slouken@2275
   123
                                                              int height,
slouken@2275
   124
                                                              int depth,
slouken@2275
   125
                                                              int pitch,
slouken@2275
   126
                                                              Uint32 Rmask,
slouken@2275
   127
                                                              Uint32 Gmask,
slouken@2275
   128
                                                              Uint32 Bmask,
slouken@2275
   129
                                                              Uint32 Amask);
slouken@2275
   130
extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
slouken@2275
   131
slouken@2275
   132
/**
slouken@3407
   133
 *  \brief Set the palette used by a surface.
slouken@7191
   134
 *
slouken@3407
   135
 *  \return 0, or -1 if the surface format doesn't use a palette.
slouken@7191
   136
 *
slouken@3407
   137
 *  \note A single palette can be shared with many surfaces.
slouken@2275
   138
 */
slouken@2275
   139
extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
slouken@2275
   140
                                                  SDL_Palette * palette);
slouken@2275
   141
slouken@3341
   142
/**
slouken@3407
   143
 *  \brief Sets up a surface for directly accessing the pixels.
slouken@7191
   144
 *
slouken@3407
   145
 *  Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write
slouken@7191
   146
 *  to and read from \c surface->pixels, using the pixel format stored in
slouken@7191
   147
 *  \c surface->format.  Once you are done accessing the surface, you should
slouken@3407
   148
 *  use SDL_UnlockSurface() to release it.
slouken@7191
   149
 *
slouken@3407
   150
 *  Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
slouken@3407
   151
 *  to 0, then you can read and write to the surface at any time, and the
slouken@3407
   152
 *  pixel format of the surface will not change.
slouken@7191
   153
 *
slouken@3407
   154
 *  No operating system or library calls should be made between lock/unlock
slouken@3407
   155
 *  pairs, as critical system locks may be held during this time.
slouken@7191
   156
 *
slouken@3407
   157
 *  SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
slouken@7191
   158
 *
slouken@3407
   159
 *  \sa SDL_UnlockSurface()
slouken@2275
   160
 */
slouken@2275
   161
extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
slouken@3341
   162
/** \sa SDL_LockSurface() */
slouken@2275
   163
extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
slouken@2275
   164
slouken@3341
   165
/**
slouken@4971
   166
 *  Load a surface from a seekable SDL data stream (memory or file).
slouken@7191
   167
 *
slouken@4971
   168
 *  If \c freesrc is non-zero, the stream will be closed after being read.
slouken@7191
   169
 *
slouken@3407
   170
 *  The new surface should be freed with SDL_FreeSurface().
slouken@7191
   171
 *
slouken@3407
   172
 *  \return the new surface, or NULL if there was an error.
slouken@2275
   173
 */
slouken@2275
   174
extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
slouken@2275
   175
                                                    int freesrc);
slouken@2275
   176
slouken@3407
   177
/**
slouken@3407
   178
 *  Load a surface from a file.
slouken@7191
   179
 *
slouken@3407
   180
 *  Convenience macro.
slouken@3407
   181
 */
slouken@7191
   182
#define SDL_LoadBMP(file)   SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
slouken@2275
   183
slouken@3341
   184
/**
slouken@4971
   185
 *  Save a surface to a seekable SDL data stream (memory or file).
slouken@7191
   186
 *
slouken@10404
   187
 *  Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the
slouken@10404
   188
 *  BMP directly. Other RGB formats with 8-bit or higher get converted to a
slouken@10404
   189
 *  24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit
slouken@10404
   190
 *  surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
slouken@10404
   191
 *  not supported.
slouken@10404
   192
 *
slouken@4971
   193
 *  If \c freedst is non-zero, the stream will be closed after being written.
slouken@7191
   194
 *
slouken@3407
   195
 *  \return 0 if successful or -1 if there was an error.
slouken@2275
   196
 */
slouken@2275
   197
extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
slouken@2275
   198
    (SDL_Surface * surface, SDL_RWops * dst, int freedst);
slouken@2275
   199
slouken@7191
   200
/**
slouken@3407
   201
 *  Save a surface to a file.
slouken@7191
   202
 *
slouken@3407
   203
 *  Convenience macro.
slouken@3407
   204
 */
slouken@2275
   205
#define SDL_SaveBMP(surface, file) \
slouken@7191
   206
        SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
slouken@2275
   207
slouken@3341
   208
/**
slouken@3407
   209
 *  \brief Sets the RLE acceleration hint for a surface.
slouken@7191
   210
 *
slouken@3407
   211
 *  \return 0 on success, or -1 if the surface is not valid
slouken@7191
   212
 *
slouken@3407
   213
 *  \note If RLE is enabled, colorkey and alpha blending blits are much faster,
slouken@3407
   214
 *        but the surface must be locked before directly accessing the pixels.
slouken@2275
   215
 */
slouken@2275
   216
extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface,
slouken@2275
   217
                                              int flag);
slouken@2275
   218
slouken@3341
   219
/**
slouken@3407
   220
 *  \brief Sets the color key (transparent pixel) in a blittable surface.
slouken@7191
   221
 *
slouken@3407
   222
 *  \param surface The surface to update
slouken@6257
   223
 *  \param flag Non-zero to enable colorkey and 0 to disable colorkey
slouken@3407
   224
 *  \param key The transparent pixel in the native surface format
slouken@7191
   225
 *
slouken@3407
   226
 *  \return 0 on success, or -1 if the surface is not valid
slouken@6257
   227
 *
slouken@6257
   228
 *  You can pass SDL_RLEACCEL to enable RLE accelerated blits.
slouken@2275
   229
 */
slouken@2275
   230
extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface,
slouken@3560
   231
                                            int flag, Uint32 key);
slouken@2275
   232
slouken@3341
   233
/**
slouken@3550
   234
 *  \brief Gets the color key (transparent pixel) in a blittable surface.
slouken@7191
   235
 *
slouken@3407
   236
 *  \param surface The surface to update
slouken@7191
   237
 *  \param key A pointer filled in with the transparent pixel in the native
slouken@3407
   238
 *             surface format
slouken@7191
   239
 *
slouken@7191
   240
 *  \return 0 on success, or -1 if the surface is not valid or colorkey is not
slouken@3407
   241
 *          enabled.
slouken@3103
   242
 */
slouken@3103
   243
extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface,
slouken@3103
   244
                                            Uint32 * key);
slouken@3103
   245
slouken@2275
   246
/**
slouken@3407
   247
 *  \brief Set an additional color value used in blit operations.
slouken@7191
   248
 *
slouken@3407
   249
 *  \param surface The surface to update.
slouken@4971
   250
 *  \param r The red color value multiplied into blit operations.
slouken@4971
   251
 *  \param g The green color value multiplied into blit operations.
slouken@4971
   252
 *  \param b The blue color value multiplied into blit operations.
slouken@7191
   253
 *
slouken@3407
   254
 *  \return 0 on success, or -1 if the surface is not valid.
slouken@7191
   255
 *
slouken@3407
   256
 *  \sa SDL_GetSurfaceColorMod()
slouken@2275
   257
 */
slouken@2275
   258
extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface,
slouken@2275
   259
                                                   Uint8 r, Uint8 g, Uint8 b);
slouken@2275
   260
slouken@2275
   261
slouken@2275
   262
/**
slouken@3407
   263
 *  \brief Get the additional color value used in blit operations.
slouken@7191
   264
 *
slouken@3407
   265
 *  \param surface The surface to query.
slouken@4971
   266
 *  \param r A pointer filled in with the current red color value.
slouken@4971
   267
 *  \param g A pointer filled in with the current green color value.
slouken@4971
   268
 *  \param b A pointer filled in with the current blue color value.
slouken@7191
   269
 *
slouken@3407
   270
 *  \return 0 on success, or -1 if the surface is not valid.
slouken@7191
   271
 *
slouken@3407
   272
 *  \sa SDL_SetSurfaceColorMod()
slouken@2275
   273
 */
slouken@2275
   274
extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface,
slouken@2275
   275
                                                   Uint8 * r, Uint8 * g,
slouken@2275
   276
                                                   Uint8 * b);
slouken@2275
   277
slouken@2275
   278
/**
slouken@3407
   279
 *  \brief Set an additional alpha value used in blit operations.
slouken@7191
   280
 *
slouken@3407
   281
 *  \param surface The surface to update.
slouken@4971
   282
 *  \param alpha The alpha value multiplied into blit operations.
slouken@7191
   283
 *
slouken@3407
   284
 *  \return 0 on success, or -1 if the surface is not valid.
slouken@7191
   285
 *
slouken@3407
   286
 *  \sa SDL_GetSurfaceAlphaMod()
slouken@2275
   287
 */
slouken@2275
   288
extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface,
slouken@2275
   289
                                                   Uint8 alpha);
slouken@2275
   290
slouken@2275
   291
/**
slouken@3407
   292
 *  \brief Get the additional alpha value used in blit operations.
slouken@7191
   293
 *
slouken@3407
   294
 *  \param surface The surface to query.
slouken@4971
   295
 *  \param alpha A pointer filled in with the current alpha value.
slouken@7191
   296
 *
slouken@3407
   297
 *  \return 0 on success, or -1 if the surface is not valid.
slouken@7191
   298
 *
slouken@3407
   299
 *  \sa SDL_SetSurfaceAlphaMod()
slouken@2275
   300
 */
slouken@2275
   301
extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface,
slouken@2275
   302
                                                   Uint8 * alpha);
slouken@2275
   303
slouken@2275
   304
/**
slouken@3407
   305
 *  \brief Set the blend mode used for blit operations.
slouken@7191
   306
 *
slouken@3407
   307
 *  \param surface The surface to update.
slouken@3407
   308
 *  \param blendMode ::SDL_BlendMode to use for blit blending.
slouken@7191
   309
 *
slouken@3407
   310
 *  \return 0 on success, or -1 if the parameters are not valid.
slouken@7191
   311
 *
slouken@3407
   312
 *  \sa SDL_GetSurfaceBlendMode()
slouken@2275
   313
 */
slouken@2275
   314
extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface,
slouken@4929
   315
                                                    SDL_BlendMode blendMode);
slouken@2275
   316
slouken@2275
   317
/**
slouken@3407
   318
 *  \brief Get the blend mode used for blit operations.
slouken@7191
   319
 *
slouken@3407
   320
 *  \param surface   The surface to query.
slouken@3407
   321
 *  \param blendMode A pointer filled in with the current blend mode.
slouken@7191
   322
 *
slouken@3407
   323
 *  \return 0 on success, or -1 if the surface is not valid.
slouken@7191
   324
 *
slouken@3407
   325
 *  \sa SDL_SetSurfaceBlendMode()
slouken@2275
   326
 */
slouken@2275
   327
extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
slouken@4929
   328
                                                    SDL_BlendMode *blendMode);
slouken@2275
   329
slouken@2275
   330
/**
slouken@3407
   331
 *  Sets the clipping rectangle for the destination surface in a blit.
slouken@7191
   332
 *
slouken@3407
   333
 *  If the clip rectangle is NULL, clipping will be disabled.
slouken@7191
   334
 *
slouken@3407
   335
 *  If the clip rectangle doesn't intersect the surface, the function will
slouken@3407
   336
 *  return SDL_FALSE and blits will be completely clipped.  Otherwise the
slouken@3407
   337
 *  function returns SDL_TRUE and blits to the surface will be clipped to
slouken@3407
   338
 *  the intersection of the surface area and the clipping rectangle.
slouken@7191
   339
 *
slouken@3407
   340
 *  Note that blits are automatically clipped to the edges of the source
slouken@3407
   341
 *  and destination surfaces.
slouken@2275
   342
 */
slouken@2275
   343
extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
slouken@2275
   344
                                                 const SDL_Rect * rect);
slouken@2275
   345
slouken@3341
   346
/**
slouken@3407
   347
 *  Gets the clipping rectangle for the destination surface in a blit.
slouken@7191
   348
 *
slouken@3407
   349
 *  \c rect must be a pointer to a valid rectangle which will be filled
slouken@3407
   350
 *  with the correct values.
slouken@2275
   351
 */
slouken@2275
   352
extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
slouken@2275
   353
                                             SDL_Rect * rect);
slouken@2275
   354
slouken@3341
   355
/**
slouken@7191
   356
 *  Creates a new surface of the specified format, and then copies and maps
slouken@7191
   357
 *  the given surface to it so the blit of the converted surface will be as
slouken@3407
   358
 *  fast as possible.  If this function fails, it returns NULL.
slouken@7191
   359
 *
slouken@7191
   360
 *  The \c flags parameter is passed to SDL_CreateRGBSurface() and has those
slouken@3407
   361
 *  semantics.  You can also pass ::SDL_RLEACCEL in the flags parameter and
slouken@3407
   362
 *  SDL will try to RLE accelerate colorkey and alpha blits in the resulting
slouken@3407
   363
 *  surface.
slouken@2275
   364
 */
slouken@2275
   365
extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
icculus@7725
   366
    (SDL_Surface * src, const SDL_PixelFormat * fmt, Uint32 flags);
slouken@5375
   367
extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat
slouken@5375
   368
    (SDL_Surface * src, Uint32 pixel_format, Uint32 flags);
slouken@2275
   369
slouken@3341
   370
/**
slouken@3434
   371
 * \brief Copy a block of pixels of one format to another format
slouken@7191
   372
 *
slouken@6041
   373
 *  \return 0 on success, or -1 if there was an error
slouken@3434
   374
 */
slouken@3434
   375
extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
slouken@3434
   376
                                              Uint32 src_format,
slouken@3434
   377
                                              const void * src, int src_pitch,
slouken@3434
   378
                                              Uint32 dst_format,
slouken@3434
   379
                                              void * dst, int dst_pitch);
slouken@3434
   380
slouken@3434
   381
/**
slouken@3407
   382
 *  Performs a fast fill of the given rectangle with \c color.
slouken@7191
   383
 *
slouken@3536
   384
 *  If \c rect is NULL, the whole surface will be filled with \c color.
slouken@7191
   385
 *
slouken@7191
   386
 *  The color should be a pixel of the format used by the surface, and
slouken@3407
   387
 *  can be generated by the SDL_MapRGB() function.
slouken@7191
   388
 *
slouken@3407
   389
 *  \return 0 on success, or -1 on error.
slouken@2275
   390
 */
slouken@2275
   391
extern DECLSPEC int SDLCALL SDL_FillRect
slouken@3536
   392
    (SDL_Surface * dst, const SDL_Rect * rect, Uint32 color);
slouken@3536
   393
extern DECLSPEC int SDLCALL SDL_FillRects
slouken@5297
   394
    (SDL_Surface * dst, const SDL_Rect * rects, int count, Uint32 color);
slouken@2275
   395
slouken@3341
   396
/**
slouken@3407
   397
 *  Performs a fast blit from the source surface to the destination surface.
slouken@7191
   398
 *
slouken@3407
   399
 *  This assumes that the source and destination rectangles are
slouken@3407
   400
 *  the same size.  If either \c srcrect or \c dstrect are NULL, the entire
slouken@3407
   401
 *  surface (\c src or \c dst) is copied.  The final blit rectangles are saved
slouken@3407
   402
 *  in \c srcrect and \c dstrect after all clipping is performed.
slouken@7191
   403
 *
slouken@3407
   404
 *  \return If the blit is successful, it returns 0, otherwise it returns -1.
slouken@2275
   405
 *
slouken@3407
   406
 *  The blit function should not be called on a locked surface.
slouken@2275
   407
 *
slouken@7502
   408
 *  The blit semantics for surfaces with and without blending and colorkey
slouken@3407
   409
 *  are defined as follows:
slouken@3407
   410
 *  \verbatim
slouken@3407
   411
    RGBA->RGB:
slouken@7502
   412
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
slouken@7502
   413
        alpha-blend (using the source alpha-channel and per-surface alpha)
slouken@3407
   414
        SDL_SRCCOLORKEY ignored.
slouken@7502
   415
      Source surface blend mode set to SDL_BLENDMODE_NONE:
slouken@3407
   416
        copy RGB.
slouken@3407
   417
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
philipp@7125
   418
        RGB values of the source color key, ignoring alpha in the
slouken@3407
   419
        comparison.
slouken@7191
   420
slouken@3407
   421
    RGB->RGBA:
slouken@7502
   422
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
slouken@7502
   423
        alpha-blend (using the source per-surface alpha)
slouken@7502
   424
      Source surface blend mode set to SDL_BLENDMODE_NONE:
slouken@3407
   425
        copy RGB, set destination alpha to source per-surface alpha value.
slouken@3407
   426
      both:
slouken@3407
   427
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
philipp@7125
   428
        source color key.
slouken@7191
   429
slouken@3407
   430
    RGBA->RGBA:
slouken@7502
   431
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
slouken@7502
   432
        alpha-blend (using the source alpha-channel and per-surface alpha)
slouken@3407
   433
        SDL_SRCCOLORKEY ignored.
slouken@7502
   434
      Source surface blend mode set to SDL_BLENDMODE_NONE:
slouken@3407
   435
        copy all of RGBA to the destination.
slouken@3407
   436
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
philipp@7125
   437
        RGB values of the source color key, ignoring alpha in the
slouken@7502
   438
        comparison.
slouken@7191
   439
slouken@7191
   440
    RGB->RGB:
slouken@7502
   441
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
slouken@7502
   442
        alpha-blend (using the source per-surface alpha)
slouken@7502
   443
      Source surface blend mode set to SDL_BLENDMODE_NONE:
slouken@3407
   444
        copy RGB.
slouken@3407
   445
      both:
slouken@3407
   446
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
philipp@7125
   447
        source color key.
slouken@3407
   448
    \endverbatim
slouken@7191
   449
 *
slouken@3407
   450
 *  You should call SDL_BlitSurface() unless you know exactly how SDL
slouken@3407
   451
 *  blitting works internally and how to use the other blit functions.
slouken@2275
   452
 */
slouken@2275
   453
#define SDL_BlitSurface SDL_UpperBlit
slouken@2275
   454
slouken@3407
   455
/**
slouken@3407
   456
 *  This is the public blit function, SDL_BlitSurface(), and it performs
slouken@3341
   457
 *  rectangle validation and clipping before passing it to SDL_LowerBlit()
slouken@3341
   458
 */
slouken@2275
   459
extern DECLSPEC int SDLCALL SDL_UpperBlit
slouken@4949
   460
    (SDL_Surface * src, const SDL_Rect * srcrect,
slouken@2275
   461
     SDL_Surface * dst, SDL_Rect * dstrect);
slouken@3341
   462
slouken@3407
   463
/**
slouken@3407
   464
 *  This is a semi-private blit function and it performs low-level surface
slouken@3341
   465
 *  blitting only.
slouken@3341
   466
 */
slouken@2275
   467
extern DECLSPEC int SDLCALL SDL_LowerBlit
slouken@2275
   468
    (SDL_Surface * src, SDL_Rect * srcrect,
slouken@2275
   469
     SDL_Surface * dst, SDL_Rect * dstrect);
slouken@2275
   470
slouken@2275
   471
/**
slouken@3407
   472
 *  \brief Perform a fast, low quality, stretch blit between two surfaces of the
slouken@3407
   473
 *         same pixel format.
slouken@7191
   474
 *
slouken@3407
   475
 *  \note This function uses a static buffer, and is not thread-safe.
slouken@2275
   476
 */
slouken@2275
   477
extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
slouken@2828
   478
                                            const SDL_Rect * srcrect,
slouken@2275
   479
                                            SDL_Surface * dst,
slouken@2828
   480
                                            const SDL_Rect * dstrect);
slouken@2275
   481
ken@5499
   482
#define SDL_BlitScaled SDL_UpperBlitScaled
ken@5499
   483
ken@5296
   484
/**
ken@5499
   485
 *  This is the public scaled blit function, SDL_BlitScaled(), and it performs
ken@5499
   486
 *  rectangle validation and clipping before passing it to SDL_LowerBlitScaled()
ken@5296
   487
 */
ken@5499
   488
extern DECLSPEC int SDLCALL SDL_UpperBlitScaled
ken@5296
   489
    (SDL_Surface * src, const SDL_Rect * srcrect,
ken@5499
   490
    SDL_Surface * dst, SDL_Rect * dstrect);
ken@5499
   491
ken@5499
   492
/**
ken@5499
   493
 *  This is a semi-private blit function and it performs low-level surface
ken@5499
   494
 *  scaled blitting only.
ken@5499
   495
 */
ken@5499
   496
extern DECLSPEC int SDLCALL SDL_LowerBlitScaled
ken@5499
   497
    (SDL_Surface * src, SDL_Rect * srcrect,
ken@5499
   498
    SDL_Surface * dst, SDL_Rect * dstrect);
ken@5296
   499
ken@5296
   500
slouken@2275
   501
/* Ends C function definitions when using C++ */
slouken@2275
   502
#ifdef __cplusplus
slouken@2275
   503
}
slouken@2275
   504
#endif
slouken@2275
   505
#include "close_code.h"
slouken@2275
   506
slouken@2275
   507
#endif /* _SDL_surface_h */
slouken@2275
   508
slouken@2275
   509
/* vi: set ts=4 sw=4 expandtab: */