функция обратного вызова DXGKDDI_PRESENT (d3dkmddi.h)

Статья
03/08/2023

Функция DxgkDdiPresent копирует содержимое из исходных выделений на основную поверхность (а иногда и на выделение памяти вне экрана).

Синтаксис

DXGKDDI_PRESENT DxgkddiPresent;

NTSTATUS DxgkddiPresent(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_PRESENT pPresent
)
{...}

Параметры

[in] hContext

Дескриптор контекста устройства для сведений о копировании. Функция DxgkDdiCreateContext драйвера miniport для отображения ранее возвращала этот дескриптор в элементе hContextструктуры DXGKARG_CREATECONTEXT , на которую указывает параметр pCreateContextобъекта DxgkDdiCreateContext .

Если драйвер не поддерживает создание контекста, подсистема ядра графики Microsoft DirectX заменяет дескриптор контекста дескриптором для устройства. Функция DxgkDdiCreateDevice драйвера дисплея miniport ранее возвращала дескриптор устройства в элементе hDeviceструктуры DXGKARG_CREATEDEVICE , на которую указывает параметр pCreateDeviceобъекта DxgkDdiCreateDevice .

[in/out] pPresent

Указатель на структуру DXGKARG_PRESENT , содержащую сведения об операции копирования.

Возвращаемое значение

DxgkDdiPresent возвращает одно из следующих значений:

Код возврата	Описание
STATUS_SUCCESS	DxgkDdiPresent успешно скопировал содержимое.
STATUS_NO_MEMORY или STATUS_INSUFFICIENT_RESOURCES	DxgkDdiPresent не удалось выделить память, необходимую для ее завершения.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	Текущий буфер прямого доступа к памяти (DMA) исчерпан.
STATUS_GRAPHICS_CANNOTCOLORCONVERT	Драйвер мини-порта дисплея обнаружил передачу битового блока (bitblt) для преобразования цвета, которое устройство не может выполнить. Среда выполнения Microsoft Direct3D не позволяет продолжить работу приложения, и приложение получает сбой при копировании содержимого.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiPresent обнаружил непривилегированные инструкции (т. е. инструкции, которые обращаются к памяти за пределами привилегий текущего процесса центрального процессора [ЦП]).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiPresent обнаружил инструкции, которые не поддерживаются графическим оборудованием.
STATUS_INVALID_HANDLE	DxgkDdiPresent обнаружил недопустимый дескриптор в буфере команд.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Драйвер мини-порта дисплея обнаружил ошибку в потоке DMA. Если драйвер возвращает этот код ошибки, устройство графического контекста помещается в потерянное состояние.

Подсистема ядра графики DirectX вызывает функцию DxgkDdiPresent драйвера мини-порта дисплея для копирования содержимого из исходных выделений, как правило, на основную поверхность. (Эта функция также может копировать содержимое при выделении памяти системы вне экрана.) Так как основная поверхность определена слабо, DxgkDdiPresent можно реализовать в следующих сценариях:

В зависимости от положения окна функция DxgkDdiPresent должна выполняться в разных источниках, которые могут находиться на одном адаптере или в разных адаптерах.
Основной объект находится на удаленном мониторе и получает доступ через клиент служб терминалов или Microsoft NetMeeting.
Недавно произошло переключение режима, и основной формат отличается от исходного, поэтому требуется преобразование цвета. Кроме того, операция DxgkDdiPresent может быть обрезана из-за обрезки окон и упорядочивания.

Так как предыдущие сценарии могут изменяться асинхронно, драйвер дисплея пользовательского режима не может заранее скомпилировать аппаратные инструкции для функции DxgkDdiPresent драйвера мини-порта дисплея. Драйвер мини-порта дисплея должен создавать аппаратные команды для фактической операции DxgkDdiPresent и помещаться в выходной буфер DMA. После вызова функции DxgkDdiPresent драйвера мини-порта дисплея для создания буфера DMA операционная система гарантирует, что изменение сценария не произойдет до отрисовки буфера.

Драйвер мини-порта дисплея не обязан учитывать особенности предыдущих сценариев, если драйвер поддерживает следующие абстракции:

В операции копирования из источника видеопамячи в основное место назначения видео или системной памяти, копии из источника памяти системы вне экрана в основное назначение, копии из и в основной или копии из основного источника в место назначения внеэкранной системной памяти источник задается элементом hDeviceSpecificAllocation элемента массива pAllocationList[DXGK_PRESENT_SOURCE_INDEX] структуры DXGKARG_PRESENT , что pPresent параметр DxgkDdiPresent указывает на . Назначение, являющееся текущим основным элементом устройства или выделением памяти вне экрана системы, определяется элементом hDeviceSpecificAllocation элемента массива pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] DXGKARG_PRESENT. Если назначение равно источнику (то есть destination == source), операция копирования представляет собой передачу битовых блоков с экрана на экран (bitblt). Таким образом, графическая подсистема задает для источника и назначения следующие значения:
- destination != NULL (то есть destination == nonNULL)
- source != NULL (то есть source == nonNULL)
При перемещении видеопамяти с текущего выделения на другое выделение источник может быть указан операционной системой и задан в элементе hDeviceSpecificAllocation элемента массива pAllocationList[DXGK_PRESENT_SOURCE_INDEX] DXGKARG_PRESENT. Графическая подсистема задает для источника и назначения следующие значения:
- destination == NULL
- source != NULL (то есть source == nonNULL)
Примечание Перевернуть без операции можно из того же исходного выделения, что и отсканированное выделение. Флип без операции используется для вставки в очередь ожидания вертикального пробела в потоке отрисовки. Драйвер мини-порта дисплея должен вставить аппаратную команду flip, как если бы она переворачивалась к другому выделению.
В операции заливки цвета на основную поверхность выделение источника не требуется, а назначение является основным дескриптором выделения, который задается элементом hDeviceSpecificAllocation элемента массива pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] DXGKARG_PRESENT. Элемент Color DXGKARG_PRESENT обычно имеет формат D3DDDIFMT_A8R8G8B8 из типа перечисления D3DDDIFORMAT . Однако если основным форматом является палетизированный RGB, цвет содержит индекс палитры. Таким образом, графическая подсистема задает для источника и назначения следующие значения:
- destination != NULL (то есть destination == nonNULL)
- source == NULL

Для правильной работы всех сценариев DxgkDdiPresent функция DxgkDdiCreateDevice драйвера мини-порта дисплея должна задать член DmaBufferSize структуры DXGK_DEVICEINFO , чтобы он был достаточно большим, чтобы вместить аппаратные команды, необходимые для представления по крайней мере одного прямоугольника RECT на дисплее или вне экрана. Однако функция DxgkDdiPresent драйвера может возвращать STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER, если количество вложенных параметров в сценарии DxgkDdiPresent истощает текущий буфер DMA и драйверу требуется другой буфер DMA для продолжения.

Затем графическая подсистема получает новый буфер DMA и снова вызывает функцию DxgkDdiPresent драйвера с тем же списком структур RECT, что и предыдущий вызов DxgkDdiPresent . Драйвер должен использовать элемент MultipassOffsetструктуры DXGKARG_PRESENT , на которую указывает pPresent , для записи хода выполнения списка RECT в предыдущем вызове DxgkDdiPresent , чтобы драйвер мог продолжить работу с того места, где он остановился с новым буфером DMA. Когда функция DxgkDdiPresent драйвера завершает список структур RECT, она возвращает STATUS_SUCCESS.

Помимо создания буфера DMA, драйвер мини-порта дисплея должен создать список расположений исправлений, указывающий различные смещения в буфере DMA, которые необходимо исправить позже, когда физические адреса для выделения будут известны. Иногда диспетчер видеопамять предоставляет драйверу предварительно исправленные сведения (т. е. последние известные физические адреса источника и назначения) в списке выделения.

Когда диспетчер видеопамяти предоставляет эти сведения, драйвер должен создать буфер DMA, определив, что эти физические адреса являются конечными адресами, которые будет предоставлять подсистема графического ядра DirectX. Графическая подсистема может не вызывать функцию DxgkDdiPatch в буфере DMA, чтобы исправить ее позже. Поэтому драйвер должен использовать сведения о предварительном исправлении для правильного создания буфера DMA. Предварительно исправленные сведения предоставляются для элемента N , если элемент SegmentIdN-гоэлемента массива pAllocationListDXGKARG_PRESENT не равен нулю.

Примечание Несмотря на то, что функция DxgkDdiPresent драйвера предварительно исправляет буфер DMA, драйвер должен по-прежнему вставлять все ссылки на выделения в выходной список расположений исправлений, указанный членом pPatchLocationListOutDXGKARG_PRESENT . Драйвер должен вставить эти ссылки, так как адреса выделений могут измениться перед отправкой буфера DMA в GPU; Поэтому подсистема ядра графики DirectX вызовет функцию DxgkDdiPatch для повторного исправления буфера DMA.

Если драйвер поддерживает поворот (то есть сообщает о поддержке вращающихся режимов в элементе RotationSupport структуры D3DKMDT_VIDPN_PRESENT_PATH_TRANSFORMATION в вызове функции DxgkDdiEnumVidPnCofuncModality ), драйвер должен иметь возможность выполнять повернутые битовые блоки (bitblt) из источника в назначение. Если в структуре DXGK_PRESENTFLAGS для элемента Flags DXGKARG_PRESENT указан флаг поворотабитового поля, драйвер должен применить поворот, как если бы он переходил от невернутой поверхности к конечной ориентации текущего источника.

Основное выделение источника указывается в функции DxgkDdiCommitVidPn . Если из заданного источника (режим клонирования) исходит несколько путей, драйвер мини-порта дисплея должен убедиться, что выходные данные правильно поворачиваются в соответствии с режимом поворота пути для различных целевых объектов. Все параметры, предоставляемые DxgkDdiPresent , не зависят от поворота. Исходный и целевой прямоугольники могут быть весь экран по мере его восприятия клиентами (например, 768 x 1024).

Примечание Эта ситуация не относится к полноэкранным приложениям Direct3D в повернутом режиме.

Если драйвер мини-порта дисплея ранее в вызове функции DxgkDdiQueryAdapterInfo указал, что он поддерживает сопоставленный в памяти операции ввода-вывода (MMIO) flip (путем установки флага битового поля FlipOnVSyncMmIo в элементе FlipCaps структуры DXGK_DRIVERCAPSзначение TRUE), функция DxgkDdiPresent драйвера впоследствии вызывается с элементом pDmaBufferDXGKARG_PRESENT присвоено значение NULL . так как для переворачивания на основе MMIO не требуется буфер DMA для работы на GPU. Вместо этого функция DxgkDdiPresent драйвера должна проверять исходную поверхность и программную проверку оборудования при необходимости. Подсистема графического ядра DirectX вызывает функцию Драйвера DxgkDdiSetVidPnSourceAddress для выполнения этого типа flip.

DxgkDdiPresent должен быть доступным для страниц.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista
Целевая платформа	Персональный компьютер
Верхняя часть	d3dkmddi.h
IRQL	PASSIVE_LEVEL