IDirect3DRMClippedVisual

Microsoft® DirectX® version 6.0 introduced the IDirect3DRMClippedVisual interface. This interface allows applications to clip visual objects against arbitrary planes, specified in world space, before rendering. You create a clipped visual from another visual in much the same way you create a shadow from another visual. For example, you can create a clipped visual from a sphere and pass a clipping plane straight through the middle of the sphere to have only half of the sphere render. Create clipped visual objects by calling the IDirect3DRM3::CreateClippedVisual method. Then add the clipped visual to the scene by using the IDirect3DRMFrame3::AddVisual method.

IDirect3DRMClippedVisual inherits from IDirect3DRMVisual, as the other visual interfaces do. When the reference frame moves, the clipping plane does not move (see the AddPlane method for more information).

For a history of the Microsoft Direct3D® Retained Mode interfaces, see Interface Changes.

The methods of the IDirect3DRMClippedVisual interface can be organized into the following groups.
Initialization Init
Planes AddPlane
DeletePlane
GetPlane
GetPlaneIDs
SetPlane

The IDirect3DRMClippedVisual interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods.
AddRef
QueryInterface
Release

In addition, the IDirect3DRMClippedVisual interface inherits the following methods from the IDirect3DRMObject interface.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

You can create an Direct3DRMClippedVisual object by using the IDirect3DRM3 interface.

IDirect3DRMClippedVisual::AddPlane

IDirect3DRMClippedVisual

Adds a clipping plane.

Syntax

HRESULT AddPlane(
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lpdvPoint,
  LPD3DVECTOR lpdvNormal,
  DWORD dwFlags,
  LPDWORD lpdwReturnID);

Parameters

lpRef
Reference frame for the point and normal paramters.
lpdvPoint
Point on the plane relative to the reference frame.
lpdvNormal
Vector normal to the plane relative to the reference frame.
dwFlags
Unused flags. Must be zero.
lpdwReturnID
Pointer that receives a unique ID number for the plane on successful return.

Return Value

Returns DD_OK or DDERR_INVALIDPARAMS.

Remarks

Clipping planes are stored internally as world coordinates. When the reference frame moves, the clipping plane does not move. Use the SetPlane method to update the position and orientation of the clipping plane, as needed.

This method was introduced with DirectX version 6.0.

IDirect3DRMClippedVisual::DeletePlane

IDirect3DRMClippedVisual

Deletes a clipping plane.

Syntax

HRESULT DeletePlane(
  DWORD dwID,
  DWORD dwFlags);

Parameters

dwID
ID number of the plane to delete.
dwFlags
Unused flags.

Return Value

Returns DD_OK if successful.

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMClippedVisual::GetPlane

IDirect3DRMClippedVisual

Retrieves information about a clipping plane.

Syntax

HRESULT GetPlane(
  DWORD dwID,
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lpdvPoint,
  LPD3DVECTOR lpdvNormal,
  DWORD dwFlags);

Parameters

lpRef
Reference frame for this operation.
dwID
ID of the plane.
lpdvPoint
Pointer that receives a point on the plane relative to the reference frame on successful return.
lpdvNormal
Pointer that receives a vector normal to the plane, relative to the reference frame on successful return.
dwFlags
Unused flags. Must be zero.

Return Value

Returns DD_OK or DDERR_INVALIDPARAMS.

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMClippedVisual::GetPlaneIDs

IDirect3DRMClippedVisual

Retrieves an array of IDs.

Syntax

HRESULT GetPlanes(
  LPDWORD lpdwCount,
  LPDWORD lpdwID,
  DWORD dwFlags);

Parameters

lpdwCount
Pointer that receives the number of planes on successful return.
lpdwID
Addresss of a buffer large enough to contain an array of all the plane ID numbers. On successful return, contains the IDs of the planes. If NULL, only the number of planes is returned.
dwFlags
Unused flags. Must be zero.

Return Value

Returns DD_OK or DDERR_INVALIDPARAMS.

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMClippedVisual::Init

IDirect3DRMClippedVisual

Initializes the clipped visual.

Syntax

HRESULT Init(
  LPDIRECT3DRMVISUAL lpD3DRMVisual);

Parameters

lpD3DRMVisual
Visual that is to be clipped and rendered.

Return Value

Returns DD_OK if successful.

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMClippedVisual::SetPlane

IDirect3DRMClippedVisual

Changes the parameters of a clipping plane that has already been added.

Syntax

HRESULT SetPlane(
  DWORD dwID,
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lpdvPoint,
  LPD3DVECTOR lpdvNormal,
  DWORD dwFlags);

Parameters

dwID
ID number of the plane to be changed.
lpRef
The reference frame for the point and normal paramters. If this parameter is NULL, lpdvPoint and lpdvNormal are in world space.
lpdvPoint
Point on the plane relative to the reference frame.
lpdvNormal
Vector normal to the plane, relative to the reference frame.
dwFlags
Flag value. Must be zero.
lpdwReturnID
Pointer that receives a unique ID number for the plane on successful return.

Return Value

Returns DD_OK or DDERR_INVALIDPARAMS.

Remarks

This method was introduced with DirectX version 6.0.


Top of Page Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.