Procédure pas à pas : capture d'informations Graphics par programmation

  • Article

Vous pouvez utiliser les outils Graphics Diagnostics de Visual Studio pour capturer par programmation les informations graphiques d'une application Direct3D.

La capture par programmation est particulièrement utile pour déboguer les nuanceurs de calcul dans les programmes qui n'appellent jamais Present ou quand un problème de rendu est difficile à prévoir et à capturer dans le cadre d'un test manuel, mais qui peut être prédit par programmation à partir d'informations sur l'état de l'application au moment de l'exécution.

Capture par programmation dans DirectX 11.2

Cette partie de la procédure pas à pas illustre la capture par programmation dans des applications qui utilisent l'API DirectX 11.2, qui elle-même utilise la méthode de capture robuste. Pour plus d'informations sur l'utilisation de la capture par programmation dans les applications qui utilisent des versions antérieures de DirectX, voir Programmatic capture in DirectX 11.1 and earlier plus loin dans cette procédure pas à pas.

Cette section montre comment effectuer ces tâches :

  • Préparation de votre application à l'utilisation de la capture par programmation

  • Obtention de l'interface IDXGraphicsAnalysis

  • Capture d'informations graphiques

Notes

Si les implémentations précédentes de la capture par programmation dépendaient des Outils de contrôle à distance de Visual Studio pour proposer la fonctionnalité de capture, DirectX 11.2 prend directement en charge la capture.Ainsi, vous n'avez plus besoin d'installer les Outils de contrôle à distance pour mettre en œuvre la capture par programmation dans les applications qui utilisent l'API DirectX 11.2.

Préparation de votre application à l'utilisation de la capture par programmation

Préparer votre application Direct3D 11.2 à utiliser la capture par programmation est un processus en deux étapes. En premier lieu, veillez à inclure les fichiers d'en-tête nécessaires à la capture par programmation, puis définissez l'interface IDXGraphicsAnalysis dans le code source de votre application.

Pour inclure les en-têtes de capture par programmation

  • Incluez les en-têtes suivants dans le fichier source où sera définie l'interface IDXGraphicsAnalysis :

    #include <DXGItype.h>
#include <dxgi1_2.h>
#include <dxgi1_3.h>

    Important

    N'incluez pas le fichier d'en-tête vsgcapture.h (qui prend en charge la capture par programmation dans DirectX version 11.1 et antérieures) pour exécuter la capture par programmation dans vos applications DirectX 11.2.Cet en-tête est incompatible avec DirectX 11.2.Si ce fichier est inclus après l'en-tête d3d11_2, le compilateur émet un avertissement.Si vsgcapture.h est inclus avant d3d11_2, l'application ne démarre pas.

    Notes

    Si le Kit de développement logiciel (SDK) DirectX de juin 2010 est installé sur votre ordinateur et que le chemin d'accès include de votre projet contient %DXSDK_DIR%include\x86, déplacez-le à la fin du chemin d'accès include.Faites-en autant pour le chemin d'accès à votre bibliothèque.

Pour définir l'interface IDXGraphicsAnalysis

  • Définissez l'interface IDXGraphicsAnalysis dans le fichier où vous avez inclus les fichiers d'en-tête.

    interface DECLSPEC_UUID("9f251514-9d4d-4902-9d60-18988ab7d4b5") DECLSPEC_NOVTABLE
IDXGraphicsAnalysis : public IUnknown
{
    STDMETHOD_(void, BeginCapture)() PURE;
    STDMETHOD_(void, EndCapture)() PURE;
};

Pour des raisons pratiques, vous pouvez effectuer ces étapes dans un nouveau fichier d'en-tête et l'inclure là où votre application en a besoin.

Obtention de l'interface IDXGraphicsAnalysis

Avant de pouvoir capturer les informations graphiques de DirectX 11.2, vous devez créer une interface pour l'interface de débogage DXGI.

Pour obtenir l'interface IDXGraphicsAnalysis

  • Utilisez le code suivant pour raccorder l'interface IDXGraphicsAnalysis à l'interface de débogage DXGI.

    IDXGraphicsAnalysis* pGraphicsAnalysis;
HRESULT getAnalysis = DXGIGetDebugInterface1(0, __uuidof(pGraphicsAnalysis), reinterpret_cast<void**>(&pGraphicsAnalysis));

    Veillez à examiner le HRESULT retourné par DXGIGetDebugInterface1 pour vous assurer d'obtenir une interface valide avant de l'utiliser :

    if (FAILED(getAnalysis))
{
    // Abort program or disable programmatic capture in your app.
}

    Notes

    Si l'application ne s'exécute pas sous Graphics Diagnostics (Alt+F5 dans Visual Studio), DXGIGetDebugInterface1 retourne une erreur : E_NOINTERFACE Aucune interface de ce type n’est prise en charge.

Capture d'informations graphiques

Maintenant que vous avez une interface IDXGraphicsAnalysis valide, vous pouvez utiliser BeginCapture et EndCapture pour capturer des informations graphiques.

Pour capturer des informations graphiques

  • Pour commencer à capturer des informations graphiques, utilisez BeginCapture :

    ...
pGraphicsAnalysis->BeginCapture();
...

    La capture commence de suite après l'appel de BeginCapture ; il n'attend pas le frame suivant pour commencer. La capture s'arrête dès la présentation du frame actif ou l'appel de EndCapture :

    ...
pGraphicsAnalysis->EndCapture();
...

Capture par programmation dans DirectX version 11.1 et antérieures

Cette partie de la procédure pas à pas illustre la capture par programmation dans des applications qui utilisent l'API DirectX 11.1, qui elle-même utilise la méthode de capture héritée. Pour plus d'informations sur l'utilisation de la capture par programmation dans les applications qui utilisent DirectX 11.2, voir Programmatic capture in DirectX 11.2 plus haut dans cette procédure pas à pas.

Cette partie présente les tâches suivantes :

  • Préparation de votre ordinateur à l'utilisation de la capture par programmation

  • Préparation de votre application à l'utilisation de la capture par programmation

  • Configuration du nom et de l'emplacement du fichier journal de graphisme

  • Utilisation de l'API CaptureCurrentFrame

Préparation de votre ordinateur à l'utilisation de la capture par programmation

L'API de capture par programmation utilise les Outils de contrôle à distance de Visual Studio pour proposer la fonctionnalité de capture. Les Outils de contrôle à distance doivent être installés sur l'ordinateur destiné à exécuter l'application, même quand vous utilisez la capture par programmation sur votre ordinateur local. Visual Studio n'a pas besoin de s'exécuter quand vous effectuez une capture par programmation sur un ordinateur local.

Pour utiliser les API de capture distante dans une application qui s'exécute sur un ordinateur, vous devez d'abord installer les Outils de contrôle à distance de Visual Studio sur cet ordinateur. Les plateformes matérielles prises en charge varient en fonction de la version des Outils de contrôle à distance. Pour plus d'informations sur l'installation des Outils de contrôle à distance, voir la page de téléchargement des Outils de contrôle à distance sur le site web Téléchargements de Microsoft.

Sinon, Visual Studio installe les composants nécessaires pour assurer la capture distante pour les applications 32 bits.

Notes

Comme la plupart des applications de bureau Windows (y compris Visual Studio) ne sont pas prises en charge sous Windows 8 pour les appareils ARM, l'utilisation conjointe des Outils de contrôle à distance de Visual Studio et de l'API de capture par programmation est le seul moyen de capturer les diagnostics graphiques sur les appareils ARM.

Préparation de votre application à l'utilisation de la capture par programmation

Pour utiliser les outils Graphics Diagnostics, vous devez d'abord capturer les informations graphiques dont ils ont besoin. Vous pouvez capturer par programmation les informations à l'aide de l'API CaptureCurrentFrame.

Pour préparer votre application à la capture d'informations graphiques par programmation

  1. Assurez-vous que l'en-tête vsgcapture.h est inclus dans le code source de l'application. Il peut être inclus à un seul emplacement (par exemple, dans le fichier de code source où vous prévoyez d'appeler l'API de capture par programmation) ou dans un fichier d'en-tête précompilé pour appeler l'API à partir de plusieurs fichiers de code source.

  2. Dans le code source de l'application, chaque fois que vous voulez capturer le reste du frame actif, appelez g_pVsgDbg->CaptureCurrentFrame(). Cette méthode ne fait appel à aucun paramètre et ne retourne aucune valeur.

Configuration du nom et de l'emplacement du fichier journal de graphisme

Le journal de graphisme est créé à l'emplacement défini par les macros DONT_SAVE_VSGLOG_TO_TEMP et VSG_DEFAULT_RUN_FILENAME.

Pour configurer le nom et l'emplacement du fichier journal de graphisme

  • Pour éviter que le journal de graphisme soit écrit dans le répertoire temporaire, avant la ligne #include <vsgcapture.h>, ajoutez ceci :

    #define DONT_SAVE_VSGLOG_TO_TEMP

    Vous pouvez définir cette valeur pour écrire le journal de graphisme à un emplacement relatif au répertoire de travail ou dans un chemin d'accès absolu si la définition de VSG_DEFAULT_RUN_FILENAME est un chemin d'accès absolu.

  • Pour enregistrer le journal de graphisme à un emplacement différent ou pour lui donner un autre nom de fichier, avant la ligne #include <vsgcapture.h>, ajoutez ceci :

    #define VSG_DEFAULT_RUN_FILENAME <filename>

    Si vous n'effectuez pas cette étape, le nom de fichier est default.vsglog. Si vous n'avez pas défini DONT_SAVE_VSGLOG_TO_TEMP, l'emplacement du fichier est relatif au répertoire temporaire ; sinon, il est relatif au répertoire de travail ou se situe à un autre emplacement si vous avez spécifié un nom de fichier absolu.

Pour les applications Windows Store, l'emplacement du répertoire temporaire est propre à chaque utilisateur et application. Il se trouve généralement à un emplacement tel que C:\users\nom_utilisateur\AppData\Local\Packages\nom de famille du package\TempState\. Pour les applications de bureau, l'emplacement du répertoire temporaire est propre à chaque utilisateur et se trouve généralement à un emplacement tel que C:\Users\nom_utilisateur\AppData\Local\Temp\.

Notes

Pour écrire à un emplacement spécifique, vous devez avoir des autorisations d'accès en écriture à cet emplacement ; sinon, une erreur se produit.Gardez à l'esprit que les applications Windows Store sont plus limitées que les applications de bureau en ce qui concerne l'écriture des données et qu'une configuration supplémentaire peut être nécessaire pour leur permettre d'écrire à certains emplacements.

Capture des informations graphiques

Après avoir préparé l'application à la capture par programmation et éventuellement configuré l'emplacement et le nom du fichier journal de graphisme, générez, puis exécutez ou déboguez l'application pour capturer les données ; ne démarrez pas Graphics Diagnostics à partir de Visual Studio quand vous utilisez l'API de capture par programmation. Le journal de graphisme est écrit à l'emplacement que vous avez spécifié. Si vous voulez conserver cette version du journal, déplacez-le à un autre emplacement ; à défaut, il sera remplacé quand vous exécuterez à nouveau l'application.

Conseil

Vous pouvez toujours capturer les informations graphiques manuellement pendant que vous utilisez la capture par programmation : il vous suffit d'appuyer sur Impr. écran pendant que l'application a le focus.Vous pouvez employer cette technique pour capturer des informations graphiques supplémentaires qui ne sont pas capturées par l'API de capture par programmation.

Étapes suivantes

Cette procédure pas à pas vous a montré comment capturer des informations graphiques par programmation. Pour franchir une étape supplémentaire, envisagez cette possibilité :

Voir aussi

Tâches

Procédure pas à pas : capture d'informations Graphics

Concepts

Capture d'informations Graphics