Mercurial > sdl-ios-xcode

comparison include/SDL_video.h @ 2222:926294b2bb4e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Emphasized the separation between SDL_Surface and SDL_Texture - SDL_Surface is a system memory representation of pixel data - SDL_Texture is a video memory representation of pixel data The concept of SDL_Surface with SDL_HWSURFACE is no longer used. Separated SDL_Texture types by usage rather than memory type - SDL_TEXTUREACCESS_STATIC is for rarely changed pixel data, can be placed in video memory. - SDL_TEXTUREACCESS_STREAMING is for frequently changing pixel data, usually placed in system memory or AGP memory. Optimized the SDL_compat usage of the OpenGL renderer by only using one copy of the framebuffer instead of two.
author Sam Lantinga <slouken@libsdl.org>
date Sat, 11 Aug 2007 20:54:31 +0000
parents b03710fb0333
children e61ad15a205f
comparison
equal deleted inserted replaced
2221:1d75c38e1e5c 2222:926294b2bb4e
202 * 202 *
203 * \brief The access pattern allowed for a texture 203 * \brief The access pattern allowed for a texture
204 */ 204 */
205 typedef enum 205 typedef enum
206 { 206 {
207 SDL_TEXTUREACCESS_LOCAL, /**< Lockable system memory */ 207 SDL_TEXTUREACCESS_STATIC, /**< Changes rarely, not lockable */
208 SDL_TEXTUREACCESS_REMOTE /**< Unlockable video memory */ 208 SDL_TEXTUREACCESS_STREAMING /**< Changes frequently, lockable */
209 } SDL_TextureAccess; 209 } SDL_TextureAccess;
210 210
211 /** 211 /**
212 * \enum SDL_TextureModulate 212 * \enum SDL_TextureModulate
213 * 213 *
262 typedef void *SDL_GLContext; 262 typedef void *SDL_GLContext;
263 263
264 264
265 /* These are the currently supported flags for the SDL_surface */ 265 /* These are the currently supported flags for the SDL_surface */
266 /* Used internally (read-only) */ 266 /* Used internally (read-only) */
267 #define SDL_HWSURFACE 0x00000001 /* Surface represents a texture */ 267 #define SDL_PREALLOC 0x00000001 /* Surface uses preallocated memory */
268 #define SDL_PREALLOC 0x00000002 /* Surface uses preallocated memory */
269 #define SDL_SRCALPHA 0x00000004 /* Blit uses source alpha blending */ 268 #define SDL_SRCALPHA 0x00000004 /* Blit uses source alpha blending */
270 #define SDL_SRCCOLORKEY 0x00000008 /* Blit uses a source color key */ 269 #define SDL_SRCCOLORKEY 0x00000008 /* Blit uses a source color key */
271 #define SDL_RLEACCELOK 0x00000010 /* Private flag */ 270 #define SDL_RLEACCELOK 0x00000010 /* Private flag */
272 #define SDL_RLEACCEL 0x00000020 /* Surface is RLE encoded */ 271 #define SDL_RLEACCEL 0x00000020 /* Surface is RLE encoded */
273 272
274 /* Evaluates to true if the surface needs to be locked before access */ 273 /* Evaluates to true if the surface needs to be locked before access */
275 #define SDL_MUSTLOCK(S) (((S)->flags & (SDL_HWSURFACE|SDL_RLEACCEL)) != 0) 274 #define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0)
276 275
277 /* This structure should be treated as read-only, except for 'pixels', 276 /* This structure should be treated as read-only, except for 'pixels',
278 which, if not NULL, contains the raw pixel data for the surface. 277 which, if not NULL, contains the raw pixel data for the surface.
279 */ 278 */
280 typedef struct SDL_Surface 279 typedef struct SDL_Surface
285 int pitch; /* Read-only */ 284 int pitch; /* Read-only */
286 void *pixels; /* Read-write */ 285 void *pixels; /* Read-write */
287 286
288 /* Application data associated with the surfade */ 287 /* Application data associated with the surfade */
289 void *userdata; /* Read-write */ 288 void *userdata; /* Read-write */
290
291 /* texture associated with the surface, if any */
292 SDL_TextureID textureID; /* Read-only */
293 289
294 /* information needed for surfaces requiring locks */ 290 /* information needed for surfaces requiring locks */
295 int locked; /* Read-only */ 291 int locked; /* Read-only */
296 void *lock_data; /* Read-only */ 292 void *lock_data; /* Read-only */
297 293
925 extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTexture(Uint32 format, 921 extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTexture(Uint32 format,
926 int access, int w, 922 int access, int w,
927 int h); 923 int h);
928 924
929 /** 925 /**
930 * \fn SDL_TextureID SDL_CreateTextureFromSurface(Uint32 format, int access, SDL_Surface *surface) 926 * \fn SDL_TextureID SDL_CreateTextureFromSurface(Uint32 format, SDL_Surface *surface)
931 * 927 *
932 * \brief Create a texture from an existing surface. 928 * \brief Create a texture from an existing surface.
933 * 929 *
934 * \param format The format of the texture, or 0 to pick an appropriate format 930 * \param format The format of the texture, or 0 to pick an appropriate format
935 * \param access One of the enumerated values in SDL_TextureAccess
936 * \param surface The surface containing pixel data used to fill the texture 931 * \param surface The surface containing pixel data used to fill the texture
937 * 932 *
938 * \return The created texture is returned, or 0 if no rendering context was active, the format was unsupported, or the surface width or height were out of range. 933 * \return The created texture is returned, or 0 if no rendering context was active, the format was unsupported, or the surface width or height were out of range.
939 * 934 *
940 * \note The surface is not modified or freed by this function. 935 * \note The surface is not modified or freed by this function.
942 * \sa SDL_QueryTexture() 937 * \sa SDL_QueryTexture()
943 * \sa SDL_DestroyTexture() 938 * \sa SDL_DestroyTexture()
944 */ 939 */
945 extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTextureFromSurface(Uint32 940 extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTextureFromSurface(Uint32
946 format, 941 format,
947 int access,
948 SDL_Surface 942 SDL_Surface
949 * surface); 943 * surface);
950 944
951 /** 945 /**
952 * \fn int SDL_QueryTexture(SDL_TextureID textureID, Uint32 *format, int *access, int *w, int *h) 946 * \fn int SDL_QueryTexture(SDL_TextureID textureID, Uint32 *format, int *access, int *w, int *h)
968 /** 962 /**
969 * \fn int SDL_QueryTexturePixels(SDL_TextureID textureID, void **pixels, int pitch) 963 * \fn int SDL_QueryTexturePixels(SDL_TextureID textureID, void **pixels, int pitch)
970 * 964 *
971 * \brief Query the pixels of a texture, if the texture does not need to be locked for pixel access. 965 * \brief Query the pixels of a texture, if the texture does not need to be locked for pixel access.
972 * 966 *
973 * \param texture A texture to be queried, which was created with SDL_TEXTUREACCESS_LOCAL 967 * \param texture A texture to be queried, which was created with SDL_TEXTUREACCESS_STREAMING
974 * \param pixels A pointer filled with a pointer to the pixels for the texture 968 * \param pixels A pointer filled with a pointer to the pixels for the texture
975 * \param pitch A pointer filled in with the pitch of the pixel data 969 * \param pitch A pointer filled in with the pitch of the pixel data
976 * 970 *
977 * \return 0 on success, or -1 if the texture is not valid, or must be locked for pixel access. 971 * \return 0 on success, or -1 if the texture is not valid, or must be locked for pixel access.
978 */ 972 */
1153 * \param pixels The raw pixel data 1147 * \param pixels The raw pixel data
1154 * \param pitch The number of bytes between rows of pixel data 1148 * \param pitch The number of bytes between rows of pixel data
1155 * 1149 *
1156 * \return 0 on success, or -1 if the texture is not valid 1150 * \return 0 on success, or -1 if the texture is not valid
1157 * 1151 *
1158 * \note This is a very slow function for textures not created with SDL_TEXTUREACCESS_LOCAL. 1152 * \note This is a fairly slow function.
1159 */ 1153 */
1160 extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_TextureID textureID, 1154 extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_TextureID textureID,
1161 const SDL_Rect * rect, 1155 const SDL_Rect * rect,
1162 const void *pixels, int pitch); 1156 const void *pixels, int pitch);
1163 1157
1164 /** 1158 /**
1165 * \fn void SDL_LockTexture(SDL_TextureID textureID, const SDL_Rect *rect, int markDirty, void **pixels, int *pitch) 1159 * \fn void SDL_LockTexture(SDL_TextureID textureID, const SDL_Rect *rect, int markDirty, void **pixels, int *pitch)
1166 * 1160 *
1167 * \brief Lock a portion of the texture for pixel access. 1161 * \brief Lock a portion of the texture for pixel access.
1168 * 1162 *
1169 * \param texture The texture to lock for access, which must have been created with SDL_TEXTUREACCESS_LOCAL. 1163 * \param textureID The texture to lock for access, which was created with SDL_TEXTUREACCESS_STREAMING.
1170 * \param rect A pointer to the rectangle to lock for access. If the rect is NULL, the entire texture will be locked. 1164 * \param rect A pointer to the rectangle to lock for access. If the rect is NULL, the entire texture will be locked.
1171 * \param markDirty If this is nonzero, the locked area will be marked dirty when the texture is unlocked. 1165 * \param markDirty If this is nonzero, the locked area will be marked dirty when the texture is unlocked.
1172 * \param pixels This is filled in with a pointer to the locked pixels, appropriately offset by the locked area. 1166 * \param pixels This is filled in with a pointer to the locked pixels, appropriately offset by the locked area.
1173 * \param pitch This is filled in with the pitch of the locked pixels. 1167 * \param pitch This is filled in with the pitch of the locked pixels.
1174 * 1168 *
1175 * \return 0 on success, or -1 if the texture is not valid or was created with SDL_TEXTUREACCESS_REMOTe 1169 * \return 0 on success, or -1 if the texture is not valid or was created with SDL_TEXTUREACCESS_STATIC
1176 * 1170 *
1177 * \sa SDL_DirtyTexture() 1171 * \sa SDL_DirtyTexture()
1178 * \sa SDL_UnlockTexture() 1172 * \sa SDL_UnlockTexture()
1179 */ 1173 */
1180 extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_TextureID textureID, 1174 extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_TextureID textureID,
1195 /** 1189 /**
1196 * \fn void SDL_DirtyTexture(SDL_TextureID textureID, int numrects, const SDL_Rect * rects) 1190 * \fn void SDL_DirtyTexture(SDL_TextureID textureID, int numrects, const SDL_Rect * rects)
1197 * 1191 *
1198 * \brief Mark the specified rectangles of the texture as dirty. 1192 * \brief Mark the specified rectangles of the texture as dirty.
1199 * 1193 *
1200 * \note The texture must have been created with SDL_TEXTUREACCESS_LOCAL. 1194 * \param textureID The texture to mark dirty, which was created with SDL_TEXTUREACCESS_STREAMING.
1195 * \param numrects The number of rectangles pointed to by rects.
1196 * \param rects The pointer to an array of dirty rectangles.
1201 * 1197 *
1202 * \sa SDL_LockTexture() 1198 * \sa SDL_LockTexture()
1203 * \sa SDL_UnlockTexture() 1199 * \sa SDL_UnlockTexture()
1204 */ 1200 */
1205 extern DECLSPEC void SDLCALL SDL_DirtyTexture(SDL_TextureID textureID, 1201 extern DECLSPEC void SDLCALL SDL_DirtyTexture(SDL_TextureID textureID,
1345 int pitch, 1341 int pitch,
1346 Uint32 Rmask, 1342 Uint32 Rmask,
1347 Uint32 Gmask, 1343 Uint32 Gmask,
1348 Uint32 Bmask, 1344 Uint32 Bmask,
1349 Uint32 Amask); 1345 Uint32 Amask);
1350 extern DECLSPEC SDL_Surface *SDLCALL
1351 SDL_CreateRGBSurfaceFromTexture(SDL_TextureID textureID);
1352 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface); 1346 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
1353 1347
1354 /** 1348 /**
1355 * \fn int SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette) 1349 * \fn int SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette)
1356 * 1350 *