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:

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

Error Handling When Setting Opacity

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

Retrieving Opacity Using `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 When Retrieving Opacity

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.

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 a dedicated lesson later in this chapter.

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.

Window Opacity

Setting Opacity Using `SDL_SetWindowOpacity()`

Error Handling When Setting Opacity

Retrieving Opacity Using `SDL_GetWindowOpacity()`

Error Handling When Retrieving Opacity

Summary

Window Visibility

Game Development with SDL2

Questions & Answers

Window Opacity

Setting Opacity Using SDL_SetWindowOpacity()

Error Handling When Setting Opacity

Retrieving Opacity Using SDL_GetWindowOpacity()

Error Handling When Retrieving Opacity

Summary

Window Visibility

Questions & Answers

Setting Opacity Using `SDL_SetWindowOpacity()`

Retrieving Opacity Using `SDL_GetWindowOpacity()`