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:

 Basic Structures
 Video Information
 Creating and
 Destroying Surfaces

 Using SDL Video

 Printable version
 Discuss this article

The Series
 Setting Up Your
 System for SDL

 SDL Video

Mission Statement

Graphics make the game/application. There is no question about this. In WIN32, if you intend to do 2D graphics, you normally have two choices: GDI or DirectDraw. GDI is slow as hell, and DirectDraw is MicroSoft specific. Porting an application that uses either GDI or DirectDraw to a non-WIN32 platform can be painful.

One of your other options is SDL's video component. Keep in mind that SDL can only be used (by itself) for 2D graphics. If you want 3D graphics, though, SDL works well with OpenGL. For the purposes of this article, we are going to talk only about SDL's 2D graphical capabilities.

Here are the TGOs*(Topical Guide Objectives) for this article.

TGO-02-AKnow the basic structures SDL uses for doing graphics
TGO-02-BKnow how to get information from the SDL video subsystem.
TGO-02-CKnow how to create and destroy various types of SDL surfaces
TGO-02-DKnow how to work with SDL surfaces
TGO-02-D1Know how to do filled rectangles
TGO-02-D2Know how to get and set pixels
TGO-02-D3Know how to blit from one surface to another
TGO-02-D4Know how to use color keys
TGO-02-D5Know how to clip output

*About TGOs: The concept of TGOs I borrowed from the United States Navy. In training programs, the specific knowledge that you are responsible for having are all listed in a book of Topical Guide Objectives. This book is referred to as the "Topical Guide". TGOs are good for both the reader and the author, as it lets the reader know exactly what he or she will be learning at a glance, and it reminds the author exactly what he will be covering.

Basic Structures (TGO-02-A)

As of version 1.2.3 of SDL, there are seven structures in the library that deal with the video subsystem. These are SDL_Rect, SDL_Color, SDL_Palette, SDL_PixelFormat, SDL_Surface, SDL_VideoInfo, and SDL_Overlay. Most of them do exactly what you'd expect them to do. We're going to cover the first six of these (leaving out SDL_Overlay).


SDL_Rect is one of the simpler structures. As you probably guessed, it abstracts a rectangular area on the screen. Here's what it looks like:

typedef struct{
  Sint16 x, y;
  Uint16 w, h;
} SDL_Rect;

This is a pretty standard rectangle structure, unless of course you are used to working with the WIN32 RECT structure. The x and y members contain the upper left hand corner. The w and h members contain the width and height. All of these members measure units in pixels (and never anything but pixels).

A brief note about some of the odd looking types used in SDL: because it is cross platform, the writers of SDL had to make some integral types that would be the same size no matter what platform they were used on. Considering differences between platforms and the size of the int type, they came up with things like Sint16 and Uint16, there are a number of types like these. They all take the form:


In front of the type name, you will see either an S or a U. S stands for "signed" and U stands for "unsigned". n is a number, either 8, 16, or 32.

In the case of SDL_Rect, x and y are Sint16s, and so they range from -32768 to +32767, which is more than enough to deal with rectangular areas of the screen. The w and h members are Uint16s, and so can range from 0 to 65535. Notice that these are always non-negative, since you cannot have a rectangle with a negative width or height (unlike in the WIN32 RECT structure).

A point (x,y) lies within a rectangle (rect) if the all of the following are true:

x >= rect.x
y >= rect.y
x < ( rect.x + rect.w )
y < ( rect.y + rect.h )

If a rectangles w or h members are 0, it is an empty rectangle, and it contains no points whatsoever. There are absolutely no functions whatsoever for working with SDL_Rects (like the ones they have for WIN32 RECTs, like OffsetRect or UnionRect or IntersectRect), so if you need them, you have to make them yourself.


The second structure is just as simple. SDL_Color abstracts an RGB color value in an independent way. Here's what it looks like:

typedef struct{
  Uint8 r;
  Uint8 g;
  Uint8 b;
  Uint8 unused;
} SDL_Color;

SDL_Color is a lot like the WIN32 PALETTEENTRY or RGBQUAD structure. It contains four Uint8 values (bytes), and each member can range from 0 to 255. The r, g, and b members represent a colors red, green, and blue value. The unused member is just that--unused. Just sort of pretend it doesn't exist.

No functions exist for working with the SDL_Color structure either. If you want them, you can make your own, or just work with the members themselves. I personally like wrapping SDL_Color into a class.


In theory, the use of palettes has gone the way of the dinosaur. Still, there are times when they are useful, and so SDL has them. Palettes in SDL are strictly 8 bit palettes, for 256 different colors. However, you can make a palette whatever size you like, for example you could make one 256 color master palette, and then 8 different 8 color palettes that you use for palette animation and overwrite only a certain portion of the actual palette with those eight colors.

The SDL_Palette structure is pretty simple:

typedef struct{
  int ncolors;
  SDL_Color *colors;
} SDL_Palette;

The ncolors member is the number of colors in the palette. The colors member is a pointer to an array of SDL_Color values. You have to work with these members manually, allocating and deallocating colors, setting them, and so on. SDL doesn't include any functions for working with palettes, other than those that set the palette entries for a surface.

SDL_Palette is roughly akin to IDirectDrawPalette, but without any of the encapsulation.


This structure is highly useful. It is similar in purpose to the DDPIXELFORMAT structure of DirectDraw. It describes everything you'd ever want to know about how pixels are represented for a particular surface. Here's what it looks like:

typedef struct{
  SDL_Palette *palette;
  Uint8  BitsPerPixel;
  Uint8  BytesPerPixel;
  Uint32 Rmask, Gmask, Bmask, Amask;
  Uint8  Rshift, Gshift, Bshift, Ashift;
  Uint8  Rloss, Gloss, Bloss, Aloss;
  Uint32 colorkey;
  Uint8  alpha;
} SDL_PixelFormat;

Everything you want to know about a pixel format is right here. First, the palette member is a pointer to an SDL_Palette, if the format has one. If not, this member will be NULL.

Next, BitsPerPixel and BytesPerPixel specify how many bits and bytes are per pixel for this format (kind of obvious from the name, no?).

The next group of members are Rmask, Gmask, Bmask, and Amask. These are the bit masks in the pixel format for each of the color components, Rmask for red, Gmask for green, Bmask for blue, and Amask for alpha. These are useful for using the & operator to isolate certain color components.

The next group, Rshift, Gshift, Bshift, and Ashift specify the bit position in the pixel that begins the color component in question. After you take a pixel value and & with the Rmask value, you can >> by the Rshift value to get it in the lowest bits of the variable.

Rloss, Gloss, Bloss, and Aloss is another group of members used for color conversion. These members contain the number of bits that are lost when starting from an 8 bit value. After you have & by the Rmask, and >> by the Rshift, you can << by Rloss, and you'll have a value in the range of 0 to 255 for your red component. This makes color conversion to and from SDL_Color values really easy.

//color is an SDL_Color, and format is an SDL_PixelFormat
//convert color to native format
Uint32 native = 0 ;
Uint32 red , green , blue ;
red = color.r >> format.Rloss ;
green = color.g >> format.Gloss ;
blue = color.b >> format.Bloss ;
red <<= format.Rshift ;
green <<= format.Gshift ;
blue <<= format.Bshift ;

//convert native pixel to SDL_Color
red = native & format.Rmask ;
green = native & format.Gmask ;
blue = native & format.Bmask ;
red >>= format.Rshift ;
green >>= format.Gshift ;
blue >>= format.Bshift ;
red <<= format.Rloss ;
green <<= format.Gloss ;
blue <<= format.Bloss ;
color.r = red ;
color.g = green ;
color.b = blue ;

Pretty simple, right? Don't worry too much about this code, though. SDL provides functions that will do these things for you.

The colorkey member of SDL_PixelFormat stores the transparent color for the format. This color is in the native pixel format, not as an SDL_Color.

Finally, the alpha member is an eight bit value that stores an overall alpha value for the surface.

Next : SDL_Surface