The SetDisplayMode function switches to a display mode or primary that is not supported by the GDI desktop.



__checkReturn HRESULT APIENTRY SetDisplayMode(
  _In_       HANDLE                   hDevice,
{ ... }


hDevice [in]

A handle to the display device (graphics context).

pData [in]

A pointer to a D3DDDIARG_SETDISPLAYMODE structure that specifies parameters for setting the display mode.

Return value

SetDisplayMode returns S_OK or an appropriate error result if the display mode is not successfully set.


The Microsoft Direct3D runtime calls SetDisplayMode to switch to a display mode or primary that is not supported by the GDI desktop. The following list describes examples of such primaries:

  • Primaries that are created with 10-bits-per-channel (10:10:10:2) display and render target formats (for example, D3DFMT_A2R10G10B10)

  • Multiple-sampled primaries where the multiple-sampling is performed while scanning-out

  • Persistent primaries that are used by full-screen Microsoft DirectX version 9.L applications

The Direct3D runtime calls the user-mode display driver's CreateResource function to create the primary to be scanned out. However, the driver should program the hardware to scan out only when its SetDisplayMode function is called. Therefore, the runtime sets the hResource and SubResourceIndex members of the D3DDDIARG_SETDISPLAYMODE structure that is pointed to by the pData parameter to the primary that was created through the call to the driver's CreateResource function. The driver should then translate the primary that is represented by hResource and SubResourceIndex to a primary allocation handle. After the driver makes this translation, the driver should pass the resulting handle in a call to the pfnSetDisplayModeCb function, which then initiates a call to the display miniport driver's DxgkDdiCommitVidPn function.

The user-mode display driver can set the hPrimaryAllocation member of the D3DDDICB_SETDISPLAYMODE structure in the call to pfnSetDisplayModeCb to scan out any allocation. However, the allocation must be marked as a primary (that is, the user-mode display driver must have set the Primary bit-field flag in the Flags member of the D3DDDI_ALLOCATIONINFO structure in a call to the pfnAllocateCb function to create the allocation).


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