IDXEffect Interface
The IDXEffect interface is used to generically control transition settings on all transform objects. These transitions often produce animated images from static images or meshes. There could be other animation properties that the transform needs to produce its output. In this case, you should add these properties to the transform custom interface.
There are two variables that control the development of the effect. The Progress variable is a number from 0.0 to 1.0 that controls the percentage of the transition to be completed. Animation effects are often produced by looping over increasing values for Progress, producing transform output at each step.
The Duration variable is a suggested time (in seconds) that such a stepwise transition should take. In general, it only provides storage of the time value, and has no control over the transform output. It is up to the transform user to see that the transition over Progress values happens in the suggested time.
This interface inherits from the IDispatch interface.
IDXEffect Methods
get_Capabilities Retrieves a value indicating the specific capabilities of a transition. get_Duration Retrieves the recommended length of time for performing a transition. get_Progress Retrieves the current setting of the transform's progress. get_StepResolution Retrieves the step size corresponding to the smallest meaningful change for Progress. put_Duration Sets the suggested duration for the transition. put_Progress Sets the requested progress made on the transform.
IDXEffect::get_Capabilities
Retrieves a value indicating specific capabilities of a transition.
Syntax
HRESULT get_Capabilities(
long *pVal
);
Parameters
- pVal
- [out] Pointer to a value indicating the type (or types) of image transform.
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
If the return value has no flags set, the transform type is unknown.
If DXTET_PERIODIC is set, the transform produces the same result at Progress = 0 and at Progress = 1.
If DXTET_MORPH is set, and when the transform is set up with two inputs, the result at Progress = 0 will be equal to the first input, and the result at Progress = 1 will equal the second. This flag will be set for all image 1 to image 2 transitions. For transforms that take two DXSurface inputs and produce a three-dimensional (3-D) mesh, getting this flag indicates the transform will produce a mesh with a texture containing the image of input one at Progress = 0. When Progress = 1, the transform must produce a mesh with a texture containing the image of input two.
Note that if both PERIODIC and MORPH are specified, the transform will be periodic if set up with only one input, and the transform will act as a morph if set up with two inputs.
See Also
IDXEffect::get_Duration
Retrieves the recommended length of time for performing a transition.
Syntax
HRESULT get_Duration(
float *pVal
);
Parameters
- pVal
- [out] Pointer to a value indicating the amount of time (in seconds) the transition should take.
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
This method retrieves the most recently suggested value for the transform duration. This value is only a suggestion, and for some transforms is completely ignored.
See Also
IDXEffect::get_Progress
Retrieves the current setting of the transform's progress.
Syntax
HRESULT get_Progress(
float *pVal
);
Parameters
- pVal
- [out] Pointer to a value indicating the current progress setting of the transform.
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
The return value will be a float value from zero to one, with one signifying completion.
See Also
IDXEffect::get_StepResolution
Retrieves the step size corresponding to the smallest meaningful change for Progress.
Syntax
HRESULT get_StepResolution(
float *pVal
);
Parameters
- pVal
- [out] Value indicating the smallest meaningful step size for the transform's transition.
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
Some transforms may not have a natural step resolution, or may be unable to compute their resolution. In these cases, the transform will return a value of zero.
The value returned by this method can be used to determine the maximum number of times a transform must Execute for a complete transition. For example, if the transform is alpha fading from 0 to 255 (clear to fully opaque), the step resolution will be 0.00392, or 1/255.
Executing the transform in smaller steps than pVal will not affect the outcome of the transform. You can use this to skip unnecessary executions of transforms.
IDXEffect::put_Duration
Sets the suggested duration for the transition.
Syntax
HRESULT put_Duration(
float newVal
);
Parameters
- newVal
- [in] Amount of time in seconds the effect should take.
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
This method enables you to suggest a reasonable default duration for transforms to use. This value is only a suggestion, and in some cases is completely ignored.
You can use this method while authoring content to force the transform to store the duration. When a transform is persisted, it saves the current value of the duration. Later, when it is restored from the persisted information, get_Duration will return the duration that was set earlier.
See Also
IDXEffect::put_Progress
Sets the requested progress made on the transform.
Syntax
HRESULT put_Progress(
float newVal
);
Parameters
- newVal
- [in] Value from zero to one that indicates how much of the transition should be completed.
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
Effects use this value to determine what output to generate. For example, an image 1 to image 2 fade transform would produce an output of image 1 at Progress = 0 and an output of image 2 at Progress = 1. For Progress = 0.5, the resulting image is a blend of 50 percent image 1 and 50 percent image 2.
A user doesn't need to modify Progress in a linear fashion, as it is possible to go through a random sequence of values for this parameter. If not initialized by this method, the value of Progress is undefined and could produce unexpected output.
See Also
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.