Hello SDL

We now have an empty project, which links to the SDL library, so it is time to start our SDL development. Click on Source Files and use the keyboard shortcut Ctrl + Shift + A to add a new item. Create a C++ file called main.cpp. After creating this file, copy the following code into the source file:

#include<SDL.h>

SDL_Window* g_pWindow = 0;
SDL_Renderer* g_pRenderer = 0;

int main(int argc, char* args[])
{
  // initialize SDL
  if(SDL_Init(SDL_INIT_EVERYTHING) >= 0)
  {
    // if succeeded create our window
    g_pWindow = SDL_CreateWindow("Chapter 1: Setting up SDL", 
    SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED,
    640, 480, 
    SDL_WINDOW_SHOWN);

    // if the window creation succeeded create our renderer
    if(g_pWindow != 0)
    {
      g_pRenderer = SDL_CreateRenderer(g_pWindow, -1, 0);
    }
  }
  else
  {
    return 1; // sdl could not initialize
  }

  // everything succeeded lets draw the window

  // set to black // This function expects Red, Green, Blue and 
  //  Alpha as color values
  SDL_SetRenderDrawColor(g_pRenderer, 0, 0, 0, 255);

  // clear the window to black
  SDL_RenderClear(g_pRenderer);

  // show the window
  SDL_RenderPresent(g_pRenderer);

  // set a delay before quitting
  SDL_Delay(5000);

  // clean up SDL
  SDL_Quit();

  return 0;
}

We can now attempt to build our first SDL application. Right-click on the project and choose Build. There will be an error about the SDL.dll file not being found:

The attempted build should have created a Debug or Release folder within the project directory (usually located in your Documents folder under visual studio and projects). This folder contains the .exe file from our attempted build; we need to add the SDL.dll file to this folder. The SDL.dll file is located at C:\SDL2\VisualC\SDL\Win32 (or x64)\Release\SDL.dll l). When you want to distribute your game to another computer, you will have to share this file as well as the executable. After you have added the SDL.dll file to the executable folder, the project will now compile and show an SDL window; wait for 5 seconds and then close.

An overview of Hello SDL

Let's go through the Hello SDL code:

1. First, we included the SDL.h header file so that we have access to all of SDL's functions:

   #include<SDL.h>

2. The next step is to create some global variables. One is a pointer to an SDL_Window function, which will be set using the SDL_CreateWindow function. The second is a pointer to an SDL_Renderer object; set using the SDL_CreateRenderer function:

   SDL_Window* g_pWindow = 0;
   SDL_Renderer* g_pRenderer = 0;

3. We can now initialize SDL. This example initializes all of SDL's subsystems using the SDL_INIT_EVERYTHING flag, but this does not always have to be the case (see SDL initialization flags):

   int main(int argc, char* argv[])
   {
     // initialize SDL
     if(SDL_Init(SDL_INIT_EVERYTHING) >= 0)
      {

4. If the SDL initialization was successful, we can create the pointer to our window. SDL_CreateWindow returns a pointer to a window matching the passed parameters. The parameters are the window title, x position of the window, y position of the window, width, height, and any required SDL_flags (we will cover these later in the chapter). SDL_WINDOWPOS_CENTERED will center our window relative to the screen:

   // if succeeded create our window
   g_pWindow = SDL_CreateWindow("Chapter 1: Setting up SDL", SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED, 640, 480, SDL_WINDOW_SHOWN);

5. We can now check whether the window creation was successful, and if so, move on to set the pointer to our renderer, passing the window we want the renderer to use as a parameter; in our case, it is the newly created g_pWindow pointer. The second parameter passed is the index of the rendering driver to initialize; in this case, we use -1 to use the first capable driver. The final parameter is SDL_RendererFlag (see SDL renderer flags):

   // if the window creation succeeded create our renderer
   if(g_pWindow != 0)
   {
     g_pRenderer = SDL_CreateRenderer(g_pWindow, -1, 0);
   }
   else
   {
     return 1; // sdl could not initialize
   }

6. If everything was successful, we can now create and show our window:

   // everything succeeded lets draw the window
   
     // set to black
   SDL_SetRenderDrawColor(g_pRenderer, 0, 0, 0, 255);
   
      // clear the window to black
   SDL_RenderClear(g_pRenderer);
   
      // show the window
   SDL_RenderPresent(g_pRenderer);
   
      // set a delay before quitting
   SDL_Delay(5000);
   
      // clean up SDL
   SDL_Quit();

SDL initialization flags

Event handling, file I/O, and threading subsystems are all initialized by default in SDL. Other subsystems can be initialized using the following flags:

Flag	Initialized subsystem(s)
SDL_INIT_HAPTIC	Force feedback subsystem
SDL_INIT_AUDIO	Audio subsystem
SDL_INIT_VIDEO	Video subsystem
SDL_INIT_TIMER	Timer subsystem
SDL_INIT_JOYSTICK	Joystick subsystem
SDL_INIT_EVERYTHING	All subsystems
SDL_INIT_NOPARACHUTE	Don't catch fatal signals

We can also use bitwise (|) to initialize more than one subsystem. To initialize only the audio and video subsystems, we can use a call to SDL_Init, for example:

SDL_Init(SDL_INIT_AUDIO | SDL_INIT_VIDEO);

Checking whether a subsystem has been initialized or not can be done with a call to the SDL_WasInit() function:

if(SDL_WasInit(SDL_INIT_VIDEO) != 0)
{
  cout << "video was initialized";
}

SDL renderer flags

When initializing an SDL_Renderer flag, we can pass in a flag to determine its behavior. The following table describes each flag's purpose:

Flag	Purpose
SDL_RENDERER_SOFTWARE	Use software rendering
SDL_RENDERER_ACCELERATED	Use hardware acceleration
SDL_RENDERER_PRESENTVSYNC	Synchronize renderer update with screen's refresh rate
SDL_RENDERER_TARGETTEXTURE	Supports render to texture