Under Construction - Coming 2024

Learn C++ and SDL development by creating hands on, practical projects inspired by classic retro games

Game Dev with SDL2





<Excerpt>


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.


</Excerpt>


## 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:


```c++
// Window.h
#pragma once
#include <SDL.h>

class Window {
public:
  Window(){
    SDL_Init(SDL_INIT_VIDEO);

    SDLWindow = SDL_CreateWindow(
      "Hello Window", 100, 100, 700, 300, 0
    );

    SDLWindowSurface = SDL_GetWindowSurface(
      SDLWindow);

    SDL_FillRect(
      SDLWindowSurface,
      nullptr,
      SDL_MapRGB(SDLWindowSurface->format, 40,
                 40, 40)
    );
  }

  void RenderFrame(){
    SDL_UpdateWindowSurface(SDLWindow);
  }

private:
  SDL_Window* SDLWindow{nullptr};
  SDL_Surface* SDLWindowSurface{nullptr};
};
```


<Aside>


### `#include` Directories


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


```c++
#include <SDL.h>
```


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


</Aside>


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


```c++
// main.cpp
#include <SDL.h>
#include "Window.h"//<h>

int main(int argc, char** argv){
  Window GameWindow;//<h>
  SDL_Event event;
  while (true) {
    SDL_PollEvent(&event);
    GameWindow.RenderFrame();
  }
  
  SDL_Quit();
  return 0;
}
```


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


<Img file=”sdl2-window-gray.png” width=”722” height=”352” alt=”Screenshot of a window with a dark background” blurHash=”LXCZbFWBxuWB?bfQayfQ~qfQWBj[” />


<Aside>


### Closing the Window


You may have noticed the window doesn’t respond to being closed from the title bar - it remains open.


We’ll fix this a little later in the chapter, where we cover _**events**_.  For now, if you’re running the code through your IDE, hitting the stop button within your editor will terminate the process and close the window.


Otherwise, you can force your operating system to close it. That can be done using the _Ctrl + Alt + Del_ menu in Windows, or the _Opt + Cmd + Esc_ menu on Mac


</Aside>


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


<Ad />


## 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.


```c++
SDL_Init(SDL_INIT_VIDEO);
```


Here, we’re just initializing the video subsystem.  Checking [the ](/fa3131a850634dbca7ecd4d686ae06be)[`SDL_Init`](/fa3131a850634dbca7ecd4d686ae06be)[ documentation](/fa3131a850634dbca7ecd4d686ae06be), 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:


```c++
SDL_Init(
  SDL_INIT_VIDEO |
  SDL_INIT_AUDIO |
  SDL_INIT_TIMER
);
```


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:


<LessonPromo slug=”bitwise-operators” />


### `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`:


```c++
SDLWindow = SDL_CreateWindow(
  "Hello Window", 0, 0, 700, 300, 0
);
```


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](https://wiki.libsdl.org/SDL_CreateWindow), 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:

```c++
SDLWindow = SDL_CreateWindow(
  "Hello Window",
  SDL_WINDOWPOS_UNDEFINED,//<h>
  SDL_WINDOWPOS_UNDEFINED,//<h>
  700, 300, 0
);
```


The final argument to `SDL_CreateWindow` gives us more control over how the window behaves.  The [documentation](https://wiki.libsdl.org/SDL_WindowFlags) 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:


```c++
SDLWindow = SDL_CreateWindow(
  "Hello Window",
  SDL_WINDOWPOS_UNDEFINED,
  SDL_WINDOWPOS_UNDEFINED,
  700, 300,
  SDL_WINDOW_BORDERLESS | SDL_WINDOW_RESIZABLE//<h>
);
```


<Ad />


### `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:


```c++
SDLWindowSurface = 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

```c++
SDL_FillRect(
  SDLWindowSurface,
  nullptr,
  SDL_MapRGB(SDLWindowSurface->format,
    40, 40, 40)
);
```


### Colors and `SDL_MapRGB()`


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


This function accepts four arguments:

1. The format we want the colour to be output in.  The colour 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 choose `40`, which is relatively low in the 0-255 range.  As such, our grey was relatively dark:


<Img file=”sdl2-window-gray.png” width=”722” height=”352” alt=”Screenshot of a window with a dark background” blurHash=”LXCZbFWBxuWB?bfQayfQ~qfQWBj[” />


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


```c++
SDL_FillRect(
  SDLWindowSurface,
  nullptr,
  SDL_MapRGB(WindowSurface->format,
    40, 40, 100)//<h>
);
```


<Img file=”sdl2-window-blue.png” width=”723” height=”351” alt=”Screenshot of a window with a blue background” blurHash=”LXCj3Layxuay_3a{WCfQ~pfQWBfQ” />


### `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:


```c++
void RenderFrame() {
  SDL_UpdateWindowSurface(SDLWindow);
}
```


<Aside>


### Preview: Frames and Buffers


Behind the scenes, video output it simply a series of still images, usually called _**frames**_.  If we show these frames in a quick enough succession - that is, at a high enough _**frame rate**_ - we create the illusion of motion.


Frame rates are typically represented in frames per second.  For motion to appear smooth, we typically want our programs to be capable of generating at least 30 new frames per second.


`SDL_UpdateWindowSurface()` is how we tell SDL that we’re ready to show users the next frame.  We cover the theory behind this in more detail in our lesson on frames and buffers later in the chapter.


</Aside>


<Ad />


## The `main` Function


Finally, lets take a look at our `main` function.  It looks like this:


```c++
//<show-line-numbers>
// main.cpp
#include <SDL.h>
#include "Window.h"

int main(int argc, char** argv){
  Window GameWindow;//<h>
  SDL_Event event;
  while (true) {
    SDL_PollEvent(&event);
    GameWindow.RenderFrame();
  }
  
  SDL_Quit();
  return 0;
}
```

- 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 colour 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.

<FAQ>


```javascript
//<m>
{
  slug: 'handling-window-close-events-in-sdl',
  title: 'How to Handle Window Close Events in SDL',
  question: 'How can I make my SDL window respond to close events, such as clicking the close button?',
}
```


To make your SDL window respond to close events, you need to modify your event handling loop to detect when the SDL_QUIT event is triggered, which occurs when the window's close button is clicked. Here's how you can incorporate this into your code:


```c++
#include <SDL.h>
#include "Window.h"

int main(int argc, char** argv) {
  Window GameWindow;
  SDL_Event event;
  bool running = true;

  while (running) {
    while (SDL_PollEvent(&event)) {
      if (event.type == SDL_QUIT) {
        running = false; //<h>
      }
    }
    GameWindow.RenderFrame();
  }

  SDL_Quit();
  return 0;
}
```


This modification introduces a boolean flag **`running`** that controls the main loop. The loop continues as long as **`running`** is true, but sets **`running`** to false when an SDL_QUIT event is detected, effectively closing the window.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'using-multiple-windows-in-sdl',
  title: 'Using Multiple Windows in SDL',
  question: 'Can I create and manage multiple windows in SDL, and if so, how?',
}
```


Yes, SDL supports managing multiple windows. Each window in SDL is managed through a separate **`SDL_Window`** pointer. You can create multiple instances of your **`Window`** class or manage multiple **`SDL_Window`** pointers directly in your main application. Here’s a simple example of managing two windows:


```c++
#include <SDL.h>

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);

  SDL_Window* window1 = SDL_CreateWindow(
    "Window 1", 100, 100, 640, 480, 0);
  SDL_Window* window2 = SDL_CreateWindow(
    "Window 2", 750, 100, 640, 480, 0);

  bool running = true;
  SDL_Event event;

  while (running) {
    while (SDL_PollEvent(&event)) {
      if (event.type == SDL_QUIT) {
        running = false;
      }
    }

    SDL_UpdateWindowSurface(window1);
    SDL_UpdateWindowSurface(window2);
  }

  SDL_DestroyWindow(window1);
  SDL_DestroyWindow(window2);
  SDL_Quit();
  return 0;
}
```


This example initializes two separate windows and updates their surfaces in the main loop. When the SDL_QUIT event is detected, both windows close.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'adjusting-window-size-dynamically-in-sdl',
  title: 'Adjusting Window Size Dynamically in SDL',
  question: 'How can I adjust the size of an SDL window dynamically during runtime?',
}
```


SDL allows you to adjust the size of a window dynamically using the **`SDL_SetWindowSize()`** function. Here's how you can integrate this into your application to change the window size based on user input or other conditions:


```c++
#include <SDL.h>
#include "Window.h"

int main(int argc, char** argv) {
  Window GameWindow;
  SDL_Event event;
  bool running = true;

  while (running) {
    while (SDL_PollEvent(&event)) {
      if (event.type == SDL_QUIT) {
        running = false;
      } else if (event.type == SDL_KEYDOWN) {
        switch (event.key.keysym.sym) {
          case SDLK_UP:
            SDL_SetWindowSize(//<h>
              GameWindow.SDLWindow, 800, 600);  //<h>
            break;
          case SDLK_DOWN:
            SDL_SetWindowSize(//<h>
              GameWindow.SDLWindow, 640, 480);  //<h>
            break;
        }
      }
    }
    GameWindow.RenderFrame();
  }

  SDL_Quit();
  return 0;
}
```


In this example, pressing the UP key increases the window size to 800x600, while pressing the DOWN key reduces it to 640x480. This dynamic resizing can be triggered by any event or condition in your program.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'improving-sdl-window-performance',
  title: 'Improving SDL Window Performance',
  question: 'What are some tips to improve the performance of an SDL window?',
}
```


To improve the performance of an SDL window, consider the following tips:
- **Optimize your event loop**: Only process events when necessary and avoid unnecessary computations or rendering in your loop.
- **Use hardware acceleration**: Utilize the `SDL_WINDOW_OPENGL` flag when creating your window to enable OpenGL, which can help leverage GPU acceleration.
- **Manage your surfaces and textures efficiently**: Minimize the use of `SDL_UpdateWindowSurface()` by using SDL textures and renderers for more efficient drawing and updates.


Here's how you could modify your existing window setup to use OpenGL for hardware acceleration:


```c++
#include <SDL.h>

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);
  SDL_Window* window =
    SDL_CreateWindow("Optimized Window",
      SDL_WINDOWPOS_UNDEFINED,
      SDL_WINDOWPOS_UNDEFINED,
      640, 480, SDL_WINDOW_OPENGL);  //<h>

  // Your rendering and event handling code here

  SDL_DestroyWindow(window);
  SDL_Quit();
  return 0;
}
```


This example shows the inclusion of the **`SDL_WINDOW_OPENGL`** flag to enable OpenGL features for better rendering performance.
</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'handling-keyboard-input-in-sdl',
  title: 'Handling Keyboard Input in SDL',
  question: 'How can I handle keyboard inputs in an SDL application?',
}
```


This is the answer to the question. Handling keyboard input in SDL is straightforward using the SDL event system. You need to check for `SDL_KEYDOWN` and `SDL_KEYUP` events in your event loop. Here's a simple example that reacts to keyboard inputs:


```c++
#include <SDL.h>

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);
  SDL_Window* window = SDL_CreateWindow(
    "Keyboard Input Window",
    SDL_WINDOWPOS_UNDEFINED,
    SDL_WINDOWPOS_UNDEFINED,
    640, 480, 0
  );
  SDL_Event event;
  bool running = true;

  while (running) {
    while (SDL_PollEvent(&event)) {
      if (event.type == SDL_QUIT) {
        running = false;
      } else if (event.type == SDL_KEYDOWN) {
        switch (event.key.keysym.sym) {
          case SDLK_ESCAPE:
            running = false;
            break;
            // Handle other key presses here
        }
      }
    }
  }

  SDL_DestroyWindow(window);
  SDL_Quit();
  return 0;
}
```


This code initializes an SDL window and processes keyboard input to close the window when the Escape key is pressed.
</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'using-sdl-with-other-languages',
  title: 'Using SDL with Other Programming Languages',
  question: 'Can SDL be used with programming languages other than C++?',
}
```


Yes, SDL can be used with various programming languages besides C++. It has bindings for languages like Python, C#, Java, and Rust, allowing it to integrate into different types of projects. Here's an example of using SDL with Python using the PySDL2 library:


```python
import sdl2
import sdl2.ext

def run():
  sdl2.ext.init()
  window = sdl2.ext.Window("SDL with Python", size=(640, 480))
  window.show()

  running = True
  while running:
    events = sdl2.ext.get_events()
    for event in events:
      if event.type == sdl2.SDL_QUIT:
        running = False
    window.refresh()

  sdl2.ext.quit()

if __name__ == "__main__":
  run()
```


This Python script uses PySDL2 to create a window, handle events, and refresh the window, demonstrating SDL's flexibility across languages.
</FAQ>



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

How to Handle Window Close Events in SDL

Using Multiple Windows in SDL

Adjusting Window Size Dynamically in SDL

Improving SDL Window Performance

Handling Keyboard Input in SDL

Using SDL with Other Programming Languages

General rewrite of the lesson to improve explanations and simplify examples

Frontpage

`SDL_Init()`

`SDL_CreateWindow()`

`SDL_Window`

SDL_WindowFlags

SDL_Surface

SDL_Rect

`SDL_FillRect()`

`SDL_MapRGB()`

`SDL_PollEvent()`

UPDATED FOR C++23 | Learn how to create and customize windows in C++ using SDL2, covering initialization, window management, and rendering | Clear explanations and simple code examples

Creating and Customising a Window in SDL2 and C++ | A Practical Guide

Creating a Window

Handling Keyboard Input in SDL

How can I handle keyboard inputs in an SDL application?

Creating a Window

How can I make my SDL window respond to close events, such as clicking the close button?

Can I create and manage multiple windows in SDL, and if so, how?

How can I adjust the size of an SDL window dynamically during runtime?

What are some tips to improve the performance of an SDL window?

Can SDL be used with programming languages other than C++?

Creating a Window

Game Dev with SDL2

This course includes:

Professional C++