• SDL_Surface

SDL_Surface structure

SDL_Surface -- Graphic surface structure

Structure Definition

   1 typedef struct SDL_Surface {
   2     Uint32 flags;                           /* Read-only */
   3     SDL_PixelFormat *format;                /* Read-only */
   4     int w, h;                               /* Read-only */
   5     Uint16 pitch;                           /* Read-only */
   6     void *pixels;                           /* Read-write */
   7     SDL_Rect clip_rect;                     /* Read-only */
   8     int refcount;                           /* Read-mostly */
   9 
  10   /* This structure also contains private fields not shown here */
  11 } SDL_Surface;

Description

An SDL_Surface represents an area of graphical memory that can be drawn to. The video framebuffer is returned as a SDL_Surface by SDL_SetVideoMode and SDL_GetVideoSurface.

Structure details

flags

• The field supports the following OR-ed values:

format

• The format of the pixels stored in the surface. See SDL_PixelFormat

w, h

• The surface width and height in pixels

pitch

• The length of a surface scanline in bytes

pixels

• The pointer to the actual pixel data. The surface should be locked by SDL_LockSurface before accessing this field.

clip_rect

• The surface clip rectangle which can be set by SDL_SetClipRect

refcount

• The reference count -- used when freeing surface

See also

SDL_PixelFormat, SDL_Rect, SDL_CreateRGBSurface, SDL_CreateRGBSurfaceFrom, SDL_FreeSurface, SDL_SetVideoMode, SDL_LockSurface, SDL_SetAlpha, SDL_SetColorKey

Requirements

User comments

Given an SDL_Surface, this is how you might want to inspect it:

   1 void SDL_SurfaceInfo(char * name, SDL_Surface *thing)
   2 {
   3     printf("Surface %s: w:%d h:%d bpp:%d\n", name, thing->w, thing->h, thing->format->BitsPerPixel);
   4 }

You can call this as SDL_SurfaceInfo("Background Image", background_image); where background_image is an SDL_Surface.

All pixels of RGB surfaces (including screen) start, on surface creation, at color definition [R;G;B] = [ 0 ; 0 ; 0 ]. For RGBA surfaces pixels start at color definition [R;G;B;A] = [ 0 ; 0 ; 0 ; SDL_ALPHA_TRANSPARENT ].

An SDL_Surface contains some pointers (Especially pixels). The following code show an error which occur when you deal with two SDL_Surface :

   1     SDL_Surface *Srfc1, *Srfc2;
   2 
   3     Srfc1 = IMG_Load("foo.png");
   4     Srfc2 = (SDL_Surface*)malloc(sizeof(SDL_Surface));
   5     memcpy(Srfc2, Srfc1, sizeof(SDL_Surface));
   6 ...
   7     SDL_FreeSurface(Srfc1);   /* Work */
   8     SDL_FreeSurface(Srfc2);   /* SEGFAULT */

This error can be explained because some data are contained in a pointer, so when you do the memcpy(), the data pointed by these pointers isn't copied. The first call the SDL_FreeSurface will free this data, so the second will segfault.

The proper way to duplicate a surface is

   1     SDL_Surface *Srfc1, *Srfc2;
   2     Srfc1= IMG_Load("foo.png");
   3     Srfc2= Srfc1;
   4     Srfc2->refcount++;
   5 ...
   6     SDL_FreeSurface(Srfc1);
   7     SDL_FreeSurface(Srfc2);

To make a real copy of a SDL_Surface, use SDL_ConvertSurface like this

   1     SDL_Surface *Srfc1;
   2 ...
   3     SDL_Surface *Srfc2 = SDL_ConvertSurface(Srfc1, Srfc1->format, Srfc1->flags);
   4 ...
   5     SDL_FreeSurface(Srfc1);
   6     SDL_FreeSurface(Srfc2);

CategorySDLVideo