IDXGIKeyedMutex：：AcquireSync 方法 (dxgi.h)

项目
08/23/2023

使用密钥获取对共享资源的独占呈现访问权限。

语法

HRESULT AcquireSync(
  UINT64 Key,
  DWORD  dwMilliseconds
);

参数

Key

类型： UINT64

一个值，该值指示要授予访问权限的设备。当当前拥有 Surface 的设备使用相同的值调用 IDXGIKeyedMutex：：ReleaseSync 方法时，此方法将成功。此值可以是任何 UINT64 值。

dwMilliseconds

类型： DWORD

超时间隔（以毫秒为单位）。如果间隔已过，并且尚未使用指定的 Key 释放键的互斥体，则此方法将返回。如果此值设置为零， 则 AcquireSync 方法将测试是否已释放键锁互斥体并立即返回。如果此值设置为 INFINITE，则超时间隔永远不会经过。

返回值

类型： HRESULT

如果成功，则返回S_OK。

如果拥有的设备尝试在同一共享资源上创建另一个键锁互斥体， AcquireSync 将返回E_FAIL。

AcquireSync 还可以返回以下 DWORD 常量。因此，应显式检查这些常量。如果仅在返回值上使用 SUCCEEDED 宏来确定 AcquireSync 是否成功，则不会捕获这些常量。

WAIT_ABANDONED - 共享图面和键锁互斥体不再处于一致状态。如果 AcquireSync 返回此值，则应释放并重新创建键锁互斥体和共享图面。
WAIT_TIMEOUT - 释放指定键之前经过的超时间隔。

备注

AcquireSync 方法创建在多个设备之间共享的图面的锁，一次只允许一台设备呈现到图面。
此方法使用密钥来确定哪个设备当前具有对图面的独占访问权限。

使用 D3D10_RESOURCE_MISC_FLAG 枚举的D3D10_RESOURCE_MISC_SHARED_KEYEDMUTEX值创建图面时，必须先调用 AcquireSync 方法，然后才能呈现到图面。完成对图面的呈现后，必须调用 ReleaseSync 方法。

若要获取对共享资源的键化互斥对象的引用，请调用资源的 QueryInterface 方法并传入 IDXGIKeyedMutex 接口的 UUID。有关获取此引用的详细信息，请参阅以下代码示例。

AcquireSync 方法使用键，如下所示，具体取决于图面的状态：

在初始创建时，图面是无所有者的，任何设备都可以调用 AcquireSync 方法来获取访问权限。对于无所有者设备，只有密钥 0 将成功。为任何其他键调用 AcquireSync 方法将停止调用 CPU 线程。
如果在调用 AcquireSync 方法时设备拥有该图面，则调用 AcquireSync 方法的 CPU 线程将停止，直到拥有的设备使用相同的密钥调用 ReleaseSync 方法。
例如，如果在调用 AcquireSync 方法 (上一个拥有的设备已调用 ReleaseSync 方法) ，则如果指定上次调用 ReleaseSync 方法时指定的键，则 AcquireSync 方法将成功。使用任何其他键调用 AcquireSync 方法将导致停止。
当拥有的设备使用特定密钥调用 ReleaseSync 方法，并且多个设备在使用同一密钥调用 AcquireSync 方法后正在等待时，任何一个等待的设备都可能首先被唤醒。设备的唤醒顺序未定义。
键锁互斥体不支持对 AcquireSync 方法的递归调用。

示例

获取键锁互斥体

下面的代码示例演示如何获取共享资源的锁，以及如何在释放时指定密钥。


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