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.

Initialization	Init

Planes	AddPlane
	DeletePlane
	GetPlane
	GetPlaneIDs
	SetPlane