# Functions#

## Color, masking and remapping functions#

### clamp#

Color Function Description
FP clamp(FP x, FP lo, FP hi) Constrain x to range [lo..hi]
FP compress(FP x, FP lo, FP hi) Compress the dynamic range from [0..1] to [lo..hi]
FP expand(FP x, FP lo, FP hi) Expand the dynamic range from [lo..hi] to [0..1]
FP contrast(FP x, FP c) Adjust the contrast: for c < 0.5, contrast is decreased, for c > 0.5, contrast is increased.
FP invert(FP x) Invert the value: returns 1 - x
FP remap(FP x,FP source, FP range,FP falloff, INTERP interp) General remapping function. When x is within +/- range of source, the result is one. The result falls to zero beyond that range over falloff distance. The falloff shape is controlled by interp.
COLOR hsi(COLOR x,FP h, FP s, FP i, FP map=1) Shift the hue by h (in degrees) and scales the saturation and intensity by s and i respectively. A map may be supplied which will control the shift - the full shift will happen when the map is one and no shift will happen when the map is zero. The shift will be scaled back for values between zero and one.
COLOR midhsi(COLOR x, FP h, FP s, FP i, FP map, FP falloff=1, INT interp=0) Like the hsi function except that the control map is centered around the mid point (value of 0.5) and can scale the shift in both directions. At the mid point, no shift happens. At 1.0, the full shift happens, and at 0.0, the full inverse shift happens. Additional falloff and interp controls are provided to adjust the map using the remap function. The default falloff and interp values result in no remapping.
COLOR rgbtohsl(COLOR rgb) COLOR hsltorgb(COLOR hsl) RGB to HSL color space conversion. HSL is Hue, Saturation, Lightness (all in range [0..1])These functions have also been extended to support rgb and hsl values outside of the range [0..1] in a reasonable way. For any rgb or hsl value (except for negative s values), the conversion is well-defined and reversible.
FP bias(FP x, FP b) Variation of gamma where control parameter b goes from 0 to 1 with values > 0.5 pulling the curve up and values < 0.5 pulling the curve down. Defined as pow(x, log(b)/log(0.5)).
FP gamma(FP x, FP g) Apply a gamma function. Returns pow(x, 1/g).
FP fit(FP x, FP a1, FP b1, FP a2, FP b2) Linear remapping of x from [a1..b1] to [a2..b2]
FP mix(FP a, FP b, FP alpha) Blend of a and b according to alpha. Defined as a * (1 - alpha) + b * alpha
FP boxstep(FP x, FP a)
FP gaussstep(FP x, FP a, FP b)
FP linearstep(FP x, FP a, FP b)
FP smoothstep(FP x, FP a, FP b)
The step functions are 0 for x < a and 1 for x > b (or x > a in the case of boxstep). Between a and b, the value changes continuously between 0 and 1. The gausstep function uses the standard gaussian "bell" curve which is based on an exponential curve. The smoothstep function uses a cubic curve. Intuitively, gausstep has a sharper transition near 1 and a softer transition near 0 whereas smoothstep is has a medium softness near both 1 and 0.

## Noise functions#

Noise Function Description
FP rand()
FP rand(FP min, FP max)
INT rand(INT seed)
Random number between [min..max] (or [0..1] if unspecified). If a seed is supplied, it will reset the random generator with the specified seed. Note: This set of functions is Clarisse-only. It should be used for debugging purposes only. The order of evaluation determines the outputted value as the seed is global to the application. In other word, you are not guaranteed to get reliable random numbers as the order of evaluation will change as soon as there's a modification in the dependency graph.
FP hash(FP seed)
FP hash(FP seed1, … FP seedN)
Like rand, but with no internal seeds. Any number of seeds may be given and the result will be a random function based on all the seeds.
FP cellnoise(VECTOR v)
FP cellnoise1(FP x)
FP cellnoise2(FP x, FP y)
FP cellnoise3(FP x, FP y, FP z)
COLOR ccellnoise(VECTOR v)
Generate a field of constant colored cubes based on the integer location. This is the same as the prman cellnoise function.
FP noise(VECTOR v)
FP noise(FP x, FP y)
FP noise(FP x, FP y, FP z)
FP noise(FP x, FP y, FP z, FP w)
COLOR cnoise(VECTOR v)
FP snoise(VECTOR v)
VECTOR vnoise(VECTOR v)
COLOR cnoise4(VECTOR v, FP t)
FP snoise4(VECTOR v, FP t)
VECTOR vnoise4(VECTOR v, FP t)
FP pnoise(VECTOR v, VECTOR period)
noise is a random function that smoothly blends between samples at integer locations. This is Ken Perlin's original noise function.cnoise functions return a RGB color while vnoise return a 3D vector. snoise functions return a signed FP in range [-1..1]. Finally, pnoise is a periodic noise.
FP perlin(VECTOR v)
COLOR cperlin(VECTOR v)
FP sperlin(VECTOR v)
VECTOR vperlin(VECTOR v)
Improved Perlin Noise, based on Ken Perlin's 2002 Java reference code. cperlin is a color noise, vperlin a vector noise and sperlin a signed FP noise within [-1..1].
FP fbm(VECTOR v, INT octaves = 6, FP lacunarity = 2, FP gain = 0.5)
COLOR cfbm(VECTOR v, INT octaves = 6, FP lacunarity = 2, FP gain = 0.5)
VECTOR vfbm( VECTOR v, INT octaves = 6, FP lacunarity = 2, FP gain = 0.5)
FBM (Fractal Brownian Motion) is a multi-frequency noise function. The base frequency is the same as the noise functions. The total number of frequencies is controlled by octaves. The lacunarity is the spacing between the frequencies - a value of 2 means each octave is twice the previous frequency. The gain controls how much each frequency is scaled relative to the previous frequency.
FP fbm4(VECTOR v, FP time, INT octaves = 6, FP lacunarity = 2, FP gain = 0.5)
COLOR cfbm4(VECTOR v, FP time, INT octaves = 6, FP lacunarity = 2, FP gain = 0.5)
VECTOR vfbm4(VECTOR v, FP time, INT octaves = 6, FP lacunarity = 2, FP gain = 0.5)
Time-dependent FBM functions.
FP turbulence(VECTOR v, INT octaves = 6, FP lacunarity = 2, FP gain = 0.5)
COLOR cturbulence(VECTOR v, INT octaves = 6, FP lacunarity = 2, FP gain = 0.5)
VECTOR vturbulence(VECTOR v, INT octaves = 6, FP lacunarity = 2, FP gain = 0.5)
Turbulence is a variant of FBM where the absolute value of each noise term is taken. This gives a more billowy appearance.
FP voronoi(VECTOR v, INT type = 1, FP jitter = 0.5, FP fbm_scale = 0, INT fbm_octaves = 4, FP fbm_lacunarity = 2, FP fbm_gain = 0.5)
COLOR cvoronoi(VECTOR v, INT type = 1, FP jitter = 0.5, FP fbm_scale = 0, INT fbm_octaves = 4, FP fbm_lacunarity = 2, FP fbm_gain = 0.5)
VECTOR pvoronoi(VECTOR v, INT type = 1, FP jitter = 0.5, FP fbm_scale = 0, INT fbm_octaves = 4, FP fbm_lacunarity = 2, FP fbm_gain = 0.5)
Voronoi is a cellular noise pattern. It is a jittered variant of cellnoise. cvoronoi returns a random color for each cell and pvoronoi returns the point location of the center of the cell. The type argument describes different variants of the noise function. The jitter argument controls how irregular the pattern is (jitter = 0 is like ordinary cellnoise). The fbm functions arguments can be used to distort the noise field. When fbm_scale is 0 (by default), there is no distortion. The remaining arguments are the same as for the FBM functions.

type = 1

type = 2

type = 3

type = 4

type = 5

## Selection functions#

Selection Function Description
INT cycle(INT index, INT lo, INT hi) Cycles through values in range [lo..hi] based on supplied index. This is an offset mod function.The result is computed as: (lo + value % (hi - lo + 1)).
INT pick(FP index, INT lo, INT hi)
INT pick(FP index, INT lo, INT hi, FP weight1, ..., FP weightN)
Picks values randomly in range [lo..hi] based on supplied index (which is automatically hashed). The values will be distributed according to the supplied weights. Any weights not supplied are assumed to be 1.0.
Examples:
- pick(value, 1, 10): returns integer values between 1 and 10.
- pick(value, 1, 10, 2, 2.5): the values 1 and 2 will be returned twice and 2.5 times as often respectively as compared to the other values (3-10)
- pick(value,10, 20, 1, 1, 0): values 10, 11, and 13 through 20 will be returned (12 is skipped due to zero weight)
FP choose(FP index, FP choice1, ..., FP choiceN) Chooses one of the supplied choices based on the index (assumed to be in range [0..1]).
FP wchoose(FP index, FP choice1, FP weight1, ...,FP choiceN, FP weightN) Chooses one of the supplied choices based on the index (assumed to be in range [0..1]). The values will be distributed according to the supplied weights.

## Maths functions and constants#

Math Function Description
FP abs(FP x) Absolute value of x
FP max(FP x, FP y) Greater of x and y (x > y ? x : y)
FP min(FP x, FP y) Lesser of x and y (x < y ? x : y)
FP fmod(FP x, FP y) Remainder of x / y (also available as % operator)
FP cbrt(FP x) Cube root of x
FP sqrt(FP x) Square root of x
FP ceil(FP x) Next higher integer
FP floor(FP x) Next lower integer
FP round(FP x) Nearest integer
FP trunc(FP x) Nearest integer towards 0
FP exp(FP x) E raised to the x power
FP log(FP x) Natural logarithm of x
FP log10(FP x) Decimal logarithm of x
FP pow(FP x, FP y) x to the y power (also available as ^ operator)

### Trigonometry functions#

Trigonometry Function Description
FP acos(FP x) Arc cosine of x in radians
FP asin(FP x) Arc sine of x in radians
FP atan(FP x) Arc tangent of x in radians
FP atan2(FP y, FP x) Arc tangent in radians of y/x in range [-PI..PI]
FP cos(FP x) Cosine of x in radians
FP sin(FP x) Sine of x in radians
FP tan(FP x) Tangent of x in radians
FP acosd(FP x) Arc cosine of x in degrees
FP asind(FP x) Arc sine of x in degrees
FP atand(FP x) Arc tangent of x in degrees
FP atan2d(FP x) Arc tangent in degrees of y/x in range [-180..180]
FP cosd(FP x) Cosine of x in degrees
FP sind(FP x) Sine of x in degrees
FP tand(FP x) Tangent of x in degrees
FP acosh(FP x) Hyperbolic arc cosine
FP asinh(FP x) Hyperbolic arc sine
FP atanh(FP x) Hyperbolic arc tangent
FP cosh(FP x) Hyperbolic cosine
FP sinh(FP x) Hyperbolic sine
FP tanh(FP x) Hyperbolic tangent
FP deg(FP x) Radians to degrees
FP rad(FP x) Degrees to radians
FP hypot(FP x, FP y) Length of 2D vector (x, y)

### Vector Functions#

3D Vector Function Description
FP angle(VECTOR u, VECTOR v) Angle between vectors u and v, in radians
VECTOR cross(VECTOR u, VECTOR v) Cross production of u and v
FP dist(FP ax, FP, ay, FP, az, FP bx, FP by, FP bz) Distance between two points a = (ax, ay, az) and b = (bx, by, bz)
FP dot(VECTOR u, VECTOR v) Dot product of u and v
FP length(VECTOR v) Length of vector v
VECTOR norm(VECTOR v) Scale vector v to unit-length
VECTOR ortho(VECTOR u, VECTOR v) Vector orthographic to vectors u and v
VECTOR up(VECTOR v, VECTOR up) Rotate v such that the Y axis points in the given up direction.
VECTOR rotate(VECTOR v, VECTOR axis, FP angle) Rotate v around axis by given angle (in radians)

### Curve Functions#

Curve Function Description
COLOR curve(FP param, FP pos0, COLOR val0, INT interp0, ..., FP posN, COLOR valN, INT interpN) Interpolates color ramp given by control points at param. Control points are specified by triples of parameters pos, val, and interp. Interpolation codes are:
- 0 - none,
- 1 - linear,
- 2 - smooth,
- 3 - spline,
- 4 - monotone (non-oscillating) spline
FP curve( FP param, FP pos0, FP val0, INT interp0, ..., FP posN, FP valN, INT interpN) Interpolates 1D ramp given by control points at param. Control points are specified by triples of parameters pos, val, and interp. Interpolation codes are:
- 0 - none,
- 1 - linear,
- 2 - smooth,
- 3 - spline,
- 4 - monotone (non-oscillating) spline
FP spline(FP param, FP y1, FP y2, ..., FP yN) Interpolates a set of values to the parameter specified where y are distributed evenly from [0..1]

### String Functions#

String Function Description
STRING sprintf(STRING format, ...) Returns a string formatted from given values. See man sprintf for format details. Example:
sprintf("%s/renders/frame_%04d.exr", PDIR, F)