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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.