Called by a Windows Display Driver Model (WDDM) 1.2 or later display miniport driver to allocate a GPU context or device-specific context.



NTSTATUS APIENTRY CALLBACK* DxgkCbCreateContextAllocation(
{ ... }


ContextAllocation [in, out]

A pointer to a DXGKARGCB_CREATECONTEXTALLOCATION structure that specifies the attributes of the context to be allocated.

Return value

DxgkCbCreateContextAllocation returns STATUS_SUCCESS if it succeeds. Otherwise, it returns one of the error codes defined in Ntstatus.h.


Starting with WDDM 1.2, display miniport drivers can allocate a GPU-specific context (GPU context allocation) or a device-specific context (device context allocation).

A GPU context allocation allows GPUs to store context state from DMA buffers that are preempted in the middle of their execution. Drivers create allocations associated with a GPU context to save its state when it is necessary. The operating system ensures that the context allocation is resident before a command from this context is placed in the GPU's hardware execution queue. The context will stay resident until a command from another context is placed in the hardware execution queue.

In addition, the operating system supports lazy GPU context switching by assuming that hardware context state is retained on the GPU after completing a command that belongs to the context. In this way, contexts are only switched on the GPU when a command from a different context is submitted to the hardware queue.

GPU context allocations

GPU context allocations can only be made for non-system contexts. The display miniport driver creates these contexts by calling DxgkDdiCreateContext. To create a non-system context, the driver sets the SystemContext member of a DXGK_CREATECONTEXTFLAGS structure to zero, and passes a pointer to this structure in the pCreateContext parameter.

A device context allocation follows a similar model, except that it will remain resident for any context that belongs to the device that it’s associated with. This model allows drivers to use GPU context allocations for storing GPU context save area (CSA) data and to use device context allocations for storing page table data.

Device context allocations

Device context allocations can only be made for non-system devices. The display miniport driver creates these devices by calling DxgkDdiCreateDevice. To create a non-system device, the driver sets the Flags.SystemDevice member of a DXGK_CREATEDEVICEFLAGS structure to zero, and passes a pointer to this structure in the pCreateDevice parameter.

The display miniport driver calls DxgkCbDestroyContextAllocation to free the context resources that were allocated through DxgkCbCreateContextAllocation.

Virtual addresses for destination context allocations

To ensure that the operating system sets a valid (non-NULL) virtual address for the destination context allocation (InitContextResource->Destination->VirtualAddress member of the DXGKARG_BUILDPAGINGBUFFER structure), when the display miniport driver calls DxgkCbCreateContextAllocation it must:


Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Target platform



D3dkmddi.h (include D3dkmddi.h)



See also




Send comments about this topic to Microsoft