Layered display

Hi all,

I’ve quickly written an interface header defining a very basic and generic
system to support multiple layers in SDL, in the form of an SDL_Surface array.

Here is the code:

------------------- BEGINNING ---------------------

#ifndef SDL_LayeredDisplay_h
#define SDL_LayeredDisplay_h

#include “SDL.h”

/** @file SDL_LayeredDisplay.h

  • @author Julien CLEMENT
  • @brief A generic system to manage multiple blit layers
  •      with the SDL library (
  • @note You can use it either with the dirty rectangles
  •      method (SDL_UpdateRects) or with a whole refresh
  •      method (SDL_Flip).
  • @note Comments, suggestions, bugs are welcomed.
  •      Email me at:
  •      @Julien_Clement1


/** This source code will be integrated in your project.

  • To avoid dealing with dynamic memory and because you’re
  • supposed to know how many layers you need for your project
  • at compile time, it’s far easier and safer
  • to allocate memory statically for the layers.

/** The default option is to use the dirty rectangles method.

  • Comment out the following three lines if you choose
  • to refresh the whole display at each frame.
  • Note that if you choose the dirty rectangles method,
  • beware not to exceed 255 rectangles to refresh at each
  • frame.

/** @struct SDL_LayeredDisplay

  • @brief We store:
  •      - a list of SDL_Surface known as "layers"
  •      - the number of layers
  •      (stored as an Uint8 because we take for granted
  •      that no project will use more than 255 layers)
  • @note The lowest layer is the layer at indice 0 (zero).

struct SDL_LayeredDisplay
Uint8 n_layers;

SDL_Rect refresh_rects[255];
Uint8 n_refresh_rects;


typedef struct SDL_LayeredDisplay SDL_LayeredDisplay;

/** Create a new LayeredDisplay with each surface beeing in the display format.*

  • Parameters are exactly the same as the ones of SDL_CreateRGBSurface.
  • See the SDL documentation for more information.
  • @return A newly allocated layered display
  • @see SDL_FreeLayeredDisplay
    SDL_LayeredDisplay *
    SDL_CreateRGBLayeredDisplay (Uint32 flags, int width, int height, int bitsPerPixel,
    Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);

/** Frees the memory allocated for the layered display.

  • It internally calls SDL_FreeSurface on each layer surface.
  • @param layered_display The layered display to free
    void SDL_FreeLayeredDisplay (SDL_LayeredDisplay * layered_display);

/** Blits a surface onto a particular layer of the layered display.

  • If using the dirty rectangle method, the appropriate screen zone will be added to
  • the refresh list so that graphics belonging to upper and lower layers get
  • updated too.
  • @param src Surface to blit from
  • @param srcrect Area of the source surface to blit
  • @param layered_display Layered display to blit to
  • @param dstrect Area of the layered display to which the blit is performed
  • @param layer_number Layer number on which the blit will be performed
  • @see SDL_RefreshLayeredDisplay
    void SDL_BlitSurfaceOnLayeredDisplay (SDL_Surface * src, SDL_Rect * srcrect,
    SDL_LayeredDisplay * layered_display, SDL_Rect * dstrect,
    Uint8 layer_number);

/** Make a blit of all the layers of the layered display on the display surface (screen),

  • beginning from the lowest layer (layer at indice 0).
  • Then, update the screen according to the selected refresh method (dirty rectangles or flip).
  • @param layered_display The layered display to blit on the screen
    void SDL_UpdateLayeredDisplay (SDL_LayeredDisplay * layered_display);


------------------- END ---------------------

The implementation is not done yet but is quite straightforward.
I’d be grateful you give your opinion on this idea. In my experience, I’ve found quite
annoying to manage this multiple layers/planes stuff when developping a game,
and have to redraw graphics below and upper to a particular sprite.

A possible enhancement can be to give each layer a scrolling offset to have nice
background/foreground effects, with each layer moving at a particular speed.
I didn’t include this in the previous code, because I want to keep it as simple and clear as

All suggestions, comments, help are welcomed !




Envoyez avec Yahoo! Mail. Une boite mail plus intelligente

Hi Julien

This is what I have wanted but never got around to writing! In my opinion this is one of the most important
"missing libraries" from SDL!

I have experience with a library for a “game operating system” I used in a commercial application, the source code was
not available, sadly.

I don’t know if I can be much help but what you are doing certainly looks like the right direction!

Sent from Yahoo! Mail.
A Smarter Email

Hi all,

I’ve quickly written an interface header defining a very basic and generic
system to support multiple layers in SDL, in the form of an SDL_Surface

I don’t like the #define method for determine layers number and blit method,
why not to use a parameter in the create API for the first and a boolean
flag in the display method for the second?On Wed, Jun 11, 2008 at 4:32 PM, julien CLEMENT wrote:


I think it’s pretty useful. I don’t see any accessor functions, though. What kind of design are you going for? That is, are you expecting the programmer to use your struct manually or through functions that you provide? You should go dynamic on all your options, since you shouldn’t force the programmer to use only one layered display nor to have each one with the same settings. Also, I would suggest that the 255 layer limit be adjustable. Sure, a Uint8 would be nice, but if you’re using the layers as sprites, you might need more. I suggest adding a #define for using Uint16 or Uint32 instead. Then you could write your function signatures like ‘void fn(UintXX layerNum)’, where the UintXX is defined to be whatever you want. You would probably want to rename UintXX as something more unique, though.

Jonny D