IDXGIKeyedMutex：：AcquireSync 方法 (dxgi.h)

發行項
08/23/2023

使用金鑰，取得共用資源的獨佔轉譯存取權。

語法

HRESULT AcquireSync(
  UINT64 Key,
  DWORD  dwMilliseconds
);

參數

Key

類型： UINT64

值，指出要授與存取權的裝置。當目前擁有介面的裝置使用相同的值呼叫 IDXGIKeyedMutex：：ReleaseSync 方法時，此方法將會成功。此值可以是任何 UINT64 值。

dwMilliseconds

類型： DWORD

逾時間隔，以毫秒為單位。如果間隔經過，而且索引鍵 Mutex 尚未使用指定的 Key釋放，這個方法會傳回。如果此值設定為零， AcquireSync 方法會測試是否已釋放索引鍵 Mutex 並立即傳回。如果此值設定為 INFINITE，則逾時間隔永遠不會經過。

傳回值

類型： HRESULT

如果成功，則傳回S_OK。

如果擁有的裝置嘗試在同一個共用資源上建立另一個索引鍵的 Mutex， AcquireSync 會傳回E_FAIL。

AcquireSync 也可以傳回下列 DWORD 常數。因此，您應該明確檢查這些常數。如果您只在傳回值上使用 SUCCEEDED 宏來判斷 AcquireSync 是否成功，則不會攔截這些常數。

WAIT_ABANDONED - 共用表面和索引鍵 Mutex 不再處於一致狀態。如果 AcquireSync 傳回此值，您應該釋放並重新建立索引鍵 Mutex 和共用介面。
WAIT_TIMEOUT - 在釋放指定索引鍵之前經過的逾時間隔。

備註

AcquireSync方法會建立多個裝置之間共用表面的鎖定，一次只允許一個裝置轉譯至表面。
此方法會使用金鑰來判斷目前哪些裝置具有介面的獨佔存取權。

使用D3D10_RESOURCE_MISC_FLAG列舉的D3D10_RESOURCE_MISC_SHARED_KEYEDMUTEX值建立介面時，您必須先呼叫AcquireSync方法，才能轉譯至介面。當您完成轉譯至介面時，必須呼叫 ReleaseSync 方法。

若要取得共用資源的索引鍵 mutex 物件的參考，請呼叫資源的QueryInterface方法，並傳入IDXGIKeyedMutex介面的UUID。如需取得此參考的詳細資訊，請參閱下列程式碼範例。

AcquireSync方法會使用金鑰，視介面的狀態而定：

在初始建立時，介面未擁有，且任何裝置都可以呼叫 AcquireSync 方法來取得存取權。對於未擁有的裝置，只有 0 的金鑰會成功。呼叫任何其他金鑰的 AcquireSync 方法將會停止呼叫 CPU 執行緒。
如果您在呼叫AcquireSync方法時，裝置擁有介面，則呼叫AcquireSync方法的 CPU 執行緒將會停止，直到擁有的裝置使用相同的 Key 呼叫ReleaseSync方法為止。
例如，如果您呼叫AcquireSync方法時未擁有介面 (，則最後一個擁有裝置已呼叫ReleaseSync方法) ，如果您指定了上次呼叫ReleaseSync方法時所指定的相同索引鍵，AcquireSync方法將會成功。使用任何其他索引鍵呼叫 AcquireSync 方法會導致停止。
當擁有的裝置使用特定金鑰呼叫 ReleaseSync 方法，且多個裝置在使用相同金鑰呼叫 AcquireSync 方法之後正在等候時，任何一個等候的裝置都可以先喚醒。裝置已喚醒的順序未定義。
索引鍵 Mutex 不支援 對 AcquireSync 方法的遞迴呼叫。

範例

取得索引鍵 Mutex

下列程式碼範例示範如何取得共用資源的鎖定，以及如何在發行時指定金鑰。


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