IDirect3DRMFrame3 Methods A to M

IDirect3DRMFrame3 Methods A to M

This section contains the reference pages for the methods of the IDirect3DRMFrame3 interface that begin with the letters A through M.
IDirect3DRMFrame3::AddChild
IDirect3DRMFrame3
Adds a child frame to a frame hierarchy.
Syntax
HRESULT AddChild(
  LPDIRECT3DRMFRAME3 lpD3DRMFrameChild
  );
Parameters

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

Return Value

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 IDirect3DRMFrame3::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

IDirect3DRMFrame3::AddLight
IDirect3DRMFrame3
Adds a light to a frame.
Syntax
HRESULT AddLight(
  LPDIRECT3DRMLIGHT lpD3DRMLight
  );
Parameters

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

Return Value

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

IDirect3DRMFrame3::AddMoveCallback
IDirect3DRMFrame3
Adds a callback function for special movement processing. The callback is called when the frame is moved or updated.
Syntax
HRESULT AddMoveCallback(
  D3DRMFRAME3MOVECALLBACK d3drmFMC,
  VOID * lpArg,
  DWORD dwFlags
  );
Parameters

d3drmFMC
Application-defined D3DRMFRAME3MOVECALLBACK callback function.
lpArg
Application-defined data to be passed to the callback function.
dwFlags
One of the following values:
D3DRMCALLBACK_PREORDER — The default value. When IDirect3DRMFrame3::Move traverses the hierarchy, callbacks for a frame are used before any child frames are traversed.
D3DRMCALLBACK_POSTORDER — When IDirect3DRMFrame3::Move traverses the hierarchy, callbacks for a frame are used after the child frames are traversed.

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 replaces IDirect3DRMFrame2::AddMoveCallback2. Multiple callbacks on an individual frame are used in the order that the callbacks were created.

See Also

IDirect3DRMFrame3::Move, IDirect3DRMFrame3::DeleteMoveCallback

IDirect3DRMFrame3::AddRotation
IDirect3DRMFrame3
Adds a rotation about (rvX, rvY, rvZ) by the number of radians specified in rvTheta.
Syntax
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 Value

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 IDirect3DRMFrame3 interface. This method changes the objects in the frame only once, unlike IDirect3DRMFrame3::SetRotation, which changes the matrix with every render tick.

See Also

3-D Transformations, IDirect3DRMFrame3::SetRotation

IDirect3DRMFrame3::AddScale
IDirect3DRMFrame3
Scales a frame's local transformation by (rvX, rvY, rvZ).
Syntax
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
Scale factors in the x-, y-, and z-directions.

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 specified transformation only changes the matrix for the frame identified by the IDirect3DRMFrame3 interface.

See Also

3-D Transformations

IDirect3DRMFrame3::AddTransform
IDirect3DRMFrame3
Transforms the local coordinates of the frame by the affine transformation specified by rctCombine and rmMatrix.
Syntax
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 Value

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 changes the matrix only for the frame identified by this IDirect3DRMFrame3 interface.

See Also

3-D Transformations

IDirect3DRMFrame3::AddTranslation
IDirect3DRMFrame3
Adds a translation by (rvX, rvY, rvZ) to a frame's local coordinate system.
Syntax
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
Definitions of the position changes in the x-, y-, and z-directions.

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 specified translation changes the matrix only for the frame identified by this IDirect3DRMFrame3 interface.

See Also

3-D Transformations

IDirect3DRMFrame3::AddVisual
IDirect3DRMFrame3
Adds a visual object to a frame.
Syntax
HRESULT AddVisual(
  LPUNKNOWN lpD3DRMVisual
  );
Parameters

lpD3DRMVisual
Pointer to a variable that represents the visual object to be added to the frame.

Return Value

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, progressive meshes, textures, shadows, user visuals, and 3-D DirectX Transform objects. When a visual object is added to a frame, it becomes visible if the frame is in view. The frame references the visual object.

IDirect3DRMFrame3::DeleteChild
IDirect3DRMFrame3
Removes a frame from the hierarchy. If the frame is not referenced, it is destroyed along with any child frames, lights, and meshes.
Syntax
HRESULT DeleteChild(
  LPDIRECT3DRMFRAME3 lpChild
  );
Parameters

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

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

Hierarchies

IDirect3DRMFrame3::DeleteLight
IDirect3DRMFrame3
Removes a light from a frame, destroying the light if it is no longer referenced. When a light is removed from a frame, the light no longer affects meshes in the scene its frame was in.
Syntax
HRESULT DeleteLight(
  LPDIRECT3DRMLIGHT lpD3DRMLight
  );
Parameters

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

Return Value

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

IDirect3DRMFrame3::DeleteMoveCallback
IDirect3DRMFrame3
Removes a frame-move callback function previously added with AddMoveCallback.
Syntax
HRESULT DeleteMoveCallback(
  D3DRMFRAME3MOVECALLBACK d3drmFMC,
  VOID * lpArg
  );
Parameters

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

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

IDirect3DRMFrame3::AddMoveCallback, IDirect3DRMFrame3::Move

IDirect3DRMFrame3::DeleteVisual
IDirect3DRMFrame3
Removes a visual object from a frame, destroying it if it is no longer referenced.
Syntax
HRESULT DeleteVisual(
  LPUNKNOWN lpD3DRMVisual
  );
Parameters

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

Return Value

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

IDirect3DRMFrame3::GetAxes
IDirect3DRMFrame3
Retrieves the vectors that are aligned with the direction (rvDx, rvDy, rvDz) and up (rvUx, rvUy, rvUz) vectors supplied to the IDirect3DRMFrame3::SetOrientation method.
Syntax
HRESULT GetAxes(
  LPD3DVECTOR dir,
  LPD3DVECTOR up
  );
Parameters

dir
The z-axis for the frame. Default is (0,0,1).
up
The y-axis for the frame. Default is (0,1,0).

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 along with IDirect3DRMFrame3::SetAxes helps support both left-handed and right-handed coordinate systems. SetAxes allows you to specify that the negative z-axis represents the front of the object.

See Also

IDirect3DRMFrame3::SetAxes, IDirect3DRMFrame3::GetInheritAxes, IDirect3DRMFrame3::SetInheritAxes

IDirect3DRMFrame3::GetBox
IDirect3DRMFrame3
Retrieves the bounding box containing a DIRECT3DRMFRAME2 object. The bounding box gives the minimum and maximum model coordinates in each dimension.
Syntax
HRESULT GetBox(
  D3DRMBOX * lpD3DRMBox
  );
Parameters

lpD3DRMBox
Address of a D3DRMBOX structure that will be filled with the bounding box coordinates.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. Returns D3DRMERR_BOXNOTSET unless a valid bounding box has already been set on the frame. For a list of other possible return codes, see Direct3D Retained Mode Return Values.

Remarks

This method supports a bounding box on a frame for hierarchical culling. A valid bounding box must be set on the frame with IDirect3DRMFrame3::SetBox. For a bounding box to be enabled, the IDirect3DRMFrame3::SetBoxEnable method must be used to set the enable flag to TRUE. By default, the box-enable flag is FALSE. There is no default bounding box.

See Also

IDirect3DRMFrame3::SetBox, IDirect3DRMFrame3::SetBoxEnable, IDirect3DRMFrame3::GetBoxEnable

IDirect3DRMFrame3::GetBoxEnable
IDirect3DRMFrame3
Retrieves the flag that determines whether a bounding box is enabled for this Direct3DRMFrame3 object.
Syntax
BOOL GetBoxEnable( );
Return Value

Returns TRUE if a bounding box is enabled, or FALSE if it is not enabled.

Remarks

For a bounding box to be enabled, the IDirect3DRMFrame3::SetBoxEnable flag must be used to set the enable flag to TRUE. By default, the box enable flag is FALSE.

See Also

IDirect3DRMFrame3::SetBoxEnable IDirect3DRMFrame3::GetBox, IDirect3DRMFrame3::SetBox

IDirect3DRMFrame3::GetChildren
IDirect3DRMFrame3
Retrieves a list of child frames in the form of a Direct3DRMFrameArray object.
Syntax
HRESULT GetChildren(
  LPDIRECT3DRMFRAMEARRAY* lplpChildren
  );
Parameters

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

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

DIRECT3DRMFRAMEARRAY, Hierarchies

IDirect3DRMFrame3::GetColor
IDirect3DRMFrame3
Retrieves the color of the frame.
Syntax
D3DCOLOR GetColor( );
Return Value

Returns the color of the Direct3DRMFrame2 object. By default, the color is white.

See Also

IDirect3DRMFrame3::SetColor

IDirect3DRMFrame3::GetHierarchyBox
IDirect3DRMFrame3
Calculates a bounding box to contain all the geometry in the hierarchy rooted in this Direct3DRMFrame3 object.
Syntax
HRESULT GetHierarchyBox(
  D3DRMBOX * lpD3DRMBox
  );
Parameters

lpD3DRMBox
Address of a D3DRMBOX structure that will be filled with the bounding box coordinates.

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

IDirect3DRMFrame3::GetBox, IDirect3DRMFrame3::SetBox, IDirect3DRMFrame3::SetBoxEnable, IDirect3DRMFrame3::GetBoxEnable

IDirect3DRMFrame3::GetInheritAxes
IDirect3DRMFrame3
Retrieves the flag that indicates whether the axes for the frame are inherited from the parent frame.
Syntax
BOOL GetInheritAxes( );
Return Value

Returns TRUE if the frame inherits axes (the default) and FALSE if the frame does not inherit axes.

Remarks

By default, the axes are inherited from the parent. If a frame is set to inherit from a parent and there is no parent, the frame acts as if it inherits from a parent with the default axes (direction=(0,0,1) and up=(0,1,0)).
This method and the IDirect3DRMFrame3::SetInheritAxes method allow a single policy for axes to be set at the root of the hierarchy.

See Also

IDirect3DRMFrame3::SetInheritAxes, IDirect3DRMFrame3::GetAxes, IDirect3DRMFrame3::SetAxes

IDirect3DRMFrame3::GetLights
IDirect3DRMFrame3
Retrieves a list of lights in the frame in the form of a Direct3DRMLightArray object.
Syntax
HRESULT GetLights(
  LPDIRECT3DRMLIGHTARRAY* lplpLights
  );
Parameters

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

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

IDirect3DRMLightArray

IDirect3DRMFrame3::GetMaterial
IDirect3DRMFrame3
Retrieves the material of the Direct3DRMFrame2 object.
Syntax
HRESULT GetMaterial(
  LPDIRECT3DRMMATERIAL2 *lplpMaterial
  );
Parameters

lplpMaterial
Address of a variable that will be filled with a pointer to the Direct3DRMMaterial object that is applied to the frame. By default, the material is NULL.

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

IDirect3DRMFrame3::SetMaterial

IDirect3DRMFrame3::GetMaterialMode
IDirect3DRMFrame3
Retrieves the material mode of the frame.
Syntax
D3DRMMATERIALMODE GetMaterialMode( );
Return Value

Returns a member of the D3DRMMATERIALMODE enumerated type that specifies the current material mode. By default, the mode is D3DRMMATERIAL_FROMMESH.

See Also

IDirect3DRMFrame3::SetMaterialMode

IDirect3DRMFrame3::GetMaterialOverride
IDirect3DRMFrame3
Retrieves the current per-attribute override settings for material attributes.
Syntax
HRESULT GetMaterialOverride(
  LPD3DRMMATERIALOVERRIDE lpdmOverride);
Parameters

lpdmOverride

Pointer to a D3DRMMATERIALOVERRIDE structure that describes the properties to be overridden.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.
If a texture exists in the override, its reference count has been incremented (with AddRef) before being passed back, and you need to release the texture when you exit. Therefore, if you apply a texture override, remember to release it.

See Also

SetMaterialOverride

IDirect3DRMFrame3::GetOrientation
IDirect3DRMFrame3
Retrieves the orientation of a frame relative to the given reference frame.
Syntax
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 normalized directions of the frame's z-axis and y-axis, respectively. The default orientation of a frame has a direction vector of [0, 0, 1] and an up vector of [0, 1, 0].

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

IDirect3DRMFrame3::SetOrientation

IDirect3DRMFrame3::GetParent
IDirect3DRMFrame3
Retrieves the parent frame of the current frame.
Syntax
HRESULT GetParent(
  LPDIRECT3DRMRAME3 * 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 Value

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

IDirect3DRMFrame3::GetPosition
IDirect3DRMFrame3
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.
Syntax
HRESULT GetPosition(
  LPDIRECT3DRMFRAME3 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 Value

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

See Also

IDirect3DRMFrame3::SetPosition

IDirect3DRMFrame3::GetRotation
IDirect3DRMFrame3
Retrieves the rotation of the frame relative to the given reference frame.
Syntax
HRESULT GetRotation(
  LPDIRECT3DRMFRAME3 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 Value

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

See Also

IDirect3DRMFrame3::SetRotation, Transformations

IDirect3DRMFrame3::GetScene
IDirect3DRMFrame3
Retrieves the root frame of the hierarchy containing the given frame.
Syntax
HRESULT GetScene(
  LPDIRECT3DRMFRAME3 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 Value

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

IDirect3DRMFrame3::GetSceneBackground
IDirect3DRMFrame3
Retrieves the background color of a scene.
Syntax
D3DCOLOR GetSceneBackground( );
Return Value

Returns the color.

IDirect3DRMFrame3::GetSceneBackgroundDepth
IDirect3DRMFrame3
Retrieves the current background-depth buffer for the scene.
Syntax
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 Value

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

See Also

IDirect3DRMFrame3::SetSceneBackgroundDepth

IDirect3DRMFrame3::GetSceneFogColor
IDirect3DRMFrame3
Retrieves the fog color of a scene.
Syntax
D3DCOLOR GetSceneFogColor( );
Return Value

Returns the fog color. By default, the color is white.

IDirect3DRMFrame3::GetSceneFogEnable
IDirect3DRMFrame3
Retrieves whether fog is currently enabled for this scene.
Syntax
BOOL GetSceneFogEnable( );
Return Value

Returns TRUE if fog is enabled, and FALSE otherwise. By default, this flag is FALSE.

IDirect3DRMFrame3::GetSceneFogMethod
IDirect3DRMFrame3
Retrieves the current fogging method.
Syntax
HRESULT GetSceneFogMethod(
  LPDWORD lpdwFlags);
Parameters

lpdwFlags

Pointer to a DWORD that receives the current fog method. Note that these flags are mutually exclusive. The currently defined flags are:

D3DRMFOGMETHOD_ANY

Indicates that Direct3DRM should choose an applicable method.

D3DRMFOGMETHOD_VERTEX

Use vertex fog.

D3DRMFOGMETHOD_TABLE

Use table fog.

Return Value

Returns one of the following values:

D3DRMERR_BADVALUE

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

The default behavior for Direct3DRMFrame objects created by the IDirect3DRM3 interface is D3DRMFOGMETHOD_ANY and the fog method will be chosen based on the capabilities of the device. If the device supports both vertex- and table-based fog then vertex fogging will be used. If the application requests table fog, but table fog is not available, vertex fog will be used. The default behavior for Direct3DRMFrame objects created with an IDirect3DRM or IDirect3DRM2 interface is D3DRMFOGMETHOD_VERTEX.
This method was introduced with DirectX version 6.0.

IDirect3DRMFrame3::GetSceneFogMode
IDirect3DRMFrame3
Retrieves the current fog mode for this scene.
Syntax
D3DRMFOGMODE GetSceneFogMode( );
Return Value

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

IDirect3DRMFrame3::GetSceneFogParams
IDirect3DRMFrame3
Retrieves the current fog parameters for this scene.
Syntax
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 Value

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

IDirect3DRMFrame3::GetSortMode
IDirect3DRMFrame3
Retrieves the sorting mode used to process child frames.
Syntax
D3DRMSORTMODE GetSortMode( );
Return Value

Returns the member of the D3DRMSORTMODE enumerated type that specifies the sorting mode. The default value is D3DRMSORT_FROMPARENT.

See Also

IDirect3DRMFrame3::SetSortMode

IDirect3DRMFrame3::GetTexture
IDirect3DRMFrame3
Retrieves the texture of the given frame.
Syntax
HRESULT GetTexture(
  LPDIRECT3DRMTEXTURE3* lplpTexture
  );
Parameters

lplpTexture
Address of the pointer that will be filled with the address of the Direct3DRMTexture object representing the frame's texture. By default, the texture is NULL.

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

IDirect3DRMFrame3::SetTexture

IDirect3DRMFrame3::GetTransform
IDirect3DRMFrame3
Retrieves the current-world transformation of the frame as a 4×4 affine matrix.
Syntax
HRESULT GetTransform(
  LPDIRECT3DRMFRAME lpRefFrame,
  D3DRMMATRIX4D rmMatrix);
Parameters

lpRefFrame

Frame that serves as the root of the scene for the purposes of this call. If this argument is NULL, the current root frame (as returned by GetScene) is used.

rmMatrix

D3DRMMATRIX4D array that receives the frame's transformation. Because this is an array, this value is an address.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0. This method extends IDirect3DRMFrame::GetTransform by adding the lpRefFrame parameter.

See Also

3-D Transformations

IDirect3DRMFrame3::GetTraversalOptions
IDirect3DRMFrame3
Retrieves the traversal status of the current frame.
Syntax
HRESULT GetTraversalOptions(
  LPDWORD lpdwFlags);
Parameters

lpdwFlags

Pointer to a DWORD that will be filled in with the current enable status. The currently defined flags are:

D3DRMFRAME_RENDERENABLE

Indicates render this frame or any children of this frame.

D3DRMFRAME_PICKENABLE

Indicates pick any visuals in this frame or any children of this frame.

By default, dwFlags is D3DRMFRAME_RENDERENABLE | D3DRMFRAME_PICKENABLE, and the frame is enabled for both rendering and picking.

Return Value

Returns one of the following values:

D3DRMERR_BADVALUE

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMFrame3::GetVelocity
IDirect3DRMFrame3
Retrieves the velocity of the frame relative to the given reference frame. Velocity is specified as units per tick. See IDirect3DRM3::Tick for more information.
Syntax
HRESULT GetVelocity(
  LPDIRECT3DRMFRAME3 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 Value

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

See Also

IDirect3DRMFrame3::SetVelocity

IDirect3DRMFrame3::GetVisuals
IDirect3DRMFrame3
Retrieves a list of visuals in the frame.
Syntax
HRESULT GetVisuals(
  LPDWORD pdwNumVisuals, LPUNKNOWN *ppUnk
  );
Parameters

pdwNumVisuals

Pointer to a DWORD value containing the number of vectors expected to be returned. If ppUnk is NULL, GetVisuals returns the number of visuals contained by the frame. If ppUnk is not NULL, the DWORD value receives the number of visuals actually retrieved.

ppUnk

Pointer to a Direct3DRMVisualArray object containing the array of visuals that will be initialized. Setting this to NULL causes GetVisuals to return the number of visuals contained by the frame. Otherwise, this is a user-allocated array with space for pdwNumVisuals.

Return Value

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

IDirect3DRMFrame3::GetZbufferMode
IDirect3DRMFrame3
Retrieves the z-buffer mode; that is, whether z-buffering is enabled or disabled.
Syntax
D3DRMZBUFFERMODE GetZbufferMode( );
Return Value

Returns one of the members of the D3DRMZBUFFERMODE enumerated type. The default value is D3DRMZBUFFER_FROMPARENT.

See Also

IDirect3DRMFrame3::SetZbufferMode

IDirect3DRMFrame3::InverseTransform
IDirect3DRMFrame3
Transforms the vector in the lprvSrc parameter in world coordinates to model coordinates, and returns the result in the lprvDst parameter.
Syntax
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 Value

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

See Also

IDirect3DRMFrame3::Transform, 3-D Transformations

IDirect3DRMFrame3::InverseTransformVectors
IDirect3DRMFrame3
This transforms an array of vectors from world- to model-space.
Syntax
HRESULT InverseTransformVectors
(LPDIRECT3DRMFRAME3 lpRefFrame,
DWORD dwNumVectors,
LPD3DVECTOR	lpDstVectors,
LPD3DVECTOR	lpSrcVectors);
Parameters

lpRefFrame

Frame that is to be used as the root of the scene for the purposes of this call. If this argument is NULL, the current root frame (as would be returned by GetScene) will be used.

dwNumVectors

The number of vectors whose coordinates are to be transformed.

lpDstVectors

Destination of the transformation.

lpSrcVectors

Array of vectors to transform.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMFrame3::Load
IDirect3DRMFrame3
Loads a Direct3DRMFrame2 object.
Syntax
HRESULT Load(
  LPVOID lpvObjSource,
  LPVOID lpvObjID,
  D3DRMLOADOPTIONS d3drmLOFlags,
  D3DRMLOADTEXTURE3CALLBACK 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
D3DRMLOADTEXTURE3CALLBACK callback function used to load any textures used by the object that require special formatting. This parameter can be NULL.
lpArgLTP
Pointer to application-defined data passed to the D3DRMLOADTEXTURE3CALLBACK callback function.

Return Value

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. By default, perspective correction is on.

IDirect3DRMFrame3::LookAt
IDirect3DRMFrame3
Faces the frame toward the target frame, relative to the given reference frame, locking the rotation by the given constraints.
Syntax
HRESULT LookAt(
  LPDIRECT3DRMFRAME3 lpTarget,
  LPDIRECT3DRMFRAME3 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 Value

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

IDirect3DRMFrame3::Move
IDirect3DRMFrame3
Applies the linear and rotational velocities for all frames in the given hierarchy.
Syntax
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 Value

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