Creating a Window

With SDL2 successfully installed and added to our project, lets start our journey.

The first step is being able to create and manipulate a window. 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 describing the most common options.

Let's start by creating a class to manage our window..

Creating the Window Class

Note, this article assumes we've completed the SDL2 setup for our environment. Guides for doing this on most common environments are provided below:

Installing SDL2 Libraries on macOS

Preparing our development environment for this chapter by Installing SDL2 and the SDL_image and SDL_ttf extensions. Setup guide for Xcode or CMake. 

Installing SDL2 Libraries Manually on Windows

Preparing our development environment for this chapter by Installing SDL2 and the SDL_image and SDL_ttf extensions. Setup guide for Visual Studio on Windows. 

Installing SDL Libraries using vcpkg on Windows

An introduction to C++ package managers, and a step-by-step guide to installing SDL libraries using vcpkg on Windows and Visual Studio

Below, we've created a Window class to manage the window. We'll break down every line of code we're using here, once we see it working:

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", 0, 0, 500, 300, 0
12    );
13
14    SDLWindowSurface = SDL_GetWindowSurface(SDLWindow);
15
16    SDL_FillRect(
17      SDLWindowSurface,
18      nullptr,
19      SDL_MapRGB(SDLWindowSurface->format, 40, 40, 40)
20    );
21  }
22
23  void RenderFrame() {
24    SDL_UpdateWindowSurface(SDLWindow);
25  }
26
27private:
28  SDL_Window* SDLWindow { nullptr };
29  SDL_Surface* SDLWindowSurface { nullptr };
30};
31

Then, from our main.cpp we can include the header file and create our window:

1#include <SDL.h>
2#include "Window.h"
3
4int main() {
5  Window GameWindow;
6  SDL_Event event;
7  while(true) {
8    SDL_PollEvent(&event);
9    GameWindow.RenderFrame();
10  }
11}
12

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

Let's break this code down, line by line.

SDL_Init

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

1SDL_Init(SDL_INIT_VIDEO);
2

Here, we’re just initializing the video subsystem. Checking the SDL2 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, |

An explanation of the | operator, and how this code works more generally, is available here:

Bitwise Operators and Bit Flags

An introduction to the bitwise AND, OR, and XOR operators - and one of their most interesting use cases

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

1SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO | SDL_INIT_TIMER);
2

SDL_Window

Next, we need to create the window, which will have a type provided by SDL: SDL_Window. We store a pointer to it in a private member we’re calling SDLWindow:

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

The SDL_CreateWindow function helps us do this. It accepts 6 arguments:

• The window title - “Hello Window”
• The horizontal position of the window - 0, indicating the left-most edge of our screen
• The vertical position of the window - 0, indicating the top-most edge of our screen
• The width of the window - 500 pixels
• The height of the window - 300 pixels
• “Flags” to modify the behavior of the window

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

• 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. This is a good default, as operating systems have put a lot of thought into what gives the best user experience

1SDLWindow = SDL_CreateWindow(
2  "Hello Window",
3  SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED,
4  500, 300, 0
5);
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, SDL_WINDOWPOS_UNDEFINED,
4  500, 300,
5  SDL_WINDOW_BORDERLESS | SDL_WINDOW_RESIZABLE
6);
7

SDL_Surface

An SDL_Surface is where we draw our content. Later in this chapter, we will create our own surfaces.

However, the window we created come with a surface by default. We can access that surface using the SDL_GetWindowSurface function.

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);
2

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 create our own. rectangles later - for now, passing a nullptr indicates we want the entire surface to be filled
• The colour to fill the rectangle with

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

Surfaces can have different ways to represent color. The SDL_MapRGB function standardizes this. We can provide the format of the surface, accessible through the surface pointer, and then our three color components: red, green, and blue.

These components are in the 0-255 range. So, for example, if we wanted to make our window background red, we would change our code to this:

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

SDL_UpdateWindowSurface

Once we’ve made all the changes we need to our surface, we are ready to render our next frame. 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}
4

The Render Loop

Finally, our last block of code is over in our main function. It looks like this:

1Window GameWindow;
2SDL_Event event;
3while(true) {
4  SDL_PollEvent(&event);
5  GameWindow.RenderFrame();
6}
7

Here, we first create our window, calling all the code in our Window constructor.

Then, we have an infinite loop, causing our window to constantly render new frames.

The two new things here are lines 2 and 4, which are dealing with events. We’ll introduce events in the next lesson.