Miguel Ruiz / SDL_lib

SDL standard library

Dependents:   H261_encoder

SDL_surface.h@0:dda4f4550403, 2016-09-07 (annotated)

Committer:
miruga27
Date:
Wed Sep 07 18:46:53 2016 +0000
Revision:
0:dda4f4550403
7/09/2016;

Who changed what in which revision?

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