Handling Resource Creation and Destruction
To enable the Microsoft DirectX graphics kernel subsystem to properly track resource lifetime and to prevent memory leaks in the operating system, the user-mode display driver must properly create and destroy resources.
The Microsoft Direct3D runtime calls the following user-mode display driver functions to create user-mode resources.
CreateResource creates a new shared or unshared resource.
OpenResource opens a view to an existing shared resource.
In both calls, the Direct3D runtime passes a unique user-mode runtime resource handle that the user-mode display driver uses to call back into the runtime. When CreateResource or OpenResource returns successfully, the user-mode display driver returns a unique user-mode handle that represents the resource. This handle is the user-mode driver resource handle. The runtime uses the user-mode driver resource handle in subsequent driver calls.
A one-to-one correspondence exists between the user-mode runtime resource handle and the user-mode driver resource handle. The Direct3D runtime and the user-mode display driver exchange the user-mode runtime and driver resource handles through the hResource members of the D3DDDIARG_CREATERESOURCE and D3DDDIARG_OPENRESOURCE structures.
When the user-mode display driver calls the Direct3D runtime's pfnAllocateCb function to create allocations for a user-mode resource, the driver should specify the user-mode runtime resource handle in the hResource member of the D3DDDICB_ALLOCATE structure that the pData parameter points to. The Direct3D runtime generates a unique kernel-mode handle to the resource and passes it back to the user-mode display driver in the hKMResource member of D3DDDICB_ALLOCATE. The user-mode display driver can insert the kernel-mode resource handle in the command stream for the display miniport driver to use later.
To destroy a user-mode resource that CreateResource or OpenResource created, the Direct3D runtime passes the user-mode driver resource handle in the hResource parameter in a call to the user-mode display driver's DestroyResource function. To release the kernel-mode resource handle and all of the allocations that are associated with the user-mode resource, the user-mode display driver passes the user-mode runtime resource handle in the hResource member of the D3DDDICB_DEALLOCATE structure that the pData parameter points to in a call to the pfnDeallocateCb function.
Consider the following items when a user-mode display driver creates and destroys resources:
For allocations that the user-mode display driver creates in response to shared resources (that is, in response to CreateResource calls with the SharedResource bit-field flag set in the Flags member of D3DDDIARG_CREATERESOURCE), the driver must assign a non-NULL value to the hResource member of D3DDDICB_ALLOCATE.
- For allocations that the user-mode display driver creates in response to non-shared resources, the driver is not required to assign a non-NULL value to the hResource member of D3DDDICB_ALLOCATE. If the driver assigns NULL to hResource, the allocations are associated with the device and not a particular resource (and kernel-mode resource handle). However, if allocations are truly related to a resource, the driver should associate the allocations with that resource.
When DestroyResource is called to destroy a non-shared user-mode resource, the user-mode display driver can call pfnDeallocateCb with the hResource member of D3DDDICB_DEALLOCATE set to NULL only if the driver never associated any allocations with the resource. If the user-mode display driver associated allocations with the resource, the driver must call pfnDeallocateCb with the hResource member of D3DDDICB_DEALLOCATE set to a non-NULL value; otherwise, a memory leak will occur.