In this lesson, we'll explore SDL3's window management system, learning how to create, configure, and respond to window events. We'll cover essential concepts like window creation, error handling, and event processing, providing the foundation needed to build robust windowed applications. ## Starting Point This lesson builds on our earlier work. To focus on window configuration, we will start with a minimal project containing just a `main.cpp` file and our `Window.h` class from earlier chapters. This provides a clean foundation for exploring the windowing system if you want to follow along. ```c++ #include #include #include "Window.h" int main(int, char**) { SDL_Init(SDL_INIT_VIDEO); Window GameWindow; SDL_Event Event; bool IsRunning = true; while (IsRunning) { while (SDL_PollEvent(&Event)) { if (Event.type == SDL_EVENT_QUIT) { IsRunning = false; } } GameWindow.Render(); GameWindow.Update(); } SDL_Quit(); return 0; } ``` ```c++ #pragma once #include class Window { public: Window() { SDLWindow = SDL_CreateWindow( "My Program", 600, 300, 0 ); } SDL_Window* GetRaw() const { return SDLWindow; } void Render() { const auto* Fmt = SDL_GetPixelFormatDetails( GetSurface()->format ); SDL_FillSurfaceRect( GetSurface(), nullptr, SDL_MapRGB(Fmt, nullptr, 50, 50, 50) ); } void Update() { SDL_UpdateWindowSurface(SDLWindow); } SDL_Surface* GetSurface() const { return SDL_GetWindowSurface(SDLWindow); } Window(const Window&) = delete; Window& operator=(const Window&) = delete; ~Window() { if (SDLWindow && SDL_WasInit(SDL_INIT_VIDEO)) { SDL_DestroyWindow(SDLWindow); } } private: SDL_Window* SDLWindow{nullptr}; }; ``` ## Creating Windows Using `SDL_CreateWindow()` As we've seen in previous lessons, the main way we create a window using SDL3 is the `SDL_CreateWindow()` function. It has been simplified from SDL2 and now accepts 4 arguments: ```c++ SDL_Window* Window{SDL_CreateWindow( "My Program", // Title 600, // Width 300, // Height 0 // Configuration )}; ``` 1. The window title. 2. The window's horizontal size - 600 points wide, in this example. 3. The window's vertical size - 300 points tall, in this example. 4. A collection of window flags representing configuration options. In this example, we've passed `0`, indicating we just want the default configuration. ### The `SDL_Window` Type Windows are internally managed by SDL, using a type called `SDL_Window`. The `SDL_CreateWindow()` function returns a pointer to the `SDL_Window` that it created. We should save this pointer, as we'll need to use it later: ```c++ SDL_Window* Window{SDL_CreateWindow( "My Program", 600, 300, 0 )}; ``` However, we should consider `SDL_Window` objects to be _**read-only**_. While it is possible to modify the properties and behavior of windows in our application, this should only be done through specific functions provided by SDL. Direct modification of the `SDL_Window` structure is not recommended. We'll cover most of these functions throughout this chapter. ### Deleting Windows Using `SDL_DestroyWindow()` The first function used with an `SDL_Window*` is `SDL_DestroyWindow()` which, as we might guess, deletes the window when we no longer need it. We should remember to call `SDL_DestroyWindow()` when we're done with any window. Window creation requires SDL to allocate quite a lot of memory so, to prevent memory leaks, we should tell SDL when it's safe to release those resources: ```c++ // Create the Window SDL_Window* Window{SDL_CreateWindow( "My Program", 600, 300, 0 )}; // Use the Window // ... // Destroy the Window when we're done SDL_DestroyWindow(Window);// ``` In most programs, our primary window will be open for the entire duration of our program, so this might not seem useful. However, as we'll see later in this chapter, a program can contain multiple windows. This can include temporary "utility windows" used to implement UI designs like tooltips and right-click menus. To manage this, we'll typically have a custom `Window` type that controls an `SDL_Window` in the context of our application. This involves creating the `SDL_Window` in its constructor, and destroying it in the destructor. We don't want objects of this type to be copyable, so we also delete the copy constructor and copy assignment operator: ```c++ #pragma once #include class Window { public: // ... ~Window() { if (SDLWindow && SDL_WasInit(SDL_INIT_VIDEO)) { SDL_DestroyWindow(SDLWindow); } } Window(const Window&) = delete; Window& operator=(const Window&) = delete; // ... }; ``` ### Error Handling The `SDL_CreateWindow()` function can fail. When this happens, it returns a `nullptr`, which we can test for using an `if` statement. We can also call `SDL_GetError()` to receive an explanation of why window creation failed, a technique we covered in our lesson on error handling. Below, we attempt to create a window using Metal (an API used on Apple systems) on a platform that doesn't support it: ```c++ #pragma once #include #include class Window { public: Window() { SDLWindow = SDL_CreateWindow( "My Program", 600, 300, SDL_WINDOW_METAL // ); if (!SDLWindow) {// std::cout << SDL_GetError() << '\n';// }// } // ... }; ``` ```c++ #include #include #include "Window.h" int main(int, char**) { SDL_Init(SDL_INIT_VIDEO); Window GameWindow; SDL_Quit(); return 0; } ``` ```c++ // Metal support is either not configured in SDL or not available in current SDL video driver (windows) or platform ``` ## Configuring Windows Using `SDL_WindowFlags` The 4th argument to `SDL_CreateWindow()` controlling our window configuration has a type of `SDL_WindowFlags`. In SDL3, this is a 64-bit unsigned integer that acts as a bit set, where each individual bit in the type corresponds to whether a specific setting should be enabled or disabled. A value of `0` corresponds to no flags being enabled: ```c++ SDL_WindowFlags Flags{0};// SDL_CreateWindow( "My Program", 600, 300, Flags // ); ``` SDL provides a collection of bit masks, helping us select specific bits within the `SDL_WindowFlags` bit set. We'll cover the available window flags throughout the rest of this chapter, but some examples include `SDL_WINDOW_FULLSCREEN`, `SDL_WINDOW_BORDERLESS`, and `SDL_WINDOW_RESIZABLE`: ```c++ SDL_WindowFlags A{SDL_WINDOW_FULLSCREEN}; SDL_WindowFlags B{SDL_WINDOW_BORDERLESS}; SDL_WindowFlags C{SDL_WINDOW_RESIZABLE}; ``` One of the benefits of a bit set is that we can easily select multiple flags at once using the `|` operator. Below, we create a set of flags that will make the window both borderless and resizable: ```c++ SDL_WindowFlags Flags{ SDL_WINDOW_BORDERLESS | SDL_WINDOW_RESIZABLE }; ``` Note that the bitwise OR operator uses a single vertical bar - `|` . It is not the same as the more common logical OR operator, which uses two: `||`. We cover bitwise operators and bit flags in much more detail in our introductory course. ## Retrieving Window Flags Using `SDL_GetWindowFlags()` When our program runs, the state of our window can be changed by the code we write or actions performed by the user. For example, whilst we may configure our window to be initially maximized, the user may later resize it. SDL keeps the `SDL_WindowFlags` associated with a window up to date through these interactions. We can get the current state of a window's flags by passing the `SDL_Window` pointer to `SDL_GetWindowFlags()`: ```c++ SDL_Window* Window{SDL_CreateWindow( "My Program", 600, 300, SDL_WINDOW_RESIZABLE | SDL_WINDOW_MAXIMIZED// )}; SDL_WindowFlags Flags{// SDL_GetWindowFlags(Window)// };// ``` We can examine the state of a specific flag by using the same masks we introduced earlier. To test if a flag is enabled, we use the bitwise AND operator, `&`. This will return `0` if the flag is disabled, and a non-zero number otherwise: ```c++ SDL_Window* Window{SDL_CreateWindow( "My Program", 600, 300, SDL_WINDOW_RESIZABLE | SDL_WINDOW_MAXIMIZED )}; SDL_WindowFlags Flags{ SDL_GetWindowFlags(Window) }; bool isMaximized{(Flags & SDL_WINDOW_MAXIMIZED) != 0};// ``` ## Updating the Window Class Remember, if any of the capabilities we introduce are useful to the program we're building, we can expand our `Window` class to incorporate them in a managed, elegant way. For example, we might update our `Window` constructor to accept an `SDL_WindowFlags` argument and a public method that can be used to determine if our window is currently maximized: ```c++ #pragma once #include #include class Window { public: Window(SDL_WindowFlags Flags = 0) {// SDLWindow = SDL_CreateWindow( "My Program", 600, 300, Flags // ); if (!SDLWindow) { std::cout << SDL_GetError() << '\n'; } } bool GetIsMaximized() const {// return (// SDL_GetWindowFlags(SDLWindow) &// SDL_WINDOW_MAXIMIZED// ) != 0;// }// // ... }; ``` ## Summary In this lesson, we've explored the basics of window management in SDL3. We've learned how to create windows, handle errors, and configure window behavior using flags Key takeaways: - Windows are created using `SDL_CreateWindow()` with customizable size and behavior. - We should consider the possibility that window creation can fail, and use `SDL_GetError()` to understand why. - Window management requires proper cleanup using `SDL_DestroyWindow()`. - `SDL_WindowFlags` control window behavior through bitwise operations. - Window state can be monitored through `SDL_GetWindowFlags()`.

Window Configuration

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation