ハンドル (Direct3D 9)
ハンドルは、ID3DXEffectCompiler または ID3DXEffect を使って、テクニック、パス、アノテーション、またはパラメーターを参照するための効率的な手段を提供します。ハンドルは、Get[Parameter|Annotation|Function|Technique|Pass][ByName|BySemantic|Element] という形式の関数を呼び出すときに動的に生成されます。
プログラムの実行中に同じオブジェクトに対するハンドルを複数回生成した場合は、毎回同じハンドルが返されます。ただし、プログラムを複数回実行する場合は、ハンドルが必ずしも一定でないことに注意する必要があります。また、ID3DXEffect および ID3DXEffectCompiler の異なるインスタンスによって生成されたハンドルも異なるものになることに注意する必要があります。
ヘッダー ファイルを見ると、ハンドル (D3DXHANDLE) は実際は文字列ポインターであることがわかります。
GetParameter[ByName|Element|BySemantic] や GetAnnotation[ByName] などの関数に渡すハンドルには、次の 3 つの形式があります。
- GetParameter[ByName|Element|BySemantic] などの関数によって返されたハンドル
- MyVariableName、MyTechniqueName、MyArray[0] などの文字列
- ハンドル = NULL。これには 4 つのケースがあります。
- これがメソッドの戻り値の場合、メソッドはハンドルを見つけることができませんでした。
- GetParameter[ByName|Element|BySemantic] の最初のパラメーターとして NULL ハンドルが渡されると、その関数は最上位パラメーターを返します。逆に、ハンドルが NULL でない場合、関数は、ハンドルによって識別される構造体のメンバーまたは要素を返します。
- ValidateTechnique の第 1 引数または IsParameterUsed の第 2 引数として NULL ハンドルを渡すと、現在のテクニックの妥当性が検査されます。
- FindNextValidTechnique の第 1 引数として NULL ハンドルを渡すと、有効なテクニックの検索はエフェクト内の最初のテクニックから開始されます。
パフォーマンスのヒント: アプリケーションの開始時に、初期化パスを実行して文字列からハンドルを生成します。それ以降はハンドルだけを使います。生成されたハンドルではなく文字列を渡すと、処理が遅くなります。
例
次に、Get[Parameter|Annotation|Function|Technique|Pass][ByName|BySemantic|Element] 関数を使用してハンドルを生成する例を示します。
// Gets handle of second top-level parameter handle in the effect file
h1 = GetParameter(NULL, 1);
// Gets handle of the third struct member of MyStruct
h2 = GetParameter("MyStruct", 2);
// Gets handle of the third array element handle of MyArray
h3 = GetParameterElement("MyArray", 2);
// Gets handle of first member of h1 (that is, the second top-level param)
h4 = GetParameter(h1, 0);
// Gets handle of MyStruct.Data
h5 = GetParameterByName("MyStruct", "Data");
// or
h6 = GetParameterByName(NULL, "MyStruct.Data");
// Gets handle of MyStruct.Data.SubData
h7 = GetParameterByName("MyStruct.Data", "SubData");
// or
h8 = GetParameterByName(NULL, "MyStruct.Data.SubData");
// Gets handle of fifth annotation of h1 (that is, second top-level param)
h9 = GetAnnotation(h1, 4);
// Gets handle of MyStruct's annotation, called Author
h10 = GetAnnotationByName("MyStruct", "Author");
// or
h11 = GetParameterByName(NULL, "MyStruct@Author");