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

SDL_Surface flags values

SDL_ANYFORMAT

Allow any pixel-format *

SDL_ASYNCBLIT

Use asynchronous blit if possible

SDL_DOUBLEBUF

Double buffered *

SDL_HWACCEL

Use hardware acceleration blit

SDL_HWPALETTE

Have an exclusive palette

SDL_HWSURFACE

Stored in video memory

SDL_FULLSCREEN

Full screen surface *

SDL_OPENGL

Have an OpenGL context *

SDL_OPENGLBLIT

Support OpenGL blitting *. NOTE: This option is kept for compatibility only, and is not recommended for new code.

SDL_RESIZABLE

Resizable surface *

SDL_RLEACCEL

Accelerated colorkey blitting with RLE

SDL_SRCALPHA

Use alpha blending blit

SDL_SRCCOLORKEY

Use colorkey blitting

SDL_SWSURFACE

Stored in the system memory. SDL_SWSURFACE is not actually a flag (it is defined as 0). A lack of SDL_HWSURFACE implies SDL_SWSURFACE

SDL_PREALLOC

Use preallocated memory

format

w, h

pitch

pixels

clip_rect

refcount

See also

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

Requirements

Header

SDL.h

Version

1.2.13

Shared object

libSDL.so

DLL

SDL.dll

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

SDL_Surface (last edited 2010-04-16 13:06:01 by 145)