## 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
);

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