DXGKDDI_CREATEALLOCATION fonction de rappel (d3dkmddi.h)

Article
05/26/2023

La fonction DxgkDdiCreateAllocation crée des allocations de mémoire système ou vidéo.

Syntaxe

DXGKDDI_CREATEALLOCATION DxgkddiCreateallocation;

NTSTATUS DxgkddiCreateallocation(
  [in]     IN_CONST_HANDLE hAdapter,
  [in/out] INOUT_PDXGKARG_CREATEALLOCATION pCreateAllocation
)
{...}

Paramètres

[in] hAdapter

Handle d’un bloc de contexte associé à une carte d’affichage. Le pilote miniport d’affichage a précédemment fourni cette poignée au sous-système du noyau graphique Microsoft DirectX dans le paramètre de sortie MiniportDeviceContext de la fonction DxgkDdiAddDevice .

[in/out] pCreateAllocation

Pointeur vers une structure de DXGKARG_CREATEALLOCATION qui contient des informations pour créer des allocations.

Valeur retournée

DxgkDdiCreateAllocation retourne l’une des valeurs suivantes :

Code de retour	Description
STATUS_SUCCESS	DxgkDdiCreateAllocation a correctement créé l’allocation.
STATUS_INVALID_PARAMETER	Les paramètres passés à DxgkDdiCreateAllocation contenaient des erreurs qui l’empêchaient de se terminer.
STATUS_NO_MEMORY	DxgkDdiCreateAllocation n’a pas pu allouer la mémoire nécessaire à sa fin.
STATUS_GRAPHICS_DRIVER_MISMATCH	Le pilote miniport d’affichage n’est pas compatible avec le pilote d’affichage en mode utilisateur qui a lancé l’appel à DxgkDdiCreateAllocation.

Remarques

Une fois que le pilote d’affichage en mode utilisateur a appelé la fonction pfnAllocateCb , le sous-système du noyau graphique DirectX appelle la fonction DxgkDdiCreateAllocation du pilote d’affichage miniport pour créer les allocations. Le pilote miniport d’affichage doit interpréter les données privées (dans le membre pPrivateDriverData de la structure DXGK_ALLOCATIONINFO pour chaque allocation) transmises à partir du pilote d’affichage en mode utilisateur et doit déterminer la liste des paramètres nécessaires pour créer chaque allocation via le gestionnaire de mémoire vidéo. Pour plus d’informations sur la façon dont le pilote miniport d’affichage fournit ces paramètres au gestionnaire de mémoire vidéo, consultez Spécification de segments lors de la création d’allocations.

Le pilote miniport d’affichage doit retourner un handle d’allocation, qui est généralement un pointeur vers une structure de données de pilote privé qui contient des informations sur l’allocation. Le pilote miniport d’affichage peut appeler la fonction DxgkCbGetHandleData à tout moment pour récupérer les données privées d’un handle d’allocation. Par conséquent, le pilote de miniport d’affichage n’est pas nécessaire pour gérer une table de handle d’allocation privée. En fait, nous déconseillons fortement les tables de gestion privées, car elles pourraient devenir obsolètes ou non synchronisées avec le sous-système du noyau graphique DirectX dans des scénarios de basculement en mode d’affichage, tels que le commutateur rapide d’utilisateur, le débranchement à chaud, etc.

Le pilote d’affichage en mode utilisateur affecte une allocation à une ressource ou à un appareil. Pour déterminer si l’allocation appartient à une ressource, le pilote miniport d’affichage peut case activée si l’indicateur de champ bit de ressource est défini dans le membre Flags de la structure DXGKARG_CREATEALLOCATION vers laquelle pointe le paramètre pCreateAllocation de DxgkDdiCreateAllocation. Si l’allocation appartient à une ressource, le pilote miniport d’affichage peut (mais n’est pas obligatoire pour) retourner un handle de ressource, qui est généralement un pointeur vers une structure de données de pilote privé qui décrit la ressource. Si le sous-système du noyau graphique DirectX appelle DxgkDdiCreateAllocation pour créer une allocation supplémentaire pour une ressource existante, le membre hResource de DXGKARG_CREATEALLOCATION contient le handle retourné par l’appel DxgkDdiCreateAllocation précédent pour cette ressource. Si nécessaire, le pilote miniport d’affichage peut modifier le handle de ressource lors d’un appel à DxgkDdiCreateAllocation.

Si le pilote d’affichage en mode utilisateur place un handle de ressource dans une mémoire tampon de commande, le pilote miniport d’affichage peut récupérer les données privées en appelant DxgkCbGetHandleData. Le pilote miniport d’affichage peut également énumérer toutes les allocations enfants de la ressource en appelant la fonction DxgkCbEnumHandleChildren .

À compter de Windows 7, si un pilote miniport d’affichage traite un appel à la fonction DxgkDdiCreateAllocation pour créer des allocations pour l’accélération matérielle GDI, le pilote doit définir la taille de l’allocation (y compris la valeur pitch pour les allocations visibles du processeur), pCreateAllocation-pAllocationInfo-Size>.>

Les ressources créées dans l’appel DxgkDdiCreateAllocation appartiennent à l’adaptateur et non à l’appareil. Le pilote miniport d’affichage ne doit pas référencer les données de l’appareil dans les structures de données d’allocation privée et de ressources. En raison du partage de surface, une ressource peut être utilisée après la destruction de l’appareil à partir duquel le pilote d’affichage en mode utilisateur a créé la ressource.

DxgkDdiCreateAllocation doit être rendu paginable.

Allocation de mémoires tampons d’historique

À partir de Windows 8.1, lorsque DxgkDdiCreateAllocation est appelé, le pilote miniport d’affichage peut définir le DXGK_ALLOCATIONINFOFLAGS.Membre HistoryBuffer pour indiquer que le pilote en mode utilisateur peut gérer la création et la destruction des mémoires tampons d’historique.