Upcoming Events
Unite 2010
11/10 - 11/12 @ Montréal, Canada

GDC China
12/5 - 12/7 @ Shanghai, China

Asia Game Show 2010
12/24 - 12/27  

GDC 2011
2/28 - 3/4 @ San Francisco, CA

More events...
Quick Stats
67 people currently visiting GDNet.
2406 articles in the reference section.

Help us fight cancer!
Join SETI Team GDNet!
Link to us Events 4 Gamers
Intel sponsors gamedev.net search:

Contents
 Basic Structures
 SDL_Surface
 Video Information
 Creating and
 Destroying Surfaces

 Using SDL Video

 Printable version
 Discuss this article

The Series
 Setting Up Your
 System for SDL

 SDL Video

SDL_Surface

Just like the IDirectDrawSurface object in DirectDraw and the HDC in GDI, the SDL_Surface is the most important structure in the SDL video subsystem. It abstracts a rectangular area of pixel data. Here's what it looks like:

typedef struct SDL_Surface {
  Uint32 flags;
  SDL_PixelFormat *format;
  int w, h;
  Uint16 pitch;
  void *pixels;
  SDL_Rect clip_rect;
  int refcount;
} SDL_Surface;

There are actually more members than this, but they should not be publicly accessed, and so are not shown.

The flags member contains a combination of bit flags that describe what type of surface this is. These flags are listed and briefly explained in table 1.

Table 1: Surface Flags
Flag Meaning
SDL_SWSURFACE Surface exists in software (non-video RAM)
SDL_HWSURFACE Surface exists in video RAM.
SDL_ASYNCBLIT Blits occur asynchronously.
SDL_ANYFORMAT* This flag specifies to use whatever the current display format is for the display surface. Typically, this is used when making a windowed SDL application.
SDL_HWPALETTE The surface makes use of a hardware palette.
SDL_DOUBLEBUF* The surface is double buffered (i.e. a flipping chain).
SDL_FULLSCREEN* The surface is full screen.
SDL_OPENGL* The surface will be used as a destination for OpenGL rendering.
SDL_OPENGLBLIT* The surface will be used as a destination for OpenGL rendering.
SDL_RESIZABLE* (Windowed mode only) the window is resizable.
SDL_HWACCEL The surface will use hardware accelerated blitting.
SDL_SRCCOLORKEY The surface has a color key.
SDL_RLEACCEL The surface is used for run-length-encoded blits.
SDL_SRCALPHA The surface has an alpha component.
SDL_PREALLOC The surface came to be from a pre-allocated array of pixel data.

*only the display surface may have these flags

The format member is a pointer to an SDL_PixelFormat structure that describes the pixel format for this surface.

The w and h members describe the width and height of the surface.

The pitch contains the number of bytes per scan line for the surface. Video cards being what they are, this value is often not the same as the BytesPerPixel times the width.

The pixels is a pointer to pixel data for the surface. It is used to read or write pixels to and from the surface.

The clip_rect member is an SDL_Rect that describes the clipping area of the surface. Any writing outside of this area will not be shown.

And finally, refcount is a reference count. When a surface is created, it is set to one. You can increment it manually. It is decremented whenever the surface is freed. Once it reaches 0, the surface is deleted from memory. This member is sort of like using AddRef for COM objects.

IMPORTANT NOTE: with the exception of refcount and the data pointed to by pixels, these members should not by modified by you directly. There are functions for dealing with and changing most of them.

SDL_VideoInfo

The last structure we're going to look at is SDL_VideoInfo. As you might expect, it contains information about the video display on the machine it is running on. Here's what it looks like:

typedef struct{
  Uint32 hw_available:1;
  Uint32 wm_available:1;
  Uint32 blit_hw:1;
  Uint32 blit_hw_CC:1;
  Uint32 blit_hw_A:1;
  Uint32 blit_sw:1;
  Uint32 blit_sw_CC:1;
  Uint32 blit_sw_A:1;
  Uint32 blit_fill:1;
  Uint32 video_mem;
  SDL_PixelFormat *vfmt;
} SDL_VideoInfo;

The closest equivalent in DirectDraw is the DDCAPS structure. SDL_VideoInfo, however, is much easier to read. Most of the members are single bits, and a value of 0 means that the feature in question is not supported, and 1 means that the feature is supported.

The hw_available indicates that you may create hardware surfaces, which naturally will be faster than software surface.

The wm_available indicates that a window manager is available. In WIN32, one is, but for other platforms, one might not be. The window manager is another subsystem of SDL that deals with some pretty basic settings for a window (if you are using windowed mode versus fullscreen).

The blit_hw, blit_hw_CC, and blit_hw_A all deal with the availability of hardware acceleration for blits between surface stored in hardware. The blit_hw bit specifies that generic hardware to hardware blits are accelerated, blit_hw_CC specifies that hardware to hardware colorkeyed blits are accelerated, and blit_hw_A specifies that hardware to hardware alpha blits are accelerated.

The blit_sw, blit_sw_CC, and blit_sw_A are much the same as the blit_hw members, except that they specify the capabilities for software to hardware blits instead.

The blit_fill member specifies that color fill operations are accelerated.

The video_mem contains, in kilobytes, the amount of video RAM for the system.

The vfmt member is a pointer to an SDL_PixelFormat. Depending on when you call it, it will contain either the "best" video format (the one with the most capabilities), or the current video format (depending on if you have already set up your display surface or not).





Next : Video Information