Gradients, number of keys and Alpha values?

Scripting
,
1

Hey everyone!

So I wanted to use Unity’s gradient controls to control certain aspects of my volume renderer, but I am either doing something wrong, or I am running into some rather strange limitations.
For one it seems like the number of keys is limited to 8? This is way too few for what I need. Is there a way to increase that number?
Further it seems like that while I can get the Colors to be in floats, I can not get more than 255 levels for the Alpha.
The Alpha levels might not be quite as bad, but 8 Gradient keys are waaaay too few.
Please tell me that there is a way around those limits.
Here is what I did to get the HDR for my gradient colors (the bool defines that). But it only seems to apply to the colors. I can not find an option to increase the number of keys?

gradientControls.OpacityAndColor = EditorGUILayout.GradientField(new GUIContent("OpacityAndColor"), gradientControls.OpacityAndColor, true);

Thanks a lot!

2

If you check out this page in the manual.
It says “Color keys of the gradient (maximum 8 color keys).”

You can make your own Gradient object, which isn’t that hard. However, you then need to make your own GradientField control for the IMGUI which is arguably harder.

If you really need this, a hybrid solution would be to make only a custom Gradient object, and ignore the IMGUI tool, and make a list of colors instead.

To implement your own custom Gradient object, you need to understand that it does two things. One is to collect keys which contain { color, alpha } properties, and the other is to evaluate (interpolate) based on some parameter t (typically 0 … 1). Gradient evaluators can be made much more fancy, but you seem to be okay with the basic linear interpolation.

To make this, you have to imagine having keys sitting anywhere between 0 … 1, so this is another property you need to account for: { t, color, alpha }. Then you have to be able to sort the keys based on t (ideally only when the list changes), to have an easier time finding the two neighboring ones for any arbitrary point on this segment.

Imagine a simple diagram of a segment going from 0 to 1, and now imagine 3 keys, positioned at 0%, 75% and 85%

Q1 What should a color at 50% be?
Q2 What should a color at 80% be?
Q3 What should a color at 90% be?

Let’s get you properly introduced to linear interpolation.

On one hand, you want a value that’s some % in between A and B.
You basically mix the two values in some linear proportion.
If you want them 50-50 you add half of A and half of B. You get an average, right? x = (a + b) * 0.5

However, a generalized “mixture” looks like this x = a * (1 - t) + b * t

Let’s check this out, if A was 10, and B was 20
This would make a t of 30% result in 10 * (1 - 0.3) + 20 * 0.3 = 7 + 6 = 13
Interesting right? You end up on a value exactly 3/10ths away from A, and 7/10ths away from B.
This means that t is literally at 30% of this segment between A and B.

An inverse concept is also important. If I told you we have A at 10 and B at 20 and some point X at 16, what’s t equal to? Intuitively you can guess it’s 60%, and it is, but let’s do the actual inversion

a * (1 - t) + b * t = x
b * t + a * (1 - t) = x
b * t + a - a * t = x
t * (b - a) + a = x
t * (b - a) = x - a
t = (x - a) / (b - a)

So if A was 10, and B was 20, and X was 16
(16 - 10) / (20 - 10) = 6 / 10 = 0.6

We can now formally write some code

// lerp is short for linear interpolation
float Lerp(float min, float max, float t) => min * (1f - t) + max * t;
float InverseLerp(float min, float max, float v) => (v - min) / (max - min);

Let’s now return to questions.

For Q1
t (50%) lies between keys 0 (0%) and 1 (75%).
Where would t be if we stretched this from 0 to 100%?
This is answered by InverseLerp(0, 0.75, 0.5) = 0.6666
So what’s the evaluated color here?
This is answered by Lerp(color1, color2, 0.6666) (note that this kind of lerp works with the colors)
This works with alpha as well.

For Q2
t (80%) lies between keys 1 (75%) and 2 (85%).
Where would t be if we stretched this from 0 to 100%?
InverseLerp(0.75, 0.85, 0.8) = 0.5
So what’s the evaluated color here?
This is answered by Lerp(color1, color2, 0.5)

For Q3
t (90%) lies to the right of the rightmost key 2 (85%).
Because there are no other neighbors, we assume that this key’s color is fixed.

This was the hardest part.

To find where input t lands exactly, you simply walk through the sorted keys in order, and accumulate them until the result surpasses it stop once a key’s t surpasses the input t. This key and the previous key are the neighbors. If there are no more keys and input t is still greater, or when there was no previous key, this is a fixed color (non-interpolated).

Code might look something like this (edit: check the next post for getNeighborKeys because I made a mistake)

public Color Evaluate(float t) {
  if(_keys.Length == 0) return new Color(0f, 0f, 0f, 0f);
  var n = getNeighborKeys(_keys, t);
  if(n.l < 0) return _keys[n.r].Color;
    else if(n.r < 0) return _keys[n.l].Color;
  return Color.Lerp(_keys[n.l].Color, _keys[n.r].Color, n.t);
}

Feel free to ask if you need more detail.

3

In fact upon further inspection, you do not accumulate the t’s in keys, because these values are absolute, not incremental. That’s a mistake on my part.

// this internal function is made so that it returns three values through a tuple
// this is particularly convenient in this case, because we want to get the left neighbor, the
// right neighbor, and the actual interpolant
(int l, int r, float t) getNeighborKeys(GradientKey[] keys, float t) {
  for(int i = 0; i < keys.Length; i++) {
    if(keys[i].t >= t) {
      if(i == 0) return ( -1, 0, 0f ); // we use -1 to denote that the neighbor is missing
      return ( i - 1, i, InverseLerp(keys[i - 1].t, keys[i].t, t) );
    }
  }
  return ( keys.Length - 1, -1, 0f );
}

edit: typos, typos everywhere :slight_smile:

4

Btw when it comes to lerping, Unity comes with basic lerps on its own.
You can simply use Mathf.Lerp and Mathf.InverseLerp. Likewise, there is also Color.Lerp.
Pay attention to Mathf.LerpUnclamped (and Color.LerpUnclamped) because this is the variant I have implemented above.

Unity’s (ordinary) Mathf.Lerp does this

public static float Lerp(float min, float max, float t) {
  t = Mathf.Clamp01(t); // this prevents t from being less than 0 or greater than 1
  return min * (1f - t) + max * t;
}

Color.Lerp thus does the following

public static Color Lerp(Color a, Color b, float t) {
  t = Mathf.Clamp01(t);
  return new Color(
    Mathf.Lerp(a.r, b.r, t),
    Mathf.Lerp(a.g, b.g, t),
    Mathf.Lerp(a.b, b.b, t),
    Mathf.Lerp(a.a, b.a, t)
  );
}

It is also worth noting that InverseLerp works correctly when min and max are different values, as apparent by that formula

float InverseLerp(float min, float max, float v) => (v - min) / (max - min);

If (max - min) evaluate to zero, we get division by zero (which might return NaN result). So you might want to handle that case differently. In reality, if the two values are very close to each other (or equal), the result should be any of the two, it doesn’t matter which one if they are so close to each other.

This is how you can handle this behavior for a more robust outcome

float InverseLerp(float min, float max, float v) {
  var denom = max - min;
  if(Mathf.Abs(denom) < 1E-7f) return min; // compare against a sufficiently small number for 32-bit precision
  return (v - min) / denom;
}
5

And so how do you actually assemble all of this into an actual gradient?

using System;
using System.Collections.Generic;
using UnityEngine;

public struct MyGradientKey {

  public float t { get; set; }
  public Color Color { get; set; } // comes with r, g, b, alpha

  public MyGradientKey(float t, Color color) {
    this.t = t;
    this.Color = color;
  }

}

public class MyGradient {

  List<MyGradientKey> _keys;

  public MyGradient() {
    _keys = new List<MyGradientKey>();
  }

  public int Count => _keys.Count;

  public MyGradientKey this[int index] {
    get => _keys[index];
    set { _keys[index] = value; sortKeys(); }
  }

  public void AddKey(float t, Color color)
    => AddKey(new MyGradientKey(t, color));

  public void AddKey(MyGradientKey key) {
    _keys.Add(key);
    sortKeys();
  }

  public void InsertKey(int index, float t, Color color)
    => InsertKey(index, new MyGradientKey(t, color));

  public void InsertKey(int index, MyGradientKey key) {
    _keys.Insert(index, key);
    sortKeys();
  }

  public void RemoveKey(int index) {
    _keys.RemoveAt(index);
    sortKeys();
  }

  public void RemoveInRange(float min, float max) {
    for(int i = _keys.Count - 1; i >= 0; i--)
      if(_keys[i].t >= min && _keys[i].t <= max) _keys.RemoveAt(i);
    sortKeys();
  }

  public void Clear() => _keys.Clear();

  void sortKeys() => _keys.Sort( (a, b) => a.t.CompareTo(b.t) );

  (int l, int r) getNeighborKeys(float t) {
    var l = Count - 1;

    for(int i = 0; i <= l; i++) {
      if(_keys[i].t >= t) {
        if(i == 0) return ( -1, i );
        return ( i - 1, i );
      }
    }

    return ( l, -1 );
  }

  public Color Evaluate(float t) {
    if(Count == 0) return new Color(0f, 0f, 0f, 0f);

    var n = getNeighborKeys(t);

    if(n.l < 0) return _keys[n.r].Color;
      else if(n.r < 0) return _keys[n.l].Color;

    return Color.Lerp(
      _keys[n.l].Color,
      _keys[n.r].Color,
      Mathf.InverseLerp(_keys[n.l].t, _keys[n.r].t, t)
    );
  }

}

There.

Edit: I’ve decided to simplify getNeighborKeys and compute interpolant in Evaluate instead. It looks and performs slightly better.

6

Thanks for the very in depth reply!
I will look into this once I get back to the gradients. Any idea why the Unity Devs chose to limit gradients to only 8 keys ( I mean I presume it is because it is a byte, but still)?
It is seems like a pretty bad limitation.

7

I think it was an intentional design limit made with performance in mind. Or to make you aware that you should really do something of your own if you want anything more specialized than that. Or both.

It’s not because it’s a byte though. 8 keys are structs, each having at least 4 bytes (32-bit floating point), one for each channel. Each gradient object thus has at most 32 bytes + overhead array info.