# GLSL Programming/Unity/Light Attenuation

“The Rich Fool” by Rembrandt Harmenszoon van Rijn, 1627. Note the attenuation of the candlelight with the distance from the candle.

This tutorial covers textures for light attenuation or — more generally spoken — textures as lookup tables.

It is based on Section “Cookies”. If you haven't read that tutorial yet, you should read it first.

### Texture Maps as Lookup Tables

One can think of a texture map as an approximation to a two-dimensional function that maps the texture coordinates to an RGBA color. If one of the two texture coordinates is kept fixed, the texture map can also represent a one-dimensional function. Thus, it is often possible to replace mathematical expressions that depend only on one or two variables by lookup tables in the form of texture maps. (The limitation is that the resolution of the texture map is limited by the size of the texture image and therefore the accuracy of a texture lookup might be insufficient.)

The main advantage of using such a texture lookup is a potential gain of performance: a texture lookup doesn't depend on the complexity of the mathematical expression but only on the size of the texture image (to a certain degree: the smaller the texture image the more efficient the caching up to the point where the whole texture fits into the cache). However, there is an overhead of using a texture lookup; thus, replacing simple mathematical expressions — including built-in functions — is usually pointless.

Which mathematical expressions should be replaced by texture lookups? Unfortunately, there is no general answer because it depends on the specific GPU whether a specific lookup is faster than evaluating a specific mathematical expression. However, one should keep in mind that a texture map is less simple (since it requires code to compute the lookup table), less explicit (since the mathematical function is encoded in a lookup table), less consistent with other mathematical expressions, and has a wider scope (since the texture is available in the whole fragment shader). These are good reasons to avoid lookup tables. However, the gains in performance might outweigh these reasons. In that case, it is a good idea to include comments that document how to achieve the same effect without the lookup table.

### Unity's Texture Lookup for Light Attenuation

Unity actually uses a lookup texture `_LightTextureB0` internally for the light attenuation of point lights and spotlights. (Note that in some cases, e.g. point lights without cookie textures, this lookup texture is set to `_LightTexture0` without `B`. This case is ignored here.) In Section “Diffuse Reflection”, it was described how to implement linear attenuation: we compute an attenuation factor that includes one over the distance between the position of the light source in world space and the position of the rendered fragment in world space. In order to represent this distance, Unity uses the ${\displaystyle z}$ coordinate in light space. Light space coordinates have been discussed in Section “Cookies”; here, it is only important that we can use the Unity-specific uniform matrix `_LightMatrix0` to transform a position from world space to light space. Analogously to the code in Section “Cookies”, we store the position in light space in the varying variable `positionInLightSpace`. We can then use the ${\displaystyle z}$ coordinate of this varying to look up the attenuation factor in the alpha component of the texture `_LightTextureB0` in the fragment shader:

```               float distance = positionInLightSpace.z;
// use z coordinate in light space as signed distance
attenuation =
texture2D(_LightTextureB0, vec2(distance)).a;
// texture lookup for attenuation
// alternative with linear attenuation:
//    float distance = length(vertexToLightSource);
//    attenuation = 1.0 / distance;
```

Using the texture lookup, we don't have to compute the length of a vector (which involves three squares and one square root) and we don't have to divide by this length. In fact, the actual attenuation function that is implemented in the lookup table is more complicated in order to avoid saturated colors at short distances. Thus, compared to a computation of this actual attenuation function, we save even more operations.

The shader code is based on the code of Section “Cookies”. The `ForwardBase` pass was slightly simplified by assuming that the light source is always directional without attenuation. The vertex shader of the `ForwardAdd` pass is identical to the code in Section “Cookies” but the fragment shader includes the texture lookup for light attenuation, which is described above. However, the fragment shader lacks the cookie attenuation in order to focus on the attenuation with distance. It is straightforward (and a good exercise) to include the code for the cookie again.

```Shader "GLSL light attenuation with texture lookup" {
Properties {
_Color ("Diffuse Material Color", Color) = (1,1,1,1)
_SpecColor ("Specular Material Color", Color) = (1,1,1,1)
_Shininess ("Shininess", Float) = 10
}
Pass {
Tags { "LightMode" = "ForwardBase" }
// pass for ambient light and
// first directional light source without attenuation

GLSLPROGRAM

// User-specified properties
uniform vec4 _Color;
uniform vec4 _SpecColor;
uniform float _Shininess;

// The following built-in uniforms (except _LightColor0)
// are also defined in "UnityCG.glslinc",
// i.e. one could #include "UnityCG.glslinc"
uniform vec3 _WorldSpaceCameraPos;
// camera position in world space
uniform mat4 _Object2World; // model matrix
uniform mat4 _World2Object; // inverse model matrix
uniform vec4 _WorldSpaceLightPos0;
// direction to or position of light source
uniform vec4 _LightColor0;
// color of light source (from Lighting.cginc)

varying vec4 position;
// position of the vertex (and fragment) in world space
varying vec3 varyingNormalDirection;
// surface normal vector in world space

#ifdef VERTEX

void main()
{
mat4 modelMatrix = _Object2World;
mat4 modelMatrixInverse = _World2Object; // unity_Scale.w
// is unnecessary because we normalize vectors

position = modelMatrix * gl_Vertex;
varyingNormalDirection = normalize(vec3(
vec4(gl_Normal, 0.0) * modelMatrixInverse));

gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;
}

#endif

#ifdef FRAGMENT

void main()
{
vec3 normalDirection = normalize(varyingNormalDirection);

vec3 viewDirection =
normalize(_WorldSpaceCameraPos - vec3(position));
vec3 lightDirection =
normalize(vec3(_WorldSpaceLightPos0));
// we assume that the light source in ForwardBase pass
// is a directional light source without attenuation

vec3 ambientLighting =
vec3(gl_LightModel.ambient) * vec3(_Color);

vec3 diffuseReflection = vec3(_LightColor0) * vec3(_Color)
* max(0.0, dot(normalDirection, lightDirection));

vec3 specularReflection;
if (dot(normalDirection, lightDirection) < 0.0)
// light source on the wrong side?
{
specularReflection = vec3(0.0, 0.0, 0.0);
// no specular reflection
}
else // light source on the right side
{
specularReflection = vec3(_LightColor0)
* vec3(_SpecColor) * pow(max(0.0, dot(
reflect(-lightDirection, normalDirection),
viewDirection)), _Shininess);
}

gl_FragColor = vec4(ambientLighting
+ diffuseReflection + specularReflection, 1.0);
}

#endif

ENDGLSL
}

Pass {
Tags { "LightMode" = "ForwardAdd" }
// pass for additional light sources
Blend One One // additive blending

GLSLPROGRAM

// User-specified properties
uniform vec4 _Color;
uniform vec4 _SpecColor;
uniform float _Shininess;

// The following built-in uniforms (except _LightColor0)
// are also defined in "UnityCG.glslinc",
// i.e. one could #include "UnityCG.glslinc"
uniform vec3 _WorldSpaceCameraPos;
// camera position in world space
uniform mat4 _Object2World; // model matrix
uniform mat4 _World2Object; // inverse model matrix
uniform vec4 _WorldSpaceLightPos0;
// direction to or position of light source
uniform vec4 _LightColor0;
// color of light source (from Lighting.cginc)

uniform mat4 _LightMatrix0; // transformation
// from world to light space (from Autolight.cginc)
uniform sampler2D _LightTextureB0;
// texture lookup (from Autolight.cginc)

varying vec4 position;
// position of the vertex (and fragment) in world space
varying vec4 positionInLightSpace;
// position of the vertex (and fragment) in light space
varying vec3 varyingNormalDirection;
// surface normal vector in world space

#ifdef VERTEX

void main()
{
mat4 modelMatrix = _Object2World;
mat4 modelMatrixInverse = _World2Object; // unity_Scale.w
// is unnecessary because we normalize vectors

position = modelMatrix * gl_Vertex;
positionInLightSpace = _LightMatrix0 * position;
varyingNormalDirection = normalize(vec3(
vec4(gl_Normal, 0.0) * modelMatrixInverse));

gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;
}

#endif

#ifdef FRAGMENT

void main()
{
vec3 normalDirection = normalize(varyingNormalDirection);

vec3 viewDirection =
normalize(_WorldSpaceCameraPos - vec3(position));
vec3 lightDirection;
float attenuation;

if (0.0 == _WorldSpaceLightPos0.w) // directional light?
{
attenuation = 1.0; // no attenuation
lightDirection = normalize(vec3(_WorldSpaceLightPos0));
}
else // point or spot light
{
vec3 vertexToLightSource =
vec3(_WorldSpaceLightPos0 - position);
lightDirection = normalize(vertexToLightSource);

float distance = positionInLightSpace.z;
// use z coordinate in light space as signed distance
attenuation =
texture2D(_LightTextureB0, vec2(distance)).a;
// texture lookup for attenuation
// alternative with linear attenuation:
//    float distance = length(vertexToLightSource);
//    attenuation = 1.0 / distance;
}

vec3 diffuseReflection =
attenuation * vec3(_LightColor0) * vec3(_Color)
* max(0.0, dot(normalDirection, lightDirection));

vec3 specularReflection;
if (dot(normalDirection, lightDirection) < 0.0)
// light source on the wrong side?
{
specularReflection = vec3(0.0, 0.0, 0.0);
// no specular reflection
}
else // light source on the right side
{
specularReflection = attenuation * vec3(_LightColor0)
* vec3(_SpecColor) * pow(max(0.0, dot(
reflect(-lightDirection, normalDirection),
viewDirection)), _Shininess);
}

gl_FragColor =
vec4(diffuseReflection + specularReflection, 1.0);
}

#endif

ENDGLSL
}
}
// The definition of a fallback shader should be commented out
// during development:
// Fallback "Specular"
}
```

If you compare the lighting computed by this shader with the lighting of a built-in shader, you will notice a difference in intensity by a factor of about 2 to 4. However, this is mainly due to additional constant factors in the built-in shaders. It is straightforward to introduce similar constant factors in the code above.

It should be noted that the ${\displaystyle z}$ coordinate in light space is not equal to the distance from the light source; it's not even proportional to that distance. In fact, the meaning of the ${\displaystyle z}$ coordinate depends on the matrix `_LightMatrix0`, which is an undocumented feature of Unity and can therefore change anytime. However, it is rather safe to assume that a value of 0 corresponds to very close positions and a value of 1 corresponds to farther positions.

Also note that point lights without cookie textures specify the attenuation lookup texture in `_LightTexture0` instead of `_LightTextureB0`; thus, the code above doesn't work for them. Moreover, the code doesn't check the sign of the ${\displaystyle z}$ coordinate, which is fine for spot lights but results in a lack of attenuation on one side of point light sources.

### Computing Lookup Textures

So far, we have used a lookup texture that is provided by Unity. If Unity wouldn't provide us with the texture in `_LightTextureB0`, we had to compute this texture ourselves. Here is some JavaScript code to compute a similar lookup texture. In order to use it, you have to change the name `_LightTextureB0` to `_LookupTexture` in the shader code and attach the following JavaScript to any game object with the corresponding material:

```@script ExecuteInEditMode()

public var upToDate : boolean = false;

function Start()
{
upToDate = false;
}

function Update()
{
if (!upToDate) // is lookup texture not up to date?
{
upToDate = true;
var texture = new Texture2D(16, 16);
// width = 16 texels, height = 16 texels
texture.filterMode = FilterMode.Bilinear;
texture.wrapMode = TextureWrapMode.Clamp;

renderer.sharedMaterial.SetTexture("_LookupTexture", texture);
// "_LookupTexture" has to correspond to the name
// of the uniform sampler2D variable in the shader
for (var j : int = 0; j < texture.height; j++)
{
for (var i : int = 0; i < texture.width; i++)
{
var x : float = (i + 0.5) / texture.width;
// first texture coordinate
var y : float = (j + 0.5) / texture.height;
// second texture coordinate
var color = Color(0.0, 0.0, 0.0, (1.0 - x) * (1.0 - x));
// set RGBA of texels
texture.SetPixel(i, j, color);
}
}
texture.Apply(); // apply all the texture.SetPixel(...) commands
}
}
```

In this code, `i` and `j` enumerate the texels of the texture image while `x` and `y` represent the corresponding texture coordinates. The function `(1.0-x)*(1.0-x)` for the alpha component of the texture image happens to produce similar results as compared to Unity's lookup texture.

Note that the lookup texture should not be computed in every frame. Rather it should be computed only when necessary. If a lookup texture depends on additional parameters, then the texture should only be recomputed if any parameter has been changed. This can be achieved by storing the parameter values for which a lookup texture has been computed and continuously checking whether any of the new parameters are different from these stored values. If this is the case, the lookup texture has to be recomputed.

### Summary

Congratulations, you have reached the end of this tutorial. We have seen:

• How to use the built-in texture `_LightTextureB0` as a lookup table for light attenuation.
• How to compute your own lookup textures in JavaScript.

If you still want to know more

• about light attenuation for light sources, you should read Section “Diffuse Reflection”.
• about the SECS principles (simple, explicit, consistent, minimal scope), you could read Chapter 3 of David Straker's book “C Style: Standards and Guidelines”, published by Prentice-Hall in 1991, which is available online.

Unless stated otherwise, all example source code on this page is granted to the public domain.