Bewerken

Delen via


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.

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.

Note   Although user-mode resource handles are always unique for each user-mode resource creation, kernel-mode resource handles are not always unique. When the Direct3D runtime calls the user-mode display driver's OpenResource function to open a view to an existing shared resource, the runtime passes the resource's kernel-mode handle in the hKMResource member of the D3DDDIARG_OPENRESOURCE structure that the pResource parameter points to. The runtime previously created this kernel-mode handle after the runtime called the user-mode display driver's CreateResource function.

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. Note   A kernel-mode resource handle is created only if the user-mode display driver sets the hResource member of D3DDDICB_ALLOCATE to the user-mode runtime resource handle that the driver received from the hResource member of the D3DDDIARG_CREATERESOURCE structure in a call to CreateResource.

  • 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.