VEX Arrays

VEX includes an array datatype. This is useful in several places:

• Supporting ramp parameters.

• Reading capture data from surface nodes using the import function.

• General programming, wherever arrays would be useful.

This example shows off some of the crazy things that you can do with arrays:

surface
crazy(
      string maps[] = { "Mandril.rat", "default.pic" };
      export float alength = 0;
      )
{
    vector texclr, av[];

    texclr = texture(maps[s+t > 1], s, t);
    av = array( {1,0,0}, vector(nrandom()), t, texclr, {.5,0,0});

    if (fit(noise(s*8), 0, 1, .3, .7) > t)
        av = array(1, {0,1,0}, 0);

    Cf = spline("linear", s, av);
    alength = arraylength(av);
}

To declare an array variable, the general form is member_type var_name[]:

// my_array is an array of floats
float   my_array[];

// v is a single vector, vector_array is an array of vectors
vector  v, vector_array[];

// str_array is an array of strings
string  str_array[];

You can optionally put a size inside the square brackets, but the VEX compiler currently ignores it.

To declare a function returns an array:

// A function which returns an array of vectors
vector[] rgb_array()
{
...
};    

To specify a literal array, use curly braces, with the array members separated by commas:

vector an_array[] = { {1, 2, 3}, {2, 3, 4}, {4, 5, 6} };

vector[] rgb_array()
{
    return { {1, 0, 0}, {0, 1, 0}, {0, 0, 1} };
}

If you specify scalars where a vector is expected, the compiler assigns the scalar value to all components of the vector:

vector an_array[] = { 1, 2, 3};
// an_array[] == { {1, 1, 1}, {2, 2, 2}, {3, 3, 3} }

The array() function creates an array from its arguments.

int[] my_array = array(1, 2, 3, 4, 5);

You can use array() to generate an array of any type. To force array() to generate vectors (for example):

vector (array (value1, value2, ...) );

Use arrayname[index] to look up a value by its position in the array.

vector bw[] = { 0, 1 };
// bw[] == { {0, 0, 0}, {1, 1, 1} }
Cf = bw[index];

Array bounds are checked at run time. Out-of-bounds indices do not cause an error. VEX clamps the given index to the length of the array. Trying to access a member of an empty array returns 0 or "".

int nums[] = { 0, 1, 2, 3, 4, 5 };
int n = nums[10];  // Returns 5

string strs[] = { };
string s = strs[20];  // Returns ""

You can also assign values using the square brackets notation:

float nums[] = { };
nums[0] = 3.14;

(The getcomp and setcomp functions are equivalents for using the square brackets notation.)

The assignment operator supports assigning values between vector types and arrays of floats:

float x[];
// Cf and P are vectors

x = P   // Assigns the components of P to the corresponding
        // members of the array x

Cf = x  // Assigns the first 3 members of x as the
        // components of the vector Cf

If the array is not long enough to fill the vector/matrix, the last member is repeated as often as necessary.

float x[] = {1, 2} // Not long enough to fill a vector
Cf = x;  // Cf == {1, 2, 2}

You can also assign between matrix types and arrays of vectors/vector4:

vector      v[];
vector4     v4[];
matrix3     m3 = 1;
matrix      m4 = 1;

v = m3;     // Each row of the 3x3 matrix is put into a vector
m3 = v;     // Copy the vectors into the row vectors of the matrix
v4 = m4;    // Extract the rows of the matrix into the vector4 array
m4 = v4;    // Create a matrix using the vector4's in the array as row vectors

In summary:

See foreach.

The following functions let you query and manipulate arrays.

In addition, the following functions work with arrays:

• min

• avg

• spline

• import

• addattribute

• metaimport

The ramp pragma lets you specify a ramp user interface for a set of parameters.

#pragma ramp <ramp_parm> <basis_parm> <keys_parm> <values_parm>

See VCC pragmas for more information.

• Currently VEX does not support multi-dimensional arrays.

• Array values may not be declared as parameter exports. This means that…

  • Arrays cannot be passed between shaders (through simport, etc.).

  • Arrays cannot be written to image planes.

  • Arrays cannot be exported to geometry attributes (SOP/POP contexts).

• There is no interface to array types in plug-in VEX functions.

• Arrays should not be passed as variadic keyword arguments.