QueryResourceResidencyDXGI callback function

The QueryResourceResidencyDXGI function determines the residency of the given list of resources.

Syntax


pfnQueryResourceResidency QueryResourceResidencyDXGI;

HRESULT __stdcall* QueryResourceResidencyDXGI(
   DXGI_DDI_ARG_QUERYRESOURCERESIDENCY *pResidencyData
)
{ ... }

Parameters

pResidencyData

[in] A pointer to a DXGI_DDI_ARG_QUERYRESOURCERESIDENCY structure that describes a list of resources that residency is verified on.

Return value

QueryResourceResidencyDXGI returns one of the following values:

Return codeDescription
S_OK

All of the resources are in GPU-accessible memory.

D3DDDIERR_DEVICEREMOVED

The driver detected that the graphics adapter was removed. Therefore, the driver did not complete the operation. If the driver never notices the adapter-removal condition, the driver is not required to return this error code.

S_RESIDENT_IN_SHARED_MEMORY

No allocations that comprise the resources are on disk. However, at least one allocation is not in GPU-accessible memory.

S_NOT_RESIDENT

At least one allocation that comprises the resources is on disk.

E_INVALIDARG

Parameters were validated and determined to be incorrect.

E_OUTOFMEMORY

QueryResourceResidencyDXGI could not allocate memory that is required for it to complete.

 

Remarks

The Microsoft Direct3D runtime calls the user-mode display driver's QueryResourceResidencyDXGI function for applications to determine if the operating system will incur a significant stall at draw time if the system must make resources GPU-accessible. The information that is returned from QueryResourceResidencyDXGI is an approximation of the residency of resources because the resources might become demoted before applications use the resources.

QueryResourceResidencyDXGI must call the pfnQueryResidencyCb function. pfnQueryResidencyCb returns the residency status of a resource in the elements of the array that is specified by the pResidencyStatus member of the D3DDDICB_QUERYRESIDENCY structure. If pfnQueryResidencyCb returns D3DDDI_RESIDENCYSTATUS_NOTRESIDENT for any query, QueryResourceResidencyDXGI must return S_NOT_RESIDENT. If pfnQueryResidencyCb returns D3DDDI_RESIDENCYSTATUS_RESIDENTINSHAREDMEMORY for any query and does not return D3DDDI_RESIDENCYSTATUS_NOTRESIDENT for any query, QueryResourceResidencyDXGI must return S_RESIDENT_IN_SHARED_MEMORY. QueryResourceResidencyDXGI must return S_OK only if all calls to pfnQueryResidencyCb for all queries return D3DDDI_RESIDENCYSTATUS_RESIDENTINGPUMEMORY.

For each resource that the runtime queries through a call to QueryResourceResidencyDXGI, the user-mode display driver must determine which allocations that belong to the resource to query through a call to pfnQueryResidencyCb. For a resource that owns a single allocation, the determination is simple--the driver will query that allocation. However, if a resource owns multiple allocations, the determination is more difficult. The driver must determine which allocations that an application will likely use for rendering, and the driver must query only those allocations. For example, if a resource owns an allocation that is used for rendering and a scratch allocation that handles a lock operation, the driver should query only for the residency of the first allocation, because an application will most likely not use the second allocation for rendering.

Note   Because the runtime does not support residency-querying of system memory resources, the runtime will always fail requests from applications for the residency status of system memory resources and will never call the user-mode display driver's QueryResourceResidencyDXGI function for these system memory resources.
 

Requirements

Target platform

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Dxgiddi.h (include D3d10umddi.h)

See also

DXGI_DDI_ARG_QUERYRESOURCERESIDENCY
pfnQueryResidencyCb

 

 

Send comments about this topic to Microsoft

Show: