vr.h

The C APIs in vr.h provide basic interfaces for interacting with WebVR from Emscripten.

Test/Example code

The vr test code demonstrates how to use this API:

Functions

Initialization

int emscripten_vr_init(em_vr_arg_callback_func callback, void* userData)

Initialize the emscripten VR API. This will navigator.getVRDisplays() and when completed, set the return of emscripten_vr_ready() to be true.

Parameters:
  • callback (em_vr_callback_arg_func) – C function to call when initialization is complete. The function signature must have a void* parameter for passing the arg value.
  • arg (void*) – User-defined data passed to the callback, untouched by the API itself.
Returns:

1 on success, 0 if the browsers WebVR support is insufficient.
Return type:

int

Tip

This call succeeding is not sufficient for use of the rest of the API. Please make sure to wait until the callback is executed.

int emscripten_vr_ready()

Check whether the VR API has finished initializing VR displays. See also emscripten_vr_init().

This function may return 1 event if WebVR is not supported in the running browser.

Returns:1 if ready, 0 otherwise.
int emscripten_vr_deinit()

Deinitialize the emscripten VR API. This will free all memory allocated for display name strings.

Returns:1 on success.
Return type:int

API Queries

All of the following functions require emscripten_vr_init() to have been called but do not require VR displays and can therefore be called before the return value of emscripten_vr_ready() is true.

int emscripten_vr_version_minor()

Minor version of the WebVR API currently supported by the browser.

Returns:minor version of WebVR, or -1 if not supported or API not initialized.
Return type:int
int emscripten_vr_version_major()

Major version of the WebVR API currently supported by the browser.

Returns:major version of WebVR, or -1 if not supported or API not initialized.
Return type:int

Display Functions

All of the following functions require emscripten_vr_init() to have been called the return value of emscripten_vr_ready() to be true.

int emscripten_vr_count_displays()
Returns:Number of displays connected.
Return type:int
VRDisplayHandle emscripten_vr_get_display_handle(int displayIndex)
Parameters:
Returns:

handle for a VR display.
Return type:

VRDisplayHandle
const char* emscripten_vr_get_display_name(VRDisplayHandle handle)

Get a user-readable name which identifies the VR display. The memory for the returned string is managed by the API and will be freed on emscripten_vr_deinit().

Parameters:
  • handle (VRDisplayHandle) – a display handle.
Returns:

name of the VR display or 0 (NULL) if the handle is invalid.
Return type:

char*
bool emscripten_vr_display_connected(VRDisplayHandle handle)
Parameters:
  • handle (VRDisplayHandle) – a display handle.
Returns:

true if the display is connected, false otherwise or when the handle is invalid.
Return type:

bool
bool emscripten_vr_display_presenting(VRDisplayHandle handle)

See also emscripten_vr_request_present().

Parameters:
  • handle (VRDisplayHandle) – a display handle.
Returns:

true if the display is currently presenting, false otherwise or when the handle is invalid.
Return type:

bool
int emscripten_vr_get_display_capabilities(VRDisplayHandle handle, VRDisplayCapabilities* displayCaps)
Parameters:
  • handle (VRDisplayHandle) – a display handle.
  • displayCaps (VRDisplayCapabilities) – receives capabilities of the VR display.
Returns:

1 on success, 0 if handle was invalid.
Return type:

bool
int emscripten_vr_get_eye_parameters(VRDisplayHandle handle, VREye whichEye, VREyeParameters* eyeParams)
Parameters:
  • handle (VRDisplayHandle) – a display handle.
  • whichEye (VREye) – which eye to query parameters for.
  • eyeParam (VREyeParameters) – receives the parameters for requested eye.
Returns:

1 on success, 0 if handle was invalid.
Return type:

bool

Render Loop

In contrast to the usual emscripten main loop (see Browser Execution Environment), VR displays require their own rendering loop which is independent from the main loop. The rendering loop can be set per display and will act like a main loop with timing mode EM_TIMING_RAF until the display is requested to present, as of which it will run at the VR display’s refresh rate.

void emscripten_vr_set_display_render_loop(VRDisplayHandle handle, em_vr_callback_func callback)

Set a C function as the per frame rendering callback of a VR display.

Parameters:
  • handle (VRDisplayHandle) – a display handle.: id of the display to set the render loop for.
  • callback (em_vr_callback_func) – C function to set as per frame rendering callback.
Return type:

1 on success, 0 if handle was invalid.

Tip

There can be only one render loop function per VR display. To change the render loop function, first cancel the current loop, and then call this function to set another.

void emscripten_vr_set_display_render_loop_arg(VRDisplayHandle handle, em_vr_callback_func callback, void* arg)

Set a C function as the per frame rendering callback of a VR display.

Parameters:
  • handle (VRDisplayHandle) – a display handle.
  • callback (em_vr_callback_arg_func) – C function to set as per frame rendering callback. The function signature must have a void* parameter for passing the arg value.
  • arg (void*) – User-defined data passed to the render loop function, untouched by the API itself.
Return type:

1 on success, 0 if handle was invalid.
void emscripten_vr_cancel_display_render_loop(VRDisplayHandle handle: |display-handle-parameter-doc|)

Cancels the render loop of a VR display should there be one running for it.

See also emscripten_vr_set_display_render_loop() and emscripten_vr_set_display_render_loop_arg() for information about setting and using the render loop.

Parameters:
  • handle (VRDisplayHandle) – a display handle.
Return type:

1 on success, 0 if handle was invalid.
int emscripten_vr_get_frame_data(VRDisplayHandle handle, VRFrameData* frameData)

Get view matrix, projection matrix, timestamp and head pose for current frame. Only valid when called from within a render loop callback.

See also emscripten_vr_set_display_render_loop() and emscripten_vr_set_display_render_loop_arg() for information about setting and using the render loop.

Parameters:
  • handle (VRDisplayHandle) – a display handle.
  • frameData (VRFrameData*) – Will receive the new framedata values.
Return type:

1 on success, 0 if handle was invalid.
int emscripten_vr_submit_frame(VRDisplayHandle handle)

Submit the current state of canvases passed via VRLayerInit to emscripten_vr_request_present() to be rendered to the VR display. Only valid when called from within a render loop callback.

See also emscripten_vr_set_display_render_loop() and emscripten_vr_set_display_render_loop_arg() for information about setting and using the render loop.

Parameters:
  • handle (VRDisplayHandle) – a display handle.
Return type:

1 on success, 0 if handle was invalid.
int emscripten_vr_request_present(VRDisplayHandle handle, VRLayerInit* layerInit, int layerCount, em_vr_arg_callback_func callback, void* userData)

Request present for the VR display using canvases specified in the layerInit array. If the request is successful callback will be called with userData and the render loop will continue rendering at the refresh rate of the VR display.

Must be called from a user callback (see HTML5 API).

See the specification of VRDisplay.requestPresent for detailed information.

Parameters:
  • handle (VRDisplayHandle) – a display handle.
  • layers (VRLayerInit) – array of layers which will be rendered to.
  • layerCount (int) – number of layers in layers.
  • callback (em_vr_arg_callback_func) – optional function that will be called when the requst has succeeded.
  • userData (void*) – optional data to pass to the callback when the request succeeds. Is not modified by the API.
Return type:

1 on success, 0 if handle was invalid.
int emscripten_vr_exit_present(VRDisplayHandle handle)

Request present exit.

Parameters:
  • handle (VRDisplayHandle) – a display handle.
Return type:

1 on success, 0 if handle was invalid.

Defines

VR_EYE_LEFT
VR_EYE_RIGHT

Eye values for use with emscripten_vr_get_eye_parameters().

VR_POSE_POSITION
VR_POSE_LINEAR_VELOCITY
VR_POSE_LINEAR_ACCELERATION
VR_POSE_ORIENTATION
VR_POSE_ANGULAR_VELOCITY
VR_POSE_ANGULAR_ACCELERATION

Flags which describe which properties of a VRPose are valid.

VR_LAYER_DEFAULT_LEFT_BOUNDS
VR_LAYER_DEFAULT_RIGHT_BOUNDS

Default values to pass to VRLayerInit.

Types

VRDisplayCapabilities

Structure passed to emscripten_vr_get_display_capabilities(), maps to the WebVR VRDisplayCapabilities interface.

int32_t hasPosition
int32_t hasExternalDisplay
int32_t canPresent
unsigned long maxLayers
VRLayerInit

Structure passed to emscripten_vr_request_present(), maps to the WebVR VRLayerInit interface.

const char* source

Id of the source canvas which will be used to present to the VR display.

0 (NULL) is used to refer to Module.canvas.

float[4] leftBounds

Texture bounds of the left eye on the target canvas. Initialize with VR_LAYER_DEFAULT_LEFT_BOUNDS for default.

float[4] rightBounds

Texture bounds of the right eye on the target canvas. Initialize with VR_LAYER_DEFAULT_RIGHT_BOUNDS for default.

VRPose

Substructure of VRFrameData, maps to the WebVR VRPose interface.

VR Displays do not necessarily report all of the pose values (mobile VR devices usually only report orientation, but not position for example). To check which values are valid, the poseFlags member provides a bitmask of VR_POSE_* which has a bit set for every valid value.

VRVector3 position

Position, valid only if poseFlags & VR_POSE_POSITION != 0.

VRVector3 linearVelocity

Linear velocity, valid only if poseFlags & VR_POSE_LINEAR_VELOCITY != 0.

VRVector3 linearAcceleration

Linear acceleration, valid only if poseFlags & VR_POSE_LINEAR_ACCELERATION != 0.

VRQuaternion orientation

Orientation quaternion, valid only if poseFlags & VR_POSE_ORIENTATION != 0.

VRVector3 angularVelocity

Angular velocity, valid only if poseFlags & VR_POSE_ANGULAR_VELOCITY != 0.

VRVector3 angularAcceleration

Angular acceleration, valid only if poseFlags & VR_POSE_ANGULAR_ACCELERATION != 0.

int poseFlags

Bitmask of VR_POSE_* which determines whether the corresponding pose attributes are valid

VRFrameData

Structure passed to emscripten_vr_get_frame_data(), maps to the WebVR VRFrameData interface.

double timestamp
float[16] leftProjectionMatrix
float[16] leftViewMatrix
float[16] rightProjectionMatrix
float[16] rightViewMatrix
VRPose pose
VREyeParameters

Structure passed to emscripten_vr_get_eye_parameters(), maps to the WebVR VREyeParameters interface.

VRVector3 offset
unsigned long renderWidth
unsigned long renderHeight

Math

VRVector3

A 3-dimensional vector.

float x
float y
float z
VRQuaternion

A quaternion.

float x
float y
float z
float w