D3DKMTRender function

The D3DKMTRender function submits the current command buffer to the Microsoft DirectX graphics kernel subsystem (Dxgkrnl.sys).

Syntax

NTSTATUS D3DKMTRender(

);

Parameters

This function has no parameters.

Return Value

D3DKMTRender returns one of the following values:

Return code Description
STATUS_SUCCESS
The command buffer was successfully submitted.
STATUS_DEVICE_REMOVED
The graphics adapter was stopped or the display context was reset.
STATUS_INVALID_PARAMETER
Parameters were validated and determined to be incorrect.
STATUS_NO_MEMORY
D3DKMTRender could not complete because of insufficient memory.
STATUS_INVALID_HANDLE
The OpenGL ICD detected an invalid handle in the command buffer.
STATUS_PRIVILEGED_INSTRUCTION
D3DKMTRender detected nonprivileged instructions (that is, instructions that access memory beyond the privilege of the current CPU process).
STATUS_ILLEGAL_INSTRUCTION
D3DKMTRender detected instructions that could not be supported by graphics hardware.
STATUS_INVALID_USER_BUFFER
D3DKMTRender detected data or instruction underrun or overrun. That is, less or more instructions or data were received than were expected.
STATUS_GRAPHICS_CANT_RENDER_LOCKED_ALLOCATION
The video memory manager detected references to a locked allocation in the allocation list. Note that the video memory manager returns this error only if it could not reposition the allocation to an AGP or system memory segment.
STATUS_GRAPHICS_ALLOCATION_INVALID
The primary surface handle was invalidated because of a display mode change.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE
An error occurred on the rendering device context that the hContext member of D3DKMT_RENDER specifies.
Note This error code does not indicate the initiation of a Timeout Detection and Recovery (TDR) process or that the GPU stopped responding.
For example, the DirectX graphics kernel subsystem puts a device into an error state if the display miniport driver indicated that a DMA buffer that was submitted from this device caused a fault or if the video memory manager could not page-in all of the allocations that are required for a DMA buffer even after splitting the DMA buffer. After a device is in an error state, it cannot perform any more operations and must be destroyed and recreated. The ICD can call the D3DKMTGetDeviceState function to determine a more precise reason for the error.

This function might also return other NTSTATUS values.

Remarks

A command buffer typically contains many graphics commands.

If D3DKMTRender returns STATUS_GRAPHICS_ALLOCATION_INVALID, the OpenGL ICD should re-open or re-create the primary handle, replace all references in the command buffer to the previous handle with the new handle, and then call D3DKMTRender again to resubmit the buffer.

After a call to D3DKMTRender, the OpenGL ICD should determine the base address and size of the command buffer that it should use for its next submission from the values that are returned in the pCommandBuffer and CommandBufferSize members of the D3DKMT_RENDER structure that is pointed to by the pData parameter.

For a device that uses guaranteed DMA buffer contract mode (for more information about this mode, see Using the Guaranteed Contract DMA Buffer Model), the size of the DMA buffer that is available to the display miniport driver to translate the command buffer at the next submission is the same as the size of the command buffer itself. For such a device, the OpenGL ICD should also determine the size of the allocation list that will be available to the display miniport driver during the translation of the command buffer at the next submission from the value that is returned in the AllocationListSize member of D3DKMT_RENDER.

For devices that do not use guaranteed DMA buffer contract, the OpenGL ICD can use the information that is returned in the CommandBufferSize and AllocationListSize members to determine the size of the next DMA buffer and allocation list that will be available for translation. However, under low-memory conditions, the actual DMA buffer and allocation list that is provided to the display miniport driver might be smaller than required.

If the OpenGL ICD detects that most of the command buffer flushes are because the driver runs out of space in the command buffer or allocation list, the driver can request for them to be resized. To resize the command buffer, the driver sets the ResizeCommandBuffer bit-field flag in the Flags member of D3DKMT_RENDER and puts the requested size in the CommandBufferSize member of D3DKMT_RENDER. Similarly, to resize the allocation list, the driver sets the ResizeAllocationList bit-field flag in the Flags member of D3DKMT_RENDER and puts the requested number of elements in the AllocationListSize member of D3DKMT_RENDER.

Note Even though the driver can request for resizing of both the command buffer and the allocation list, the video memory manager might not be able to comply. Therefore, if the call to D3DKMTRender is successful, the driver should verify the values that are returned in the pCommandBuffer, CommandBufferSize, and AllocationListSize members.

However, if the call to D3DKMTRender fails, the driver determines that the command buffer, the allocation list, or both were not resized. Therefore, the driver should not process the values that are returned in the pCommandBuffer, CommandBufferSize, and AllocationListSize members because they are invalid.

Examples

The following code example demonstrates how an OpenGL ICD can use D3DKMTRender to render 3-D primitives.

HRESULT Render(D3DKMT_HANDLE hDevice, UINT CommandOffset, UINT CommandLength)
{
    D3DKMT_RENDER RenderData;

    memset(&RenderData, 0, sizeof(RenderData));
    RenderData.hDevice = hDevice;
    RenderData.CommandOffset = CommandOffset;
    RenderData.CommandLength = CommandLength;

    if (NT_SUCCESS((*pfnKTRender)(&RenderData))) {
        return S_OK;
    }
    return E_FAIL;
}

Requirements

   
Windows version Available in Windows Vista and later versions of the Windows operating systems.
Target Platform Universal
Header d3dkmthk.h (include D3dkmthk.h)
Library Gdi32.lib
DLL Gdi32.dll

See Also

D3DKMTGetDeviceState

D3DKMT_RENDER