The pfnSetPriorityCb function sets the priority level of a resource or list of allocations.



__checkReturn HRESULT APIENTRY CALLBACK pfnSetPriorityCb(
  _In_ HANDLE               hDevice,
{ ... }


hDevice [in]

A handle to the display device (graphics context).

pData [in]

A pointer to a D3DDDICB_SETPRIORITY structure that describes the priority level to set a resource or list of allocations to.

Return value

pfnSetPriorityCb returns one of the following values:

Return codeDescription

The priority level was successfully set.


Parameters were validated and determined to be incorrect.


This function might also return other HRESULT values.


The user-mode display driver can call the pfnSetPriorityCb function to set the priority of the underlying resource or list of allocations. If the priority level of a resource is set, all of the allocations that belong to the resource are set to the specified priority level. Typically, the user-mode display driver sets the priority of a resource or list of allocations after the Microsoft Direct3D runtime calls the user-mode display driver's SetPriority or SetResourcePriorityDXGI function to set the eviction-from-memory priority for a resource. However, the user-mode display driver can set the priority of allocations at any time.

After an application requests to set the priority level of a surface, the user-mode display driver should set the appropriate resource or list of allocations to the priority level that is specified by the application.

Note   Priority levels are only a hint to the video memory manager; they can be ignored by the memory manager under various conditions.

An allocation priority defines both the likelihood that the allocation remains resident and the likelihood of how hard the video memory manager will try to respect the driver's preference for the placement of the allocation. The following priority levels are defined in the D3dukmdt.h header file:


Marks the allocation as unused and for eviction immediately. The allocation should be evicted as soon as another allocation requires the resource that the allocation occupies.

If an allocation will not be used for a while, the driver marks the allocation as unused at the soonest opportunity. Note that changing allocation priority is not a queued operation; that is, the change is effective immediately. Changing the priority of an allocation that has a queued reference can cause the video memory manager to evict the allocation, then bring the allocation back, and then evict the allocation again.


Marks the priority of the allocation as low.

The placement of the allocation is not critical, and the video memory manager performs minimal work to find a location for the allocation. For example, if a GPU can render with a vertex buffer from either local or non-local memory with little difference in performance, the driver should mark that vertex buffer as low priority. Marking the buffer as low priority allows other more critical allocations (for example, allocations for a render target or texture) to occupy the faster memory.


Marks the priority of the allocation as normal.

The placement of the allocation is important, but not critical, for performance. The video memory manager should try to place the allocation that is marked as normal in the allocation's preferred location instead of a low-priority allocation.

Typically, textures are marked as normal.


Marks the priority of the allocation as high.

The placement of the allocation is critical for performance. The video memory manager should try to place the allocation that is marked as high in the allocation's preferred location instead of a low-priority or normal-priority allocation.

Typically, render targets are marked as high.

Beginning with Windows 8, when the DxgkCbCreateContextAllocation function is called, the Microsoft DirectX graphics subsystem sets this allocation priority value.


Marks the priority of the allocation as soft-pinned. A soft-pinned allocation is evicted from memory only if there is no other way of resolving the memory requirement of a DMA buffer. The video memory manager attempts to split a DMA buffer to its minimum size and evict all other nonpinned and non soft-pinned allocations before evicting a soft-pinned allocation. This level of priority should be used only for applications that require no errors.

The driver can use priority levels other than the preceding defined values when appropriate. For example, marking an allocation with a priority level of 0x78000001 indicates that the allocation is slightly above normal.


The following code example shows how to set priority level.

    DWORD  dwSurfaceHandle = (DWORD)(DWORD_PTR)pSetPriority->hResource;
    CResource   &res = m_RTbl[dwSurfaceHandle];
    UINT                    priority;

    priority = pSetPriority->Priority;

    memset(&setPri, 0, sizeof(setPri));

    setPri.hResource   = res.m_hResRuntime;
    setPri.pPriorities = &priority;

    return (m_d3dCallbacks.pfnSetPriorityCb(m_hD3D, &setPri));


Target platform



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


D3dumddi.h (include D3dumddi.h)

See also




Send comments about this topic to Microsoft