Implementing an Application Loop

The first step of implementing any application is writing the foundational code that keeps the program running until we or the user decide it’s time to quit. This code is often called the application loop, main loop, or, if we’re making a game, the game loop.

Typically, every iteration of the loop involves 3 steps:

1. Process any events, such as user input. This involves a second, nested loop often called the event loop.
2. Ask all of our objects to update themselves, ready to be rendered to the screen. Any events that occurred in step 1 can influence this process
3. Render a new frame to the screen, so the user can see the changes.

1int main() {
2  while(true) {
3    // 1. Handle Events
4    while(GetUnhandledEvent()) {
5      // Process event
6      // ...
7    }
8    
9    // 2. Update Objects
10    // ...
11    
12    // 3. Render Frame
13    // ...
14  }
15}

Each iteration of this outer loop happens extremely quickly. The faster each iteration runs, the higher our application’s frame rate will be. Higher frame rates make our application feel more responsive to user input.

For example, the minimum frame rate that is typically considered acceptable is 30 frames per second. To achieve that, we need to complete each iteration of our loop within 33 milliseconds - that is 1000ms / 30.

If we want 60 frames per second, we only have 16 milliseconds per frame: 1000ms / 60.

The Event Queue and Event Loop

In this lesson and the next, we’ll focus on the "process any events" part of the application loop. We’ll cover updating objects and rendering them to the screen in the following chapters.

It’s worth exploring this event-handling aspect a little deeper. SDL uses an extremely common way of managing events, called an event queue.

An event 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.

These actions are typically called "pushing" and "popping", respectively. We push events to the back of the queue, and pop them from the front:

Any time an event occurs, an object representing that event gets added to the back of this queue.

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 delete it.

The code we write that repeatedly checks the front of the queue for events is an event loop.

Creating the SDL Application Loop and Event Loop

Let's take a look at a minimalist application loop using SDL2:

1#include <SDL.h>
2
Window Class|Show
3class Window {/*...*/};
28
29int main(int argc, char** argv) {
30  Window GameWindow;
31  SDL_Event Event;
32
33  // Application Loop
34  while(true) {
35    // Event Loop
36    while(SDL_PollEvent(&Event)) {
37      // 1. Handle Event
38      // ...
39    }
40    
41    // 2. Update Objects
42    // ...
43    
44    // 3. Render Frame
45    GameWindow.RenderFrame();
46  }
47
48  SDL_Quit();
49  return 0;
50}

Note that this example is using the Window class and related techniques we covered in the previous lesson:

Creating a Window

Learn how to create and customize windows, covering initialization, window management, and rendering

We’re handling events in our main function, and the two key components are the SDL_Event object and the SDL_PollEvent() function call. These are how we interact with SDL’s event queue.

• SDL_Event is the base class for all of SDL’s events. It is the type of objects that are on the event queue.
• SDL_PollEvent() is the method whereby we remove the next element in the queue, so we can process it.

To implement SDL_PollEvent(), we must first create an SDL_Event object and then pass its pointer into SDL_PollEvent().

SDL will then update our object with the details of the next event we need to handle, and remove that event from the queue.

When there are no more events to process, SDL_PollEvent() will return 0. So, we can use that return value to determine when our event loop ends for this frame. The official documentation for SDL_Event is available here.

1while(SDL_PollEvent(&Event)) {
2  // 1. Handle Event
3  // 2. Update Everything
4  // 3. Render Frame
5}

1while(true) {
2  SDL_PollEvent(&Event);
3  // 1. Handle Event
4  // 2. Update Everything
5  // 3. Render Frame
6}

1while(true) {
2  // Handle all the events
3  while(SDL_PollEvent(&Event)) {
4    // ...
5    }
6    
7   // Update The Frame
8   GameWindow.RenderFrame();
9}

Handling Events

Once SDL_PollEvent() has updated our event object, it’s time for us to examine that object. We can then determine what action, if any, we need to take.

The first thing we need to do is determine what type of event it is. SDL events have a type property for this:

1#include <SDL.h>
2#include <iostream>
3
Window Class|Show
4class Window {/*...*/};
29
30int main(int argc, char** argv) {
31  Window GameWindow;
32  SDL_Event Event;
33
34  while (true) {
35    while (SDL_PollEvent(&Event)) {
36      std::cout << "\nType: " << Event.type;
37    }
38    
39    GameWindow.RenderFrame();
40  }
41  
42  SDL_Quit();
43  return 0;
44}

We can now run our program and generate some events by performing actions like:

• Moving the mouse around our window
• Clicking mouse buttons or pressing keyboard buttons
• Resizing, moving and trying to close the window

Going so will stream output like the following to our terminal:

1Type: 512
2Type: 770
3Type: 512
4Type: 1024

SDL provides us with variables to help us understand what these integers represent. For example, we can determine if an event represents mouse movement by comparing its type to the SDL_MOUSEMOTION variable.

1Event.type == SDL_MOUSEBUTTONDOWN

We can use this technique to expand our event handling loop with conditional logic, allowing us to programmatically react to different event types:

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == SDL_MOUSEMOTION) {
3    std::cout << "Mouse moved\n";
4  } else if (Event.type == SDL_MOUSEBUTTONDOWN) {
5    std::cout << "Mouse clicked\n";
6  } else if (Event.type == SDL_KEYDOWN) {
7    std::cout << "Keyboard button pressed\n";
8  }
9}

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

We’ll go into much more detail on these events in the next chapter. For now, let’s use these techniques to finally let users close our application.

Quitting the Application

Typically, the first event we’ll want to handle is SDL_QUIT. When we encounter this event, it means something has requested our application close. For example, the user may have clicked the x button on our window’s title bar.

When an attempt is made to close our application, SDL pushes an event to the queue for us to react to:

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == SDL_QUIT) {
3    std::cout << "User wants to quit";
4  }
5  // ... handle other event types
6}

Running our application and trying to quit, we should now see the output:

1User wants to quit

Let’s update our program to handle this. We can do this in three steps:

• Introduce a shouldQuit variable, defaulted to false
• Replace while(true) in our outer application loop with while(!shouldQuit)
• Set shouldQuit to true in our event loop, when we detect the user requested to quit.

Putting everything together, it looks like this:

1#include <SDL.h>
2#include <iostream>
3
Window Class|Show
4class Window {/*...*/};
29
30int main(int argc, char** argv) {
31  Window GameWindow;
32  SDL_Event Event;
33  bool shouldQuit{false};
34
35  while (!shouldQuit) {
36    while (SDL_PollEvent(&Event)) {
37      if (Event.type == SDL_QUIT) {
38        std::cout << "User wants to quit\n";
39        shouldQuit = true;
40      }
41      // ... handle other event types
42    }
43
44    GameWindow.RenderFrame();
45  }
46
47  std::cout << "Goodbye world";
48  SDL_Quit();
49
50  return 0;
51}

Running our program and pressing the quit button, we should see the output we defined, and our program should quit successfully:

1User wants to quit
2Goodbye world

Using Attributes in the Event Loop

Almost by definition, the SDL_QUIT branch of our event loop is only going to happen once. Other events, such as mouse motion, could happen millions of times in our event loop.

As such, we may want to add attributes such as [[unlikely]] to our event loop, providing the compiler with some context that it can use to make optimization decisions:

1while (SDL_PollEvent(&Event)) {
2  if (Event.type == SDL_QUIT) [[unlikely]] {
3    // Handle Quit
4    // ...
5  }
6  // Handle other event types
7  // ...
8}

Attributes

Explore the fundamentals of attributes, including [[nodiscard]], [[likely]], and [[deprecated]]

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

Summary

In this lesson, we set up the foundations for developing an SDL2-based application, focusing on creating an application loop. Here’s a recap of the key topics covered:

• Understanding the Application Loop: We started by discussing the structure of the application loop. This loop is responsible for processing events, updating application state, and rendering.
• Event Handling: The lesson provided a look at how events are managed in SDL2. We explored the event queue mechanism and demonstrated how to handle different types of events, including user input like keyboard and mouse events.
• SDL Event Queue: We delved into the specifics of the SDL event queue, explaining how events are pushed to and popped from the queue using SDL_PollEvent().
• Rendering: We also covered how to manage rendering in sync with the handling of events to maintain smooth visual output.
• Best Practices and Common Mistakes: We discussed several best practices for setting up and using the SDL2 library, as well as common pitfalls to avoid, especially relating to event handling and frame rate management.

This lesson serves as a foundation for further exploration into more complex SDL2 functionalities, which we’ll cover throughout the rest of this course.

Next Lesson

Double Buffering

Learn the essentials of double buffering in C++ with practical examples and SDL2 specifics to improve your graphics projects

ContinueView Course