ID3D11DeviceContext ::Map, méthode (d3d11.h)

Article
08/22/2023

Obtient un pointeur vers les données contenues dans une sous-ressource et refuse l’accès GPU à cette sous-ressource.

Syntaxe

HRESULT Map(
  [in]            ID3D11Resource           *pResource,
  [in]            UINT                     Subresource,
  [in]            D3D11_MAP                MapType,
  [in]            UINT                     MapFlags,
  [out, optional] D3D11_MAPPED_SUBRESOURCE *pMappedResource
);

Paramètres

[in] pResource

Type : ID3D11Resource*

Pointeur vers une interface ID3D11Resource .

[in] Subresource

Type : UINT

Numéro d’index de la sous-ressource.

[in] MapType

Type : D3D11_MAP

Valeur de type D3D11_MAP qui spécifie les autorisations de lecture et d’écriture du processeur pour une ressource.

[in] MapFlags

Type : UINT

Indicateur qui spécifie ce que fait l’UC lorsque le GPU est occupé. Cet indicateur est facultatif.

[out, optional] pMappedResource

Type : D3D11_MAPPED_SUBRESOURCE*

Pointeur vers la structure D3D11_MAPPED_SUBRESOURCE pour la sous-ressource mappée. Consultez la section Remarques concernant les pointeurs NULL.

Valeur retournée

Type : HRESULT

Cette méthode retourne l’un des codes de retour Direct3D 11.

Cette méthode retourne également DXGI_ERROR_WAS_STILL_DRAWING si MapFlags spécifie D3D11_MAP_FLAG_DO_NOT_WAIT et que le GPU n’est pas encore terminé avec la ressource.

Cette méthode retourne également DXGI_ERROR_DEVICE_REMOVED si MapType autorise l’accès en lecture au processeur et que le carte vidéo a été supprimé.

Pour plus d’informations sur ces codes d’erreur, consultez DXGI_ERROR.

Remarques

Si vous appelez Map sur un contexte différé, vous pouvez uniquement passer D3D11_MAP_WRITE_DISCARD, D3D11_MAP_WRITE_NO_OVERWRITE ou les deux au paramètre MapType . Les autres valeurs de type D3D11_MAP ne sont pas prises en charge pour un contexte différé.

Note Le runtime Direct3D 11.1, disponible à partir de Windows 8, permet de mapper des mémoires tampons constantes dynamiques et des vues de ressources de nuanceur (SMV) des mémoires tampons dynamiques avec D3D11_MAP_WRITE_NO_OVERWRITE. Les runtimes Direct3D 11 et antérieurs limitaient le mappage aux tampons de vertex ou d’index. Pour déterminer si un appareil Direct3D prend en charge ces fonctionnalités, appelez ID3D11Device ::CheckFeatureSupport avec D3D11_FEATURE_D3D11_OPTIONS. CheckFeatureSupport remplit les membres d’une structure D3D11_FEATURE_DATA_D3D11_OPTIONS avec les fonctionnalités de l’appareil. Les membres concernés ici sont MapNoOverwriteOnDynamicConstantBuffer et MapNoOverwriteOnDynamicBufferSRV.

Pour plus d’informations sur l’utilisation de Map, consultez Guide pratique pour utiliser des ressources dynamiques.

Pointeurs NULL pour pMappedResource

Le paramètre pMappedResource peut avoir la valeur NULL lorsqu’une texture créée avec D3D11_USAGE_DEFAULT est fournie et que l’API est appelée sur un contexte immédiat. Cela permet de mapper une texture par défaut, même si elle a été créée à l’aide de D3D11_TEXTURE_LAYOUT_UNDEFINED. Après cet appel d’API, la texture est accessible à l’aide de ID3D11DeviceContext3 ::WriteToSubresource et/ou ID3D11DeviceContext3 ::ReadFromSubresource.

Ne pas lire à partir d’une sous-ressource mappée pour l’écriture

Lorsque vous transmettez D3D11_MAP_WRITE, D3D11_MAP_WRITE_DISCARD ou D3D11_MAP_WRITE_NO_OVERWRITE au paramètre MapType , vous devez vous assurer que votre application ne lit pas les données de sous-ressource vers lesquelles le membre pData de D3D11_MAPPED_SUBRESOURCE pointe, car cela peut entraîner une pénalité importante en matière de performances. Région de mémoire à laquelle les points pData peuvent être alloués avec PAGE_WRITECOMBINE, et votre application doit respecter toutes les restrictions associées à cette mémoire.

Remarque

Même le code C++ suivant peut lire à partir de la mémoire et déclencher une pénalité de performances, car le code peut être étendu au code d’assembly x86 suivant.

Code C++ :

*((int*)MappedResource.pData) = 0;

Code d’assembly x86 :

AND DWORD PTR [EAX],0

Utilisez les paramètres d’optimisation et les constructions linguistiques appropriés pour éviter cette pénalité de performances. Par exemple, vous pouvez éviter l’optimisation xor à l’aide d’un pointeur volatile ou en optimisant la vitesse du code au lieu de la taille du code.

Windows Phone 8 : Cette API est prise en charge.

Configuration requise

Condition requise	Valeur
Plateforme cible	Windows
En-tête	d3d11.h
Bibliothèque	D3D11.lib

Voir aussi

ID3D11DeviceContext