Fullscreen Windows

We can update the fullscreen mode of an existing window using SDL_SetWindowFullscreen(). In SDL3, this function takes the SDL_Window pointer and a boolean:

1SDL_Window* Window{SDL_CreateWindow(
2  "Window",
3  800, 600, 0
4)};
5
6// Set window to be fullscreen
7SDL_SetWindowFullscreen(Window, true);

By default, windows use the non-exclusive, desktop full screen technique when we set SDL_SetWindowFullscreen() to true. We'll learn how to control this using SDL_SetWindowFullscreenMode() in the next lesson.

Exiting Fullscreen

To return to windowed mode from any fullscreen state, simply call SDL_SetWindowFullscreen() with false.

1// Disable fullscreen
2SDL_SetWindowFullscreen(Window, false);

Error Handling

The SDL_SetWindowFullscreen() function returns true on success and false on failure. We can check the return value and call SDL_GetError() for more information:

1if (!SDL_SetWindowFullscreen(nullptr, true)) {
2  std::cout << "Error changing fullscreen mode: "
3            << SDL_GetError();
4}

1Error changing fullscreen mode: Invalid window

Complete Example

Here is an example of toggling full screen in a complete program, where we can enter and exit full screen mode using the up and down arrows respectively:

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleKeyboardEvent(
7  const SDL_KeyboardEvent& E, SDL_Window* Window
8) {
9  if (E.key == SDLK_UP) {
10    if (!SDL_SetWindowFullscreen(Window, true)) {
11      std::cout << "Failed to set fullscreen: "
12        << SDL_GetError() << '\n';
13    } else {
14      std::cout << "Entered fullscreen mode\n";
15    }
16  } else if (E.key == SDLK_DOWN) {
17    if (!SDL_SetWindowFullscreen(Window, false)) {
18      std::cout << "Failed to exit fullscreen: "
19        << SDL_GetError() << '\n';
20    } else {
21      std::cout << "Exited fullscreen mode\n";
22    }
23  }
24}
25
26int main(int, char**) {
27  SDL_Init(SDL_INIT_VIDEO);
28  Window GameWindow;
29
30  std::cout << "Window created. Press UP arrow for "
31    "fullscreen, DOWN arrow to exit fullscreen.\n";
32
33  bool IsRunning = true;
34  SDL_Event E;
35  while (IsRunning) {
36    while (SDL_PollEvent(&E)) {
37      if (E.type == SDL_EVENT_QUIT) {
38        IsRunning = false;
39      } else if (E.type == SDL_EVENT_KEY_DOWN) {
40        HandleKeyboardEvent(E.key, GameWindow.GetRaw());
41      }
42    }
43    
44    GameWindow.Render();
45    GameWindow.Update();
46  }
47
48  SDL_Quit();
49  return 0;
50}

To check a window's current fullscreen state, we can use the SDL_GetWindowFlags() function, and then check the SDL_WINDOW_FULLSCREEN bit.

In the following program, we make our window full screen using the up arrow, revert it to a regular window using the down arrow, and log whether it is currently full screen using the spacebar

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6void HandleKeydownEvent(
7  const SDL_KeyboardEvent& E, SDL_Window* Window
8) {
9  if (E.key == SDLK_UP) {
10    SDL_SetWindowFullscreen(Window, true);
11  } else if (E.key == SDLK_DOWN) {
12    SDL_SetWindowFullscreen(Window, false);
13  } else if (E.key == SDLK_SPACE) {
14    SDL_WindowFlags Flags{SDL_GetWindowFlags(Window)};
15    if (Flags & SDL_WINDOW_FULLSCREEN) {
16      std::cout << "Fullscreen\n";
17    } else {
18      std::cout << "Windowed\n";
19    }
20  }
21}
22
23int main(int, char**) {
24  SDL_Init(SDL_INIT_VIDEO);
25  Window GameWindow;
26
27  SDL_Event E;
28  bool IsRunning = true;
29  while (IsRunning) {
30    while (SDL_PollEvent(&E)) {
31      if (E.type == SDL_EVENT_QUIT) {
32        IsRunning = false;
33      } else if (E.type == SDL_EVENT_KEY_DOWN) {
34        HandleKeydownEvent(E.key, GameWindow.GetRaw());
35      }
36    }
37
38    GameWindow.Render();
39    GameWindow.Update();
40  }
41
42  SDL_Quit();
43  return 0;
44}

1Window
2Fullscreen
3Window

On some platforms, certain window operations in like changing the fullscreen state are asynchronous. This means the function call - e.g., SDL_SetWindowFullscreen() - returns immediately, but the actual operation might still be in progress. The operating system could be performing an animation or other tasks before the window's state is fully updated.

Depending on our program and the platforms we're targetting, continuing to execute arbitrary instructions when the window itself is transitioning to a new state can cause issues.

To help with this, we can use SDL_SyncWindow(). This function will attempt to pause our program's execution until all pending changes for the specified window have been applied.

In our previous example, we could call SDL_SyncWindow() after setting or unsetting fullscreen mode like this:

1void HandleKeydownEvent(
2  const SDL_KeyboardEvent& E, SDL_Window* Window
3) {
4  if (E.key == SDLK_UP) {
5    SDL_SetWindowFullscreen(Window, true);
6    // Wait for the change to complete
7    SDL_SyncWindow(Window);
8  } else if (E.key == SDLK_DOWN) {
9    SDL_SetWindowFullscreen(Window, false);
10    // Wait for the change to complete
11    SDL_SyncWindow(Window);
12  } else if (E.key == SDLK_SPACE) {
13    SDL_WindowFlags Flags{SDL_GetWindowFlags(Window)};
14    if (Flags & SDL_WINDOW_FULLSCREEN) {
15      std::cout << "Fullscreen\n";
16    } else {
17      std::cout << "Windowed\n";
18    }
19  }
20}

Instead of polling the window flags, we can react to fullscreen state changes using SDL's event system. When a window enters or leaves fullscreen mode, SDL dispatches one of two top-level events:

• SDL_EVENT_WINDOW_ENTER_FULLSCREEN: Fired when the window successfully enters any fullscreen mode.
• SDL_EVENT_WINDOW_LEAVE_FULLSCREEN: Fired when the window leaves any fullscreen mode and returns to a windowed state.

Here's how you can handle these events in your event loop:

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  SDL_Event E;
10
11  bool IsRunning = true;
12  while (IsRunning) {
13    while (SDL_PollEvent(&E)) {
14      if (E.type == SDL_EVENT_WINDOW_ENTER_FULLSCREEN) {
15        std::cout << "Window entered fullscreen\n";
16      } else if (E.type == SDL_EVENT_WINDOW_LEAVE_FULLSCREEN) {
17        std::cout << "Window left fullscreen\n";
18      } else if (E.type == SDL_EVENT_QUIT) {
19        IsRunning = false;
20      }
21    }
22    GameWindow.Render();
23    GameWindow.Update();
24  }
25
26  SDL_Quit();
27  return 0;
28}

These events are triggered whether the change was initiated by your code using SDL_SetWindowFullscreen() or by some platform-specific mechanism.

To let users toggle the full screen state through their platform-specific controls, such as the green pill button on macOS, we generally need to declare the window to be resizable .

We can do that using the SDL_WINDOW_RESIZABLE flag, or the SDL_SetWindowResizable() function:

1SDL_Window* SomeWindow{SDL_CreateWindow(
2  "My Program",
3  600, 300,
4  SDL_WINDOW_RESIZABLE
5)};
6
7// Alternatively:
8SDL_SetWindowResizable(SomeWindow, true);

In this lesson, we've learned how to implement fullscreen functionality. We introduced both desktop and exclusive fullscreen modes, understanding their benefits and tradeoffs. Key takeaways:

• Desktop Fullscreen: Offers seamless multitasking
• Exclusive Fullscreen: Can offer better performance by changing the monitor's resolution. We cover this in more detail in the next lesson
• Runtime Switching: SDL_SetWindowFullscreen(window, bool) is the primary function for entering and exiting fullscreen modes.
• State Checking: To determine the current state, check for the SDL_WINDOW_FULLSCREEN flag.
• Async Operations: Synchronize window operations with SDL_SyncWindow() to ensure state changes are complete before proceeding.
• Events: Monitor fullscreen state changes using the SDL_EVENT_WINDOW_ENTER_FULLSCREEN and SDL_EVENT_WINDOW_LEAVE_FULLSCREEN events.