Функция D3DKMTPresent (d3dkmthk.h)

Статья
08/07/2023

Функция D3DKMTPresent отправляет текущую команду подсистеме ядра графики 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	Произошла ошибка в контексте устройства отрисовки, указанного элементом hContextD3DKMT_PRESENT .

Примечание

Код ошибки STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE не указывает на запуск процесса обнаружения и восстановления времени ожидания (TDR) или на то, что GPU перестал отвечать. Например, подсистема графического ядра DirectX переводит устройство в состояние ошибки, если драйвер мини-порта дисплея указал, что буфер DMA, отправленный с этого устройства, вызвал сбой, или если диспетчеру видеопамяти не удалось перейти на страницу всех выделений, необходимых для буфера DMA, даже после разделения буфера DMA. После того как устройство находится в состоянии ошибки, оно не может выполнять больше никаких операций и должно быть уничтожено и повторно создано. ICD может вызвать функцию D3DKMTGetDeviceState , чтобы определить более точную причину ошибки.

Функция D3DKMTPresent может возвращать STATUS_INVALID_PARAMETER в зависимости от сочетания значений параметров (то есть значений в членах структуры D3DKMT_PRESENT , на которую указывает pData ). В следующем списке описаны наиболее распространенные сочетания значений параметров, которые могут привести к возврату D3DKMTPresent STATUS_INVALID PARAMETER:

Член hDestination имеет значение, отличное от NULL , и выполняется по крайней мере одно из следующих условий:
- Член pSrcSubRects имеет значение NULL.
- Член SubRectCnt равен 0.
- Флаг битового поля Blt элемента Flags не задан.
- Флаг битового поля SrcRectValidфлагов не установлен.
- Установлен флаг битового поля ColorFillфлагов .
- Установлен флаг битового поля Flip, FlipDoNotFlip, FlipDoNotWait или FlipRestartдля флагов .
- Установлен флаг битового поля SrcColorKey или DstColorKeyфлагов .
- Элемент hSource равен hDestination.
- Источник и назначение не являются основной поверхностью.
Флаг битового поля Flip для флагов установлен, и выполняется по крайней мере одно из следующих условий:
- Установлен флаг битового поля ColorFillфлагов .
- Для флага Флаги установлен флаг битового поля Blt.
- Установлен флаг битового поля SrcColorKey или DstColorKeyфлагов .
- Установлен флаг битового поля SrcRectValid или DstRectValidфлагов .
- Для флага Флаги установлен флаг Повернуть битовое поле.
- Установлен флаг битового поля RestrictVidPnSourceфлагов .
- Источник не является основной поверхностью.
- Драйвер мини-порта дисплея не поддерживает интервал переворачивания, заданный элементом FlipInterval .
- Функция D3DKMTSetDisplayMode ранее не вызывалась.
Флаг битового поля ColorFill для флагов установлен, и выполняется одно из следующих условий:
- pSrcSubRects имеет значение NULL.
- SubRectCnt имеет значение 0.
- Для флага Флаги установлен флаг битового поля Blt.
- Установлен флаг битового поля Flip, FlipDoNotFlip, FlipDoNotWait или FlipRestartдля флагов .
- Установлен флаг битового поля SrcColorKey или DstColorKeyфлагов .
- Установлен флаг битового поля SrcRectValidфлага Flags .
Флаг битового поля Blt для флагов установлен, и выполняется одно из следующих условий:
- pSrcSubRects имеет значение NULL.
- SubRectCnt имеет значение 0.
- Установлен флаг битового поля ColorFillфлагов .
- Установлен флаг битового поля Flip, FlipDoNotFlip, FlipDoNotWait или FlipRestartдля флагов .

Графическим драйверам пользовательского режима, которые вызывают D3DKMTPresent для представления в стиле blt, с флагом битового поля Blt для флагов , необходимо соблюдать особую осторожность, чтобы убедиться, что все ранее отправленные работы в контекстах, представляемых из, полностью истощаемы. Сбой может привести к взаимоблокировке самого приложения или, в некоторых угловых случаях, к взаимоблокировке рабочего стола текущего пользователя. Контекст полностью истощается, если он содержит только ожидания для объекта синхронизации GPU, где соответствующий сигнал уже поставлен в очередь в базу данных планировщика GPU и где этот сигнал не находится за другим неудерживаемым ожиданием. Иными словами, если пространство пользователя всех процессов в системе было приостановлено сразу после вызова D3DKMTPresent, ожидание будет удовлетворено, когда зависимая цепочка отрисовки, уже поставленная в очередь в планировщик GPU, завершит отрисовку. Драйвер никогда не должен вызывать blit present в контексте, который зависит от ожидания GPU, которое в настоящее время не удовлетворяется и ожидается, что будет удовлетворено какой-либо последующей операцией, исходящей из этого или другого процесса.

Примеры

В следующем примере кода показано, как 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;
}

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista
Целевая платформа	Универсальное
Верхняя часть	d3dkmthk.h (включая D3dkmthk.h)
Библиотека	Gdi32.lib
DLL	Gdi32.dll

См. также раздел

D3DKMTGetDeviceState

D3DKMTSetDisplayMode

D3DKMT_PRESENT