As we've likely noticed, platforms typically add decorations to our windows, such as a title bar and borders. But what if you need a clean, borderless look?

In this lesson, we'll cover everything you need to know about customizing SDL3 window styles, including removing decorations and dynamically adding them back.

The following screenshot is from Windows 11. It shows a decorated window on the left and an equivalent window without those decorations on the right:

Screenshot comparing a bordered and borderless window

SDL refers to these decorations as borders but, as we can see above, they can also include things like the title bar on desktop platforms.

Starting Point

This lesson builds on our earlier work. To focus on window borders, we will start with a minimal project containing a Window class and a main function with a basic application loop:

Files

src

Select a file to view its content

Creating a Borderless Window

By default, SDL asks the platform to include these decorations for our window. We can opt to exclude them by passing the SDL_WINDOW_BORDERLESS window flag to SDL_CreateWindow():

src/Window.h

1#pragma once
2#include <SDL3/SDL.h>
3
4class Window {
5public:
6  Window() {
7    SDLWindow = SDL_CreateWindow(
8      "My Program", 600, 300,
9      SDL_WINDOW_BORDERLESS
10    );
11  }
12  // ...
13};

Running this code will produce a clean, undecorated window.

Adding and Removing Borders

We can add or remove decorations from an existing window using the SDL_SetWindowBordered() function. We pass the SDL_Window pointer as the first argument, and true or false as the second argument.

Let's add a SetBordered() method to our Window class to encapsulate this functionality:

src/Window.h

1#pragma once
2#include <SDL3/SDL.h>
3
4class Window {
5public:
6  // ...
7  void SetBordered(bool Bordered) {
8    SDL_SetWindowBordered(GetRaw(), Bordered);
9  }
10  // ...
11};

Now we can toggle the border from our main function. For example, we could remove the border when the 'B' key is pressed:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include "Window.h"
4
5int main(int, char**) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8  SDL_Event Event;
9
10  bool IsRunning = true;
11  while (IsRunning) {
12    while (SDL_PollEvent(&Event)) {
13      if (Event.type == SDL_EVENT_KEY_DOWN &&
14          Event.key.key == SDLK_B) {
15        GameWindow.SetBordered(false);
16      } else if (Event.type == SDL_EVENT_QUIT) {
17        IsRunning = false;
18      }
19    }
20    GameWindow.Render();
21    GameWindow.Update();
22  }
23
24  SDL_Quit();
25  return 0;
26}

We can check if a window currently has borders by retrieving its flags with SDL_GetWindowFlags() and testing if the SDL_WINDOW_BORDERLESS flag is set. Let's add an IsBorderless() helper to our Window class:

src/Window.h

1#pragma once
2#include <SDL3/SDL.h>
3
4class Window {
5public:
6  // ...
7  bool IsBorderless() const {
8    return (SDL_GetWindowFlags(GetRaw()) &
9      SDL_WINDOW_BORDERLESS) != 0;
10  }
11  // ...
12};

We can now use this method to check the window's state:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9  GameWindow.SetBordered(false);
10
11  if (GameWindow.IsBorderless()) {
12    std::cout << "Window is borderless\n";
13  }
14
15  GameWindow.SetBordered(true);
16
17  if (!GameWindow.IsBorderless()) {
18    std::cout << "Not any more!";
19  }
20
21  // ... (rest of the main function)
22}

1Window is borderless
2Not any more!

Client Area and Border Size

When setting the position or size of a window in SDL, we are defining the dimensions of the client area. The client area is the region of the window where the application's content is displayed, excluding any decorations like the title bar or window borders.

Decorations are added outside the client area. For instance, if you specify a window height of 200, the client area will be exactly 200 points tall, but the total window height will also include the additional space occupied by decorations.

To precisely control the overall window size or position, it's important to account for the size of these decorations.

The SDL_GetWindowBordersSize() function can help us here. We pass the SDL_Window pointer and four integer pointers. The integers will be updated with the size of the decorations on the top, left, bottom, and right of our window respectively:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9
10  int Top, Left, Bottom, Right;
11  SDL_GetWindowBordersSize(
12    GameWindow.GetRaw(),
13    &Top, &Left, &Bottom, &Right
14  );
15
16  std::cout << "Top: " << Top
17    << ", Left: " << Left
18    << ", Bottom: " << Bottom
19    << ", Right: " << Right << '\n';
20
21  // ... (rest of the main function)
22}

1Top: 31, Left: 8, Bottom: 8, Right: 8

We can pass a nullptr for any of these arguments to ignore the decoration size on that side. For example, passing nullptr for the left and right pointers will only return the sizes of the top and bottom decorations.

1// We only care about the top and bottom decoration size
2int Top, Bottom;
3SDL_GetWindowBordersSize(
4  GameWindow.GetRaw(),
5  &Top,
6  nullptr,
7  &Bottom,
8  nullptr
9);

This function returns 0 if successful, or a negative error code otherwise. We can call SDL_GetError() for an explanation of the error, a technique covered in our lesson on .

1int Top;
2int ExitCode = SDL_GetWindowBordersSize(
3  nullptr, &Top, nullptr, nullptr, nullptr);  
4
5if (ExitCode < 0) {
6  std::cout << "Error getting border size: "
7    << SDL_GetError();
8}

1Error getting border size: Invalid window

Summary

In this lesson, we introduced window decorations and how to control them. This included making windows borderless and measuring their decorations for precise layout control.

Key Takeaways

SDL provides the SDL_WINDOW_BORDERLESS flag to create borderless windows.
Use SDL_SetWindowBordered() to dynamically toggle decorations.
The SDL_GetWindowBordersSize() function helps calculate the size of window decorations.

Window Decorations and Borders

Starting Point

Files

Creating a Borderless Window

src/Window.h

Adding and Removing Borders

src/Window.h

src/main.cpp

src/Window.h

src/main.cpp

Client Area and Border Size

src/main.cpp

Summary

Key Takeaways

Window Titles

Game Development with SDL3