On some platforms, we can set the opacity of our window. In this lesson, we explore how to adjust the transparency of SDL3 windows using `SDL_SetWindowOpacity()` and `SDL_GetWindowOpacity()`. We'll cover how to handle errors, retrieve the current opacity, and understand the practical uses of window transparency. Opacity is represented by a floating-point number ranging from `0.0` to `1.0`. The default value is `1.0`, which represents a completely opaque window. A window with an opacity of `0.0` is fully transparent. Intermediate values between `0.0` and `1.0` are used to make our windows semi-transparent. The following window has an opacity of `0.5`: Screenshot showing a semitransparant window

Screenshot showing a semitransparant window

## Setting Opacity Using `SDL_SetWindowOpacity()` To change a window's opacity, we use the `SDL_SetWindowOpacity()` function. This function takes two arguments: a pointer to the `SDL_Window` whose opacity we want to change and a `float` value representing the desired opacity. The value should be between `0.0` (fully transparent) and `1.0` (fully opaque): ```c++ SDL_Window* Window{SDL_CreateWindow( "Window", 400, 200, 0)}; SDL_SetWindowOpacity(Window, 0.5f);// ``` ### Error Handling When Setting Opacity In SDL3, `SDL_SetWindowOpacity()` returns a `bool` indicating success or failure. This aligns with the updated error-handling pattern across the library. The function will fail if the provided `SDL_Window*` is invalid or if the platform doesn't support window opacity. As usual, we can call `SDL_GetError()` to retrieve an explanation for the failure, a technique we covered in our lesson on error handling. ```c++ if (!SDL_SetWindowOpacity(nullptr, 0.5f)) {// std::cout << "Error Setting Opacity: " << SDL_GetError();// } ``` ```c++ // Error Setting Opacity: Invalid window ``` ## Retrieving Opacity Using `SDL_GetWindowOpacity()` In SDL3, `SDL_GetWindowOpacity()` has been simplified to directly return the window's current opacity as a `float`. This is a change from SDL2, which used an output parameter. ```c++ SDL_Window* Window{SDL_CreateWindow( "Window", 400, 200, 0)}; float Opacity = SDL_GetWindowOpacity(Window); std::cout << "Window Opacity: " << Opacity; SDL_SetWindowOpacity(Window, 0.5f); Opacity = SDL_GetWindowOpacity(Window); std::cout << "\nWindow Opacity: " << Opacity; ``` ```c++ // Window Opacity: 1 Window Opacity: 0.5 ``` ### Error Handling When Retrieving Opacity If `SDL_GetWindowOpacity()` fails (for example, if an invalid window pointer is passed), it will return `-1.0f`. We can check for this value to detect errors. ```c++ float Opacity = SDL_GetWindowOpacity(nullptr); if (Opacity < 0.0f) {// std::cout << "Error Getting Opacity: " << SDL_GetError();// } ``` ```c++ // Error Getting Opacity: Invalid window ``` If the platform does not support opacity, `SDL_GetWindowOpacity()` will not report an error. Instead, it will simply return `1.0f`, indicating the window is fully opaque. ### Window Visibility If we want to make a window invisible, it's generally preferred to hide it rather than setting its opacity to `0.0`. We can hide and show a window by passing its `SDL_Window*` to `SDL_HideWindow()` or `SDL_ShowWindow()` respectively: ```c++ // Hide the window SDL_HideWindow(Window); // Show the window SDL_ShowWindow(Window); ``` We cover window visibility in more detail in the next lesson. ## Summary In this lesson, we introduced how to manage window opacity in SDL3. We covered how to use `SDL_SetWindowOpacity()` and `SDL_GetWindowOpacity()` to set and retrieve transparency values, along with handling errors. Key takeaways: - Use `SDL_SetWindowOpacity()` to adjust a window's transparency. - Retrieve a window's current opacity with `SDL_GetWindowOpacity()`. - Consider platform-specific limitations by implementing error handling and using `SDL_GetError()` to debug issues.

Window Opacity

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation