IDXGIKeyedMutex::AcquireSync, méthode (dxgi.h)

Article
08/23/2023

À l’aide d’une clé, acquiert un accès de rendu exclusif à une ressource partagée.

Syntaxe

HRESULT AcquireSync(
  UINT64 Key,
  DWORD  dwMilliseconds
);

Paramètres

Key

Type : UINT64

Valeur qui indique l’appareil auquel accorder l’accès. Cette méthode réussit lorsque l’appareil qui possède actuellement la surface appelle la méthode IDXGIKeyedMutex::ReleaseSync à l’aide de la même valeur. Cette valeur peut être n’importe quelle valeur UINT64.

dwMilliseconds

Type : DWORD

Intervalle de délai d’attente, en millisecondes. Cette méthode retourne si l’intervalle s’écoule et que le mutex à clé n’a pas été libéré à l’aide de la clé spécifiée. Si cette valeur est définie sur zéro, la méthode AcquireSync teste pour voir si le mutex à clé a été libéré et retourne immédiatement. Si cette valeur est définie sur INFINITE, l’intervalle de délai d’attente ne s’écoulera jamais.

Valeur retournée

Type : HRESULT

Retournez S_OK en cas de réussite.

Si l’appareil propriétaire a tenté de créer un autre mutex à clé sur la même ressource partagée, AcquireSync retourne E_FAIL.

AcquireSync peut également retourner les constantes DWORD suivantes. Par conséquent, vous devez case activée explicitement pour ces constantes. Si vous utilisez uniquement la macro SUCCEEDED sur la valeur de retour pour déterminer si AcquireSync a réussi, vous n’interceptez pas ces constantes.

WAIT_ABANDONED : la surface partagée et le mutex à clé ne sont plus dans un état cohérent. Si AcquireSync retourne cette valeur, vous devez libérer et recréer à la fois le mutex à clé et la surface partagée.
WAIT_TIMEOUT : intervalle de délai d’attente écoulé avant la libération de la clé spécifiée.

Notes

La méthode AcquireSync crée un verrou sur une surface partagée entre plusieurs appareils, ce qui permet à un seul appareil de s’afficher sur une surface à la fois.
Cette méthode utilise une clé pour déterminer quel appareil dispose actuellement d’un accès exclusif à la surface.

Lorsqu’une surface est créée à l’aide de la valeur D3D10_RESOURCE_MISC_SHARED_KEYEDMUTEX de l’énumération D3D10_RESOURCE_MISC_FLAG , vous devez appeler la méthode AcquireSync avant le rendu sur la surface. Vous devez appeler la méthode ReleaseSync lorsque vous avez terminé le rendu sur une surface.

Pour acquérir une référence à l’objet mutex à clé d’une ressource partagée, appelez la méthode QueryInterface de la ressource et transmettez l’UUID de l’interface IDXGIKeyedMutex . Pour plus d’informations sur l’acquisition de cette référence, consultez l’exemple de code suivant.

La méthode AcquireSync utilise la clé comme suit, en fonction de l’état de la surface :

Lors de la création initiale, la surface n’est pas propriétaire et n’importe quel appareil peut appeler la méthode AcquireSync pour y accéder. Pour un appareil non propriétaire, seule une clé de 0 réussit. L’appel de la méthode AcquireSync pour toute autre clé bloque le thread d’UC appelant.
Si la surface appartient à un appareil lorsque vous appelez la méthode AcquireSync , le thread de processeur qui a appelé la méthode AcquireSync se bloque jusqu’à ce que l’appareil propriétaire appelle la méthode ReleaseSync à l’aide de la même clé.
Si la surface n’est pas propriétaire lorsque vous appelez la méthode AcquireSync (par exemple, le dernier appareil propriétaire a déjà appelé la méthode ReleaseSync ), la méthode AcquireSync réussit si vous spécifiez la même clé qui a été spécifiée lors du dernier appel de la méthode ReleaseSync . L’appel de la méthode AcquireSync à l’aide d’une autre clé entraîne un blocage.
Lorsque l’appareil propriétaire appelle la méthode ReleaseSync avec une clé particulière et que plusieurs appareils attendent après avoir appelé la méthode AcquireSync à l’aide de la même clé, l’un des appareils en attente peut être réveillé en premier. L’ordre dans lequel les appareils sont réveillés n’est pas défini.
Un mutex à clé ne prend pas en charge les appels récursifs à la méthode AcquireSync .

Exemples

Acquisition d’un mutex à clé

L’exemple de code suivant montre comment acquérir un verrou sur une ressource partagée et comment spécifier une clé lors de la mise en production.


// pDesc has already been set up with texture description.
pDesc.MiscFlags = D3D10_RESOURCE_MISC_SHARED_KEYEDMUTEX;

// Create a shared texture resource.
pD3D10DeviceD->CreateTexture2D(pDesc, NULL, pD3D10Texture);

// Acquire a reference to the keyed mutex.
pD3D10Texture->QueryInterface(_uuidof(IDXGIKeyedMutex), pDXGIKeyedMutex);

// Acquire a lock to the resource.
pDXGIKeyedMutex->AcquireSync(0, INFINITE);

// Release the lock and specify a key.
pDXGIKeyedMutex->ReleaseSync(1);