This lesson explores the tools SDL3 offers for controlling window sizes and responding to changes. We'll cover:

Allowing users to resize windows.
Retrieving and setting window dimensions programmatically.
Using resize events for dynamic layouts.

Starting Point

A minimal project containing a Window class and a main function with a basic application loop is provided below if you want to follow along.

We've removed the specific event handling logic from main.cpp and the positioning methods from Window.h to keep the code focused on this lesson's topic.

Files

src

Select a file to view its content

Setting the Window Size

As we've seen, we can define the initial size when creating our window using the 2nd and 3rd arguments to SDL_CreateWindow():

1SDL_CreateWindow(
2  "My Program", // Title
3  600, // Width
4  300, // Height
5  0 // Configuration
6);

Resizable Windows

In most desktop environments, users can resize windows by clicking and dragging their borders. We can allow our window to be resized by passing the SDL_WINDOW_RESIZABLE window flag:

1SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  SDL_WINDOW_RESIZABLE
5);

We cover window flags in detail in our lesson on .

Using `SDL_SetWindowResizable()`

We can specify whether an existing window can be resized by players using the SDL_SetWindowResizable() function. We pass the SDL_Window pointer as the first argument. The second argument is a bool - true if we want the window to be resizable, or false otherwise:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  // Not setting the resizable flag
5  0 
6)};
7
8// Update the window to be resizable
9SDL_SetWindowResizable(Window, true);
10
11// Disable resizing
12SDL_SetWindowResizable(Window, false);

Checking if a Window is Resizable

If we need to check if an SDL_Window is currently resizable by players, we can retrieve its window flags and use the & operator to isolate the SDL_WINDOW_RESIZABLE bit:

1bool isResizable(SDL_Window* Window) {
2  SDL_WindowFlags Flags{SDL_GetWindowFlags(Window)};
3  return Flags & SDL_WINDOW_RESIZABLE;
4}

The window flags associated with a window are kept up to date as we use other functions, like SDL_SetWindowResizable(), to update the configuration of our window:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7if (isResizable(Window)) {
8  std::cout << "Window is resizable\n";
9}
10
11SDL_SetWindowResizable(Window, false);
12
13if (!isResizable(Window)) {
14  std::cout << "Not any more!";
15}

1Window is resizable
2Not any more!

Minimum Size

If we want to let players resize our window, we will often want to set some constraints on how large or how small they can make it.

To set the minimum size, we use the SDL_SetWindowMinimumSize() function, passing three arguments:

The pointer to the SDL_Window we want to constrain
The minimum horizontal size
The minimum vertical size

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7SDL_SetWindowMinimumSize(Window, 200, 200);

We can retrieve the currently configured minimum size using SDL_GetWindowMinimumSize(). We pass the SDL_Window pointer and two integer pointers. The integers are updated with the current minimum width and height, respectively:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7SDL_SetWindowMinimumSize(Window, 200, 200);
8
9int minW, minH;
10SDL_GetWindowMinimumSize(Window, &minW, &minH);
11
12std::cout << "Minimum Width: " << minW
13  << "\nMinimum Height: " << minH;

1Minimum Width: 200
2Minimum Height: 200

Either of the integer pointers can be a nullptr if we don't care about the minimum size in that dimension:

1int minW, minH;
2
3// We only care about the minimum width
4SDL_GetWindowMinimumSize(Window, &minW, nullptr);
5
6// We only care about the minimum height
7SDL_GetWindowMinimumSize(Window, nullptr, &minH);

Maximum Size

For the maximum window size, we have the SDL_SetWindowMaximumSize() and SDL_GetWindowMaximumSize() functions. These work in the same way as their minimum-size counterparts:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7SDL_SetWindowMaximumSize(Window, 1200, 1200);
8
9int maxW, maxH;
10SDL_GetWindowMaximumSize(Window, &maxW, &maxH);
11
12std::cout << "Maximum Width: " << maxW
13  << "\nMaximum Height: " << maxH;

1Maximum Width: 1200
2Maximum Height: 1200

Getting the Current Window Size

We can request the current window size at any time using the SDL_GetWindowSize() function. We pass the window pointer and two pointers to integers. The integers will be updated with the width and height of the window respectively:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7int w, h;
8SDL_GetWindowSize(Window, &w, &h);
9std::cout << "Size: " << w << "x" << h;

1Size: 600x300

If we only care about the size in a single dimension, we can pass a nullptr as the other argument:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7int w;
8SDL_GetWindowSize(Window, &w, nullptr);
9std::cout << "Width: " << w;
10
11int h;
12SDL_GetWindowSize(Window, nullptr, &h);
13std::cout << "\nHeight: " << h;

1Width: 600
2Height: 300

Programmatic Resizing

In addition to letting users resize our window, we can programmatically resize our window at any time. We do this using the SDL_SetWindowSize() function, passing our SDL_Window pointer, and two integers representing the desired width and height respectively:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7int w, h;
8SDL_GetWindowSize(Window, &w, &h);
9std::cout << "\nSize: " << w << "x" << h;
10
11SDL_SetWindowSize(Window, 500, 700);
12
13SDL_GetWindowSize(Window, &w, &h);
14std::cout << "\nSize: " << w << "x" << h;

1Size: 600x300
2Size: 500x700

Maximising and Restoring Windows

Desktop platforms typically support the idea of having a window maximized within a screen. Maximized windows are sized and positioned to fill almost the entire visible area of the screen, only leaving space for some platform-specific elements like the taskbar on Windows.

If our SDL_Window is resizable, users will typically also be able to maximize it by, for example, double-clicking the title bar in Windows or macOS:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  // If a window is resizable, it will also
5  // also be maximizable in supported platforms
6  SDL_WINDOW_RESIZABLE
7)};

We can also create our window in the maximized state using the SDL_WINDOW_MAXIMIZED flag. This does not require the window to be resizable but, in most circumstances, we'll want a maximized window to also be resizable:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  SDL_WINDOW_RESIZABLE | SDL_WINDOW_MAXIMIZED
5)};

Maximising Windows Using `SDL_MaximizeWindow()`

We can maximize an existing window by passing its SDL_Window pointer to SDL_MaximizeWindow():

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7SDL_MaximizeWindow(Window);

Restoring Windows Using `SDL_RestoreWindow()`

When a window is maximized, the platform remembers its previous position and size. We can restore a window to this state by passing its SDL_Window pointer to SDL_RestoreWindow():

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7SDL_MaximizeWindow(Window);
8SDL_RestoreWindow(Window);

Checking if a Window is Maximized

We can check if a window is currently maximized by retrieving its SDL_WindowFlags and isolating the SDL_WINDOW_MAXIMIZED bit:

1SDL_Window* Window{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  SDL_WINDOW_RESIZABLE | SDL_WINDOW_MAXIMIZED
5)};
6
7if (SDL_GetWindowFlags(Window) &
8    SDL_WINDOW_MAXIMIZED) {
9  std::cout << "Window is maximized";
10}

1Window is maximized

Window Resize Events

When a window's size changes for any reason, SDL dispatches a top-level event with the type SDL_EVENT_WINDOW_RESIZED. This happens whether the change was caused by the user dragging the window border or by a programmatic call to a function like SDL_SetWindowSize().

The new horizontal and vertical dimensions of the window are available in the data1 and data2 members of the SDL_WindowEvent struct, which can be accessed via Event.window:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleWindowEvent(const SDL_WindowEvent& E) {
7  if (E.type == SDL_EVENT_WINDOW_RESIZED) {
8    std::cout << "Window Resized to: "
9      << E.data1 << "x" << E.data2 << '\n';
10  }
11}
12
13int main(int, char** argv) {
14  SDL_Init(SDL_INIT_VIDEO);
15  Window GameWindow;
16  SDL_Event E;
17
18  bool IsRunning = true;
19  while (IsRunning) {
20    while (SDL_PollEvent(&E)) {
21      if (E.type >= SDL_EVENT_WINDOW_FIRST &&
22          E.type <= SDL_EVENT_WINDOW_LAST) {
23        HandleWindowEvent(E.window);
24      } else if (E.type == SDL_EVENT_QUIT) {
25        IsRunning = false;
26      }
27    }
28    GameWindow.Render();
29    GameWindow.Update();
30  }
31
32  SDL_Quit();
33  return 0;
34}

1Window Resized to: 831x497

Window Maximize and Minimize Events

Window resize events will also be triggered if the act of maximizing or restoring a window causes the size to change. However, if we need to react to maximizing and restoring actions explicitly, additional top-level events are also reported to help us achieve that: SDL_EVENT_WINDOW_MAXIMIZED and SDL_EVENT_WINDOW_RESTORED.

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleWindowEvent(const SDL_WindowEvent& E) {
7  if (E.type == SDL_EVENT_WINDOW_RESIZED) {
8    std::cout << "Window Resized to "
9      << E.data1 << 'x' << E.data2 << '\n';
10  } else if (E.type == SDL_EVENT_WINDOW_MAXIMIZED) {
11    std::cout << "Maximized: ";
12  } else if (E.type == SDL_EVENT_WINDOW_RESTORED) {
13    std::cout << "Restored: ";
14  }
15}
16
17int main(int, char**) {/*...*/}

1Maximized: Window Resized to 2560x1369
2Restored: Window Resized to 600x300

Summary

This lesson explored the ways in which we manage our window sizes. Key points to remember include:

Use the SDL_WINDOW_RESIZABLE flag to create a resizable window, or to determine if an existing window is resizable.
The SDL_SetWindowResizable() function lets us configure whether an existing window is resizable.
Use SDL_SetWindowMinimumSize() and SDL_SetWindowMaximumSize() to limit the extent to which a window is resizable.
We can programmatically resize a window using SDL_SetWindowSize().
SDL_GetWindowSize() lets us determine the current size of a window.
Windows can be maximized and restored using SDL_MaximizeWindow() and SDL_RestoreWindow().
If we need to react to users resizing, maximizing or restoring our windows, we can monitor the event loop for the corresponding top-level events.

Window Sizing

Starting Point

Files

Setting the Window Size

Resizable Windows

Using `SDL_SetWindowResizable()`

Checking if a Window is Resizable

Minimum Size

Maximum Size

Getting the Current Window Size

Programmatic Resizing

Maximising and Restoring Windows

Maximising Windows Using `SDL_MaximizeWindow()`

Restoring Windows Using `SDL_RestoreWindow()`

Checking if a Window is Maximized

Window Resize Events

src/main.cpp

Window Maximize and Minimize Events

src/main.cpp

Summary

Game Development with SDL3

Window Sizing

Starting Point

Files

Setting the Window Size

Resizable Windows

Using SDL_SetWindowResizable()

Checking if a Window is Resizable

Minimum Size

Maximum Size

Getting the Current Window Size

Programmatic Resizing

Maximising and Restoring Windows

Maximising Windows Using SDL_MaximizeWindow()

Restoring Windows Using SDL_RestoreWindow()

Checking if a Window is Maximized

Window Resize Events

src/main.cpp

Window Maximize and Minimize Events

src/main.cpp

Summary

Using `SDL_SetWindowResizable()`

Maximising Windows Using `SDL_MaximizeWindow()`

Restoring Windows Using `SDL_RestoreWindow()`