5.3. Common Functions

Common functions can be used within either vertex shaders or fragment shaders. These functions all operate in a component-wise fashion (see Table 5.3) The description column specifies the operation on each component.

Table 5.3. Common functions

Syntax	Description
float abs (float x) vec2 abs (vec2 x) vec3 abs (vec3 x) vec4 abs (vec4 x)	Returns x if x >= 0; otherwise, it returns -x.
float sign (float x) vec2 sign (vec2 x) vec3 sign (vec3 x) vec4 sign (vec4 x)	Returns 1.0 if x > 0, 0.0 if x = 0, or -1.0 if x < 0.
float floor (float x) vec2 floor (vec2 x) vec3 floor (vec3 x) vec4 floor (vec4 x)	Returns a value equal to the nearest integer that is less than or equal to x.
float ceil (float x) vec2 ceil (vec2 x) vec3 ceil (vec3 x) vec4 ceil (vec4 x)	Returns a value equal to the nearest integer that is greater than or equal to x.
float fract (float x) vec2 fract (vec2 x) vec3 fract (vec3 x) vec4 fract (vec4 x)	Returns x floor (x).
float mod (float x, float y) vec2 mod (vec2 x, float y) vec3 mod (vec3 x, float y) vec4 mod (vec4 x, float y)	Modulus. Returns x y * floor (x/y) for each component in x using the floating-point value y.
vec2 mod (vec2 x, vec2 y) vec3 mod (vec3 x, vec3 y) vec4 mod (vec4 x, vec4 y)	Modulus. Returns x y * floor (x/y) for each component in x using the corresponding component of y.
float min (float x, float y) vec2 min (vec2 x, vec2 y) vec3 min (vec3 x, vec3 y) vec4 min (vec4 x, vec4 y)	Returns y if y < x; otherwise, it returns x.
vec2 min (vec2 x, float y) vec3 min (vec3 x, float y) vec4 min (vec4 x, float y)	Returns minimum of each component of x compared with the floating-point value y.
float max (float x, float y) vec2 max (vec2 x, vec2 y) vec3 max (vec3 x, vec3 y) vec4 max (vec4 x, vec4 y)	Returns y if x < y; otherwise, it returns x.
vec2 max (vec2 x, float y) vec3 max (vec3 x, float y) vec4 max (vec4 x, float y)	Returns maximum of each component of x compared with the floating-point value y.
float clamp (float x, float minVal, float maxVal) vec2 clamp (vec2 x, float minVal, float maxVal) vec3 clamp (vec3 x, float minVal, float maxVal) vec4 clamp (vec4 x, float minVal, float maxVal)	Returns min (max (x, minVal), maxVal) for each component in x using the floating-point values minVal and maxVal. Results are undefined if minVal > maxVal.
vec2 clamp (vec2 x, vec2 minVal, vec2 maxVal) vec3 clamp (vec3 x, vec3 minVal, vec3 maxVal) vec4 clamp (vec4 x, vec4 minVal, vec4 maxVal)	Returns the component-wise result of min (max (x, minVal), maxVal). Results are undefined if minVal > maxVal.
float mix (float x, float y, float a) vec2 mix (vec2 x, vec2 y, float a) vec3 mix (vec3 x, vec3 y, float a) vec4 mix (vec4 x, vec4 y, float a)	Returns x * (1.0 a) + y * a, i.e., the linear blend of x and y using the floating-point value a. The value for a is not restricted to the range [0,1].
vec2 mix (vec2 x, vec2 y, vec2 a) vec3 mix (vec3 x, vec3 y, vec3 a) vec4 mix (vec4 x, vec4 y, vec4 a)	Returns the component-wise result of x * (1.0 a) + y * a, i.e., the linear blend of vectors x and y using the vector a. The value for a is not restricted to the range [0,1].
float step (float edge, float x) vec2 step (vec2 edge, vec2 x) vec3 step (vec3 edge, vec3 x) vec4 step (vec4 edge, vec4 x)	Returns 0 if x < edge; otherwise, it returns 1.0.
float smoothstep (float edge0, float edge1, float x) vec2 smoothstep (vec2 edge0, vec2 edge1, vec2 x) vec3 smoothstep (vec3 edge0, vec3 edge1, vec3 x) vec4 smoothstep (vec4 edge0, vec4 edge1, vec4 x)	Returns 0 if x <= edge0 and 1.0 if x >= edge1 and performs smooth Hermite interpolation between 0 and 1 when edge0 < x < edge1. Results are undefined if edge0 >= edge1.

Aside from their general usefulness as math functions, many of these functions are useful in creating interesting shaders, as we see in subsequent chapters. The abs function can ensure that a particular function never produces negative values. It can also introduce a discontinuity in an otherwise smooth function. As we see in Section 15.5, this property of the abs function is used to introduce discontinuities in a noise function to produce an effect that looks like turbulence. A graphical representation of the abs function is shown in Figure 5.2.

The sign function simply maps the incoming value to -1, 0, or 1, depending on its sign. This results in a discontinuous function, as shown in Figure 5.3.

The floor function produces a discontinuous stair-step pattern, as shown in Figure 5.4. The fractional part of each incoming value is dropped, so the output value is always the integer value that is closest to but less than or equal to the input value.

The ceil function is almost the same as the floor function, except that value returned is always the integer value that is closest to but greater than or equal to the input value. This function is shown in Figure 5.5. As you can see, this function looks the same as Figure 5.4 except that the output values are shifted up by one. (Although ceil and floor always produce integer values, the functions are defined to return floating-point data types.)

The fract function produces a discontinuous function where each segment has a slope of 1.0 (see Figure 5.6).

The mod function is very similar to fract. In fact, if we divide the result of mod(x, y) by y, the result is very nearly the same. The only difference is the period of the discontinuous segments (see Figure 5.7).

The clamp function is useful for making sure that a value is within a particular range. A common operation is

clamp(x, 0.0, 1.0);

which clamps the variable x to the range [0,1]. Because two comparisons are necessary for this function, you should use it only when there is a chance that the tested value could be outside either end of the specified range. For the min and max functions, only one comparison is necessary. If you know a value will not be less than 0, using

min(x, 1.0);

will likely be faster and may use fewer machine instructions than

clamp(x, 0.0, 1.0);

because there is no point in testing to see whether the final value is less than 0. Keep in mind that there is no need to clamp the final color and depth values computed by a fragment shader because they are clamped automatically by the back-end fixed functionality processing.

The min, max, and clamp functions are shown in Figure 5.8, Figure 5.9, and Figure 5.10. The min(x, y) function has a slope of 1 where x is less than y, and a slope of 0 where x is greater than y. This function is often used to put an upper bound on a value, for instance, to make sure the computed result never exceeds 1.0.

The max(x, y) function has a slope of 0 where x is less than y, and a slope of 1 where x is greater than y. This function is often used to put a lower bound on a value, for instance, to make sure the computed result never goes below 0.

The clamp(x, minVal, maxVal) function has a slope of 0 where x is less than minVal and where x is greater than maxVal, and it has a slope of 1 in between where x is greater than minVal and less than maxVal. It is functionally equivalent to the expression min(max(x, minVal), maxVal).

The step function creates a discontinuous jump at an arbitrary point (see Figure 5.11). We use this function to create a simple procedural brick shader in Chapter 6.

The smoothstep function (see Figure 5.12) is useful in cases in which you want a threshold function with a smooth transition. For the case in which t is a float, this is equivalent to

float t;
t = clamp((x - edge0) / (edge1 - edge0), 0.0, 1.0);
return t * t * (3.0 - 2.0 * t);

The cases for vec2, vec3, and vec4 differ from the preceding example only in the data type used to declare t.