IDXGIFactory ::CreateSwapChain, méthode (dxgi.h)

Article
08/23/2023

[À compter de Direct3D 11.1, nous vous recommandons de ne plus utiliser CreateSwapChain pour créer une chaîne d’échange. Utilisez plutôt CreateSwapChainForHwnd, CreateSwapChainForCoreWindow ou CreateSwapChainForComposition selon la façon dont vous souhaitez créer la chaîne d’échange.]

Crée une chaîne d’échange.

Syntaxe

HRESULT CreateSwapChain(
  [in]  IUnknown             *pDevice,
  [in]  DXGI_SWAP_CHAIN_DESC *pDesc,
  [out] IDXGISwapChain       **ppSwapChain
);

Paramètres

[in] pDevice

Type : IUnknown*

Pour Direct3D 11 et les versions antérieures de Direct3D, il s’agit d’un pointeur vers l’appareil Direct3D pour la chaîne d’échange. Pour Direct3D 12, il s’agit d’un pointeur vers une file d’attente de commandes directes (reportez-vous à ID3D12CommandQueue). Ce paramètre ne peut pas être NULL.

[in] pDesc

Type : DXGI_SWAP_CHAIN_DESC*

Pointeur vers une structure de DXGI_SWAP_CHAIN_DESC pour la description de la chaîne d’échange. Ce paramètre ne peut pas être NULL.

[out] ppSwapChain

Type : IDXGISwapChain**

Pointeur vers une variable qui reçoit un pointeur vers l’interface IDXGISwapChain pour la chaîne d’échange créée par CreateSwapChain .

Valeur retournée

Type : HRESULT

DXGI_ERROR_INVALID_CALL si pDesc ou ppSwapChain a la valeur NULL, DXGI_STATUS_OCCLUDED si vous demandez le mode plein écran et qu’il n’est pas disponible, ou E_OUTOFMEMORY. D’autres codes d’erreur définis par le type d’appareil passé peuvent également être retournés.

Remarques

Note Si vous appelez cette API dans un processus session 0, elle retourne DXGI_ERROR_NOT_CURRENTLY_AVAILABLE.

Si vous tentez de créer une chaîne d’échange en mode plein écran et que le mode plein écran n’est pas disponible, la chaîne d’échange est créée en mode fenêtré et DXGI_STATUS_OCCLUDED est retournée.

Si la largeur de la mémoire tampon ou la hauteur de la mémoire tampon est égale à zéro, les tailles sont déduites de la taille de la fenêtre de sortie dans la description de la chaîne d’échange.

Étant donné que la sortie cible ne peut pas être choisie explicitement lors de la création de la chaîne d’échange, nous vous recommandons de ne pas créer de chaîne d’échange en plein écran. Cela peut réduire les performances de la présentation si la taille de la chaîne d’échange et la taille de la fenêtre de sortie ne correspondent pas. Voici deux façons de s’assurer que les tailles correspondent :

Créez une chaîne d’échange fenêtré, puis définissez-la en plein écran à l’aide de IDXGISwapChain ::SetFullscreenState.
Enregistrez un pointeur vers la chaîne d’échange immédiatement après la création et utilisez-le pour obtenir la taille de la fenêtre de sortie pendant un événement WM_SIZE. Redimensionnez ensuite les mémoires tampons de la chaîne d’échange (avec IDXGISwapChain ::ResizeBuffers) pendant la transition de fenêtres à plein écran.

Si la chaîne d’échange est en mode plein écran, avant de la libérer, vous devez utiliser SetFullscreenState pour la basculer en mode fenêtré. Pour plus d’informations sur la libération d’une chaîne d’échange, consultez la section « Destruction d’une chaîne d’échange » dans vue d’ensemble de DXGI.

Une fois que le runtime a rendu l’image initiale en plein écran, le runtime peut quitter le plein écran de manière inattendue lors d’un appel à IDXGISwapChain ::P resent. Pour contourner ce problème, nous vous recommandons d’exécuter le code suivant juste après avoir appelé CreateSwapChain pour créer une chaîne d’échange plein écran (membre fenêtré de DXGI_SWAP_CHAIN_DESC défini sur FALSE).


// Detect if newly created full-screen swap chain isn't actually full screen.
IDXGIOutput* pTarget; BOOL bFullscreen;
if (SUCCEEDED(pSwapChain->GetFullscreenState(&bFullscreen, &pTarget)))
{
   pTarget->Release();
}
else
   bFullscreen = FALSE;
// If not full screen, enable full screen again.
if (!bFullscreen)
{
   ShowWindow(hWnd, SW_MINIMIZE);
   ShowWindow(hWnd, SW_RESTORE);
   pSwapChain->SetFullscreenState(TRUE, NULL);
}

Vous pouvez spécifier DXGI_SWAP_EFFECT et DXGI_SWAP_CHAIN_FLAG valeurs dans la description de la chaîne d’échange vers laquelle pDesc pointe. Ces valeurs vous permettent d’utiliser des fonctionnalités telles que la présentation de modèle inversé et la protection du contenu à l’aide d’API pré-Windows 8.

Toutefois, pour utiliser la présentation stéréo et modifier le comportement de redimensionnement du modèle de retournement, les applications doivent utiliser la méthode IDXGIFactory2 ::CreateSwapChainForHwnd . Sinon, le contenu de la mémoire tampon d’arrière-mémoire est mis à l’échelle implicitement pour s’adapter à la taille cible de présentation ; Autrement dit, vous ne pouvez pas désactiver la mise à l’échelle.

Remarques pour les applications du Windows Store

Si une application du Windows Store appelle CreateSwapChain avec le mode plein écran spécifié, CreateSwapChain échoue.

Les applications du Windows Store appellent la méthode IDXGIFactory2 ::CreateSwapChainForCoreWindow pour créer une chaîne d’échange.

Pour plus d’informations sur le choix d’un format pour la mémoire tampon d’arrière-plan de la chaîne d’échange, consultez Conversion de données pour l’espace de couleurs.