![]() |
VEX Language Reference - Version 7.0Side Effects Software Inc. 2004 |
Unlike C or C++ VEX has different "contexts" for compiling. These contexts define how the function is to be used. For example, one context is the "COP" context. Functions written in this context can only be used to do image compositing. The "POP" context is a different context where functions are used to define the motion or attributes of particle systems. While a COP function processes pixel color information, a POP function deals with particle velocities and positions. Therefore, the information and functions required for each "context" have to be slightly different.
Each VEX context has different global variables as well as a special set of runtime functions suited to the context.
It is also possible to define user functions which return one of the standard VEX types (or void). These functions must be declared before they are referenced. The functions are in-lined automatically by the compiler, meaning that recursion is not possible.
Like with the RenderMan(tm) shading language, parameters to user functions are always passed by reference. This means that modifications in a user function affect the variable the function was called with.
The RenderMan(tm) shading language has certain restrictions on user functions which do not exist in VEX. It is possible to have multiple return points from within user functions. It is also possible to reference global variables from within user functions without requiring "extern" declarations. Although it is possible to reference global variables, this practice is discouraged since this limits the function to be used solely within the context containing the global variables referenced. Since parameters are passed by reference, it is probably better coding practice to pass references for global variables to be modified within a user function.
The compiler expects that each source file contains one (and only one) context function definition. Any number of user functions can be defined.
Parameters to context functions are dealt with in a special way with VEX. It is possible to override a parameter's value using a geometry attribute with the same name as the variable. Aside from this special case, parameters should be considered "const" within the scope of the shader. This means that it is illegal to modify a parameter value. The compiler will generate errors if this occurs.
The RenderMan(tm) style of parameter declaration is used by VEX. This is similar to the ANSI C/C++ style of parameter declarations with some minor differences for context functions.
Operator | Associativity | Function |
( )  . | left to right | Function call or expression grouping, Structure member |
! ~ + - ++ -- (type) | right to left | Logical negation, ones complement, unary plus, unary minus, increment, decrement, explicit type cast |
* / % | left to right | Multiplication, Division, Modulus |
+ - | left to right | Addition, Subtraction |
< > <= >= | left to right | Less than, Greater than, Less or equal, Greater or equal |
== != | left to right | Equal, Not equal |
& | left to right | Bitwise and |
^ | left to right | Bitwise exclusive or |
| | left to right | Bitwise or |
&& | left to right | Logical and |
|| | left to right | Logical or |
? : | left to right | Conditional |
= += -= *= /= %= &= ^= |= | right to left | Assignment (or short-hand assignment) |
, | left to right | Comma |
The compiler (vcc) has several pre-defined macros which can be used for compiling.
It is possible to specify "stdout" as a filename. In this case, output will be generated to the stdout file descriptor rather than a disk file.
If the compiler detects encrypted source in its input stream, then the final output will be encrypted. This guarantees the integrity of the encryption (meaning it's not possible to reverse engineer an encrypted function by compiling it and decoding the assembler output). To generate encrypted object code, use the -c option on vcc.
The usage of the vcrypt program is:
The #pragma crypt does not require a closing #pragma endcrypt. The two directives can be thought of as turning encryption on and off.
It is also possible to generate encrypted compiled code by using the -c option on the vcc command line.
Type Name | Definition | Example |
int | Integer values | 21, -3, 0x31 |
float | Floating point scalar values | 21.3, -3.2, 1.0 |
vector | Three floating point values. These values can be used to represent positions, directions, normals or colors (RGB or HSV) | {0,0,0}, {0.3,0.5,-0.5} |
vector4 | Four floating point values. These values can be used to represent positions in homogeneous coordinates, colors (RGBA) | {0,0,0,1}, {0.3,0.5,-0.5,0.2} |
matrix3 | Nine floating point values representing a 3D rotation matrix or a 2D transformation matrix. | |
matrix | Sixteen floating point values representing a 3D transformation matrix. | |
string | A string of characters. | "hello world", "Mandril.pic" |
The standard C operations are defined (with the standard precedence order). There are several special exceptions to the C standard.
1, 392, -43 | integer constants |
1.0, 3.14, -1e3 | float constants |
{1,2,3}, {0,1,0} | vector constants |
{1,2,3,4}, {0,1,0,1} | vector4 constants |
{ {1,0,0}, {0,1,0}, {0,0,1} } | matrix3 constant |
{ {1,0,0,0}, {0,1,0,0}, {0,0,1,0}, {0,0,0,1} } | matrix constant |
This is done by function casting which simply gives the compiler a hint as to which version of the function to use. For example:
When generating code for the above fragment, the compiler has a choice for the nested noise function. It can choose from:
To eliminate this warning, we can use an explicit function cast which takes the form:
The other form of casting involves additional code generation and therefore is less desirable than the previous function casting. The second form is the form which is used in C and C++.
However, the second form of casting is occasionally necessary. Consider the following example:
The general rule of thumb is to try to perform function type casting as much as you want. There is no run-time cost to this casting and it ensures correct code generation. However, it is also a good rule of thumb to avoid variable casting since this can incur a run-time cost.
The pragmas supported are:
Because of architectural limitations in Houdini, certain criteria need
to be met for this #pragma to work:
Example:
Example:
Example:
Example:
Example:
There are also parmtag's which
allow the evaluation of the parameter to resolve any
bundles or groups specified in the list of objects.
Furthermore, it is possible to choose a specific type
of object using an opfilter of:
Or a specific type of SHOP, by using one of:
Example:
Example:
If the choicereplace pragma is used, the menu is non-exclusive, and
the user can choose to either use the menu or enter a different text
value. The choicetoggle also creates a non-exclusive menu, but unlike
the choicereplace menu selecting an item from a toggle menu will add
it to the string if it is not already present, or remove it from the
string if it is there. If not all menu items are specified with the
same pragma, the menu style specified in the first menu item is used.
This can also be used to define integer values. However, the integer
values ignore the labels and instead number the choices in order from
0 to N (where N is the number of entries in the menu). The
choicereplace and choicetoggle pragmas can only be used for parameters
with string values.
The script variants of the choice pragmas allow a script to be
specified instead of a fixed list of entries. This script is run
whenever Houdini needs to generate the menu entries (i.e. the
generated values are not cached) so this script should be as efficient
as possible. A multi-line script can be created by using a series of
choicescript pragmas with the same parameter name. The output of the
script must be a series of value/label pairs, which have the same
meaning as the value and label fields in the choice pragma.
Example:
Disabling parameters is a good way to let the user know what context a given
parameters is valid in (ie, "Number of Subdivisions" is only valid when
"Subdivide" is on).
Examples:
The rendermask parameter is closely bound to the code which generates
scene descriptions for a renderer. Thus, the renderer names are quite
specific. At the time that this document was written, the different
renderers which support SHOPs are:
For per-OP selectors, the bindselector pragma expects 7
arguments:
Example:
Example:
Example:
Example:
Example:
Example:
Example:
The full set of well known token value pairs is currently defined as:
VEX Compiler Pragmas
#pragma callback name script
If this pragma is a little on the esoteric side. It allows an hscript
command file to be bound to the parameter specified by name. If the
UI dialog script is bound to a Houdini operator (i.e. a SHOP, SOP,
POP, etc.), when the parameter is changed, the script specified will
be executed.
Example:
#pragma crypt
If this pragma is found in the source, the generated VEX bytecode will
be encrypted. This prevents users of the source from reverse
engineering the object code.
#pragma help "text"
The help pragma will add the text argument to the help in the dialog
script. This can be used to give hints to users of the VEX code as to
what parameters mean, what the code is useful for, etc.
#pragma info "text"
Like the help pragma, this information is displayed in the help
for the dialog script. However, the info text shows up in a separate
section of the help at the very beginning of the help display. This
is intended to be used to specify any copyrights, version information,
etc.
#pragma name "text"
This defines the label which appears in the UI. This pragma is
typically not required since the label is now usually defined in the
operator table definition.
#pragma label parameter_name "text"
This allows the definition of a more descriptive label for a
parameter.
#pragma parmhelp parameter_name "parameter help text"
This allows the definition of a help string that appears when the user
hovers the mouse over the specified parameter label.
#pragma hint parameter_name hint_type
This pragma gives more information about what a parameter is meant to
represent. For example, in VEX, a vector may represent a point in
space, a color or a direction. This hint allows precise definition of
what a parameter is intended to be used for. The UI generated for
the parameter will then reflect this hint.
Hint Type
Meaning
none
No hint is available.
toggle
The integer (or float) parameter represents a toggle
button. The UI will generate a toggle button for this
parameter and generate values 0 for off and 1 for on.
color
The parameter represents a color. The UI will generate
color sliders for this parameter.
direction
The parameter represents a direction vector. The UI will
generate a direction gadget for this parameter.
vector
The parameter represents a 3 dimensional vector in space.
The UI for this is the same as the default UI for a
parameter with 3 floats. The difference is that the
channel names for this parameter will end with x, y, z
instead of 1, 2, 3.
vector4
The parameter represents a 4 dimensional vector in space.
The UI for this is the same as the default UI for a
parameter with 4 floats. The difference is that the
channel names for this parameter will end with x, y, z, w
instead of 1, 2, 3, 4.
uv
The parameter represents a pair of uv coordinates. The UI
for this type of parameter will be two entry fields
instead of three. The third value passed to the VEX
function will always be 0. Also, the channel names for
the parameter will end with u, v instead of 1, 2.
uvw
The parameter represents a set of uvw coordinates.
The UI for this is the same as the default UI for a
parameter with 3 floats. The difference is that the
channel names for this parameter will end with u, v, w
instead of 1, 2, 3.
angle
The parameter represents a direction vector. The UI will
generate an angle gadget for this parameter.
file
The parameter represents a disk file. A file
prompter will be available for this parameter.
image
The parameter represents an image on disk. A file
prompter will be available for this parameter. Only
recognized image files will be displayed in the file
prompter.
geometry
The parameter represents an image on disk. A file
prompter will be available for this parameter. Only
recognized geometry files will be displayed in the file
prompter.
hidden
There will be no UI generated for this parameter. This
is quite useful when a parameter is intended to be overridden
by a geometry attribute.
oplist [opfilter]
The parameter represents a list of objects.
Optionally, an opfilter can be specified to limit
the types of operators which can be selected. Please see
oppath or the parmtag
pragma for the list of opfilters.
invisible
The created parameter will exist in the operator but hidden from
the user interface.
oppath [opfilter]
The parameter represents a path to an object.
Optionally, an opfilter can be specified to limit
the types of operators which can be selected. The
current list of strings handled for opfilters are:
obj Any Object sop Any SOP pop Any POP chop Any CHOP cop Any COP vop Any VOP rop Any Output Driver
obj/geo Any Geometry Object obj/null Any Null Object obj/light Any Light Object obj/camera Any Camera Object obj/fog Any Fog Object obj/bone Any Bone Object
shop/surface Any Surface SHOP shop/displace Any Displacement SHOP shop/interior Any Interior SHOP shop/light Any Light SHOP shop/shadow Any Shadow SHOP shop/fog Any Atmosphere SHOP shop/photon Any Photon SHOP shop/image3d Any Image3D SHOP
#pragma range parameter_name min_value max_value
This pragma defines an ideal range for a parameter. The slider
generated for the float value will have the range specified by the
minimum and maximum values specified. This works for both integers
and floating point parameters.
#pragma choice parameter_name "value" "label"
#pragma choicescript parameter_name "scriptline"
#pragma choicereplace parameter_name "value" "label"
#pragma choicereplacescript parameter_name "scriptline"
#pragma choicetoggle parameter_name "value" "label"
#pragma choicetogglescript parameter_name "scriptline"
When a choice pragma is defined for a parameter, the parameter is then
represented as a menu of all the choice pragmas defined for that
parameter. This is an exclusive list and there is no easy way for a
user to set the parameter to something other than a choice in the
list.
#pragma disable ParmToDisableName ControlParmName ControlValue
[ControlParmName2 ControlValue2...]
This pragma allows you to define simple rules for disabling a parameter
based on the values of other parameters in the VEX function. It takes the name
of the parm to potentially be disabled, followed by at least one pair of a
control parm name and a value. If more than 1 pair is in the pragma, all of
the conditions must be met (like an AND function). This pragma may be called
several times on the same parameter - if any of the conditions are met, the
parameter will be disabled (like an OR).
#pragma group group_name parameter_name1 parameter_name2 ...
This pragma allows you to group like parameters into a single folder
in the dialog box. There can be multiple pragmas for each group.
Example:
#pragma rendermask (VMantra | RIB | MI)
This pragma is only useful for SHOP dialog generation. Each SHOP has
a mask defining which renderers can use the SHOP. It is possible to
have a similar shader written in the RenderMan shading language and
also in VEX (or another shading language). In this case, the
rendermask can be specified to include more than just VMantra.
#pragma export parmName (none | dialog | all)
When generating dialog scripts for OPs, it is possible to "export"
parameters to the operation parameters dialog, or the operation controls
bar above the viewport. There are three levels of export for parameters:
See also the hidden hint.
#pragma bindhandle channel_name h_name h_label h_index h_settings
When generating dialog scripts for OPs, it is possible to
bind handles to specific parameters by default. This can, of course,
be overridden by users, but defaults can be specified without
modifying the OPbindings file. The bindhandle pragma expects
five arguments:
Examples:
#pragma bindhandlereserved reserved_channel_name h_name h_label h_index h_settings
Each scripted operator type has a number of parameters that are added
to every operator of that type (regardless of the contents of the
dialog script file). To bind a handle to one of these parameters, you
must use the bindhandlereserved pragma. This pragma takes
exactly the same arguments as the bindhandle pragma. The only
exception is that the channel name argument must specify the name of
a reserved parameter.
#pragma bindselector [parm_name] sel_type sel_name sel_prompt
sel_mask allow_dragging group_type_parm asterisk_sel_all [input_index
input_required]
When an operator is created interactively in Houdini, the user can be
prompted for the data to work on. These prompts are handled by
selectors. Selectors can be defined on a per-OP basis, or a
per-parameter basis.
For per-parameter selectors, the bindselector pragma expects 10
arguments:
Examples:
#pragma bindselectorreserved reserved_parm_name sel_type sel_name
sel_prompt sel_mask allow_dragging group_type_parm asterisk_sel_all
input_index input_required
Similar to the bindhandlereserved pragma, this pragma allows
you to bind selectors to reserved parameters in your scriped
operators. The arguments to this pragma are the same as those passed
to the bindselector pragma used to bind a selector to a
parameter defined in the dialog script. The only difference is that
the parameter name argument must specify a reserved parameter.
#pragma opname "text"
This pragma lets you specify the internal operator name that should be
assigned to this operator type. By default the name of the source file
is used. Using the -n command line option to vcc overrides this
pragma.
#pragma oplabel "text"
This pragma lets you specify the descriptive name that should be
assigned to this operator type. This is the name that appears in the
operator toolbars. By default the operator name is used. Using the -N
command line option to vcc overrides this pragma.
#pragma opshader "text"
If this operator type represents a shader that can be used from
renderers other than mantra, this pragma lets you set the name of the
shader file that these other renderers should look for. By using this
pragma, the operator type name does not need to match the shader file
name. The -S option on the vcc command line overrides this pragma.
#pragma opicon "text"
Use this pragma to set the icon to use for this operator type. It can
be a path to an external .icon or .bicon file, or the name of one of
the standard icons. The -C option on the vcc command line overrides
this pragma.
#pragma opmininputs num
For VEX operator types, this pragma sets the minimum number of inputs
that must be connected to the operator. This value is ignored for
SHOPs, which take no inputs. The operator will generate an error if
fewer than this many nodes are connected as inputs. The -t command
line option to vcc overrides this pragma.
#pragma opmaxinputs num
For VEX operator types, this pragma sets the maximum number of inputs
that can be connected to the operator. This value is ignored for
SHOPs, which take no inputs. The -T command line option to vcc
overrides this pragma.
#pragma inputlabel inputnum "Input Label"
For VEX operator types, this pragma sets the label for one of the
operator inputs. This label appears when the user presses the middle
mouse button on one of the operator inputs. The inputnum is the
index of the input for which you want to set the label. The first
input is specified with inputnum = 1.
#pragma parmtag parmName Token Value
Each parameter defined in an operator has a set of token/value tags
associated with it. This pragma allows a set of tag token/value
pairs to be added to the parameter.
Token
Description
autoscope
This is a string of one's or zero's (i.e. "1011") with one
value for each component of the parameter. If there
aren't enough characters in the string for the number of
components, the last character will be extended for the
remaining components.
With a value of 1, the parameter will be auto-scoped when
the node is selected. With a value of 0, no auto-scoping
will be done. If the tag is absent, Houdini will
attempt to guess at whether the parameter should be
auto-scoped or not.
opfilter
For parameters referring to object paths, this provides a
filter as to which types of OP's will be presented in the OP
chooser. If this tag is specified, the oprelative tag
should also be specified.
NOTE: this tag is also handled by the hint oppath pragma, but in a slightly
different form.
Values are:
!!OBJ!!
Only show objects !!OBJ/GEOMETRY!!
Only show geometry objects !!OBJ/LIGHT!!
Only show light objects !!OBJ/CAMERA!!
Only show camera objects (lights are considered cameras) !!OBJ/BONE!!
Only show bone objects !!OBJ/FORCE!!
Only show force objects !!SOP!!
Only show SOPs !!POP!!
Only show POPs !!CHOP!!
Only show CHOPs !!COP2!!
Only show COPs !!VOP!!
Only show VOPs !!ROP!!
Only show output drivers (ROPs) !!DOP!!
Only show DOPs !!SHOP!!
Only show SHOPs !!SHOP/ATMOSPHERE!!
Only show atmosphere shader SHOPs !!SHOP/BACKGROUND!!
Only show background shader SHOPs !!SHOP/CONTOUR!!
Only show contour shader SHOPs !!SHOP/CONTOUR_CONTRAST!!
Only show contour-contrast shader SHOPs !!SHOP/CONTOUR_STORE!!
Only show contour-store shader SHOPs !!SHOP/DISPLACEMENT!!
Only show displacement shader SHOPs !!SHOP/EMITTER!!
Only show emitter shader SHOPs !!SHOP/GEOMETRY!!
Only show geometry shader SHOPs !!SHOP/IMAGE3D!!
Only show image3d shader SHOPs !!SHOP/LENS!!
Only show lens shader SHOPs !!SHOP/LIGHT!!
Only show light shader SHOPs !!SHOP/LIGHT_SHADOW!!
Only show light-shadow shader SHOPs !!SHOP/OUTPUT!!
Only show output shader SHOPs !!SHOP/PHOTON!!
Only show photon shader SHOPs !!SHOP/PHOTON_VOLUME!!
Only show photon volume shader SHOPs !!SHOP/SURFACE!!
Only show surface shader SHOPs !!SHOP/SURFACE_SHADOW!!
Only show surface-shadow shader SHOPs
oprelative
This token determines how paths should be resolved.
Typically, the value of this token is "." so that paths
are resolved relative to the current operator. However,
in many cases when referencing objects, the value is
"/obj".
opexpand
In SHOPs, this token will cause oplist parameters
to be expanded to the full path names. Thus, if a bundle
or pattern is chosen, the pattern will be expanded before
it's sent to the renderer.
opfullpath
When used in conjunction with the opexpand tag,
this will cause the path names of the objects to be fully
qualified rather than being expanded relative to the value
of the oprelative tag.
script_callback
The value associated with this is the callback script associated
with the parameter.
NOTE: this tag is also handled by the callback pragma.
script_ritype
The value associated with this is used when
generating RIB streams and mapping the parameter to an
appropriate renderman type specification. The value
should be a valid renderman type (i.e. "uniform color").
script_unquoted
This tag is used in VOP definitions to indicate that
the string parameter should be used in an unquoted form.
It's primarily used to allow strings from menus to be
placed verbatim in the code block (see the trig VOP).
sop_input
This is used internally by SOPs to determine the place to
search for groups when building a group menu of
points/primitives.
477 Richmond Street West, Toronto, Ontario, Canada M5V 3E7