Introduction to SDL video

Video is probably the most common thing that SDL is used for, and so it has the most complete subsystem. Here are a few examples to demonstrate the basics.

Initializing the Video Display

This is what almost all SDL programs have to do in one way or another.

Examples:

Initializing the video display

   1     SDL_Surface* screen = NULL;
   2 
   3     /* Initialize the SDL library and the video subsystem */
   4     if( SDL_Init(SDL_INIT_VIDEO) < 0 ) {
   5         fprintf(stderr, "Couldn't initialize SDL: %s\n", SDL_GetError());
   6         exit(1);
   7     }
   8 
   9     /* Clean up on exit */
  10     atexit(SDL_Quit);
  11 
  12     /*
  13      * Initialize the display in a 640x480 8-bit palettized mode,
  14      * requesting a software surface
  15      */
  16     screen = SDL_SetVideoMode(640, 480, 8, SDL_SWSURFACE);
  17     if ( screen == NULL ) {
  18         fprintf(stderr, "Couldn't set 640x480x8 video mode: %s\n", SDL_GetError());
  19         exit(1);
  20     }

Initializing the best video mode

If you have a preference for a certain pixel depth but will accept any other, use SDL_SetVideoMode with SDL_ANYFORMAT as below. You can also use SDL_VideoModeOK to find the native video mode that is closest to the mode you request.

   1     /* Have a preference for 8-bit, but accept any depth */
   2     screen = SDL_SetVideoMode(640, 480, 8, SDL_SWSURFACE|SDL_ANYFORMAT);
   3     if ( screen == NULL ) {
   4         fprintf(stderr, "Couldn't set 640x480x8 video mode: %s\n", SDL_GetError());
   5         exit(1);
   6     }
   7     printf("Set 640x480 at %d bits-per-pixel mode\n", screen->format->BitsPerPixel);

Loading and displaying a BMP file

The following function loads and displays a BMP file given as argument, once SDL is initialised and a video mode has been set.

   1 void display_bmp(char* file_name)
   2 {
   3     SDL_Surface* image = NULL;
   4 
   5     /* Load the BMP file into a surface */
   6     image = SDL_LoadBMP(file_name);
   7     if (image == NULL) {
   8         fprintf(stderr, "Couldn't load %s: %s\n", file_name, SDL_GetError());
   9         return;
  10     }
  11 
  12     /*
  13      * Palettized screen modes will have a default palette (a standard
  14      * 8*8*4 colour cube), but if the image is palettized as well we can
  15      * use that palette for a nicer colour matching
  16      */
  17     if (image->format->palette && screen->format->palette) {
  18         SDL_SetColors(screen, image->format->palette->colors, 0, image->format->palette->ncolors);
  19     }
  20 
  21     /* Blit onto the screen surface */
  22     if (SDL_BlitSurface(image, NULL, screen, NULL) < 0)
  23         fprintf(stderr, "BlitSurface error: %s\n", SDL_GetError());
  24 
  25     /* Update the modified region of the screen */
  26     SDL_UpdateRect(screen, 0, 0, image->w, image->h);
  27 
  28     /* Free the allocated BMP surface */
  29     SDL_FreeSurface(image);
  30 }

Get the pixels directly from the video device

The following two functions can be used to get and set single pixels of a surface. They are carefully written to work with any depth currently supported by SDL. Remember to lock the surface before calling them, and to unlock it before calling any other SDL functions.

To convert between pixel values and their red, green, blue components, use SDL_GetRGB and SDL_MapRGB.

   1 /*
   2  * Return the pixel value at (x, y)
   3  * NOTE: The surface must be locked before calling this!
   4  */
   5 Uint32 getpixel(SDL_Surface *surface, int x, int y)
   6 {
   7     int bpp = surface->format->BytesPerPixel;
   8     /* Here p is the address to the pixel we want to retrieve */
   9     Uint8 *p = (Uint8 *)surface->pixels + y * surface->pitch + x * bpp;
  10 
  11     switch (bpp) {
  12     case 1:
  13         return *p;
  14 
  15     case 2:
  16         return *(Uint16 *)p;
  17 
  18     case 3:
  19         if (SDL_BYTEORDER == SDL_BIG_ENDIAN)
  20             return p[0] << 16 | p[1] << 8 | p[2];
  21         else
  22             return p[0] | p[1] << 8 | p[2] << 16;
  23 
  24     case 4:
  25         return *(Uint32 *)p;
  26 
  27     default:
  28         return 0;       /* shouldn't happen, but avoids warnings */
  29     } // switch
  30 }

Put the pixels directly to the video device

   1 /*
   2  * Set the pixel at (x, y) to the given value
   3  * NOTE: The surface must be locked before calling this!
   4  */
   5 void putpixel(SDL_Surface *surface, int x, int y, Uint32 pixel)
   6 {
   7     int bpp = surface->format->BytesPerPixel;
   8     /* Here p is the address to the pixel we want to set */
   9     Uint8 *p = (Uint8 *)surface->pixels + y * surface->pitch + x * bpp;
  10 
  11     switch (bpp) {
  12     case 1:
  13         *p = pixel;
  14         break;
  15 
  16     case 2:
  17         *(Uint16 *)p = pixel;
  18         break;
  19 
  20     case 3:
  21         if (SDL_BYTEORDER == SDL_BIG_ENDIAN) {
  22             p[0] = (pixel >> 16) & 0xff;
  23             p[1] = (pixel >> 8) & 0xff;
  24             p[2] = pixel & 0xff;
  25         }
  26         else {
  27             p[0] = pixel & 0xff;
  28             p[1] = (pixel >> 8) & 0xff;
  29             p[2] = (pixel >> 16) & 0xff;
  30         }
  31         break;
  32 
  33     case 4:
  34         *(Uint32 *)p = pixel;
  35         break;
  36 
  37    default:
  38         break;           /* shouldn't happen, but avoids warnings */
  39     } // switch
  40 }

Using putpixel() example

The following code uses the putpixel() function above to set a yellow pixel in the middle of the screen.

   1     /* Code to set a yellow pixel at the center of the screen */
   2     int x, y;
   3     Uint32 yellow;
   4 
   5     /* Map the color yellow to this display (R=0xff, G=0xFF, B=0x00)
   6        Note:  If the display is palettized, you must set the palette first.
   7     */
   8     yellow = SDL_MapRGB(screen->format, 0xff, 0xff, 0x00);
   9 
  10     x = screen->w / 2;
  11     y = screen->h / 2;
  12 
  13     /* Lock the screen for direct access to the pixels */
  14     if ( SDL_MUSTLOCK(screen) ) {
  15         if ( SDL_LockSurface(screen) < 0 ) {
  16             fprintf(stderr, "Can't lock screen: %s\n", SDL_GetError());
  17             return;
  18         }
  19     }
  20 
  21     putpixel(screen, x, y, yellow);
  22 
  23     if ( SDL_MUSTLOCK(screen) ) {
  24         SDL_UnlockSurface(screen);
  25     }
  26     /* Update just the part of the display that we've changed */
  27     SDL_UpdateRect(screen, x, y, 1, 1);
  28 
  29     return;

Example: drawpixel()

   1 /*
   2  * Set the pixel at (x, y) of the specified surface to the given RGB value
   3  * NOTE: The surface must be locked before calling this!
   4  * Also, this doesn't update the screen, you'll have to do it yourself!
   5  * Also, It's not little-endian safe, so it's only for x86
   6  */
   7 void DrawPixel(SDL_Surface *Surface, int x, int y,Uint8 R, Uint8 G,Uint8 B)
   8 {
   9     Uint32 color = SDL_MapRGB(Surface->format, R, G, B);
  10     Uint8 *  bufp= (Uint8 *)Surface->pixels + y*Surface->pitch + x*Surface->format->BytesPerPixel;
  11     switch (Surface->format->BytesPerPixel) {
  12         case 4:
  13             bufp[3] = color >> 24;
  14         case 3:
  15             bufp[2] = color >> 16;
  16         case 2:
  17             bufp[1] = color >> 8;
  18         case 1:
  19             bufp[0] = color;
  20     }
  21     return;
  22 }

Example: using drawpixel()

   1 /*
   2  * This will scroll a Red/Green table across the screen, while adding Blue on each update
   3  */
   4 #include "SDL.h"
   5 
   6 int main()
   7 {
   8     SDL_Surface* display = NULL;
   9     Uint32 x,y,i;
  10 
  11     SDL_Init(SDL_INIT_VIDEO);
  12     display = SDL_SetVideoMode( 320, 320, 32, SDL_HWSURFACE );
  13 
  14     for (i=0; i!=255; i++){
  15        if (SDL_MUSTLOCK(display))
  16            SDL_LockSurface(display);
  17 
  18        for(y=0;y<(display->h);y++) {
  19            for(x=0;x<(display->w);x++) {
  20                DrawPixel(display, x, y,  x+i, y+i, i);
  21            }
  22        }
  23 
  24        if ( SDL_MUSTLOCK(display) )
  25            SDL_UnlockSurface(display);
  26 
  27        SDL_UpdateRect(display, 0, 0,  display->w,  display->h);
  28     }
  29 
  30     SDL_UpdateRect(display, 0, 0,  display->w,  display->h);
  31     SDL_Delay(3000);
  32     return 0;
  33 }

See also

Using_OpenGL_With_SDL

Introduction_to_SDL_Video (last edited 2010-02-11 11:29:37 by yix)