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

Статья
06/09/2023

Для адаптеров дисплея, поддерживающих аппаратное ускорение GDI, функция DxgkDdiRenderKm создает буфер прямого доступа к памяти (DMA) из буфера команд, переданного драйвером канонического дисплея в режиме ядра (CDD).

Синтаксис

DXGKDDI_RENDERKM DxgkddiRenderkm;

NTSTATUS DxgkddiRenderkm(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_RENDER pRenderKmArgs
)
{...}

Параметры

[in] hContext

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

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

[in/out] pRenderKmArgs

Указатель на структуру DXGKARG_RENDER , содержащую сведения о буфере DMA и отформатированный буфер команд.

Если драйвер мини-порта дисплея поддерживает аппаратное ускорение GDI, pRenderKmArgs-pCommand> указывает на буфер команд DXGK_RENDERKM_COMMAND.

Драйвер должен преобразовать буфер входных команд в команды буфера DMA и создать список расположений исправлений.

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

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

Код возврата	Описание
STATUS_SUCCESS	Был переведен весь буфер команд.
STATUS_NO_MEMORY	DxgkDdiRenderKm не удалось выделить память, необходимую для ее завершения.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	Текущий буфер DMA исчерпан.
STATUS_INVALID_PARAMETER	DxgkDdiRenderKm обнаружил параметры инструкций, которые не поддерживает графическое оборудование; однако графическое оборудование может поддерживать сами инструкции. Драйвер не обязан возвращать этот код ошибки. Вместо этого он может возвращать STATUS_ILLEGAL_INSTRUCTION при обнаружении неподдерживаемых параметров инструкций.
STATUS_INVALID_USER_BUFFER	DxgkDdiRenderKm обнаружил недостаточное или переполнение данных или инструкций. То есть драйвер получил меньше или больше инструкций или данных, чем ожидалось. Драйвер не обязан возвращать этот код ошибки. Вместо этого он может возвращать STATUS_ILLEGAL_INSTRUCTION при обнаружении данных или инструкций, недостаточно запущенных или переполненных.
STATUS_INVALID_HANDLE	DxgkDdiRenderKm обнаружил недопустимый дескриптор в буфере команд.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Драйвер мини-порта дисплея обнаружил ошибку в потоке DMA. Если драйвер возвращает этот код ошибки, устройство графического контекста помещается в потерянное состояние.

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

Доступ к буферам ядра не требует защиты от try/except кода.

Драйвер мини-порта дисплея не требуется использовать сведения, предоставляемые CDD, если он может повторно создать информацию более оптимально. Например, если элемент pRender-pPatchLocationListIn> пуст, так как драйвер отображения пользовательского режима не предоставил входной список расположения исправлений, драйвер мини-порта дисплея может создать содержимое элемента pRender-pPatchLocationListOut> на основе содержимого буфера команд.

В дополнение к дескриптору для конкретного устройства подсистема ядра графики DirectX предоставляет драйверу мини-порта дисплея последний известный адрес сегмента GPU для каждого выделения. Если индекс распределения N в настоящее время выстраивать, подсистема графического ядра DirectX устанавливает элемент SegmentIdN-гоэлемента элемента pAllocationListDXGKARG_RENDER равным нулю. Если член SegmentIdN-гоэлемента списка выделения не равен нулю, драйвер мини-порта дисплея должен исправить созданный буфер DMA указанными адресными данными сегмента, прежде чем подсистема графического ядра DirectX вызовет функцию DxgkDdiPatch для повторного исправления буфера DMA. Драйвер должен выполнить это начальное исправление по запросу, так как подсистема графического ядра DirectX может не вызывать функцию DxgkDdiPatch в буфере DMA, который драйвер должен правильно исправить.

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

Чтобы отменить привязку выделения, драйвер мини-порта отображения может указать элемент в списке выделения, который ссылается на дескриптор NULL , а затем использовать элемент patch-location, который ссылается на это выделение NULL . Как правило, драйвер должен использовать первый элемент списка выделения (элемент 0) в качестве элемента NULL .

В режиме DMA с гарантированным контрактом, когда драйвер мини-порта для отображения преобразует буфер команд в буфер DMA, CDD должен гарантировать достаточно ресурсов для команды преобразования. Если для преобразования недостаточно ресурсов, драйвер мини-порта дисплея должен отклонить буфер DMA. Дополнительные сведения см. в разделе Использование модели буфера DMA с гарантированным контрактом.

DxgkDdiRenderKm следует сделать страничной.

Требования

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