DXGKDDI_RENDERKM callback function (d3dkmddi.h)
For display adapters that support GDI hardware acceleration, the DxgkDdiRenderKm function generates a direct memory access (DMA) buffer from the command buffer that the kernel-mode Canonical Display Driver (CDD) passed.
Syntax
DXGKDDI_RENDERKM DxgkddiRenderkm;
NTSTATUS DxgkddiRenderkm(
[in] IN_CONST_HANDLE hContext,
[in/out] INOUT_PDXGKARG_RENDER pRenderKmArgs
)
{...}
Parameters
[in] hContext
A handle to the device context for the DMA and command buffers. The display miniport driver's DxgkDdiCreateContext function previously returned this handle in the hContext member of the DXGKARG_CREATECONTEXT structure that the pCreateContext parameter of DxgkDdiCreateContext points to.
If the driver does not support context creation, the Microsoft DirectX graphics kernel subsystem replaces the handle to the context with a handle to the device. The display miniport driver's DxgkDdiCreateDevice function previously returned the device handle in the hDevice member of the DXGKARG_CREATEDEVICE structure that the pCreateDevice parameter of DxgkDdiCreateDevice points to.
[in/out] pRenderKmArgs
A pointer to a DXGKARG_RENDER structure that contains information about the DMA buffer and a formatted command buffer.
If the display miniport driver supports GDI hardware acceleration, pRenderKmArgs->pCommand points to the DXGK_RENDERKM_COMMAND command buffer.
The driver must translate the input command buffer into DMA buffer commands and build the patch location list.
Return value
DxgkDdiRenderKm returns one of the following values:
| Return code | Description |
|---|---|
| STATUS_SUCCESS | The entire command buffer was translated. |
| STATUS_NO_MEMORY | DxgkDdiRenderKm could not allocate memory that was required for it to complete. |
| STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER | The current DMA buffer is depleted. |
| STATUS_INVALID_PARAMETER | DxgkDdiRenderKm detected instruction parameters that graphics hardware could not support; however, the graphics hardware can support the instructions themselves. The driver is not required to return this error code. Instead, it can return STATUS_ILLEGAL_INSTRUCTION when it detects unsupported instruction parameters. |
| STATUS_INVALID_USER_BUFFER | DxgkDdiRenderKm detected data or instruction underrun or overrun. That is, the driver received less or more instructions or data than expected. The driver is not required to return this error code. Instead, it can return STATUS_ILLEGAL_INSTRUCTION when it detects data or instruction underrun or overrun. |
| STATUS_INVALID_HANDLE | DxgkDdiRenderKm 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
The DirectX graphics kernel subsystem calls the display miniport driver's DxgkDdiRenderKm function to generate a DMA buffer from the command buffer that is passed by the kernel-mode Canonical Display Driver (CDD) provided by the operating system. In addition to the output DMA buffer, the display miniport driver should also generate a list of output patch locations. The video memory manager uses this list to split and patch DMA buffers appropriately.
Access to the kernel buffers does not require protection from try/except code.
The display miniport driver is not required to use information that the CDD provides if it can re-create the information more optimally. For example, if the pRender->pPatchLocationListIn member is empty because the user-mode display driver did not provide an input patch-location list, the display miniport driver can generate the content of the pRender->pPatchLocationListOut member based on the content of the command buffer instead.
In addition to the device-specific handle, the DirectX graphics kernel subsystem provides the display miniport driver with the last known GPU segment address for each allocation. If allocation index N is currently paged out, the DirectX graphics kernel subsystem sets the SegmentId member of the Nth element of the pAllocationList member of DXGKARG_RENDER to zero. If the SegmentId member of the Nth element of the allocation list is not set to zero, the display miniport driver must patch the generated DMA buffer with the provided segment address information before the DirectX graphics kernel subsystem calls the DxgkDdiPatch function to repatch the DMA buffer. The driver must perform this initial patching when requested because the DirectX graphics kernel subsystem might not call the DxgkDdiPatch function on a DMA buffer that the driver should have properly patched.
Even though the driver's DxgkDdiRenderKm function performs the initial DMA buffer patching as described earlier, the driver must still insert all the references to allocations into the output patch-location list that the pPatchLocationListOut member of DXGKARG_RENDER specifies. This list must contain all of the references because the addresses of the allocations might change before the DMA buffer is submitted to the GPU; therefore, the DirectX graphics kernel subsystem will call the DxgkDdiPatch function to repatch the DMA buffer.
To unbind an allocation, the display miniport driver can specify an element in the allocation list that references a NULL handle and then can use a patch-location element that references that NULL allocation. Typically, the driver should use the first element of the allocation list (element 0) as the NULL element.
In guaranteed contract DMA mode, when the display miniport driver translates a command buffer to a DMA buffer, the CDD must guarantee enough resources for the translation command. If enough resources do not exist for the translation, the display miniport driver must reject the DMA buffer. For more information, see Using the Guaranteed Contract DMA Buffer Model.
DxgkDdiRenderKm should be made pageable.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 7 |
| Target Platform | Desktop |
| Header | d3dkmddi.h |
| IRQL | PASSIVE_LEVEL |