How to display bitmaps using Simple Direct Media Layer(SDL)

Unless you're interested in making an old school text based game, you're probably going to want to display an image here or there. This tutorial will show you how to set up SDL video and display a bitmap to the screen.

Initializing SDL video is fairly easy:

The SDL_Init function is passed the SDL_INIT_VIDEO constant to indicate that we'd like to initialize SDL video. SDL_Init returns zero on success, so the code above checks for failure, and outputs a message if needed. The SDL_GetError function returns a string describing the most recent SDL error, and can be quite handy for determining what went wrong with your program. atexit is then used to guarantee that the SDL_Quit function is called when the application exits; this is very important, otherwise SDL won't clean itself up, and resources may not be released!

Now that SDL video has been initialized, we need to set the video mode:

The SDL_SetVideoMode function's first three parameters indicate screen resolution and colour depth. The above code will set the video mode to 640pixels by 480pixels, with 16bit colour. The fourth parameter is the flags parameter, and will accept the following values:


 * SDL_ANYFORMAT : If the colour depth requested in the SDL_SetVideoMode</tt> is not available, passing the SDL_ANYFORMAT</tt> constant will instruct SDL not to emulate the colour depth, and simply use whatever format the hardware can accommodate.
 * SDL_ASYNCBLIT : Allow the display to be updated asynchronously. This may give a speed boost on some systems, but could also result in visual artifacts.
 * SDL_DOUBLEBUF : Double buffering sets up a second screen-sized surface in memory (called a back buffer) enables fast pointer flips between the back buffer and the primary buffer when SDL_Flip</tt> is called. This prevents problems with tearing, but requires a little more memory and CPU time.  If your program doesn't need to update the entire screen every frame, you might be better off using a "dirty rectangles" method of redrawing the screen.
 * SDL_FULLSCREEN : If possible, SDL will attempt to change to the specified resolution in a full-screen mode. If SDL fails to achieve this, it will attempt to emulate the effect.
 * SDL_HWPALETTE : You must pass SDL_HWPALETTE</tt> if you intend to use SDL_SetColors</tt> or SDL_SetPalette</tt>, or you may get unexpected results.
 * SDL_HWSURFACE : Use hardware to create the video surface; this creates the surface in video memory.
 * SDL_NOFRAME : If the underlying windowing system will allow it, SDL will create a window with no title bar or frame.
 * SDL_OPENGL : Sets up the display to act as an OpenGL context.
 * SDL_RESIZABLE : Passing this constant creates a resizable window. If the user resizes the window, a SDL_VIDEORESIZE</tt> event is triggered, and the program can make a new call to SDL_SetVideoMode</tt> to accommodate the size change.
 * SDL_RLEACCEL : Uses Run Length Encoding to compress video data. This may have the effect of increasing display speed.
 * SDL_SWSURFACE : Use software to create the video surface; this creates the surface in system memory.

In the code above we have passed SDL_DOUBLEBUF | SDL_FULLSCREEN</tt> which will combine the flags to give us a double-buffered full-screen display. If successful, SDL_SetVideoMode</tt> returns a pointer to an SDL_Surface</tt>. On failure, it returns NULL</tt>. The code above demonstrates how to check for failure, and output a meaningful description of the problem.

Now that the video mode has been set, we can load our chosen bitmap into a surface:

The SDL_LoadBMP</tt> function accepts a path string, pointing to the bitmap we wish to load. On success, the function will return a pointer to an SDL_Surface</tt>, which we will store in a temporary variable, temp</tt>. On failure, SDL_LoadBMP</tt> returns <tt>NULL</tt>. Again, the code shows how to handle and report on failure.

Once the <tt>temp</tt> variable has been assigned, we call <tt>SDL_DisplayFormat</tt> to convert the surface data to a format which is compatible with the video mode that we selected with <tt>SDL_SetVideoMode</tt>. The result is referenced by our pointer <tt>image</tt>. <tt>SDL_FreeSurface</tt> is then called to release the temporary variable, as the surface it references is no longer needed.

Now that our bitmap has been loaded into a surface, we can display it to the screen:

We first define two <tt>SDL_Rect</tt> structures, and fill them with data. The <tt>src</tt> rectangle will describe the portion of the surface we wish to display. Since we want to display the entire image, we set the <tt>x</tt> and <tt>y</tt> values to zero, and the <tt>w</tt> (width) and <tt>h</tt> (height) values to the <tt>w</tt> and <tt>h</tt> values of the <tt>image</tt>.

The <tt>dest</tt> rectangle describes the portion of the screen to display the image upon. As above, we want to display the entire image, so we set the width and height values to equal the values contained within the <tt>image</tt>. The <tt>x</tt> and <tt>y</tt> values of the <tt>dest</tt> indicate where the top-left corner of the image will be displayed, and I've set the values to <tt>100</tt>, in order place the image slightly away from the top-left corner of the screen.

Once our two <tt>SDL_Rect</tt> structures are ready, we can call <tt>SDL_BlitSurface</tt>, passing the source surface, the source rectangle, the destination surface, and the destination rectangle. <tt>SDL_BlitSurface</tt> takes this information and performs a Bit-Block Transfer, copying the image data from the source surface onto the destination surface, within the rectangles defined. The result of the above code is that our image is copied on to the back buffer, ready to be flipped to the primary buffer.

<tt>SDL_Flip</tt> swaps the primary buffer pointer to reference the back buffer, thereby displaying our image on the screen. The call to <tt>SDL_Delay</tt> simply pauses execution for 2500ms (2.5 seconds), in order to let us see the results on screen.

Only clean-up remains to be handled:

<tt>SDL_FreeSurface</tt> is called, releasing the resources associated with our image. That's all we have to do! When the program exits, our previous <tt>atexit(SDL_Quit)</tt> call will ensure that SDL has a chance to clean up.

Credits
This howto came from
 * http://gpwiki.org

From HowTo Wiki, a Wikia wiki.