|
VEX Language Reference - Version 6.5
Side Effects Software Inc. 2003
|
VEX Compiler Reference
Basic Language Information
The compiler (vcc) compiles VEX code into an "executable" form.
VEX is loosely based on the C language but takes pieces from C++ as
well as the RenderMan(tm) shading language.
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.
- Parameters to a context function must be declared with
default values. This does not apply to user functions.
- Parameters of the same are declared in a comma
separated list without needing to re-declare the type.
- Different type declarations must be separated by a
semi-colon.
Some examples of function declarations are:
void
user_function1(float a, b; vector c) {...}
cop
cop_function(float a=0, b=0; vector c=1) {...}
pop
pop_function(string a="string1", b="string2";
float c = 1, d = 1.3;
vector e={1,2,3}, f={-1,0,.1}) {...}
Language Structure
The structure of VEX is similar to the structure of a C program. A
function is declared and consists of statements which operate on
variables. Expressions are defined using the standard C operators
which have the precedence as follows:
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 |
Statements
The basic control statements in VEX are:
Some contexts have additional statements (i.e. the surface context adds an
illuminance statement to the language). Please see the context
specific information for further details.
Compiler Pre-Processor
The compiler has a pre-processor which is responsible for macro
expansion as well as stripping out comments. Comments can be in
either the C form (/* */) or the C++ form (//). The pre-processor is
also responsible for handling encryption of
source code. The pre-processor supports many of the standard C
Pre-Processor directives:
Symbols can be defined using the -D option of vcc.
The compiler (vcc) has several pre-defined macros which can be
used for compiling.
__vex
This symbol is always defined so that you know the source is
being compiled by vcc.
__vex_major
The major version number of the compiler being used to compile.
__vex_minor
The minor version number of the compiler being used to compile.
__LINE__
The current line of the source code being compiled.
__FILE__
The current file being compiled.
__DATE__
The current date (as a quoted string). Example: "Dec 31 1999"
__TIME__
The current time (as a quoted string). Example: "23:59:59"
Compiler Options
The VEX compiler (vcc) is capable of compiling VEX code, generating
dialog scripts for VEX functions and also giving quick help by listing
the global variables and functions available in any given context.
-?, -H, -h
Show help message for the compiler
-X context_name
Rather than compiling code, this option will display the list
of global variables, VEX constructs and all functions
available for the context specified.
-D name=def, -D name
Define a name for the pre-processor. If no value is given
with the name, the name is defined with a value of 1.
-I path
Add the path specified to the include path for the
pre-processor. By default, the standard Houdini path is
searched for include files (under vex/include).
-o file
By default, the compiler will generate the compiled .vex code
in the current directory. This option allows you to specify
an alternate location and name for the output.
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.
-c
Generate a binary/crypted version of the function. This means
that the generated .vex file will not be readable by a human.
However, it can still be used by Houdini. See also #pragma crypt.
-e file
Send error messages to this file rather than stderr.
-w wlist
The -w will supress the printing of the specified warnings.
The wlist should be a comma separated list of warning numbers
to suppress.
-q, -Q
The -q will cause the compiler to omit printing of messages. The
-Q option will supress both messages and warnings. Errors
will still be printed out with either option.
-i
Make the generated .vex code more readable by indenting the
output based on nesting.
-u, -U
Generate a corresponding dialog script for the VEX function.
This dialog script will be usable by Houdini to let the user
modify parameters interactively (rather than editing a
string). If the -U option is specified, only the dialog
script file will be generated, compilation of the code will be
bypassed.
-g nparms
When generating dialog scripts (with the -u or -U option), it
is possible to "auto-group" parameters in to groups of N
parameters. If no groups are specified using the #pragma group directive, then this option
will force groups to be created with a maximum of
nparms per folder tab.
-v
If you only have compiled VEX code, this option can be used to
extract the parameter information and build a dialog script
for the compiled code. Warning: All
pragma information is lost in the compiled code so it is
much better to generate dialog scripts from the source code
where possible.
Encryption
In some cases, VEX code may contain proprietary algorithms which the
author doesn't wish to become public knowledge. The compiler has a
special set of directives to turn on/off crypting (#pragma
crypt, and #pragma endcrypt). For example:
float
wavenoise(float height, float distance)
{
#pragma crypt
return sin(distance)*height;
#pragma endcrypt
}
When this code is compiled, the output of the compiler will be
encrypted so that the code is reasonably secure. However, since VEX
does not support dynamic linking (i.e. linking of pre-compiled code),
there is a utility vcrypt which will encrypt the specific
portions of the source files. The compiler can still read these
encrypted files, however, the code contained will be secure.
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:
Usage: vcrypt [source [destination]]
If no source and destination files are specified, then input is read
from stdin and output to stdout. If no destination file is specified,
the crypted code is output to stdout.
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.
Data Types
VEX supports a fixed set of data types and does not allow user data
types to be defined. As well, arrays are not currently supported
within VEX. The data types supported by VEX are:
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.
Multiplication is defined between two vectors or
points. The multiplication performs an element by
element multiplication (rather than a dot or cross
product).
The dot operator (.) is defined only for vector and
vector4. The structure names have been arbitrarily
chosen to be:
.x or .r to reference the first data
element.
.y or .g to reference the second data
element.
.z or .b to reference the third data
element.
.w or .a to reference the fouth data
element (for vector4 types only).
Many operators are defined for non-scalar data types (i.e. a
vector multiplied by a matrix will transform the vector by
the matrix).
Constants are declared in a similar fashion to C.
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 |
Please see the Quick Reference guide for
a more complete guide to operators and functions.
Type Casting
There are two separate ways to cast a variable or return type in VEX.
VEX is a polymorphic language, meaning that the same function can have
different signatures to specify different calling syntaxes. For
example, the noise() function can take different arguments to generate
1D, 2D, 3D, or 4D noise (noise(float), noise(float, float),
noise(vector), noise(vector4)). However, unlike similar languages
(i.e. C++), the return code is also considered in constructing the
signature of the function. This is an open ended problem, so in many
cases, it is possible to give the compiler a "hint" as to which
version of the function should be used.
This is done by function casting which simply gives the
compiler a hint as to which version of the function to use. For
example:
float n;
n = noise(noise(P));
As stated above, the noise function can take different sets of
parameters. However, there are also versions of the noise() function
which return different types. In particular, the noise() function can
return either a float or a vector.
When generating code for the above fragment, the compiler has a choice
for the nested noise function. It can choose from:
- float noise(vector)
- vector noise(vector)
Both of these forms of the noise() function are valid, so the compiler
has to guess which version to use. When it makes a guess, it will
print out a warning:
WARNING (2005) Implicit casting failed for noise - guessing
noise@VF - please try to use an explicit cast
To eliminate this warning, we can use an explicit function cast which
takes the form:
n = noise( vector(noise(P)));
This form of cast generates no additional code, it just tells the
compiler which version of the function to use.
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++.
n = noise( (vector) noise(P));
This form will cause the compiler to guess the return code and then
take the returned value and cast it to the type specified. The
compiler has some heuristics to attempt to minimize the cost of
functions, so in the above case, the nested noise() function will
return a float, which is then cast to a vector. This is most likely
not the desired behaviour, and is also more expensive.
However, the second form of casting is occasionally necessary.
Consider the following example:
int a, b;
float c;
c = a / b;
In this case, the compiler will generate the instruction for integer
division. If the floating point result is desired, then, it is
important to cast the integers to floats. This is done using the
second form.
c = (float)a / (float)b;
This, however, will generate additional instructions to perform the
cast of the variables.
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.
VEX Compiler Pragmas
The VEX compiler (vcc) supports pragmas for automatically building UI
dialog scripts. These pragmas are typically ignored unless the -u
option is specified on the vcc command line. The pragma's allow
specification of help, hints for how to represent the parameter,
improving readability etc.
The pragmas supported are:
#pragma callback
#pragma crypt
#pragma help
#pragma info
#pragma name
#pragma label
#pragma parmhelp
#pragma hint
#pragma range
#pragma choice
#pragma disable
#pragma group
#pragma rendermask
#pragma export
#pragma bindhandle
#pragma bindhandlereserved
#pragma bindselector
#pragma bindselectorreserved
#pragma opname
#pragma oplabel
#pragma opshader
#pragma opicon
#pragma opmininputs
#pragma opmaxinputs
#pragma inputlabel
#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.
Because of architectural limitations in Houdini, certain criteria need
to be met for this #pragma to work:
- The dialog script needs to be bound to a Houdini Operator
(i.e. SHOP, POP, SOP, etc.)
- The parameter needs to be either a toggle button, or have a
menu bound to it (see #pragma hint and
#pragma choice).
Example:
#pragma callback initialize_menu "sop/initialize_sop.cmd"
The standard $HOUDINI_PATH/scripts path is searched for the script to
run. If the script is found, then a local variable
$script_parm will be set to the name of the parameter being
changed, and the script will be executed. For example, with the above
specification, the following hscript commands would be run:
set -l script_parm initialize_menu
source -q sop/initialize_sop.cmd
#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.
Example:
#pragma help "This is help for the VEX function."
#pragma help "It gets added automatically to the help text"
#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.
Example:
#pragma info "Created by Bob Loblaws - (c)1999"
Caveats:
At the current time, only SHOPs display the info text.
#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.
Example:
#pragma name "Shiny Marble"
#pragma label parameter_name "text"
This allows the definition of a more descriptive label for a
parameter.
Example:
// The "amp" parameter represents noise amplitude
#pragma label amp "Noise Amplitude"
displacement bumpy(float amp=0) {...}
#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.
Example:
// The "amp" parameter represents noise amplitude
#pragma parmhelp amp "Increase this value to add more noise."
displacement bumpy(float amp=0) {...}
#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.
|
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 |
Furthermore, it is possible to choose a specific type
of object using an opfilter of:
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 |
Or a specific type of SHOP, by using one of:
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 |
|
Example:
#pragma hint __nondiffuse toggle // Define as a toggle button
#pragma hint specularcolor color // This represents a color
#pragma hint rest hidden // Don't show rest parameter in UI
#pragma hint mapname image // This represents an image file
#pragma hint nullobject oppath "obj/null" // Only null objects
#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.
Example:
#pragma range seed 0 10
#pragma range roughness 0.001 1
#pragma choice parameter_name "value" "label"
#pragma choicereplace parameter_name "value" "label"
#pragma choicetoggle parameter_name "value" "label"
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.
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.
Example:
#pragma choice operation "over" "Composite A Over B"
#pragma choice operation "under" "Composite A Under B"
#pragma choice operation "add" "Add A and B"
#pragma choice operation "sub" "Subtract A from B"
cop texture(string operation="over")
{
if (operation == "over") ... // texture coordinates
if (operation == "under") ... // parametric coordinates
if (operation == "add") ... // orthographic
if (operation == "sub") ... // polar
}
This would define a menu for the parameter "operation". The menu
would consist of 4 entries. The values for the string parameter would
be one of "over", "under", "add" or "sub". However, the user would be
presented with more meaningful labels for the operation types.
#pragma choice operation "0" "Use texture coordinates"
#pragma choice operation "1" "Use parametric coordinates"
#pragma choice operation "2" "Orthographic Projection"
#pragma choice operation "3" "Polar Projection"
sop texture(int operation=0)
{
if (operation == 0) ... // texture coordinates
if (operation == 1) ... // parametric coordinates
if (operation == 2) ... // orthographic
if (operation == 3) ... // polar
}
#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).
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:
// Disable parm B when A is 0 or A is 1:
#pragma disable B A 0
#pragma disable B A 1
// Disable parm C when A is 0 and B is 0, or just when A is 1.
#pragma disable C A 0 B 0
#pragma disable C A 1
// Disable parm D when C is "none".
#pragma disable D C "none"
cop2 function(int A = 0;
int B = 0;
string C = "gaussian";
vector D = { 0,0,0 })
{ ... }
#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:
// Group Ka, Kd, Ks, roughness into a folder called BRDF
#pragma group BRDF Ka Kd Ks
#pragma group BRDF roughness
#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.
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:
MI - Output generation for MentalRay compliant
renderers.
RIB - RIB generation for RenderMan compliant
renderers.
VMantra - The version of mantra which uses VEX for
shading.
OGL - OpenGL(tm) rendering. This is a special
renderer which automatically adds itself to most render
masks. There is currently no way to prevent this.
#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:
- 0 or none - the parameter will appear only in
the standard dialog box for the OP.
- 1 or dialog - the parameter will appear in the
operation parameters dialog for the OP.
- 2 or all - the parameter will appear in both
the operation parameters dialog and the operation controls bar
for the OP.
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:
- The name of the channel in the VEX operator that should be
bound to the handle.
- Handle name. This is one of the pre-defined Houdini handles
(i.e. ladder). Please see run omls in Houdini for a full list
of available handles.
- Label. A brief description of the handle.
- Handle index. Many handles (for example xform) have multiple
parameters associated with them. This allows you to choose
which handle parameter gets bound to the VEX parameter.
- Default Settings. An optional handle-specific string that can be
used to set some default behavior for the handle.
Examples:
#pragma bindhandle offset1 xform "Translate" tx "invisible(1)"
#pragma bindhandle offset2 xform "Translate" ty
#pragma bindhandle offset3 xform "Translate" tz
sop translate(vector offset=0) { P += offset; }
#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-OP selectors, the bindselector pragma expects 7
arguments:
- The entity to select. Please run the omsls command
from within Houdini for a complete list of possibilities.
- A label. This is a brief description of the selector.
- A user prompt. This is the description which is presented to
the user when they are required to select geometry.
- A primitive mask. This is a pattern which allows selection
of specific primitive types. The list of possible primitive
types are:
- all - Select all primitive types
- face - Select polygons, NURBs or Bezier curves.
- surface - Select mesh, NURBs or Bezier surfaces
- quadric - Select primitive circles, spheres or tubes.
- poly - Select polygons
- nurbscurve - Select NURBS curves
- bezcurve - Select Bezier curves
- mesh - Select meshes
- nurbs - Select NURBS surfaces
- bezier - Select Bezier surfaces
- circle - Select primitive circles
- sphere - Select primitive spheres
- tube - Select primitive tubes
- meta - Select metaballs
- particle - Select particle systems
The primitive types can be combined in standard Houdini
grouping mechanisms. For example:
- all,^p* - Select all primitive types except
polygons and particles.
- face,surface - Select face and surface
primitives.
- *,^quad*,^meta - Select any primitive but
quadrics or metaballs.
- Dragging. This can be either 0 or 1 to allow the selection
to be modified without forcing the user to hit the right mouse
button to complete the selection. For example, if this
parameter is set to 1, the user would be able to click on a
primitive and start moving the mouse. The selection would be
completed and the mouse movement would be passed to the
operator handles.
- Group menu parameter. This parameter is used to indicate what
geometry type the selection group will have. Typically this
will point to a menu for choosing "Points", "Primitives", or
"Guess from group". Please see the OMbindings file for the
Blast SOP.
- Asterisk selects all. This can be either 0 or 1, and
indicates whether the selector needs to set the selection
string to "*" to indicate that all geometry was selected. If
this parameter is 0, the selector assumes that an empty group
parameter indicates that all geometry was selected.
For per-parameter selectors, the bindselector pragma expects 10
arguments:
- The VEX parameter to bind the selector to.
- The entity to select.
- A label.
- A description.
- A primitive mask.
- Dragging.
- Group menu parameter.
- Asterisk selects all.
- Input Index. When the user selects geometry,
the selector must connect the output from the selected
operator to the input of this operator. This parameter
specifies the index of the input number where the operator
should be connected. This parameter can be -1 if the selector
needs to connect multiple input operators into this operator.
- Input Required. Whether the user is required to select
geometry for this input.
Examples:
#pragma bindselector prims "Switch Geometry" \
"Choose the geometry to switch between" \
all 0 "" 0
#pragma bindhandle input_number 0 ladder Input parm0
sop switcher(int input_number=0) { import("P", P, input_number) }
#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.
Example:
#pragma opname "myshop"
#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.
Example:
#pragma oplabel "My New Shop"
#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.
Example:
#pragma opshader "rman_myshader"
#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.
Example:
#pragma opicon "SHOP_plastic"
#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.
Example:
#pragma opmininputs 1
#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.
Example:
#pragma opmaxinputs 4
#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.
Example:
#pragma inputlabel 1 "Geometry to Modify"
Copyright © 1999-2003 Side Effects Software Inc.
477 Richmond Street West, Toronto, Ontario, Canada M5V 3E7