Qt Gamepad

Qt Gamepad — это дополнительная библиотека, которая позволяет приложениям Qt поддерживать использование джойстиков и в некоторых случаях устройств дистанционного управления. Модуль предоставляет интерфейсы QML и C++. Основная целевая аудитория — это встраиваемые устройства с полноэкранными пользовательскими интерфейсами и мобильные приложения, ориентированные на телевизионные форматы.

В настоящее время поддерживаются следующие платформы:

• Windows (рабочий стол Win32, через XInput 1.3 и 1.4)
• Linux (evdev)
• Linux (SDL2)
• Android
• macOS, iOS, tvOS (включая пульт tvOS)

Этот модуль предоставляет классы, которые могут:

• Считывать события от игровых контроллеров (события кнопок и осей),
• предоставлять эти события как для C++, так и для Qt Quick (QML),
• предоставлять базовую возможность настройки макета джойстика, и
• предоставлять возможность (по желанию) генерировать события клавиш и мыши при нажатии кнопок джойстика.

Примечание: API разработан с учётом контроллеров XBox и аналогичных. Джойстики не входят в сферу применения этого модуля. Возможно, ряд джойстиков от сторонних производителей также будет поддерживаться, однако для некоторых из них могут потребоваться дополнительные шаги по настройке, чтобы сопоставить коды кнопок/триггеров устройства или драйвера с тем, что ожидает QtGamepad. Это можно сделать с помощью примера configureButtons, который также может сохранять сгенерированный макет для использования другими приложениями.

Начало работы

Перед началом использования API, предоставляемого этим модулем, убедитесь, что джойстик обнаруживается вашей средой разработки.

Linux

На стандартных дистрибутивах Linux, таких как Ubuntu, джойстики, такие как XBox или контроллеры PlayStation, обнаруживаются по умолчанию. Чтобы проверить, обнаружен ли джойстик, grep dmesg журналы, используя:

dmesg | grep "<gamepad-make>"

Если вы не видите записей для используемого джойстика, проверьте, установлен ли пакет joystick. Если нет, установите пакет и grep dmesg журналы снова.

Сильно рекомендуется проверить, что устройство ввода джойстика присутствует и отправляет события, используя утилиты lsinput и evtest.

Контроллеры PlayStation, вероятно, потребуют дополнительного инструмента, такого как xboxdrv. После установки и подключения контроллера PS3 через USB, следующие действия обеспечат корректную работу с QtGamepad:

sudo xboxdrv --detach-kernel-driver --mimic-xpad -s

Qt Gamepad использует архитектуру с плагинами и множеством бэкэндов. Это означает, что на некоторых платформах, таких как Linux, доступны несколько бэкэндов. В случае Linux, доступны следующие варианты:

• evdev — бэкенд, считывающий события напрямую из устройства ввода evdev
• sdl2 — бэкенд, использующий модуль Gamepad SDL2. Этот плагин компилируется только при наличии SDL2 во время сборки, поэтому обычно отсутствует в предварительно собранных пакетах Qt. Этот бэкенд, вероятно, обеспечивает более широкую поддержку различных устройств, но за счёт дополнительной зависимости от стороннего программного обеспечения.

Чтобы принудительно использовать определённый бэкенд, установите переменную окружения QT_GAMEPAD в имя желаемого бэкенда.

Доступность устройств джойстиков отслеживается через libudev, предполагая, что Qt был скомпилирован с поддержкой libudev. Это означает, что подключение проводных джойстиков или беспроводных dongles возможно также во время работы приложения.

Примечание: беспроводные dongles могут сообщать об одном или нескольких устройствах ввода даже тогда, когда к ним не подключены контроллеры. Qt Gamepad будет интерпретировать это как подключение имеющихся джойстиков.

С бэкэндом evdev, для явного указания устройства ввода, используйте переменную окружения QT_GAMEPAD_DEVICE с желаемым узлом /dev/input/event*. Это обычно не требуется, но может быть полезно в случае подключения нескольких джойстиков, и приложением интересен только один из них.

Windows

Служба Windows Plug-n-Play автоматически устанавливает необходимые драйверы, когда джойстик подключается через порт USB в первый раз. После установки драйверов выберите Панель управления > Устройства и принтеры и проверьте, указан ли джойстик в разделе Устройства.

Чтобы проверить, распознаётся ли ввод джойстика, выберите Настройки контроллера джойстика в контекстном меню, выберите Свойства > Тест и запустите тестирование. Также можно запустить пример quickGamepad для проверки.

Android

Бэкенд Android использует API InputDevice.

macOS, iOS, tvOS

Этот бэкенд использует API GCController.

Помимо игровых контроллеров, он также поддерживает пульт tvOS (microGamepad). Сопоставление следующее:

• X button — воспроизведение/пауза
• A button — нажатие сенсорной области
• left thumbstick — сенсорная область

Устранение неполадок

Некоторые бэкэнды (evdev на Linux и xinput на Windows) и загрузчик плагинов используют категорию логов qt.gamepad. Включение этой категории выведет полезную информацию в выходные данные отладки.

Примеры

Примеры examples демонстрируют, как обработать ввод с джойстика с помощью API QML и C++.

Справочник по API

• Типы QML Qt Gamepad
• Классы C++ Qt Gamepad