-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathxrapi.html
More file actions
272 lines (255 loc) · 10.7 KB
/
Copy pathxrapi.html
File metadata and controls
272 lines (255 loc) · 10.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head profile="http://www.w3.org/2005/10/profile">
<link rel="icon" type="image/png" href="img/favicon.png">
<meta http-equiv="Content-Language" content="en" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="author" content="WinlatorXR" />
<meta name="description" content="WinlatorXR" />
<meta name="robots" content="index,nofollow" />
<meta name="copyright" content="WinlatorXR" />
<link rel="stylesheet" href="styles.css">
<title>WinlatorXR</title>
</head>
<body>
<script src="scripts.js" defer></script>
<p>
<strong>WinlatorXR's API</strong> provides 6DOF tracking data and controller inputs over UDP for use in games and mods within a container.
</p>
<p>
The XR API is an experimental and continuously evolving feature of WinlatorXR. As development progresses, multiple versions of the API are maintained to ensure long-term compatibility and to prevent existing projects from breaking as improvements and refinements are introduced. Because the API is still under active development, it is not yet designed to function as a complete replacement for the OpenXR runtime. At this stage, it must be implemented on a per-game or per-mod basis, allowing developers to selectively integrate XR functionality where needed.
</p>
<p>Some features of XR API include:</p>
<ul>
<li><strong>Render in 3D</strong> – WinlatorXR API supports rendering 3D content via both Side-By-Side (SBS) and Alternate Eye Rendering (AER) methods.</li>
<li><strong>Controller Haptics</strong> – UDP data returned from a game or app using the WinlatorXR API can trigger haptics in the player controllers.</li>
<li><strong>Monocular VR</strong> – For content that cannot render in 3D, 6DOF tracking can still be used for a monocular VR experience.</li>
<li><strong>VR in a Window</strong> – 6DOF tracking data can also be used without needing to render a fully immersive display, for a hybrid gaming experience.</li>
</ul>
<center>
<img src="img/winlatorxr_api.png"><br/>
<p>Rendering flow between WinlatorXR and sandboxed Windows app</p><br/>
</center>
<div>
<h2 class="heading-element" tabindex="-1">
Required changes for the Windows app
</h2>
</div>
<ol>
<li>
WinlatorXR checks for Z:\tmp\xr\version file and read the API version which should be used
</li>
<li>
The data are sent using UDP protocol on localhost:7872 as ASCII string in order which can be found below.
</li>
<li>
It is important to keep the Windows app as much in sync as possible, ideally holding renderer until HMD_SYNC changes.
</li>
<li>
Windows app have to render value of HMD_SYNC as shade of red (in sRGB colorspace) into top-left corner.
</li>
<li>
Information about used headset is written into Z:\tmp\xr\system (manufacturer, product, Android version, security patch version and virtual screen resolution).
</li>
</ol>
<center>
<img src="img/winlatorxr_pcvr.png"><br/>
<p>The major difference between PCVR and WinlatorXR API</p><br/>
</center>
<div>
<h2 class="heading-element" tabindex="-1">
XrAPI 0.5 specification
</h2>
</div>
<h3>Outgoing UDP Data (Windows App → WinlatorXR) for XR state</h3>
<p>The Windows app/game has to sent data on localhost:7278 as string of float numbers separated by space:</p>
<center><table>
<tr>
<th>Field</th><th>Type</th><th>Description</th>
</tr>
<tr>
<td>L_HAPTICS</td><td>Float</td><td>Left controller vibration duration (frames), this will be forwarded to bHaptics/ProTube accessory arm accessory (if available)</td>
</tr>
<tr>
<td>R_HAPTICS</td><td>Float</td><td>Right controller vibration duration (frames), this will be forwarded to bHaptics/ProTube accessory arm accessory (if available)</td>
</tr>
<tr>
<td>MODE_VR</td><td>Integer</td>
<td>
0 = Disable (no UDP data are sent), 1 = Enable VR, 2 = Screen mode (no automatic head tracking)<br/>
3 = Screen mode with head tracking mapped to mouse in 3DoF immersive mode
</td>
</tr>
<tr>
<td>MODE_3D</td><td>Integer</td><td>0 = No 3D, 1 = SBS, 2 = AER, -1 = User controlled</td>
</tr>
<tr>
<td>HMD_FOVX</td><td>Float</td><td>Custom horizontal FOV (degrees, if > 1)</td>
</tr>
<tr>
<td>HMD_FOVY</td><td>Float</td><td>Custom vertical FOV (degrees, if > 1)</td>
</tr>
</table></center>
<br/>
<p>3D mode defines which method is going to be used to render stereoscopic frames</p>
<center><table>
<tr>
<th>3D Mode</th><th>Description</th>
</tr>
<tr>
<td><strong>Side-by-Side (SBS)</strong></td>
<td>
The left half of the rendered frame is displayed to the left eye,
and the right half is displayed to the right eye.
</td>
</tr>
<tr>
<td><strong>Alternate Eye Rendering (AER)</strong></td>
<td>Set the blue frame sync pixel to: 0 when rendering the left eye, 255 when rendering the right eye<br/>
Rapidly alternating between left and right frames creates the stereoscopic 3D effect.
</td>
</tr>
<tr>
<td><strong>User controlled</strong></td>
<td>User can select in XR settings whenever SBS or flat mode should be used.</td>
</tr>
</table></center><br/><br/>
<h3>Optional outgoing UDP Data (Windows App → WinlatorXR) for XServer input simulation</h3>
<p>The Windows app/game could sent data on localhost:7728 as string of codes separated by commas to simulate an input</p>
<center><table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td><code>K</code></td>
<td>Array of integers</td>
<td>XServer keycodes separated by comma which should be simulated to press<br/>
The full list of supported keycodes could be found <a href="https://github.com/WinlatorXR/WinlatorXR/blob/c8fbecb49ec05e9093c1fe404ca98decea95b600/app/src/main/java/com/winlator/cmod/xserver/XKeycode.java" target="_blank" rel="noopener noreferrer">here</a>.<br/><br/>
Eg: "K,50,38" presses SHIFT_L and A at the same time</td>
</tr>
<tr>
<td><code>M</code></td>
<td>Array of booleans</td>
<td>Ones and zeros separated by comma representing state of the mouse buttons in order:<br/>
BUTTON_LEFT, BUTTON_RIGHT, BUTTON_MIDDLE, BUTTON_SCROLL_UP, BUTTON_SCROLL_DOWN.<br/><br/>
Eg: "M,1,0,0,0,0" triggers left mouse click</td>
</tr>
</table></center>
<h3>Incoming UDP Data (WinlatorXR → Windows App)</h3>
<p>WinlatorXR provides data on localhost:7872 (or localhost:7873 if second instance needed) as a string separated by space:</p>
<center><table>
<tr>
<th>Section</th><th>Fields</th><th>Description</th>
</tr>
<tr>
<td><strong>Float Array</strong></td>
<td valign="top">
<strong>Left Controller</strong><br>
L_QX, L_QY, L_QZ, L_QW<br>
L_THUMBSTICK_X, L_THUMBSTICK_Y<br>
L_X, L_Y, L_Z<br><br>
<strong>Right Controller</strong><br>
R_QX, R_QY, R_QZ, R_QW<br>
R_THUMBSTICK_X, R_THUMBSTICK_Y<br>
R_X, R_Y, R_Z<br><br>
<strong>Headset (HMD)</strong><br>
HMD_QX, HMD_QY, HMD_QZ, HMD_QW<br>
HMD_X, HMD_Y, HMD_Z<br>
HMD_IPD, HMD_FOVX, HMD_FOVY, HMD_SYNC
</td>
<td valign="top">
Space-separated float values representing full 6DOF tracking data.<br><br>
• QX/QY/QZ/QW = Quaternion rotation<br>
• X/Y/Z = Position in 3D space<br>
• THUMBSTICK_X/Y = Analog input values<br>
• HMD_IPD = Interpupillary distance<br>
• HMD_SYNC = Frame synchronization value
</td>
</tr>
<tr>
<td><strong>Boolean States</strong></td>
<td valign="top">
<strong>Left Controller</strong><br>
L_GRIP, L_MENU, L_THUMBSTICK_PRESS<br>
L_THUMBSTICK_LEFT, L_THUMBSTICK_RIGHT<br>
L_THUMBSTICK_UP, L_THUMBSTICK_DOWN<br>
L_TRIGGER, L_X, L_Y<br><br>
<strong>Right Controller</strong><br>
R_A, R_B, R_GRIP<br>
R_THUMBSTICK_PRESS<br>
R_THUMBSTICK_LEFT, R_THUMBSTICK_RIGHT<br>
R_THUMBSTICK_UP, R_THUMBSTICK_DOWN<br>
R_TRIGGER
</td>
<td valign="top">
Boolean string containing characters:<br>
<strong>T</strong> = TRUE<br>
<strong>F</strong> = FALSE<br><br>
Values are transmitted in the exact order shown.
</td>
</tr>
<tr>
<td><strong>Boolean States</strong></td>
<td valign="top">Immersive, SBS</td>
<td valign="top">
Boolean string containing characters:<br>
<strong>T</strong> = TRUE<br>
<strong>F</strong> = FALSE<br><br>
<strong>Immersive</strong> – 3DoF immersive mode active<br>
<strong>SBS</strong> – Side-by-side rendering enabled
</td>
</tr>
<tr>
<td><strong>Float Array</strong></td>
<td valign="top">
<strong>Headset (HMD)</strong><br>
HMD_ALTITUDE<br><br>
<strong>Left Controller</strong><br>
LG_QX, LG_QY, LG_QZ, LG_QW<br><br>
<strong>Right Controller</strong><br>
RG_QX, RG_QY, RG_QZ, RG_QW<br><br>
</td>
<td valign="top">
Space-separated float values representing additional 6DOF tracking data.<br><br>
* HMD_ALTITUDE = Height between detected floor and headset start tracking position<br><br>
• LG/RG = Left/right controller grip pose, this pose is oriented upwards<br>
• QX/QY/QZ/QW = Quaternion rotation
</td>
</tr>
</table></center>
<div>
<h2 class="heading-element" tabindex="-1">
Code examples
</h2>
</div>
<ul>
<li>
<a target="_blank" rel="noopener noreferrer" href="https://github.com/bigelod/SixDOFinator_MinimalProject">SixDOFinator_MinimalProject</a> - Unity sample implementation (minimal project EXE, C#)
</li>
<li>
<a target="_blank" rel="noopener noreferrer" href="https://github.com/bigelod/SixDOFinator_SampleProject">SixDOFinator_SampleProject</a> - Unity sample implementation (full project EXE, C#)
</li>
<li>
<a target="_blank" rel="noopener noreferrer" href="https://github.com/WinlatorXR/opentrackWXR">opentrackWXR</a> - A fork of Opentrack to send 6DOF data to TrackIR compatible games (full project EXE, C++)
</li>
<li>
<a target="_blank" rel="noopener noreferrer" href="https://github.com/WinlatorXR/HaloCEWXR">HWXR</a> - A fork of the Halo CE PCVR mod to support the WinlatorXR API (mod DLL, C++)
</li>
</ul>
<div>
<h2 class="heading-element" tabindex="-1">
Code tools
</h2>
</div>
<ul>
<li>
<a target="_blank" rel="noopener noreferrer" href="https://github.com/WinlatorXR/XrAPIUDPTester">XrAPIUDPTester</a> - A simple tool for sending test 6DOF data to your own games or apps (full project EXE, C#)
</li>
</ul>
<center>
<iframe src="https://www.youtube.com/embed/aPVFDYeOwXw?si=K3QUILYvzwA3l2qc" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen class="youtube-embed"></iframe>
</center>
</body>
</html>