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. The child frame is added to the end of the Direct3DRMFrameArray object. You can obtain the Direct3DRMFrameArray object with IDirect3DRMFrame3::GetChildren.
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.

Remarks

The light is added to the end of the Direct3DRMLightArray object. You can obtain the Direct3DRMLightArray object with IDirect3DRMFrame3::GetLights.

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. This can be NULL. If NULL, the method uses its own local transform matrix instead of using the reference frame's transform matrix.
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. This can be NULL. If NULL, the method uses its own local transform matrix instead of using the reference frame's transform matrix.
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. This can be NULL. If NULL, the method uses its own local transform matrix instead of using the reference frame's transform matrix.
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. This can be NULL. If NULL, the method uses its own local transform matrix instead of using the reference frame's transform matrix.
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
Address of the variable that represents the Direct3DRMFrame object to be used as the target.

lpRef

Address of the variable that represents the Direct3DRMFrame object to be used as the reference. This can be NULL. If NULL, the method uses its own local transform matrix instead of using the reference frame's transform matrix.
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.