IDirect3DRMExternalVisual Interface

This interface is implemented by the external visual object, and is called by Microsoft® Direct3D® Retained Mode to allow the object to interact with the visual hierarchy as a first-class object.

IDirect3DRMExternalVisual Methods

BeginScene Begins the scene.
CanSee Specifies whether the external visual should be rendered.
DeviceChange Responds to device changes. Direct3D Retained Mode uses this method when the IDirect3DRMDevice2 object that the external visual is being rendered with changes.
EndScene Ends the scene.
GetAge Supplies the external visual's current age to Direct3D Retained Mode.
GetBox Supplies the external visual's bounding box to Direct3D Retained Mode.
Initialize Initializes the external visual.
Load Handles loading of an external visual from a DirectX file.
Pick Determines whether the external visual has been picked.
RayPick Determines whether the external visual has been picked by the specified ray.
Render Renders the external visual.
SetRenderContext Provides the external visual with the current context in which to render.

IDirect3DRMExternalVisual::BeginScene

IDirect3DRMExternalVisual

Begins the scene. The Direct3D Retained Mode IDirect3DRMViewport2::Render method calls this method immediately after calling the Microsoft Direct3D® Immediate Mode IDirect3DDevice::BeginScene method.

Syntax

HRESULT BeginScene(void);

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDirect3DRMExternalVisual::CanSee

IDirect3DRMExternalVisual

Specifies whether the external visual should be rendered. This method is called when an external visual is rendered. You can set the bounding box around the external visual with IDirect3DRMExternalUtil::UpdateBounds. Before rendering, the bounding box is checked to see if it is within the viewport. If it is, CanSee is called and should return D3DRMEXTVIS_CANSEE if the external visual should be rendered. If it shouldn't be rendered, CanSee should return D3DRMEXTVIS_CANNOTSEE.

Syntax

HRESULT CanSee(
    LPDIRECT3DRMDEVICE2 pRMDev,
    LPDIRECT3DRMVIEWPORT2 pRMView,
    LPDWORD pdwCanSee
    );

Parameters

pRMDev
[in] Pointer to the Direct3D Retained Mode device.
pRMView
[in] Pointer to the Direct3D Retained Mode viewport.
pdwCanSee
[out] Pointer to the value indicating whether the external visual should be rendered or not. This value should be either D3DRMEXTVIS_CANSEE or D3DRMEXTVIS_CANNOTSEE.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDirect3DRMExternalVisual::DeviceChange

IDirect3DRMExternalVisual

Responds to device changes. Direct3D Retained Mode uses this method when the IDirect3DRMDevice2 object that the external visual is being rendered with changes. The next IDirect3DRMExternalVisual::Render call will pass the new IDirect3DRMDevice2 object.

Syntax

HRESULT DeviceChange(void);

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDirect3DRMExternalVisual::EndScene

IDirect3DRMExternalVisual

Ends the scene. The Direct3D Retained Mode IDirect3DRMDevice3::Update method uses EndScene immediately before using the Direct3D Immediate Mode IDirect3DDevice::EndScene method.

Syntax

HRESULT EndScene(void);

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDirect3DRMExternalVisual::GetAge

IDirect3DRMExternalVisual

Supplies the external visual's current age to Direct3D Retained Mode. Age is a number that is incremented every time the external visual changes. Direct3D Retained Mode determines that the external visual has changed by examining its age. The external visual should increment its current age whenever an internal state changes. Note that the age must be incremented. It cannot simply be changed (for example, decremented).

Syntax

HRESULT GetAge(
    LPDWORD pdwAge
    );

Parameters

pdwAge
[out] Return pointer in which the external visual should fill in its current age.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDirect3DRMExternalVisual::GetBox

IDirect3DRMExternalVisual

Supplies the external visual's bounding box to Direct3D Retained Mode.

Syntax

HRESULT GetBox(
    LPD3DRMBOX pRMBox
    );

Parameters

pRMBox
[out] Return pointer in which the external visual should fill in its current bounding box values.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDirect3DRMExternalVisual::Initialize

IDirect3DRMExternalVisual

Initializes the external visual. Direct3D Retained Mode uses this method for all external visuals that it instantiates. The external visual is passed pointers to the creating Direct3D Retained Mode IDirect3DRM object and to an IDirect3DRMExternalUtil object.

Syntax

HRESULT Initialize(
    LPDIRECT3DRM pD3DRM, 
    LPDIRECT3DRMEXTERNALUTIL pExtUtil,
    DWORD dwFlags
    );

Parameters

pD3DRM
[in] Pointer to the IDirect3DRM object. The reference count for this object has already been incremented for the external visual. The object should be released by the external visual when it is no longer required.
pExtUtil
[in] Pointer to the IDirect3DRMExternalUtil object. The reference count for this object has already been incremented for the external visual. The object should be released by the external visual when it is no longer required. The IDirect3DRMExternalUtil object implements helper functions for texture caching.
dwFlags
[in] Must be zero.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDirect3DRMExternalVisual::Load

IDirect3DRMExternalVisual

Handles loading of an external visual from a DirectX file. The Direct3D Retained Mode DirectX file loader first uses CoCreateInstance on the external visual using the CLSID specified by the external visual's DirectX file object (hence the file loader calls IDirect3DRMExternalVisual::Initialize before calling this method). The loader then loads any properties contained by the external visual object and calls this method to load the external visual. Any properties are passed to the external visual in the IPropertyBag object, pPropBag.

The Direct3D Retained Mode IDirectXFileData object can be used to parse and create any data specific to external visual that is stored in the DirectX file.

Syntax

HRESULT Load(
    IDirectXFileData *dObject,
    IPropertyBag *pPropBag,
    DWORD dwFlags
    );

Parameters

dObject
[in] Pointer to the current External Visual DirectX file object. The external visual can call the IDirectXFileData::GetNextObject method to parse through any DirectX File objects that it requires.
pPropBag
[in] Property bag containing any text properties.
dwFlags
[in] Must be zero.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDirect3DRMExternalVisual::Pick

IDirect3DRMExternalVisual

Determines whether the external visual has been picked. IDirect3DRMViewport::Pick calls this method.

Syntax

HRESULT Pick(
    LPDIRECT3DRMVIEWPORT2 pViewIn,
    LPDIRECT3DRMFRAME3 pFrameIn,
    DWORD dwXIn,
    DWORD dwYIn,
    LPD3DVALUE pdvZOut,
    LPDWORD pdwPicked
    );

Parameters

pViewIn
[in] Pointer to a valid Direct3D Retained Mode viewport.
pFrameIn
[in] Pointer to the Direct3D Retained Mode frame containing the external visual.
dwXIn
[in] Screen x-coordinate used for picking.
dwYIn
[in] Screen y-coordinate used for picking.
pdvZOut
[out] Z-value for where the pick hit the external visual.
pdwPicked
[out] Pointer to a value specifying whether the external visual was picked. Set to D3DRMEXTVIS_PICK if the ray hits the external visual, otherwise set to D3DRMEXTVIS_NOTPICKED.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDirect3DRMExternalVisual::RayPick

IDirect3DRMExternalVisual

Determines whether the external visual has been picked by the specified ray. The Direct3D Retained Mode IDirect3DRMFrame3::RayPick calls this method.

Syntax

HRESULT RayPick(
    LPDIRECT3DRMFRAME3 pFrameIn,
    LPD3DRMRAY pRayIn,
    DWORD dwFlags,
    DWORD pdwPicked,
    LPD3DRMEXTVISRAYPICKINFO pPickInfo
    );

Parameters

pFrameIn
[in] Pointer to a valid Direct3D Retained Mode frame from which the ray originates.
pRayIn
[in] Pointer to the specified ray.
dwFlags
[in] Must be zero.
pdwPicked
[out] Pointer to a value specifying whether the external visual was picked. Set to D3DRMEXTVIS_PICK if the ray hits the external visual, otherwise set to D3DRMEXTVIS_NOTPICKED.
pPickInfo
[out] Pointer to the D3DRMEXTVISRAYPICKINFO structure containing information about the point at which the ray hit. See Remarks for a description of the structure.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The D3DRMEXTVISRAYPICKINFO structure contains information about the point the ray hit and is defined as follows. 

typedef struct
{
    D3DVALUE  dDistance;
    D3DVECTOR dvPosition;
    D3DVECTOR dvNormal;
    D3DVALUE  tu;
    D3DVALUE  tv;
    D3DCOLOR  dcColor;
} D3DRMEXTVISRAYPICKINFO, *LPD3DRMEXTVISRAYPICKINFO;

Members

dDistance
Distance between origin of the ray and the point where it hits the object being picked.
dvPosition
Position of ray when it hits the object.
dvNormal
Normal on the object at the point the ray hits the object.
tu, tv
Texture coordinate values at the point the ray hits the object.
dcColor
Color at the point the ray hits the object.

IDirect3DRMExternalVisual::Render

IDirect3DRMExternalVisual

Renders the external visual. Direct3D Retained Mode calls this method when it requires the external visual to render itself. Direct3D Retained Mode guarantees to pass the external visual an IDirect3DRMDevice2 interface from which the external visual can obtain a Direct3D Immediate Mode IDirect3DDevice2 interface. The external visual can then use the DirectX DrawPrimitive interface. Similarly, the external visual can obtain a Direct3D Immediate Mode IDirect3DViewport2 interface from the Direct3D Retained Mode IDirect3DRMViewport2 interface. The external visual should set any required render states (unless an override is in effect).

Render should call the IDirect3DRMExternalUtil::SetExtents method when it has finished rendering.

Syntax

HRESULT Render(
    LPDIRECT3DRMDEVICE2 pRMDev,
    LPDIRECT3DRMVIEWPORT2 pRMView, 
    DWORD dwFlags
    );

Parameters

pRMDev
[in] Direct3D Retained Mode device to render with.
pRMView
[in] Direct3D Retained Mode viewport to render with.
dwFlags
[in] Must be zero.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDirect3DRMExternalVisual::SetRenderContext

IDirect3DRMExternalVisual

Provides the external visual with the current context in which to render. Direct3D Retained Mode calls this method immediately before calling IDirect3DRMExternalVisual::Render. The current context includes any material overrides that are in effect.

Syntax

HRESULT SetRenderContext(
    LPD3DRMEXTVISRENDERCONTEXT pCntx,
    DWORD dwFlags
    );

Parameters

pCntx
[in] Pointer to the current render context.
dwFlags
[in] Must be zero.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

If the data members pCntx.hMat or pCntx.hTex are valid (indicated with the D3DRMEXTVIS_RENDERCONTEXT_OVERRIDEMATERIAL and D3DRMEXTVIS_RENDERCONTEXT_OVERRIDETEXTURE flags), the external visual should use these handles to set the current material light state and texture render state. If D3DRMEXTVIS_RENDERCONTEXT_NEWUSEROVERRIDE is set, the pCntx.dmUserOverride is valid, and the external visual should override the individual material attributes. For more information, see the Direct3D Retained Mode IDirect3DRMFrame3::SetMaterialOverride method.

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