Создание пользовательского приложения compositor для подключенных к голове и специализированных мониторов

API Windows.Devices.Display.Core — это низкоуровневый API среда выполнения Windows (WinRT) для сторонних компостаторов и внутренних компонентов Windows, которые сидят под всеми другими общедоступными API для перечисления, настройки и вождения адаптеров дисплея и целевых объектов отображения в Windows. Идея заключается в том, чтобы рассматривать контроллер дисплея как отдельный модуль, аналогичный трехмерной подсистеме и подсистеме мультимедиа на GPU. Этот API отвечает за следующее:

• Ответы на запросы к оборудованию отображения (например, возможности и возможные режимы отображения)
• Ответы на запросы о текущей конфигурации
• Настройка свойств на оборудовании отображения (например, режимы отображения)
• Настройка оборудования отображения (разрешение подключенных мониторов, их формат провода и т. д.)
• Выделение и сканирование специальных поверхностей GPU, известных как первичные
• Разрешение взаимодействия между Direct3D и API Windows.Devices.Display.Core (например, предоставление общего доступа к поверхностям, заборам)

Стоит обратить внимание на то, что windows.Devices.Display.Core не является:

• Это не API, используемый играми или приложениями для отображения содержимого в окне. Приложения по-прежнему используют DXGI, XAML, API композиции, GDI и т. д.
• Это не API, используемый играми или приложениями для отображения полноэкранного содержимого. Приложения по-прежнему используют DXGI, приложения Win32 по-прежнему используют HWND, а приложения UWP всегда отображают содержимое в CoreWindow.

Этот API предназначен только для приложений compositor, движущих специализированное оборудование.

Сценарии создания пользовательских компостов

API Windows.Devices.Display.Core подходят для использования в следующих сценариях:

• Виртуальная и дополненная реальность отображаются, для которых требуется собственный компостатор, чтобы напрямую управлять контроллером дисплея и получать подробный контроль над настройкой времени и режима отдельно от рабочего стола Windows.
• Специализированные сценарии отображения оборудования, для которых требуется выделенный контроль над дисплеем в коммерческом параметре. Например, в случаях, когда настольный компьютер Windows не может правильно отображать на таком дисплее из-за аппаратного перенапряжения, экранов серого уровня и т. д.
• Специализированные сценарии "(модуль)", в которых монитор может быть полностью выделен для приложения без каких-либо помех с классическим интерфейсом Windows в течение длительного периода времени (например, выделенный видео монитор).

ЭТОТ API выполняется следующим образом:

• Обеспечение точного контроля над полнофункционированными сведениями о режиме отображения, включая формат провода, HDR и т. д.
• Использование заборов для синхронизации презентации позволяет компостору цепочки презентаций между процессами или подкомпонентами с почти нулевыми затратами на производительность.
• Улучшение возможности запроса и настройки базовой сети представления видео (VidPN) позволяет как системным компонентам, так и компонентам композиции низкого уровня выполнять более сложные операции с меньшей вероятностью ошибок и более расширяемым способом.

Обратите внимание, что этот API предназначен только для определенного набора сторонних вариантов использования с специализированным оборудованием. Его использование очень ограничено оборудованием, которое объявляет себя нуждающимся в функциональных возможностях этого API. Таким образом, определенная степень знакомства с аппаратными понятиями ожидается от разработчиков, и партнеры должны обратиться к корпорации Майкрософт напрямую, чтобы помочь с проблемами.

Требования к оборудованию и программному обеспечению

Сторонние пользовательские компостаторы могут получать только экраны, предварительно назначенные как встроенные в голову дисплея (HMD) или "специализированные". Это обозначение должно быть предоставлено одним из двух способов:

• Расширение EDID — пользовательские устройства отображения, предназначенные для постоянного использования в качестве HMD, рентгеновских мониторов, видеостен или других специализированных сценариев, должны реализовать расширение Microsoft EDID для головного и специализированного дисплея.
• Переопределение пользователя . Для пользовательских установок оборудования с помощью отключенных мониторов Windows предоставляет переключатель пользовательского интерфейса для назначения мониторов в качестве специализированных.

Отображение может не быть назначено как HMD или специализированные отображения путем переопределения EDID в программном обеспечении.

Примечание.

Специализированные экраны доступны только в Windows 10 версии 2004 и требуют Windows 10 Корпоративная, Windows 10 Pro для рабочих станций или Windows 10 IoT Корпоративная.

Стратегия реализации пользовательского компостатора

Реализация пользовательского компостатора может быть разбита на несколько этапов:

• Перечисление и обнаружение связанных HMD или специализированных дисплеев
• Получение владения выбранными дисплеями
• Настройка режимов для всех выбранных отображений
• Создание ресурсов для представления кадров в дисплеях
• Визуализация содержимого и представления кадра расписания

Сравнение ИНТЕРФЕЙСов API, связанных с отображением

API	Назначение и целевая аудитория
DisplayInformation	Используется для получения свойств отрисовки и макета для CoreWindow.
HdmiDisplayInformation	API только для Xbox для перечисления и настройки ограниченного набора режимов. Высокоспециализировался для сценариев приложений мультимедиа Xbox.
DisplayMonitor	Используется для запроса свойств физического монитора устройства. Не предоставляет никаких сведений о настройке или текущем использовании монитора операционной системой.
EnumDisplayDevices, EnumDisplayMonitors, EnumDisplay Параметры Ex	Устаревшие API Win32 для запроса HMONITORs, устройств GDI и сопоставлений физических мониторов. Возвращаемые здесь сведения высоко виртуализированы и поддерживаются для обеспечения совместимости приложений.
Direct3d	Используется для отрисовки содержимого пикселя в поверхности GPU и выполнения вычислений на GPU.
Цепочки буферов DXGI	Используется для презентации полноэкранного окна с окнами без окон. Поток содержимого цепочки буферов приложений через системный компостатор DWM.
Перечисление выходных данных DXGI	Предоставляет оболочки DXGI вокруг HMONITORs.
QueryDisplayConfig, SetDisplayConfig, DisplayConfigGetDeviceInfo, DisplayConfigSetDeviceInfo	API Win32 для настройки топологии отображения. Не предоставляет механизма перечисления нескольких режимов, но содержит широкий набор сведений о текущей конфигурации и параметрах. Однако не все новые свойства режима предоставляются этими API.
Windows.Devices.Display.Core (этот документ)	Используется для перечисления целевых объектов, перечисления режимов, настройки режимов, выделения поверхностей GPU для презентации и представления содержимого для отображения.

Обзор конфигурации отображения

Перечисление физического оборудования

API Windows.Devices.Display.Core имеет различные объекты для представления физических аппаратных объектов. DisplayAdapter обычно (но не всегда) физическое аппаратное устройство, например GPU с подключением PCI Express или интегрированный GPU на ЦП. Объекты DisplayTarget представляют физические соединители (например, HDMI, VGA, DisplayPort и т. д.), к которым можно подключиться с GPU. Это может включать внутренние неясные подключения для устройств с внутренними мониторами (ноутбуки, планшеты и т. д.). В программном обеспечении может быть больше объектов DisplayTarget , чем пользователь может физически подключаться одновременно. Например, так как стандарт подключения DisplayPort позволяет выполнять цепочку управляющей цепочки, драйверы GPU обычно перечисляют несколько целевых объектов DisplayPort на физический порт, чтобы учитывать цепочки мониторов.

Объекты для режимов настройки

Для перечисления объектов DisplayTarget , режима настройки и запроса и т. д. подключения к объектам DisplayTarget представлены с объектами DisplayPath . Группы путей, отображающие то же содержимое (клонированные группы), представлены DisplayView, и они объединяются в DisplayState. Таким образом, один объект DisplayState может представлять полный набор состояний режима, которые можно отправлять драйверам для нескольких мониторов.

Атомарное состояние для конфигурации и перечисления в режиме

API Windows.Devices.Display.Core предназначен для обеспечения того, чтобы компостаторы могли получать доступ к различным состояниям отображения системы атомарно и с четко определенным поведением устаревших значений. Это важно, так как графические процессоры являются общими ресурсами, с очень жесткой пропускной способностью и ограничениями питания. В современных системах устройства могут прибыть и уйти в любое время, и другие вещи могут повлиять на список доступных режимов отображения (например, закрепление или открепления, состояния сна, другое изменение компонентов в другом пути). Поэтому важно, чтобы компостаторы устойчивы к изменениям в системной конфигурации с помощью API Windows.Devices.Display.Core и следующих рекомендуемых шаблонов настройки состояния.

Таким образом, API Windows.Devices.Display.Core предоставляет простую модель транзакций для чтения и изменения фиксации, аналогичную базе данных. Клиенты могут атомарно считывать объект DisplayState для отображения устройств в системе. Все объекты являются неизменяемыми или предоставляют четко определенные API для обновления или фиксации состояния обратно в систему. Изменения не вносятся до вызова DisplayState.TryApply , который "фиксирует" изменения в системе. Фиксация или применение изменений в DisplayState завершается сбоем без влияния или успешно выполнено с примененными полными изменениями.

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

• Выполните запись любой логики конфигурации режима в цикл повторных попыток.
• Создайте новый DisplayState в начале конфигурации режима в каждом цикле.
• При вызове DisplayState.TryApply используйте флаг FailIfStateChanged, чтобы определить, что состояние системы больше не совпадает с состоянием системы при создании DisplayState. Это позволяет повторить операцию. Если операция завершается ошибкой с помощью SystemStateChanged, повторите весь цикл.
• Не смешивайте другие API (DXGI, GDI и т. д.), которые считывают или изменяют состояние с использованием API Windows.Devices.Display.Core, так как они могут не иметь одинаковых гарантий атомарности.

#include <winrt\Windows.Devices.Display.Core.h>
using namespace winrt::Windows::Devices::Display::Core;
...

// Create a DisplayManager
DisplayManager manager = DisplayManager::Create(DisplayManagerOptions::EnforceSourceOwnership);

// Loop around trying to acquire a target and set a mode
bool shouldRetry;
do
{
    shouldRetry = false;

    // ... Find the target that you want to use
    auto targets = manager.GetCurrentTargets();
    DisplayTarget selectedTarget = ...;

    auto stateCreationResult = manager.TryAcquireTargetsAndCreateEmptyState(
        winrt::single_threaded_vector<DisplayTarget>({ selectedTarget }));

    if (stateCreationResult.ErrorCode() != DisplayManagerResult::Success)
    {
        winrt::check_hresult(stateCreationResult.ExtendedErrorCode());
    }

    auto state = stateCreationResult.State();
    DisplayPath newPath = state.ConnectTarget(selectedTarget);

    // ... Configure the path

    auto applyResult = state.TryApply(DisplayStateApplyOptions::FailIfStateChanged);

    if (applyResult.Status() == DisplayStateOperationStatus::SystemStateChanged)
    {
        shouldRetry = true;
    }
    else if (applyResult.Status() != DisplayStateOperationStatus::Success)
    {
        winrt::check_hresult(applyResult.ExtendedErrorCode());
    }

} while (shouldRetry);

Следующие API считывают состояние атомарно из системы:

• DisplayManager
  • GetCurrentTargets
  • GetCurrentAdapters
  • TryReadCurrentStateForAllTargets/TryAcquireTargetsAndReadCurrentState
• DisplayState
  • IsStale
  • TryFunctionalize
• DisplayPath
  • FindAllModes
• DisplayTarget
  • DisplayTarget.IsStale

Следующие API-интерфейсы фиксируют состояние обратно в систему:

• DisplayManager
  • TryAcquireTarget ReleaseTarget/ (и получение целевых объектов с TryAcquireTargetsAnd* помощью методов) получает владение DisplayTargets из системы.
• DisplayState
  • TryApply Обновления текущее состояние отображения системы путем установки или очистки режимов на всех собственных целевых объектах в системе с помощью драйверов отображения.

Известные ограничения

API Windows.Devices.Display.Core имеет несколько известных ограничений (начиная с Windows 10 версии 2004):

• В настоящее время непрямые драйверы отображения (например, Miracast, USB-адаптеры, драйверы программного обеспечения) не могут быть устранены. DisplayManager.CreateDisplayDevice завершится ошибкой при передаче непрямого адаптера отображения.

Пример кода

Пример приложения см . в примере пользовательского компостора Windows.Devices.Display.Core.