From 1332c771ca1669a7bffc0c6c19fd2364149c6f3e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81rmin?= Date: Tue, 12 Sep 2023 23:22:35 +0200 Subject: [PATCH] Separate developer documentation --- README.md | 181 +++++++++++++++-------------------------- docs/README.md | 6 ++ docs/browser-client.md | 7 ++ docs/client-project.md | 4 + docs/desktop-client.md | 23 ++++++ docs/server.md | 28 +++++++ 6 files changed, 134 insertions(+), 115 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/browser-client.md create mode 100644 docs/client-project.md create mode 100644 docs/desktop-client.md create mode 100644 docs/server.md diff --git a/README.md b/README.md index 95bacbd4..02da5be3 100644 --- a/README.md +++ b/README.md @@ -14,66 +14,6 @@ XOutput is a software that can convert [DirectInput](https://docs.microsoft.com/ DirectInput data is read and sent to a virtual XInput (Xbox 360 Controller) device. XInput is the new standard game controller input on windows, and DirectInput can no longer be used with [Universal Windows Platform](https://docs.microsoft.com/en-us/windows/uwp/) software, but with this tool you can use DirectInput devices as well. -Problem visualisation - -```mermaid -graph TD - subgraph XInput - X1(Xbox controller 1) -->|Read hardware input| XD[Xbox controller driver - xusb22.sys] - X2(Xbox controller 2) -->|Read hardware input| XD - XD -->|Read input| XR[XInput handler - xinput1_3.dll] - end - subgraph DirectInput - D1(fa:fa-gamepad Older controller) -->|Read hardware input| D1D[Controller driver] - D2(Joystick) -->|Read hardware input| D2D[Joystick driver] - D3(Gaming wheel) -->|Read hardware input| D3D[Gaming wheel driver] - D1D -->|Read input| DR[Direct input handler - dinput8.dll] - D2D -->|Read input| DR - D3D -->|Read input| DR - end - subgraph Games - XR -->|Read XInput| NG[Newer games] - XR -->|Read XInput| CG[Compatible games] - DR -->|Read DInput| CG[Compatible games] - DR -->|Read DInput| OG[Older games] - end -``` - -Offered solution - -```mermaid -graph TD - subgraph XInput - X1(Xbox controller 1) -->|Read hardware input| XD[Xbox controller driver - xusb22.sys] - X2(Xbox controller 2) -->|Read hardware input| XD - XD -->|Read input| XR[XInput handler - xinput1_3.dll] - end - subgraph DirectInput - D1(fa:fa-gamepad Older controller) -->|Read hardware input| D1D[Controller driver] - D2(Joystick) -->|Read hardware input| D2D[Joystick driver] - D3(Gaming wheel) -->|Read hardware input| D3D[Gaming wheel driver] - D1D -->|Read input| DR[Direct input handler - dinput8.dll] - D2D -->|Read input| DR - D3D -->|Read input| DR - end - DR -->|Read DInput| XOA[XOutput.App] - subgraph Solution - DR -->|Read HTML5 gamepad API| BC[Chrome] - DR -->|Read HTML5 gamepad API| BF[Firefox] - BC -->|Sends input| XOS[XOutput.Server] - BF -->|Sends input| XOS[XOutput.Server] - XOA -->|Sends input| XOS[XOutput.Server] - XOS -->|Control emulation| V[ViGEm] - end - V -->|Emulate controller| XD - subgraph Games - XR -->|Read XInput| NG[Newer games] - XR -->|Read XInput| CG[Compatible games] - DR -->|Read DInput| CG[Compatible games] - DR -->|Read DInput| OG[Older games] - end -``` - ## General information If you have any questions or feature requests feel free to create [Github Issue](https://github.com/csutorasa/XOutput/issues). @@ -106,7 +46,7 @@ Install one of the two libraries. ViGEm (preferred) or SCPToolkit (unsupported, Install: -- DirectX +- DirectX (any version that contains dinput8.dll) - Visual C++ Redistributable for Visual Studio 2015 32-bit - Visual C++ Redistributable for Visual Studio 2015 64-bit - all the drivers for your controllers @@ -126,17 +66,6 @@ Download the application: - Unzip to the same directory as before - If there are errors, remove the existing `conf` directory -## How it works - -| Component | Implementation | Description | -| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| Device emualation | ViGEm | External software that emulates XBox and DS4 controllers | -| Device emualation | SCP toolkit | Legacy external software that emulates XBox controllers | -| Backend | XOutput.Server | Server that collects data from clients and sends to the emulation software | -| Client | XOutput.App | Desktop application that collects data from the devices and sends to the backend | -| Client | Web controller | Web application that allows to emulate a device | -| Client | Web client | Web application that uses the [Gamepad API](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API) | - ## Hiding original input (exclusive mode) | Software | State | Download | @@ -144,7 +73,7 @@ Download the application: | [HidHide](https://github.com/nefarius/hidhide) | Active development | [HidHide](https://github.com/nefarius/HidHide/releases) | | [HidGuardian](https://github.com/nefarius/hidguardian) | Deprecated since Jul 27, 2023 | [HidGuardian](https://docs.nefarius.at/projects/HidGuardian/HidGuardian-Gen1-Installation/) | -### HidGuardian +### HidGuardian setup Affected devices and whitelist can be managed by the application, but it needs administrator priviledges. @@ -170,51 +99,73 @@ Manage process whitelist manually (use this method only, if you want to use HidG 4. Run `regedit` and go to `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\HidGuardian\Parameters\Whitelist` 5. Create subkey with the PID you found before. -## Developer Information - -The 4.x version backend is built with .NET 7, you will need to [download it](https://dotnet.microsoft.com/download). - -| Action | Required dependency | -| ------------------------------ | -------------------- | -| Running the server application | ASP.NET Core Runtime | -| Running the reader application | .NET Desktop Runtime | -| Building the application | SDK | +## Technical problem -However these runtimes and SDKs are cross platform the application is only compatible with Windows. - -### Server application - -The server application is responsible for: - -- collecting input from various sources -- mapping these sources -- emulating devices -- configuring all the above - -It is recommended to create a Windows task from the server, -so it can start at computer startup (with Administrator priviledges without UAC). -Help can be found in the [bin directory](./bin). - -Server application might write the registry, therefore it needs administrator prividledges. -Alternatively it can be started without admin access, but then when it tries to write the registry it will prompt UAC. - -### Webapp - -The web application required Node 16 to build it, you can [download it](https://nodejs.org/en/download/). -It can be found in the [web directory](./@xoutput). +Problem visualisation -### Reader application +```mermaid +graph TD + subgraph XInput + X1(Xbox controller 1) -->|Read hardware input| XD[Xbox controller driver - xusb22.sys] + X2(Xbox controller 2) -->|Read hardware input| XD + XD -->|Read input| XR[XInput handler - xinput1_3.dll] + end + subgraph DirectInput + D1(fa:fa-gamepad Older controller) -->|Read hardware input| D1D[Controller driver] + D2(Joystick) -->|Read hardware input| D2D[Joystick driver] + D3(Gaming wheel) -->|Read hardware input| D3D[Gaming wheel driver] + D1D -->|Read input| DR[Direct input handler - dinput8.dll] + D2D -->|Read input| DR + D3D -->|Read input| DR + end + subgraph Games + XR -->|Read XInput| NG[Newer games] + XR -->|Read XInput| CG[Compatible games] + DR -->|Read DInput| CG[Compatible games] + DR -->|Read DInput| OG[Older games] + end +``` -The reader application is a GUI Windows application which can read input values. +Offered solution -| Interface | Devices | Requirements | -| ------------ | ----------------------------- | --------------------------------------- | -| Windows API | Mouse and keyboard | None | -| Raw input | Mouse, keyboard and joysticks | USB device with drivers | -| Direct input | Joysticks | DirectX compatible devices with drivers | -| XInput | Joysticks | XInput compatible devices | +```mermaid +graph TD + subgraph XInput + X1(Xbox controller 1) -->|Read hardware input| XD[Xbox controller driver - xusb22.sys] + X2(Xbox controller 2) -->|Read hardware input| XD + XD -->|Read input| XR[XInput handler - xinput1_3.dll] + end + subgraph DirectInput + D1(fa:fa-gamepad Older controller) -->|Read hardware input| D1D[Controller driver] + D2(Joystick) -->|Read hardware input| D2D[Joystick driver] + D3(Gaming wheel) -->|Read hardware input| D3D[Gaming wheel driver] + D1D -->|Read input| DR[Direct input handler - dinput8.dll] + D2D -->|Read input| DR + D3D -->|Read input| DR + end + DR -->|Read DInput| XOA[XOutput.App] + subgraph Solution + DR -->|Read HTML5 gamepad API| B[Browser] + B -->|Browser| XOS[XOutput.Server] + XOA -->|Sends input| XOS[XOutput.Server] + XOS -->|Control emulation| V[ViGEm] + end + V -->|Emulate controller| XD + subgraph Games + XR -->|Read XInput| NG[Newer games] + XR -->|Read XInput| CG[Compatible games] + DR -->|Read DInput| CG[Compatible games] + DR -->|Read DInput| OG[Older games] + end +``` -### Client project +## How it works -The client project enabled developers to create a new type of input. -It can be used to integrate with the server application. +| Component | Implementation | Description | +| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| Device emualation | ViGEm | External software that emulates XBox and DS4 controllers | +| Device emualation | SCP toolkit | Legacy external software that emulates XBox controllers | +| Backend | XOutput.Server | Server that collects data from clients and sends to the emulation software | +| Client | XOutput.App | Desktop application that collects data from the devices and sends to the backend | +| Client | Web controller | Web application that allows to emulate a device | +| Client | Web client | Web application that uses the [Gamepad API](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API) | diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..189cf13b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,6 @@ +# Developer documentation + +- [server](server.md) +- [client-project](client-project.md) +- [desktop-client](desktop-client.md) +- [browser-client](browser-client.md) \ No newline at end of file diff --git a/docs/browser-client.md b/docs/browser-client.md new file mode 100644 index 00000000..1c7be912 --- /dev/null +++ b/docs/browser-client.md @@ -0,0 +1,7 @@ +# Browser client + +The browser client can be found in the [web directory](../@xoutput). + +## Prerequisites + +The web application required Node 16 to build it, you can [download it](https://nodejs.org/en/download/). diff --git a/docs/client-project.md b/docs/client-project.md new file mode 100644 index 00000000..191bf42d --- /dev/null +++ b/docs/client-project.md @@ -0,0 +1,4 @@ +# Client project + +The client project enabled developers to create a new type of input. +It can be used to integrate with the server application. diff --git a/docs/desktop-client.md b/docs/desktop-client.md new file mode 100644 index 00000000..e8342887 --- /dev/null +++ b/docs/desktop-client.md @@ -0,0 +1,23 @@ +# Desktop client + +## Prerequisites + +The 4.x version client is built with .NET 7, you will need to [download it](https://dotnet.microsoft.com/download). + +| Action | Required dependency | +| ------------------------------ | -------------------- | +| Running the reader application | .NET Desktop Runtime | +| Building the application | SDK | + +However these runtimes and SDKs are cross platform the application is only compatible with Windows. + +### Reader application + +The reader application is a GUI Windows application which can read input values. + +| Interface | Devices | Requirements | +| ------------ | ----------------------------- | --------------------------------------- | +| Windows API | Mouse and keyboard | None | +| Raw input | Mouse, keyboard | USB device with drivers | +| Direct input | Joysticks | DirectX compatible devices with drivers | +| XInput | Joysticks | XInput compatible devices | diff --git a/docs/server.md b/docs/server.md new file mode 100644 index 00000000..f6d2f2c8 --- /dev/null +++ b/docs/server.md @@ -0,0 +1,28 @@ +# Server + +## Prerequisites + +The 4.x version backend is built with .NET 7, you will need to [download it](https://dotnet.microsoft.com/download). + +| Action | Required dependency | +| ------------------------------ | -------------------- | +| Running the server application | ASP.NET Core Runtime | +| Building the application | SDK | + +However these runtimes and SDKs are cross platform the application is only compatible with Windows. + +## Server application + +The server application is responsible for: + +- collecting input from various sources +- mapping these sources +- emulating devices +- configuring all the above + +It is recommended to create a Windows task from the server, +so it can start at computer startup (with Administrator priviledges without UAC). +Help can be found in the [bin directory](./bin). + +Server application might write the registry, therefore it needs administrator prividledges. +Alternatively it can be started without admin access, but then when it tries to write the registry it will prompt UAC.