vr.h¶

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

Table of Contents

Test/Example code
Functions
Defines
Types

Test/Example code ¶

The vr test code demonstrates how to use this API:

test_vr.c

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

displayIndex (int) – index of display (inclusive 0 to exclusive emscripten_vr_count_displays()).

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)¶

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 ¶

type 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¶

type 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.

type 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

type 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¶

type VREyeParameters¶

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

VRVector3 offset¶

unsigned long renderWidth¶

unsigned long renderHeight¶

Math¶

type VRVector3¶

A 3-dimensional vector.

float x¶

float y¶

float z¶

type VRQuaternion¶

A quaternion.

float x¶

float y¶

float z¶

float w¶

vr.h¶

Test/Example code¶

Functions¶

Initialization¶

API Queries¶

Display Functions¶

Render Loop¶

Defines¶

Types¶

Math¶

Test/Example code ¶

Functions ¶

Defines ¶

Types ¶