IDirect3DRMAnimation2

Applications use the methods of the IDirect3DRMAnimation2 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 IDirect3DRMAnimation2::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 IDirect3DRMAnimation2::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 IDirect3DRMAnimation2::SetTime is an arbitrary value, based on the positions of keys the application has already added.

Microsoft DirectX version 6.0 introduced the IDirect3DRMAnimation2 interface. IDirect3DRMAnimation2 extends the older IDirect3DRMAnimation interface that it replaces by adding the AddKey, DeleteKeyByID, GetKeys, and ModifyKey methods that allow access to the keys of an animation. It also adds the GetFrame method that returns the frame of the corresponding animation. For a history of the Direct3D Retained Mode interfaces, see Interface Changes.

The methods of the IDirect3DRMAnimation2 interface can be organized into the following groups:

Keys AddKey

AddPositionKey

AddRotateKey
AddScaleKey
DeleteKey

DeleteKeyByID

GetKeys

ModifyKey

Miscellaneous GetFrame

SetFrame

SetTime
Options GetOptions
SetOptions

The IDirect3DRMAnimation2 interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:

AddRef
QueryInterface
Release

In addition, the IDirect3DRMAnimation2 interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMAnimation object is obtained by calling the IDirect3DRM3::CreateAnimation method.

IDirect3DRMAnimation2::AddKey

IDirect3DRMAnimation2

Adds a new key.

Syntax

HRESULT AddKey
(LPD3DRMANIMATIONKEY lpKey);

Parameters

lpKey

D3DRMANIMATIONKEY structure that defines a new key. The dwID member of the structure is ignored and is filled in with the ID of the new key upon return.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMAnimation2::AddPositionKey

IDirect3DRMAnimation2

Adds a position key to the animation.

Syntax

HRESULT AddPositionKey(
  D3DVALUE rvTime,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

Parameters

rvTime
Time in the animation to store the position key. The time units are arbitrary and zero-based; a key whose rvTime value is 49 occurs exactly in the middle of an animation whose last key has an rvTime value of 99.
rvX, rvY, and rvZ
Position.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The transformation applied by this method is a translation. For information about the matrix mathematics involved in transformations, see 3-D Transformations.

See Also

IDirect3DRMAnimation2::DeleteKey

IDirect3DRMAnimation2::AddRotateKey

IDirect3DRMAnimation2

Adds a rotate key to the animation.

Syntax

HRESULT AddRotateKey(
  D3DVALUE rvTime,
  D3DRMQUATERNION *rqQuat
  );

Parameters

rvTime
Time in the animation to store the rotate key. The time units are arbitrary and zero-based; a key whose rvTime value is 49 occurs exactly in the middle of an animation whose last key has an rvTime value of 99.
rqQuat
Quaternion representing the rotation.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method applies a rotation transformation. For information about the matrix mathematics involved in transformations, see 3-D Transformations.

See Also

IDirect3DRMAnimation2::DeleteKey

IDirect3DRMAnimation2::AddScaleKey

IDirect3DRMAnimation2

Adds a scale key to the animation.

Syntax

HRESULT AddScaleKey(
  D3DVALUE rvTime,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

Parameters

rvTime
Time in the animation to store the scale key. The time units are arbitrary and zero-based; a key whose rvTime value is 49 occurs exactly in the middle of an animation whose last key has an rvTime value of 99.
rvX, rvY, and rvZ
Scale factor.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method applies a scaling transformation. For information about the matrix mathematics involved in transformations, see 3-D Transformations.

See Also

IDirect3DRMAnimation2::DeleteKey

IDirect3DRMAnimation2::DeleteKey

IDirect3DRMAnimation2

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

HRESULT DeleteKey(
  D3DVALUE rvTime
  );

Parameters

rvTime
Time identifying the key that will be removed from the animation.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMAnimation2::DeleteKeyByID

IDirect3DRMAnimation2

Deletes the key corresponding to a particular ID.

Syntax

HRESULT DeleteKeyByID
(DWORD dwID);

Parameters

dwID

ID of the key to delete.

Return Value

Returns one of the following values:

D3DRMERR_NOSUCHKEY

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMAnimation2::GetFrame

IDirect3DRMAnimation2

Retrieves the frame corresponding to the animation.

Syntax

HRESULT GetFrame
(LPDIRECT3DRMFRAME3 *lplpFrame);

Parameters

lplpFrame

Pointer to receive an interface of the current Direct3DRMFrame object that the animation references. This can be NULL.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMAnimation2::GetKeys

IDirect3DRMAnimation2

Retrieves the keys corresponding to a particular time.

Syntax

HRESULT GetKeys
(D3DVALUE dvTimeMin,
D3DVALUE dvTimeMax,
LPDWORD lpdwNumKeys,
LPD3DRMANIMATIONKEY lpKey);

Parameters

dvTimeMin

Minimum time value of keys to be returned.

dvTimeMax

Maximum time value of keys to be returned.

lpdwNumKeys

Pointer to a variable the contains the number of keys to be returned in lpKey. If lpKey is NULL, lpdwNumKeys is filled in with the number of keys at the specified time.

lpKey

Pointer to a D3DRMANIMATIONKEY structure that will be filled in with the key value. If lpKey is NULL, lpdwNumKeys will be filled in with the number of keys at the specified time. If lpKey is non-NULL, it will be filled in with the keys corresponding to the specified time up to a maximum number of keys indicated by lpdwNumKeys.

Return Value

Returns one of the following values:

D3DRMERR_NOSUCHKEY

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMAnimation2::GetOptions

IDirect3DRMAnimation2

Retrieves animation options.

Syntax

D3DRMANIMATIONOPTIONS GetOptions( );

Return Value

Returns the value of the D3DRMANIMATIONOPTIONS type describing the animation options.

See Also

IDirect3DRMAnimation2::SetOptions

IDirect3DRMAnimation2::ModifyKey

IDirect3DRMAnimation2

Modifies the value of a key.

Syntax

HRESULT Modify
(LPD3DRMANIMATIONKEY lpKey);

Parameters

lpKey

D3DRMANIMATIONKEY structure that defines an existing key's value. The dwID member of the structure must be an existing key.

Return Value

Returns one of the following values:

D3DRMERR_INCOMPATIBLEKEY

D3DRMERR_NOSUCHKEY

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.
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.

IDirect3DRMAnimation2::SetFrame

IDirect3DRMAnimation2

Sets the frame for the animation.

Syntax

HRESULT SetFrame(
  LPDIRECT3DRMFRAME3 lpD3DRMFrame
  );

Parameters

lpD3DRMFrame
Address of a variable representing the frame to set for the animation.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMAnimation2::SetOptions

IDirect3DRMAnimation2

Sets the animation options.

Syntax

HRESULT SetOptions(
  D3DRMANIMATIONOPTIONS d3drmanimFlags
  );

Parameters

d3drmanimFlags
Value of the D3DRMANIMATIONOPTIONS type describing the animation options.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMAnimation2::GetOptions

IDirect3DRMAnimation2::SetTime

IDirect3DRMAnimation2

Sets the current time for this animation.

Syntax

HRESULT SetTime(
  D3DVALUE rvTime
  );

Parameters

rvTime
New current time for the animation. The time units are arbitrary and zero-based; a key whose rvTime value is 49 occurs exactly in the middle of an animation whose last key has an rvTime value of 99.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Keys	AddKey
	AddPositionKey
	AddRotateKey
	AddScaleKey
	DeleteKey
	DeleteKeyByID
	GetKeys
	ModifyKey

Miscellaneous	GetFrame
	SetFrame
	SetTime

Options	GetOptions
	SetOptions