IDirect3DRMExternalUtil Interface

The IDirect3DRMExternalUtil interface provides some general helper methods for external visuals. It is primarily useful for texture caching, and because it provides access to the IDirect3DRMObject interface methods.

IDirect3DRMExternalUtil inherits from IDirect3DRMObject. If you create your external visual with IDirect3DRM3::CreateObject or IDirect3DRM3::Load, your external visual is aggregated with IDirect3DRMObject, and you can access the IDirect3DRMObject methods. However, if you create your external visual some other way, for example, with CoCreateInstance, you cannot access the IDirect3DRMObject methods and if you call them, you will get a D3DRMERR_NOTAGGREGATED error.

IDirect3DRMExternalUtil Methods

DestroyDeviceTexture Destroys the Microsoft® Direct3D® Retained Mode internal representation of the device-dependent texture.

FindDeviceTexture Enables you to obtain a device-dependent texture ID.

GetTextureHandle Enables you to obtain a D3DTEXTUREHANDLE texture handle with which to render textures from a device-dependent texture ID.

SetExtents Updates the current viewport's two-dimensional (2-D) extents.

UpdateBounds Enables the external visual to set the current bounding box stored for it by Direct3D Retained Mode.

ValidateDeviceTextures Validates textures to ensure they are supported by the device.

Methods Inherited from IDirect3DRMObject

AddDestroyCallback Registers a function that will be called when an object is destroyed.

Clone Creates a copy of an object.

DeleteDestroyCallback Removes a function previously registered with the IDirect3DRMExternalUtil::AddDestroyCallback method.

GetAppData Retrieves the 32 bits of application-specific data in the object. The default value of the data is zero.

GetClassName Retrieves the name of the object's class.

GetName Retrieves the object's name.

SetAppData Sets the 32 bits of application-specific data in the object.

SetName Sets the object's name.

IDirect3DRMExternalUtil::AddDestroyCallback

IDirect3DRMExternalUtil

Registers a function that will be called when an object is destroyed.

Syntax

HRESULT AddDestroyCallback(
  D3DRMOBJECTCALLBACK lpCallback,
  LPVOID lpArg
  );

Parameters

lpCallback
User-defined callback function that will be used when the object is destroyed.
lpArg
Address of application-defined data passed to the callback function. Because this function is used after the object has been destroyed, you should not use this function with the object as an argument.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. Returns D3DRMERR_NOTAGGREGATED if the external visual was not created with IDirect3DRM3::CreateObject or IDirect3DRM3::Load, and thus is not aggregated onto IDirect3DRMObject.

IDirect3DRMExternalUtil::Clone

IDirect3DRMExternalUtil

Creates a copy of an object.

Syntax

HRESULT Clone(
  LPUNKNOWN pUnkOuter,
  REFIID riid,
  LPVOID *ppvObj
  );

Parameters

pUnkOuter
Pointer to the outer IUnknown interface that allows COM aggregation features.
riid
Identifier of the object being copied.
ppvObj
Address that will contain the copy of the object when the method returns.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. Returns D3DRMERR_NOTAGGREGATED if the external visual was not created with IDirect3DRM3::CreateObject or IDirect3DRM3::Load and is not aggregated onto IDirect3DRMObject.

IDirect3DRMExternalUtil::DeleteDestroyCallback

IDirect3DRMExternalUtil

Removes a function previously registered with the IDirect3DRMExternalUtil::AddDestroyCallback method.

Syntax

HRESULT DeleteDestroyCallback(
  D3DRMOBJECTCALLBACK d3drmObjProc,
  LPVOID lpArg
  );

Parameters

d3drmObjProc
User-defined callback function that was to be used when the object was destroyed.
lpArg
Address of application-defined data passed to the callback function.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. Returns D3DRMERR_NOTAGGREGATED if the external visual was not created with IDirect3DRM3::CreateObject or IDirect3DRM3::Load and is not aggregated onto IDirect3DRMObject.

IDirect3DRMExternalUtil::DestroyDeviceTexture

IDirect3DRMExternalUtil

Destroys the Microsoft® Direct3D® Retained Mode internal representation of the device-dependent texture.

Syntax

HRESULT DestroyDeviceTexture(
    DWORD dwDevTexId
    );

Parameters

dwDevTexId

[in] Valid device-dependent texture ID, as returned by IDirect3DRMExternalUtil::FindDeviceTexture.

Return Value

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

IDirect3DRMExternalUtil::FindDeviceTexture

IDirect3DRMExternalUtil

Enables you to obtain a device-dependent texture ID. You should use this method every time the current device changes and you want to obtain a D3DTEXTUREHANDLE texture handle to render with. Use GetTextureHandle to get the texture handle for the texture ID.

Syntax

HRESULT FindDeviceTexture(
    LPDIRECT3DRMDEVICE2 lpRMDev, 
    LPDIRECT3DRMTEXTURE lpRMTex,
    LPDWORD dwDevTexId
    );

Parameters

lpRMDev

[in] Pointer to a valid Direct3D Retained Mode device.

lpRMTex

[in] Pointer to a valid Direct3D Retained Mode texture.

dwDevTexId

[out] Device-dependent texture ID.

Return Value

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

IDirect3DRMExternalUtil::GetAppData

IDirect3DRMExternalUtil

Retrieves the 32 bits of application-specific data in the object. The default value of the data is zero.

Syntax

DWORD GetAppData( );

Return Value

Returns the data value defined by the application.

See Also

IDirect3DRMExternalUtil::SetAppData

IDirect3DRMExternalUtil::GetClassName

IDirect3DRMExternalUtil

Retrieves the name of the object's class.

Syntax

HRESULT GetClassName(
  LPDWORD lpdwSize,
  LPSTR lpName
  );

Parameters

lpdwSize
Address of a variable containing the size, in bytes, of the buffer pointed to by the lpName parameter.
lpName
Address of a variable that will contain a null-terminated string identifying the class name when the method returns. If this parameter is NULL, the lpdwSize parameter will contain the required size for the string when the method returns.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. Returns D3DRMERR_NOTAGGREGATED if the external visual was not created with IDirect3DRM3::CreateObject or IDirect3DRM3::Load and is not aggregated onto IDirect3DRMObject.

IDirect3DRMExternalUtil::GetName

IDirect3DRMExternalUtil

Retrieves the object's name.

Syntax

HRESULT GetName(
  LPDWORD lpdwSize,
  LPSTR lpName
  );

Parameters

lpdwSize
Address of a variable containing the size, in bytes, of the buffer pointed to by the lpName parameter.
lpName
Address of a variable that will contain a null-terminated string identifying the object's name when the method returns. If this parameter is NULL, the lpdwSize parameter will contain the required size for the string when the method returns.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. Returns D3DRMERR_NOTAGGREGATED if the external visual was not created with IDirect3DRM3::CreateObject or IDirect3DRM3::Load and is not aggregated onto IDirect3DRMObject.

See Also

IDirect3DRMExternalUtil::SetName

IDirect3DRMExternalUtil::GetTextureHandle

IDirect3DRMExternalUtil

Enables you to obtain a D3DTEXTUREHANDLE texture handle with which to render textures from a device-dependent texture ID. IDirect3DRMExternalUtil::FindDeviceTexture supplies the texture ID.

Syntax

HRESULT GetTextureHandle(
    DWORD dwDevTexId,
    LPDWORD pdwHandle
    );

Parameters

dwDevTexId

[in] Valid device-dependent texture ID, as returned by IDirect3DRMExternalUtil::FindDeviceTexture.

pdwHandle

[out] D3DTEXTUREHANDLE that the external visual developer uses to render.

Return Value

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

Remarks

A texture handle identifies the coupling of a texture map with a device. A texture can be associated with more than one device.

IDirect3DRMExternalUtil::SetAppData

IDirect3DRMExternalUtil

Sets the 32 bits of application-specific data in the object.

Syntax

HRESULT SetAppData(
  DWORD ulData
  );

Parameters

ulData
User-defined data to be stored with the object.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. Returns D3DRMERR_NOTAGGREGATED if the external visual was not created with IDirect3DRM3::CreateObject or IDirect3DRM3::Load and is not aggregated onto IDirect3DRMObject.

See Also

IDirect3DRMExternalUtil::GetAppData

IDirect3DRMExternalUtil::SetExtents

IDirect3DRMExternalUtil

Updates the current viewport's two-dimensional (2-D) extents. The IDirect3DRMExternalVisual::Render method uses this method.

You can pass an array of values returned by the Microsoft® Direct3D® Immediate Mode IDirect3DDevice::GetClipStatus method to this function.

Syntax

HRESULT SetExtents(
    LPDIRECT3DRMVIEWPORT2 lpRMView,
    DWORD dwNumExtents, 
    LPD3DCLIPSTATUS pExtents
    );

Parameters

lpRMView

[in] Viewport whose extents are going to be updated.

dwNumExtents

[in] Number of extents in the array pExtents.

pExtents

[in] Pointer to an array of 2-D extents, as returned by IDirect3DDevice2::GetClipStatus.

Return Value

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

IDirect3DRMExternalUtil::SetName

IDirect3DRMExternalUtil

Sets the object's name.

Syntax

HRESULT SetName(
  const char * lpName
  );

Parameters

lpName
User-defined data to name the object.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. Returns D3DRMERR_NOTAGGREGATED if the external visual was not created with IDirect3DRM3::CreateObject or IDirect3DRM3::Load and is not aggregated onto IDirect3DRMObject.

See Also

IDirect3DRMExternalUtil::GetName

IDirect3DRMExternalUtil::UpdateBounds

IDirect3DRMExternalUtil

Enables the external visual to set the current bounding box stored for it by Direct3D Retained Mode.

Syntax

HRESULT UpdateBounds(
    DWORD dwFlags,
    LPD3DVECTOR dvMin,
    LPD3DVECTOR dvMax
    );

Parameters

dwFlags

[in] Valid flag values include the following:

D3DRMEXTUTIL_BOUNDSVALID

Indicates the values passed in dvMin and dvMax are used to set the new bounding box.

D3DRMEXTUTIL_BOUNDSINVALIDATE

Indicates the current bounding box is cleared.

dvMin, dvMax

[in] Bounding box values.

Return Value

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

IDirect3DRMExternalUtil::ValidateDeviceTextures

IDirect3DRMExternalUtil

Validates device textures. A texture is validated to ensure that the device can support the specified type of texture format and dimensions. This method should be used for every frame in which a texture is going to be used when rendering an external visual.

Syntax

HRESULT ValidateDeviceTextures(
    LPDIRECT3DRMDEVICE2 lpRMDev,
    LPDWORD dwDevTexIds,
    DWORD dwNumIds
    );

Parameters

lpRMDev

[in] Pointer to a valid Direct3D Retained Mode device.

dwDevTexIds

[in] Array containing each of the device-dependent texture ID's that are being used. This array is passed to Direct3D Retained Mode.

dwNumIds

[in] Number of device-dependent texture IDs in the array dwDevTexIds.

Return Value

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

DestroyDeviceTexture	Destroys the Microsoft® Direct3D® Retained Mode internal representation of the device-dependent texture.
FindDeviceTexture	Enables you to obtain a device-dependent texture ID.
GetTextureHandle	Enables you to obtain a D3DTEXTUREHANDLE texture handle with which to render textures from a device-dependent texture ID.
SetExtents	Updates the current viewport's two-dimensional (2-D) extents.
UpdateBounds	Enables the external visual to set the current bounding box stored for it by Direct3D Retained Mode.
ValidateDeviceTextures	Validates textures to ensure they are supported by the device.

AddDestroyCallback	Registers a function that will be called when an object is destroyed.
Clone	Creates a copy of an object.
DeleteDestroyCallback	Removes a function previously registered with the IDirect3DRMExternalUtil::AddDestroyCallback method.
GetAppData	Retrieves the 32 bits of application-specific data in the object. The default value of the data is zero.
GetClassName	Retrieves the name of the object's class.
GetName	Retrieves the object's name.
SetAppData	Sets the 32 bits of application-specific data in the object.
SetName	Sets the object's name.