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