Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Separate developer documentation #793

Merged
merged 1 commit into from
Sep 12, 2023
Merged

Separate developer documentation #793

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 66 additions & 115 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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
Expand All @@ -126,25 +66,14 @@ 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 |
| ------------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------- |
| [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.

Expand All @@ -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) |
6 changes: 6 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Developer documentation

- [server](server.md)
- [client-project](client-project.md)
- [desktop-client](desktop-client.md)
- [browser-client](browser-client.md)
7 changes: 7 additions & 0 deletions docs/browser-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/).
4 changes: 4 additions & 0 deletions docs/client-project.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
23 changes: 23 additions & 0 deletions docs/desktop-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 |
28 changes: 28 additions & 0 deletions docs/server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading