With SDL2 successfully installed and added to our project, we should now be able to create and manipulate windows.

This lesson goes over the steps in how we can do this. We break down and explain every function in the process, as well as describe the most common options we have for customizing our window.

After installing SDL in the previous chapter, we can now compile and run the following program, and confirm that it creates a window:

1#include <SDL.h>
2#include <SDL_image.h>
3#include <SDL_ttf.h>
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  IMG_Init(IMG_INIT_PNG);
8  TTF_Init();
9    
10  SDL_CreateWindow(
11    "Hello Window",
12    100, 100, 700, 300, 0
13  );
14    
15  while(true) {
16    SDL_PumpEvents();
17  }
18  
19  return 0;
20}

We'll explain every line of this program throughout the first few chapters of this course. For now, let's delete the SDL_image and SDL_ttf lines to keep things simple. SDL_image and SDL_ttf are for rendering images and text respectively. We'll cover that soon, but we don't need it now:

1#include <SDL.h>
2#include <SDL_image.h>
3#include <SDL_ttf.h>
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  IMG_Init(IMG_INIT_PNG);
8  TTF_Init();
9    
10  SDL_CreateWindow(
11    "Hello Window",
12    100, 100, 700, 300, 0
13  );
14    
15  while(true) {
16    SDL_PumpEvents();
17  }
18  
19  return 0;
20}

Note that this example program does not allow itself to be closed. For now, we can close it using our IDE if possible, or force it to close through our operating system (Ctrl + Alt + Del on Windows or Cmd + Option + Esc on macOS).

We'll update our program to support quitting later in this chapter.

Including SDL

In the code examples in this course, we'll be using #include directives in the following form:

1#include <SDL.h>

However, you may need to use an alternative format, such as #include <SDL2/SDL.h>. This depends on how your include directories (sometimes also called search paths) were configured in the previous chapter.

Initializing SDL

Before we use any SDL functions, we need to initialize the library. SDL has a lot of features, and few programs need all of them. As such, the features are broken into subsystems, which allows us to load only the things our program needs.

The first thing we do in our main function is call SDL_Init(), which receives the subsystems we want to initialize as an argument:

1SDL_Init(SDL_INIT_VIDEO);

Here, we're just initializing the video subsystem, which we'll need in almost every lesson in this course. Checking the official documentation, we see that SDL_INIT_VIDEO will also initialize the events subsystem, which we'll be using later in this chapter.

The documentation claims we can initialize multiple subsystems by "OR-ing them together". This refers to the bitwise OR operator, |

So, for example, we could initialize 3 subsystems like this:

1SDL_Init(
2  SDL_INIT_VIDEO |
3  SDL_INIT_AUDIO |
4  SDL_INIT_TIMER
5);

Note, the | operator is not the same as the more common || operator. The single | refers to the bitwise or. It's used quite a lot in SDL, and game development more generally. We can just treat it as a way to combine multiple options but, if you want to go a little deeper on how it works, we cover in more detail here:

Bitwise Operators and Bit Flags

Unravel the fundamentals of bitwise operators and bit flags in this practical lesson

View Related Lesson

Quitting SDL

It's also a best practice to shut down SDL when we no longer need it. We can do this using the SDL_Quit() function.

In most applications that use SDL, we need to keep it running through the entire lifecycle of our program, so we'd only call SDL_Quit() just before our program ends.

Our program doesn't currently end because of the infinite loop, which we'll address soon, but let's just add an unreachable call to SDL_Quit() in the typical place for now:

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

Window Management

As we've likely noticed, programs running on our computer can be opened within their own, dedicated windows. The companies that created the platforms (such as Apple for macOS and Microsoft for Windows) provide APIs to create and manage those windows.

Unfortunately, these APIs are quite complex, and they're also completely different from one platform to the next. If we create an application for Windows by directly using a Windows API, and then wanted to release on macOS too, we'd have a lot of work to do.

One of the main reasons for using SDL that it is cross-platform. If we write code using the SDL APIs then, behind the scenes, SDL can interpret that to work with the Windows API, the macOS API, and about 20 other platforms.

For the rest of this lesson, we'll focus on window creation. Currently, that's done through the SDL_CreateWindow() invocation in our main function. Let's add a dedicated Window class to take care of this, and to keep our main function organized:

1// Window.h
2#pragma once
3#include <SDL.h>
4
5class Window {
6public:
7  Window(){
8    SDL_CreateWindow(
9      "Hello Window",
10      100, 100, 700, 300, 0
11    );
12  }
13};

Our Window constructor is using an SDL function, so ensure SDL is initialized before it runs:

1// main.cpp
2#include <SDL.h>
3#include "Window.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8    
9  SDL_CreateWindow(
10    "Hello Window",
11    100, 100, 700, 300, 0
12  );
13    
14  while(true) {
15    SDL_PumpEvents();
16  }
17  
18  SDL_Quit();
19  return 0;
20}

The Window constructor contains the code we previously had in our main function, so our program should still behave as it did before:

The `SDL_CreateWindow()` Function

We're passing six arguments to our SDL_CreateWindow() function call:

1// Window.h
2#pragma once
3#include <SDL.h>
4
5class Window {
6public:
7  Window(){
8    SDL_CreateWindow(
9      "Hello Window",
10      100, 100, 700, 300, 0
11    );
12  }
13};

Let's break down what these arguments are:

The window title tells the platform what our window should be called. How this is used depends on the underlying platform. For example, it might get displayed on the title bar or in the task bar.
The horizontal position of the window. We've set it to 100 in this example, indicating we want our window to be opened 100 units from the left-most edge of the user's screen
The vertical position of the window. We've set it to 100 in this example, indicating we want it to be opened 100 units from the top edge of the user's screen
The width of the window. In this example, we create a window that is 700 units wide
The height of the window. In this example, we create a window that is 300 units tall
"Flags" to modify the behavior of the window. For now, we've set it to 0 indicating we want to use the default behavior, but we cover this in more detail later in this section

Window Position Helpers

In our previous example, we're opening our window 100 pixels from the left edge of the screen, and 100 pixels from the top edge. These values were chosen somewhat arbitrarily, just so we could get something on the screen.

In most cases, we don't have any specific preference on where our window should open - we'd rather let the platform decide the best place. We can do that by passing SDL_WINDOWPOS_UNDEFINED as the horizontal or vertical position. We'd typically use it for both:

1// Window.h
2#pragma once
3#include <SDL.h>
4
5class Window {
6public:
7  Window(){
8    SDL_CreateWindow(
9      "Hello Window",
10      // Horizontal position
11      SDL_WINDOWPOS_UNDEFINED,
12      // Vertical position
13      SDL_WINDOWPOS_UNDEFINED,
14      700, 300, 0
15    );
16  }
17};

If we want our window to be centered on the screen, we can pass SDL_WINDOWPOS_CENTERED as the horizontal and/or vertical position:

1// Window.h
2#pragma once
3#include <SDL.h>
4
5class Window {
6public:
7  Window(){
8    SDL_CreateWindow(
9      "Hello Window",
10      // Horizontal position
11      SDL_WINDOWPOS_CENTERED,
12      // Vertical position
13      SDL_WINDOWPOS_CENTERED,
14      700, 300, 0
15    );
16  }
17};

Unless we have a compelling reason to specify the position, letting the platform decide using SDL_WINDOWPOS_UNDEFINED is recommended.

Platform owners have often put some thought into what makes for a good user experience. For example, they might open the window near the user's cursor, or they might remember where the user moved the window to the last time they ran our program, and open it in that same position.

Window Flags

The last argument to SDL_CreateWindow(), which we're currently passing 0 to, is for SDL window flags. Window flags give us some control over how our window should behave.

For example, we can make our window resizable by passing SDL_WINDOW_RESIZABLE:

1// Window.h
2#pragma once
3#include <SDL.h>
4
5class Window {
6public:
7  Window(){
8    SDL_CreateWindow(
9      "Hello Window",
10      SDL_WINDOWPOS_UNDEFINED,
11      SDL_WINDOWPOS_UNDEFINED,
12      700, 300,
13      SDL_WINDOW_RESIZABLE
14    );
15  }
16};

Window flags are a bit mask, so we can combine multiple flags using the bitwise | operator. Below, we make our window both resizable and minimized.

1// Window.h
2#pragma once
3#include <SDL.h>
4
5class Window {
6public:
7  Window(){
8    SDL_CreateWindow(
9      "Hello Window",
10      SDL_WINDOWPOS_UNDEFINED,
11      SDL_WINDOWPOS_UNDEFINED,
12      700, 300,
13      SDL_WINDOW_RESIZABLE
14      | SDL_WINDOW_MINIMIZED 
15    );
16  }
17};

The flags we pass to SDL_CreateWindow() only apply to the initial state of the window.

These flags can be changed later - sometimes using specific SDL functions that we'll cover throughout the course, or sometimes SDL will change them automatically.

Whilst our previous window will start minimized, the player can indirectly remove that flag later by, for example, clicking on their window in the taskbar.

The `SDL_WindowFlags` Type

We can store a set of window flags using the SDL_WindowFlags type if needed:

1SDL_WindowFlags Flags{
2  SDL_WINDOW_RESIZABLE | SDL_WINDOW_MINIMIZED
3};

The official documentation lists all of the available flags, and we cover most of them throughout this course.

The `SDL_Window` Type

The SDL_CreateWindow() function returns a pointer to the SDL_Window it created. We should store this pointer, as we need it for future window management. Let's add it as a member variable to our class:

1// Window.h
2#pragma once
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  
16private:
17  SDL_Window* SDLWindow{nullptr};
18};

`SDL_Window` Memory Management

Unfortunately, SDL_Window objects require us to do some memory management. This section may be a little annoying, but don't get too disheartened - it's somewhat uncommon that this level of manual intervention is required.

Behind the scenes, SDL allocates dynamic memory to support each SDL_Window. When we no longer need a window, we need to notify SDL so it can release that memory and prevent a memory leak.

To do this, we call SDL_DestroyWindow(), passing a pointer to the SDL_Window we want to get rid of. Let's add a destructor to our Window class for this:

1// Window.h
2#pragma once
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  
16  ~Window() {
17    SDL_DestroyWindow(SDLWindow);
18  }
19  
20private:
21  SDL_Window* SDLWindow{nullptr};
22};

The Rule of Three

As we're adding a destructor to our class, the rule of three should remind us that we need to consider our copy constructor and assignment operators too. In this case, we don't need our Window objects to be copyable, so we'll simplify things and just delete the copy operations:

1// Window.h
2#pragma once
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  
16  Window(const Window&) = delete;
17  Window& operator=(const Window&) = delete;
18  
19  ~Window() {
20    SDL_DestroyWindow(SDLWindow);
21  }
22  
23private:
24  SDL_Window* SDLWindow{nullptr};
25};

We covered object copying and the rule of three in more detail in our introductory course:

Copy Constructors and Operators

Explore advanced techniques for managing object copying and resource allocation

View Related Lesson

Safety Checks

There are two further scenarios we should consider in our Window memory management, specifically within our destructor:

Our SDL_Window pointer may be a nullptr. It is technically safe to pass a nullptr to SDL_DestroyWindow(), but SDL will report it as an error, so let's not do it. We will introduce SDL errors and why our SDL_Window might be a nullptr later in this chapter.
SDL is no longer initialized - that is, SDL_Quit() has been called. SDL_Quit() will delete all the resources SDL is managing, including windows, and will leave our GameWindow with a dangling pointer. It is not safe to call SDL_DestroyWindow() on a dangling pointer, so we should check for this.

We can check if an SDL system is currently intialized using SDL_WasInit(). We pass the same initialization flag we passed to SDL_Init(). For example, if we wanted to check if the video subsystem is initialized, we'd use this:

1SDL_WasInit(SDL_INIT_VIDEO);

If we want to check if any subsystem is initialized, we can pass 0 as the argument:

1SDL_WasInit(0);

Let's update our destructor to include a nullptr and SDL_WasInit() check:

1// Window.h
2// ...
3
4class Window {
5public:
6  // ...
7
8  ~Window() {
9    if (SDLWindow && SDL_WasInit(SDL_INIT_VIDEO)) {
10      SDL_DestroyWindow(SDLWindow);
11    } else {
12      std::cout << "Skipping SDL_DestroyWindow\n";
13    }
14  }
15};

In our current program, SDL_Quit() is called near the end of our main function, and our GameWindow is destroyed slightly later, once main ends. As such, we should see our safety check being triggered when we close our program:

1Skipping SDL_DestroyWindow

Managing an `SDL_Window` using a Smart Pointer

If we prefer, we can automate the management of our SDL_Window using a smart pointer, such as a std::unique_ptr. We covered std::unique_ptr in our introductory course:

Memory Ownership and Smart Pointers

Learn how to manage dynamic memory using unique pointers and the concept of memory ownership

View Related Lesson

Using it for an SDL_Window is a little more complex, as std::unique_ptr doesn't know how to delete an SDL_Window - that is, it doesn't know about the SDL_DestroyWindow() function.

However, std::unique_ptr has an alternative constructor that allows us to supply a custom deleter. A custom deleter is something that behaves like a function. When the std::unique_ptr wants to delete the resource, it will call this function and pass the memory address as an argument. Within the function body, we implement our custom deletion logic.

We cover custom deleters in more detail later in the course but, as an example, changing our Window class to apply this technique would look like the following:

1#include <SDL.h>
2#include <memory>  // for std::unique_ptr
3
4// Define a custom deleter for SDL_Window*
5struct SDLWindowDeleter {
6  void operator()(SDL_Window* Ptr) const {
7    if (Ptr && SDL_WasInit(SDL_INIT_VIDEO)) {
8      SDL_DestroyWindow(Ptr);
9    }
10  }
11};
12
13// Alias for convenience
14using UniqueSDLWindow = std::unique_ptr<
15  SDL_Window, SDLWindowDeleter>;
16
17class Window {
18 public:
19  Window() {
20    // Get the raw pointer
21    SDL_Window* Ptr{SDL_CreateWindow(
22      "Smart Pointer Window",
23      SDL_WINDOWPOS_UNDEFINED,
24      SDL_WINDOWPOS_UNDEFINED,
25      700, 300, 0
26    )};
27
28    // Store in the smart pointer
29    SDLWindow = static_cast<UniqueSDLWindow>(Ptr); 
30  }
31
32  // We still need a way to get the raw pointer
33  // for interactions with other SDL functions
34  SDL_Window* GetRaw() const {
35    return SDLWindow.get();
36  }
37  
38  // No longer need copy semantics or destructor
39  // as the std::unique_ptr takes care of it
40  Window(const Window&) = delete;             
41  Window& operator=(const Window&) = delete;  
42  ~Window() {
43    if (SDLWindow && SDL_WasInit(SDL_INIT_VIDEO)) {
44      SDL_DestroyWindow(SDLWindow);
45    }
46  }
47
48 private:
49  // Store the window resource in a unique_ptr
50  UniqueSDLWindow SDLWindow{nullptr};  
51};

To keep things simple, we'll continue to use the raw pointer approach for now.

Complete Code

The state of our program at the end of this lesson is as follows. We'll continue to build on this program throughout the rest of the chapter:

Summary

In this lesson, we introduced the following topics:

Initializing SDL with SDL_Init() and understanding subsystem initialization.
Creating a window using SDL_CreateWindow() and understanding the parameters involved.
Managing window properties and behaviors using SDL flags.

Creating a Window

Initializing SDL

Bitwise Operators and Bit Flags

Quitting SDL

Window Management

The `SDL_CreateWindow()` Function

Window Position Helpers

Window Flags

The `SDL_WindowFlags` Type

The `SDL_Window` Type

`SDL_Window` Memory Management

The Rule of Three

Copy Constructors and Operators

Safety Checks

Complete Code

Summary

SDL Surfaces and Colors

Game Development with SDL2

Questions & Answers

Creating a Window

Initializing SDL

Bitwise Operators and Bit Flags

Quitting SDL

Window Management

The SDL_CreateWindow() Function

Window Position Helpers

Window Flags

The SDL_WindowFlags Type

The SDL_Window Type

SDL_Window Memory Management

The Rule of Three

Copy Constructors and Operators

Safety Checks

Complete Code

Summary

SDL Surfaces and Colors

Questions & Answers

The `SDL_CreateWindow()` Function

The `SDL_WindowFlags` Type

The `SDL_Window` Type

`SDL_Window` Memory Management