IDirect3DRMFrame

Applications use the methods of the IDirect3DRMFrame interface to interact with frames—an object's frame of reference. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMFrame, IDirect3DRMFrame2, and IDirect3DRMFrameArray Interfaces.

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

Background	GetSceneBackground
	GetSceneBackgroundDepth
	SetSceneBackground
	SetSceneBackgroundDepth
	SetSceneBackgroundImage
	SetSceneBackgroundRGB
Color	GetColor
	SetColor
	SetColorRGB
Fog	GetSceneFogColor
	GetSceneFogEnable
	GetSceneFogMode
	GetSceneFogParams
	SetSceneFogColor
	SetSceneFogEnable
	SetSceneFogMode
	SetSceneFogParams
Hierarchies	AddChild
	DeleteChild
	GetChildren
	GetParent
	GetScene
Lighting	AddLight
	DeleteLight
	GetLights
Loading	Load
Material modes	GetMaterialMode
	SetMaterialMode
Positioning and	AddMoveCallback
movement	AddRotation
	AddScale
	AddTranslation
	DeleteMoveCallback
	GetOrientation
	GetPosition
	GetRotation
	GetVelocity
	LookAt
	Move
	SetOrientation
	SetPosition
	SetRotation
	SetVelocity
Sorting	GetSortMode
	GetZbufferMode
	SetSortMode
	SetZbufferMode
Textures	GetTexture
	GetTextureTopology
	SetTexture
	SetTextureTopology
Transformations	AddTransform
	GetTransform
	InverseTransform
	Transform
Visual objects	AddVisual
	DeleteVisual
	GetVisuals

The IDirect3DRMFrame 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 IDirect3DRMFrame interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback

Clone

DeleteDestroyCallback

GetAppData

GetClassName

GetName

SetAppData

SetName

The Direct3DRMFrame object is obtained by using the IDirect3DRM::CreateFrame method.

---

IDirect3DRMFrame::AddChild

IDirect3DRMFrame

Adds a child frame to a frame hierarchy.

HRESULT AddChild(
  LPDIRECT3DRMFRAME lpD3DRMFrameChild
  );

Parameters

lpD3DRMFrameChild

Address of the Direct3DRMFrame object that will be added as a child.

Return Values

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

Remarks

If the frame being added as a child already has a parent, this method removes it from its previous parent before adding it to the new parent.

To preserve an object's transformation, use the IDirect3DRMFrame::GetTransform method to retrieve the object's transformation before using the AddChild method. Then reapply the transformation after the frame is added.

See Also

Hierarchies

---

IDirect3DRMFrame::AddLight

IDirect3DRMFrame

Adds a light to a frame.

HRESULT AddLight(
  LPDIRECT3DRMLIGHT lpD3DRMLight
  );

Parameters

lpD3DRMLight

Address of a variable that represents the Direct3DRMLight object to be added to the frame.

Return Values

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

---

IDirect3DRMFrame::AddMoveCallback

IDirect3DRMFrame

Adds a callback function for special movement processing. The callback is called when the frame is moved or updated.

HRESULT AddMoveCallback(
  D3DRMFRAMEMOVECALLBACK d3drmFMC,
  VOID * lpArg
  );

Parameters

d3drmFMC

Application-defined D3DRMFRAMEMOVECALLBACK callback function.

lpArg

Application-defined data to be passed to the callback function.

Return Values

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

See Also

IDirect3DRMFrame::Move, IDirect3DRMFrame::DeleteMoveCallback

---

IDirect3DRMFrame::AddRotation

IDirect3DRMFrame

Adds a rotation about (rvX, rvY, rvZ) by the number of radians specified in rvTheta.

HRESULT AddRotation(
  D3DRMCOMBINETYPE rctCombine,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ,
  D3DVALUE rvTheta
  );

Parameters

rctCombine

A member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new rotation with any current frame transformation.

rvX, rvY, and rvZ

Axis about which to rotate.

rvTheta

Angle of rotation, in radians.

Return Values

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

Remarks

The specified rotation changes the matrix only for the frame identified by this IDirect3DRMFrame interface. This method changes the objects in the frame only once, unlike IDirect3DRMFrame::SetRotation, which changes the matrix with every render tick.

See Also

3-D Transformations, IDirect3DRMFrame::SetRotation

---

IDirect3DRMFrame::AddScale

IDirect3DRMFrame

Scales a frame's local transformation by (rvX, rvY, rvZ).

HRESULT AddScale(
  D3DRMCOMBINETYPE rctCombine,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

Parameters

rctCombine

Member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new scale with any current frame transformation.

rvX, rvY, and rvZ

Defines the scale factors in the x, y, and z directions.

Return Values

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

Remarks

The specified transformation changes the matrix only for the frame identified by this IDirect3DRMFrame interface.

See Also

3-D Transformations

---

IDirect3DRMFrame::AddTransform

IDirect3DRMFrame

Transforms the local coordinates of the frame by the affine transformation specified by rctCombine and rmMatrix.

HRESULT AddTransform(
  D3DRMCOMBINETYPE rctCombine,
  D3DRMMATRIX4D rmMatrix
  );

Parameters

rctCombine

Member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new transformation with any current transformation.

rmMatrix

Member of the D3DRMMATRIX4D array that defines the transformation matrix to be combined.

Return Values

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

Remarks

Although a 4×4 matrix is given, the last column must be the transpose of [0 0 0 1] for the transformation to be affine.

The specified transformation only changes the matrix for the frame identified by this IDirect3DRMFrame interface.

See Also

3-D Transformations

---

IDirect3DRMFrame::AddTranslation

IDirect3DRMFrame

Adds a translation by (rvX, rvY, rvZ) to a frame's local coordinate system.

HRESULT AddTranslation(
  D3DRMCOMBINETYPE rctCombine,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

Parameters

rctCombine

Member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new translation with any current translation.

rvX, rvY, and rvZ

Defines the position changes in the x, y, and z directions.

Return Values

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

Remarks

The specified translation changes the matrix only for the frame identified by this IDirect3DRMFrame interface.

See Also

3-D Transformations

---

IDirect3DRMFrame::AddVisual

IDirect3DRMFrame

Adds a visual object to a frame.

HRESULT AddVisual(
  LPDIRECT3DRMVISUAL lpD3DRMVisual
  );

Parameters

lpD3DRMVisual

Address of a variable that represents the Direct3DRMVisual object to be added to the frame.

Return Values

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

Remarks

Visual objects include meshes and textures. When a visual object is added to a frame, it becomes visible if the frame is in view. The frame references the visual object.

---

IDirect3DRMFrame::DeleteChild

IDirect3DRMFrame

Removes a frame from the hierarchy. If the frame is not referenced, it is destroyed along with any child frames, lights, and meshes.

HRESULT DeleteChild(
  LPDIRECT3DRMFRAME lpChild
  );

Parameters

lpChild

Address of the Direct3DRMFrame object to be used as the child.

Return Values

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

See Also

Hierarchies

---

IDirect3DRMFrame::DeleteLight

IDirect3DRMFrame

Removes a light from a frame, destroying the light if it is no longer referenced. When a light is removed from a frame, it no longer affects meshes in the scene its frame was in.

HRESULT DeleteLight(
  LPDIRECT3DRMLIGHT lpD3DRMLight
  );

Parameters

lpD3DRMLight

Address of a variable that represents the Direct3DRMLight object to be removed.

Return Values

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

---

IDirect3DRMFrame::DeleteMoveCallback

IDirect3DRMFrame

Removes a frame-move callback function previously added with AddMoveCallback.

HRESULT DeleteMoveCallback(
  D3DRMFRAMEMOVECALLBACK d3drmFMC,
  VOID * lpArg
  );

Parameters

d3drmFMC

Application-defined D3DRMFRAMEMOVECALLBACK callback function.

lpArg

Application-defined data that was passed to the callback function.

Return Values

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

See Also

IDirect3DRMFrame::AddMoveCallback, IDirect3DRMFrame::Move

---

IDirect3DRMFrame::DeleteVisual

IDirect3DRMFrame

Removes a visual object from a frame, destroying it if it is no longer referenced.

HRESULT DeleteVisual(
  LPDIRECT3DRMVISUAL lpD3DRMVisual
  );

Parameters

lpD3DRMVisual

Address of a variable that represents the Direct3DRMVisual object to be removed.

Return Values

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

---

IDirect3DRMFrame::GetChildren

IDirect3DRMFrame

Retrieves a list of child frames in the form of a Direct3DRMFrameArray object.

HRESULT GetChildren(
  LPDIRECT3DRMFRAMEARRAY* lplpChildren
  );

Parameters

lplpChildren

Address of a pointer to be initialized with a valid Direct3DRMFrameArray pointer if the call succeeds.

Return Values

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

See Also

Direct3DRMFrameArray, Hierarchies

---

IDirect3DRMFrame::GetColor

IDirect3DRMFrame

Retrieves the color of the frame.

D3DCOLOR GetColor( );

Return Values

Returns the color of the Direct3DRMFrame object.

See Also

IDirect3DRMFrame::SetColor

---

IDirect3DRMFrame::GetLights

IDirect3DRMFrame

Retrieves a list of lights in the frame in the form of a Direct3DRMLightArray object.

HRESULT GetLights(
  LPDIRECT3DRMLIGHTARRAY* lplpLights
  );

Parameters

lplpLights

Address of a pointer to be initialized with a valid Direct3DRMLightArray pointer if the call succeeds.

Return Values

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

See Also

IDirect3DRMLightArray

---

IDirect3DRMFrame::GetMaterialMode

IDirect3DRMFrame

Retrieves the material mode of the frame.

D3DRMMATERIALMODE GetMaterialMode( );

Return Values

Returns a member of the D3DRMMATERIALMODE enumerated type that specifies the current material mode.

See Also

IDirect3DRMFrame::SetMaterialMode

---

IDirect3DRMFrame::GetOrientation

IDirect3DRMFrame

Retrieves the orientation of a frame relative to the given reference frame.

HRESULT GetOrientation(
  LPDIRECT3DRMFRAME lpRef,
  LPD3DVECTOR lprvDir,
  LPD3DVECTOR lprvUp
  );

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

lprvDir and lprvUp

Addresses of D3DVECTOR structures that will be filled with the directions of the frame's z-axis and y-axis, respectively.

Return Values

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

See Also

IDirect3DRMFrame::SetOrientation

---

IDirect3DRMFrame::GetParent

IDirect3DRMFrame

Retrieves the parent frame of the current frame.

HRESULT GetParent(
  LPDIRECT3DRMFRAME* lplpParent
  );

Parameters

lplpParent

Address of a pointer that will be filled with the pointer to the Direct3DRMFrame object representing the frame's parent. If the current frame is the root, this pointer will be NULL when the method returns.

Return Values

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

---

IDirect3DRMFrame::GetPosition

IDirect3DRMFrame

Retrieves the position of a frame relative to the given reference frame, that is, it retrieves the distance of the frame from the reference. The distance is stored in the lprvPos parameter as a vector rather than as a linear measure.

HRESULT GetPosition(
  LPDIRECT3DRMFRAME lpRef,
  LPD3DVECTOR lprvPos
  );

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

lprvPos

Address of a D3DVECTOR structure that will be filled with the frame's position.

Return Values

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

See Also

IDirect3DRMFrame::SetPosition

---

IDirect3DRMFrame::GetRotation

IDirect3DRMFrame

Retrieves the rotation of the frame relative to the given reference frame.

HRESULT GetRotation(
  LPDIRECT3DRMFRAME lpRef,
  LPD3DVECTOR lprvAxis,
  LPD3DVALUE lprvTheta
  );

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

lprvAxis

Address of a D3DVECTOR structure that will be filled with the frame's axis of rotation.

lprvTheta

Address of a variable that will be the frame's rotation, in radians.

Return Values

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

See Also

IDirect3DRMFrame::SetRotation, Transformations

---

IDirect3DRMFrame::GetScene

IDirect3DRMFrame

Retrieves the root frame of the hierarchy containing the given frame.

HRESULT GetScene(
  LPDIRECT3DRMFRAME* lplpRoot
  );

Parameters

lplpRoot

Address of the pointer that will be filled with the pointer to the Direct3DRMFrame object representing the scene's root frame.

Return Values

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

---

IDirect3DRMFrame::GetSceneBackground

IDirect3DRMFrame

Retrieves the background color of a scene.

D3DCOLOR GetSceneBackground( );

Return Values

Returns the color.

---

IDirect3DRMFrame::GetSceneBackgroundDepth

IDirect3DRMFrame

Retrieves the current background-depth buffer for the scene.

HRESULT GetSceneBackgroundDepth(
  LPDIRECTDRAWSURFACE * lplpDDSurface
  );

Parameters

lplpDDSurface

Address of a pointer that will be initialized with the address of a DirectDraw surface representing the current background-depth buffer.

Return Values

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

See Also

IDirect3DRMFrame::SetSceneBackgroundDepth

---

IDirect3DRMFrame::GetSceneFogColor

IDirect3DRMFrame

Retrieves the fog color of a scene.

D3DCOLOR GetSceneFogColor( );

Return Values

Returns the fog color.

---

IDirect3DRMFrame::GetSceneFogEnable

IDirect3DRMFrame

Retrieves whether fog is currently enabled for this scene.

BOOL GetSceneFogEnable( );

Return Values

Returns TRUE if fog is enabled, or FALSE otherwise.

---

IDirect3DRMFrame::GetSceneFogMode

IDirect3DRMFrame

Retrieves the current fog mode for this scene.

D3DRMFOGMODE GetSceneFogMode( );

Return Values

Returns a member of the D3DRMFOGMODE enumerated type that specifies the current fog mode.

---

IDirect3DRMFrame::GetSceneFogParams

IDirect3DRMFrame

Retrieves the current fog parameters for this scene.

HRESULT GetSceneFogParams(
  D3DVALUE * lprvStart,
  D3DVALUE * lprvEnd,
  D3DVALUE * lprvDensity
  );

Parameters

lprvStart, lprvEnd, and lprvDensity

Addresses of variables that will be the fog start, end, and density values.

Return Values

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

---

IDirect3DRMFrame::GetSortMode

IDirect3DRMFrame

Retrieves the sorting mode used to process child frames.

D3DRMSORTMODE GetSortMode( );

Return Values

Returns the member of the D3DRMSORTMODE enumerated type that specifies the sorting mode.

See Also

IDirect3DRMFrame::SetSortMode

---

IDirect3DRMFrame::GetTexture

IDirect3DRMFrame

Retrieves the texture of the given frame.

HRESULT GetTexture(
  LPDIRECT3DRMTEXTURE* lplpTexture
  );

Parameters

lplpTexture

Address of the pointer that will be filled with the address of the Direct3DRMTexture object representing the frame's texture.

Return Values

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

See Also

IDirect3DRMFrame::SetTexture

---

IDirect3DRMFrame::GetTextureTopology

IDirect3DRMFrame

Retrieves the topological properties of a texture when mapped onto objects in the given frame.

HRESULT GetTextureTopology(
  BOOL * lpbWrap_u,
  BOOL * lpbWrap_v
  );

Parameters

lpbWrap_u and lpbWrap_v

Addresses of variables that are set to TRUE if the texture is mapped in the u and v directions, respectively.

Return Values

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

See Also

IDirect3DRMFrame::SetTextureTopology

---

IDirect3DRMFrame::GetTransform

IDirect3DRMFrame

Retrieves the local transformation of the frame as a 4×4 affine matrix.

HRESULT GetTransform(
  D3DRMMATRIX4D rmMatrix
  );

Parameters

rmMatrix

A D3DRMMATRIX4D array that will be filled with the frame's transformation. Because this is an array, this value is actually an address.

Return Values

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

See Also

3-D Transformations

---

IDirect3DRMFrame::GetVelocity

IDirect3DRMFrame

Retrieves the velocity of the frame relative to the given reference frame. Velocity is specified as units per tick. See IDirect3DRM::Tick for more information.

HRESULT GetVelocity(
  LPDIRECT3DRMFRAME lpRef,
  LPD3DVECTOR lprvVel,
  BOOL fRotVel
  );

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

lprvVel

Address of a D3DVECTOR structure that will be filled with the frame's velocity.

fRotVel

Flag specifying whether the rotational velocity of the object is taken into account when retrieving the linear velocity. If this parameter is TRUE, the object's rotational velocity is included in the calculation.

Return Values

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

See Also

IDirect3DRMFrame::SetVelocity

---

IDirect3DRMFrame::GetVisuals

IDirect3DRMFrame

Retrieves a list of visuals in the frame.

HRESULT GetVisuals(
  LPDIRECT3DRMVISUALARRAY* lplpVisuals
  );

Parameters

lplpVisuals

Address of a pointer to be initialized with a valid Direct3DRMVisualArray pointer if the call succeeds.

Return Values

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

---

IDirect3DRMFrame::GetZbufferMode

IDirect3DRMFrame

Retrieves the z-buffer mode; that is, whether z-buffering is enabled or disabled.

D3DRMZBUFFERMODE GetZbufferMode( );

Return Values

Returns one of the members of the D3DRMZBUFFERMODE enumerated type.

See Also

IDirect3DRMFrame::SetZbufferMode

---

IDirect3DRMFrame::InverseTransform

IDirect3DRMFrame

Transforms the vector in the lprvSrc parameter in world coordinates to model coordinates, and returns the result in the lprvDst parameter.

HRESULT InverseTransform(
  D3DVECTOR *lprvDst,
  D3DVECTOR *lprvSrc
  );

Parameters

lprvDst

Address of a D3DVECTOR structure that will be filled with the result of the transformation.

lprvSrc

Address of a D3DVECTOR structure that is the source of the transformation.

Return Values

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

See Also

IDirect3DRMFrame::Transform, 3-D Transformations

---

IDirect3DRMFrame::Load

IDirect3DRMFrame

Loads a Direct3DRMFrame object.

HRESULT Load(
  LPVOID lpvObjSource,
  LPVOID lpvObjID,
  D3DRMLOADOPTIONS d3drmLOFlags,
  D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
  LPVOID lpArgLTP
  );

Parameters

lpvObjSource

Source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the d3drmLOFlags parameter.

lpvObjID

Object name or position to be loaded. The use of this parameter depends on the identifier flags specified in the d3drmLOFlags parameter. If the D3DRMLOAD_BYPOSITION flag is specified, this parameter is a pointer to a DWORD value that gives the object's order in the file. This parameter can be NULL.

d3drmLOFlags

Value of the D3DRMLOADOPTIONS type describing the load options.

d3drmLoadTextureProc

A D3DRMLOADTEXTURECALLBACK callback function used to load any textures used by the object that require special formatting. This parameter can be NULL.

lpArgLTP

Address of application-defined data passed to the D3DRMLOADTEXTURECALLBACK callback function.

Return Values

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

Remarks

By default, this method loads the first frame hierarchy in the file specified by the lpvObjSource parameter. The frame that uses this method is used as the parent of the new frame hierarchy.

---

IDirect3DRMFrame::LookAt

IDirect3DRMFrame

Faces the frame toward the target frame, relative to the given reference frame, locking the rotation by the given constraints.

HRESULT LookAt(
  LPDIRECT3DRMFRAME lpTarget,
  LPDIRECT3DRMFRAME lpRef,
  D3DRMFRAMECONSTRAINT rfcConstraint
  );

Parameters

lpTarget and lpRef

Addresses of variables that represent the Direct3DRMFrame objects to be used as the target and reference, respectively.

rfcConstraint

Member of the D3DRMFRAMECONSTRAINT enumerated type that specifies the axis of rotation to constrain.

Return Values

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

---

IDirect3DRMFrame::Move

IDirect3DRMFrame

Applies the linear and rotational velocities for all frames in the given hierarchy.

HRESULT Move(
  D3DVALUE delta
  );

Parameters

delta

Amount to change the linear and rotational velocity. The change in each component is equal to the velocity of that component multiplied by delta. Although either or both of these velocities can be set relative to any frame, the system automatically converts them to velocities relative to the parent frame for the purpose of applying time deltas.

Return Values

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

---

IDirect3DRMFrame::SetColor

IDirect3DRMFrame

Sets the color of the frame. This color is used for meshes in the frame when the D3DRMMATERIALMODE enumerated type is D3DRMMATERIAL_FROMFRAME.

HRESULT SetColor(
  D3DCOLOR rcColor
  );

Parameters

rcColor

New color for the frame.

Return Values

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

Remarks

This method is also used to add a color key to a Direct3DRMFrameInterpolator object.

See Also

IDirect3DRMFrame::GetColor, IDirect3DRMFrame::SetMaterialMode

---

IDirect3DRMFrame::SetColorRGB

IDirect3DRMFrame

Sets the color of the frame. This color is used for meshes in the frame when the D3DRMMATERIALMODE enumerated type is D3DRMMATERIAL_FROMFRAME.

HRESULT SetColorRGB(
  D3DVALUE rvRed,
  D3DVALUE rvGreen,
  D3DVALUE rvBlue
  );

Parameters

rvRed, rvGreen, and rvBlue

New color for the frame. Each component of the color should be in the range 0 to 1.

Return Values

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

Remarks

This method is also used to add an RGB color key to a Direct3DRMFrameInterpolator object.

See Also

IDirect3DRMFrame::SetMaterialMode

---

IDirect3DRMFrame::SetMaterialMode

IDirect3DRMFrame

Sets the material mode for a frame. The material mode determines the source of material information for visuals rendered with the frame.

HRESULT SetMaterialMode(
  D3DRMMATERIALMODE rmmMode
  );

Parameters

rmmMode

One of the members of the D3DRMMATERIALMODE enumerated type.

Return Values

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

See Also

IDirect3DRMFrame::GetMaterialMode

---

IDirect3DRMFrame::SetOrientation

IDirect3DRMFrame

Aligns a frame so that its z-direction points along the direction vector [rvDx, rvDy, rvDz] and its y-direction aligns with the vector [rvUx, rvUy, rvUz].

HRESULT SetOrientation(
  LPDIRECT3DRMFRAME lpRef,
  D3DVALUE rvDx,
  D3DVALUE rvDy,
  D3DVALUE rvDz,
  D3DVALUE rvUx,
  D3DVALUE rvUy,
  D3DVALUE rvUz
  );

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

rvDx, rvDy, and rvDz

New z-axis for the frame.

rvUx, rvUy, and rvUz

New y-axis for the frame.

Return Values

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

Remarks

The default orientation of a frame has a direction vector of [0, 0, 1] and an up vector of [0, 1, 0].

If [rvUx, rvUy, rvUz] is parallel to [rvDx, rvDy, rvDz], the D3DRMERR_BADVALUE error value is returned; otherwise, the [rvUx, rvUy, rvUz] vector passed is projected onto the plane that is perpendicular to [rvDx, rvDy, rvDz].

This method is also used to add an orientation key to a Direct3DRMRFrameInterpolator object.

See Also

IDirect3DRMFrame::GetOrientation

---

IDirect3DRMFrame::SetPosition

IDirect3DRMFrame

Sets the position of a frame relative to the frame of reference. It places the frame a distance of [rvX, rvY, rvZ] from the reference. When a child frame is created within a parent, it is placed at [0, 0, 0] in the parent frame.

HRESULT SetPosition(
  LPDIRECT3DRMFRAME lpRef,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

rvX, rvY, and rvZ

New position for the frame.

Return Values

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

Remarks

This method also is used to add a position key to a Direct3DRMFrameInterpolator object.

See Also

IDirect3DRMFrame::GetPosition

---

IDirect3DRMFrame::SetRotation

IDirect3DRMFrame

Sets a frame rotating by the given angle around the given vector at each call to the IDirect3DRM::Tick or IDirect3DRMFrame::Move method. The direction vector [rvX, rvY, rvZ] is defined in the reference frame.

HRESULT SetRotation(
  LPDIRECT3DRMFRAME lpRef,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ,
  D3DVALUE rvTheta
  );

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

rvX, rvY, and rvZ

Vector about which rotation occurs.

rvTheta

Rotation angle, in radians.

Return Values

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

Remarks

The specified rotation changes the matrix with every render tick, unlike the IDirect3DRMFrame::AddRotation method, which changes the objects in the frame only once.

See Also

IDirect3DRMFrame::AddRotation, IDirect3DRMFrame::GetRotation

---

IDirect3DRMFrame::SetSceneBackground

IDirect3DRMFrame

Sets the background color of a scene.

HRESULT SetSceneBackground(
  D3DCOLOR rcColor
  );

Parameters

rcColor

New color for the background.

Return Values

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

Remarks

This method is also used to add a background color key to a Direct3DRMFrameInterpolator object.

---

IDirect3DRMFrame::SetSceneBackgroundDepth

IDirect3DRMFrame

Specifies a background-depth buffer for a scene.

HRESULT SetSceneBackgroundDepth(
  LPDIRECTDRAWSURFACE lpImage
  );

Parameters

lpImage

Address of a DirectDraw surface that will store the new background depth for the scene.

Return Values

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

Remarks

The image must have a depth of 16 bits per pixel. If the image and viewport sizes are different, the image is scaled first. For best performance when animating the background-depth buffer, the image should be the same size as the viewport. This enables the depth buffer to be updated directly from the image memory without incurring extra overhead.

See Also

IDirect3DRMFrame::GetSceneBackgroundDepth

---

IDirect3DRMFrame::SetSceneBackgroundImage

IDirect3DRMFrame

Specifies a background image for a scene.

HRESULT SetSceneBackgroundImage(
  LPDIRECT3DRMTEXTURE lpTexture
  );

Parameters

lpTexture

Address of a Direct3DRMTexture object that will contain the new background scene.

Return Values

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

Remarks

If the image is a different size or color depth than the viewport, the image will first be scaled or converted to the correct depth. For best performance when animating the background, the image should be the same size and color depth. This enables the background to be rendered directly from the image memory without incurring extra overhead.

---

IDirect3DRMFrame::SetSceneBackgroundRGB

IDirect3DRMFrame

Sets the background color of a scene.

HRESULT SetSceneBackgroundRGB(
  D3DVALUE rvRed,
  D3DVALUE rvGreen,
  D3DVALUE rvBlue
  );

Parameters

rvRed, rvGreen, and rvBlue

New color for the background.

Return Values

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

Remarks

This method is also used to add a background RGB color key to a Direct3DRMFrameInterpolator object.

---

IDirect3DRMFrame::SetSceneFogColor

IDirect3DRMFrame

Sets the fog color of a scene.

HRESULT SetSceneFogColor(
  D3DCOLOR rcColor
  );

Parameters

rcColor

New color for the fog.

Return Values

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

Remarks

This method is also used to add a fog color key to a Direct3DRMRFrameInterpolator object.

---

IDirect3DRMFrame::SetSceneFogEnable

IDirect3DRMFrame

Sets the fog-enable state.

HRESULT SetSceneFogEnable(
  BOOL bEnable
  );

Parameters

bEnable

New fog-enable state.

Return Values

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

---

IDirect3DRMFrame::SetSceneFogMode

IDirect3DRMFrame

Sets the fog mode.

HRESULT SetSceneFogMode(
  D3DRMFOGMODE rfMode
  );

Parameters

rfMode

One of the members of the D3DRMFOGMODE enumerated type, specifying the new fog mode.

Return Values

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

See Also

IDirect3DRMFrame::SetSceneFogParams

---

IDirect3DRMFrame::SetSceneFogParams

IDirect3DRMFrame

Sets the current fog parameters for this scene.

HRESULT SetSceneFogParams(
  D3DVALUE rvStart,
  D3DVALUE rvEnd,
  D3DVALUE rvDensity
  );

Parameters

rvStart and rvEnd

Fog start and end points for linear fog mode. These settings determine the distance from the camera at which fog effects first become visible and the distance at which fog reaches its maximum density.

rvDensity

Fog density for the exponential fog modes. This value should be in the range 0 through 1.

Return Values

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

Remarks

This method also is used to add a fog parameters key to a Direct3DRMRFrameInterpolator object.

See Also

D3DRMFOGMODE, IDirect3DRMFrame::SetSceneFogMode

---

IDirect3DRMFrame::SetSortMode

IDirect3DRMFrame

Sets the sorting mode used to process child frames. You can use this method to change the properties of hidden-surface-removal algorithms.

HRESULT SetSortMode(
  D3DRMSORTMODE d3drmSM
  );

Parameters

d3drmSM

One of the members of the D3DRMSORTMODE enumerated type, specifying the sorting mode. The default value is D3DRMSORT_FROMPARENT.

Return Values

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

See Also

IDirect3DRMFrame::GetSortMode

---

IDirect3DRMFrame::SetTexture

IDirect3DRMFrame

Sets the texture of the frame.

HRESULT SetTexture(
  LPDIRECT3DRMTEXTURE lpD3DRMTexture
  );

Parameters

lpD3DRMTexture

Address of a variable that represents the Direct3DRMTexture object to be used.

Return Values

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

Remarks

The texture is used for meshes in the frame when the D3DRMMATERIALMODE enumerated type is D3DRMMATERIAL_FROMFRAME. To disable the frame's texture, use a NULL texture.

See Also

IDirect3DRMFrame::GetTexture, IDirect3DRMFrame::SetMaterialMode

---

IDirect3DRMFrame::SetTextureTopology

IDirect3DRMFrame

Defines the topological properties of the texture coordinates across objects in the frame.

HRESULT SetTextureTopology(
  BOOL bWrap_u,
  BOOL bWrap_v
  );

Parameters

bWrap_u and bWrap_v

Variables that are set to TRUE to map the texture in the u- and v-directions, respectively.

Return Values

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

See Also

IDirect3DRMFrame::GetTextureTopology

---

IDirect3DRMFrame::SetVelocity

IDirect3DRMFrame

Sets the velocity of the given frame relative to the reference frame. The frame will be moved by the vector [rvX, rvY, rvZ] with respect to the reference frame at each successive call to the IDirect3DRM::Tick or IDirect3DRMFrame::Move method.

HRESULT SetVelocity(
  LPDIRECT3DRMFRAME lpRef,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ,
  BOOL fRotVel
  );

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

rvX, rvY, and rvZ

New velocity for the frame.

fRotVel

Flag specifying whether the rotational velocity of the object is taken into account when setting the linear velocity. If TRUE, the object's rotational velocity is included in the calculation.

Return Values

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

See Also

IDirect3DRMFrame::GetVelocity

---

IDirect3DRMFrame::SetZbufferMode

IDirect3DRMFrame

Sets the z-buffer mode.

HRESULT SetZbufferMode(
  D3DRMZBUFFERMODE d3drmZBM
  );

Parameters

d3drmZBM

One of the members of the D3DRMZBUFFERMODE enumerated type, specifying the z-buffer mode. The default value is D3DRMZBUFFER_FROMPARENT.

Return Values

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

See Also

IDirect3DRMFrame::GetZbufferMode

---

IDirect3DRMFrame::Transform

IDirect3DRMFrame

Transforms the vector in the lpd3dVSrc parameter in model coordinates to world coordinates, returning the result in the lpd3dVDst parameter.

HRESULT Transform(
  D3DVECTOR *lpd3dVDst,
  D3DVECTOR *lpd3dVSrc
  );

Parameters

lpd3dVDst

Address of a D3DVECTOR structure that will be filled with the result of the transformation operation.

lpd3dVSrc

Address of a D3DVECTOR structure that is the source of the transformation operation.

Return Values

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

See Also

IDirect3DRMFrame::InverseTransform, 3-D Transformations

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page