-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathxrapi.html
More file actions
229 lines (215 loc) · 8.88 KB
/
xrapi.html
File metadata and controls
229 lines (215 loc) · 8.88 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
<!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).
</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.4 specification
</h2>
</div>
<h3>Outgoing UDP Data (Windows App → WinlatorXR)</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>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>
</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>