estructura DXGI_DDI_BASE_FUNCTIONS (dxgiddi.h)

Artículo
03/08/2023

La estructura de DXGI_DDI_BASE_FUNCTIONS contiene funciones que el controlador de pantalla en modo de usuario puede implementar para realizar tareas de bajo nivel, como presentar fotogramas representados a una salida, controlar gamma y administrar una transición de pantalla completa.

Sintaxis

typedef struct DXGI_DDI_BASE_FUNCTIONS {
  HRESULT()(DXGI_DDI_ARG_PRESENT *) * pfnPresent;
  HRESULT()(DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS *) * pfnGetGammaCaps;
  HRESULT()(DXGI_DDI_ARG_SETDISPLAYMODE *) * pfnSetDisplayMode;
  HRESULT()(DXGI_DDI_ARG_SETRESOURCEPRIORITY *) * pfnSetResourcePriority;
  HRESULT()(DXGI_DDI_ARG_QUERYRESOURCERESIDENCY *) * pfnQueryResourceResidency;
  HRESULT()(DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES *) * pfnRotateResourceIdentities;
  HRESULT()(DXGI_DDI_ARG_BLT *) * pfnBlt;
} DXGI_DDI_BASE_FUNCTIONS;

Miembros

pfnPresent

Puntero a la función PresentDXGI que notifica al controlador de pantalla en modo de usuario que una aplicación ha terminado de representar y solicita que el controlador se muestre en la superficie de destino.

El miembro hDevice de la estructura DXGI_DDI_ARG_PRESENT a la que apunta el parámetro pPresentData es el mismo identificador al que la función CreateDevice(D3D10) del controlador se pasa al tiempo de ejecución en el miembro hDrvDevice de la estructura D3D10DDIARG_CREATEDEVICE . Por lo tanto, los escritores de controladores deben definir cuidadosamente el tipo de este identificador. Además, los controladores pueden proporcionar diferentes implementaciones de la función PresentDXGI en función de la implementación de DDI que controló la llamada a CreateDevice(D3D10). El tiempo de ejecución nunca mezclará los controladores en las implementaciones de DDI. Del mismo modo, los miembros hSurfaceToPresent y hDstResource de DXGI_DDI_ARG_PRESENT también son identificadores de recursos definidos por el controlador que el controlador devolvió al tiempo de ejecución en llamadas anteriores a la función CreateResource(D3D10) del controlador.

El miembro pDXGIContext de DXGI_DDI_ARG_PRESENT es un mecanismo de comunicación opaco. El tiempo de ejecución pasa este contexto DXGI al controlador. El controlador debe copiar este contexto DXGI sin cambios en el miembro pDXGIContext de la estructura DXGIDDICB_PRESENT cuando el controlador llama a la función pfnPresentCbDXGI .

El controlador debe enviar todos los datos de representación parcialmente compilados (búferes de comandos) mediante la función pfnRenderCb . Después, el controlador debe traducir los parámetros de identificador de recursos en identificadores de kernel y usar esos identificadores de kernel en una llamada a pfnPresentCbDXGI.

Nota

Cuando la función PresentDXGI del controlador copia el contenido con formato sRGB de una superficie de origen a una superficie de destino que no sea sRGB, el controlador debe copiar el contenido sRGB sin cambios (es decir, el controlador no debe realizar la conversión sRGB a lineal).

pPresentData

[in] Puntero a una estructura de DXGI_DDI_ARG_PRESENT que describe cómo mostrar en la superficie de destino.

pfnGetGammaCaps

La función GetGammaCapsDXGI recupera funcionalidades gamma.

pGammaData

[in] Puntero a una estructura DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS que contiene capacidades gamma.

pfnSetDisplayMode

Puntero a la función SetDisplayModeDXGI del controlador.

pfnSetResourcePriority

La función SetResourcePriorityDXGI establece la prioridad de expulsión de memoria para un recurso.

El tiempo de ejecución de Microsoft Direct3D llama a SetResourcePriorityDXGI para establecer el nivel de prioridad de un recurso. El controlador de pantalla en modo de usuario debe traducir el identificador de recursos proporcionado en el miembro hResource de la estructura de DXGI_DDI_ARG_SETRESOURCEPRIORITY a la que apunta pPriorityData a un identificador de asignación. Una vez que el controlador realiza esta traducción, el controlador debe pasar el identificador resultante en una llamada a la función pfnSetPriorityCb .

pPriorityData

[in] Puntero a una estructura de DXGI_DDI_ARG_SETRESOURCEPRIORITY que describe el nivel de prioridad en el que se va a establecer un recurso.

pfnQueryResourceResidency

Esta función determina la residencia de la lista de recursos especificada.

El tiempo de ejecución de Microsoft Direct3D llama a la función QueryResourceResidencyDXGI del controlador de pantalla en modo de usuario para que las aplicaciones determinen si el sistema operativo incurrirá en un retraso significativo en el tiempo de dibujo si el sistema debe hacer que los recursos sean accesibles para GPU. La información que se devuelve de QueryResourceResidencyDXGI es una aproximación de la residencia de recursos porque los recursos se pueden degradar antes de que las aplicaciones usen los recursos.

QueryResourceResidencyDXGI debe llamar a la función pfnQueryResidencyCb . pfnQueryResidencyCb devuelve el estado de residencia de un recurso en los elementos de la matriz que especifica el miembro pResidencyStatus de la estructura D3DDDICB_QUERYRESIDENCY . Si pfnQueryResidencyCb devuelve D3DDDI_RESIDENCYSTATUS_NOTRESIDENT para cualquier consulta, QueryResourceResidencyDXGI debe devolver S_NOT_RESIDENT. Si pfnQueryResidencyCb devuelve D3DDDI_RESIDENCYSTATUS_RESIDENTINSHAREDMEMORY para cualquier consulta y no devuelve D3DDDI_RESIDENCYSTATUS_NOTRESIDENT para ninguna consulta, QueryResourceResidencyDXGI debe devolver S_RESIDENT_IN_SHARED_MEMORY. QueryResourceResidencyDXGI debe devolver S_OK solo si todas las llamadas a pfnQueryResidencyCb para todas las consultas devuelven D3DDDI_RESIDENCYSTATUS_RESIDENTINGPUMEMORY.

Para cada recurso que el tiempo de ejecución consulta a través de una llamada a QueryResourceResidencyDXGI, el controlador de visualización en modo de usuario debe determinar qué asignaciones pertenecen al recurso que se van a consultar a través de una llamada a pfnQueryResidencyCb. Para un recurso que posee una única asignación, la determinación es simple: el controlador consultará esa asignación. Sin embargo, si un recurso posee varias asignaciones, la determinación es más difícil. El controlador debe determinar qué asignaciones probablemente usará una aplicación para la representación y el controlador solo debe consultar esas asignaciones. Por ejemplo, si un recurso posee una asignación que se usa para la representación y una asignación temporal que controla una operación de bloqueo, el controlador solo debe consultar la residencia de la primera asignación, ya que probablemente una aplicación no usará la segunda asignación para la representación.

Nota

Dado que el tiempo de ejecución no admite la consulta de residencia de recursos de memoria del sistema, el tiempo de ejecución siempre producirá un error en las solicitudes de las aplicaciones para el estado de residencia de los recursos de memoria del sistema y nunca llamará a la función QueryResourceResidencyDXGI del controlador de visualización en modo de usuario para estos recursos de memoria del sistema.

pResidencyData

[in] Puntero a una estructura de DXGI_DDI_ARG_QUERYRESOURCERESIDENCY que describe una lista de recursos en los que se comprueba la residencia.

pfnRotateResourceIdentities

Gira una lista de recursos.

La función RotateResourceIdentitiesDXGI debe intercambiar identidades de la matriz de recursos que se pasan en el miembro pResources de la estructura DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES a la que apunta el parámetro pRotateData . Por ejemplo, si la matriz de recursos hace referencia a los recursos X, Y y Z, al aumentar el orden de índice de matriz, RotateResourceIdentitiesDXGI debe girar esos identificadores para hacer referencia a Y, Z y X, en el orden creciente del índice de matriz. En concreto, el controlador de visualización en modo de usuario debe intercambiar los identificadores del kernel de los recursos correspondientes. Sin embargo, el controlador no debe intercambiar los identificadores de tiempo de ejecución (RT) correspondientes. El tiempo de ejecución llama a RotateResourceIdentitiesDXGI para girar los búferes de reserva durante la presentación. Por lo tanto, una llamada a RotateResourceIdentitiesDXGI es poco frecuente. El tiempo de ejecución puede especificar la marca D3D10_DDI_BIND_PRESENT en el miembro BindFlags de la estructura D3D10DDIARG_CREATERESOURCE cuando el tiempo de ejecución llama a la función CreateResource(D3D10) del controlador para indicar que el recurso puede participar en una operación de rotación.

El controlador de pantalla en modo de usuario también debe controlar otros aspectos del intercambio de identidades. Por ejemplo, en Direct3D versión 10, las vistas pueden hacer referencia a recursos; y estas vistas pueden tener direcciones de recursos insertadas en ellas. Por lo tanto, el controlador debe volver a crear estas vistas. Además, es posible que sea necesario que el controlador vuelva a aplicar las vistas enlazadas actualmente.

A partir de Windows 8, el controlador debe admitir la rotación de búferes de reserva estéreo.

pRotateData

[in] Puntero a una estructura DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES que describe una lista de recursos que se van a rotar.

pfnBlt

Copia el contenido de una superficie de origen en una superficie de destino y puede girar el contenido.

El tiempo de ejecución de Direct3D podría establecer el miembro Flags de la estructura DXGI_DDI_ARG_BLT a la que apunta el parámetro pBltData de forma que requiera que la función BltDXGI realice una operación de transferencia de bloques de bits (bitblt) que resuelva recursos de muestra múltiple, realice la conversión de formato de color y realice una extensión o reducción a la vez. Sin embargo, el tiempo de ejecución de Direct3D nunca establecerá el miembro Flags de DXGI_DDI_ARG_BLT en cero (es decir, no hay marcas establecidas) junto con el valor DXGI_DDI_MODE_ROTATION_IDENTITY establecido en el miembro Rotate de DXGI_DDI_ARG_BLT (es decir, para indicar que no hay rotación) para realizar una operación de copia de memoria recta. En su lugar, a menos que ambos recursos sean de muestra múltiple, el tiempo de ejecución de Direct3D llama a la función ResourceCopy o ResourceCopyRegion del controlador para realizar una operación de copia de memoria recta.

La calidad del ajuste o reducción que realiza el controlador de pantalla en modo de usuario debe ser tan buena como la extensión o reducción que realiza un filtro bilineal.

El tiempo de ejecución de Direct3D llamará a la función BltDXGI del controlador con poca frecuencia. Es decir, el tiempo de ejecución debe llamar a BltDXGI no más de una vez o dos veces por fotograma porque el tiempo de ejecución usa BltDXGI principalmente para admitir una presentación.

Cuando el tiempo de ejecución llama a BltDXGI para una presentación, el tiempo de ejecución establece la marca de campo de bits Presente en el miembro Flags de DXGI_DDI_ARG_BLT. El tiempo de ejecución establece la marca de campo de bits Presente para informar al controlador de que hay requisitos adicionales para el bitblt y que puede ser necesaria la sincronización adicional (por ejemplo, el tiempo de ejecución podría necesitar realizar una sincronización adicional en las configuraciones del equipo que contienen dos adaptadores de gráficos que cada uno controla partes independientes de la pantalla). Cuando se establece la marca de campo de bits Presente , el controlador debe realizar una operación de copia desde los búferes de reserva de una aplicación a la superficie compartida de DWM. Dado que la sincronización de este tipo de operación de copia es inexacta, los artefactos de desmontaje deben ser el peor tipo de artefactos que experimenta un usuario. Para este tipo de operación de copia, el controlador no debe usar un enfoque de varios pasos resolviendo primero en la superficie de destino y, a continuación, convertir los resultados en contexto porque los posibles artefactos serían mucho peores.

Si el controlador admite la devolución de DXGI_DDI_ERR_UNSUPPORTED durante la creación de una superficie principal (es decir, devolver DXGI_DDI_ERR_UNSUPPORTED de una llamada a su función CreateResource(D3D10) con la marca D3D10_DDI_BIND_PRESENT establecida en el miembro BindFlags de D3D10DDIARG_CREATERESOURCE junto con el miembro pPrimaryDesc de D3D10DDIARG_CREATERESOURCE establecido en distinto de NULL), el controlador también debe admitir la rotación durante una operación de copia. Si el controlador nunca devuelve DXGI_DDI_ERR_UNSUPPORTED de una llamada a su función CreateResource(D3D10), el tiempo de ejecución nunca pasará el DXGI_DDI_MODE_ROTATION_ROTATE90, DXGI_DDI_MODE_ROTATION_ROTATE180 o DXGI_DDI_MODE_ROTATION_ROTATE270 valor al miembro Rotate de DXGI_DDI_ARG_BLT. Por lo tanto, en esta situación, la función BltDXGI del controlador no es necesaria para admitir la rotación.

El tiempo de ejecución establece un valor en el miembro Rotate de DXGI_DDI_ARG_BLT para indicar el número de grados para girar en sentido contrario al reloj el contenido del origen antes de que el controlador copie el contenido en el destino. La rotación se especifica en incrementos de 90 grados.

Nota

Cuando la función BltDXGI del controlador copia el contenido con formato sRGB de una superficie de origen a una superficie de destino que no sea sRGB, el controlador debe copiar el contenido sRGB sin cambios (es decir, el controlador no debe realizar la conversión sRGB a lineal).

Restricciones de origen

La función BltDXGI siempre usa un subrecurso de origen completo (frente a algún área sub rectangular) para realizar la operación bitblt. Además, el origen es una representación D3D10DDIRESOURCE_TEXTURE2D (especificada en el miembro ResourceDimension de D3D10DDIARG_CREATERESOURCE cuando el origen se crea en una llamada a la función CreateResource(D3D10) del controlador de visualización en modo de usuario). Cuando el tiempo de ejecución establece el campo de bits Resolver en el miembro Flags de DXGI_DDI_ARG_BLT, el origen es un recurso de muestra múltiple. El recurso de origen está restringido a un recurso en el que se estableció la marca D3D10_DDI_BIND_PRESENT en el miembro BindFlags de D3D10DDIARG_CREATERESOURCE. El formato del origen (especificado en el miembro Format de D3D10DDIARG_CREATERESOURCE) está restringido a formatos de modo de presentación, especificados por los valores siguientes de la enumeración DXGI_FORMAT :

DXGI_FORMAT_B5G6R5_UNORM
DXGI_FORMAT_B5G5R5A1_UNORM
DXGI_FORMAT_B8G8R8A8_UNORM (consulte la nota a continuación).
DXGI_FORMAT_B8G8R8X8_UNORM
DXGI_FORMAT_R16G16B16A16_FLOAT
DXGI_FORMAT_R10G10B10A2_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM_SRGB

Nota

Si el controlador admite el formato de origen DXGI_FORMAT_B8G8R8A8_UNORM, se aplican las restricciones siguientes:

Cuando el controlador realiza una operación bitblt desde un formato de punto flotante a un formato entero como BGRA8888, debe codificar implícitamente gamma en los resultados.
Por el contrario, cuando el controlador realiza una operación bitblt de un formato entero a un formato de punto flotante, debe quitar implícitamente la codificación gamma de los resultados.

Restricciones de destino

El destino también es una representación D3D10DDIRESOURCE_TEXTURE2D . El formato del destino también está restringido a los formatos de modo de presentación. El recurso de destino está restringido a un recurso enlazado como destino de representación (D3D10_DDI_BIND_RENDER_TARGET establecido en el miembro BindFlags de D3D10DDIARG_CREATERESOURCE o D3D11DDIARG_CREATERESOURCE).

Creación de un búfer de retroceso estéreo

A partir de Windows 8, si el controlador debe crear un búfer de retroceso estéreo, debe establecer miembros de la estructura D3D10DDIARG_CREATERESOURCE o D3D11DDIARG_CREATERESOURCE, respectivamente, apuntado por el parámetro pCreateResource de las funciones CreateResource(D3D10) o CreateResource(D3D11), como se indica a continuación:

Establezca el miembro ArraySize en un valor de 2.
Establezca el valor de marca D3D10_DDI_BIND_PRESENT en el miembro BindFlags .

Además, para admitir la presentación estéreo, la función BltDXGI debe permitir cualquier valor para los miembros DstSubresource y SrcSubresource de la estructura DXGI_DDI_ARG_BLT que se encuentran dentro del intervalo de los recursos de origen y destino.