Direct3DRMAnimation2

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:

• AddDestroyCallback
• CloneObject
• DeleteDestroyCallback
• GetAppData
• GetClassName
• GetName
• SetAppData
• SetName

The Direct3DRMAnimation object is obtained by calling the Direct3DRM3.CreateAnimation method.

Direct3DRMAnimation2.AddKey

---

Direct3DRMAnimation2

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.

Direct3DRMAnimation2.AddPositionKey

---

Direct3DRMAnimation2

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

Direct3DRMAnimation2.DeleteKey

Direct3DRMAnimation2.AddRotateKey

---

Direct3DRMAnimation2

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

Direct3DRMAnimation2.DeleteKey

Direct3DRMAnimation2.AddScaleKey

---

Direct3DRMAnimation2

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

Direct3DRMAnimation2.DeleteKey

Direct3DRMAnimation2.DeleteKey

---

Direct3DRMAnimation2

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.

Direct3DRMAnimation2.DeleteKeyByID

---

Direct3DRMAnimation2

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.

• D3DRMERR_NOSUCHKEY
• DDERR_INVALIDOBJECT
• DDERR_INVALIDPARAMS

Direct3DRMAnimation2.GetFrame

---

Direct3DRMAnimation2

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.

Direct3DRMAnimation2.GetKeys

---

Direct3DRMAnimation2

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.

• D3DRMERR_NOSUCHKEY
• DDERR_INVALIDOBJECT
• DDERR_INVALIDPARAMS
• DD_OK

Direct3DRMAnimation2.GetKeysCount

---

Direct3DRMAnimation2

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.

Direct3DRMAnimation2.GetOptions

---

Direct3DRMAnimation2

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

Direct3DRMAnimation2.SetOptions

Direct3DRMAnimation2.ModifyKey

---

Direct3DRMAnimation2

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.

• D3DRMERR_INCOMPATIBLEKEY
• D3DRMERR_NOSUCHKEY
• DDERR_INVALIDOBJECT
• DDERR_INVALIDPARAMS

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.

Direct3DRMAnimation2.SetFrame

---

Direct3DRMAnimation2

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.

Direct3DRMAnimation2.SetOptions

---

Direct3DRMAnimation2

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

Direct3DRMAnimation2.GetOptions

Direct3DRMAnimation2.SetTime

---

Direct3DRMAnimation2

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
© 1999 Microsoft and/or its suppliers. All rights reserved. Terms of Use.