Merge pull request #49 from microdee/develop

update 1.2

CHANGELOG.md

@@ -0,0 +1,68 @@
+
+# **1.2** (WIP) (Github)
+
+### **Goals:**
+* [x] Completely rewrite the SpaceMouseReader module to support more data sources and just have better code quality
+* [ ] MacOS support. **Postponed to 1.3 :(**
+* [x] Participate properly in Unreal's Input Device system (have bindable `FKey`s and axes)
+* [x] Trigger Editor commands directly
+* [x] Support Orthographic viewports
+* [ ] Improve axis configuration UX
+* [ ] Per-device model default button bindings
+* [ ] Detect device models through the Universal Receiver
+
+## 1.2.3-β
+* *RUNTIME*
+  * __^__ SpaceMouse buttons are now properly registered as `FKey`s and as such can be used as Blueprint input events or input events in Slate/UMG widgets
+  * __^__ Separated the single static Blueprint device data getter, into multiple nodes
+* *EDITOR*
+  * __\+__ **BREAKING CHANGE!** Configuration refactored to support new SpaceMouse `FKey`'s
+    * Configuration from previous versions will not work.
+  * __\+__ Use the `Keyboard Shortcuts` editor preferences to bind SpaceMouse buttons to any of the pre-existing editor commands
+  * __\+__ Added a "universal" default button binding until the per-device system is ready.
+    * User needs to trigger this configuration from the SpaceMouse preferences
+  * __\+__ Added support for Orthographic viewports
+  * __\+__ Binding the `MenuOptions` SpaceMouse button to open the SpaceMouse preferences by default.
+  * __^__ **BREAKING CHANGE!** Fixed stupid spelling error for Orbiting (with one T).
+    * User has to re-select orbiting camera behaviors, and reconfigure their settings
+
+## 1.2.2-α
+* *EDITOR*
+  * __^__ Internal button mappings for devices are complete (copied from Blender)
+  * __^__ Fixed a bug with Universal Receiver not having
+  * __\+__ Started MacOS support but ran into a roadblock issue
+
+## 1.2.1-α
+* *EDITOR*
+  * __\+__ Started support for device type detection and button configuration
+  * __\+__ Test release for the SpaceMouseReader rewrite
+
+## 1.2.0-α
+* *READER*
+  * __^__ Rewrote the device data reader module so it can support more features, and it has higher quality of code and architecture
+  * __\+__ Among many other benefits it introduced Normalized device data as output.
+  * __\+__ Test release for the SpaceMouseReader rewrite
+
+# **1.1** (Current) (Marketplace)
+
+## <= 1.1.4 
+[See releases](https://github.com/microdee/UE4-SpaceMouse/releases)
+
+# **1.3** (roadmap)
+
+### **Goals:**
+
+* [ ] Fix the current roadblock with macOS support.
+* [ ] Use official 3DxWare SDK when it's available on Windows as well (use HID as a fallback)
+  * as per request
+
+# **?.?** (future)
+
+### **Goals:**
+* [ ] Deal with the TDxUnrealEd collision
+* [ ] Use space mice in any spatial editor, not just viewports like
+  * Blueprint/Material/Niagara/etc graph editors
+  * Sequencers/timelines
+  * Curve editors
+  * etc
+

MAC.md

@@ -0,0 +1,14 @@
+## MacOS Requirements and instructions
+
+In order for this plugin to function on MacOS you'll need to install the official drivers from 3DConnexion like for any other software. The links are:
+
+* [3DConnexion drivers](https://3dconnexion.com/uk/product/3dxware-10/) (for MacOS X 10.x)
+* [BETA drivers for MacOS Big Sur 11.x](https://3dconnexion.com/uk/support/faq/beta-driver-for-macos-11-big-sur/) (as of 17.03.2021)
+
+Once installed and restarted you will NEED to open the **3DConnexion Home** app. Before that the driver is not activated.
+
+![icon](ReadmeMedia/mac_home_icon.png)
+
+3DConnexion assigns their button mappings to the buttons on space mice by default. While this seems useful it actually interferes with the button assignment in Unreal Engine. To prevent that open the **Properties** from the 3DConnexion Home and while the **Any Application** is selected for the **Configure** dropdown menu, go to the **Buttons** tab and disable all the mappings, as seen on this screenshot:
+
+![buttons](ReadmeMedia/mac_disable_buttons.png)

README.md

@@ -1,75 +1,153 @@
-## SpaceMouse camera controller for UE4 editor viewports
+# SpaceMouse for Unreal Engine
+
+- [SpaceMouse for Unreal Engine](#spacemouse-for-unreal-engine)
+- [Installation](#installation)
+  - [Disclaimer about the new official plugin shipped by 3DConnexion](#disclaimer-about-the-new-official-plugin-shipped-by-3dconnexion)
+  - [Requirements](#requirements)
+- [Config / Usage](#config--usage)
+  - [Buttons](#buttons)
+    - [Default editor bindings](#default-editor-bindings)
+  - [Behavior](#behavior)
+    - [Orbiting](#orbiting)
+    - [Orthographic viewports](#orthographic-viewports)
+  - [Axis configuration](#axis-configuration)
+  - [Misc](#misc)
+- [More info](#more-info)
+  - [Changelog](#changelog)
+  - [Major changes from version 1.2](#major-changes-from-version-12)
+  - [Major changes from version 1.1](#major-changes-from-version-11)
+  - [Build a release](#build-a-release)
+  - [Note on macOS support](#note-on-macos-support)
+  - [Known issues:](#known-issues)
+  - [Known nuances](#known-nuances)
+  - [Credits](#credits)
+
+# Installation
+
+**Pre-Compiled for UE 4.23 .. 4.26.**
 
-**Compatible with UE 4.26 and below**  
-**Compiled for UE 4.23 .. 4.26.**
+Demo video: https://youtu.be/Qibig0gQWvE
 
 **[Download manually for free](https://github.com/microdee/UE4-SpaceMouse/releases/latest)**
 
 **[Buy it via the Marketplace](https://www.unrealengine.com/marketplace/en-US/product/spacemouse-for-unreal-engine)**
 
-Demo video: https://youtu.be/Qibig0gQWvE
+**If you have a code project just use this repo as submodule**
+```
+git submodule add https://github.com/microdee/UE4-SpaceMouse.git Plugins/SpaceMouse
+```
 
 ## [Disclaimer about the new official plugin shipped by 3DConnexion](DISCLAIMER.md)
 
-# About
+## Requirements
+
+This plugin works with the HID device directly and doesn't use 3DxWare (official "drivers") SDK or its services (similar how Blender does it). However it has different requirements depending on your operating system:
+
+* **Windows** treats space mice as generic HID input devices before 3DxWare is installed. Therefore this plugin works out of the box, without the need for official drivers to be installed.
+  * In case you need to install their software package for other applications, make sure to untick their UE4 plugin in the installer.
+  * However if you already installed the official drivers with default settings, please remove their UE4 plugin from `<path-to-ue4>\Engine\Plugins\3DConnexion` before using this one.
+  * Supporting official 3DxWare shenanigans are a planned thing now on Windows as well, when the driver is installed.
+* **MacOS** [see below](#note-on-macos-support)
 
-You can control any 3D editor viewport currently in focus (user clicked on it). There are multiple control schemes, check below.
+# Config / Usage
+
+You can control any 3D editor viewport (Perspective or Ortho) currently in focus (user needs to click on it first).
 
 ![Alt text](/ReadmeMedia/featured.png?raw=true "Coordinates")
 
 Transition speed is controllable via the camera speed setting and the camera speed scalar of the viewport. Camera speed can be increased or decreased with configurable buttons on the spacemice. Multiple devices are supported however their data is merged together into a global context.
 
-On default speeds (speed setting = 4) transition velocity is 1000 units/sec by default and rotation speed is 270°/sec by default. Rotation speed is not affected by camera speed settings. You can change these in the **Editor Preference** under SpaceMouse section.
+On default speeds (speed setting = 4) transition velocity is 1000 units/sec by default and rotation speed is 270°/sec by default. Rotation speed is not affected by camera speed settings. You can change these in the **Editor Preferences -> Plugins -> SpaceMouse** section.
 
 ![Alt text](/ReadmeMedia/settings.png?raw=true "Settings")
 
+## Buttons
+
+With **Button mappings** one can remap some functionalities to SpaceMouse buttons.
+* For the SpaceMouse specific actions listed in here, either explicitly select a button, or press the small "keyboard" icon to learn a button.
+* For further actions go to the `Keyboard Shortcuts` Editor preferences (link provided) and bind your SpaceMouse buttons as you would bind a regular keyboard shortcut. Using the ***SECONDARY*** input binding form is recommended.
+
+### Default editor bindings
+
+There's a pre-defined default set of bindings you can activate by clicking on _"Configure default button bindings"_.
+
+* Under the hood it just assigns sensically the buttons from space mice, to the ***SECONDARY*** binding of the equivalent or close-enough™ Unreal Editor input action. It doesn't touch the primary binding which is usually the default keyboard shortcut.
+* In some rare cases there's already something assigned as the ***SECONDARY*** binding which will be overwritten by this operation. This is also the reason why I chose to trigger this by the user, and why it's guarded with a confirmation dialog.
+
+## Behavior
+
 **Active in Background** When false, only control the camera of UE4 while the editor is the foreground application.
 
-**Camera Behavior** Sets the mode of controlling the viewport camera. For all modes movement is always applied in current camera space.
+**Camera Behavior** Sets the mode of controlling the viewport camera. All behavior controls the viewport camera.
 
 * **Camera Delta with Roll**
   * SpaceMouse represents the Delta Movement of the camera in Free-flight/Helicopter fashion. All rotation is in current camera space.
 * **Camera Delta with No Roll**
   * Same as above but roll is ignored and Yaw is always in World space (instead of current camera space))
-* **Orbitting with Roll** (EXPERIMENTAL)
-  * SpaceMouse represents the Delta Movement of the camera around "the object" OR the Delta movement of "the object" in front of the camera. The pivot of orbitting is either surface point in the center of the viewport, or a fixed distance if set in the settings.
-* **Orbitting with No Roll** (EXPERIMENTAL)
+* **Orbiting with Roll**
+  * SpaceMouse represents the Delta Movement of the camera around "the object" OR the Delta movement of "the object" in front of the camera. The pivot of orbiting is either surface point in the center of the viewport, or a fixed distance if set in the settings.
+* **Orbiting with No Roll**
   * Same as above but roll is ignored and Yaw is always in World space (instead of current camera space))
 
-**Orbitting Moves/Rotates Object** When true, SpaceMouse represents the Delta movement of "the object" in front of the camera (meaning axes are inverted)
+### Orbiting
 
-**Orbitting at Fixed Pivot Distance** When enabled, sets a fixed distance for the orbitting mode in UE4 units (usually cm).
+**Orbiting Moves/Rotates Object** When true, SpaceMouse represents the Delta movement of "the object" in front of the camera (meaning axes are inverted)
 
-**Orbitting Line Trace Length** is the maximum possible radius of the orbitting behavior in UE4 units (usually cm).
+**Orbiting at Fixed Pivot Distance** When enabled, sets a fixed distance for the orbiting mode in UE4 units (usually cm).
 
-**Axis mappings** are conversions between the space of spacemice and the space of UE4. You can invert rotations and translations here by flipping the sign. The default values are my subjective preferences (as you can see in the coordinate system image above).
+**Orbiting Line Trace Length** is the maximum possible radius of the orbiting behavior in UE4 units (usually cm).
 
-**Rotation/Translation Curve** are defining the 0..1 curvature from resting state to fully pushed/pulled state of the SpaceMouse puck. Dead-zone, clamping, exponent or other less useful transformations can be expressed with this. Default is 0..1 linear curve, which means no effect.
+### Orthographic viewports
 
-**Display Debug Information** prints HID data onto the viewport. You don't need to change **Max Hid Read Operations Per Frame**. Just ignore it.
+Camera controls are slightly different when controlling an Orthographic viewport (Top/Bottom, Left/Right, Front/Rear). Rotation is disabled, and the SpaceMouse is used only to pan on the selected plane and zoom.
 
-With **Button mappings** one can remap some functionalities to SpaceMouse buttons. Activate the toggle button next to the property to learn the desired button mapping for said function.
+**Ortho Zoom Speed** An arbitrary multiplier of the Zoom speed while insdide an Orthographic viewport. Negative numbers reverse the direction of zooming.
 
-* Increase, Decrease and Reset camera speed.
-* Reset the roll of the camera
-* Map SpaceMouse buttons to keyboard presses in UE4 editor, so if you have a SpaceMouse Pilot or Enterprise you can spare some hand lifts while working.
+**OrthoPanningPlane** Select the plane of the device (2 axes) which will control the panning motion inside an Orthographic viewport.
+* **Lateral Is Zoom, Vertical Is Up**: Move puck orthogonal to the plane of the Monitor to move around, Push Forward / Pull Backward to zoom.
+* **Lateral Is Up, Vertical Is Zoom**: Move puck orthogonal to the plane of the Desk to move around, Push Down / Pull Up to zoom.
 
-This plugin works with the HID device directly so no 3DxWare service is needed to run (similar how Blender does it). And I highly recommend to disable said service because it's a big pile of steaming hot garbage imo. It doesn't need you to install any drivers at all in theory. However it shouldn't interfere with a running 3DxWare service in case you need it for other less fortunate programs.
+## Axis configuration
+
+**Axis mappings** are conversions between the space of spacemice and the space of UE4. You can invert rotations and translations here by flipping the sign. The default values are my subjective preferences (as you can see in the coordinate system image above).
+
+**Rotation/Translation Curve** are defining the 0..1 curvature from resting state to fully pushed/pulled state of the SpaceMouse puck. Dead-zone, clamping, exponent or other less useful transformations can be expressed with this. Default is 0..1 linear curve, which means no effect.
+
+## Misc
+
+**Display Debug Information** prints HID data onto the viewport. You don't need to change **Max Hid Read Operations Per Frame**. Just ignore it.
 
 [Report bugs](https://github.com/microdee/UE4-SpaceMouse/issues)
 
 [Have any feedback or ideas? Go to Discussions!](https://github.com/microdee/UE4-SpaceMouse/discussions)
 
 [UE4 forum (please prefer Github Discussions)](https://forums.unrealengine.com/unreal-engine/feedback-for-epic/437-support-for-space-navigator-3d-mouse?p=1609440#post1609440)
 
+# More info
+
+## [Changelog](CHANGELOG.md)
+
+## Major changes from version 1.2
+
+The structure of SpaceMouse preferences has changed significantly. Upon updating from prior versions (<= 1.1.x) you might need to re-configure the plugin. Don't worry though, the button binding UX has been improved significantly.
+
 ## Major changes from version 1.1
 
-Upon updating from prior versions please delete both HIDUE and SpaceMouse plugins from your Engine or Project plugins folder!
+Upon updating from prior versions (<= 1.0.x pre-marketplace) please delete both HIDUE and SpaceMouse plugins from your Engine or Project plugins folder!
 
 1. Editor settings is moved to Plugins -> SpaceMouse to follow conventions
 2. HIDUE is now demoted to a module instead of an entire plugin
 3. This repository now only contains the plugin itself which you can also directly submodule now in your code projects if you wish.
 
+## Build a release
+
+If for any reason you cannot use this plugin as a submodule and you want to make a pre-built release to be an engine plugin, then work with the [official test project](https://github.com/microdee/UE4-SpaceMouse-TestProject) and see the build instructions there.
+
+## Note on macOS support
+
+macOS is not yet supported due to a roadblock I'm super frustrated about. Anyway it treats space mice as regular 2D mice before 3DxWare is installed. This means the OS prevents other programs accessing their HID data via the `HIDManager` to fight keyloggers, so they need the official drivers, which unfortunately don't want to cooperate with me as of the time of writing.
+[See installation instructions](MAC.md)
+
 ## Known issues:
 
 * ~~"Focus selected" is broken while this plugin is loaded~~
@@ -79,27 +157,24 @@ Upon updating from prior versions please delete both HIDUE and SpaceMouse plugin
 * ~~Upon exiting the editor the engine crashes. I know why it does that but I didn't figure it out quite yet how to prevent it.~~
   * FIXED
 * Jumping forward periodically when leaning / going forward with the camera
-  * This is most probably caused by the scroll-wheel emulation of 3DxWare. Disable it in the per-application settings, or uninstall it.
+  * __TL;DR:__ Open 3DxWare per-application settings and disable scroll-wheel emulation (disable tilt axis) (per-application settings are opened by the Menu button or bottom left button on your SpaceMouse by default)
+  * [See issue](https://github.com/microdee/UE4-SpaceMouse/issues/12)
 * If you install or update 3DxWare with their new plugin (TDxUnrealEditor), and you had this plugin before, you might experience undefined interaction glitches.
   * Remove either this or the 3DConnexion plugin (TDxUnrealEditor) according to your preference.
 
 ## Known nuances
-* ~~Only free-fly mode is supported and every orbitting perspective viewport in focus is forced to be free-fly while any spacemice operates on them.~~
+* ~~Only free-fly mode is supported and every orbiting perspective viewport in focus is forced to be free-fly while any spacemice operates on them.~~
   * Now multiple camera behaviors are implemented
 * Camera roll is not reset when one tries to navigate viewport with traditional methods
   * There's a mappable button now to reset roll
   * There are camera behaviors now which should not introduce roll
   * In case the SpaceMouse becomes unavailable Maya style Alt + Right-drag dollying resets camera roll
 
-## Roadmap:
-
-* Actively maintained cross platform support of HIDUE for MacOS and Linux (coming after mid-January)
-* Default bindings for connected device and friendlier button name display (coming after mid-January)
-* More intuitive and usable implementation of the Orbiting mode.
-
-## Credits:
+## Credits
 
 * [HIDAPI](https://github.com/libusb/hidapi)
+* **Gabor Papp** for initially investigating macOS support
 * From UE4 forums:
   * **enzo_molinari** for the plugin icon
   * **adlord** for testing with wireless devices
+  * **mrboni** for testing with discontinued SpacePilot Pro