C++ Callback Functions

The Microsoft® Direct3D® Retained Mode callback functions for C++ are:

D3DRMDEVICE3UPDATECALLBACK

Alerts the application when the device changes. This callback function is application-defined.

Syntax

void (*D3DRMDEVICE3UPDATECALLBACK)(
  LPDIRECT3DRMDEVICE3 lpobj,
  LPVOID lpArg,
  int iRectCount,
  LPD3DRECT d3dRectUpdate);

Parameters

lpobj
Address of a pointer to the Direct3DRMDevice3 object to which this callback function applies.
lpArg
Address of a pointer to application-defined data passed to this callback function.
iRectCount
Number of rectangles specified in the d3dRectUpdate parameter.
d3dRectUpdate
Array of one or more D3DRECT structures that describe the area to be updated. The coordinates are specified in device units.

Return Value

No return value.

Remarks

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

D3DRMDEVICE3UPDATECALLBACK was introduced with DirectX version 6.0 and replaces the older D3DRMUPDATECALLBACK. The only difference between the two callbacks is that the new callback takes a Direct3DRMDevice3 object, rather than a Direct3DRMDevice object for the lpobj parameter.

See Also

IDirect3DRMDevice3::AddUpdateCallback, IDirect3DRMDevice3::DeleteUpdateCallback, IDirect3DRMDevice3::Update

D3DRMDOWNSAMPLECALLBACK

Called when the video memory is getting overloaded and the texture surfaces need to be reduced in size. Direct3D Retained Mode provides default methods for reducing texture sizes, such as DirectDraw blitting and bilinear filtering, but users can define their own method to scale down texture size with this callback. This callback function is application-defined.

Syntax

HRESULT (*D3DRMDOWNSAMPLECALLBACK)(
  LPDIRECT3DRMTEXTURE3 lpDirect3DRMTexture,
  LPVOID lpArg,
  LPDIRECTDRAWSURFACE pDDSSrc,
  LPDIRECTDRAWSURFACE pDDSDst);

Parameters

lpDirect3DRMTexture
Address of a pointer to the Direct3DRMTexture3 object to which this callback function applies.
lpArg
Address of a pointer to application-defined data passed to this callback function.
pDDSSrc
Pointer to the system memory prototype surface.
pDDSDst
Pointer to the scaled down surface.

Return Value

No return value.

Remarks

D3DRMDOWNSAMPLECALLBACK was introduced with DirectX version 6.0.

See Also

IDirect3DRMTexture3::SetDownsampleCallback

D3DRMFRAME3MOVECALLBACK

Enables an application to apply customized algorithms when a frame is moved or updated. You can use this callback function to compensate for changing frame rates. This callback function is application-defined.

Syntax

void (*D3DRMFRAME3MOVECALLBACK)(
  LPDIRECT3DRMFRAME3 lpD3DRMFrame,
  LPVOID lpArg,
  D3DVALUE delta);

Parameters

lpD3DRMFrame
Address of a pointer to the Direct3DRMFrame3 object that is being moved.
lpArg
Address of a pointer to application-defined data passed to this callback function.
delta
Amount of change to apply to the movement. There are two components to the change in position of a frame: linear and rotational. The change in each component is equal to velocity_of_component × delta. Although either or both of these velocities can be set relative to any frame, the system automatically converts them to velocities relative to the parent frame for the purpose of applying time deltas.

Return Value

No return value.

Remarks

Your application can synthesize the acceleration of a frame relative to its parent frame. To do so, on each tick your application should set the velocity of the child frame relative to itself to (a units per tick) × 1 tick, where a is the required acceleration. This is equal to a × delta units per tick. Internally, a × delta units per tick relative to the child frame is converted to (v + (a × delta)) units per tick relative to the parent frame, where v is the current velocity of the child relative to the parent.

You can add and remove this callback function from your application by using the IDirect3DRMFrame3::AddMoveCallback and IDirect3DRMFrame3::DeleteMoveCallback methods.

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

D3DRMFRAME3MOVECALLBACK was introduced with DirectX version 6.0 and replaces the older D3DRMFRAMEMOVECALLBACK. The only difference between the two callbacks is that the new callback takes a Direct3DRMFrame3 object rather than a Direct3DRMFrame object for the lpD3DRMFrame parameter.

D3DRMLOADCALLBACK

Loads objects named in a call to the IDirect3DRM3::Load method. This callback function is application-defined.

Syntax

void (*D3DRMLOADCALLBACK)(
  LPDIRECT3DRMOBJECT lpObject,
  REFIID ObjectGuid,
  LPVOID lpArg);

Parameters

lpObject
Address of a pointer to the Direct3DRMObject being loaded.
ObjectGuid
Globally unique identifier (GUID) of the object being loaded.
lpArg
Address of a pointer to application-defined data passed to this callback function.

Return Value

No return value.

Remarks

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

See Also

IDirect3DRM3::Load

D3DRMLOADTEXTURECALLBACK

Loads texture maps from a file or resource named in a call to one of the Load methods. This callback function is application-defined.

Syntax

HRESULT (*D3DRMLOADTEXTURECALLBACK)(
  char *tex_name,
  void *lpArg,
  LPDIRECT3DRMTEXTURE *lpD3DRMTex);

Parameters

tex_name
Address of a pointer to a string containing the name of the texture.
lpArg
Address of a pointer to application-specific data.
lpD3DRMTex
Address of a pointer to the Direct3DRMTexture object.

Return Value

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

Remarks

In order to maintain an accurate reference count, you should call AddRef on texture objects created in a texture callback.

Applications can use this callback function to implement support for textures that are not in the Microsoft® Windows® bitmap (.bmp) or Portable Pixelmap bitmap (.ppm) P6 format. The P6 format is a binary file format for color images.

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

See Also

IDirect3DRM3::Load, IDirect3DRMAnimationSet2::Load, IDirect3DRMFrame3::Load, IDirect3DRMMeshBuilder3::Load

D3DRMLOADTEXTURE3CALLBACK

Loads texture maps from a file or resource named in a call to one of the Load methods. This callback function is application-defined.

Syntax

HRESULT (*D3DRMLOADTEXTURE3CALLBACK)(
  char *tex_name,
  void *lpArg,
  LPDIRECT3DRMTEXTURE3 *lpD3DRMTex3);

Parameters

tex_name
Address of a pointer to a string containing the name of the texture.
lpArg
Address of a pointer to application-specific data.
lpD3DRMTex3
Address of a pointer to the Direct3DRMTexture3 object.

Return Value

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

Remarks

In order to maintain an accurate reference count, you should call AddRef on texture objects created in a texture callback.

Applications can use this callback function to implement support for textures that are not in the Microsoft® Windows® bitmap (.bmp) or Portable Pixelmap bitmap (.ppm) P6 format. The P6 format is a binary file format for color images.

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

See Also

IDirect3DRM3::Load, IDirect3DRMAnimationSet2::Load, IDirect3DRMFrame3::Load, IDirect3DRMMeshBuilder3::Load

D3DRMOBJECTCALLBACK

Enumerates objects in response to a call to the IDirect3DRM3::EnumerateObjects method. This callback function is application-defined.

Syntax

void (*D3DRMOBJECTCALLBACK)(
  LPDIRECT3DRMOBJECT lpD3DRMobj,
  LPVOID lpArg);

Parameters

lpD3DRMobj
Pointer to the IDirect3DRMObject interface for the object being enumerated. The application must use the Release method for each enumerated object.
lpArg
Address of a pointer to application-defined data passed to this callback function.

Return Value

No return value.

Remarks

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

See Also

IDirect3DRM3::EnumerateObjects

D3DRMUSERVISUALCALLBACK

Alerts an application that supplies user-visual objects that it should execute the execute buffer. This function is application-defined.

Syntax

int (*D3DRMUSERVISUALCALLBACK)(
  LPDIRECT3DRMUSERVISUAL lpD3DRMUV,
  LPVOID lpArg,
  D3DRMUSERVISUALREASON lpD3DRMUVreason,
  LPDIRECT3DRMDEVICE lpD3DRMDev,
  LPDIRECT3DRMVIEWPORT lpD3DRMview);

Parameters

lpD3DRMUV
Address of a pointer to the Direct3DRMUserVisual object.
lpArg
Address of a pointer to application-defined data passed to this callback function.
lpD3DRMUVreason
One of the members of the D3DRMUSERVISUALREASON enumerated type:
D3DRMUSERVISUAL_CANSEE
The application should return TRUE if the user-visual object is visible in the viewport. In this case, the application uses the device specified in the lpD3DRMview parameter.
D3DRMUSERVISUAL_RENDER
The application should render the user-visual element. In this case, the application uses the device specified in the lpD3DRMDev parameter.
lpD3DRMDev
Address of a pointer to a Direct3DRMDevice object used to render the Direct3DRMUserVisual object.
lpD3DRMview
Address of a pointer to a Direct3DRMViewport object used to determine whether the Direct3DRMUserVisual object is visible.

Return Value

Returns TRUE if the lpD3DRMUVreason parameter is D3DRMUSERVISUAL_CANSEE, and the user-visual object is visible in the viewport. Returns FALSE otherwise. If the lpD3DRMUVreason parameter is D3DRMUSERVISUAL_RENDER, the return value is application-defined. It is always safe to return TRUE.

Remarks

If the application changes the render state, it should restore the render state before returning from this function.

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

See Also

IDirect3DRMUserVisual::Init and IDirect3DRM3::CreateUserVisual

D3DRMVALIDATIONCALLBACK

Called when a texture region that has previously been marked as invalid, meaning it has changed but not been updated, now needs to be updated. This callback function is application-defined.

Syntax

HRESULT (*D3DRMVALIDATIONCALLBACK)(
  LPDIRECT3DRMTEXTURE3 lpDirect3DRMTexture,
  LPVOID lpArg,
  DWORD dwFlags,
  DWORD dwcRects,
  LPRECT pRects);

Parameters

lpDirect3DRMTexture
Address of a pointer to the Direct3DRMTexture3 object to which this callback function applies.
lpArg
Address of a pointer to application-defined data passed to this callback function.
dwFlags
Not used. Set to 0.
dwcRects
Number of rectangles specified in the pRects parameter.
pRects
Array of one or more RECT structures that describe the area to be updated. The coordinates are specified in device units.

Return Value

No return value.

Remarks

When you want to inform Direct3D Retained Mode that a texture region has been changed but want to defer changing it, you can say the region is invalid and store the region in the array pointed to by pRects. Then, if the texture is needed, call this callback function to inform your application to update the texture region.

D3DRMVALIDATIONCALLBACK was introduced with DirectX version 6.0.

See Also

IDirect3DRMTexture3::SetValidationCallback

D3DRMWRAPCALLBACK

This callback function is not supported.

Syntax

void (*D3DRMWRAPCALLBACK)(
  LPD3DVECTOR lpD3DVector,
  int *lpU,
  int *lpV,
  LPD3DVECTOR lpD3DRMVA,
  LPD3DVECTOR lpD3DRMVB,
  LPVOID lpArg);

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