Brightness and Gamma

Game developers need precise control over how their games appear on screen. In this lesson, we'll cover SDL's display management functions, learning how to adjust brightness, work with gamma curves, and implement color correction.

Players are often asked to configure the brightness of our game the first time they launch it. This is because the displays we develop the game on are likely to have different settings to what a player is using, and the environment they’re playing in has different lighting to the environment where we made the game.

By letting players calibrate the brightness, it lets them get the experience closer to what we intended:

Setting Display Brightness

The SDL_SetWindowBrightness() function can help us set the brightness of a window or, more typically, the display that the window is on. We pass the SDL_Window pointer as the first argument, and a floating point number representing the desired brightness as the second argument:

1#include <SDL.h>
2
3int main(int argc, char* argv[]) {
4  SDL_Init(SDL_INIT_VIDEO);
5
6  SDL_Window* Window{SDL_CreateWindow(
7    "Window",
8    SDL_WINDOWPOS_UNDEFINED,
9    SDL_WINDOWPOS_UNDEFINED,
10    800, 600, 0
11  )};
12
13  SDL_SetWindowBrightness(Window, 2.0);
14
15  SDL_DestroyWindow(Window);
16  SDL_Quit();
17  return 0;
18}

The default brightness is 1.0, whilst the range of acceptable values depends on the platform. Recent versions of Windows typically support values from 0.25 to 4.0.

Error Handling

The SDL_SetWindowBrightness() function returns 0 if it was successful, or a negative error code otherwise. If the call fails, we can call SDL_GetError() for an explanation of what went wrong:

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char* argv[]) {
5  SDL_Init(SDL_INIT_VIDEO);
6
7  if (SDL_SetWindowBrightness(nullptr, 2.0) < 0) {
8    std::cout << "Error Setting Brightness: "
9      << SDL_GetError();
10  }
11
12  SDL_Quit();
13  return 0;
14}

1Error Setting Brightness: Invalid window

Getting Display Brightness

The SDL_GetWindowBrightness() function lets us query the current brightness setting of a display. It returns a floating-point value representing the brightness level, where 1.0 represents normal brightness.

We pass the SDL_Window pointer as an argument:

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char* argv[]) {
5  SDL_Init(SDL_INIT_VIDEO);
6
7  SDL_Window* Window{SDL_CreateWindow(
8    "Brightness Demo",
9    SDL_WINDOWPOS_UNDEFINED,
10    SDL_WINDOWPOS_UNDEFINED,
11    800, 600, 0
12  )};
13
14  // Get initial brightness
15  float InitialBrightness{
16    SDL_GetWindowBrightness(Window)};
17
18  std::cout << "Initial brightness: "
19    << InitialBrightness << '\n';
20
21  // Change brightness
22  SDL_SetWindowBrightness(Window, 2.0);
23
24  float NewBrightness{
25    SDL_GetWindowBrightness(Window)};
26    
27  std::cout << "New brightness: "
28    << NewBrightness << '\n';
29
30  SDL_DestroyWindow(Window);
31  SDL_Quit();
32  return 0;
33}

1Initial brightness: 1
2New brightness: 2

This can be particularly useful when implementing features like brightness sliders or automatic brightness adjustment based on game events.

Gamma

Conceptually, we can think of any color as having an associated brightness. This is easiest to visualise with grayscale colors, where colors closer to white have higher brightness values. We often represent these brightnesses on a scale from 0.0 to 1.0:

We can think of brightness adjustment as being a function that accepts the color as an argument, and returns a similar color with a different brightness:

1float GetAdjustedColor(float Color) {
2  float AdjustedColor{/* Calculate me */};
3  return AdjustedColor;
4}

To do this, we can define an additional floating point number. This number is applied as an exponent for the input color to calculate the desired output color. This exponent is often represented by the greek letter gamma - $\gamma$

Mathematically, the function looks like this:

We can use SDL_pow() or the C++ standard library’s std::powf() function to calculate exponents. Therefore, in C++, our function might look like this:

1#include <iostream>
2
3float GetAdjustedColor(float Color, float Gamma) {
4  return std::powf(Color, Gamma);
5  
6  // Alternatively:
7  // return SDL_pow(Color, Gamma);
8}
9
10int main() {
11  std::cout
12    << "Input: 0.0, Gamma: 2.0, Output: "
13    << GetAdjustedColor(0, 2)
14    << "\nInput: 0.5, Gamma: 2.0, Output: "
15    << GetAdjustedColor(0.5, 2)
16    << "\nInput: 0.5, Gamma: 0.5, Output: "
17    << GetAdjustedColor(0.5, 0.5)
18    << "\nInput: 1.0, Gamma: 2.0, Output: "
19    << GetAdjustedColor(1, 2);
20}

1Input: 0.0, Gamma: 2.0, Output: 0
2Input: 0.5, Gamma: 2.0, Output: 0.25
3Input: 0.5, Gamma: 0.5, Output: 0.707107
4Input: 1.0, Gamma: 2.0, Output: 1

This function has two notable characteristics. First, it doesn’t change the range of our color values - the outputs are also in the range 0.0 to 1.0, as $0^{\gamma} = 0$ and $1^{\gamma} = 1$, regardless of the $\gamma$ value we use.

Secondly, it means lower gamma values result in brighter output colors, due to the effect that exponents have on values in the range of 0.0 to 1.0.

For example, let’s imagine we have an input color of $0.5$.

• Applying a gamma value of $2$ will reduce this brightness, as $0.5^2 = 0.25$.
• Applying a gamma value of $0.5$ will increase the brightness, as $0.5^{0.5} \thickapprox 0.71$.

Whilst these examples have used grayscale colors, the same idea can be applied to all colors. The only difference is that, instead of representing our color by a single floating point number, we would have three, representing the red, green and blue channels:

A C++ type to represent a color, and a function to change it, might look something like this:

1#include <cmath>
2
3struct Color {
4  float Red;
5  float Green;
6  float Blue;
7};
8
9Color GetAdjustedColor(Color C, float Gamma) {
10  return {
11    std::powf(C.Red, Gamma),
12    std::powf(C.Green, Gamma),
13    std::powf(C.Blue, Gamma),
14  };
15}

Gamma Curves

We can visualise the effect of different gamma correcting functions as a curve on a chart. Below, we plot the input values on the horizontal axis, and the corresponding output value of our gamma-correcting function on the vertical axis.

If our function returns the exact same value as its input (ie, the gamma value is 1.0), our function will be a straight line, and our output will be identical to our input:

Gamma values other than 1.0 will change the shape of our curve, and the effect the corresponding function will have on our output:

We’re not restricted to using simple $output = input^{\gamma}$ functions to define these ramps. Whilst these functions are useful if we just want to adjust the brightness, we can use gamma ramps for other effects too:

We can also have different gamma ramps for each of the red, green and blue components of a color. Below, we use this technique to reduce the amount of red in our output, whilst increasing the green and blue:

Gamma Ramps in SDL

SDL refers to these gamma curves as ramps, and represents them as a C-style array of 256 unsigned integers, each having 16 bits (Uint16). This means that our luminance values are represented by integers from 0 to 65,535, the maximum value of a Uint16.

Whilst this makes the maths a little different from the more common 0.0 to 1.0 representation, SDL takes care of that for us, and the underlying concepts are the same.

We are free to use any technique we want to construct an array of 256 Uint16 values, but for the simple case where we want to implement an $output = input^{\gamma}$ function, the SDL_CalculateGammaRamp() function can help us.

We pass the gamma value we want to use, and the pointer to the 256-element array we want to populate:

1Uint16 Ramp[256];
2SDL_CalculateGammaRamp(1.0, Ramp);
3std::cout << "Ramp from " << Ramp[0]
4  << " to " << Ramp[255];

1Ramp from 0 to 65535

We cover C-style arrays in more detail here:

C-Style Arrays

A detailed guide to working with classic C-style arrays within C++, and why we should avoid them where possible

Setting the Gamma Ramp

Once we have created our 256 integers representing a gamma ramp, we can apply it to our display using the SDL_SetWindowGammaRamp() function. We pass the SDL_Window* as the first argument, and the ramp to the second, third and fourth arguments, representing the red, green, and blue channel respectively.

Below, we recreate our previous example where we set the display’s brightness to 2.0, except this time using the gamma-based approach:

1#include <SDL.h>
2
3int main(int argc, char* argv[]) {
4  SDL_Init(SDL_INIT_VIDEO);
5
6  SDL_Window* Window{SDL_CreateWindow(
7    "Window",
8    SDL_WINDOWPOS_UNDEFINED,
9    SDL_WINDOWPOS_UNDEFINED,
10    800, 600,
11    SDL_WINDOW_SHOWN
12  )};
13
14  Uint16 Ramp[256];
15  SDL_CalculateGammaRamp(2.0, Ramp);
16  SDL_SetWindowGammaRamp(
17    Window, Ramp, Ramp, Ramp);
18
19  SDL_DestroyWindow(Window);
20  SDL_Quit();
21  return 0;
22}

The SDL_SetWindowGammaRamp() gives us more flexibility than SDL_SetWindowBrightness() in two ways

1. Our ramp doesn’t need to come from SDL_CalculateGammaRamp(), or any other form of simple $output = input^{\gamma}$ calculation. We can generate the 256-element array in any way we want, giving us complete control over the shape of our gamma curve.
2. Each color channel (red, green and blue) can use different gamma ramps, letting us completely change the look of our output, controlling how shadows, midtones and highlights are handled for each color.

Professional photo and video editing tools combine these techniques for their color grading workflows, allowing users to define gamma curves on a per-channel basis:

Error Handling

The SDL_SetWindowGammaRamp() function handles errors in a similar way to other SDL functions. It returns a negative error code if it encounters an error, and we can call SDL_GetError() for an explanation of what went wrong:

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char* argv[]) {
5  SDL_Init(SDL_INIT_VIDEO);
6
7  Uint16 Ramp[256];
8  SDL_CalculateGammaRamp(2.0, Ramp);
9
10  if (SDL_SetWindowGammaRamp(
11    nullptr, Ramp, Ramp, Ramp) < 0
12  ) {
13    std::cout << "Error setting gamma ramp: "
14      << SDL_GetError();
15  }
16
17  SDL_Quit();
18  return 0;
19}

1Error setting gamma ramp: Invalid window

Getting the Gamma Ramp

We can retrieve the gamma ramp associated with a window or the display the window is on using the SDL_GetWindowGammaRamp() function. We pass four arguments:

1. The SDL_Window pointer we want to query
2. The memory location to update with the red channel ramp
3. The memory location to update with the green channel ramp
4. The memory location to update with the blue channel ramp

Each of the memory locations should have enough space to store a collection of 256 integers, each of 16 bits:

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char* argv[]) {
5  SDL_Init(SDL_INIT_VIDEO);
6
7  SDL_Window* Window{SDL_CreateWindow(
8    "Window",
9    SDL_WINDOWPOS_UNDEFINED,
10    SDL_WINDOWPOS_UNDEFINED,
11    800, 600, 0
12  )};
13
14  Uint16 Red[256];
15  Uint16 Green[256];
16  Uint16 Blue[256];
17  SDL_GetWindowGammaRamp(
18    Window, Red, Green, Blue);
19
20  std::cout << "Red ramping from " << Red[0]
21    << " to " << Red[255];
22
23  SDL_DestroyWindow(Window);
24  SDL_Quit();
25  return 0;
26}

1Red ramping from 0 to 65535

We can pass nullptr values to any of the memory locations if we don’t care about the ramp that is used in that specific channel:

1Uint16 Red[256];
2  
3// Only get the red channel ramp
4SDL_GetWindowGammaRamp(
5  Window, Red, nullptr, nullptr);

Error Handling

The SDL_GetWindowGammaRamp() also returns a negative error code if it encounters an error, and we can use the SDL_GetError() function for a description of that error:

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char* argv[]) {
5  SDL_Init(SDL_INIT_VIDEO);
6
7  Uint16 Red[256];
8  if (SDL_GetWindowGammaRamp(
9    nullptr, Red, nullptr, nullptr
10  ) < 0) {
11    std::cout << "Failed to get window ramp: "
12      << SDL_GetError();
13  }
14
15  SDL_Quit();
16  return 0;
17}

1Failed to get window ramp: Invalid window

Summary

In this lesson, we've explored SDL's display management capabilities, learning how to control brightness and implement gamma correction for our game graphics. Key takeaways:

• Use SDL_SetWindowBrightness() for simple brightness adjustments
• SDL_SetWindowGammaRamp() provides advanced color control
• Gamma curves can be customized for specific visual effects
• Each color channel can be controlled independently
• Remember to to consider and handle errors when working with display functions

Next Lesson

Pixel Density and High-DPI Displays

Learn how to create SDL applications that look great on modern displays across different platforms

ContinueView Course