SDL:Tutorials:Initializing SDL Libraries

From GPWiki

SDL video

SDL video is probably the thing that you're mainly after. This handles all the graphical side of your programming, such as blitting (drawing), alpha blending (with ease!), transparency, 3D, and more! Best of all, it is supported on most operating systems. So what can it do? (From the SDL Website) Here are some things that might interest you:

1. Set a video mode at any depth (8-bpp or greater) with optional conversion, if the video mode is not supported by the hardware.
2. Write directly to a linear graphics framebuffer.
3. Create surfaces with colorkey or alpha blending attributes.
4. Surface blits are automatically converted to the target format using optimized blitters and are hardware accelerated, when possible. MMX optimized blits are available for the x86.
5. Hardware accelerated blit and fill operations are used if supported by the hardware.

Now I think it's time to get this beast up and running with minimal effort!

Tutorial

The first thing you must do is add the directory with the SDL header files to your include path in your IDE.

Next, you must declare everything you're going to use.

Note: C++ is case sensitive! You might want to keep everything lowercase :) (or upper!)

#include <cstdlib> // For some useful functions such as atexit :)
#include "SDL.h" // main SDL header
 
#define SCREEN_WIDTH 640
#define SCREEN_HEIGHT 480
 
SDL_Surface *screen; //This pointer will reference the backbuffer 

Now for the main thing...

int InitVideo(Uint32 flags = SDL_DOUBLEBUF | SDL_FULLSCREEN) {
  // Load SDL
  if (SDL_Init(SDL_INIT_VIDEO) != 0) {
    fprintf(stderr, "Unable to initialize SDL: %s\n", SDL_GetError());
    return false;
  }
  atexit(SDL_Quit); // Clean it up nicely :)
 
  // fullscreen can be toggled at run time :) any you might want to change the flags with params?
  //set the main screen to SCREEN_WIDTHxSCREEN_HEIGHT with a colour depth of 16:
  screen = SDL_SetVideoMode(SCREEN_WIDTH, SCREEN_HEIGHT, 16, flags);
  if (screen == NULL) {
    fprintf(stderr, "Unable to set video mode: %s\n", SDL_GetError());
    return false;
  }
  return true;
}

Setting window manager properties

Talking to the window manager is extremely easy. Here is a list of functions:

• SDL_WM_SetCaption — Sets the window tile and icon name.
• SDL_WM_GetCaption — Gets the window title and icon name.
• SDL_WM_SetIcon — Sets the icon for the display window.
• SDL_WM_IconifyWindow — Iconify/Minimise the window.
• SDL_WM_ToggleFullScreen — Toggles fullscreen mode.
• SDL_WM_GrabInput — Grabs mouse and keyboard input.

If you're using a window for your display then you're probably most interested in SDL_WM_SetCaption and WM_SetIcon.

SDL_WM_SetCaption

SDL_WM_SetCaption("Window Title","Icon Title");

The Window Title is the title that is on the top of the window in the titlebar. The Icon Title is the name it is given when refering to it in the system. {Check?}
(In linux, at least in GNOME, the Icon Title shows up in the task bar while the window title shows up in the title bar [yay, I checked something ^_^]) (on OS X, at least in Tiger ;->, the Icon Title shows up when you hover over the app's dock icon [yay, I checked something, too!])

SDL Audio with SDL_mixer

#include "SDL_mixer.h" 

int InitAudio() {
  //Load Audio Support
  if(SDL_Init(SDL_INIT_AUDIO) != 0) {
    fprintf(stderr, "Warning: unable to initialize audio: %s\n", SDL_GetError());
    return false;
  }
 
  if (Mix_OpenAudio(11025, AUDIO_S16, 2, 512) < 0) {
    fprintf(stderr, "Warning: Audio could not be setup for 11025 Hz 16-bit stereo.\nReason: %s\n", SDL_GetError());
    return false;
  }
  return true;
}

Fonts with SDL_ttf

SDL, itself, doesn't handle fonts, but there is an extension, SDL_ttf, that makes it possible to use fonts. SDL_ttf is a wrapper around FreeType.

Includes:

#include "SDL_ttf.h" 

int InitTTF() {
  if(TTF_Init()==-1) {
    fprintf(stderr, "Error: unable to initialize TTF_SDL, %s\n", TTF_GetError());
    return false;
  }
  atexit(TTF_Quit);
  return true;
}

Networking with SDL_net

#include "SDL_net.h" 

int InitNet() {
  if(SDLNet_Init()==-1) {
    fprintf(stderr, "Error: unable to initialize SDL networking, %s\n", SDLNet_GetError());
    return false;
  }
  atexit(SDLNet_Quit);
  return true;
}

A note about the headers and sdl-config

I'm adding here a note about the header inclusion of SDL and SDL_* libraries, since I see confusions in some SDL Sources I saw.

SDL is a portable library, portable means that it runs on many different systems, and as you may think each system can have a different path for SDL headers. The common mistake is to do

#include <SDL/SDL.h>

(I did this error too), but this isn't correct: actually SDL library can be installed in different position, and the path to the SDL/SDL.h file may be wrong on some systems.

To avoid this problem the SDL team made a tool which can be used to get the correct path for the current system: sdl-config.

You can use

sdl-config --cflags

to get the path for the headers, and use

sdl-config --libs

to get the path for the libraries.

Of couse you can't do something like

#include "path/to/SDL.h" 

so SDL team say that "SDL.h" must be used as the portable way to include libSDL headers, and then you specify the include path - got with sdl-config - at compile time.

Another note is about the sdl-config itself: on some systems (like FreeBSD), the executable name is different (sdl-config11 in the case of FreeBSD). So another convention has been set: the name of the executable file is sdl-config by default, BUT can be set an override enviroment variable called SDL_CONFIG.

To summarize, you should build a code like this

#include "SDL.h"
#include "SDL_*.h" 

and compile it with (in pseudo-shell-code)

if the env-var $SDL_CONFIG is empty
then set SDL_CONFIG="sdl-config"

CFLAGS=<execute command $SDL_CONFIG --cflags>
LFLAGS=<execute command $SDL_CONFIG --libs> + <additional SDL_* libraries>

compile $CFLAGS source.c $LFLAGS

This way is the most portable actually. Of course it's good to use config and makefiles to improve the portability.