Brightness and 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:

A gamma curve with a gamma value of 1

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

A gamma curve with a gamma value of 0.5 being used to increase image brightness

A gamma curve with a gamma value of 1

A gamma curve with a gamma value of 2 being used to reduce image brightness

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:

Using an S-shaped curve to increase image contrast

Using a gamma curve to invert the image

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:

Using gamma curves to color-correct the image

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:

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:

Curves Editor in DaVinci Resolve

Handling Errors When Setting Gamma

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

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

Handling Errors When Getting Gamma

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

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