1.. _vr-h:
2
3====
4vr.h
5====
6
7The C APIs in `vr.h <https://github.com/emscripten-core/emscripten/blob/master/system/include/emscripten/vr.h>`_ provide basic interfaces for interacting with WebVR from Emscripten.
8
9.. contents:: Table of Contents
10  :local:
11  :depth: 1
12
13.. _test-example-code-vr-api:
14
15Test/Example code
16-----------------
17
18The vr test code demonstrates how to use this API:
19
20  - `test_vr.c <https://github.com/emscripten-core/emscripten/blob/master/tests/test_vr.c>`_
21
22.. _functions-vr-api:
23
24Functions
25---------
26
27Initialization
28==============
29
30.. c:function:: int emscripten_vr_init(em_vr_arg_callback_func callback, void* userData)
31
32  Initialize the emscripten VR API. This will `navigator.getVRDisplays()
33  <https://w3c.github.io/webvr/spec/1.1/#navigator-getvrdisplays-attribute>`_
34  and when completed, set the return of :c:func:`emscripten_vr_ready` to be `true`.
35
36  :param em_vr_callback_arg_func callback: C function to call when initialization is complete. The function signature must have a ``void*`` parameter for passing the ``arg`` value.
37  :param void* arg: User-defined data passed to the callback, untouched by the API itself.
38  :returns: `1` on success, `0` if the browsers WebVR support is insufficient.
39  :rtype: int
40
41.. tip:: This call succeeding is not sufficient for use of the rest of the API. Please
42  make sure to wait until the callback is executed.
43
44.. c:function:: int emscripten_vr_ready()
45
46  Check whether the VR API has finished initializing VR displays.
47  See also :c:func:`emscripten_vr_init`.
48
49  This function may return `1` event if WebVR is not supported in the
50  running browser.
51
52  :returns: `1` if ready, `0` otherwise.
53
54.. c:function:: int emscripten_vr_deinit()
55
56  Deinitialize the emscripten VR API. This will free all memory allocated for
57  display name strings.
58
59  :returns: `1` on success.
60  :rtype: int
61
62API Queries
63===========
64
65All of the following functions require :c:func:`emscripten_vr_init` to have been
66called but do not require VR displays and can therefore be called before the return
67value of :c:func:`emscripten_vr_ready` is `true`.
68
69.. c:function:: int emscripten_vr_version_minor()
70
71  Minor version of the WebVR API currently supported by the browser.
72
73  :returns: minor version of WebVR, or `-1` if not supported or API not initialized.
74  :rtype: int
75
76.. c:function:: int emscripten_vr_version_major()
77
78  Major version of the WebVR API currently supported by the browser.
79
80  :returns: major version of WebVR, or `-1` if not supported or API not initialized.
81  :rtype: int
82
83Display Functions
84=================
85
86All of the following functions require :c:func:`emscripten_vr_init` to have been
87called the return value of :c:func:`emscripten_vr_ready` to be `true`.
88
89.. c:function:: int emscripten_vr_count_displays()
90
91  :returns: Number of displays connected.
92  :rtype: int
93
94.. c:function:: VRDisplayHandle emscripten_vr_get_display_handle(int displayIndex)
95
96  :param int displayIndex: index of display (inclusive 0 to exclusive :c:func:`emscripten_vr_count_displays`).
97  :returns: handle for a VR display.
98  :rtype: VRDisplayHandle
99
100.. c:function:: const char* emscripten_vr_get_display_name(VRDisplayHandle handle)
101
102  Get a user-readable name which identifies the VR display. The memory for the
103  returned string is managed by the API and will be freed on
104  :c:func:`emscripten_vr_deinit`.
105
106  :param VRDisplayHandle handle: |display-handle-parameter-doc|
107  :returns: name of the VR display or `0 (NULL)` if the handle is invalid.
108  :rtype: char*
109
110.. c:function:: bool emscripten_vr_display_connected(VRDisplayHandle handle)
111
112  :param VRDisplayHandle handle: |display-handle-parameter-doc|
113  :returns: `true` if the display is connected, `false` otherwise or when
114    the handle is invalid.
115  :rtype: bool
116
117.. c:function:: bool emscripten_vr_display_presenting(VRDisplayHandle handle)
118
119  See also :c:func:`emscripten_vr_request_present`.
120
121  :param VRDisplayHandle handle: |display-handle-parameter-doc|
122  :returns: `true` if the display is currently presenting, `false` otherwise
123    or when the handle is invalid.
124  :rtype: bool
125
126.. c:function:: int emscripten_vr_get_display_capabilities(VRDisplayHandle handle, VRDisplayCapabilities* displayCaps)
127
128  :param VRDisplayHandle handle: |display-handle-parameter-doc|
129  :param VRDisplayCapabilities displayCaps: receives capabilities of the VR display.
130  :returns: |display-function-return-doc|
131  :rtype: bool
132
133.. c:function:: int emscripten_vr_get_eye_parameters(VRDisplayHandle handle, VREye whichEye, VREyeParameters* eyeParams)
134
135  :param VRDisplayHandle handle: |display-handle-parameter-doc|
136  :param VREye whichEye: which eye to query parameters for.
137  :param VREyeParameters eyeParam: receives the parameters for requested eye.
138  :returns: |display-function-return-doc|
139  :rtype: bool
140
141Render Loop
142===========
143
144In contrast to the usual emscripten main loop (see :ref:`emscripten-h-browser-execution-environment`),
145VR displays require their own rendering loop which is independent from the main loop. The rendering
146loop can be set per display and will act like a main loop with timing mode ``EM_TIMING_RAF`` until the
147display is requested to present, as of which it will run at the VR display's refresh rate.
148
149.. c:function:: void emscripten_vr_set_display_render_loop(VRDisplayHandle handle, em_vr_callback_func callback)
150
151  Set a C function as the per frame rendering callback of a VR display.
152
153  :param VRDisplayHandle handle: |display-handle-parameter-doc|: id of the display to set the render loop for.
154  :param em_vr_callback_func callback: C function to set as per frame rendering callback.
155  :rtype: |display-function-return-doc|
156
157.. tip:: There can be only *one* render loop function per VR display. To change the render loop function, first :c:func:`cancel <emscripten_vr_cancel_display_render_loop>` the current loop, and then call this function to set another.
158
159.. c:function:: void emscripten_vr_set_display_render_loop_arg(VRDisplayHandle handle, em_vr_callback_func callback, void* arg)
160
161  Set a C function as the per frame rendering callback of a VR display.
162
163  :param VRDisplayHandle handle: |display-handle-parameter-doc|
164  :param em_vr_callback_arg_func callback: C function to set as per frame rendering callback. The function signature must have a ``void*`` parameter for passing the ``arg`` value.
165  :param void* arg: User-defined data passed to the render loop function, untouched by the API itself.
166  :rtype: |display-function-return-doc|
167
168.. c:function:: void emscripten_vr_cancel_display_render_loop(VRDisplayHandle handle: |display-handle-parameter-doc|)
169
170  Cancels the render loop of a VR display should there be one running for it.
171
172  |render-loop-info|
173
174  :param VRDisplayHandle handle: |display-handle-parameter-doc|
175  :rtype: |display-function-return-doc|
176
177.. c:function:: int emscripten_vr_get_frame_data(VRDisplayHandle handle, VRFrameData* frameData)
178
179  Get view matrix, projection matrix, timestamp and head pose for current frame.
180  Only valid when called from within a render loop callback.
181
182  |render-loop-info|
183
184  :param VRDisplayHandle handle: |display-handle-parameter-doc|
185  :param VRFrameData* frameData: Will receive the new framedata values.
186  :rtype: |display-function-return-doc|
187
188.. c:function:: int emscripten_vr_submit_frame(VRDisplayHandle handle)
189
190  Submit the current state of canvases passed via VRLayerInit to
191  :c:func:`emscripten_vr_request_present` to be rendered to the VR display.
192  Only valid when called from within a render loop callback.
193
194  |render-loop-info|
195
196  :param VRDisplayHandle handle: |display-handle-parameter-doc|
197  :rtype: |display-function-return-doc|
198
199.. c:function:: int emscripten_vr_request_present(VRDisplayHandle handle, VRLayerInit* layerInit, int layerCount, em_vr_arg_callback_func callback, void* userData)
200
201  Request present for the VR display using canvases specified in the `layerInit` array.
202  If the request is successful `callback` will be called with `userData` and the render
203  loop will continue rendering at the refresh rate of the VR display.
204
205  Must be called from a user callback (see :ref:`HTML5 API <html5-h>`).
206
207  See the specification of `VRDisplay.requestPresent <https://w3c.github.io/webvr/spec/1.1/#dom-vrdisplay-requestpresent>`_ for detailed information.
208
209  :param VRDisplayHandle handle: |display-handle-parameter-doc|
210  :param VRLayerInit layers: array of layers which will be rendered to.
211  :param int layerCount: number of layers in `layers`.
212  :param em_vr_arg_callback_func callback: optional function that will be called when the requst has succeeded.
213  :param void* userData: optional data to pass to the callback when the request succeeds. Is not modified by the API.
214  :rtype: |display-function-return-doc|
215
216.. c:function:: int emscripten_vr_exit_present(VRDisplayHandle handle)
217
218  Request present exit.
219
220  :param VRDisplayHandle handle: |display-handle-parameter-doc|
221  :rtype: |display-function-return-doc|
222
223.. _defines-vr-api:
224
225Defines
226-------
227
228.. c:macro:: VR_EYE_LEFT
229  VR_EYE_RIGHT
230
231  Eye values for use with :c:func:`emscripten_vr_get_eye_parameters`.
232
233.. _vr-pose-defines-vr-api:
234
235.. c:macro:: VR_POSE_POSITION
236  VR_POSE_LINEAR_VELOCITY
237  VR_POSE_LINEAR_ACCELERATION
238  VR_POSE_ORIENTATION
239  VR_POSE_ANGULAR_VELOCITY
240  VR_POSE_ANGULAR_ACCELERATION
241
242  Flags which describe which properties of a :c:type:`VRPose` are valid.
243
244.. c:macro:: VR_LAYER_DEFAULT_LEFT_BOUNDS
245  VR_LAYER_DEFAULT_RIGHT_BOUNDS
246
247  Default values to pass to :c:type:`VRLayerInit`.
248
249.. _types-vr-api:
250
251Types
252-----
253
254.. c:type:: VRDisplayCapabilities
255
256  Structure passed to :c:func:`emscripten_vr_get_display_capabilities`, maps to the WebVR `VRDisplayCapabilities <https://w3c.github.io/webvr/spec/1.1/#interface-vrdisplaycapabilities>`__ interface.
257
258  .. c:member:: int32_t hasPosition
259
260  .. c:member:: int32_t hasExternalDisplay
261
262  .. c:member:: int32_t canPresent
263
264  .. c:member:: unsigned long maxLayers
265
266
267.. c:type:: VRLayerInit
268
269  Structure passed to :c:func:`emscripten_vr_request_present`, maps to the WebVR `VRLayerInit <https://w3c.github.io/webvr/spec/1.1/#interface-vrlayerinit>`__ interface.
270
271  .. c:member:: const char* source
272
273    Id of the source canvas which will be used to present to the VR display.
274
275    `0 (NULL)` is used to refer to ``Module.canvas``.
276
277  .. c:member:: float[4] leftBounds
278
279    Texture bounds of the left eye on the target canvas. Initialize with :c:macro:`VR_LAYER_DEFAULT_LEFT_BOUNDS` for default.
280
281  .. c:member:: float[4] rightBounds
282
283    Texture bounds of the right eye on the target canvas. Initialize with :c:macro:`VR_LAYER_DEFAULT_RIGHT_BOUNDS` for default.
284
285
286.. c:type:: VRPose
287
288  Substructure of :c:type:`VRFrameData`, maps to the WebVR
289  `VRPose <https://w3c.github.io/webvr/spec/1.1/#interface-vrpose>`__ interface.
290
291  VR Displays do not necessarily report all of the pose values (mobile VR devices usually
292  only report orientation, but not position for example). To check which values are valid,
293  the :c:member:`poseFlags <poseFlags>` member provides a bitmask of
294  :ref:`VR_POSE_* <vr-pose-defines-vr-api>` which has a bit set for every valid value.
295
296  .. c:member:: VRVector3 position
297
298    Position, valid only if ``poseFlags & VR_POSE_POSITION != 0``.
299
300  .. c:member:: VRVector3 linearVelocity
301
302    Linear velocity, valid only if ``poseFlags & VR_POSE_LINEAR_VELOCITY != 0``.
303
304  .. c:member:: VRVector3 linearAcceleration
305
306    Linear acceleration, valid only if ``poseFlags & VR_POSE_LINEAR_ACCELERATION != 0``.
307
308  .. c:member:: VRQuaternion orientation
309
310    Orientation quaternion, valid only if ``poseFlags & VR_POSE_ORIENTATION != 0``.
311
312  .. c:member:: VRVector3 angularVelocity
313
314    Angular velocity, valid only if ``poseFlags & VR_POSE_ANGULAR_VELOCITY != 0``.
315
316  .. c:member:: VRVector3 angularAcceleration
317
318    Angular acceleration, valid only if ``poseFlags & VR_POSE_ANGULAR_ACCELERATION != 0``.
319
320  .. c:member:: int poseFlags
321
322    Bitmask of :ref:`VR_POSE_* <vr-pose-defines-vr-api>` which determines whether the corresponding pose attributes are valid
323
324
325.. c:type:: VRFrameData
326
327  Structure passed to :c:func:`emscripten_vr_get_frame_data`, maps to the WebVR
328  `VRFrameData <https://w3c.github.io/webvr/spec/1.1/#interface-vrframedata>`__ interface.
329
330  .. c:member:: double timestamp
331
332  .. c:member:: float[16] leftProjectionMatrix
333
334  .. c:member:: float[16] leftViewMatrix
335
336  .. c:member:: float[16] rightProjectionMatrix
337
338  .. c:member:: float[16] rightViewMatrix
339
340  .. c:member:: VRPose pose
341
342
343.. c:type:: VREyeParameters
344
345  Structure passed to :c:func:`emscripten_vr_get_eye_parameters`, maps to the WebVR
346  `VREyeParameters <https://w3c.github.io/webvr/spec/1.1/#interface-vreyeparameters>`__ interface.
347
348  .. c:member:: VRVector3 offset
349
350  .. c:member:: unsigned long renderWidth
351
352  .. c:member:: unsigned long renderHeight
353
354Math
355====
356
357.. c:type:: VRVector3
358
359  A 3-dimensional vector.
360
361  .. c:member:: float x
362
363  .. c:member:: float y
364
365  .. c:member:: float z
366
367
368.. c:type:: VRQuaternion
369
370  A quaternion.
371
372  .. c:member:: float x
373
374  .. c:member:: float y
375
376  .. c:member:: float z
377
378  .. c:member:: float w
379
380
381
382.. COMMENT (not rendered): Following values are common to many functions, and currently only updated in one place (here).
383.. COMMENT (not rendered): These can be properly replaced if required either wholesale or on an individual basis.
384
385.. |display-handle-parameter-doc| replace:: a display handle.
386
387.. |display-function-return-doc| replace:: `1` on success, `0` if handle was invalid.
388
389.. |render-loop-info| replace:: See also :c:func:`emscripten_vr_set_display_render_loop` and :c:func:`emscripten_vr_set_display_render_loop_arg` for information about setting and using the render loop.
390
391