kotschak/qelectrotech-source-mirror
0
0
Fork 0
mirror of https://github.com/qelectrotech/qelectrotech-source-mirror.git synced 2026-10-18 03:54:14 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity

Add a hidapi 3D mouse backend that needs no 3Dconnexion driver

Browse Source 
The 3D mouse only worked on Linux, through spacenavd. This adds a second
backend that reads the device directly over USB through hidapi, with no
3Dconnexion driver or SDK: the route to Windows and macOS (discussion
#599), and usable on Linux without spacenavd.

SpaceMouseHid decodes the raw reports from the device's own report
descriptor -- where each axis and button sits, its range, absolute or
relative -- so no per-model table is needed, with the classic report
1/2/3 layout as a fallback when the descriptor cannot be read and the
0x1c button list newer devices send. Absolute axes are rescaled to
+-500 exactly as spacenavd does, so both backends give QET the same
values. HidBackend polls from the main thread (fast while moving, slow
when still), emits one sample per poll, and looks for a device every 3 s
so plugging one in or back in needs no restart.

QET_SPACEMOUSE_BACKEND (auto, spnav, hid) picks the backend; auto keeps
libspnav on Linux when it is found and uses hidapi otherwise. hidapi is
found through pkg-config as hidapi-hidraw (Linux) or hidapi (MSYS2,
Homebrew).

A sample arriving in the same millisecond as the previous one now counts
for no time instead of a full period, so a burst of queued samples no
longer moves the view further than the time it covers.

Tested without a device: tst_spacemousehid (descriptor parsing, broken
and hostile descriptors, every report form, recordings from real devices
once they are added to fixtures/spacemouse), and end to end on Linux
through a virtual USB device created with /dev/uhid: the same moves give
byte-identical screenshots through the hidapi and libspnav backends, an
absolute axis is rescaled as spacenavd does, buttons trigger their
bound action, and unplugging and replugging while QET runs (including
with a dialog open that a device button opened) reconnects cleanly.
Not tested on Windows, macOS or real hardware.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
ispyisail
2026-09-25 10:55:30 +12:00
parent 17ebbffbca
commit aaeaff55cc
15 changed files with 1176 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cmake/developer_options.cmake
+4 -4
View File
@@ -48,7 +48,7 @@ option(BUILD_WITH_KF "Build with KDE Frameworks" ON)
# strict behaviour, and only developers who opt in trade that for the speed.
option(QET_ENABLE_PCH "Use precompiled headers (developer build speed; may mask missing #includes)" OFF)
# Phase 1 (Linux, libspnav) of discussion #599: 3Dconnexion SpaceMouse/
# SpacePilot pan/zoom support. Off by default -- see cmake/find_spacemouse.cmake
# for what happens when it is on but libspnav isn't found.
option(QET_ENABLE_SPACEMOUSE "Build with 3Dconnexion/libspnav 3D mouse support for pan/zoom (Linux, requires libspnav-dev and spacenavd)" OFF)
# Discussion #599: 3Dconnexion SpaceMouse/SpacePilot pan/zoom support. Off by
# default -- see cmake/find_spacemouse.cmake for the backends and what happens
# when it is on but no library is found.
option(QET_ENABLE_SPACEMOUSE "Build with 3D mouse (3Dconnexion SpaceMouse) support for pan/zoom; needs libspnav or hidapi, see QET_SPACEMOUSE_BACKEND" OFF)
cmake/find_spacemouse.cmake
+47 -27
View File
@@ -20,44 +20,64 @@ message(" - find_spacemouse")
# so none of this runs, and the default build is entirely unaffected: no new
# dependency, no new source files, no new symbols.
#
# When it is on, the platform decides which backend (if any) is available --
# see sources/spacemouse/spacemousebackend.h for what a backend is. Only one
# exists today: SpnavBackend, Linux, via libspnav. A Windows/macOS backend
# would need 3Dconnexion's proprietary 3DxWare SDK and is not implemented
# (see discussion #599's own phase split); until it is, turning this option
# on there downgrades cleanly with a warning rather than failing configure.
# When it is on, QET_SPACEMOUSE_BACKEND picks how the device is read -- see
# sources/spacemouse/spacemousebackend.h for what a backend is:
# spnav Linux, through the spacenavd daemon (libspnav)
# hid any platform, directly over USB (hidapi), no 3Dconnexion driver
# auto spnav on Linux when libspnav is found, hid otherwise
# A backend whose library is not found downgrades the option to off with a
# warning, rather than failing configure for an opt-in feature.
set(QET_SPACEMOUSE_BACKEND "auto" CACHE STRING "3D mouse backend: auto, spnav or hid")
set_property(CACHE QET_SPACEMOUSE_BACKEND PROPERTY STRINGS auto spnav hid)
set(QET_SPACEMOUSE_ENABLED FALSE)
set(QET_SPACEMOUSE_BACKEND_SPNAV_ENABLED FALSE)
set(QET_SPACEMOUSE_BACKEND_HID_ENABLED FALSE)
if(QET_ENABLE_SPACEMOUSE)
if(UNIX AND NOT APPLE)
# libspnav is looked for via its pkg-config file (present on every
# distro package of it this was checked against: Debian/Ubuntu's
# libspnav-dev ships /usr/share/pkgconfig/spnav.pc). Not found does
# not hard-fail the whole configure -- it downgrades the option back
# to off with a clear message, so a developer who doesn't have the
# library installed still gets a normal build instead of a configure
# error for an opt-in feature they didn't ask to block on.
find_package(PkgConfig)
if(PkgConfig_FOUND)
pkg_check_modules(SPNAV IMPORTED_TARGET spnav)
endif()
find_package(PkgConfig)
set(_qet_spacemouse_try_spnav FALSE)
set(_qet_spacemouse_try_hid FALSE)
if(QET_SPACEMOUSE_BACKEND STREQUAL "spnav")
set(_qet_spacemouse_try_spnav TRUE)
elseif(QET_SPACEMOUSE_BACKEND STREQUAL "hid")
set(_qet_spacemouse_try_hid TRUE)
else()
if(UNIX AND NOT APPLE)
set(_qet_spacemouse_try_spnav TRUE)
endif()
set(_qet_spacemouse_try_hid TRUE)
endif()
# libspnav: Debian/Ubuntu's libspnav-dev ships spnav.pc.
if(_qet_spacemouse_try_spnav AND PkgConfig_FOUND)
pkg_check_modules(SPNAV IMPORTED_TARGET spnav)
if(SPNAV_FOUND)
set(QET_SPACEMOUSE_ENABLED TRUE)
set(QET_SPACEMOUSE_BACKEND_SPNAV_ENABLED TRUE)
add_definitions(-DQET_SPACEMOUSE_SUPPORT)
add_definitions(-DQET_SPACEMOUSE_BACKEND_SPNAV)
message("QET_ENABLE_SPACEMOUSE ON (backend: libspnav ${SPNAV_VERSION})")
else()
message(WARNING "QET_ENABLE_SPACEMOUSE is ON but libspnav was not found via pkg-config "
"(install libspnav-dev, or the equivalent for your distribution) -- "
"building WITHOUT 3D mouse support.")
endif()
endif()
# hidapi: hidapi-hidraw.pc on Linux (libhidapi-dev), hidapi.pc from
# MSYS2 (mingw-w64-ucrt-x86_64-hidapi) and Homebrew (hidapi).
if(NOT QET_SPACEMOUSE_ENABLED AND _qet_spacemouse_try_hid AND PkgConfig_FOUND)
pkg_search_module(HIDAPI IMPORTED_TARGET hidapi-hidraw hidapi)
if(HIDAPI_FOUND)
set(QET_SPACEMOUSE_ENABLED TRUE)
set(QET_SPACEMOUSE_BACKEND_HID_ENABLED TRUE)
add_definitions(-DQET_SPACEMOUSE_BACKEND_HID)
message("QET_ENABLE_SPACEMOUSE ON (backend: hidapi ${HIDAPI_VERSION})")
endif()
endif()
if(QET_SPACEMOUSE_ENABLED)
add_definitions(-DQET_SPACEMOUSE_SUPPORT)
else()
message(WARNING "QET_ENABLE_SPACEMOUSE is ON but no 3D mouse backend is implemented yet "
"for this platform (only Linux/libspnav exists today -- see "
"https://github.com/qelectrotech/qelectrotech-source-mirror/discussions/599) "
"-- building WITHOUT 3D mouse support.")
message(WARNING "QET_ENABLE_SPACEMOUSE is ON but no library was found for the "
"'${QET_SPACEMOUSE_BACKEND}' backend (libspnav-dev for spnav, "
"hidapi for hid, via pkg-config) -- building WITHOUT 3D mouse support.")
endif()
endif()
cmake/qet_compilation_vars.cmake
+9
View File
@@ -896,6 +896,15 @@ if(QET_SPACEMOUSE_BACKEND_SPNAV_ENABLED)
)
endif()
if(QET_SPACEMOUSE_BACKEND_HID_ENABLED)
list(APPEND QET_SRC_FILES
${QET_DIR}/sources/spacemouse/hidbackend.cpp
${QET_DIR}/sources/spacemouse/hidbackend.h
${QET_DIR}/sources/spacemouse/spacemousehid.cpp
${QET_DIR}/sources/spacemouse/spacemousehid.h
)
endif()
set(TS_FILES
${QET_DIR}/lang/qet_ar.ts
${QET_DIR}/lang/qet_ca.ts