Método IDXGIKeyedMutex::AcquireSync (dxgi.h)

Artigo
08/23/2023

Usando uma chave, adquire acesso de renderização exclusivo a um recurso compartilhado.

Sintaxe

HRESULT AcquireSync(
  UINT64 Key,
  DWORD  dwMilliseconds
);

Parâmetros

Key

Tipo: UINT64

Um valor que indica a qual dispositivo conceder acesso. Esse método terá êxito quando o dispositivo que atualmente possui a superfície chamar o método IDXGIKeyedMutex::ReleaseSync usando o mesmo valor. Esse valor pode ser qualquer valor UINT64.

dwMilliseconds

Tipo: DWORD

O intervalo de tempo limite em milissegundos. Esse método retornará se o intervalo decorrido e o mutex com chave não tiver sido liberado usando a chave especificada. Se esse valor for definido como zero, o método AcquireSync testará para ver se o mutex com chave foi liberado e retornará imediatamente. Se esse valor for definido como INFINITE, o intervalo de tempo limite nunca será decorrido.

Valor retornado

Tipo: HRESULT

Retorne S_OK se tiver êxito.

Se o dispositivo proprietário tentou criar outro mutex com chave no mesmo recurso compartilhado, AcquireSync retornará E_FAIL.

AcquireSync também pode retornar as seguintes constantes DWORD . Portanto, você deve marcar explicitamente para essas constantes. Se você usar apenas a macro SUCCEEDED no valor retornado para determinar se AcquireSync foi bem-sucedido, não capturará essas constantes.

WAIT_ABANDONED - A superfície compartilhada e o mutex com chave não estão mais em um estado consistente. Se AcquireSync retornar esse valor, você deverá liberar e recriar o mutex com chave e a superfície compartilhada.
WAIT_TIMEOUT – o intervalo de tempo limite decorrido antes do lançamento da chave especificada.

Comentários

O método AcquireSync cria um bloqueio para uma superfície que é compartilhada entre vários dispositivos, permitindo que apenas um dispositivo seja renderizado em uma superfície de cada vez.
Esse método usa uma chave para determinar qual dispositivo atualmente tem acesso exclusivo à superfície.

Quando uma superfície é criada usando o valor D3D10_RESOURCE_MISC_SHARED_KEYEDMUTEX da enumeração D3D10_RESOURCE_MISC_FLAG , você deve chamar o método AcquireSync antes de renderizar para a superfície. Você deve chamar o método ReleaseSync quando terminar de renderizar para uma superfície.

Para adquirir uma referência ao objeto mutex com chave de um recurso compartilhado, chame o método QueryInterface do recurso e passe a UUID da interface IDXGIKeyedMutex . Para obter mais informações sobre como adquirir essa referência, consulte o exemplo de código a seguir.

O método AcquireSync usa a chave da seguinte maneira, dependendo do estado da superfície:

Na criação inicial, a superfície é sem proprietário e qualquer dispositivo pode chamar o método AcquireSync para obter acesso. Para um dispositivo sem proprietário, somente uma chave de 0 terá êxito. Chamar o método AcquireSync para qualquer outra chave atrasará o thread de CPU de chamada.
Se a superfície pertencer a um dispositivo quando você chamar o método AcquireSync , o thread da CPU que chamou o método AcquireSync irá parar até que o dispositivo proprietário chame o método ReleaseSync usando a mesma Chave.
Se a superfície não for semeada quando você chamar o método AcquireSync (por exemplo, o último dispositivo proprietário já chamou o método ReleaseSync ), o método AcquireSync terá êxito se você especificar a mesma chave especificada quando o método ReleaseSync foi chamado pela última vez. Chamar o método AcquireSync usando qualquer outra chave causará uma parada.
Quando o dispositivo proprietário chama o método ReleaseSync com uma chave específica e mais de um dispositivo está aguardando depois de chamar o método AcquireSync usando a mesma chave, qualquer um dos dispositivos em espera pode ser acordado primeiro. A ordem na qual os dispositivos são acordados é indefinida.
Um mutex com chave não dá suporte a chamadas recursivas para o método AcquireSync .

Exemplos

Adquirir um Mutex com chave

O exemplo de código a seguir demonstra como adquirir um bloqueio para um recurso compartilhado e como especificar uma chave após a versão.


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