Metodo IDXGIKeyedMutex::AcquireSync (dxgi.h)

Articolo
08/23/2023

Usando una chiave, acquisisce l'accesso esclusivo per il rendering a una risorsa condivisa.

Sintassi

HRESULT AcquireSync(
  UINT64 Key,
  DWORD  dwMilliseconds
);

Parametri

Key

Tipo: UINT64

Valore che indica il dispositivo a cui concedere l'accesso. Questo metodo avrà esito positivo quando il dispositivo proprietario della superficie chiama il metodo IDXGIKeyedMutex::ReleaseSync usando lo stesso valore. Questo valore può essere qualsiasi valore UINT64.

dwMilliseconds

Tipo: DWORD

Intervallo di timeout, espresso in millisecondi. Questo metodo restituirà se l'intervallo è trascorso e il mutex con chiave non è stato rilasciato usando la chiave specificata. Se questo valore è impostato su zero, il metodo AcquireSync verificherà se il mutex con chiave è stato rilasciato e restituisce immediatamente. Se questo valore è impostato su INFINITE, l'intervallo di timeout non scade mai.

Valore restituito

Tipo: HRESULT

Restituisce S_OK in caso di esito positivo.

Se il dispositivo proprietario ha tentato di creare un altro mutex con chiave nella stessa risorsa condivisa, AcquireSync restituisce E_FAIL.

AcquireSync può anche restituire le costanti DWORD seguenti. Pertanto, è consigliabile verificare in modo esplicito la presenza di queste costanti. Se si utilizza solo la macro SUCCEEDED sul valore restituito per determinare se AcquireSync ha esito positivo, non verranno rilevate queste costanti.

WAIT_ABANDONED: la superficie condivisa e il mutex con chiave non sono più in uno stato coerente. Se AcquireSync restituisce questo valore, è necessario rilasciare e ricreare sia il mutex con chiave che la superficie condivisa.
WAIT_TIMEOUT : intervallo di timeout trascorso prima del rilascio della chiave specificata.

Commenti

Il metodo AcquireSync crea un blocco su una superficie condivisa tra più dispositivi, consentendo il rendering di un solo dispositivo a una superficie alla volta.
Questo metodo usa una chiave per determinare quale dispositivo ha attualmente accesso esclusivo alla superficie.

Quando viene creata una superficie usando il valore D3D10_RESOURCE_MISC_SHARED_KEYEDMUTEX dell'enumerazione D3D10_RESOURCE_MISC_FLAG , è necessario chiamare il metodo AcquireSync prima di eseguire il rendering sulla superficie. È necessario chiamare il metodo ReleaseSync al termine del rendering in una superficie.

Per acquisire un riferimento all'oggetto mutex con chiave di una risorsa condivisa, chiamare il metodo QueryInterface della risorsa e passare l'UUID dell'interfaccia IDXGIKeyedMutex . Per altre informazioni sull'acquisizione di questo riferimento, vedere l'esempio di codice seguente.

Il metodo AcquireSync usa la chiave come indicato di seguito, a seconda dello stato della superficie:

Durante la creazione iniziale, la superficie non viene creata e qualsiasi dispositivo può chiamare il metodo AcquireSync per ottenere l'accesso. Per un dispositivo non creato, solo una chiave pari a 0 avrà esito positivo. La chiamata al metodo AcquireSync per qualsiasi altra chiave blocca il thread CPU chiamante.
Se la superficie è di proprietà di un dispositivo quando chiami il metodo AcquireSync , il thread CPU che ha chiamato il metodo AcquireSync si blocca finché il dispositivo proprietario chiama il metodo ReleaseSync usando la stessa chiave.
Se la superficie non viene generata quando chiami il metodo AcquireSync (ad esempio, l'ultimo dispositivo proprietario ha già chiamato il metodo ReleaseSync ), il metodo AcquireSync avrà esito positivo se specifichi la stessa chiave specificata quando il metodo ReleaseSync è stato chiamato per l'ultima volta. La chiamata al metodo AcquireSync tramite qualsiasi altra chiave causerà un blocco.
Quando il dispositivo proprietario chiama il metodo ReleaseSync con una chiave specifica e più dispositivi sono in attesa dopo aver chiamato il metodo AcquireSync usando la stessa chiave, uno dei dispositivi in attesa potrebbe essere svegliato per primo. L'ordine in cui i dispositivi vengono svegliati non è definito.
Un mutex con chiave non supporta chiamate ricorsive al metodo AcquireSync .

Esempio

Acquisizione di un mutex con chiave

Nell'esempio di codice seguente viene illustrato come acquisire un blocco in una risorsa condivisa e come specificare una chiave al momento del rilascio.


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