Callback Functions

The Microsoft® Direct3D® Retained Mode callback functions are:

• D3DRMDEVICEPALETTECALLBACK
• D3DRMFRAMEMOVECALLBACK
• D3DRMLOADCALLBACK
• D3DRMLOADTEXTURECALLBACK
• D3DRMOBJECTCALLBACK
• D3DRMUPDATECALLBACK
• D3DRMUSERVISUALCALLBACK
• D3DRMWRAPCALLBACK

---

D3DRMDEVICEPALETTECALLBACK

Enumerates palette entries. This callback function is application-defined.

void (
  *D3DRMDEVICEPALETTECALLBACK
  )
(
  LPDIRECT3DRMDEVICE lpDirect3DRMDev,
  LPVOID lpArg,
  DWORD dwIndex,
  LONG red,
  LONG green,
  LONG blue
  );

Parameters

lpDirect3DRMDev

Address of the IDirect3DRMDevice interface for this device.

lpArg

Address of application-defined data passed to this callback function.

dwIndex

Index of the palette entry being described.

red, green, and blue

Red, green, and blue components of the color at the given index in the palette.

Return Values

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.

---

D3DRMFRAMEMOVECALLBACK

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.

void (
  *D3DRMFRAMEMOVECALLBACK
  )(
  LPDIRECT3DRMFRAME lpD3DRMFrame,
  LPVOID lpArg,
  D3DVALUE delta
  );

Parameters

lpD3DRMFrame

Address of the Direct3DRMFrame object that is being moved.

lpArg

Address of 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 Values

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 IDirect3DRMFrame::AddMoveCallback and IDirect3DRMFrame::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.

---

D3DRMLOADCALLBACK

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

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

Parameters

lpObject

Address of the Direct3DRMObject being loaded.

ObjectGuid

Globally unique identifier (GUID) of the object being loaded.

lpArg

Address of application-defined data passed to this callback function.

Return Values

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

IDirect3DRM::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.

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

Parameters

tex_name

Address of a string containing the name of the texture.

lpArg

Address of application-specific data.

lpD3DRMTex

Address of the Direct3DRMTexture object.

Return Values

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

Remarks

Applications can use this callback function to implement support for textures that are not in the Microsoft® Windows® bitmap (.bmp) or Portable Pixmap (.ppm) P6 format.

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

IDirect3DRM::Load, IDirect3DRMAnimationSet::Load, IDirect3DRMFrame::Load, IDirect3DRMMeshBuilder::Load

---

D3DRMOBJECTCALLBACK

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

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

Parameters

lpD3DRMobj

Address of an IDirect3DRMObject interface for the object being enumerated. The application must use the Release method for each enumerated object.

lpArg

Address of application-defined data passed to this callback function.

Return Values

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

IDirect3DRM::EnumerateObjects

---

D3DRMUPDATECALLBACK

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

void (
  *D3DRMUPDATECALLBACK
  )(
  LPDIRECT3DRMDEVICE lpobj,
  LPVOID lpArg,
  int iRectCount,
  LPD3DRECT d3dRectUpdate
  );

Parameters

lpobj

Address of the Direct3DRMDevice object to which this callback function applies.

lpArg

Address of 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 Values

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

IDirect3DRMDevice::AddUpdateCallback, IDirect3DRMDevice::DeleteUpdateCallback, IDirect3DRMDevice::Update

---

D3DRMUSERVISUALCALLBACK

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

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

Parameters

lpD3DRMUV

Address of the Direct3DRMUserVisual object.

lpArg

Address of 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 Direct3DRMDevice object used to render the Direct3DRMUserVisual object.

lpD3DRMview

Address of a Direct3DRMViewport object used to determine whether the Direct3DRMUserVisual object is visible.

Return Values

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

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

---

D3DRMWRAPCALLBACK

This callback function is not supported.

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

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page