Distortion is cool, everybody knows that. Not many things are cooler than watching everything blur behind a jet engine and even fewer things are more soothing than watching the wall behind the heater move around a bit. Distortions like the ones seen behind the engines of a jet are rarely seen in games (nor the heater, but that's probably for a different reason), especially so in open source games. This library will provide the means to create such distortions.

SDL_mad is a tiny library for adding some distortion to ones favourite SDL game, application or demo. Basically it is a graphics transformation matrix (mad: Mangling and Distorting). Not much excitement there, one could build one in half an hour. However, as laziness prescribes, a coder isn't going to waste its time filling the transformation matrix. This is where years of SDL_mad research come in. The idea behind SDL_mad is to be able to use distortion filters from The Gimp, or any photo/graphics editor for that matter, and apply them realtime to your graphics.

Contents

The big idea

Many great minds have written distortion filters. So why write new ones? Because one can do better, of course, but does one really want to? The answer is simply, no. It just wouldn't be ethical (lazy) or coder like (lazy). So, there is a need to convert these existing distortion filters to real time ones, usable in games and such: thus SDL_mad was born. It creates an image which contains the source coordinates for each pixel, so when the pixels are moved around by a photo/image editor, the library can still find where they came from. The moving around is done by the distortion filter of the photo/image editor. With the new coordinates of the pixel, and the source coordinates of the pixel, the library can figure out what the distortion filter did and apply the same distortion to any image thrown at it, real time. Of course this effect will not be photo-quality, but no one will notice since the effect (or the image the effect is applied on) will be moving around, effectively making the distortion change all the time.

Download

The latest version available for download is 0.1.0

Requirements

The library SDL_mad only requires libSDL and sdl-config script to be in the PATH. If its not, either adjust the PATH or edit the Makefile.

The createmask tool requires libpng. If it's in the standard library and include paths everything should be fine, if it's not you need to edit the Makefile and add the paths to the -L and -I flags.

The madtest tool requires SDL_image for loading the .png masks.

Usage

The library itself is very easy to use, see the code example section for more info. Along with the library included are 2 tools, createmask and madtest. Run these tools without any arguments to get the usage information. The createmask tool creates an undistorted mask which can be opened in The Gimp (for instance) to apply distortion filters on. The madtest tool will display an image and move the specified mask(s) over it.

Example

Below are two examples rendered by madtest. The masks were created by applying the whirl and the lens filters of The Gimp to a 100x100 pixel mask.

Code example

In order to use the example below, the SDL_Surface "screen" must exist and be the surface returned by SDL_SetVideoMode(). Also the line #include "SDL_mad.h" must be somewhere under the #include "SDL.h" line. See madtest.c for a more thorough example.

                SDL_Surface *mask_image;
                MAD_mask *mask;
                SDL_Rect dest;
                
                // Create the mask
                mask_image = IMG_LoadImage("mask.png");
                mask = MAD_create(mask_image);
                SDL_FreeSurface(mask_image);
                
                // Apply the mask
                dest.x = 10;
                dest.y = 10;
                MAD_apply(screen, mask, &dest);
                
                // Free the mask
                MAD_free(mask);

Building and installing

A simple "make" should do, if not see the requirements section. There hasn't been time to build a complete autoconf/automake script yet and uncertainty exists over the usefulness of such a script for this library. The library is so small it's probably easiest to just add the libSDL_mad.c/h files to the project.

Roadmap

What needs to be done before version 1.0.0:

  • The 2x scaler to allow for 1024x1024 distortions
  • Optimize

News

2006-02-03 Version 0.1.0 is ready for download, happily mangling and distorting.

License

SDL_mad is distributed under the terms of the GNU General Public License. See the file COPYING in the distribution for the terms. GNU also has an FAQ available, explaining what you can and cannot do.