DXGKDDI_PRESENT función de devolución de llamada (d3dkmddi.h)

Artículo
02/26/2024

La función DxgkDdiPresent copia el contenido de las asignaciones de origen a una superficie principal (y a veces a asignaciones de memoria del sistema fuera de pantalla).

Sintaxis

DXGKDDI_PRESENT DxgkddiPresent;

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

Parámetros

[in] hContext

Identificador del contexto del dispositivo para la información de copia. La función DxgkDdiCreateContext del controlador de miniporte de pantalla devolvió previamente este identificador en el miembro hContext de la estructura DXGKARG_CREATECONTEXT a la que apunta el parámetro pCreateContext de DxgkDdiCreateContext .

Si el controlador no admite la creación de contexto, el subsistema del kernel de gráficos de Microsoft DirectX reemplaza el identificador al contexto por un identificador para el dispositivo. La función DxgkDdiCreateDevice del controlador de miniporte de pantalla devolvió previamente el identificador del dispositivo en el miembro hDevice de la estructura DXGKARG_CREATEDEVICE a la que apunta el parámetro pCreateDevice de DxgkDdiCreateDevice .

[in/out] pPresent

Puntero a una estructura DXGKARG_PRESENT que contiene información sobre la operación de copia.

Valor devuelto

DxgkDdiPresent devuelve uno de los siguientes valores:

Código devuelto	Descripción
STATUS_SUCCESS	DxgkDdiPresent copió correctamente el contenido.
STATUS_NO_MEMORY o STATUS_INSUFFICIENT_RESOURCES	DxgkDdiPresent no pudo asignar memoria necesaria para que se completara.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	El búfer de acceso directo a memoria (DMA) actual está agotado.
STATUS_GRAPHICS_CANNOTCOLORCONVERT	El controlador de minipuerto de pantalla detectó una transferencia de bloque de bits (bitblt) para la conversión de color que el dispositivo no pudo realizar. El tiempo de ejecución de Microsoft Direct3D impide que la aplicación continúe y la aplicación recibe un error al copiar contenido.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiPresent detectó instrucciones sin privilegios (es decir, instrucciones que acceden a la memoria más allá del privilegio de la unidad de procesamiento central actual [CPU]).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiPresent detectó instrucciones que el hardware gráfico no puede admitir.
STATUS_INVALID_HANDLE	DxgkDdiPresent detectó un identificador no válido en el búfer de comandos.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	El controlador de minipuerto de pantalla detectó un error en la secuencia DMA. El dispositivo de contexto gráfico se coloca en un estado perdido si el controlador devuelve este código de error.

Comentarios

El subsistema del kernel de gráficos de DirectX llama a la función DxgkDdiPresent del controlador de miniporte de pantalla para copiar el contenido de las asignaciones de origen normalmente a la superficie principal. (Esta función también puede copiar contenido en una asignación de memoria del sistema fuera de pantalla). Dado que una superficie principal está definida de forma flexible, DxgkDdiPresent se puede implementar para los escenarios siguientes:

Dependiendo de la posición de la ventana, la función DxgkDdiPresent debe realizarse en diferentes principales que pueden estar en el mismo adaptador o en diferentes adaptadores.
La principal se encuentra en un monitor remoto y se accede a ella a través de un cliente de terminal Services o Microsoft NetMeeting.
Se ha producido un modificador de modo recientemente y el formato principal es diferente del formato de origen, por lo que se necesita una conversión de color. Además, la operación DxgkDdiPresent se puede recortar debido al recorte y la ordenación de ventanas.

Dado que los escenarios anteriores pueden cambiar de forma asincrónica, el controlador de pantalla en modo de usuario no puede compilar instrucciones de hardware para la función DxgkDdiPresent del controlador de minipuerto de pantalla de antemano. El controlador de minipuerto de pantalla debe crear comandos de hardware para la operación DxgkDdiPresent real y deben colocarse en un búfer DMA de salida. Después de llamar a la función DxgkDdiPresent del controlador de minipuerto de pantalla para generar el búfer DMA, el sistema operativo garantiza que no se producirá un cambio de escenario antes de que se represente ese búfer.

El controlador de minipuerto de pantalla no es necesario tener en cuenta los detalles de los escenarios anteriores, siempre y cuando el controlador admita las abstracciones siguientes:

En una operación de copia desde un origen de memoria de vídeo a un destino de memoria del sistema o vídeo principal, una copia de un origen de memoria del sistema fuera de pantalla al destino principal, una copia de y a la principal, o una copia del origen principal a un destino de memoria del sistema fuera de pantalla, el origen se especifica mediante el miembro hDeviceSpecificAllocation del elemento de matriz pAllocationList[DXGK_PRESENT_SOURCE_INDEX] de la estructura DXGKARG_PRESENT que el pPresent parámetro de DxgkDdiPresent apunta a. El destino, que es la principal actual del dispositivo o una asignación de memoria del sistema fuera de pantalla, se especifica mediante el miembro hDeviceSpecificAllocation del elemento de matriz pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] de DXGKARG_PRESENT. Si el destino es igual al origen (es decir, destino == origen), la operación de copia es una transferencia de bloque de bits de pantalla a pantalla (bitblt). Por lo tanto, el subsistema de gráficos establece el origen y el destino en los valores siguientes:
- destination != NULL (es decir, destination == nonNULL)
- source != NULL (es decir, source == nonNULL)
En un volteo de memoria de vídeo de la asignación actual a otra asignación, el sistema operativo puede especificar el origen y establecerlo en el miembro hDeviceSpecificAllocation del elemento de matriz pAllocationList[DXGK_PRESENT_SOURCE_INDEX] de DXGKARG_PRESENT. El subsistema de gráficos establece el origen y el destino en los valores siguientes:
- destination == NULL
- source != NULL (es decir, source == nonNULL)
Nota Se puede realizar un volteo sin operación desde la misma asignación de origen que la asignación que se ha examinado actualmente. Se usa un volteo sin operación para insertar una espera en cola para un espacio en blanco vertical en la secuencia de representación. El controlador de minipuerto de pantalla debe insertar un comando de volteo de hardware como si se voltee a otra asignación.
En una operación de relleno de color en la superficie principal, no se requiere ninguna asignación de origen y el destino es un identificador de asignación principal especificado por el miembro hDeviceSpecificAllocation del elemento de matriz pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] de DXGKARG_PRESENT. El miembro Color de DXGKARG_PRESENT suele tener el formato D3DDDIFMT_A8R8G8B8 del tipo de enumeración D3DDDIFORMAT . Sin embargo, cuando el formato principal es RGB pálido, Color contiene el índice de paleta. Por lo tanto, el subsistema de gráficos establece el origen y el destino en los valores siguientes:
- destination != NULL (es decir, destination == nonNULL)
- source == NULL

Para que todos los escenarios dxgkDdiPresent funcionen correctamente, la función DxgkDdiCreateDevice del controlador de miniporte de pantalla debe establecer el miembro DmaBufferSize de la estructura DXGK_DEVICEINFO para que sea lo suficientemente grande como para contener los comandos de hardware necesarios para presentar al menos un rectángulo RECT al destino de pantalla o fuera de pantalla. Sin embargo, la función DxgkDdiPresent del controlador puede devolver STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER si el número de subrectangos en el escenario DxgkDdiPresent agota el búfer DMA actual y el controlador requiere que continúe otro búfer DMA.

A continuación, el subsistema de gráficos adquiere un nuevo búfer DMA y llama a la función DxgkDdiPresent del controlador de nuevo con la misma lista de estructuras RECT que la llamada a DxgkDdiPresent anterior. El controlador debe usar el miembro MultipassOffset de la estructura DXGKARG_PRESENT a la que apunta pPresent para registrar la cantidad de progreso realizado al completar la lista RECT en la llamada anterior a DxgkDdiPresent para que el controlador pueda continuar desde donde se detuvo con el nuevo búfer DMA. Cuando la función DxgkDdiPresent del controlador completa la lista de estructuras RECT, devuelve STATUS_SUCCESS.

Además de generar un búfer DMA, el controlador de miniporte de pantalla debe generar una lista de ubicaciones de revisión que indique los distintos desplazamientos dentro del búfer DMA que se deben aplicar revisiones más adelante cuando se conocen las direcciones físicas de las asignaciones. En ocasiones, el administrador de memoria de vídeo proporciona al controlador información revisada previamente (es decir, las últimas direcciones físicas de conocer el origen y el destino) en la lista de asignación.

Cuando el administrador de memoria de vídeo proporciona esta información, el controlador debe generar el búfer DMA mediante la determinación de que estas direcciones físicas son las direcciones finales que proporcionará el subsistema del kernel gráfico de DirectX. Es posible que el subsistema de gráficos no llame a la función DxgkDdiPatch en el búfer DMA para volver a aplicarle revisiones más adelante. Por lo tanto, el controlador debe usar la información previa a la revisión para generar correctamente el búfer DMA. La información revisada previamente se proporciona para el elemento N cuando el miembro SegmentId del elemento Nthde la matriz pAllocationList de DXGKARG_PRESENT es distinto de cero.

Nota Aunque la función DxgkDdiPresent del controlador aplica revisiones previas al búfer DMA, el controlador debe seguir insertando todas las referencias a las asignaciones en la lista de ubicación de revisión de salida que especifica el miembro pPatchLocationListOut de DXGKARG_PRESENT . El controlador debe insertar estas referencias porque las direcciones de las asignaciones pueden cambiar antes de enviar el búfer DMA a la GPU; por lo tanto, el subsistema del kernel de gráficos de DirectX llamará a la función DxgkDdiPatch para volver a guardar el búfer DMA.

Si el controlador admite la rotación (es decir, notifica la compatibilidad con los modos girados en el miembro RotationSupport de la estructura de D3DKMDT_VIDPN_PRESENT_PATH_TRANSFORMATION en una llamada a su función DxgkDdiEnumVidPnCofuncModality ), el controlador debe poder realizar transferencias de bloques de bits rotadas (bitblt) desde el origen al destino. Cuando se especifica la marca de campo de bits Girar en la estructura DXGK_PRESENTFLAGS para el miembro Flags de DXGKARG_PRESENT, el controlador debe aplicar la rotación como si pasara de una superficie no girada a la orientación final del origen actual.

La asignación principal de un origen se especifica en la función DxgkDdiCommitVidPn . Si varias rutas de acceso se originan en el origen determinado (modo de clonación), el controlador de minipuerto de pantalla debe asegurarse de que las salidas se rotan correctamente según el modo de rotación de ruta de acceso para los distintos destinos. Todos los parámetros que se proporcionan a DxgkDdiPresent son independientes de la rotación. Los rectángulos de origen y destino podrían ser la pantalla completa a medida que los clientes lo perciben (por ejemplo, 768 x 1024).

Nota Esta situación no aborda las aplicaciones direct3D de pantalla completa en modo girado.

Si el controlador de minipuerto de pantalla indicado anteriormente, en una llamada a su función DxgkDdiQueryAdapterInfo , admite un volteo basado en E/S asignada a memoria (MMIO) (estableciendo la marca de campo de bits FlipOnVSyncMmIo en el miembro FlipCaps de la estructura DXGK_DRIVERCAPS en TRUE), posteriormente se llama a la función DxgkDdiPresent del controlador con el miembro pDmaBuffer de DXGKARG_PRESENT establecido en NULL . dado que un volteo basado en MMIO no requiere un búfer DMA para ejecutarse en la GPU. En su lugar, la función DxgkDdiPresent del controlador debe validar la superficie de origen y el hardware de volteo de programa según sea necesario. El subsistema del kernel de gráficos directX llama a la función DxgkDdiSetVidPnSourceAddress del controlador para ejecutar este tipo de volteo.

DxgkDdiPresent debe ser paginable.