The C APIs in vr.h provide basic interfaces for interacting with WebVR from Emscripten.
Table of Contents
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.
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.
1 on success, 0 if the browsers WebVR support is insufficient.
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.
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.
1 if ready, 0 otherwise.
emscripten_vr_deinit
()¶Deinitialize the emscripten VR API. This will free all memory allocated for display name strings.
1 on success.
int
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.
emscripten_vr_version_minor
()¶Minor version of the WebVR API currently supported by the browser.
minor version of WebVR, or -1 if not supported or API not initialized.
int
emscripten_vr_version_major
()¶Major version of the WebVR API currently supported by the browser.
major version of WebVR, or -1 if not supported or API not initialized.
int
All of the following functions require emscripten_vr_init()
to have been
called the return value of emscripten_vr_ready()
to be true.
emscripten_vr_count_displays
()¶Number of displays connected.
int
emscripten_vr_get_display_handle
(int displayIndex)¶displayIndex (int) – index of display (inclusive 0 to exclusive emscripten_vr_count_displays()
).
handle for a VR display.
VRDisplayHandle
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()
.
handle (VRDisplayHandle) – a display handle.
name of the VR display or 0 (NULL) if the handle is invalid.
char*
emscripten_vr_display_connected
(VRDisplayHandle handle)¶handle (VRDisplayHandle) – a display handle.
true if the display is connected, false otherwise or when the handle is invalid.
bool
emscripten_vr_display_presenting
(VRDisplayHandle handle)¶See also emscripten_vr_request_present()
.
handle (VRDisplayHandle) – a display handle.
true if the display is currently presenting, false otherwise or when the handle is invalid.
bool
emscripten_vr_get_display_capabilities
(VRDisplayHandle handle, VRDisplayCapabilities *displayCaps)¶handle (VRDisplayHandle) – a display handle.
displayCaps (VRDisplayCapabilities) – receives capabilities of the VR display.
1 on success, 0 if handle was invalid.
bool
emscripten_vr_get_eye_parameters
(VRDisplayHandle handle, VREye whichEye, VREyeParameters *eyeParams)¶handle (VRDisplayHandle) – a display handle.
whichEye (VREye) – which eye to query parameters for.
eyeParam (VREyeParameters) – receives the parameters for requested eye.
1 on success, 0 if handle was invalid.
bool
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.
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.
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.
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.
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.
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.
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.
handle (VRDisplayHandle) – a display handle.
1 on success, 0 if handle was invalid.
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.
handle (VRDisplayHandle) – a display handle.
frameData (VRFrameData*) – Will receive the new framedata values.
1 on success, 0 if handle was invalid.
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.
handle (VRDisplayHandle) – a display handle.
1 on success, 0 if handle was invalid.
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.
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.
1 on success, 0 if handle was invalid.
emscripten_vr_exit_present
(VRDisplayHandle handle)¶Request present exit.
handle (VRDisplayHandle) – a display handle.
1 on success, 0 if handle was invalid.
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
.
VRDisplayCapabilities
¶Structure passed to emscripten_vr_get_display_capabilities()
, maps to the WebVR VRDisplayCapabilities interface.
hasPosition
¶hasExternalDisplay
¶canPresent
¶maxLayers
¶VRLayerInit
¶Structure passed to emscripten_vr_request_present()
, maps to the WebVR VRLayerInit interface.
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.
linearAcceleration
¶Linear acceleration, valid only if poseFlags & VR_POSE_LINEAR_ACCELERATION != 0
.
orientation
¶Orientation quaternion, valid only if poseFlags & VR_POSE_ORIENTATION != 0
.
angularVelocity
¶Angular velocity, valid only if poseFlags & VR_POSE_ANGULAR_VELOCITY != 0
.
VRFrameData
¶Structure passed to emscripten_vr_get_frame_data()
, maps to the WebVR
VRFrameData interface.
timestamp
¶float[16] leftProjectionMatrix
float[16] leftViewMatrix
float[16] rightProjectionMatrix
float[16] rightViewMatrix
VREyeParameters
¶Structure passed to emscripten_vr_get_eye_parameters()
, maps to the WebVR
VREyeParameters interface.
renderWidth
¶renderHeight
¶