Houdini 12 VEX

## Overview

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.

Note

Currently VEX does not support multi-dimensional arrays.

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);
}
```

## Declaring array types

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, ...) );
```

## Accessing and setting array values

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.)

Note

The square-brackets operator also works on vectors. You can use it with matrices as well, but it will only return float values (not vectors).

## Copying between arrays and vectors/matrices

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:

Left side =Right sideNotes
`vector``float[]`E.g. `vector v = {1,2,3}`
`vector4``float[]`E.g. `vector4 v = {1,2,3,4};`
`matrix3``float[]`E.g. `matrix3 m = {1,2,3,4,5,6,7,8,9};`
`matrix3``vector[]`E.g. `matrix3 m = { {1,2,3}, {4,5,6}, {7,8,9}};`
`matrix``float[]`E.g. `matrix m = {1,2,3,4,5,6,7,8,9.., 16};`
`matrix``vector4[]`E.g. `matrix m = { {1,2,3,4}, {5,6,7,8}, ... {13,14,15,16}};`
`float[]``vector`Create an array of 3 floats from the components
`float[]``vector4`Create an array of 4 floats from the components
`float[]``matrix3`Create an array of 9 floats from the matrix3
`vector[]``matrix3`Create an array of 3 vectors from the matrix3
`float[]``matrix4`Create an array of 16 floats
`vector4[]``matrix4`Create an array of 4 `vector4`s.

See foreach.

## Working with arrays

The following functions let you query and manipulate arrays.

 resize Sets the length of the array. If the array is enlarged, intermediate values will be uninitialized (return `0` or `""`). arraylength Returns the length of an array. pop Removes the last item from the array (decreasing the size of the array by 1) and returns it. push Adds an item to the end of an array (increasing the size of the array by 1). getcomp Gets the value of an array component, the same as `array[num]`. setcomp Sets the value of an array component, the same as `array[num] = value`. array Efficiently creates an array from its arguments. serialize Flattens an array of vectors or matrices into an array of floats. unserialize Reverses the effect of serialize: assembles a flat array of floats into an array of vectors or matrices. getneighbours An array-based replacement for the getneighbourcount/getneighbour combo. In POP/SOP contexts, returns an array of the point numbers of the neighbors of a given point.

In addition, the following functions work with arrays:

## VCC pragmas

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>
```

## Limitations

• 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).

• Arrays should not be passed as variadic keyword arguments.