PFND3DDDI_CREATERESOURCE2 función de devolución de llamada (d3dumddi.h)

Artículo
03/08/2023

Crea un recurso. Implementado por windows Display Driver Model (WDDM) 1.2 y controladores de pantalla en modo usuario posteriores.

Sintaxis

PFND3DDDI_CREATERESOURCE2 Pfnd3dddiCreateresource2;

HRESULT Pfnd3dddiCreateresource2(
  [in] HANDLE hDevice,
       D3DDDIARG_CREATERESOURCE2 *unnamedParam2
)
{...}

Parámetros

[in] hDevice

Identificador del dispositivo de visualización (contexto de gráficos) que se usa para crear el recurso.

unnamedParam2

pResource2 [in, out]

Puntero a una estructura de D3DDDIARG_CREATERESOURCE2 que describe el recurso que se crea.

Valor devuelto

Devuelve S_OK o un resultado de error adecuado. Los controladores WDDM 1.3 y versiones posteriores de Direct3D Level 9 deben devolver este código de error:

Código devuelto	Descripción
E_INVALIDARG	El D3DDDIARG_CREATERESOURCE2 . Flagsmember tiene establecido el valor de marca CaptureBuffer y el recurso supera lo que el controlador puede admitir.

Comentarios

La llamada a CreateResource2 puede contener una lista de superficies. El miembro SurfCount de la estructura D3DDDIARG_CREATERESOURCE2 especificada por el parámetro pResource2 especifica el número de superficies (incluidos los niveles de mapa miP) que se van a crear. Por ejemplo, un recurso MIP-map de textura de 256x9 de 256x9 contiene una lista de nueve superficies donde el miembro SurfCount y el número de niveles de mapa MIP se establecen en 9. Un mapa de cubo que contenga nueve niveles de mapa MIP debe tener el número de niveles de mapa de MIP establecidos en 9 y SurfCount establecido en 54. Una cadena de intercambio de tres superficies debe tener SurfCount establecido en 3 y el número de niveles de mapa MIP establecidos en 0. Tenga en cuenta que el número de niveles de mapa de MIP siempre es menor o igual que el valor de SurfCount.

En respuesta a la llamada a CreateResource2 , el controlador de pantalla en modo de usuario puede llamar a la función pfnAllocateCb para crear una o varias asignaciones de memoria. El controlador de pantalla en modo de usuario debe determinar si debe crear varias asignaciones por superficie, una asignación para todas las superficies o una asignación por superficie. Para obtener más información sobre las asignaciones, consulte Administración de memoria de vídeo y programación de GPU.

Nota La función CreateResource2 del controlador no es necesaria para llamar a pfnAllocateCb antes de devolver; en su lugar, el controlador puede aplazar la creación de la asignación.

Nota Un recurso solo se puede compartir si todas las asignaciones del recurso se realizan de forma atómica en una sola llamada a pfnAllocateCb.

El miembro hResource de la estructura D3DDDIARG_CREATERESOURCE2 es un identificador que se usa para identificar el recurso. El controlador de visualización en modo de usuario debe almacenar el valor de hResource que se pasó en la llamada a CreateResource2 y sobrescribir el valor con otro valor que el entorno de ejecución de Microsoft Direct3D puede usar cuando la llamada CreateResource2 devuelve. En otras palabras, en las llamadas al runtime, el controlador de visualización en modo de usuario usa el valor hResource que se pasó a CreateResource2; en llamadas al controlador de visualización en modo de usuario (por ejemplo, en llamadas a las funciones SetTexture o SetStreamSource ), el runtime usa el valor hResource que se devolvió desde CreateResource2. Tenga en cuenta que cada superficie no tiene un identificador explícito; si la superficie se debe hacer referencia individualmente (por ejemplo, en una llamada a la función Blt ), se hace referencia a ella mediante un identificador y un índice. El índice identifica la superficie dentro del recurso. El índice es el mismo que el índice de la superficie de la matriz contenida en el miembro pSurfList de D3DDDIARG_CREATERESOURCE2.

Los recursos se pueden compartir mediante varios dispositivos (hDevice) y procesos. El tiempo de ejecución especifica que un recurso se comparte estableciendo la marca de campo de bits SharedResource en el miembro Flags de D3DDDIARG_CREATERESOURCE2. Si se establece esta marca de campo de bits, el controlador de pantalla en modo de usuario debe cumplir las siguientes restricciones en los recursos compartidos:

El controlador de pantalla en modo de usuario puede llamar a las funciones pfnAllocateCb y pfnDeallocateCb exactamente una vez cada una.
El controlador de visualización en modo de usuario no puede crear asignaciones adicionales para el recurso después de crear el recurso inicialmente y, del mismo modo, puede destruir las asignaciones de recursos solo en el momento en que se destruye el propio recurso.
Cuando se llama a la función DestroyResource del controlador de visualización en modo de usuario para un recurso compartido que se creó o abrió a través de una llamada a la función CreateResource2 o OpenResource del controlador, el controlador debe establecer el miembro hResource de la estructura de D3DDDICB_DEALLOCATE en distinto de NULL y el miembro NumAllocations de D3DDDICB_DEALLOCATE a cero en una llamada a la función pfnDeallocateCb para destruir o cerrar el recurso. Es decir, las asignaciones asociadas a un recurso compartido no se pueden destruir ni cerrar individualmente; el recurso debe destruirse o cerrarse atómicamente en una llamada a pfnDeallocateCb.
El número de asignaciones debe ser coherente para el tipo de recurso (es decir, otro proceso que crea el mismo tipo de recurso debe generar el mismo número y tipo de asignaciones). Además, no se permite cambiar el nombre de estos recursos.

Las marcas de campo de bits especificadas en la estructura D3DDDI_RESOURCEFLAGS2 se pasan en el miembro Flags de D3DDDIARG_CREATERESOURCE2.

Nota Se puede crear un recurso sin especificar ninguna marca. Las superficies asociadas a este recurso pueden bloquearse y pueden ser un origen o destino en una operación de transferencia de bloques de bits (bitblt). Sin embargo, estas superficies no se pueden usar para nada más.

Nota Las superficies sin formato se diferencian de texturas o destinos de representación independientes por la ausencia de la marca de campo de bits Textura o Principal . Por ejemplo, la presencia de la marca de campo de bits principal indica un destino de representación independiente y la ausencia de esta marca indica un destino de representación que es un búfer de reserva.

Nota Para asegurarse de que los cambios en el entorno de ejecución no interrumpan los controladores existentes, los controladores no deben usar los siguientes miembros reservados de la estructura D3DDDIARG_CREATERESOURCE2 en las llamadas a su función CreateResource2 para afectar al comportamiento de los controladores:

Los bits no definidos del miembro Flags están reservados .
Si la marca de campo de bits principal no está establecida en Marcas, se reservan los miembros RefreshRate y Output .
Si la marca de campo de bits RenderTarget, DecodeRenderTarget o VideoProcessRenderTarget no está establecida en Flags, se reservan los miembros MultisampleType y MultisampleQuality .
Si la marca de campo de bits VertexBuffer no está establecida en Marcas, se reserva el miembro Fvf .
Si las marcas de campo de bits Texture, CubeMap y Volume no están establecidas en Marcas, se reserva el miembro MipLevels .

Para obtener más información sobre cómo crear y destruir recursos, consulte Control de la creación y destrucción de recursos.

Para un recurso de memoria del sistema, el controlador de miniporte de pantalla puede optar por encapsular una asignación alrededor de la memoria del sistema si la memoria del sistema está alineada correctamente para el acceso directo por parte de la unidad de procesamiento gráfico (GPU). El controlador de minipuerto de pantalla ajusta una asignación alrededor de la memoria del sistema estableciendo la marca ExistingSysMem en el miembro Flags de la estructura DXGK_ALLOCATIONINFO al crear la asignación mediante su función DxgkDdiCreateAllocation . Si el controlador de miniporte de pantalla no puede encapsular una asignación alrededor de la memoria del sistema o se produce un error en el ajuste, el controlador debe seguir teniendo éxito en la creación del recurso y usar la CPU para acceder al recurso.

Si el tiempo de ejecución solicita crear un búfer de vértices o índices y si el controlador de pantalla en modo de usuario no puede crear el búfer por motivos que no sean de memoria insuficiente (por ejemplo, falta de compatibilidad con hardware), el controlador debe producir un error con D3DERR_NOTAVAILABLE.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8
Servidor mínimo compatible	Windows Server 2012
Plataforma de destino	Escritorio
Encabezado	d3dumddi.h (incluya D3dumddi.h)