Creating a Window

With SDL3 successfully configured in our project, we can now create and manipulate windows.

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

The previous chapter ended with the following program, which we confirmed can compile and create a window:

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <SDL3_image/SDL_image.h>
4#include <SDL3_ttf/SDL_ttf.h>
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8
9  SDL_Window* Window{SDL_CreateWindow(
10    "Hello Window", 800, 300, 0
11  )};
12
13  bool IsRunning = true;
14  SDL_Event Event;
15  while (IsRunning) {
16    while (SDL_PollEvent(&Event)) {
17      if (Event.type == SDL_EVENT_QUIT) {
18        IsRunning = false;
19      }
20    }
21  }
22
23  SDL_DestroyWindow(Window);
24  SDL_Quit();
25
26  return 0;
27}

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

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <SDL3_image/SDL_image.h>
4#include <SDL3_ttf/SDL_ttf.h>
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8
9  SDL_Window* Window{SDL_CreateWindow(
10    "Hello Window", 800, 300, 0
11  )};
12
13  bool IsRunning = true;
14  SDL_Event Event;
15  while (IsRunning) {
16    while (SDL_PollEvent(&Event)) {
17      if (Event.type == SDL_EVENT_QUIT) {
18        IsRunning = false;
19      }
20    }
21  }
22
23  SDL_DestroyWindow(Window);
24  SDL_Quit();
25
26  return 0;
27}

C++ Language Standards

The C++ language evolves over time with new features. These updates are currently made every 3 years, and are informally given names like C++17, C++20, and C++23.

The main implication for us is that we need to make sure the feature we want to use is available in the language standard we're using.

This is particularly important for Visual Studio users as, at the time of writing, Visual Studio uses C++14 by default. That is quite old now, so we should configure our project to something more recent.

If you are using Visual Studio without CMake, you can do this by opening the Property Pages window (from the View menu on the top bar) and setting the C++ Language Standard within the General section. We'd recommend setting it to C++20 or later:

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 explains 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 it in more detail in a lesson in our introductory course .

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. In our current program, this is right before the return 0; statement in main.

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.

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 it on macOS too, we'd have a lot of work to do.

One of the main reasons for using SDL is 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:

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

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

1SDL_CreateWindow(
2  "Hello Window",
3  800, 300, 0
4);

Let's break down what these arguments are:

1. 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.
2. The width of the window. In this example, we create a window that is 800 units wide.
3. The height of the window. In this example, we create a window that is 300 units tall.
4. "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 window flags in more detail later in this section and through the rest of the course.

The last argument to SDL_CreateWindow() 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#pragma once
2#include <SDL3/SDL.h>
3
4class Window {
5public:
6  Window(){
7    SDL_CreateWindow(
8      "Hello Window",
9      800, 300,
10      SDL_WINDOW_RESIZABLE
11    );
12  }
13};

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#pragma once
2#include <SDL3/SDL.h>
3
4class Window {
5public:
6  Window(){
7    SDL_CreateWindow(
8      "Hello Window",
9      800, 300,
10      SDL_WINDOW_RESIZABLE | SDL_WINDOW_MINIMIZED
11    );
12  }
13};

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_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#pragma once
2#include <SDL3/SDL.h>
3
4class Window {
5public:
6  Window() {
7    SDLWindow = SDL_CreateWindow(
8      "Hello Window",
9      800, 300, 0
10    );
11  }
12
13private:
14  SDL_Window* SDLWindow{nullptr};
15};

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#pragma once
2#include <SDL3/SDL.h>
3
4class Window {
5public:
6  Window() {
7    SDLWindow = SDL_CreateWindow(
8      "Hello Window",
9      800, 300, 0
10    );
11  }
12
13  ~Window() {
14    SDL_DestroyWindow(SDLWindow);
15  }
16
17private:
18  SDL_Window* SDLWindow{nullptr};
19};

The Rule of Three

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

1#pragma once
2#include <SDL3/SDL.h>
3
4class Window {
5public:
6  Window() {
7    SDLWindow = SDL_CreateWindow(
8      "Hello Window",
9      800, 300, 0
10    );
11  }
12
13  Window(const Window&) = delete;
14  Window& operator=(const Window&) = delete;
15
16  ~Window() {
17    SDL_DestroyWindow(SDLWindow);
18  }
19
20private:
21  SDL_Window* SDLWindow{nullptr};
22};

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

Safety Checks

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

1. 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.
2. 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 initialized 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#pragma once
2#include <SDL3/SDL.h>
3#include <iostream>
4
5class Window {
6public:
7  Window() {
8    SDLWindow = SDL_CreateWindow(
9      "Hello Window",
10      800, 300, 0
11    );
12  }
13
14  Window(const Window&) = delete;
15  Window& operator=(const Window&) = delete;
16
17  ~Window() {
18    if (SDLWindow && SDL_WasInit(SDL_INIT_VIDEO)) {
19      SDL_DestroyWindow(SDLWindow);
20    } else {
21      std::cout << "Skipping SDL_DestroyWindow\n";
22    }
23  }
24
25private:
26  SDL_Window* SDLWindow{nullptr};
27};

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

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 a lesson in our introductory course .

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 a function, or 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.

Changing our Window class to apply this technique would look like the following example. We cover custom deleters and the syntax we use in this code in more detail later in the course, so don't worry if it doesn't entirely make sense yet:

1#include <SDL3/SDL.h>
2#include <memory>
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>;
17
18class Window {
19 public:
20  Window() {
21    // Get the raw pointer
22    SDL_Window* Ptr{SDL_CreateWindow(
23      "Smart Pointer Window",
24      800, 300, 0
25    )};
26
27    // Store in the smart pointer
28    SDLWindow = UniqueSDLWindow(Ptr);
29  }
30
31  // We still need a way to get the raw pointer
32  // for interactions with other SDL functions
33  SDL_Window* GetRaw() const {
34    return SDLWindow.get();
35  }
36
37 private:
38  // Store the window resource in a unique_ptr
39  UniqueSDLWindow SDLWindow{nullptr};
40};

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

The SDL2 version of SDL_CreateWindow() allowed us to specify the position of the window, but that is no longer the case as of SDL3. This is because in modern windowing systems, it's often best to let the system decide the optimal placement.

However, if we do need to specify a position, we can use the more powerful SDL_CreateWindowWithProperties() function added in SDL3.

To use it, we first create a set of properties using SDL_CreateProperties(), then set the values we need, and finally pass the properties to the creation function:

1// Window.h
2#pragma once
3#include <SDL3/SDL.h>
4
5class Window {
6public:
7  Window(){
8    SDL_PropertiesID props{SDL_CreateProperties()};
9    
10    // Title
11    SDL_SetStringProperty(
12      props,
13      SDL_PROP_WINDOW_CREATE_TITLE_STRING,
14      "Hello Window"
15    );
16    
17    // Width
18    SDL_SetNumberProperty(
19      props,
20      SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER,
21      800
22    );
23    
24    // Height
25    SDL_SetNumberProperty(
26      props,
27      SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER,
28      300
29    );
30    
31    // Horizontal Position
32    SDL_SetNumberProperty(
33      props,
34      SDL_PROP_WINDOW_CREATE_X_NUMBER,
35      100
36    );
37    
38    // Vertical Position
39    SDL_SetNumberProperty(
40      props,
41      SDL_PROP_WINDOW_CREATE_Y_NUMBER,
42      100
43    );
44
45    SDL_CreateWindowWithProperties(props);
46  }
47};

Any properties we create are automatically cleaned up when SDL_Quit() is called or, in more complex scenarios where we need to manually intervene, we can use SDL_DestroyProperties():

1SDL_DestroyProperties(props);

Positioning Helpers

SDL provides helper constants for common positioning needs. We can use SDL_WINDOWPOS_UNDEFINED to let the system decide, or SDL_WINDOWPOS_CENTERED to center the window on the screen.

1// Set X and Y to center the window
2SDL_SetNumberProperty(
3  props,
4  SDL_PROP_WINDOW_CREATE_X_NUMBER,
5  SDL_WINDOWPOS_CENTERED
6);
7
8SDL_SetNumberProperty(
9  props,
10  SDL_PROP_WINDOW_CREATE_Y_NUMBER,
11  SDL_WINDOWPOS_CENTERED
12);

Unless we have a compelling reason to specify the position, letting the platform decide using SDL_WINDOWPOS_UNDEFINED (or using the simpler SDL_CreateWindow() function) is recommended.

Platform owners have put 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.

To keep things simple, we'll stick to the SDL_CreateWindow() approach for now, but we have a dedicated chapter on more complex window management later in the course.

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.

After these updates, our program should compile and run as it did before:

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.
• Using SDL_CreateWindowWithProperties() to set advanced options like window position.
• Managing window properties and behaviors using SDL flags.