#pragma c++rawstring 0|1

VEXは、C++スタイルのRaw文字列に対応しています。c++rawstringプラグマを使用して、Raw文字列サポートを無効または再有効にすることができます。 例:

string a = R"(Hello world\n)";
string b = "Hello world\\n";
#pragma c++rawstrings 0        // C++スタイルのRaw文字列サポートを無効にします。
string b = R"(This will generate an error!)";
#pragma c++rawstrings 1        // C++スタイルのRaw文字列サポートを再有効にします。

#pragma bindhandle channel_name h_name h_label h_index h_settings

デフォルトでの特定のパラメータへのハンドルをバインドします(ユーザはバインドを上書きすることができます)。

#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

各スクリプト化したオペレータタイプには、そのタイプのすべてのオペレータ(ダイアログスクリプトファイルの内容に関係なく)に追加されるパラメータがあります。 ハンドルをこれらのパラメータの1つにバインドするために、bindhandlereservedプラグマを使わなければなりません。 このプラグマは、bindhandleプラグマとまったく同じ引数を受け取ります。 唯一の違いは、チャンネル名の引数は予約パラメータの名前を指定しなければならないことです。

#pragma bindselector [parm_name] sel_type sel_name sel_prompt sel_mask allow_dragging group_type_parm asterisk_sel_all [input_index input_required]

オペレータをHoudiniでインタラクティブに作成する時、ユーザはそのデータで作業するように促されます。これらのプロンプトはセレクターでハンドルされます。 セレクターはOP単位基準またはパラメータ単位基準で定義することができます。

OP単位のセレクターでは、bindselectorプラグマは7個の引数を必要とします。 パラメータ単位のセレクターでは、10個の引数を必要とします。

#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

bindhandlereservedプラグマと同様に、これはセレクターをスクリプト化したオペレータの予約パラメータにバインドします。 このプラグマへの引数は、bindselectorプラグマに渡すものと同じです。唯一の違いは、パラメータ名の引数が予約パラメータを指定しなければならないことです。

#pragma callback name "script"

コールバックのHScriptスクリプトまたはPython関数をnameパラメータにバインドします。 パラメータが変わると、Houdiniはscript文字列を実行します。

Houdiniのアーキテクチャの制限が原因で、パラメータとスクリプトは、特定の条件を満たさなければなりません:

• ダイアログスクリプトはHoudiniのノード(例えば、SHOP、SOPなど)にバインドされている必要があります。

• パラメータは、トグルボタンか、またはそれにバウンドしたメニューを持っていなければなりません(#pragma hintと#pragma choiceを参照)。

コールバックの言語(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

• HScriptコールバックでは、scriptはHScriptのステートメントまたは$HOUDINI_PATH/scriptsパス上のスクリプトの名前のどちらかを指定します。

• Pythonコールバックでは、scriptはPythonのソースコードを指定します。

Houdiniは、変化したパラメータを示すのに利用可能な特定の変数を持つコンテキスト内でscriptを実行します。

• HScriptコールバックでは、Houdiniは、パラメータが変化したノードへのパスを含む$nodeなどの変数を作成します。

• Pythonコールバックでは、Houdiniは、変化したパラメータに関する情報の辞書を含むkwargs変数を作成します。

詳細は、コールバックスクリプトを参照してください。

#pragma disablewhen parm_name conditional_expression

conditional_expressionがtrueの時にparm_nameを無効にします。

#pragma hidewhen parm_name conditional_expression

conditional_expressionがtrueの時にUIからparm_nameを隠します。

conditional_expressionの構文は、パラメータの Disable when と Hide when のオプションと同じです。条件構文の詳細は、条件ルールのヘルプを参照してください。

// 'enable'パラメータのトグルがオフの時、'samples'パラメータを無効にします。
#pragma disablewhen samples { enable == 0 }

// 文字列メニュー'choice'が'off'の時、'choice_dep1'パラメータを隠します。
#pragma hidewhen choice_dep1 { choice == "off" }

#pragma export parm_name (none | dialog | all)

パラメータUIをオペレーションパラメータダイアログに追加し、オプションでオペレータツールバーにも追加します。

このプラグマと組み合わせて#pragma hint hiddenを使うことができます。

#pragma group group_name parameter_name1 parameter_name2 ...

名前を付けたパラメータをUIのタブにグループ化します。

// Ka, Kd, Ks, roughnessをBRDFというフォルダにグループ化します。
#pragma group BRDF Ka Kd Ks
#pragma group BRDF roughness

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

#pragma help "text"

textをダイアログスクリプトのヘルプに追加します。これを使ってエンドユーザ向けに関数とパラメータのドキュメントを作成することができます。

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

#pragma helpと同様に、#pragma infoテキストがダイアログスクリプトのヘルプに追加されます。 しかし、infoテキストはヘルプの最初の別セクションにあります。これを使って著作権、バージョン情報などを指定することができます。

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

現在のところ、SOPのみがinfoテキストを表示します。

#pragma hint parameter_name hint_type

パラメータが表現する値のタイプに関する情報を追加します(例えば、VEXベクトルは空間内のポイント、カラー、方向を表現します)。 ヒントは値の編集用UIに特化するために使われます。

hint_typeには、以下のどれかを指定します:

#pragma hint __nondiffuse toggle // トグルボタンとして定義します
#pragma hint specularcolor color // これはカラーを表現します
#pragma hint rest hidden         // UIにrestパラメータを表示しません
#pragma hint mapname image       // これは画像ファイルを表現します
#pragma hint nullobject oppath "obj/null" // nullオブジェクトのみ

#pragma inputlabel inputnum "label"

VEXオペレータタイプでは、オペレータ入力のラベルを設定します。このラベルは、ユーザがオペレータ入力の1つの上でボタンを押した時に表示されます。 inputnumは入力のインデックスで1から始まります。

#pragma inputlabel 1 "Geometry to Modify"

#pragma label parameter_name "text"

パラメータの説明をしたラベルを指定します。

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

UIに表示するラベルを設定します。このプラグマは廃止されました。その理由は、今ではラベルはオペレータテーブル定義で定義するからです。

#pragma opicon "text"

このプラグマを使って、このオペレータタイプで使用するアイコンを設定します。外部の.iconや.biconファイルのパスまたは標準アイコンのどれかの名前を指定することができます。

vccの-C コマンドラインオプションは、このプラグマを上書きします。

#pragma opmininputs num

VEXオペレータタイプでは、これは、オペレータに接続しなければならない入力の 最小 の数を設定します。 この値は、入力を受け取らないSHOPでは無視されます。 接続されている入力の数がこの数よりも少ない時は、オペレータはエラーを発生します。-t コマンドラインオプションは、このプラグマを上書きします。

#pragma opmaxinputs num

VEXオペレータタイプでは、これは、オペレータに接続可能な入力の 最大 の数を設定します。 この値は、入力を受け取らないSHOPでは無視されます。 -T コマンドラインオプションは、このプラグマを上書きします。

#pragma opmininputs 1
#pragma opmaxinputs 4

#pragma opname "text"

このオペレータタイプの内部オペレータ名を指定します。デフォルトでは、 コンパイラはソースファイルの名前を使用します。vccの-n コマンドラインオプションは、このプラグマを上書きします。

#pragma oplabel "text"

このオペレータタイプを説明した名前を指定します。デフォルトでは、 コンパイラは内部のオペレータ名を使用します。vccの-N コマンドラインオプションは、このプラグマを上書きします。

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

#pragma opscript "text"

このオペレータタイプがMantra以外のレンダラーで使用可能なシェーダなら、このプラグマは、レンダラーが探すシェーダファイルの名前を設定することができます。 このプラグマを使用すれば、オペレータタイプ名はシェーダファイル名に合わせる必要がありません。vccの-S コマンドラインオプションは、このプラグマを上書きします。

#pragma opscript "rman_myshader"

#pragma parmhelp parameter_name "text"

ユーザがparameter_nameの上にカーソルを置いた時に表示されるツールチップを設定します。

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

#pragma parmtag parmName token value

オペレータで定義された各パラメータには、それに関連したトークン/値のタグのセットがあります。 このプラグマは、パラメータにトークン/値のペアを追加します。

以下のトークンが利用可能です:

#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_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} };
) { ... }

シェーダで定義されたパラメータのUIをセットアップするほとんどの他のプラグマとは違って、ランプパラメータはHoudiniで新しいUIエレメントを作成します。

現在では、デフォルト値はHoudiniのランプパラメータでサポートされていないので、指定した初期値はUIに渡されません。

値は渡されませんが、values_parmで指定したキーの数は、ランプの初期のキーの数を設定するために使われます。

詳細は、ランプパラメータを参照してください。

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

パラメータの理想の範囲を定義します。値に!を追加すれば、パラメータの値は、その範囲に制限されます。 UIも、この情報を使ってスライダの範囲を設定します。

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

#pragma rendermask (VMantra | RIB | OGL)

このプラグマはSHOPダイアログの生成だけに役に立ちます。各SHOPには、そのSHOPを使用できるレンダラーを定義したマスクがあります。 これは、RenderManシェーディング言語とVEX(または他のシェーディング言語)で同じシェーダを記述することが可能です。 この場合では、レンダーマスクを指定することで、VMantra以上の内容を含めることができます。

レンダーマスクパラメータは、レンダラーのシーン記述を生成するコードに密接にバインドされています。そのため、レンダラーの名前は完全に限定されています。 SHOPをサポートしているレンダラーは以下の通りです。

#pragma optable vop

このプラグマを使用すれば、生成するオペレータタイプを指示することができます。 現在のところ、サポートされているオプションvopのみです。つまり、VOPオペレータを作成します。

このオプションを使用して生成されたVOP otlsには、非常に特有な構造を持ちます:

• VOPの入力は、非Exportシェーダパラメータから生成されます。

• VOPの出力は、Exportシェーダパラメータから生成されます。

• VOPのパラメータは、SHOPオペレータと同様にUI生成を動作させて、非Exportシェーダパラメータすべてに対して作成されます。

• 外側コードは、import命令を使用して、外部ファイルからシェーダ関数をインポートします。

• 内側コードは、shader call構文を使用して、このシェーダを呼び出します。

シェーダの実装は、生成されたVOP内に実際には保存されないので、VOPを正しく動作させるには、外部の.vflまたは.vexファイルからアクセスしなければなりません。 シェーダ用の.vflまたはコンパイルした.vexファイルをVEX検索パスにアクセス可能な場所に配置すると、この要件を満たします。

#pragma rename oldname newname

シェーダインターフェースで使用されているオペレータパラメータの名前を別の名前に指定します。 この命令は、そのパラメータを参照している他の#pragmasすべての後に実行してください。

#pragma optable vopを使用する時、これは、VOP入力または出力がVEXグローバル変数と同じ名前を使用できるので役に立ちます。 なぜなら、そのような名前の干渉は、VOPでは有効でもVEXでは無効だからです。

choiceプラグマを定義することでパラメータのメニューUIを作成することができます。

以下のどれかによって、パラメータのリストを構築します:

• パラメータに対して複数選択プラグマ(choice, choicescript, choicereplace, choicetoggle)を使用して、メニューアイテムを作成します。

• パラメータに対して1つのchoicescriptプラグマを使用して、メニューアイテムを生成するスクリプト(choicescript、choicereplacescript、choicetogglescript)を作成します。

  このスクリプトはHoudiniがメニューエントリを生成する必要がある時にいつもで実行されます(つまり、生成される値はキャッシュ化されません)。そのため、このスクリプトは可能な限り効率化するべきです。 スクリプトの出力は一連の値/ラベルのペアでなければなりません。このペアはchoiceプラグマの値とラベルのフィールドと同じ意味を持ちます。

簡易的なchoiceプラグマは、ユーザがメニューから値を選択することしかできないUIを作成します。 choicereplaceプラグマは、メニューと、さらにユーザが別の値を手動で入力可能なUIを作成します。 choicetoggleプラグマは、ユーザ入力と、さらにメニューアイテムの選択、追加、削除が可能なメニューを用意します。

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

これは、“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
}

これらは、特定のプラグマのopfilter引数に対して使用可能なパラメータです。