PFND3DDDI_PRESENT callback function (d3dumddi.h)

Article
04/01/2021

The Present function notifies the user-mode display driver that an application finished rendering and requests that the driver display the source surface by either copying or flipping or that the driver perform a color-fill operation.

Syntax

PFND3DDDI_PRESENT Pfnd3dddiPresent;

HRESULT Pfnd3dddiPresent(
  HANDLE hDevice,
  const D3DDDIARG_PRESENT *unnamedParam2
)
{...}

Parameters

hDevice

A handle to the display device (graphics context).

unnamedParam2

pData [in]

A pointer to a D3DDDIARG_PRESENT structure that describes the resource to display.

Return value

Present returns one of the following values:

Return code	Description
S_OK	The resource is successfully displayed.
E_OUTOFMEMORY	Present could not allocate the required memory for it to complete.

Remarks

The Microsoft Direct3D runtime calls the user-mode display driver's Present function to notify the user-mode display driver that an application finished rendering and to request that the driver display out the source surface or that the driver perform a color-fill operation. If the hSrcResource member of the D3DDDIARG_PRESENT structure that the pData parameter points to is non-NULL, Present requests that the user-mode display driver display new content to the screen; if hSrcResource is NULL, Present requests that the user-mode display driver perform a color-fill operation to the screen.

If the hDstResource member of the D3DDDIARG_PRESENT structure is NULL, the destination surface is unknown. In addition, the destination surface and a list of clipping rectangles are determined in kernel mode before sending the hardware command stream through DMA to the graphics processor.

As a result, the user-mode display driver cannot generate hardware instructions to perform the present operation. These hardware instructions must be generated by the display miniport driver. However, when the hSrcResource member of D3DDDIARG_PRESENT is non-NULL, the user-mode display driver must derive the allocation handle to the source surface and insert this handle in the hSrcAllocation member of the D3DDDICB_PRESENT structure in a call to the pfnPresentCb function. The display miniport driver can then successfully generate the hardware instructions. The user-mode display driver typically derives the allocation handle from the resource information in the D3DDDIARG_PRESENT structure.

If the hDstResource member of D3DDDIARG_PRESENT is non-NULL, the destination surface for the present is known and the user-mode display driver must fill in the hDstAllocation member of D3DDDICB_PRESENT with the corresponding allocation handle.

If a user-mode display driver exposes a DDI version of less than 0x0000000C (the driver returns this value in the DriverVersion member of the D3D10DDIARG_OPENADAPTER structure in a call to the driver's OpenAdapter function), the Direct3D runtime first calls the user-mode display driver's Flush function to submit any outstanding hardware commands in the command buffer before the runtime calls the user-mode display driver's Present function. In this way, the user-mode display driver's Present function is serialized with render operations (that is, calls to the pfnRenderCb function). If a user-mode display driver exposes a DDI version of 0x0000000C or greater and the calling application runs in windowed mode, the runtime also calls Flush before it calls Present. If a user-mode display driver exposes a DDI version of 0x0000000C or greater and the calling application runs in full-screen mode, the runtime will not call Flush before it calls Present. This behavior allows drivers that implement their own threading to queue present calls. A driver that exposes a DDI version of 0x0000000C or greater must call pfnRenderCb to internally flush any outstanding command buffers before the driver calls the pfnPresentCb function.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later versions of the Windows operating systems.
Target Platform	Desktop
Header	d3dumddi.h (include D3dumddi.h)