The Microsoft® Direct3D® Retained Mode callback functions for C++ are:
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
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
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.
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
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
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
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
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
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
This callback function is not supported.
Syntax
void (*D3DRMWRAPCALLBACK)( LPD3DVECTOR lpD3DVector, int *lpU, int *lpV, LPD3DVECTOR lpD3DRMVA, LPD3DVECTOR lpD3DRMVB, LPVOID lpArg);
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.