Метод IDisplayDeviceInterop::CreateSharedHandle (windows.devices.display.core.interop.h)

Статья
11/20/2024

Для DisplaySurface или объекта DisplayFence создает общий дескриптор, который можно использовать для взаимодействия с Direct3D или другими графическими API.

Синтаксис

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

Параметры

pObject

Указатель на интерфейс IUnknownDisplaySurface или объект DisplayFence.

pSecurityAttributes

Указатель на структуру SECURITY_ATTRIBUTES, содержащую два отдельных, но связанных элемента данных: необязательный дескриптор безопасности и логическое значение, определяющее, могут ли дочерние процессы наследовать возвращенный дескриптор.

Задайте для этого параметра значение nullptr, если требуется, чтобы дочерние процессы, которые приложение может создать, чтобы не наследовать дескриптор, возвращаемый CreateSharedHandle, и если требуется, чтобы ресурс, связанный с возвращенным дескриптором безопасности по умолчанию.

Элемент lpSecurityDescriptor структуры указывает SECURITY_DESCRIPTOR для ресурса. Задайте этому элементу значение nullptr, если требуется, чтобы среда выполнения назначила дескриптор безопасности по умолчанию ресурсу, связанному с возвращаемым дескриптором. Списки управления доступом (ACL) в дескрипторе безопасности по умолчанию для ресурса приходят из первичного или олицетворения маркера создателя. Дополнительные сведения см. в разделе Безопасность объектов синхронизации и права доступа.

Access

Запрошенные права доступа к ресурсу. Помимо универсальных прав доступа, поверхность может использовать эти значения.

DXGI_SHARED_RESOURCE_READ (0x8000000000L). Указывает доступ на чтение к ресурсу.
DXGI_SHARED_RESOURCE_WRITE (1). Указывает доступ на запись к ресурсу.

Эти значения можно объединить с помощью побитовой операции OR.

Если pObject является забором, необходимо использовать GENERIC_ALL.

Name

Тип: LPCWSTR

Строка Юникода, завершающая значение NULL, содержащая имя для связывания с общей кучей. Имя ограничено MAX_PATH символами. Сравнение имен учитывает регистр.

Если имя соответствует имени существующего ресурса, CreateSharedHandle завершается ошибкой с DXGI_ERROR_NAME_ALREADY_EXISTS. Это происходит, так как эти объекты используют одно и то же пространство имен.

Имя может иметь префикс "Глобальный" или "Локальный", чтобы явно создать объект в глобальном или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Дополнительные сведения см. в разделе пространства имен объектов ядра. Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Имена объектов ядра должны соответствовать рекомендациям, описанным для служб терминалов, чтобы приложения могли поддерживать несколько пользователей.

Объект можно создать в частном пространстве имен. Дополнительные сведения см. в пространствах имен объектов.

pHandle

Указатель на HANDLE, который получает новый общий дескриптор.

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

Тип: HRESULT

Этот метод возвращает S_OK, если он выполнен успешно, в противном случае код сбоя, указывающий на то, почему он завершился сбоем. Если оно выполнено успешно, pHandle всегда указывает на только что созданный дескриптор.

Замечания

Дескриптор, возвращаемый CreateSharedHandle, можно использовать в любой функции, требующей дескриптора NT к поверхности GPU или забору (в зависимости от того, какой объект был передан), при условии, что вызывающий объект предоставлен доступ. Ниже приведены некоторые примеры.

Совместное использование поверхностей и заборов с Direct3D 12 с помощью ID3D12Device::OpenSharedHandle.
Совместное использование поверхностей с Direct3D 11 с помощью ID3D11Device1::OpenSharedResource.
Совместное использование ограждений с Direct3D 11 с помощью ID3D11Device5::OpenSharedFence.

Несколько процессов могут иметь дескриптор одного и того же объекта, что позволяет использовать объект для межпроцессной синхронизации или совместного использования. Доступны следующие механизмы общего доступа к объектам.

Дочерний процесс , созданный функцией createProcess createProcess, может наследовать дескриптор к объекту поверхности или ограждения, если параметр pSecurityAttributes CreateSharedHandle включает наследование.
Процесс может указать дескриптор объекта в вызове функции DuplicateHandle, чтобы создать повторяющийся дескриптор, который можно использовать другим процессом.
Процесс может указать имя объекта в вызове функции OpenSharedHandle или ID3D12Device::OpenSharedHandleByName.

Чтобы закрыть дескриптор, используйте функцию CloseHandle. Система автоматически закрывает дескриптор при завершении процесса. Объект уничтожается при закрытии последнего дескриптора, и выпущена последняя ссылка на интерфейс.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Сборка Windows 10 20348
минимальный поддерживаемый сервер	Сборка Windows 10 20348
целевая платформа	Виндоус
заголовка	windows.devices.display.core.interop.h
библиотеки	d3d12.lib
DLL	d3d12.dll

Поделиться через