From e5e07fb6dbb5d76fec322197e9dd0f7ea6430926 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=AC=E5=BD=A6=E8=B5=A4=E5=B1=8B=E5=85=88?= Date: Sun, 10 Apr 2022 03:07:28 +0900 Subject: [PATCH] Updated the readme for all the done stuff --- README.md | 137 ++++++++++++++++++++++++------------------------------ 1 file changed, 61 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index 1b0d5e1..1c810ad 100644 --- a/README.md +++ b/README.md @@ -13,37 +13,37 @@ This project is licensed under the GNU GPL v3 License ## **Overview** This repository contains sample projects of devices / plugins in terms of Amethyst project.
Each project in the solution is an example of a different possible implementation
-of the Microsoft Kinect V2 as a tracking device. (Later referred to as K2TrackingDevice)
+of a tracking device (Later referred to as K2TrackingDevice), and an additional one with settings.

-All ```device_KinectV2_*``` projects represent a ```K2TrackingDevice``` Kinect implementation,
-(later referred to as ```K2TrackingDevice_KinectBasis```),
-except the ```device_KinectV2_Joints``` which
represents a ```K2TrackingDevice``` Joints implementation,
later referred to as ```K2TrackingDevice_JointsBasis```.
+All `device_KinectV2_*` projects represent a `K2TrackingDevice` Kinect implementation,
+(later referred to as `K2TrackingDevice_KinectBasis`),
+except the `device_KinectV2_Joints` which
represents a `K2TrackingDevice` Joints implementation,
later referred to as `K2TrackingDevice_JointsBasis`.

-The first possible device type is ```K2TrackingDevice_KinectBasis```.
+The first possible device type is `K2TrackingDevice_KinectBasis`.
These devices will have to provide selected joints and always the head position.
-Such behaviour will allow us to use in-app automatic calibration, so-called ```flip```
+Such behaviour will allow us to use in-app automatic calibration, so-called `flip`
(which is a big deal for Kinects) and sometimes custom-calculated orientation.

-```K2TrackingDevice_KinectBasis``` must update a provided, fixed array of joints (```ITrackedJoint```s)
-with its own positions. How many joints will the device provide is a matter of its ```Characteristics```.
-And so, ```K2_Character_Full``` has to provide every possible joint, making them count 25.
-```K2_Character_Simple``` has to update head, elbows, waist, knees, ankles and foot (tip) joints.
-The last characteristics, ```K2_Character_Basic``` only has to provide head, waist and ankles;
-devices using the ```Basic``` character also won't be allowed to use ```AppOrientation```, or so-called math-based.
+`K2TrackingDevice_KinectBasis` must update a provided, fixed array of joints (`ITrackedJoint`s)
+with its own positions. How many joints will the device provide is a matter of its `Characteristics`.
+And so, `K2_Character_Full` has to provide every possible joint, making them count 25.
+`K2_Character_Simple` has to update head, elbows, waist, knees, ankles and foot (tip) joints.
+The last characteristics, `K2_Character_Basic` only has to provide head, waist and ankles;
+devices using the `Basic` character also won't be allowed to use `AppOrientation`, or so-called math-based.

-Second, but not any worse is the ```K2TrackingDeviceBase_JointsBasis``` device.
+Second, but not any worse is the `K2TrackingDeviceBase_JointsBasis` device.
This one doesn't have so many different characteristics, and is built on top of how
PSMoveService was working in 0.8~9 KinectToVR versions.
-Thses devices have to provide (push) joints, or ```K2TrackedJoint```s to the internal joints' vector.
-On each ```update()``` call, the joints have to be updated (but hopefully not rebuilt).
+Thses devices have to provide (push) joints, or `K2TrackedJoint`s to the internal joints' vector.
+On each `update()` call, the joints have to be updated (but hopefully not rebuilt).

-Each joint can be updated with position, rotation and state with its public ```update()``` function
-and signaled (optionally) for differentiating joint devices (like PSMoves), with ```signalJoint()```.
-Joints should also be named on creation / pushing by setting their ```jointName```
-for the app to be accessed by calling ```getJointName()``` before adding it to the UI.
+Each joint can be updated with position, rotation and state with its public `update()` function
+and signaled (optionally) for differentiating joint devices (like PSMoves), with `signalJoint()`.
+Joints should also be named on creation / pushing by setting their `jointName`
+for the app to be accessed by calling `getJointName()` before adding it to the UI.

Devices in Amethyst are like drivers in OpenVR. They are going to be scanned and constructed at startup.
-Therefore, each device must have a ```void* TrackingDeviceBaseFactory``` function, you'll find it in samples too.
+Therefore, each device must have a `void* TrackingDeviceBaseFactory` function, you'll find it in samples too.

Additional device type which may be used for third-party plugins is the `K2TrackingDevice_Spectator`.
As the name suggests, it's gonna be used only for grabbing data from Amethyst, and nothing else.
@@ -51,86 +51,71 @@ You can pull states, names, roles and positions of all 7 trackers (as of now).
After playing with samples you should have enough knowledge to write a device plugin yourself.
-Please remember that ```initialize()```, ```update()``` and ```shutdown()``` are the most ever important functions.
+Please remember that `initialize()`, `update()` and `shutdown()` are the most ever important functions.
(At least for the devices which actually provide tracking and not only grab it from the app)

+Since K2API v7 you also can add custom settings to each device plugin.
+Currently, the whole idea of using the `ktvr::Interface::` works similar to how ImGUI works.
+You create elements (element pointers), set them up, and push to the UI via selected functions.
+Of course you can manage them later, either via their pointers or inside handler functions.
+When Amethyst is ready for plugin-wise UI construction, it's gonna call the `OnLoad()` function,
+which you can override to set your UI up. Just remember your device must report `settingsSupported` as true. +
+
**Note:** every device has various helper internal functions, e.g. for getting the HMD position in VRSystem,
that may be called if it was initialized properly (loaded by Amethyst).
These functions may help in plugin development, as for example loading the whole OpenVR API
only to get the head position may be skipped by calling an appropriate function. -## OK, but what's actually in ```external/vendor```? +## OK, but what's actually in `external/vendor`? Ah yes. For the sake of K2API's simplicity in its current state, it's been split into 3 parts.
The currently used part, devices part allows us to make device plugins and provide the whole tracking.
-It's been grabbed from the newest ```KinectToVR API``` project files and put here for simplicity reasons.
+It's been grabbed from the newest `KinectToVR API` project files and put here for simplicity reasons.
If this part will ever get an interface update, you're going to see in logs that your device
-has provided an incorrect ```IK2API_Devices_Version``` of the interface, and you'll be able to update it. - -## **Build with Docker** -You'll need: - - The ```K2TrackingDevice_Samples``` repo cloned somewhere and ```cd```'d into - - Docker Desktop set to use Windows containers - -Notes: - - The build process contains no caching, is one-run, **and will take some time**.
- Everything that's downloaded, set up, and not saved will be gone. - -Follow these steps: - ```powershell - # Build the whole thing - > docker build -t samples . - - # Create a dummy container from saved image - > $id = $(docker create samples) - # Copy Release files to the host machine - > mkdir ./x64/Release - > docker cp ${id}:/x64/Release ./x64/Release - - # Release (remove) the dummy container - > docker rm -v $id - # Release (remove) the base samples container - > docker rmi --force $(docker images -q 'samples') - ``` - Where ```samples``` may be your very own super cool container tag name.
- Artifacts (```x64/Release``` directory) will be saved to ```x64/Release``` inside the repository root.
+has provided an incorrect `IK2API_Devices_Version` of the interface, and you'll be able to update it. +## I've read your damn essay, now what? +It seems that you're really motivated for this, nice! Please have a thorough look at the repo.
+You're going to find samples for all device types & characteristics, including a device with
+custom settings, and a spectator (data-poller) device. -## **Build manually** +## **Build instructions** You'll need: - - The ```K2TrackingDevice-Samples``` repo cloned somewhere and ```cd```'d into - - Kinect SDK 2.0 installed and visible in PATH (exclude if building `Spectator` only) - - Working installation of Amethyst/KTVR1 and SteamVR for testing + - The `K2TrackingDevice-Samples` repo cloned somewhere and `cd`'d into + - (For testing purpose) Working installation of Amethyst and SteamVR Follow these steps: -- Install Visual Studio 2022 Build Tools with needed addons
- (If you already have VS2022 or BuildTools set up, **please skip this step**)
- ```powershell - > Set-ExecutionPolicy Bypass -Scope Process -Force - > Invoke-Expression (Get-Content .dockerprepvc -Raw) - ``` - This will install Microsoft Visual Studio Build Tools 2022 in the default location.
- Nothing will be displayed during the process (just the PID & stats), just wait for it. +- [Install tools for the Windows App development](https://docs.microsoft.com/en-us/windows/apps/windows-app-sdk/set-up-your-development-environment?tabs=vs-2022-17-1-a%2Cvs-2022-17-1-b).
+ You'll have to install Visual Studio 2022 or its Build Tools. -- Clone latest Eigen3 to ```external/```
+- Clone `Eigen3` to `external/`
```powershell > git clone https://gitlab.com/libeigen/eigen ./external/eigen + # Reset Eigen to the latest OK state + > cd ./external/eigen + > git reset --hard 1fd5ce1002a6f30e1169b529b291216a18be2f7e + # Go back + > cd ../.. ``` - Build Samples:
```powershell - > Set-ExecutionPolicy Bypass -Scope Process -Force - > Invoke-Expression (Get-Content .dockerbuild -Raw) - ``` - Alternatively you can open the developer powershell for Visual Studio (or BuildTools) 2022 and: - ```powershell - > msbuild K2TrackingDevice_Samples.sln "/p:Configuration=Release;Platform=x64" + # Download the vswhere tool to find msbuild without additional interactions + > Invoke-WebRequest -Uri 'https://github.com/microsoft/vswhere/releases/latest/download/vswhere.exe' -OutFile './vswhere.exe' + # Use the downloaded vswhere tool to find msbuild. Skip this step if you use the Dev Powershell + > $msbuild = "$("$(.\vswhere.exe -legacy -prerelease -products * -format json | Select-String -Pattern "2022" | ` + Select-String -Pattern "Studio" | Select-Object -First 1 | Select-String -Pattern "installationPath")" ` + -replace('"installationPath": "','') -replace('",',''))".Trim() + "\\MSBuild\\Current\\Bin\\MSBuild.exe" + + # Restore NuGet packages and build everything + > &"$msbuild" K2TrackingDevice_Samples.sln "/p:Configuration=Release;Platform=x64" ``` -## **Deploy** -The whole output can be found in ```x64/Release``` directory
-(or ```x64/Debug``` if you're building for ```Debug```, naturally) and: - - Devices (plugins) are inside ```devices/``` folder +## **Deployment** +The whole output can be found in `x64/Release` directory
+(or `x64/Debug` if you're building for `Debug`, naturally) and: + - Devices (plugins) are inside `devices/` folder Note: Debug builds will only work with a debug host,
-the same schema applies to OpenVR for the API and Amethyst. \ No newline at end of file +the same schema applies to OpenVR Driver, the API and Amethyst. \ No newline at end of file