Applications use the methods of the IDirect3DRMFrame interface to interact with framesan 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.
Adds a child frame to a frame hierarchy.
HRESULT AddChild(
LPDIRECT3DRMFRAME lpD3DRMFrameChild
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
Adds a light to a frame.
HRESULT AddLight(
LPDIRECT3DRMLIGHT lpD3DRMLight
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMFrame::Move, IDirect3DRMFrame::DeleteMoveCallback
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
3-D Transformations, IDirect3DRMFrame::SetRotation
Scales a frame's local transformation by (rvX, rvY, rvZ).
HRESULT AddScale(
D3DRMCOMBINETYPE rctCombine,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
The specified transformation changes the matrix only for the frame identified by this IDirect3DRMFrame interface.
Transforms the local coordinates of the frame by the affine transformation specified by rctCombine and rmMatrix.
HRESULT AddTransform(
D3DRMCOMBINETYPE rctCombine,
D3DRMMATRIX4D rmMatrix
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
Adds a translation by (rvX, rvY, rvZ) to a frame's local coordinate system.
HRESULT AddTranslation(
D3DRMCOMBINETYPE rctCombine,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
The specified translation changes the matrix only for the frame identified by this IDirect3DRMFrame interface.
Adds a visual object to a frame.
HRESULT AddVisual(
LPDIRECT3DRMVISUAL lpD3DRMVisual
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Removes a frame-move callback function previously added with AddMoveCallback.
HRESULT DeleteMoveCallback(
D3DRMFRAMEMOVECALLBACK d3drmFMC,
VOID * lpArg
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMFrame::AddMoveCallback, IDirect3DRMFrame::Move
Removes a visual object from a frame, destroying it if it is no longer referenced.
HRESULT DeleteVisual(
LPDIRECT3DRMVISUAL lpD3DRMVisual
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves a list of child frames in the form of a Direct3DRMFrameArray object.
HRESULT GetChildren(
LPDIRECT3DRMFRAMEARRAY* lplpChildren
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Direct3DRMFrameArray, Hierarchies
Retrieves the color of the frame.
D3DCOLOR GetColor( );
Returns the color of the Direct3DRMFrame object.
Retrieves a list of lights in the frame in the form of a Direct3DRMLightArray object.
HRESULT GetLights(
LPDIRECT3DRMLIGHTARRAY* lplpLights
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the material mode of the frame.
D3DRMMATERIALMODE GetMaterialMode( );
Returns a member of the D3DRMMATERIALMODE enumerated type that specifies the current material mode.
IDirect3DRMFrame::SetMaterialMode
Retrieves the orientation of a frame relative to the given reference frame.
HRESULT GetOrientation(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvDir,
LPD3DVECTOR lprvUp
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMFrame::SetOrientation
Retrieves the parent frame of the current frame.
HRESULT GetParent(
LPDIRECT3DRMFRAME* lplpParent
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the rotation of the frame relative to the given reference frame.
HRESULT GetRotation(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvAxis,
LPD3DVALUE lprvTheta
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMFrame::SetRotation, Transformations
Retrieves the root frame of the hierarchy containing the given frame.
HRESULT GetScene(
LPDIRECT3DRMFRAME* lplpRoot
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the background color of a scene.
D3DCOLOR GetSceneBackground( );
Returns the color.
Retrieves the current background-depth buffer for the scene.
HRESULT GetSceneBackgroundDepth(
LPDIRECTDRAWSURFACE * lplpDDSurface
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMFrame::SetSceneBackgroundDepth
Retrieves the fog color of a scene.
D3DCOLOR GetSceneFogColor( );
Returns the fog color.
Retrieves whether fog is currently enabled for this scene.
BOOL GetSceneFogEnable( );
Returns TRUE if fog is enabled, or FALSE otherwise.
Retrieves the current fog mode for this scene.
D3DRMFOGMODE GetSceneFogMode( );
Returns a member of the D3DRMFOGMODE enumerated type that specifies the current fog mode.
Retrieves the current fog parameters for this scene.
HRESULT GetSceneFogParams(
D3DVALUE * lprvStart,
D3DVALUE * lprvEnd,
D3DVALUE * lprvDensity
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the sorting mode used to process child frames.
D3DRMSORTMODE GetSortMode( );
Returns the member of the D3DRMSORTMODE enumerated type that specifies the sorting mode.
Retrieves the texture of the given frame.
HRESULT GetTexture(
LPDIRECT3DRMTEXTURE* lplpTexture
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the topological properties of a texture when mapped onto objects in the given frame.
HRESULT GetTextureTopology(
BOOL * lpbWrap_u,
BOOL * lpbWrap_v
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMFrame::SetTextureTopology
Retrieves the local transformation of the frame as a 4×4 affine matrix.
HRESULT GetTransform(
D3DRMMATRIX4D rmMatrix
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves a list of visuals in the frame.
HRESULT GetVisuals(
LPDIRECT3DRMVISUALARRAY* lplpVisuals
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the z-buffer mode; that is, whether z-buffering is enabled or disabled.
D3DRMZBUFFERMODE GetZbufferMode( );
Returns one of the members of the D3DRMZBUFFERMODE enumerated type.
IDirect3DRMFrame::SetZbufferMode
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMFrame::Transform, 3-D Transformations
Loads a Direct3DRMFrame object.
HRESULT Load(
LPVOID lpvObjSource,
LPVOID lpvObjID,
D3DRMLOADOPTIONS d3drmLOFlags,
D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
LPVOID lpArgLTP
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Applies the linear and rotational velocities for all frames in the given hierarchy.
HRESULT Move(
D3DVALUE delta
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method is also used to add a color key to a Direct3DRMFrameInterpolator object.
IDirect3DRMFrame::GetColor, IDirect3DRMFrame::SetMaterialMode
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method is also used to add an RGB color key to a Direct3DRMFrameInterpolator object.
IDirect3DRMFrame::SetMaterialMode
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMFrame::GetMaterialMode
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
IDirect3DRMFrame::GetOrientation
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method also is used to add a position key to a Direct3DRMFrameInterpolator object.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
The specified rotation changes the matrix with every render tick, unlike the IDirect3DRMFrame::AddRotation method, which changes the objects in the frame only once.
IDirect3DRMFrame::AddRotation, IDirect3DRMFrame::GetRotation
Sets the background color of a scene.
HRESULT SetSceneBackground(
D3DCOLOR rcColor
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method is also used to add a background color key to a Direct3DRMFrameInterpolator object.
Specifies a background-depth buffer for a scene.
HRESULT SetSceneBackgroundDepth(
LPDIRECTDRAWSURFACE lpImage
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
IDirect3DRMFrame::GetSceneBackgroundDepth
Specifies a background image for a scene.
HRESULT SetSceneBackgroundImage(
LPDIRECT3DRMTEXTURE lpTexture
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
Sets the background color of a scene.
HRESULT SetSceneBackgroundRGB(
D3DVALUE rvRed,
D3DVALUE rvGreen,
D3DVALUE rvBlue
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method is also used to add a background RGB color key to a Direct3DRMFrameInterpolator object.
Sets the fog color of a scene.
HRESULT SetSceneFogColor(
D3DCOLOR rcColor
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method is also used to add a fog color key to a Direct3DRMRFrameInterpolator object.
Sets the fog-enable state.
HRESULT SetSceneFogEnable(
BOOL bEnable
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the fog mode.
HRESULT SetSceneFogMode(
D3DRMFOGMODE rfMode
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMFrame::SetSceneFogParams
Sets the current fog parameters for this scene.
HRESULT SetSceneFogParams(
D3DVALUE rvStart,
D3DVALUE rvEnd,
D3DVALUE rvDensity
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method also is used to add a fog parameters key to a Direct3DRMRFrameInterpolator object.
D3DRMFOGMODE, IDirect3DRMFrame::SetSceneFogMode
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the texture of the frame.
HRESULT SetTexture(
LPDIRECT3DRMTEXTURE lpD3DRMTexture
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
IDirect3DRMFrame::GetTexture, IDirect3DRMFrame::SetMaterialMode
Defines the topological properties of the texture coordinates across objects in the frame.
HRESULT SetTextureTopology(
BOOL bWrap_u,
BOOL bWrap_v
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMFrame::GetTextureTopology
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the z-buffer mode.
HRESULT SetZbufferMode(
D3DRMZBUFFERMODE d3drmZBM
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMFrame::GetZbufferMode
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMFrame::InverseTransform, 3-D Transformations
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.