• User functions must be declared before they are referenced.

• The functions are in-lined automatically by the compiler, so recursion will not work. To write a recursive algorithm, you should use shader calls instead.

• As in RenderMan Shading Language, parameters to user functions are always passed by reference, so modifications in a user function affect the variable the function was called with. You can force a shader parameter to be read-only by prefixing it with the const keyword. To ensure that the user function writes to an output parameter, prefix it with the export keyword.

• There is no limit on the number of user functions.

• You can have more than one return statement in a function.

• You can access global variables directly (unlike RenderMan Shading Language, you do not need to declare them with extern). However, we recommend you avoid accessing global variables, since this limits your function to only work in one context (where those globals exist). Instead, pass the global(s) to the function as parameters.

• Functions can be defined inside of a function (nested functions).

The user interface generated from this program by Houdini will be minimal, basically just the variable name and a generic text field based on the datatype. For example, you might want to specify that frequency should be a slider with a certain range, and that clr should be treated as a color (giving it a color picker UI). You can do this with user interface compiler pragmas.

#pragma opname        noise_surf
#pragma oplabel        "Noisy Surface"

#pragma label    clr            "Color"
#pragma label    frequency    "Frequency"

#pragma hint    clr            color
#pragma range    frequency    0.1 10

surface noise_surf(vector clr = {1,1,1}; float frequency = 1;
           export vector nml = {0,0,0})
{
    Cf = clr * (float(noise(frequency * P)) + 0.5) * diffuse(normalize(N));
    nml = normalize(N)*0.5 + 0.5;
}

You can use the dot operator (.) to reference individual components of a vector, matrix or struct.

For vectors, the component names are fixed.

• .x or .u to reference the first element of vector2.

• .x or .r to reference the first element of vector and vector4.

• .y or .v to reference the second element of vector2.

• .y or .g to reference the second element of vector and vector4.

• .z or .b to reference the third element. of vector and vector4

• .w or .a to reference the fourth element of a vector4.

The choice of the letters u,v/x,y,z/r,g,b is arbitrary; the same letters apply even if the vector doesn’t hold a point or color.

For matrices, you can use a pair of letters:

• .xx to reference the [0][0] element

• .zz to reference the [2][2] element

• .ax to reference the [3][0] element

In addition, the dot operator can be used to “swizzle” components of a vector. For example

• v.zyx is equivalent to set(v.z, v.y, v.x)

• v4.bgab is equivalent to set(v4.b, v4.g, v4.a, v4.b)

The comparison operators (==, !=, <, <=, >, >=) are defined when the left hand of the operator is the same type as the right hand side, for string, float and integer types only. The operations result in integer types.

The string matching operator (~=) is only defined when there is a string on both sides of the operator, and is equivalent to calling the match function with those two values.

The logical (&&, ||, and !) and bitwise (& |, ^, and ~) operators are only defined for integers.

Operators higher in the table have higher precedence.

• When you apply an operation to a float and an int, the result is the type to the left of the operator. That is, float * int = float, while int * float = int.

• If you add, multiply, divide, or subtract a vector with a scalar value (int or float), VEX returns a vector of the same size, with the operation applied component-wise. For example:

  {1.0, 2.0, 3.0} * 2.0 == {2.0, 4.0, 6.0}
  

• If you add, multiply, divide, or subtract vectors of different size, VEX returns a vector of the larger size. The operation is applied component-wise.

  Important: the “missing” component(s) on the smaller vector are filled in as {0.0, 0.0, 0.0, 1.0}

  {1.0, 2.0, 3.0} * {2.0, 3.0, 4.0, 5.0} == {2.0, 6.0, 12.0, 5.0}
  

  This can give surprising results if you're not expecting it, for example:

  // Third element of the vector2 is treated as 0,
  // but fourth element is treated as 1.0
  {1.0, 2.0} + {1.0, 2.0, 3.0, 4.0} == {2.0, 4.0, 3.0, 5.0}
  

  If you're combining different-sized vectors, you might want to break out the components and operate on them “manually” to get the results you want without surprises.

You can define functions inside structs to organize your code and allow a limited form of object-oriented programming.

• Inside a struct function, you can use this to refer to the struct instance.

• Inside a struct function, you can refer to struct fields by name as if they were variables (for example, basis is a shortcut for this.basis).

• You can call struct functions on a struct instance using the -> arrow operator, for example sampler->sample(). Note inside a struct function that you can call other methods on the struct using this->method().

struct randsampler {
    // Fields
    int        seed;

    // Methods
    float sample()
    {
        // Struct functions can refer to fields by name
        return random(seed++);
    }
} 

cvex shader()
{
    randsampler sampler = randsampler(11);
    for (int i = 0; i < 10; i++)
    {
        // Use -> to call methods on struct instances
        printf("%f\n", sampler->sample());
    }
}

This is similar to type casting in C++ or Java: you transform a value of one type into another (for example, an int into a float).

This is sometimes necessary, as when you have the following:

int a, b;
float c;
c = a / b;

In this example, the compiler will do integer division (see type resolution ). If you wanted to do floating point division instead, you need to explicitly cast a and b as floats:

int a, b;
float c;
c = (float)a / (float)b;

This generates additional instructions to perform the casts. This may be an issue in performance-sensitive sections of your code.

VEX dispatches functions based not only on the types of the arguments (like C++ or Java), but also on the return type. To disambiguate calls to functions with the same argument types but different return types, you can cast the function.

For example, the noise function can take different parameter types, but can also return different types: noise can return either a float or vector.

In the code:

float n;
n = noise(noise(P));

…VEX could dispatch to either float noise(vector) or vector noise(vector).

To cast a function call, surround it with typename( ... ), as in:

n = noise( vector( noise(P) ) );

While this looks like a function call, it does nothing but disambiguate the function call inside and has no performance overhead.

Function casting is implied when you assign a function call directly to a variable of a specified type. So the following expressions are equivalent, and the function cast may be omitted for more concise code:

vector n = vector( noise(P) );        // Unnecessary function cast
vector n = noise(P);

Since function casting does not generate any type conversions (it simply chooses a function to call), there is no performance penalty to using it. A good rule of thumb is to use function casting wherever possible and to use variable casting only when an explicit type conversion is required.