Window Opacity

On some platforms, we can set the opacity of our window. In this lesson, we explore how to adjust the transparency of SDL2 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:

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", 100, 200, 400, 200, 0)};
3
4SDL_SetWindowOpacity(Window, 0.5);

Error Handling

SDL_SetWindowOpacity() returns 0 if successful, or a negative error code if unsuccessful. The function will fail if the SDL_Window* we provide doesn’t support opacity, or the platform itself doesn’t support window opacity.

As usual, we can call SDL_GetError() to retrieve an explanation for the failure:

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

1Error Setting Opacity: Invalid window

SDL_GetWindowOpacity()

We can retrieve the current opacity of a window using the SDL_GetWindowOpacity() function. We pass the SDL_Window* as the first argument, and a pointer to a floating point number as the second argument. Our floating point number will be updated with the window’s opacity:

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

1Window Opacity: 1
2Window Opacity: 0.5

Error Handling

SDL_GetWindowOpacity() returns 0 if it was successful, or a negative error code if it failed. We can use SDL_GetError() to retrieve an explanation for the failure:

1float Opacity;
2if (SDL_GetWindowOpacity(nullptr, &Opacity) < 0) {
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 set the value pointed to by our opacity pointer to 1.0, indicating the window is fully opaque.

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

Summary

In this lesson, we introduced how to manage window opacity in SDL2. 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.

Next Lesson

Window Visibility

Learn how to control the visibility of SDL2 windows, including showing, hiding, minimizing, and more

ContinueView Course