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

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):

1SDL_Window* Window{SDL_CreateWindow(
2  "Window", 400, 200, 0)};
3
4SDL_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 .

1if (!SDL_SetWindowOpacity(nullptr, 0.5f)) {
2  std::cout << "Error Setting Opacity: "
3    << SDL_GetError();
4}

1Error 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.

1SDL_Window* Window{SDL_CreateWindow(
2  "Window", 400, 200, 0)};
3
4float Opacity = SDL_GetWindowOpacity(Window);
5std::cout << "Window Opacity: " << Opacity;
6
7SDL_SetWindowOpacity(Window, 0.5f);
8Opacity = SDL_GetWindowOpacity(Window);
9std::cout << "\nWindow Opacity: " << Opacity;

1Window Opacity: 1
2Window 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.

1float Opacity = SDL_GetWindowOpacity(nullptr);
2if (Opacity < 0.0f) {
3  std::cout << "Error Getting Opacity: "
4    << SDL_GetError();
5}

1Error 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.

Preview

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:

1// Hide the window
2SDL_HideWindow(Window);
3
4// Show the window
5SDL_ShowWindow(Window);

We cover window visibility in more detail in the .

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

Setting Opacity Using SDL_SetWindowOpacity()