Houdini 学习文档 -VEX-VEX 编译器编译指示

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 pragmas let you specify help, hints for how to represent the parameter, organization, and other information.

VEX编译器(vcc)支持用于自动构建UI对话脚本的pragmas。除非在vcc命令行上指定-u选项，否则通常会忽略这些pragmas。pragmas允许您指定帮助、提示如何表示参数、组织和其他信息。

Pragmas can be specified in one of two ways: As a #pragma preprocessor directive, or as a _Pragma VEX statement. The second form allows for bundling up multiple pragmas in a single macro.

Pragmas可以通过以下两种方式指定:#pragma预处理器指令，或者_Pragma VEX语句。第二种形式允许在一个宏中绑定多个pragmas。

The following preprocessor form: 以下预处理器表格:

#pragma label parm "Parameter Label"

is functionally equivalent to this VEX statement: 在功能上等价于VEX语句:

_Pragma("label parm \"Parameter Label\"");

Note that the pragma arguments are enclosed in quotes, with the original set of quotes escaped.

注意pragma参数被括在引号中，原始的一组引号被转义。

#pragma c++rawstring

#pragma c++rawstring 0|1

VEX supports C++ style raw strings. The c++rawstring pragma can be used to disable or re-enable raw string support. For example:

VEX支持c++风格的原始字符串。c++rawstring pragma可用于禁用或重新启用原始字符串支持。例如:

string a = R"(Hello world\n)";
string b = "Hello world\\n";
#pragma c++rawstrings 0        // Disable C++ style raw string support
string b = R"(This will generate an error!)";
#pragma c++rawstrings 1        // Re-enable C++ style raw string support

#pragma bindhandle 编译指示bindhandle

#pragma bindhandle channel_name h_name h_label h_index h_settings

Binds handles to specific parameters by default (users can override bindings).

默认情况下，将句柄绑定到特定的参数(用户可以覆盖绑定)。

channel_name

The name of the channel in the VEX operator to bind to the handle.

要绑定到句柄的VEX操作符中的通道的名称。

h_name

Handle name. This is one of the pre-defined Houdini handles (for example ladder). You can use the omls HScript command for a full list of available handles.

omls 列出操作符类型的可用句柄。omls [-t obj|sop|pop|cop2] [handle]

处理的名字。这是一个预定义的Houdini handles(例如 ladder)。您可以使用 omls HScript命令获得可用句柄的完整列表。

h_label

A brief description of the handle. handle的简单描述。

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

许多句柄(例如xform)都有多个与之关联的参数。这允许您选择将哪个句柄参数绑定到VEX参数。

h_settings

An optional handle-specific string that can be used to set some default behavior for the handle.

一个可选的特定于句柄的字符串，可用于为句柄设置一些默认行为。

#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

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

每个脚本操作符类型都有许多参数，这些参数被添加到该类型的每个操作符中(无论对话脚本文件的内容如何)。要将句柄绑定到这些参数之一，必须使用bindhandlereserved pragma。这个pragma接受与bindhandle pragma完全相同的参数。唯一的例外是通道名称参数必须指定保留参数的名称。

#pragma bindselector

#pragma bindselector [parm_name] sel_type sel_name sel_prompt sel_mask allow_dragginggroup_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.

当在Houdini中交互式地创建操作符时，可以提示用户输入要处理的数据。这些提示由选择器处理。可以根据每个操作或每个参数定义选择器。

For per-OP selectors, the bindselector pragma expects 7 arguments. For per-parameter selectors, it expects 10 arguments.

对于每个操作选择器，bindselector pragma需要7个参数。对于每个参数选择器，它需要10个参数。

parm_name

The VEX parameter to bind the selector to (for per-parameter selectors).

将选择器绑定到(对于每个参数选择器)的VEX参数。

sel_type

The entity to select. Use the omsls HScript command to print a list of possible values.

要选择的实体。使用omsls HScript命令打印可能的值列表。

sel_name

A brief description of the selector.

sel_prompt

the prompt presented to the user to select geometry.选择器的简要描述。

sel_mask

a pattern which allows selection of specific primitive types. The list of possible primitive types are:

允许选择特定原始类型的模式。可能的基本类型列表如下:

all

     all primitive types 所有的原始类型

face

      Polygons, NURBs or Bezier curves.

surface

      Mesh, NURBs or Bezier surfaces    Mesh，NURBs或Bezier曲线。

quadric

      Primitive circles, spheres or tubes.  原始的圆、球或管。

poly

       Polygons 多边形

nurbscurve

       NURBS curves  NURBS曲线

bezcurve

      Bezier curves Bezier 曲线

mesh

       Meshes

nurbs

     NURBS surfaces  NURBS曲面

bezier

      Bezier surfaces  贝塞尔曲线的表面

circle

       Primitive circles   原始的圈子

sphere

      Primitive spheres  原始的球体

tube

     Primitive tubes  原始的管

meta

      Metaballs

particle

      Particle systems 粒子系统

The primitive types can be combined in standard Houdini grouping mechanisms. For example:

基本类型可以在标准的Houdini分组机制中组合。例如:

• all,^p*: select all primitive types except polygons and particles. 选择除多边形和粒子外的所有基本类型。

• face,surface: select face and surface primitives. 选择face和surface的 primitives。

• *,^quad*,^meta: Select any primitive but quadrics or metaballs. 选择除quadrics或metaballs之外的任何 primitive 。

allow_dragging

If set to 1, the selection can be modified without forcing the user to click  to complete the selection.

如果设置为1，则可以修改选择，而无需强制用户单击鼠标右键完成选择。

This lets the user select and modify in one step (dragging with the mouse finishes selection and passes the mouse movements to the operator handles).

这允许用户在一个步骤中进行选择和修改(用鼠标拖动完成选择并将鼠标移动传递给操作符句柄)。

group_type_parm

The name of a parameter which indicates the geometry type the selection group will have. Typically this value will name a parameter with a menu for choosing "Points", "Primitives", or "Guess from group". See the OMbindings file for the Blast SOP.

参数的名称，该参数指示选择组将具有的几何类型。通常，该值将使用菜单为参数命名，用于选择“Points”、“Primitives”或“Guess from group”。有关Blast SOP，请参阅OMbindings文件。

asterisk_sel_all

If set to 1, the selector needs to set the selection string to "*" to indicate all geometry was selected. If 0, the selector assumes an empty group parameter means all geometry was selected.

如果设置为1，选择器需要将选择字符串设置为“*”，以表示选中的所有几何图形。如果为0，则选择器假设一个空组参数表示选中了所有几何图形。

input_index

For per-parameter selectors. 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. Use -1 if the selector needs to connect multiple input operators into this operator.

per-parameter选择器。当用户选择几何体时，选择器必须将所选操作符的输出连接到该操作符的输入。此参数指定应连接操作符的输入号的索引。如果选择器需要将多个输入操作符连接到此操作符，则使用-1。

input_required

For per-parameter selectors. Set to 1 if the user must select geometry for this input.

per-parameter选择器。如果用户必须为此输入选择几何体，则将其设置为1。

#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

#pragma bindselectorreserved reserved_parm_name sel_type sel_name sel_prompt sel_maskallow_dragging group_type_parm asterisk_sel_all input_index input_required

Similar to the bindhandlereserved pragma, this binds selectors to reserved parameters in your scripted operators. The arguments to this pragma are the same as those passed to the bindselector pragma. The only difference is that the parameter name argument must specify a reserved parameter.

与bindhandlereserved pragma类似，这将选择器绑定到脚本操作符中的保留参数。这个pragma的参数与传递给bindselector pragma的参数相同。唯一的区别是参数名参数必须指定一个保留参数。

#pragma callback

#pragma callback name "script"

Binds a callback HScript script or Python function to the name parameter. When the parameter changes, Houdini executes the script string.

将回调HScript脚本或Python函数绑定到name参数。当参数更改时，Houdini执行脚本字符串。

Because of architectural limitations in Houdini, the parameter and script must meet certain conditions:

由于Houdini的架构限制，参数和脚本必须满足一定的条件:

• The dialog script needs to be bound to a Houdini node (e.g. SHOP, SOP, etc.).对话脚本需要绑定到一个Houdini节点(例如SHOP、SOP等)。

• The parameter must be either a toggle button, or have a menu bound to it (see #pragma hint and #pragma choice).参数必须是一个切换按钮，或者有一个菜单绑定到它(参见#pragma hint和#pragma choice)。

To indicate the language of the callback (hscript or python), use #pragma parmtag. If you don’t use a #pragma parmtag for a callback the default is hscript. However, the recommended method for programming callback scripts is python.

要指示回调的语言(hscript或python)，请使用#pragma parmtag。如果回调不使用#pragma parmtag，默认值是hscript。但是，推荐使用python编写回调脚本。

#pragma callback parm1 "message $script_parm"
#pragma parmtag parm1 script_callback_language hscript

#pragma callback parm2 "import hou; hou.ui.displayMessage(kwargs)"
#pragma parmtag initialize_menu script_callback_language hscript

• For HScript callbacks, script can be an HScript statement or the name of a script on the $HOUDINI_PATH/scripts path.对于HScript回调，脚本可以是HScript语句，也可以是$HOUDINI_PATH/scripts路径上的脚本名称。

• For Python callbacks, script should be Python source code.对于Python回调，脚本应该是Python源代码。

Houdini executes script in a context with certain variables available indicating which parameter changed.

Houdini在一个上下文中执行脚本，其中某些变量可用来指示更改了哪个参数。

• For HScript callbacks, Houdini creates variables such as $node containing the path to the node on which the parameter changed.对于HScript回调，Houdini创建变量，如$node，其中包含参数更改所在节点的路径。

• For Python callbacks, Houdini creates a kwargs variable containing a dictionary of information about the parameter that changed.对于Python回调，Houdini创建一个kwargs变量，其中包含关于所更改参数的信息字典。

See callback scripts for more information. 有关更多信息，请参见回调脚本。 http://www.sidefx.com/docs/houdini/hom/locations.html#parameter_callback_scripts

#pragma disablewhen and #pragma hidewhen

#pragma disablewhen parm_name conditional_expression

Disables parm_name when the conditional_expression evaluates to true. 

当条件表达式的值为true时禁用parm_name。

#pragma hidewhen parm_name conditional_expression

Hides parm_name from the UI when the conditional_expression evaluates to true. 

当条件表达式的值为true时，从UI中隐藏parm_name。

The syntax of the conditional_expression is the same as for the Disable when and Hide when options on parameters. See the help for conditional rules for more information on the conditional syntax.

conditional_expression的语法与Disable when和Hide when参数上的选项相同。有关条件语法的更多信息，请参阅条件规则帮助。http://www.sidefx.com/docs/houdini/ref/windows/optype.html#conditionals

// Disable 'samples' parameter when 'enable' parameter is toggled off
#pragma disablewhen samples { enable == 0 }

// Hide 'choice_dep1' parameter when string menu 'choice' is set to 'off'.
#pragma hidewhen choice_dep1 { choice == "off" }

#pragma export

#pragma export parm_name (none | dialog | all)

Adds the parameter UI to the operation parameters dialog, and optionally also the operator toolbar.

将参数UI添加到“操作参数”对话框中，还可以选择添加“操作符”工具栏。

none or 0

No export. The parameter only appears in the operator’s standard dialog.

不能导出。该参数只出现在操作符的标准对话框中。

dialog or 1

The parameter appears in the operator’s parameter window.

该参数出现在操作符的参数窗口中。

all or 2

The parameter appears in the operator’s parameter window and the operator toolbar.

该参数出现在操作符的参数窗口和操作符工具栏中。

You can use #pragma hint hidden in combination with this pragma.

您可以结合使用 #pragma hint hidden

#pragma group

#pragma group group_name parameter_name1 parameter_name2 ...

Groups the named parameters into a tab in the UI.

将命名参数分组到UI中的选项卡中。

// Group Ka, Kd, Ks, roughness into a folder called BRDF
#pragma group BRDF Ka Kd Ks
#pragma group BRDF roughness

Note

You can put / in your group name to create nested groups. For example, the following creates a Group tab with two sub-tabs.

您可以将/放入组名来创建嵌套组。例如，下面的代码创建了一个包含两个子选项卡的Group选项卡。

#pragma group "Group/Sub Group 1" p1 p2
#pragma group "Group/Sub Group 2" p3 p4

#pragma help and #pragma info

#pragma help "text"

Adds text to the help in the dialog script. You can use this to document functions and parameters for end-users.

将文本添加到对话脚本中的帮助中。您可以使用它为最终用户记录函数和参数。

#pragma help "This is help for the VEX function."
#pragma help "It gets added automatically to the help text"

Like #pragma help, #pragma info text is added to the help in the dialog script. However, the info text is in a separate section at the beginning of the help. You can use this to specify copyrights, version information, etc.

与#pragma help类似，#pragma info文本也被添加到对话脚本中的帮助中。但是，信息文本在帮助开始时是在一个单独的部分中。您可以使用它来指定版权、版本信息等。

#pragma info "Created by Bob Loblaw - (c) 2006"

Currently, only SOPs display info text. 目前，只有SOPs显示信息文本。

#pragma hint

#pragma hint parameter_name hint_type

Adds information about what type of value a parameter represents (for example, a VEX vector may represent a point in space, a color, or a direction). The hint is used to specialize the UI for editing the value.

添加关于参数表示的值类型的信息(例如，VEX向量可以表示空间中的点、颜色或方向)。提示用于专门化用于编辑值的UI。

The hint_type can be one of the following:

hint_type可以是以下内容之一:

none

  No hint. 

toggle

The integer or float represents an on/off switch (where 1 is on and 0 is off).

整数或浮点数表示开/关开关(其中1是开的，0是关的)。

color

The parameter is a color. The UI will provide color sliders.

参数是一种颜色。UI将提供彩色滑块。

direction

The parameter is a direction. The UI will provide a gadget for specifying direction.

参数是一个方向。UI将提供一个用于指定方向的小工具。

vector

The parameter is a 3D vector in space. The UI is the same as the default UI for a parameter with 3 floats, but the channel names will end with x, y, z instead of 1, 2, 3.

参数是空间中的三维向量。UI与具有3个浮点数的参数的默认UI相同，但是通道名称将以x、y、z结尾，而不是1,2,3。

vector

The parameter is a 4D vector in space. The UI is the same as the default UI for a parameter with 4 floats, but the channel names will end with x, y, z, w instead of 1, 2, 3, 4.

参数是空间中的一个四维向量。UI与具有4个浮点数的参数的默认UI相同，但是通道名称将以x、y、z、w结尾，而不是1,2,3,4。

uv

The vector parameter is UV coordinates. The UI is two entry fields instead of three (the third component passed to VEX is always 0), and the channel names will end with u, v instead of 1, 2.

矢量参数是UV坐标。UI是两个输入字段，而不是三个(传递给VEX的第三个组件总是0)，通道名称将以u, v结尾，而不是1,2。

uvw

The vector parameter is UV coordinates. The UI is two entry fields instead of three (the third component passed to VEX is always 0), and the channel names will end with u, v instead of 1, 2.

angle

The parameter is a direction vector. The UI will provide a direction gadget.

参数是方向向量。UI将提供一个方向小工具。

file

The string parameter is a filename. The UI adds a browser button for specifying the file. (See also image and geometry below.)

字符串参数是一个文件名。UI添加了一个用于指定文件的浏览器按钮。(参见下面的image和 geometry。)

image

The string parameter is a filename of an image file. The UI adds a browser button for specifying the file, and the browser only displays image file types.

字符串参数是图像文件的文件名。UI添加了一个用于指定文件的浏览器按钮，浏览器只显示图像文件类型。

geometry

The string parameter is a filename of a geometry file. The UI adds a browser button for specifying the file, and the browser only displays geometry file types.

字符串参数是一个几何文件的文件名。UI添加了一个用于指定文件的浏览器按钮，浏览器只显示几何文件类型。

hidden

Don’t include this parameter in the parameter list. This is useful when you intend a parameter to be overridden by a geometry attribute. This is distinct from invisible, as no underlying scene parameter will be created.

不要在参数列表中包含此参数。当您希望一个参数被几何属性覆盖时，这是非常有用的。这与invisible不同，因为不会创建任何底层场景参数。

invisible

The created parameter will exist in the operator but hidden from the user interface. Unlike hidden, an actual scene parameter will get created, just not shown.

创建的参数将存在于操作符中，但对用户界面隐藏。不像隐藏，一个实际的场景参数将被创建，只是没有显示。

inputinvisible

For VOP operators built using #pragma optable vop, this hint indicates that the VOP input connector should be hidden by default when creating new nodes. The input will still be accessible through the more... connector at the bottom of the VOP. This hint has no effect when building non-VOP operator types or for export parameters.

对于使用#pragma optable VOP构建的VOP操作符，此提示表明，在创建新节点时，VOP输入连接器应该默认隐藏。输入仍然可以通过更多…连接器位于VOP底部。此提示在构建非vop操作符类型或用于导出参数时不起作用。

oplist [opfilter]

The parameter is a list of objects. You can optionally specify opfilter to limit the types of operators allowed in the list. Use #pragma parmtag to resolve any bundles or groups in the list of objects.

参数是对象列表。您可以选择指定opfilter来限制列表中允许的操作符类型。使用#pragma parmtag解析对象列表中的任何bundles或groups。

See the list of possible operator filters below.

请参见下面可能的操作符过滤器列表。

oppath [opfilter]

The parameter is an object path. You can optionally specify opfilter to limit the types of operators that can be chosen.

参数是一个对象路径。您可以选择指定opfilter来限制可以选择的操作符的类型。

See the list of possible operator filters below.

joinnext

Put the parameter after this one on the same row in the GUI. For narrow controls this can save space in the parameter editor.

将这个参数放在GUI的同一行中。对于窄控件，这可以节省参数编辑器中的空间。

Example: #pragma hint myParm joinnext

#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 inputlabel

#pragma inputlabel inputnum "label"

For VEX operator types, sets the label for an operator input. 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, starting at 1.

对于VEX操作符类型，设置操作符输入的标签。当用户在某个操作符输入上按下鼠标中键时，将出现此标签。inputnum是输入的索引，从1开始。

#pragma inputlabel 1 "Geometry to Modify"

#pragma label

#pragma label parameter_name "text"

Specifies a descriptive label for a parameter.

为参数指定描述性标签。

#pragma label amp    "Noise Amplitude"
displacement bumpy(float amp=0) {
...
}

#pragma name "text"

Sets the label that appears in the UI. This pragma is obsolete since the label is now defined in the operator table definition.

设置UI中出现的标签。这个pragma已经过时了，因为标签现在是在操作符表定义中定义的。

#pragma opicon

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

使用此pragma设置要用于此操作符类型的图标。它可以是指向外部.icon或.bicon文件的路径，也可以是一个标准图标的名称。

vcc’s -C command line option overrides this pragma.  vcc 的-C命令行选项覆盖这个pragma。

#pragma opmininputs and #pragma opmaxinputs

#pragma opmininputs num

For VEX operator types, this 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 overrides this pragma.

对于VEX操作符类型，这将设置必须连接到该操作符的最小输入数。对于不接受任何输入的 SHOPs，这个值将被忽略。如果连接的输入节点少于此数目，则操作符将生成一个错误。-t 命令行选项覆盖这个pragma。

#pragma opmaxinputs num

For VEX operator types, this 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 overrides this pragma.

对于VEX操作符类型，这将设置可以连接到该操作符的最大输入数。对于不接受任何输入的SHOPs，这个值将被忽略。-T 命令行选项覆盖这个pragma。

#pragma opmininputs 1T
#pragma opmaxinputs 4

#pragma opname and #pragma oplabel

#pragma opname "text"

Specifies the internal operator name of this operator type. By default the compiler uses the name of the source file. vcc’s -n command line option overrides this pragma.

指定此操作符类型的内部操作符名称。默认情况下，编译器使用源文件的名称。vcc的-n命令行选项覆盖这个pragma。

#pragma oplabel "text"

Specifies a descriptive name for this operator type. By default the compiler uses internal operator name. vcc’s -N command line optionoverrides this pragma.

指定此操作符类型的描述性名称。默认情况下，编译器使用内部操作符名称。vcc的-N命令行optionoverride这个pragma。

#pragma opname "myshop"
#pragma oplabel "My New Shop"

#pragma opscript

#pragma opscript "text"

If this operator type is a shader that can be used from renderers other than mantra, this pragma lets you set the name of the shader file that the renderer should look for. If you use this pragma, the operator type name does not need to match the shader file name. vcc’s -Scommand line option overrides this pragma.

如果这个操作符类型是一个着色器，可以从渲染器而不是 mantra 中使用，这个pragma允许您设置渲染器应该查找的着色器文件的名称。如果使用这个pragma，操作符类型名称不需要匹配着色器文件名。vcc的-Scommand行选项覆盖这个pragma。

#pragma opscript "rman_myshader"

#pragma parmhelp parameter_name "text"

#pragma parmhelp parameter_name "text"

Sets the tooltip that appears when the user hovers over parameter_name.  

设置当用户悬停在parameter_name上时出现的工具提示。

#pragma parmhelp amp "Increase this value to add more noise."
displacement bumpy(float amp=0) {
...
}

#pragma parmtag

#pragma parmtag parmName token value

Each parameter defined in an operator has a set of token/value tags associated with it. This pragma adds a token/value pair to a parameter.

操作符中定义的每个参数都有一组与之关联的令牌/值标记。这个pragma向参数添加了一个令牌/值对。

The following tokens are available:

以下令牌可供选择:

autoscope

A string of ones or zeros (for example "1011") corresponding to each component of the parameter. 1 means the parameter is auto-added to the channel list when the node is selected.

与参数的每个组件对应的一串1或0(例如“1011”)。1表示在选择节点时自动将参数添加到通道列表。

If there aren’t enough characters in the string for the number of components, the last character will be extended for the remaining components. This lets you specify "1" to autoscope all components and "0" to autoscope no components.

如果字符串中没有足够的字符来表示组件的数量，那么最后一个字符将被扩展为其他组件。这允许您将“1”指定为自动检查所有组件，将“0”指定为自动检查没有组件。

If this tag is not defined for a parameter, Houdini guesses if a parameter should be scoped or not.

如果没有为参数定义此标记，Houdini猜测是否应该限定参数的作用域。

editor

For string parameters, this can be used to show a multi-line editor instead of a single-line input field. Specify "1" to enable.

对于字符串参数，这可以用来显示多行编辑器，而不是单行输入字段。指定“1”启用。

editorlines

If the multi-line editor is shown, this can be used to specify how many lines of text are shown. The default value is 10.

如果显示多行编辑器，则可以使用该编辑器指定显示多少行文本。默认值是10。

opfilter

For parameters referring to object paths, this provides a filter for which types of OPs will be presented in the OP chooser. If you set this tag, you should also set the oprelative tag.

对于引用对象路径的参数，这提供了一个过滤器，用于在OP选择器中显示哪些类型的操作。如果设置了这个标记，还应该设置oprelative标记。

This tag is also set by the [#pragma hint oppath|/vex/pragmas] pragma, but using a different format.

这个标记也是由[#pragma hint oppath|/vex/pragmas] pragma设置的，但是使用了不同的格式。

Possible values are:

可能的值是:

!!OBJ!!

Only show objects 只显示 objects

!!OBJ/GEOMETRY!!

Only show geometry objects 只显示  geometry objects

!!OBJ/LIGHT!!

Only show light objects 只显示 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

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

How paths should be resolved. Typically, the value of this token is "." so that paths are resolved relative to the current operator. However, when referencing objects you can set the tag to "/obj". See the example below.

如何解析路径。通常，这个令牌的值是“.”，因此相对于当前操作符解析路径。但是，在引用对象时，可以将标记设置为“/obj”。参见下面的示例。

opexpand

In SHOPs, causes "oplist" parameters to be expanded to the full path names. If a bundle or pattern is chosen, the pattern will be expanded before it’s sent to the renderer. See the example below.

在SHOPs 中，使“oplist”参数扩展为完整的路径名称。如果选择了一个包或模式，模式将在发送到呈现程序之前展开。参见下面的示例。

opfullpath

When used in conjunction with the opexpand tag, causes the path names of the objects to be fully qualified rather than relative to the value of the oprelative tag. See the example below.

当与opexpand标记一起使用时，将使对象的路径名完全限定，而不是相对于oprelative标记的值。参见下面的示例。

rampshowcontrolsdefault

Allows you to automatically hide ramp parameter controls, using a value of 1 or 0.

允许使用值1或0自动隐藏ramp参数控件。

script_callback

The callback script associated with the parameter. See #pragma callback.

与参数关联的回调脚本。详见  #pragma callback.

script_ritype

Used when generating RIB streams and mapping the parameter to an appropriate renderman type specification. The value should be a valid renderman type (for example, "uniform color").

用于生成 RIB 流并将参数映射到适当的renderman类型规范。该值应该是一个有效的renderman类型(例如，“uniform color”)。

script_unquoted

In VOP definitions, indicates the string parameter should be used in an unquoted form. This allows strings from menus to be placed verbatim in the code block (see the trig VOP).

在VOP定义中，指示字符串参数应以非引号形式使用。这允许将菜单中的字符串逐字放在代码块中(参见 trig VOP)。

sop_input

Used internally by SOPs to determine the place to search for groups when building a group menu of points/primitives.

在构建 points/primitives 组菜单时，通过SOPs内部确定组的位置去搜索它 。

#pragma parmtag lightmask opfilter "!!OBJ/LIGHT!!"
#pragma parmtag lightmask oprelative "/obj"
#pragma parmtag lightmask opexpand 1
#pragma parmtag reflectmask opfilter "!!OBJ/GEOMETRY!!"
#pragma parmtag reflectmask opexpand 1
#pragma parmtag reflectmask opfullpath 1

#pragma ramp

Creates a ramp parameter and connects it to shader function arguments. 

创建 ramp parameter 并将其连接到着色器函数参数。

• #pragma ramp_rgb ramp_parm basis_parm keys_parm values_parm

• #pragma ramp_flt ramp_parm basis_parm keys_parm values_parm

#pragma ramp_rgb color color_the_basis_strings color_the_key_positions color_the_key_values

surface
sky(
    string color_the_basis_strings[] = { "linear", "linear" };
    float color_the_key_positions[] = { 0, 1};
    vector color_the_key_values[] = { {0,0,0}, {0,0,1} };
) { ... }

Unlike most other pragmas which set up UI for parameters defined in the shader, the ramp pragma creates a new UI element in Houdini.

与大多数为着色器中定义的参数设置UI的其他pragma不同，ramp pragma在Houdini中创建了一个新的UI元素。

ramp_parm

The name of the ramp parameter in the Houdini UI. It cannot conflict with any parameters defined on the shader (or other ramps of course).

Houdini UI中ramp参数的名称。它不能与着色器(当然也不能与其他 ramps )上定义的任何参数冲突。

 

basis_parm

A parameter containing an array of strings. These strings determine the basis values for each key (i.e. "linear", "constant"). If a constant basis is to be specified, then the basis_parm argument can be given as an empty string (i.e. ""). However, the UI may not necessarily reflect this fact.

包含字符串数组的参数。这些字符串决定了每个键的基值。“线性”、“常数”)。如果要指定一个常量基，那么basis_parm参数可以作为一个空字符串给出(即“”)。然而，UI不一定反映这个事实。

keys_parm

A parameter containing an array of floats. If the spline is uniform (i.e. has no keys), the keys_parm argument may be given as an empty string (i.e. ""). However, the UI may not necessarily reflect this fact.

包含浮点数数组的参数。如果样条是一致的(即没有键)，keys_parm参数可以作为空字符串给出(即“”)。然而，UI不一定反映这个事实。

values_parm

A parameter containing an array of floats or an array of vectors. Unlike the basis or key parameter, this is mandatory.

包含浮点数数组或向量数组的参数。与基或关键参数不同，这是强制性的。

Default values are currently not supported by Houdini ramp parameters, so the initial values given are not passed through to the UI.

Houdini  ramp parameters 目前不支持默认值，所以给定的初始值不会传递给UI。

Although the values aren’t passed, the number of keys given in the values parameter will be used to set the initial number of keys in the ramp.

虽然没有传递值，但是values参数中给定的键数将用于设置ramp中的初始键数。

See ramp parameters for more information. 有关更多信息，请参见http://www.sidefx.com/docs/houdini/network/ramps.html

#pragma range

#pragma range parameter_name[!] min_value max_value[!]

Defines the ideal range for the parameter. If you append ! to a value, the parameter value will be clamped at that range. The UI also uses this information to set the range of the slider.

定义参数的理想范围。如果你附加!对于值，参数值将被夹在该范围内。UI还使用此信息设置滑块的范围。

#pragma range seed    0 10
#pragma range roughness 0.001! 1!
#pragma range gamma     0.001! 10

#pragma rendermask

#pragma rendermask (VMantra | RIB | OGL)

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仅用于生成商店对话框。每个商店都有一个蒙版，定义了哪些渲染器可以使用商店。可以用RenderMan着色语言和VEX(或其他着色语言)编写类似的着色器。在这种情况下，rendermask能被指定包含更多而不只是VMantra。

The rendermask parameter is closely bound to the code which generates scene descriptions for a renderer. Thus, the renderer names are quite specific. The renderers which support SHOPs are…

rendermask参数与为渲染器生成场景描述的代码紧密绑定。因此，呈现器名称非常具体。支持SHOPs的渲染器是…

RIB

RIB generation for RenderMan compliant renderers. 为RenderMan兼容的渲染器生成RIB。

VMantra

The version of mantra which uses VEX for shading. 使用VEX着色的mantra版本。

OGL

OpenGL rendering. This is a special renderer which automatically adds itself to most render masks. There is currently no way to prevent this.

OpenGL渲染。这是一个特殊的渲染器，它自动将自己添加到大多数渲染蒙版中。目前没有办法防止这种情况发生。

#pragma optable

#pragma optable vop

This pragma can be used to indicate which operator type to generate. Currently the only supported option is vop meaning to create a VOP operator.

此pragma可用于指示要生成哪个操作符类型。目前唯一支持的选项是vop，即创建vop操作符。

VOP otls generated using this option have a very specific structure:

VOP使用这个选项生成的otls有一个非常具体的结构:

• The inputs on the VOP are generated from non-export shader parameters

• VOP上的输入是由非导出着色器参数生成的

• The outputs on the VOP are generated from export shader parameters

• VOP上的输出由导出着色器参数生成

• The parameters on the VOP are created for all non-export shader parameters, with UI generation working the same way it does for SHOP operators

• VOP上的参数是为所有非导出着色器参数创建的，UI生成的工作方式与 SHOP 操作符相同

• The outer code imports the shader function from an external file using the import directive

• 外部代码使用import指令从外部文件导入着色器函数

• The inner code calls this shader using the shader call syntax

• 内部代码使用 shader call 语法调用这个着色器

Since the implementation of the shader is not actually stored in the generated VOP, it must be accessible through an external .vfl or .vex file for the VOP to work correctly. Placing the .vfl or compiled .vex file for the shader in a location accessible to the VEX search path will meet this requirement.

由于着色器的实现实际上并不存储在生成的VOP中，因此必须通过外部.vfl或.vex文件访问着色器，才能使VOP正确工作。将着色器的.vfl或编译后的. VEX文件放在VEX搜索路径可访问的位置将满足此要求。

#pragma rename

#pragma rename oldname newname

Specify a different name for the operator parameter than is used in the shader interface. This directive should occur after all other #pragmas referring to that parameter.

为操作符参数指定与着色器接口中使用的名称不同的名称。这个指令应该发生在所有其他引用该参数的#pragmas之后。

When using #pragma optable vop, this can be useful to allow a VOP input or output to use the same name as a VEX global variable, since such a name collision is valid in VOPs but not in VEX.

当使用#pragma optable vop时，这对于允许vop输入或输出使用与VEX全局变量相同的名称非常有用，因为这样的名称冲突在VOPs中有效，但在VEX中无效。

How to create menus for parameters 如何为参数创建菜单

You can define choice pragmas to create a menu UI for a parameter.

您可以定义choice pragmas来为参数创建菜单UI。

You build the list for a parameter by doing one of the following:

您可以通过以下操作之一来构建参数列表:

• Use multiple choice pragmas for a parameter to create menu items (choice, choicescript, choicereplace, choicetoggle).

• 为参数使用多个选择pragmas来创建菜单项(choice、choicescript、choicereplace、choicetoggle)。

• Use one choicescript pragmas for a parameter to create a script that creates the menu items (choicescript,choicereplacescript, choicetogglescript).

 

使用一个choicescript pragmas作为参数来创建创建菜单项的脚本(choicescript、choicereplacescript、choicetogglescript)。

 

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

这个脚本在Houdini需要生成菜单项时运行(即生成的值不会缓存)，所以这个脚本应该尽可能的高效。脚本的输出必须是一系列值/标签对，它们与选择pragma中的值和标签字段具有相同的含义。

The plain choice pragma creates a UI that only allows the user to choose values from the menu. The choicereplace pragma creates UI with a menu but also lets the user enter a different value manually. The choicetoggle pragma allows user input, but also provides a menu where choosing a menu item adds or removes it to/from the input.

普通选择pragma创建了一个只允许用户从菜单中选择值的UI。choicereplace pragma使用菜单创建UI，但也允许用户手动输入不同的值。choicetoggle pragma允许用户输入，但也提供了一个菜单，在这个菜单中，选择一个菜单项可以在输入中添加或删除它。

#pragma choice parameter_name "value" "label"

Adds a menu item for parameter_name. Displays a menu of mutually exclusive choices.

为parameter_name添加菜单项。显示一个互斥选项菜单。

#pragma choicescript parameter_name language "scriptline"

Defines a script that will generate menu items for parameter_name. language can be either python or hscript. Displays a menu of mutually exclusive choices.

定义一个脚本，该脚本将为parameter_name生成菜单项。语言可以是python，也可以是hscript。显示一个互斥选项菜单。

#pragma choicereplace parameter_name "value" "label"

Adds a menu item for parameter_name. Displays a UI where the user can choose an item from the menu or input their own.

为parameter_name添加菜单项。显示用户可以从菜单中选择项或输入自己的项的UI。

#pragma choicereplacescript parameter_name "scriptline"

Defines a line in a script that will generate menu items for parameter_name. Displays a UI where the user can choose an item from the menu or input their own.

定义脚本中的一行，它将为parameter_name生成菜单项。显示用户可以从菜单中选择项或输入自己的项的UI。

#pragma choicetoggle parameter_name "value" "label"

Adds a menu item for parameter_name. Displays a menu of choices that add/remove items to/from the user input.

为parameter_name添加菜单项。显示向用户输入添加/删除项的选项菜单。

#pragma choicetogglescript parameter_name "scriptline"

Defines a line in a script that will generate menu items for parameter_name. Displays a menu of choices that add/remove items to/from the user input.

定义脚本中的一行，它将为parameter_name生成菜单项。显示向用户输入添加/删除项的选项菜单。

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

这将为参数“operation”定义一个菜单。菜单将包含4个条目。字符串参数的值将是“over”、“under”、“add”或“sub”之一。但是，将为用户提供更有意义的操作类型标签。

#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
}

Note

You can use pragmas other than choicereplace and choicetoggle to create menus for integer parameters, but the menu items ignore the labels and simply number the choices starting at 0. The choicereplace and choicetoggle pragmas are only valid for string parameters.

您可以使用pragmas而不是choicereplace和choicetoggle来为整数参数创建菜单，但是菜单项忽略标签，而只是从0开始为选项编号。choicereplace和choicetoggle pragmas只对字符串参数有效。

Operator list filters

These are the parameters you can use for the opfilter argument of certain pragmas.

这些参数可以用于某些pragmas的opfilter参数。

obj

Any object.

sop

Any SOP.

chop

Any CHOP.

cop

Any COP.

vop

Any VOP.

rop

Any ROP.

obj/geo

Any Geometry object.

obj/null

Any Null object.

obj/light

Any light.

obj/camera

Any camera.

obj/fog

Any Fog object.

obj/bone

Any bone.

shop/surface

Any surface SHOP.

shop/displace

Any Displace 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.