DXGKDDI_PRESENT callback function

DXGKDDI_PRESENT callback function

该DDI将source allocation的内容拷贝到primary surface(有时是拷贝到off-screen system memory allocation)

Syntax

DXGKDDI_PRESENT DxgkddiPresent;

NTSTATUS DxgkddiPresent(
  IN_CONST_HANDLE hContext,
  INOUT_PDXGKARG_PRESENT pPresent
)
{...}

Parameters

hContext

[in] 需要拷贝信息所在的device context的句柄。KMD在之前调用的DxgkDdiCreateContext的 DXGKARG_CREATECONTEXT结构的参数 pCreateContext 成员 hContext 中返回此句柄。

如果驱动不支持创建context，DXGK将用device的句柄替换context的句柄。KMD在之前调用的DxgkDdiCreateContext的 DXGKARG_CREATECONTEXT结构的参数 pCreateContext 成员 hDevice 中返回此句柄。

pPresent

[in/out] 指向 DXGKARG_PRESENT 的指针，该结构包含该copy操作的信息。

Return Value

DxgkDdiPresent returns one of the following values:

Return code	Description
STATUS_SUCCESS	DxgkDdiPresent successfully copied the content.
STATUS_NO_MEMORY or STATUS_INSUFFICIENT_RESOURCES	DxgkDdiPresent could not allocate memory that was required for it to complete.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	The current direct memory access (DMA) buffer is depleted.
STATUS_GRAPHICS_CANNOTCOLORCONVERT	The display miniport driver detected a bit-block transfer (bitblt) for color conversion that the device could not perform. The Microsoft Direct3D runtime prevents the application from continuing, and the application receives a failure to copy content.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiPresent detected nonprivileged instructions (that is, instructions that access memory beyond the privilege of the current central processing unit [CPU] process).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiPresent detected instructions that graphics hardware cannot support.
STATUS_INVALID_HANDLE	DxgkDdiPresent detected an invalid handle in the command buffer.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	The display miniport driver detected an error in the DMA stream. The graphics context device is placed in a lost state if the driver returns this error code.

Remarks

DXGK调用KMD的 DxgkDdiPresent 将内容数据从source allocation 拷贝到 primary surface 中。(改函数同样能拷贝到 off-screen system memory allocation中)

因为 primary surface 中内容定义是并不严格，所以 DxgkDdiPresent 的实现必须能够满足下列场景。

• 根据窗口所在的位置不同，DxgkDdiPresent 必须能在不同的 primary 之间执行操作，这些 primary 可能在同一个显卡上，也可能在不同的显卡上。
• primary 显示在远端monitor上并且通过终端服务客户端或者Microsoft NetMeeting进行访问。
• 刚切换过mode并且primary格式不同于source 格式，因此需要颜色转换。另外，因为window的clipping和ordering， DxgkDdiPresent需要能 clip，

因为以上场景能的变化是异步的，UMD不能在调用DxgkDdiPresent时预先编译好硬件指令。KMD必须在实际调用DxgkDdiPresent中创建硬件command，并且必须将这些硬件command放在 output DMA buffer中。在KMD的DxgkDdiPresent被调用生成DMA buffer之后，OS保证这个buffer被渲染之前不会发生场景变化。

KMD不需要知道之前的场景的细节，只要驱动支持下面的抽象：

• 从Video memory source拷贝到primary video 或 system memory 中，从off-screen system memory source拷贝到primary，从primary拷贝到primary，或者从primary source拷贝到off-screen system memory。以上操作中源通过DxgkDdiPresent 中参数类型为DXGKARG_PRESENT的pPresent成员pAllocationList[DXGK_PRESENT_SOURCE_INDEX]数组中的成员hDeviceSpecificAllocation 来指定。目标则是则可以是device 当前的 primary或者是一个off-screen system memory allocation，其在DXGKARG_PRESENT的pPresent成员pAllocationList[DXGK_PRESENT_DESTINATION_INDEX]数组中的成员hDeviceSpecificAllocation 来指定。如果目标就是源为同一对象，测拷贝操作就是 screen-to-screen bit-block 传输操作(bitblt)。因此DXGK可以设置源和目标为下列值：
  • destination != NULL (that is, destination == nonNULL)
  • source != NULL (that is, source == nonNULL)
• 从video memory中的当前allocation flip 到另一个allocation中时，OS通过DXGKARG_PRESENT的pPresent成员pAllocationList[DXGK_PRESENT_SOURCE_INDEX]数组中的成员hDeviceSpecificAllocation指定源。DXGK可以设置为一下值：
  • destination == NULL
  • source != NULL (that is, source == nonNULL)

•  

  Note no-op flip可以操作可以是同一个当前正在扫描的allocation。no-op flip被用来向渲染流中queue中插入一个等待vertical blank的操作。KMD应该插入一个应该的flip 命令，如同flip到另一个allocation一样。

   

• 在向primary suface填充颜色的操作中，不需要有source allocation，并且目标primary allocation句柄由pAllocationList[DXGK_PRESENT_DESTINATION_INDEX]数组中的成员hDeviceSpecificAllocation指定。DXGKARG_PRESENT 成员Color通常为为D3DDDIFORMAT枚举中的D3DDDIFMT_A8R8G8B8。但是，当primary format为palettized RGB时，Color包含的是palette的index。因此，DXGK可以设置源和目标为下列值：
  • destination != NULL (that is, destination == nonNULL)
  • source == NULL

为了所有DxgkDdiPresent 场景下能正常操作, KMD的DxgkDdiCreateDevice应该设置DXGK_DEVICEINFO成员DmaBufferSize足够大，从而能包含present至少一个矩形到显示器或者off-screen目标的硬件命令。但是DxgkDdiPresent中子矩形数量耗尽了当前的DMA buffer从而需要另外一个DMA buffer来继续执行的时候，KMD的DxgkDdiPresent能返回STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER。

当DXGK要求获得一个新的DMA buffer并且调用KMD的DxgkDdiPresent时传的RECT list参数与之前调用的一样。驱动必须使用DXGKARG_PRESENT结构MultipassOffset 成员来记录之前调用DxgkDdiPresent所完成的RECT list数量，这样KMD就在新的DMA buffer中从未执行的RECT开始继续执行拷贝。当KMD的DxgkDdiPresent完成所有RECT list，则返回STATUS_SUCCESS。

另外，对于产生一个DMA buffer，KMD需要产生一个patch-location list，其指定DMA buffer中的不同位移，这些位移会在allocation的物理地址被知道之后用于patch。有时 VMM会在allocation list中提供pre-patch信息。

当VMM提供了这些信息，驱动必须通过确定这些最终的物理地址来生成DMA buffer，这些地址由DXGK提供。之后DXGK可能并再不为DMA buffer调用DxgkDdiPatch做patch。因此，驱动必须使用pre-patch信息来适当生成DMA buffer。当DXGKARG_PRESENT数组pAllocationList 的第N个元素的SegmentId成员非零时，pre-patch信息对应元素N。

Note 即便驱动的DxgkDdiPresent能pre-patch DMA buffer，驱动也必须插入所有的allocation引用到 output patch-location list中，该list在DXGKARG_PRESENT的pPatchLocationListOut 成员中指定。因为这些allocation的地址可能在DMA buffer被提交到GPU之前被改变，所以驱动必须插入这些引用。因此，DXGK将调用DxgkDdiPatch来重新repatch这些DMA buffer。

如果驱动支持旋转时(该特性的支持在调用DxgkDdiEnumVidPnCofuncModality时由D3DKMDT_VIDPN_PRESENT_PATH_TRANSFORMATION的RotationSupport指定)，驱动必须能执行旋转的bit-block传输。当DXGKARG_PRESENT的DXGK_PRESENTFLAGS类型Flags 成员指定为Rotate 时，驱动应该应用旋转，类似从一个非旋转的surface拷贝到最终方向的当前source。

一个 source 的 primary allocation 在DxgkDdiCommitVidPn中指定。如果一个给定source产生了多条path（例如clone模式），KMD必须保证对于给定路径中不同的target的不同旋转模式的output能被正确旋转。DxgkDdiPrenset中所有参数都是和旋转无关的。source和target的矩形能都为用户能够看到的整个屏幕(例如, 768 x 1024)。

Note   这种情况不能处理旋转模式下的全屏Direct3D应用程序

如果预先由KMD的DxgkDdiQueryAdapterInfo指定了显卡支持MMIO-based flip(Memory mapped I/O)，由DXGK_DRIVERCAPS成员FlipCaps 中的bit位设置为FlipOnVSyncMmIo指定，驱动的DxgkDdiPresent随后被调用，其中DXGKARG_PRESENT的成员pDmaBuffer设置为NULL，因为MMIO-based flip不需要DMA buffer在GPU上执行。相应的KMD的DxgkDdiPresent必须按要求validate source surface和program flip硬件。DXGK调用DxgkDdiSetVidPnSourceAddress来进行此类flip。

DxgkDdiPresent should be made pageable.

Requirements

Minimum supported client	Available in Windows Vista and later versions of the Windows operating systems.
Target Platform	Desktop
Header	d3dkmddi.h
IRQL	PASSIVE_LEVEL