Applications use the methods of the Direct3DRMAnimation2 interface to animate the position, orientation, and scaling of visuals, lights, and viewports.
An animation in Retained Mode is defined by a set of keys. A key is a time value associated with a scaling operation, an orientation, or a position. A Direct3DRMAnimation object defines how a transformation is modified according to the time value. The animation can be set to operate on a Direct3DRMFrame object, so it could be used to animate the position, orientation, and scaling of Direct3DRMVisual, Direct3DRMLight, and Direct3DRMViewport objects.
The Direct3DRMAnimation2.AddPositionKey, AddRotateKey, and AddScaleKey methods each specify a time value whose units are arbitrary. If an application adds a position key with a time value of 99, for example, a new position key with a time value of 49 would occur exactly halfway between the (zero-based) beginning of the animation and the first position key.
The animation is driven by calling the Direct3DRMAnimation2.SetTime method. This sets the visual object's transformation to the interpolated position, orientation, and scale of the nearby keys in the animation. As with the methods that add animation keys, the time value for SetTime is an arbitrary value, based on the positions of keys the application has already added.
The methods of the Direct3DRMAnimation2 interface can be organized into the following groups.
Keys | AddKey |
AddPositionKey | |
AddRotateKey | |
AddScaleKey | |
DeleteKey | |
DeleteKeyByID | |
GetKeys | |
GetKeysCount | |
ModifyKey | |
Miscellaneous | GetFrame |
SetFrame | |
SetTime | |
Options | GetOptions |
SetOptions |
The Direct3DRMAnimation2 interface inherits the following methods from the Direct3DRMObject interface:
The Direct3DRMAnimation object is obtained by calling the Direct3DRM3.CreateAnimation method.
Adds a new key.
Syntax
object.AddKey(key As D3DRMANIMATIONKEY)
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
- key
- D3DRMANIMATIONKEY type that defines a new key. The id member of the type is ignored and is filled in with the ID of the new key upon return.
Error Values
If an error occurs, this method returns DDERR_INVALIDOBJECT or DDERR_INVALIDPARAMS.
Adds a position key to the animation.
Syntax
object.AddPositionKey(time As Single, x As Single, y As Single, z As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
- time
- Time in the animation to store the position key. The time units are arbitrary and zero-based; a key whose time value is 49 occurs exactly in the middle of an animation whose last key has an time value of 99.
- x, y, and z
- Coordinates for the position key added to the animation.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
The transformation applied by this method is a translation, translating the point (x, y, z) to a new point (x', y', z'):
.
See Also
Adds a rotate key to the animation.
Syntax
object.AddRotateKey(time As Single, q As D3DRMQUATERNION)
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
- time
- Time in the animation to store the rotate key. The time units are arbitrary and zero-based; a key whose time value is 49 occurs exactly in the middle of an animation whose last key has a time value of 99.
- q
- D3DRMQUATERNION type representing the rotation.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
This method applies a rotation transformation.
See Also
Adds a scale key to the animation.
Syntax
object.AddScaleKey(time As Single, x As Single, y As Single, z As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
- time
- Time in the animation to store the scale key. The time units are arbitrary and zero-based; a key whose time value is 49 occurs exactly in the middle of an animation whose last key has a time value of 99.
- x, y, and z
- Coordinates for the scale key added to the animation.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
This method applies a scaling transformation.
See Also
Removes all the keys with the given time from an animation. For example, if an animation has a scale key with time t and a rotation key with time t then both keys will be deleted.
Syntax
object.DeleteKey(time As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
- time
- Time identifying the key that will be removed from the animation.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Deletes the key corresponding to a particular ID.
Syntax
object.DeleteKeyByID(id As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
- id
- ID of the key to delete.
Error Values
If an error occurs, the method returns one of the following values.
Retrieves the frame corresponding to the animation.
Syntax
object.GetFrame( ) As Direct3DRMFrame3
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
Return Value
Returns the interface of the current Direct3DRMFrame object that the animation references.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Retrieves the keys corresponding to a particular time.
Syntax
object.GetKeys(timeMin As Single, timeMax As Single, keyArray() As D3DRMANIMATIONKEY)
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
- timeMin
- Minimum time value of keys to be returned.
- timeMax
- Maximum time value of keys to be returned.
- keyArray
- Array of D3DRMANIMATIONKEY types that will be filled in with the key value.
Error Values
If an error occurs, the method returns one of the following values.
Retrieves the keys between two particular times.
Syntax
object.GetKeysCount(timeMin As Single, timeMax As Single) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
- timeMin
- Minimum time value of keys to be returned.
- timeMax
- Maximum time value of keys to be returned.
Return Value
Returns the number of keys between timeMin and timeMax.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Retrieves animation options.
Syntax
object.GetOptions( ) As CONST_D3DRMANIMATIONFLAGS
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
Return Value
Returns a value from the CONST_D3DRMANIMATIONFLAGS enumeration describing the animation options.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Modifies the value of a key.
Syntax
object.ModifyKey(key As D3DRMANIMATIONKEY)
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
- key
- D3DRMANIMATIONKEY type that defines an existing key's value. The id member of the structure must be an existing key.
Error Values
If an error occurs, the method returns one of the following values.
Remarks
You cannot modify a key's type. To change a key's type you must delete the original key and then add a new key. You can modify a key's time and position, rotation, and scale values.
Sets the frame for the animation.
Syntax
object.SetFrame(frame As Direct3DRMFrame3)
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
- frame
- Variable representing the Direct3DRMFrame3 object to set for the animation.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Sets the animation options.
Syntax
object.SetOptions(flags As CONST_D3DRMANIMATIONFLAGS)
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
- flags
- One or more values from the CONST_D3DRMANIMATIONFLAGS enumeration describing the animation options.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Sets the current time for this animation.
Syntax
object.SetTime(time As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMAnimation2 object.
- time
- New current time for the animation. The time units are arbitrary and zero-based; a key whose time value is 49 occurs exactly in the middle of an animation whose last key has an time value of 99.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.