Метод IDXGIKeyedMutex::AcquireSync (dxgi.h)

Статья
08/23/2023

Используя ключ, получает монопольный доступ отрисовки к общему ресурсу.

Синтаксис

HRESULT AcquireSync(
  UINT64 Key,
  DWORD  dwMilliseconds
);

Параметры

Key

Тип: UINT64

Значение типа , указывающее, к какому устройству следует предоставить доступ. Этот метод будет успешным, если устройство, которому в настоящее время принадлежит surface, вызывает метод IDXGIKeyedMutex::ReleaseSync , используя то же значение. Это может быть любое значение UINT64.

dwMilliseconds

Тип: DWORD

Интервал времени ожидания в миллисекундах. Этот метод возвращает значение , если интервал истек, а мьютекс с ключом не был освобожден с помощью указанного ключа. Если это значение равно нулю, метод AcquireSync проверит, был ли освобожден мьютекс ключа, и немедленно возвращается. Если для этого значения задано значение INFINITE, интервал времени ожидания никогда не истедет.

Возвращаемое значение

Тип: HRESULT

В случае успешного выполнения верните S_OK.

Если устройство-владельце попыталось создать другой мьютекс с ключом в том же общем ресурсе, AcquireSync возвращает E_FAIL.

AcquireSync также может возвращать следующие константы DWORD . Поэтому для этих констант следует явно проверка. Если вы используете только макрос SUCCEEDED в возвращаемом значении, чтобы определить успешность AcquireSync , вы не будете перехватывать эти константы.

WAIT_ABANDONED — общая поверхность и мьютекс с ключом больше не находятся в согласованном состоянии. Если AcquireSync возвращает это значение, следует освободить и повторно создать мьютекс с ключом и общую поверхность.
WAIT_TIMEOUT — время ожидания истекло до освобождения указанного ключа.

Метод AcquireSync создает блокировку для поверхности, которая совместно используется несколькими устройствами, позволяя только одному устройству выполнять отрисовку на поверхности одновременно.
Этот метод использует ключ, чтобы определить, какое устройство в настоящее время имеет монопольный доступ к поверхности.

При создании поверхности с использованием D3D10_RESOURCE_MISC_SHARED_KEYEDMUTEX значения перечисления D3D10_RESOURCE_MISC_FLAG необходимо вызвать метод AcquireSync перед отрисовкой на поверхности. При завершении отрисовки на поверхности необходимо вызвать метод ReleaseSync .

Чтобы получить ссылку на объект мьютекса с ключом общего ресурса, вызовите метод QueryInterface ресурса и передайте UUID интерфейса IDXGIKeyedMutex . Дополнительные сведения о получении этой ссылки см. в следующем примере кода.

Метод AcquireSync использует ключ следующим образом в зависимости от состояния поверхности:

При первоначальном создании поверхность не является владельцем, и любое устройство может вызвать метод AcquireSync для получения доступа. Для устройства без владельца будет выполнено только нажатие ключа 0. Вызов метода AcquireSync для любого другого ключа приведет к остановке вызывающего потока ЦП.
Если поверхность принадлежит устройству при вызове метода AcquireSync , поток ЦП, который вызвал метод AcquireSync , будет остановлен до тех пор, пока устройство-владеющее устройство не вызовет метод ReleaseSync с помощью того же ключа.
Если поверхность не является владельцем при вызове метода AcquireSync (например, последнее устройство-владение уже вызывало метод ReleaseSync ), метод AcquireSync будет успешным, если указать тот же ключ, который был указан при последнем вызове метода ReleaseSync . Вызов метода 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);