IDXGIKeyedMutex::AcquireSync-Methode (dxgi.h)

Artikel
08/23/2023

Mit einem Schlüssel wird exklusiver Renderingzugriff auf eine freigegebene Ressource abgerufen.

Syntax

HRESULT AcquireSync(
  UINT64 Key,
  DWORD  dwMilliseconds
);

Parameter

Key

Typ: UINT64

Ein -Wert, der angibt, auf welches Gerät Zugriff erteilt werden soll. Diese Methode ist erfolgreich, wenn das Gerät, das derzeit die Oberfläche besitzt, die IDXGIKeyedMutex::ReleaseSync-Methode mit demselben Wert aufruft. Dieser Wert kann ein beliebiger UINT64-Wert sein.

dwMilliseconds

Typ: DWORD

Das Timeoutintervall in Millisekunden. Diese Methode gibt zurück, wenn das Intervall verstrichen ist und der schlüsselierte Mutex nicht mithilfe des angegebenen Schlüssels freigegeben wurde. Wenn dieser Wert auf 0 festgelegt ist, testet die AcquireSync-Methode , ob der schlüsselierte Mutex freigegeben wurde, und gibt sofort zurück. Wenn dieser Wert auf INFINITE festgelegt ist, vergeht das Timeoutintervall nie.

Rückgabewert

Typ: HRESULT

Gibt bei erfolgreicher Ausführung S_OK zurück.

Wenn das besitzende Gerät versucht hat, einen weiteren Mutex mit Schlüssel für dieselbe freigegebene Ressource zu erstellen, gibt AcquireSync E_FAIL zurück.

AcquireSync kann auch die folgenden DWORD-Konstanten zurückgeben. Daher sollten Sie diese Konstanten explizit überprüfen. Wenn Sie nur das Makro SUCCEEDED für den Rückgabewert verwenden, um zu bestimmen, ob AcquireSync erfolgreich war, werden diese Konstanten nicht abfangen.

WAIT_ABANDONED: Die freigegebene Oberfläche und der Schlüsselmutex befinden sich nicht mehr in einem konsistenten Zustand. Wenn AcquireSync diesen Wert zurückgibt, sollten Sie sowohl den schlüsselierten Mutex als auch die freigegebene Oberfläche freigeben und neu erstellen.
WAIT_TIMEOUT: Das Timeoutintervall, das verstrichen ist, bevor der angegebene Schlüssel freigegeben wurde.

Hinweise

Die AcquireSync-Methode erstellt eine Sperre für eine Oberfläche, die von mehreren Geräten gemeinsam genutzt wird, sodass jeweils nur ein Gerät auf einer Oberfläche gerendert werden kann.
Diese Methode verwendet einen Schlüssel, um zu bestimmen, welches Gerät derzeit exklusiven Zugriff auf das Surface hat.

Wenn eine Oberfläche mit dem D3D10_RESOURCE_MISC_SHARED_KEYEDMUTEX-Wert der D3D10_RESOURCE_MISC_FLAG-Enumeration erstellt wird, müssen Sie die AcquireSync-Methode aufrufen, bevor Sie auf der Oberfläche rendern. Sie müssen die ReleaseSync-Methode aufrufen, wenn Sie mit dem Rendern auf einem Surface fertig sind.

Um einen Verweis auf das schlüsselierte Mutex-Objekt einer freigegebenen Ressource abzurufen, rufen Sie die QueryInterface-Methode der Ressource auf, und übergeben Sie die UUID der IDXGIKeyedMutex-Schnittstelle . Weitere Informationen zum Abrufen dieser Referenz finden Sie im folgenden Codebeispiel.

Die AcquireSync-Methode verwendet den Schlüssel abhängig vom Zustand der Oberfläche wie folgt:

Bei der ersten Erstellung ist die Oberfläche nicht vorhanden, und jedes Gerät kann die AcquireSync-Methode aufrufen, um Zugriff zu erhalten. Bei einem nicht verwendeten Gerät ist nur der Schlüssel 0 erfolgreich. Wenn Sie die AcquireSync-Methode für einen anderen Schlüssel aufrufen, wird der aufrufende CPU-Thread blockiert.
Wenn sich die Oberfläche im Besitz eines Geräts befindet, wenn Sie die AcquireSync-Methode aufrufen, wird der CPU-Thread, der die AcquireSync-Methode aufgerufen hat, angehalten, bis das besitzende Gerät die ReleaseSync-Methode mit demselben Schlüssel aufruft.
Wenn die Oberfläche beim Aufrufen der AcquireSync-Methode nicht vorhanden ist (z. B. hat das letzte besitzende Gerät bereits die ReleaseSync-Methode aufgerufen), ist die AcquireSync-Methode erfolgreich, wenn Sie denselben Schlüssel angeben, der beim letzten Aufruf der ReleaseSync-Methode angegeben wurde. Das Aufrufen der AcquireSync-Methode mit einem anderen Schlüssel führt zu einem Stillstand.
Wenn das besitzende Gerät die ReleaseSync-Methode mit einem bestimmten Schlüssel aufruft und mehr als ein Gerät nach dem Aufruf der AcquireSync-Methode mit demselben Schlüssel wartet, kann eines der wartenden Geräte zuerst aktiviert werden. Die Reihenfolge, in der Geräte aktiviert werden, ist nicht definiert.
Ein mit Schlüssel versehener Mutex unterstützt keine rekursiven Aufrufe der AcquireSync-Methode .

Beispiele

Abrufen eines Schlüsselmutex

Im folgenden Codebeispiel wird veranschaulicht, wie Sie eine Sperre für eine freigegebene Ressource abrufen und einen Schlüssel bei der Freigabe angeben.


// 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);