[SDL] Layered display

[julien CLEMENT]

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 (http://www.libsdl.org)
 *  @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:
 *          clementj2005 at yahoo.fr
 */

/** 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.
 */
#ifndef SDL_LAYERED_DISPLAY_N_LAYERS
#define SDL_LAYERED_DISPLAY_N_LAYERS    3
#endif

/** 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.
 */
#ifndef SDL_LAYERED_DISPLAY_USE_DIRTY_RECTANGLES
#define SDL_LAYERED_DISPLAY_USE_DIRTY_RECTANGLES
#endif

/** @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_
{
    SDL_Surface    *    layers[SDL_LAYERED_DISPLAY_N_LAYERS];
    Uint8            n_layers;

#ifdef SDL_LAYERED_DISPLAY_USE_DIRTY_RECTANGLES
    SDL_Rect        refresh_rects[255];
    Uint8            n_refresh_rects;
#endif

};

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);

#endif

------------------- 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
possible.

All suggestions, comments, help are welcomed !

Regards,

Julien.



      _____________________________________________________________________________ 
Envoyez avec Yahoo! Mail. Une boite mail plus intelligente http://mail.yahoo.fr
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.libsdl.org/pipermail/sdl-libsdl.org/attachments/20080611/8e94c706/attachment.htm>