XGen Expressions

Many attributes in XGen are expressions. An expression is an extremely flexible way to specify how an attribute should be evaluated based on a combination of function calls and arithmetic operations. The simplest expression is a constant floating point value. Slightly more complex are mathematical expressions that evaluate to a floating point value.

Operators

The arithmetic operators that are understood by expressions are:

+, -, *, /, % (fmod) and ^ (power)

[x,y,z]     vector constructor
V[n]        vector component access
x ? y : z   conditional operator (if x then y else z)
x && y      AND comparison
x || y      OR comparison
x == y      equality test
x != y      inequality test
x > y       comparison
x < y       comparison
x >= y      comparison
x <= y      comparison
!x          logical negation

Any level of parentheses may be used to clarify order of evaluation.

Note

An expression can be followed by the pound sign (for example, “#”) to signal its end. Therefore, you can put comments, or alternate versions of your expression, after the pound sign.

Variables

There are a set of variables describing underlying patch information that can be used in expressions. The vector forms may be used as vectors or individual components can be referenced. For example, $N refers to the surface normal vector, and $N[0] refers to the x component of the normal vector.

Floats

$u, $v - The u and v parameters of the underlying surface.
$cLength - The final, computed length of the current primitive.
$cWidth - The final, computed width of the current primitive.
$cDepth - The final, computed depth of the current primitive without displacement.
$frame - The current frame being evaluated. This value should be used with care as it is not advisable for certain attributes to change across frames (for example, length and density) as this would make motion blur calculations impossible.
$id - The current primitive’s ID (useful for fx modules).

Vectors

$P - The surface point at which the primitive is being evaluated.
$Pg - The surface point without displacement.
$Pref - The reference surface point at which the primitive is being evaluated.
$Prefg - The reference surface point without displacement.
$Pw - The surface point at which the primitive is being evaluated. World space.
$Pgw - The surface point without displacement. World space.
$Prefw - The reference surface point at which the primitive is being evaluated. World space.
$Prefgw - The reference surface point without displacement. World space.
$N - The surface normal at which the primitive is being evaluated.
$Ng - The surface normal without displacement.
$Nref - The reference surface normal at which the primitive is being evaluated.
$Nrefg - The reference surface normal without displacement.
$dPdu - The surface dPdu at which the primitive is being evaluated.
$dPdug - The surface dPdu without displacement.
$dPduref - The reference surface dPdu at which the primitive is being evaluated.
$dPdurefg - The reference surface dPdu without displacement.
$dPdv - The surface dPdv at which the primitive is being evaluated.
$dPdvg - The surface dPdv without displacement.
$dPdvref - The reference surface dPdv at which the primitive is being evaluated.
$dPdvrefg - The reference surface dPdv.

Note

Since the value of the displaced variables, such as P and N, depend on the displacement, offset and bump expressions values, those variables cannot be used within those expressions. If you wish to use point based noise, or any other expression that needs to use values from the underlying surface, you should use the g variety, such as Prefg and Nrefg.

Functions

There is a set of function calls that may be used in expressions. All arguments can be sub-expressions. If an expression expects a vector argument, then the input value is given in upper case. If a scalar is passed to a function expecting a vector, then a vector where all three channels have an equivalent value is used (for example, length(2) == length([2,2,2])).

When a vector is passed to a scalar operation, the operation is performed component wise (for example, cos(X) = [cos(X[0]),cos(X[1]),cos(X[2])]). This includes arithmetic operations (for example, X*Y = [X[0]*Y[0],X[1]*Y[1],X[2]*Y[2]]). Comparison and conditionals use the [0] component only. Equality tests (==,!=) compare all three components. Any scalar result from a function will be the [0] component.

The square brackets in the definitions below indicate optional parameters:

abs(x): Absolute value of x.

acos(x): Arc cosine of x, in the range 0 to pi radians.

acosd(x): Arc cosine of x, in the range 0 to 180 degrees.

acosh(x): Hyperbolic cosine of x.

alignU([X]) alignV([X]) alignN([X]): Align the primitive with a given vector. These three expressions should be placed into offU, offV, and offN. If no parameter is passed, then a default of [0,1,0] is used, with the result being “grow up”. When a parameter is passed, it passes the same parameter to all three expressions. The parameter can be an expression and need not be normalized.

angle(X, Y): Angle between vectors (in radians).

asin(x): Arc sine of x, in the range -pi/2 to pi/2 radians.

asind(x): Arc sine of x, in the range -90 to 90 degrees.

asinh(x): Hyperbolic sine of x, in the range.

atan(x): Arc tangent of x, in the range -pi/2 to pi/2 radians.

atand(x): Arc tangent of x, in the range -90 to 90 degrees.

atan2(x, y): Arc tangent of x/y, in the range -pi/2 to pi/2.

atanh(x): Hyperbolic arc tangent

bias(x, b): Helper for contrast that is a variation of gamma.

boxstep(x, val): Produces 0 when the expression evaluates less than val, and 1 otherwise. Subtracting a boxstep from a boxstep produces a box function where the value is 0 when less than the first boxstep's val, 1 when between the vals, and 0 when greater than the second boxstep's val. Make sure to subtract the later occurring boxstep from the earlier, otherwise an inverted box function results.

cbrt(x): Cube root of x.

ceil(x): Smallest integer not less than x (round up). See floor, round and trunc.

clamp(x, min, max): Clamps x between min and max.

component(x, y, z): Allows expressions to set values of the individual components of a vector or color.

contrast(x, c): Contrast function for x. c < 0.5 decreases contrast, c > 0.5 increases contrast.

cos(x): Cosine of x (x in radians).

cosd(x): Cosine in degrees.

cosh(x): Hyperbolic cosine of x.

cross(V, W): Cross product of vectors

deg(r): Convert radians to degrees. See alse rad.

dot(V, W): Dot product of vectors.

dist(x1, y1, z1, x2, y2, z2): Distance between two points.

exp(x): e raised to the power of x.

fit(x, a1, b1, a2, b2): Linear transfer of [a1..x..b1] into [a2..result..b2].

floor(x): Largest integer not greater than x (round down). See also ceil, round and trunc.

fmod(x, y): Real remainder of x divided by y. Same as x%y.

gamma(x, g): Gamma correction of x. Same as pow( x, 1/g).

gaussstep(x, a, b): Produces a Gaussian transition from 0 to 1. The result is 0 when x equals a and 1 when x equals b. When outside this range, the result is continuous: past a produces all 0's and past b produces all 1's. If a is less than b, then the function is a ramp up, otherwise it is a ramp down.

hypot(x, y): Square root of (x*x + y*y).

length(V): Length of vector.

linearstep(x, a, b): Produces a linear transition from 0 to 1. The result is 0 when x equals a and 1 when x equals b. When outside this range, the result is continuous: past a produces all 0's and past b produces all 1's. If a is less than b, then the function is a ramp up, otherwise it is a ramp down.

log(x): Natural logarithm of x.

log10(x): Base 10 logarithm of x.

map("mapname" [, s, t] [, channel]): Evaluates the mapname at the current (u,v) or the provided (s,t). The mapname can just be a path to the ptex files. You only need to specify the file pattern if you plan on using a regular expression to modify the default $g.ptx that would be used. An optional channel can be specified to indicate which channel of the image should be read. You can use the variable ${DESC} for the description name. You can also use the built-in $PAL macro to reference maps. An example might be map( “baseCoat_${PAL,myPick}” ) where a palette expression named myPick would be evaluated and have its result inserted with %04d formatting.

max(x, y): Returns the larger of the two values. See alse min.

min(x, y): Returns the lesser of the two values. See also max.

noise([x] [, y] [, z]): Evaluates the Perlin noise function. When no parameters are given, it is evaluated at the current (u,v). One, two, or three parameters can be used for noise in one, two, or three dimensions. The return value is always a floating point number between -1 and 1.

norm(V): Normalize vector V.

ortho(X, Y): Orthogonal vector (equiv to norm(cross(X,Y))).

pow(x, y): Raise x to the power of y. Same as x^y.

rad(d): Convert degrees to radians. See also deg.

rand([min, max] [, seed]): Generates a random number. When no parameters are given, the number generated is between 0 and 1. Optionally, two parameters can be passed in to give a range for the random number. In either case, a seed value can be given that ensures that the number returned is random, but predictable (always x when passed y).

remap(x, source, range, falloff, interpolation): Remaps x between 0 and 1 such that the result equals 1 when x is within range distance from the source. Once outside that region, the result falls off to 0 over the falloff distance. The interpolation scheme can be specified by name or an integer key: linear=0, smooth=1, gaussian=2, boxstep=3. When using boxstep interpolation, a falloff value of 0.0 is used.

round(x): Integer value produced by rounding x towards zero when the decimal portion is less than 0.5 and away from zero otherwise. See also floor, ceil and trunc.

shadow(x): Evaluates the passed in expression only during the shadow pass of a render. Useful for changing length, width, density, and so forth between the color and shadow passes of a render. When not in the shadow pass, this function evaluates to 1.0, so it should be used as a multiplier.

sin(x): Sine of x (x in radians).

sind(x): Sine of x in degrees.

sinh(x): Hyperbolic sine of x.

smoothstep(x, a, b): Produces a smooth (quadratic) transition from zero to one. The result is 0 when x equals a and 1 when x equals b. When outside this range, the result is continuous: past a produces all 0's and past b produces all 1's. If a is less than b, then the function is a ramp up, otherwise it is a ramp down.

sqrt(x): Square root of x.

tan(x): Tangent of x (x in radians).

tanh(x): Hyperbolic tangent of x.

trunc(x): Simple dropping of the decimal portion of x (round towards zero). See also ceil, floor, and round.

other(): Palette expressions are called as functions. If you have a palette expression named myPick then you would call it in another expression by the syntax myPick(). Useful for connecting attributes, such as giving an association between length and width. Also useful for driving attributes in separate descriptions, such as setting a palette-wide width value. The name you give your palette expression should not overlap any predefined XGen functions; otherwise, your palette expression will not be accessible.

The following constants are valid:

PI: The ratio of the circumference of a circle to its diameter (3.14159265358979323846).

E: The base of natural logarithms (2.7182818284590452354).

Note

If an expression is invalid, an error message is displayed and it is evaluated as 0.001.

Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License