IDirect3DRMShadow2

Applications use the IDirect3DRMShadow2 and IDirect3DRMShadow interfaces to initialize Direct3DRMShadow2 and Direct3DRMShadow objects, respectively. Note that this initialization is not necessary if the application uses the IDirect3DRM3::CreateShadow method; it is required only if the application uses the IDirect3DRM3::CreateObject method to create the shadow. An application that calls IDirect3DRM3::CreateObject then calls the IDirect3DRMShadow2::Init method to initialize the shadow.

IDirect3DRMShadow2 extends the functionality of IDirect3DRMShadow by enabling the visual, light, plane, and option shadow parameters to be changed after creation. IDirect3DRMShadow2::SetOptions enables you to set an option that eliminates visual artifacts when blended transparency is enabled. IDirect3DRMShadow2 provides the SetVisual, GetVisual, SetLight, GetLight, SetPlane, GetPlane, SetOptions, and GetOptions methods, in addition to the Init method provided by IDirect3DRMShadow.

The methods of the IDirect3DRMShadow2 interface can be organized into the following groups.

Initialization	Init

Parameter Setting and Retrieval	GetLight
	GetOptions
	GetPlane
	GetVisual
	SetLight
	SetOptions
	SetPlane
	SetVisual

The IDirect3DRMShadow2 and IDirect3DRMShadow interfaces, like all Component Object Model (COM) interfaces, inherit the IUnknown interface methods. The IUnknown interface supports the following three methods.

AddRef
QueryInterface
Release

In addition, the IDirect3DRMShadow2 and IDirect3DRMShadow interfaces inherit the following methods from the IDirect3DRMObject interface.

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMShadow2 object is obtained by using the IDirect3DRM3::CreateShadow method.

IDirect3DRMShadow2::GetLight

IDirect3DRMShadow2

Retrieves the light source used when shadowing. If no light is associated with the shadow, an error is returned.

Syntax

HRESULT GetLight(
  LPDIRECT3DRMLIGHT  *lplpDirect3DRMLight);

Parameters

lplpDirect3DRMLight

Pointer to receive the light source.

Return Value

Returns one of the following values.

DD_OK

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMShadow2::GetOptions

IDirect3DRMShadow2

Retrieves shadow option flags.

Syntax

HRESULT GetOptions(
  LPDWORD pdwOptions);

Parameters

pdwOptions

Pointer to retrieve the current shadow options. Valid flag is:

D3DRMSHADOW_TRUEALPHA

Creates a shadow that will not have visual artifacts when rendered with true alpha enabled.

Return Value

Returns one of the following values.

DD_OK

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMShadow2::GetPlane

IDirect3DRMShadow2

Retrieves the shadow plane. The point is relative to the shadow's frame. The normal is in world space.

Syntax

HRESULT SetPlane(
  LPD3DVALUE pdvPX,
  LPD3DVALUE pdvPY,
  LPD3DVALUE pdvPZ,
  LPD3DVALUE pdvNX,
  LPD3DVALUE pdvNY,
  LPD3DVALUE pdvNZ);

Parameters

pdvPX, pdvPY, pdvPZ

Pointers to receive the x-, y-, and z-values of a point on the shadow plane relative to the shadow's frame. The values are specified as pointers to D3DVALUE data types.

pdvNX, pdvNY, pdvNZ

Pointers to receive the x-, y-, and z-values of the normal to the shadow plane as a world space vector. The values are specified as pointers to D3DVALUE data types.

Return Value

Returns one of the following values.

DD_OK

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMShadow2::GetVisual

IDirect3DRMShadow2

Retrieves the visual to be shadowed.

Syntax

HRESULT GetVisual(
  LPDIRECT3DRMVISUAL  *lplpDirect3DRMVisual);

Parameters

lplpDirect3DRMVisual

Pointer to receive the visual to be shadowed.

Return Value

Returns one of the following values.

DD_OK

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMShadow2::Init

IDirect3DRMShadow2

Initializes a Direct3DRMShadow2 object.

Syntax

HRESULT Init(
  LPUNKNOWN pUnk,
  LPDIRECT3DRMLIGHT lpD3DRMLight,
  D3DVALUE px,
  D3DVALUE py,
  D3DVALUE pz,
  D3DVALUE nx,
  D3DVALUE ny,
  D3DVALUE nz);

Parameters

pUnk
Pointer to the object casting the shadow.
lpD3DRMLight
Pointer to the Direct3DRMLight object that provides the light that defines the shadow.
px, py, and pz
Coordinates of a point on the plane on which the shadow is cast.
nx, ny, and nz
Coordinates of the normal vector of the plane on which the shadow is cast.

Return Value

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

Remarks

After you have called this method to initialize the shadow, add the shadow to the same frame in which the shadowed visual resides, using IDirect3DRMFrame3::AddVisual.

IDirect3DRMShadow2::SetLight

IDirect3DRMShadow2

Sets the light to be used when shadowing.

Syntax

HRESULT SetLight(
  LPDIRECT3DRMLIGHT lpDirect3DRMLight,
  DWORD dwFlags);

Parameters

lpDirect3DRMLight

Light to be used when shadowing.

dwFlags

Reserved. Must be zero.

Return Value

Returns one of the following values.

DD_OK

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMShadow2::SetOptions

IDirect3DRMShadow2

Sets the shadow option flags.

Syntax

HRESULT SetOptions(
  DWORD dwOptions);

Parameters

dwOptions

Shadow options. Valid flag is:

D3DRMSHADOW_TRUEALPHA

Creates a shadow that will not have visual artifacts when blended transparency (alpha blending) is enabled. Call IDirect3DRMDevice3::SetRenderMode to enable blended transparency.

Return Value

Returns one of the following values:

DD_OK

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMShadow2::SetPlane

IDirect3DRMShadow2

Sets the shadow plane. The point is relative to the shadow's frame. The normal is in world space.

Syntax

HRESULT SetPlane(
  D3DVALUE dvPX,
  D3DVALUE dvPY,
  D3DVALUE dvPZ,
  D3DVALUE dvNX,
  D3DVALUE dvNY,
  D3DVALUE dvNZ,
  DWORD dwFlags);

Parameters

dvPX, dvPY, dvPZ

Point on the shadow plane relative to the shadow's frame, specified as a D3DVALUE data type.

dvNX, dvNY, dvNZ

Normal to the shadow plane as a world space vector, specified as a D3DVALUE data type.

dwFlags

Reserved. Must be zero.

Return Value

Returns one of the following values.

DD_OK

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMShadow2::SetVisual

IDirect3DRMShadow2

Sets the visual to be shadowed.

Syntax

HRESULT SetVisual(
    LPDIRECT3DRMVISUAL lpDirect3DRMVisual,
    DWORD dwFlags);

Parameters

lpDirect3DRMVisual

Visual to be shadowed.

dwFlags

Reserved. Must be zero.

Return Value

Returns one of the following values.

DD_OK

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

Remarks

This method was introduced with DirectX version 6.0.