Metodo IDisplayDeviceInterop::CreateSharedHandle (windows.devices.display.core.interop.h)

Articolo
03/09/2024

Per un oggetto DisplaySurface o DisplayFence , crea un handle condiviso che può essere usato per l'interoperabilità con Direct3D o altre API grafiche.

Sintassi

HRESULT CreateSharedHandle(
  IInspectable              *pObject,
  const SECURITY_ATTRIBUTES *pSecurityAttributes,
  DWORD                     Access,
  HSTRING                   Name,
  HANDLE                    *pHandle
);

Parametri

pObject

Puntatore all'interfaccia IUnknown di un oggetto DisplaySurface o di un oggetto DisplayFence .

pSecurityAttributes

Puntatore a una struttura SECURITY_ATTRIBUTES che contiene due membri dati separati ma correlati: un descrittore di sicurezza facoltativo e un valore booleano che determina se i processi figlio possono ereditare l'handle restituito.

Impostare questo parametro su nullptr se si desidera che l'applicazione crei per non ereditare l'handle restituito da CreateSharedHandle e se si vuole che la risorsa associata all'handle restituito ottenga un descrittore di sicurezza predefinito.

Il membro lpSecurityDescriptor della struttura specifica un SECURITY_DESCRIPTOR per la risorsa. Impostare questo membro su nullptr se si vuole che il runtime assegna un descrittore di sicurezza predefinito alla risorsa associata all'handle restituito. Gli elenchi di controllo di accesso (ACL) nel descrittore di sicurezza predefinito per la risorsa provengono dal token primario o di rappresentazione dell'autore. Per altre informazioni, vedere Sicurezza dell'oggetto di sincronizzazione e diritti di accesso.

Access

Diritti di accesso richiesti alla risorsa. Oltre ai diritti di accesso generici, una superficie può usare questi valori.

DXGI_SHARED_RESOURCE_READ (0x80000000L). Specifica l'accesso in lettura alla risorsa.
DXGI_SHARED_RESOURCE_WRITE (1). Specifica l'accesso in scrittura alla risorsa.

È possibile combinare questi valori usando un'operazione OR bit per bit.

Se pObject è un recinto, è necessario usare GENERIC_ALL.

Name

Tipo: LPCWSTR

Stringa Unicode con terminazione null contenente il nome da associare all'heap condiviso. Il nome è limitato a MAX_PATH caratteri. Il confronto tra nomi è distinzione tra maiuscole e minuscole.

Se Name corrisponde al nome di una risorsa esistente, CreateSharedHandle ha esito negativo con DXGI_ERROR_NAME_ALREADY_EXISTS. Ciò si verifica perché questi oggetti condividono lo stesso spazio dei nomi.

Il nome può avere un prefisso "Global" o "Local" per creare in modo esplicito l'oggetto nello spazio dei nomi globale o sessione. Il resto del nome può contenere qualsiasi carattere, ad eccezione del carattere barra rovesciata (\). Per altre informazioni, vedere Spazi dei nomi degli oggetti kernel. Il passaggio rapido dell'utente viene implementato usando sessioni di Servizi terminal. I nomi degli oggetti kernel devono seguire le linee guida descritte per Servizi terminal in modo che le applicazioni possano supportare più utenti.

L'oggetto può essere creato in uno spazio dei nomi privato. Per altre informazioni, vedere Spazi dei nomi degli oggetti.

pHandle

Puntatore a un handle che riceve tale nuovo handle condiviso.

Valore restituito

Tipo: HRESULT

Questo metodo restituisce S_OK se ha avuto esito positivo, in caso contrario, un codice di errore che indica perché non è riuscito. Se ha esito positivo, pHandle punta sempre all'handle appena creato.

Commenti

L'handle restituito da CreateSharedHandle può essere usato in qualsiasi funzione che richiede un "handle NT" in una superficie o una recinzione GPU (a seconda dell'oggetto passato), purché il chiamante abbia concesso l'accesso. Di seguito sono riportati alcuni esempi.

Condividere superfici e recinzioni con Direct3D 12 usando ID3D12Device::OpenSharedHandle.
Condividere le superfici con Direct3D 11 usando ID3D11Device1::OpenSharedResource.
Condividere le recinzioni con Direct3D 11 usando ID3D11Device5::OpenSharedFence.

Più processi possono avere handle dello stesso oggetto, abilitando l'uso dell'oggetto per la sincronizzazione o la condivisione tra processi. Sono disponibili i meccanismi di condivisione degli oggetti seguenti.

Un processo figlio creato dalla funzione CreateProcess può ereditare un handle in un oggetto di superficie o di recinzione se il parametro pSecurityAttributes di CreateSharedHandle abilita l'ereditarietà.
Un processo può specificare l'handle dell'oggetto in una chiamata alla funzione DuplicateHandle per creare un handle duplicato che può essere usato da un altro processo.
Un processo può specificare il nome dell'oggetto in una chiamata alla funzione OpenSharedHandle o ID3D12Device::OpenSharedHandleByName .

Usare la funzione CloseHandle per chiudere l'handle. Il sistema chiude automaticamente l'handle al termine del processo. L'oggetto viene eliminato quando l'ultimo handle è stato chiuso e l'ultimo riferimento all'interfaccia è stato rilasciato.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 10 Build 20348
Server minimo supportato	Windows 10 Build 20348
Piattaforma di destinazione	Windows
Intestazione	windows.devices.display.core.interop.h
Libreria	d3d12.lib
DLL	d3d12.dll

Condividi tramite