Creating a Window

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.

Creating a Window

Let's start by creating a class to manage our window. We’ll break down this code line by line in the following section:

1// Window.h
2#pragma once
3#include <SDL.h>
4
5class Window {
6public:
7  Window(){
8    SDL_Init(SDL_INIT_VIDEO);
9
10    SDLWindow = SDL_CreateWindow(
11      "Hello Window", 100, 100, 700, 300, 0
12    );
13
14    SDLWindowSurface = SDL_GetWindowSurface(
15      SDLWindow);
16
17    SDL_FillRect(
18      SDLWindowSurface,
19      nullptr,
20      SDL_MapRGB(SDLWindowSurface->format, 40,
21                 40, 40)
22    );
23  }
24
25  void RenderFrame(){
26    SDL_UpdateWindowSurface(SDLWindow);
27  }
28
29private:
30  SDL_Window* SDLWindow{nullptr};
31  SDL_Surface* SDLWindowSurface{nullptr};
32};

1#include <SDL.h>

With our Window class created, over in main.cpp we can include the header file and create our window by calling the constructor:

1// main.cpp
2#include <SDL.h>
3#include "Window.h"
4
5int main(int argc, char** argv){
6  Window GameWindow;
7  SDL_Event event;
8  while (true) {
9    SDL_PollEvent(&event);
10    GameWindow.RenderFrame();
11  }
12  
13  SDL_Quit();
14  return 0;
15}

Compiling and running this code, we should see our application opens a window which we can move around:

Let's break down everything that is going on in our Window class and main function, line by line.

The Window Class

Let’s break down our Window class, line by line.

SDL_Init()

Our first action is to initialize the SDL subsystems we need, using the SDL_Init command.

1SDL_Init(SDL_INIT_VIDEO);

Here, we’re just initializing the video subsystem. Checking the SDL_Init documentation, we see that this will also initialize the events subsystem.

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, and 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

SDL_Window and SDL_CreateWindow()

Once we’ve initialized SDL, we need to create the window. SDL windows have a type of SDL_Window. and we’ll almost always be interacting with it through a pointer. The SDL_CreateWindow() function returns such a pointer, which we’re storing in a private class variable called SDLWindow:

1SDLWindow = SDL_CreateWindow(
2  "Hello Window", 0, 0, 700, 300, 0
3);

The SDL_CreateWindow() function accepts 6 arguments:

• The window title - "Hello Window"
• The horizontal position of the window - 100, indicating we want it to be opened 100 pixels from the left-most edge of our screen
• The vertical position of the window - 100, indicating we want it to be opened 100 pixels from the top edge of our screen
• The width of the window - 700 pixels in this example
• The height of the window - 300 pixels in this example
• "Flags" to modify the behavior of the window. In the previous example, we just set it to 0, but we cover it in detail later

Reviewing the documentation, we see there are some helpers for the position arguments:

• SDL_WINDOWPOS_CENTERED will automatically center the window along its axis
• SDL_WINDOWPOS_UNDEFINED will let the operating system choose the best place to open the window. Unless we have a compelling reason to specify the position, letting the platform decide using SDL_WINDOWPOS_UNDEFINED tends to result in a better user experience than us guessing what a good position would be:

1SDLWindow = SDL_CreateWindow(
2  "Hello Window",
3  SDL_WINDOWPOS_UNDEFINED,
4  SDL_WINDOWPOS_UNDEFINED,
5  700, 300, 0
6);

The final argument to SDL_CreateWindow gives us more control over how the window behaves. The documentation provides a list of "flags" that can be used with this argument.

Similarly to before, these flags can be combined using the | operator. For example, we could make our window borderless and resizable like this:

1SDLWindow = SDL_CreateWindow(
2  "Hello Window",
3  SDL_WINDOWPOS_UNDEFINED,
4  SDL_WINDOWPOS_UNDEFINED,
5  700, 300,
6  SDL_WINDOW_BORDERLESS | SDL_WINDOW_RESIZABLE
7);

SDL_Surface

An SDL_Surface is one of the ways SDL lets us render content. Later in this chapter, we will create our own surfaces.

However, the windows we create come with a surface by default. We can access that surface using the SDL_GetWindowSurface() function, passing in a pointer to the window.

In our class, we’re storing a pointer to it in a private member called SDLWindowSurface so we can draw on it later:

1SDLWindowSurface = SDL_GetWindowSurface(Window);

SDL_FillRect()

This function fills a rectangle with a solid color. It needs three arguments:

• A pointer to the surface the rectangle is on
• A pointer to the rectangle to fill. We’ll learn how to define custom rectangles later - for now, passing a nullptr indicates we want the entire surface to be filled
• The color to fill the rectangle with

1SDL_FillRect(
2  SDLWindowSurface,
3  nullptr,
4  SDL_MapRGB(SDLWindowSurface->format,
5    40, 40, 40)
6);

Colors and SDL_MapRGB()

There are many different ways of representing colors. SDL provides some utility functions to help us standardize this, such as SDL_MapRGB() in the previous example.

This function accepts four arguments:

1. The format we want the color to be output in. The color format used by a surface is available through the format member variable.
2. How red we want our color to be
3. How green we want our color to be
4. How blue we want our color to be

Typically, the red, green, and blue components of a color are each represented by an 8-bit integer, which is a value from 0 to 255. In the previous example, we set each component (or "channel") to the same number, which will result in a grey color.

Additionally, we chose 40, which is relatively low in the 0-255 range. As such, our grey was relatively dark:

In the following example, we increase our blue value (the final argument) from 40 to 100, shifting the resulting color towards blue:

1SDL_FillRect(
2  SDLWindowSurface,
3  nullptr,
4  SDL_MapRGB(WindowSurface->format,
5    40, 40, 100)
6);

SDL_UpdateWindowSurface()

Once we’ve made all the changes we need to our surface, we are ready to update the screen, letting the user see our changes.

This is sometimes referred to as rendering the next frame, and we cover the theory behind this later in the chapter.

Our class has a public RenderFrame method to do just that.

Within that function, for now, all we need to do is ask SDL to update the window surface with our changes. We aren’t making any changes yet, but we will soon.

To update the window surface, we call SDL_UpdateWindowSurface function, passing in a pointer to our window:

1void RenderFrame() {
2  SDL_UpdateWindowSurface(SDLWindow);
3}

The main Function

Finally, let’s take a look at our main function. It looks like this:

1// main.cpp
2#include <SDL.h>
3#include "Window.h"
4
5int main(int argc, char** argv){
6  Window GameWindow;
7  SDL_Event event;
8  while (true) {
9    SDL_PollEvent(&event);
10    GameWindow.RenderFrame();
11  }
12  
13  SDL_Quit();
14  return 0;
15}

• On line 6, we create an instance of our Window class, thereby calling all the code in our default constructor.
• On line 8, we have an infinite loop, causing our program to keep running
• On line 10, we call the RenderFrame() method on every iteration of our loop, thereby filling our rectangle with the grey color we defined in our Window class.
• On line 13, we call SDL_Quit(). This is how we communicate to SDL that our program is about to end, prompting it to perform any cleanup actions it needs to do. This function call is currently unreachable as our infinite loop never ends, but it will become relevant later in the chapter.

There are two further lines we haven’t covered - the SDL_Event type and SDL_PollEvent() function. As their name suggests, these deal with events.

In this program, they currently have no effect, but we need to use them to keep our program running. Events will have a large role in our program, as they’re the main way we receive and react to user input. We’ll cover this in much more detail later in 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.
• Drawing on the window surface with SDL_FillRect() and manipulating colors with SDL_MapRGB().
• Updating the window with SDL_UpdateWindowSurface() to reflect changes on the screen.
• Basic event handling setup that will be expanded in later sections.

Next Lesson

Detecting and Managing Errors

Discover techniques for detecting and responding to SDL runtime errors

ContinueView Course