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.

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:

We react to any events that happened, such as the user pressing keyboard buttons and clicking on things
We update the objects that our program is managing
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" it. 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.

Diagram showing an event loop interacting with an event 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.

Output Parameters

The design pattern where a function communicates with its caller by modifying an argument it provided is used very frequently in SDL's API. This design is sometimes referred to as an output parameter, or out parameter. In C++, output parameters are implemented as non-const references or, in the case of SDL_PollEvent(), a pointer to a non-const object.

When designing our own programs, output parameters are generally something to avoid. It's more intuitive to have a function communicate with it's caller by returning a value.

The main benefit of output parameters is performance - updating an existing object is often faster than creating a new one. So, we may want to consider using an output parameter design in scenarios where our function is updating some large object that the caller provides, or when our function is being called very frequently.

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 data that it popped from the queue. We'll see how to react to events in the next section.

Application Loops: Common Mistakes

It's fairly common for our initial attempts at application loops to be flawed. We may also not notice that something is wrong as, when our program is simple, a flawed application loop may seem to be working correctly.

Let's take a look at two of the most common mistakes. First, we have this:

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

This loop forces the application loop and event loop to be in lockstep. This is problematic because, when no events are happening, our objects will not update. Many objects, such as those playing animations, want to be updating even when no events are happening.

Another example of a flawed application loop might look something like this:

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

The application fixes the previous problem - it will now update even when the event queue is empty. However, in this case, a maximum of one event can be processed on every iteration of our main loop.

When lots of events are happening, this means there can be a significant delay between each event and our application's reaction to it. These delays make our program less responsive.

We should make sure our application loop follows the nested loop pattern we introduced in this lesson:

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}

This ensures our application loop will iterate even when no events are happening and, when multiple events occur in quick succession, all of them can be handled within the same iteration of our application loop.

Comparing `SDL_PollEvent()` and `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 we can inspect to 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
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.

This causes our main loop to iterating, which means our main function will 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}

Preview

Pushing Events and Custom Event Types

We're not limited to just reading events from the SDL event queue. We can also add events to it, using SDL_PushEvent().

The SDL_Event class has several constructors we can use. The most simple one accepts a single argument - the type of event we want to create, such as SDL_QUIT.

Here's an example of how we can push an SDL_QUIT event onto the queue:

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

We can push an event like this from anywhere in our application. For example, we might have a custom quit button in our UI that could push this event. Then, once our event loop sees it, it will terminate the main loop and shut our program down.

We can also use the SDL event queue for custom event types, specific to our application. This might include events for when the player completes a level or gains a powerup.

We'll be using this in our later projects as, whenever we're managing a large collection of objects, an event queue is a useful pattern for letting disparate parts of our application communicate with each other.

Complete Code

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

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.

Implementing an Application Loop

Starting Point

The Application Loop

Events

Handling Events

Creating an Event Loop

Comparing `SDL_PollEvent()` and `SDL_PumpEvents()`

Event Types

Quitting the Application

Complete Code

Summary

Double Buffering

Game Development with SDL2

Questions & Answers

Implementing an Application Loop

Starting Point

The Application Loop

Events

Handling Events

Creating an Event Loop

Comparing SDL_PollEvent() and SDL_PumpEvents()

Event Types

Quitting the Application

Complete Code

Summary

Double Buffering

Questions & Answers

Comparing `SDL_PollEvent()` and `SDL_PumpEvents()`