Handles

Handles provide an efficient means for referencing the techniques, passes, annotations, and parameters with ID3DXEffectCompiler or ID3DXEffect. They are generated dynamically when you call functions of the form Get[Parameter|Annotation|Function|Technique|Pass][ByName|BySemantic|Element].

While running a program, generating a handle to the same object multiple times will return the same handle back every time. But don't rely on the handle staying constant when you run your program multiple times. Also be aware that handles generated by different instances of ID3DXEffect and ID3DXEffectCompiler will be different.

If you view the header files, you'll notice that handles (D3DXHANDLEs) are technically string pointers. See Constants.

The handles that you pass into functions such as GetParameter[ByName|Element|BySemantic] or GetAnnotation[ByName] can be in three forms as follows:

1. Handles that were returned by functions such as GetParameter[ByName|Element|BySemantic].
2. Strings such as MyVariableName, MyTechniqueName, or MyArray[0].
3. Handle = NULL. There are four cases.
   • If it is a method return value, the method failed to find the handle.
   • If a NULL handle is passed in as the first parameter of GetParameter[ByName|Element|BySemantic], the function returns a top-level parameter. Conversely, if the handle is non-NULL, the function returns a structure member or element identified by the handle.
   • If a NULL handle is passed in as the first argument of ValidateTechnique or the second argument of IsParameterUsed, the current technique is validated.
   • If a NULL handle is passed in as the first argument of FindNextValidTechnique, the search for a valid technique starts at the first technique in the effect.

Performance tip  At the start of your application, perform an initialization pass to generate handles from the strings. From that point on, use only handles. Passing in strings instead of generated handles is slower.

Examples

Here are some examples using the Get[Parameter|Annotation|Function|Technique|Pass][ByName|BySemantic|Element] functions to generate handles.

// 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 = GetParameter(NULL, "MyArray[2]");

// 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");