D3DKMTPresent 函数 (d3dkmthk.h)

项目
02/26/2024

D3DKMTPresent 函数将 present 命令提交到 Microsoft DirectX 图形内核子系统 (Dxgkrnl.sys) 。

语法

NTSTATUS D3DKMTPresent(
  [in] D3DKMT_PRESENT *unnamedParam1
);

参数

[in] unnamedParam1

pData：指向描述演示参数 的D3DKMT_PRESENT 结构的指针。

返回值

D3DKMTPresent 返回 NTSTATUS 值，例如以下值之一：

返回代码	说明
STATUS_SUCCESS	已成功执行该演示。
STATUS_DEVICE_REMOVED	图形适配器已停止或显示上下文已重置。
STATUS_INVALID_PARAMETER	参数已验证，确定为不正确。
STATUS_NO_MEMORY	由于内存不足，D3DKMTPresent 无法完成。
STATUS_GRAPHICS_ALLOCATION_INVALID	主图柄因显示模式更改而失效。如果 OpenGL 可安装客户端驱动程序 (ICD) 收到此错误代码，则应重新打开或重新创建主句柄，将命令缓冲区中对旧句柄的所有引用替换为新句柄，然后重新提交缓冲区。
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	D3DKMT_PRESENT 的 hContext 成员指定的呈现设备上下文中发生错误。

注意

STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE错误代码不指示启动超时检测和恢复 (TDR) 进程，也不指示 GPU 已停止响应。例如，如果显示微型端口驱动程序指示从此设备提交的 DMA 缓冲区导致故障，或者视频内存管理器即使在拆分 DMA 缓冲区之后也无法分页输入 DMA 缓冲区所需的所有分配，则 DirectX 图形内核子系统会将设备置于错误状态。设备处于错误状态后，无法再执行任何操作，必须销毁并重新创建。 ICD 可以调用 D3DKMTGetDeviceState 函数来确定错误原因的更精确。

注解

D3DKMTPresent 函数可能会返回STATUS_INVALID_PARAMETER，具体取决于参数值 (即 pData 指向 ) 的 D3DKMT_PRESENT 结构成员中的值的组合。以下列表描述了可能导致 D3DKMTPresent 返回STATUS_INVALID PARAMETER 的参数值的最常见组合：

hDestination 成员为非 NULL，并且至少满足以下条件之一：
- pSrcSubRects 成员为 NULL。
- SubRectCnt 成员为 0。
- 未设置 Flags 成员的 Blt 位字段标志。
- 未设置 Flags 的 SrcRectValid 位字段标志。
- 设置了 Flags 的 ColorFill 位字段标志。
- 设置了 Flags 的 Flip、FlipDoNotFlip、FlipDoNotWait 或 FlipRestart 位字段标志。
- 设置了标志的 SrcColorKey 或 DstColorKey 位字段标志。
- hSource 成员等于 hDestination。
- 源和目标不是主要图面。
设置了 Flags 的 Flip 位字段标志，并且至少满足以下条件之一：
- 设置了 Flags 的 ColorFill 位字段标志。
- 设置了 Flags 的 Blt 位字段标志。
- 设置了标志的 SrcColorKey 或 DstColorKey 位字段标志。
- 设置了标志的 SrcRectValid 或 DstRectValid 位字段标志。
- 设置了 Flags 的 Rotate 位字段标志。
- 设置了 Flags 的 RestrictVidPnSource 位字段标志。
- 源不是主图面。
- 显示微型端口驱动程序不支持 FlipInterval 成员指定的翻转间隔。
- 以前未调用 D3DKMTSetDisplayMode 函数。
设置了 Flags 的 ColorFill 位字段标志，并且以下条件之一为 true：
- pSrcSubRects 为 NULL。
- SubRectCnt 为 0。
- 设置了 Flags 的 Blt 位字段标志。
- 设置了 Flags 的 Flip、FlipDoNotFlip、FlipDoNotWait 或 FlipRestart 位字段标志。
- 设置了标志的 SrcColorKey 或 DstColorKey 位字段标志。
- 设置了 Flags 的 SrcRectValid 位字段标志。
设置了 Flags 的 Blt 位字段标志，并且满足以下条件之一：
- pSrcSubRects 为 NULL。
- SubRectCnt 为 0。
- 设置了 Flags 的 ColorFill 位字段标志。
- 设置了 Flags 的 Flip、FlipDoNotFlip、FlipDoNotWait 或 FlipRestart 位字段标志。

调用 D3DKMTPresent 以呈现 blit 样式的用户模式图形驱动程序（设置了“标志”的 Blt 位字段标志）需要格外小心，以确保以前提交到上下文 () 提供的所有工作都是完全可排出的。如果不这样做，可能会导致应用程序本身死锁，或在某些情况下，导致当前用户桌面死锁。如果上下文仅包含 GPU 同步对象上的等待，其中相应的信号已排队到 GPU 计划程序数据库，并且该信号本身不在另一个不可减少的等待之后，则上下文是完全可排出的。换句话说，如果在调用 D3DKMTPresent 后立即暂停系统中所有进程的用户空间，则一旦已排队到 GPU 计划程序的依赖呈现链完成呈现，等待就会得到满足。驱动程序不得在依赖于 GPU 等待的上下文中调用存在的 blit，该上下文当前不满足，并且预期会由源自此或其他进程的某些后续操作满足。

示例

下面的代码示例演示 OpenGL ICD 如何使用 D3DKMTPresent 来呈现数据。

HRESULT Present(D3DKMT_HANDLE hDevice, 
                HWND hWnd, 
                RECT* pSrcRect,
                 RECT* pDstRect)
{
    D3DKMT_PRESENT PresentData = {0};

    PresentData.hDevice = hDevice;
    PresentData.Flags.Blt = 
    PresentData.Flags.DstRectValid = 
    PresentData.Flags.SrcRectValid = TRUE;
    PresentData.hWindow = hWnd;
    PresentData.DstRect = *pDstRect;
    PresentData.SrcRect = *pSrcRect;
    PresentData.SubRectCnt = 1;  
    PresentData.pSrcSubRects = pSrcRect; 

    if (NT_SUCCESS((*pfnKTPresent)(&PresentData))) {
        return S_OK;
    }
    return E_FAIL;
}