Implementing an Application Loop

This lesson explains the fundamental concept of the application loop – the engine that drives real-time programs. You'll learn how SDL manages events, how to poll the event queue to react to user input, and how to correctly structure your loop to handle window closing requests.

Starting Point

We’ll continue working on our main.cpp and Window.h files from earlier. Their current state is provided below.

1#include <SDL.h>
2#include "Window.h"
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6  Window GameWindow;
7
8  while (true) {
9    SDL_PumpEvents();
10  }
11
12  SDL_Quit();
13  return 0;
14}

1// Window.h
2#pragma once
3#include <iostream>
4#include <SDL.h>
5
6class Window {
7public:
8  Window(){
9    SDLWindow = SDL_CreateWindow(
10      "Hello Window",
11      SDL_WINDOWPOS_UNDEFINED,
12      SDL_WINDOWPOS_UNDEFINED,
13      700, 300, 0
14    );
15
16    SDL_FillRect(
17      GetSurface(),
18      nullptr,
19      SDL_MapRGB(
20        GetSurface()->format, 50, 50, 50
21      )
22    );
23
24    SDL_UpdateWindowSurface(SDLWindow);
25    
26  }
27
28  SDL_Surface* GetSurface() const {
29    return SDL_GetWindowSurface(SDLWindow);
30  }
31  
32  Window(const Window&) = delete;
33  Window& operator=(const Window&) = delete;
34  
35  ~Window() {
36    if (SDLWindow && SDL_WasInit(SDL_INIT_VIDEO)) {
37      SDL_DestroyWindow(SDLWindow);
38    }
39  }
40  
41private:
42  SDL_Window* SDLWindow{nullptr};
43};

The Application Loop

From a high level, we can imagine our main function has three main areas. An area where we initialize things and create our objects, followed by a loop, followed by an area where we shut things down.

1int main(int argc, char** argv) {
2  // Initialization
3  // ...
4  
5  // Loop
6  while (true) {
7    // ...
8  }
9  
10  // Shutdown
11  // ...
12  return 0;
13}

These three components are the standard, high-level structure of all desktop applications, mobile apps, games, and any other type of program that is designed to continue running until the user asks it to close.

In this lesson, we’ll focus on the loop part. In this high level design, the loop that keeps our program running is often called the main loop, the application loop, or, if our program is a game, the game loop.

Within each iteration of the main loop, we perform three actions in order:

1. We react to any events that happened, such as the user pressing keyboard buttons and clicking on things
2. We update the objects that our program is managing
3. We render some visual output to the screen so the user can see the changes

1int main(int argc, char** argv) {
2  // Initialization
3  // ...
4  
5  while (true) {
6    // 1. Process Events
7    // 2. Update Objects
8    // 3. Render Changes
9  }
10  
11  // Shutdown
12  // ...
13  return 0;
14}

If we design our application well and optimize the performance of its various components, our program can complete dozens or even hundreds of iteration of this loop every second.

This means that the player can perform some action and, within a few milliseconds, the effect of that action is visible on the screen. From a player’s perspective, a few milliseconds isn’t noticable - it may as well be instantenous, so we’ve created the illusion that they’re interacting with our program in "real time".

Events

In this lesson, we’ll focus on the first part of the application loop - processing events. SDL uses an extremely common way of managing events, called an event queue.

An queue is a data structure, similar to an array, but designed in such a way that objects get added to the structure at one side, and removed at the other. Conceptually, an "event" is something that happened in our program, but in code, it’s just an object.

Like any object, it contains some member variables that help us understand what happened. SDL’s type for representing events is an SDL_Event, which we’ll work with soon.

Adding an object to a queue is typically called "pushing" it, whilst removing and processing an event is often called "popping", respectively. We push events to the back of the queue, and pop them from the front:

To make our application react to the events that are happening, we repeatedly look at the front of the queue. If there’s an event there, we pop it from the queue, react accordingly to it, and then move on to the next event.

The code we write that repeatedly checks the front of the queue for events is an event loop. On every iteration, it pops an event, examines it, and reacts appropriately. It continues iterating until there are no more events in the queue.

Handling Events

Currently, the only thing in our application loop is a call to SDL_PumpEvents():

1#include <SDL.h>
2#include "Window.h"
3
4int main(int argc, char** argv) {
5  // Initialization
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8
9  while (true) {
10    // 1. Process Events
11    SDL_PumpEvents();
12    
13    // 2. Update Objects
14    // ...
15    
16    // 3. Render Changes
17    // ...
18  }
19  
20  // Shutdown
21  SDL_Quit();
22  return 0;
23}

This invocation tells SDL "we’re doing an iteration of our application loop right now - handle your events". Behind the scenes, SDL runs its event loop and processes all the events in its queue.

This is important - for SDL to work correctly, we must prompt it to process its events on every iteration of its application loop.

However, in most programs, we also want the opportunity to react to those events. If the user clicked their mouse somewhere in our window, that means they probably want our program to do something.

For visibility of events, we need to replace SDL_PumpEvents() with our own event loop.

Creating an Event Loop

If we want to see what events are happening in our program, we can use SDL_PollEvent(). This function pops the next event from SDL’s event queue, and lets us examine it.

To use SDL_PollEvent(), we need to create an SDL_Event object beforehand, and then pass it’s pointer to SDL_PollEvent():

1SDL_Event Event;
2SDL_PollEvent(&Event);

The SDL_PollEvent() call will update our Event object with details of the event that it popped off the queue. We can then examine that object and decide what action, if any, we need to take.

There are two additional things to note about SDL_PollEvent():

• SDL_PollEvent() returns true if there was an event in the queue awaiting processing, and false if the queue was empty
• Multiple events can happen within the same iteration of our loop, so we need to call SDL_PollEvent() repeatedly on every iteration until it returns false

This means that an application loop that includes SDL_PollEvent() will look something like this:

1#include <SDL.h>
2#include "Window.h"
3
4int main(int argc, char** argv) {
5  // Initialization
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8  
9  SDL_Event Event;
10  while (true) {
11    // 1. Process Events
12    while (SDL_PollEvent(&Event)) {
13      // Examine the Event object and react
14    }
15    
16    // 2. Update Objects
17    // ...
18    
19    // 3. Render Changes
20    // ...
21  }
22  
23  // Shutdown
24  SDL_Quit();
25  return 0;
26}

That is, on every iteration of our application loop, we have an inner loop that continues until all of the outstanding events are processed - that is, until SDL_PollEvent() returns false.

On every iteration of this inner event loop, we have the opportunity to react to an individual event. That is, the Event object that we originally created, and that SDL_PollEvent() has just updated with the event it popped from the queue. We’ll see how to react to events in the next section.

1while(true) {
2  while(SDL_PollEvent(&Event)) {
3    // 1. Process Event
4    // 2. Update Objects
5    // 3. Render Changes
6  }
7}

1while(true) {
2  SDL_PollEvent(&Event);
3  // 1. Process Event
4  // 2. Update Objects
5  // 3. Render Changes
6}

1while(true) {
2  // 1. Process all the events
3  while(SDL_PollEvent(&Event)) {
4    // ....
5  }
6
7  // 2. Update Objects
8  // 3. Render Changes
9}

SDL_PollEvent() vs SDL_PumpEvents()

If we decide we no longer need to handle events, we shouldn’t just delete our event handling. Instead, we should go back to using SDL_PumpEvents().

For SDL to work correctly, we must prompt it to process its events at the appropriate time - that is, on every iteration of our application loop. If we don’t care what the events are, we should call SDL_PumpEvents():

1while(true) {
2  // 1. Process all the events
3  SDL_PumpEvents();
4
5  // 2. Update Objects
6  // 3. Render Changes
7}

If we do care, we should call SDL_PollEvent() repeatedly until it returns false:

1while(true) {
2  // 1. Process all the events
3  while(SDL_PollEvent(&Event)) {
4    // ....
5  }
6
7  // 2. Update Objects
8  // 3. Render Changes
9}

Event Types

Now that we’re getting information on every event flowing through the system, it’s time to react to them. The first thing we need to understand is whether the event we’re currently processing is something we care about.

Our application loop can get quite complex, so if we have a lot of different things we need to react to, we should consider offloading that to a new function:

1#include <SDL.h>
2#include "Window.h"
3
4void HandleEvent(SDL_Event& E) {
5  // ... 
6}
7
8int main(int argc, char** argv) {
9  SDL_Init(SDL_INIT_VIDEO);
10  Window GameWindow;
11  
12  SDL_Event Event;
13  while (true) {
14    while (SDL_PollEvent(&Event)) {
15      HandleEvent(Event);
16    }
17  }
18  
19  SDL_Quit();
20  return 0;
21}

SDL_Event objects have a type field, that let’s us get an initial understanding of what type of event we’re dealing with. SDL provides a range of helper values that we can compare against for specific event types we’re interested in. For example:

1#include <SDL.h>
2#include "Window.h"
3
4void HandleEvent(SDL_Event& E) {
5  if (E.type == SDL_MOUSEMOTION) {
6    std::cout << "Mouse moved\n";
7  } else if (E.type == SDL_MOUSEBUTTONDOWN) {
8    std::cout << "Mouse clicked\n";
9  } else if (E.type == SDL_KEYDOWN) {
10    std::cout << "Keyboard button pressed\n";
11  }
12}
13
main Function (Unchanged)|Show
14int main(int argc, char** argv) {/*...*/}

If we move our mouse around and press some buttons, we should now see that activity being detected in our program:

1Mouse moved
2Mouse moved
3Mouse clicked
4Keyboard button pressed
5Mouse moved

These various event types have further properties, letting us understand things like which button was pressed, or where the mouse moved to. We’ll cover the most useful event types throughout this course, but a full list is also available on the official documentation.

Quitting the Application

We finally know everything we need to know to let users close our application. When the player requests our game close by, for example, clicking the "x" in the title bar, SDL pushes an event onto the queue. It has a type of SDL_QUIT:

1#include <SDL.h>
2#include "Window.h"
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6  Window GameWindow;
7  
8  SDL_Event Event;
9  while (true) {
10    while (SDL_PollEvent(&Event)) {
11      if (Event.type == SDL_QUIT) {
12        // User wants to quit...
13      }
14    }
15  }
16  
17  SDL_Quit();
18  return 0;
19}

To handle this, let’s add a new shouldContinue boolean initialized to true, and update our application loop from while(true) to while(shouldContinue). When the player wants to quit, we’ll set shouldContinue to false, causing the loop to end:

1#include <SDL.h>
2#include "Window.h"
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6  Window GameWindow;
7  
8  SDL_Event Event;
9  bool shouldContinue{true};
10  while (shouldContinue) {
11    while (SDL_PollEvent(&Event)) {
12      if (Event.type == SDL_QUIT) {
13        shouldContinue = false;
14      }
15    }
16  }
17  
18  SDL_Quit();
19  return 0;
20}

As with anything, there are multiple ways we could have handled this. We could alternatively call SDL_Quit() and return 0 from our application loop:

1#include <SDL.h>
2#include "Window.h"
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6  Window GameWindow;
7  
8  SDL_Event Event;
9  bool shouldContinue{true};
10  while (true) {
11    while (SDL_PollEvent(&Event)) {
12      if (Event.type == SDL_QUIT) {
13        SDL_Quit();
14        return 0;
15      }
16    }
17  }
18  
19  SDL_Quit();
20  return 0;
21}

1SDL_Event QuitEvent { SDL_QUIT };
2SDL_PushEvent(&QuitEvent);

Complete Code

Our latest files, which we’ve updated with the event loop and SDL_QUIT handling, are below:

1#include <SDL.h>
2#include "Window.h"
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6  Window GameWindow;
7
8  SDL_Event Event;
9  while (true) {
10    while (SDL_PollEvent(&Event)) {
11      if (Event.type == SDL_QUIT) {
12        SDL_Quit();
13        return 0;
14      }
15    }
16  }
17
18  return 0;
19}

1#pragma once
2#include <iostream>
3#include <SDL.h>
4
5class Window {
6public:
7  Window(){
8    SDLWindow = SDL_CreateWindow(
9      "Hello Window",
10      SDL_WINDOWPOS_UNDEFINED,
11      SDL_WINDOWPOS_UNDEFINED,
12      700, 300, 0
13    );
14
15    SDL_FillRect(
16      GetSurface(),
17      nullptr,
18      SDL_MapRGB(
19        GetSurface()->format, 50, 50, 50
20      )
21    );
22
23    SDL_UpdateWindowSurface(SDLWindow);
24  }
25
26  SDL_Surface* GetSurface() const {
27    return SDL_GetWindowSurface(SDLWindow);
28  }
29  
30  Window(const Window&) = delete;
31  Window& operator=(const Window&) = delete;
32  
33  ~Window() {
34    if (SDLWindow && SDL_WasInit(SDL_INIT_VIDEO)) {
35      SDL_DestroyWindow(SDLWindow);
36    }
37  }
38  
39private:
40  SDL_Window* SDLWindow{nullptr};
41};

Summary

This lesson covered implementing the main application loop in SDL. We discussed the standard structure (initialize, loop, shutdown) and the loop's core tasks: handling events, updating game state, and rendering.

We focused on event handling, using SDL_PollEvent() within a nested loop to process all events from SDL's queue and specifically reacting to the SDL_QUIT event to enable application closure.

Key Takeaways:

• Desktop applications rely on a continuous main loop.
• The loop structure is typically: Process Events -> Update -> Render.
• Events are managed in a queue; SDL_PollEvent() retrieves them.
• Use a while loop with SDL_PollEvent() to empty the event queue each frame.
• SDL_Event objects contain details about each event, including its type.
• Handle SDL_QUIT to allow the application to close cleanly.
• Remember to call SDL_PumpEvents() or SDL_PollEvent() in every iteration of your main loop.

Free and Unlimited Access

Professional C++

Unlock the true power of C++ by mastering complex features, optimizing performance, and learning expert workflows used in professional development

View Course