include/SDL_surface.h
author Ryan C. Gordon <icculus@icculus.org>
Thu, 28 May 2015 01:54:52 -0400
changeset 9671 0e1f57b051f4
parent 9619 b94b6d0bff0f
child 9998 f67cf37e9cd4
permissions -rw-r--r--
Windows GetBasePath should use GetModuleFileNameExW() and check for overflows.

Apparently you might get strange paths from GetModuleFileName(), such as
short path names or UNC filenames, so this avoids that problem. Since you have
to tapdance with linking different libraries and defining macros depending on
what Windows you plan to target, we dynamically load the API we need, which
works on all versions of Windows (on Win7, it'll load a compatibility wrapper
for the newer API location).

What a mess.

This also now does the right thing if there isn't enough space to store the
path, looping with a larger allocated buffer each try.

Fixes Bugzilla #2435.
slouken@2275
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@9619
     3
  Copyright (C) 1997-2015 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@4971
   187
 *  If \c freedst is non-zero, the stream will be closed after being written.
slouken@7191
   188
 *
slouken@3407
   189
 *  \return 0 if successful or -1 if there was an error.
slouken@2275
   190
 */
slouken@2275
   191
extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
slouken@2275
   192
    (SDL_Surface * surface, SDL_RWops * dst, int freedst);
slouken@2275
   193
slouken@7191
   194
/**
slouken@3407
   195
 *  Save a surface to a file.
slouken@7191
   196
 *
slouken@3407
   197
 *  Convenience macro.
slouken@3407
   198
 */
slouken@2275
   199
#define SDL_SaveBMP(surface, file) \
slouken@7191
   200
        SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
slouken@2275
   201
slouken@3341
   202
/**
slouken@3407
   203
 *  \brief Sets the RLE acceleration hint for a surface.
slouken@7191
   204
 *
slouken@3407
   205
 *  \return 0 on success, or -1 if the surface is not valid
slouken@7191
   206
 *
slouken@3407
   207
 *  \note If RLE is enabled, colorkey and alpha blending blits are much faster,
slouken@3407
   208
 *        but the surface must be locked before directly accessing the pixels.
slouken@2275
   209
 */
slouken@2275
   210
extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface,
slouken@2275
   211
                                              int flag);
slouken@2275
   212
slouken@3341
   213
/**
slouken@3407
   214
 *  \brief Sets the color key (transparent pixel) in a blittable surface.
slouken@7191
   215
 *
slouken@3407
   216
 *  \param surface The surface to update
slouken@6257
   217
 *  \param flag Non-zero to enable colorkey and 0 to disable colorkey
slouken@3407
   218
 *  \param key The transparent pixel in the native surface format
slouken@7191
   219
 *
slouken@3407
   220
 *  \return 0 on success, or -1 if the surface is not valid
slouken@6257
   221
 *
slouken@6257
   222
 *  You can pass SDL_RLEACCEL to enable RLE accelerated blits.
slouken@2275
   223
 */
slouken@2275
   224
extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface,
slouken@3560
   225
                                            int flag, Uint32 key);
slouken@2275
   226
slouken@3341
   227
/**
slouken@3550
   228
 *  \brief Gets the color key (transparent pixel) in a blittable surface.
slouken@7191
   229
 *
slouken@3407
   230
 *  \param surface The surface to update
slouken@7191
   231
 *  \param key A pointer filled in with the transparent pixel in the native
slouken@3407
   232
 *             surface format
slouken@7191
   233
 *
slouken@7191
   234
 *  \return 0 on success, or -1 if the surface is not valid or colorkey is not
slouken@3407
   235
 *          enabled.
slouken@3103
   236
 */
slouken@3103
   237
extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface,
slouken@3103
   238
                                            Uint32 * key);
slouken@3103
   239
slouken@2275
   240
/**
slouken@3407
   241
 *  \brief Set an additional color value used in blit operations.
slouken@7191
   242
 *
slouken@3407
   243
 *  \param surface The surface to update.
slouken@4971
   244
 *  \param r The red color value multiplied into blit operations.
slouken@4971
   245
 *  \param g The green color value multiplied into blit operations.
slouken@4971
   246
 *  \param b The blue color value multiplied into blit operations.
slouken@7191
   247
 *
slouken@3407
   248
 *  \return 0 on success, or -1 if the surface is not valid.
slouken@7191
   249
 *
slouken@3407
   250
 *  \sa SDL_GetSurfaceColorMod()
slouken@2275
   251
 */
slouken@2275
   252
extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface,
slouken@2275
   253
                                                   Uint8 r, Uint8 g, Uint8 b);
slouken@2275
   254
slouken@2275
   255
slouken@2275
   256
/**
slouken@3407
   257
 *  \brief Get the additional color value used in blit operations.
slouken@7191
   258
 *
slouken@3407
   259
 *  \param surface The surface to query.
slouken@4971
   260
 *  \param r A pointer filled in with the current red color value.
slouken@4971
   261
 *  \param g A pointer filled in with the current green color value.
slouken@4971
   262
 *  \param b A pointer filled in with the current blue color value.
slouken@7191
   263
 *
slouken@3407
   264
 *  \return 0 on success, or -1 if the surface is not valid.
slouken@7191
   265
 *
slouken@3407
   266
 *  \sa SDL_SetSurfaceColorMod()
slouken@2275
   267
 */
slouken@2275
   268
extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface,
slouken@2275
   269
                                                   Uint8 * r, Uint8 * g,
slouken@2275
   270
                                                   Uint8 * b);
slouken@2275
   271
slouken@2275
   272
/**
slouken@3407
   273
 *  \brief Set an additional alpha value used in blit operations.
slouken@7191
   274
 *
slouken@3407
   275
 *  \param surface The surface to update.
slouken@4971
   276
 *  \param alpha The alpha value multiplied into blit operations.
slouken@7191
   277
 *
slouken@3407
   278
 *  \return 0 on success, or -1 if the surface is not valid.
slouken@7191
   279
 *
slouken@3407
   280
 *  \sa SDL_GetSurfaceAlphaMod()
slouken@2275
   281
 */
slouken@2275
   282
extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface,
slouken@2275
   283
                                                   Uint8 alpha);
slouken@2275
   284
slouken@2275
   285
/**
slouken@3407
   286
 *  \brief Get the additional alpha value used in blit operations.
slouken@7191
   287
 *
slouken@3407
   288
 *  \param surface The surface to query.
slouken@4971
   289
 *  \param alpha A pointer filled in with the current alpha value.
slouken@7191
   290
 *
slouken@3407
   291
 *  \return 0 on success, or -1 if the surface is not valid.
slouken@7191
   292
 *
slouken@3407
   293
 *  \sa SDL_SetSurfaceAlphaMod()
slouken@2275
   294
 */
slouken@2275
   295
extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface,
slouken@2275
   296
                                                   Uint8 * alpha);
slouken@2275
   297
slouken@2275
   298
/**
slouken@3407
   299
 *  \brief Set the blend mode used for blit operations.
slouken@7191
   300
 *
slouken@3407
   301
 *  \param surface The surface to update.
slouken@3407
   302
 *  \param blendMode ::SDL_BlendMode to use for blit blending.
slouken@7191
   303
 *
slouken@3407
   304
 *  \return 0 on success, or -1 if the parameters are not valid.
slouken@7191
   305
 *
slouken@3407
   306
 *  \sa SDL_GetSurfaceBlendMode()
slouken@2275
   307
 */
slouken@2275
   308
extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface,
slouken@4929
   309
                                                    SDL_BlendMode blendMode);
slouken@2275
   310
slouken@2275
   311
/**
slouken@3407
   312
 *  \brief Get the blend mode used for blit operations.
slouken@7191
   313
 *
slouken@3407
   314
 *  \param surface   The surface to query.
slouken@3407
   315
 *  \param blendMode A pointer filled in with the current blend mode.
slouken@7191
   316
 *
slouken@3407
   317
 *  \return 0 on success, or -1 if the surface is not valid.
slouken@7191
   318
 *
slouken@3407
   319
 *  \sa SDL_SetSurfaceBlendMode()
slouken@2275
   320
 */
slouken@2275
   321
extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
slouken@4929
   322
                                                    SDL_BlendMode *blendMode);
slouken@2275
   323
slouken@2275
   324
/**
slouken@3407
   325
 *  Sets the clipping rectangle for the destination surface in a blit.
slouken@7191
   326
 *
slouken@3407
   327
 *  If the clip rectangle is NULL, clipping will be disabled.
slouken@7191
   328
 *
slouken@3407
   329
 *  If the clip rectangle doesn't intersect the surface, the function will
slouken@3407
   330
 *  return SDL_FALSE and blits will be completely clipped.  Otherwise the
slouken@3407
   331
 *  function returns SDL_TRUE and blits to the surface will be clipped to
slouken@3407
   332
 *  the intersection of the surface area and the clipping rectangle.
slouken@7191
   333
 *
slouken@3407
   334
 *  Note that blits are automatically clipped to the edges of the source
slouken@3407
   335
 *  and destination surfaces.
slouken@2275
   336
 */
slouken@2275
   337
extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
slouken@2275
   338
                                                 const SDL_Rect * rect);
slouken@2275
   339
slouken@3341
   340
/**
slouken@3407
   341
 *  Gets the clipping rectangle for the destination surface in a blit.
slouken@7191
   342
 *
slouken@3407
   343
 *  \c rect must be a pointer to a valid rectangle which will be filled
slouken@3407
   344
 *  with the correct values.
slouken@2275
   345
 */
slouken@2275
   346
extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
slouken@2275
   347
                                             SDL_Rect * rect);
slouken@2275
   348
slouken@3341
   349
/**
slouken@7191
   350
 *  Creates a new surface of the specified format, and then copies and maps
slouken@7191
   351
 *  the given surface to it so the blit of the converted surface will be as
slouken@3407
   352
 *  fast as possible.  If this function fails, it returns NULL.
slouken@7191
   353
 *
slouken@7191
   354
 *  The \c flags parameter is passed to SDL_CreateRGBSurface() and has those
slouken@3407
   355
 *  semantics.  You can also pass ::SDL_RLEACCEL in the flags parameter and
slouken@3407
   356
 *  SDL will try to RLE accelerate colorkey and alpha blits in the resulting
slouken@3407
   357
 *  surface.
slouken@2275
   358
 */
slouken@2275
   359
extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
icculus@7725
   360
    (SDL_Surface * src, const SDL_PixelFormat * fmt, Uint32 flags);
slouken@5375
   361
extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat
slouken@5375
   362
    (SDL_Surface * src, Uint32 pixel_format, Uint32 flags);
slouken@2275
   363
slouken@3341
   364
/**
slouken@3434
   365
 * \brief Copy a block of pixels of one format to another format
slouken@7191
   366
 *
slouken@6041
   367
 *  \return 0 on success, or -1 if there was an error
slouken@3434
   368
 */
slouken@3434
   369
extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
slouken@3434
   370
                                              Uint32 src_format,
slouken@3434
   371
                                              const void * src, int src_pitch,
slouken@3434
   372
                                              Uint32 dst_format,
slouken@3434
   373
                                              void * dst, int dst_pitch);
slouken@3434
   374
slouken@3434
   375
/**
slouken@3407
   376
 *  Performs a fast fill of the given rectangle with \c color.
slouken@7191
   377
 *
slouken@3536
   378
 *  If \c rect is NULL, the whole surface will be filled with \c color.
slouken@7191
   379
 *
slouken@7191
   380
 *  The color should be a pixel of the format used by the surface, and
slouken@3407
   381
 *  can be generated by the SDL_MapRGB() function.
slouken@7191
   382
 *
slouken@3407
   383
 *  \return 0 on success, or -1 on error.
slouken@2275
   384
 */
slouken@2275
   385
extern DECLSPEC int SDLCALL SDL_FillRect
slouken@3536
   386
    (SDL_Surface * dst, const SDL_Rect * rect, Uint32 color);
slouken@3536
   387
extern DECLSPEC int SDLCALL SDL_FillRects
slouken@5297
   388
    (SDL_Surface * dst, const SDL_Rect * rects, int count, Uint32 color);
slouken@2275
   389
slouken@3341
   390
/**
slouken@3407
   391
 *  Performs a fast blit from the source surface to the destination surface.
slouken@7191
   392
 *
slouken@3407
   393
 *  This assumes that the source and destination rectangles are
slouken@3407
   394
 *  the same size.  If either \c srcrect or \c dstrect are NULL, the entire
slouken@3407
   395
 *  surface (\c src or \c dst) is copied.  The final blit rectangles are saved
slouken@3407
   396
 *  in \c srcrect and \c dstrect after all clipping is performed.
slouken@7191
   397
 *
slouken@3407
   398
 *  \return If the blit is successful, it returns 0, otherwise it returns -1.
slouken@2275
   399
 *
slouken@3407
   400
 *  The blit function should not be called on a locked surface.
slouken@2275
   401
 *
slouken@7502
   402
 *  The blit semantics for surfaces with and without blending and colorkey
slouken@3407
   403
 *  are defined as follows:
slouken@3407
   404
 *  \verbatim
slouken@3407
   405
    RGBA->RGB:
slouken@7502
   406
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
slouken@7502
   407
        alpha-blend (using the source alpha-channel and per-surface alpha)
slouken@3407
   408
        SDL_SRCCOLORKEY ignored.
slouken@7502
   409
      Source surface blend mode set to SDL_BLENDMODE_NONE:
slouken@3407
   410
        copy RGB.
slouken@3407
   411
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
philipp@7125
   412
        RGB values of the source color key, ignoring alpha in the
slouken@3407
   413
        comparison.
slouken@7191
   414
slouken@3407
   415
    RGB->RGBA:
slouken@7502
   416
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
slouken@7502
   417
        alpha-blend (using the source per-surface alpha)
slouken@7502
   418
      Source surface blend mode set to SDL_BLENDMODE_NONE:
slouken@3407
   419
        copy RGB, set destination alpha to source per-surface alpha value.
slouken@3407
   420
      both:
slouken@3407
   421
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
philipp@7125
   422
        source color key.
slouken@7191
   423
slouken@3407
   424
    RGBA->RGBA:
slouken@7502
   425
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
slouken@7502
   426
        alpha-blend (using the source alpha-channel and per-surface alpha)
slouken@3407
   427
        SDL_SRCCOLORKEY ignored.
slouken@7502
   428
      Source surface blend mode set to SDL_BLENDMODE_NONE:
slouken@3407
   429
        copy all of RGBA to the destination.
slouken@3407
   430
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
philipp@7125
   431
        RGB values of the source color key, ignoring alpha in the
slouken@7502
   432
        comparison.
slouken@7191
   433
slouken@7191
   434
    RGB->RGB:
slouken@7502
   435
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
slouken@7502
   436
        alpha-blend (using the source per-surface alpha)
slouken@7502
   437
      Source surface blend mode set to SDL_BLENDMODE_NONE:
slouken@3407
   438
        copy RGB.
slouken@3407
   439
      both:
slouken@3407
   440
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
philipp@7125
   441
        source color key.
slouken@3407
   442
    \endverbatim
slouken@7191
   443
 *
slouken@3407
   444
 *  You should call SDL_BlitSurface() unless you know exactly how SDL
slouken@3407
   445
 *  blitting works internally and how to use the other blit functions.
slouken@2275
   446
 */
slouken@2275
   447
#define SDL_BlitSurface SDL_UpperBlit
slouken@2275
   448
slouken@3407
   449
/**
slouken@3407
   450
 *  This is the public blit function, SDL_BlitSurface(), and it performs
slouken@3341
   451
 *  rectangle validation and clipping before passing it to SDL_LowerBlit()
slouken@3341
   452
 */
slouken@2275
   453
extern DECLSPEC int SDLCALL SDL_UpperBlit
slouken@4949
   454
    (SDL_Surface * src, const SDL_Rect * srcrect,
slouken@2275
   455
     SDL_Surface * dst, SDL_Rect * dstrect);
slouken@3341
   456
slouken@3407
   457
/**
slouken@3407
   458
 *  This is a semi-private blit function and it performs low-level surface
slouken@3341
   459
 *  blitting only.
slouken@3341
   460
 */
slouken@2275
   461
extern DECLSPEC int SDLCALL SDL_LowerBlit
slouken@2275
   462
    (SDL_Surface * src, SDL_Rect * srcrect,
slouken@2275
   463
     SDL_Surface * dst, SDL_Rect * dstrect);
slouken@2275
   464
slouken@2275
   465
/**
slouken@3407
   466
 *  \brief Perform a fast, low quality, stretch blit between two surfaces of the
slouken@3407
   467
 *         same pixel format.
slouken@7191
   468
 *
slouken@3407
   469
 *  \note This function uses a static buffer, and is not thread-safe.
slouken@2275
   470
 */
slouken@2275
   471
extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
slouken@2828
   472
                                            const SDL_Rect * srcrect,
slouken@2275
   473
                                            SDL_Surface * dst,
slouken@2828
   474
                                            const SDL_Rect * dstrect);
slouken@2275
   475
ken@5499
   476
#define SDL_BlitScaled SDL_UpperBlitScaled
ken@5499
   477
ken@5296
   478
/**
ken@5499
   479
 *  This is the public scaled blit function, SDL_BlitScaled(), and it performs
ken@5499
   480
 *  rectangle validation and clipping before passing it to SDL_LowerBlitScaled()
ken@5296
   481
 */
ken@5499
   482
extern DECLSPEC int SDLCALL SDL_UpperBlitScaled
ken@5296
   483
    (SDL_Surface * src, const SDL_Rect * srcrect,
ken@5499
   484
    SDL_Surface * dst, SDL_Rect * dstrect);
ken@5499
   485
ken@5499
   486
/**
ken@5499
   487
 *  This is a semi-private blit function and it performs low-level surface
ken@5499
   488
 *  scaled blitting only.
ken@5499
   489
 */
ken@5499
   490
extern DECLSPEC int SDLCALL SDL_LowerBlitScaled
ken@5499
   491
    (SDL_Surface * src, SDL_Rect * srcrect,
ken@5499
   492
    SDL_Surface * dst, SDL_Rect * dstrect);
ken@5296
   493
ken@5296
   494
slouken@2275
   495
/* Ends C function definitions when using C++ */
slouken@2275
   496
#ifdef __cplusplus
slouken@2275
   497
}
slouken@2275
   498
#endif
slouken@2275
   499
#include "close_code.h"
slouken@2275
   500
slouken@2275
   501
#endif /* _SDL_surface_h */
slouken@2275
   502
slouken@2275
   503
/* vi: set ts=4 sw=4 expandtab: */