README.md

OVR Toolkit API Helper

This library wraps the OVR Toolkit API and provides properties and helper methods to make accessing and controlling windows easier. This script will only work when executed within a Custom App browser window in OVR Toolkit.

TODO: Add note on request flow in library/OVR Toolkit Rename references to transform to details

OVR Toolkit Custom Apps Wiki Page

Table Of Contents

• Methods
  • Setup
  • Setup Logging
  • Creating Windows
    • Web Window
    • Desktop Window
    • Application Window
    • Spawn Window
  • Using Windows
    • Get Window Details
    • Get Window Type
    • Close Window
    • Refresh Web Window
    • Get Window Boundaries
    • Set Window Position
    • Set Window Rotation
    • Set Window Setting
  • Messaging
    • Broadcast To All Web Windows
    • Send To A Specific Web Window
  • Update Properties
    • Get Monitor Count
    • Get Window Titles
  • Enable/Disable Updates
• Properties
  • Data Properties
    • Total Monitors
    • Window List
    • Knuckles Finger Curls
    • HMD/Controller Positions
  • Update Flags
    • Toggle Knuckles Finger Curl Updates
    • Toggle Window List Updates
    • Toggle HMD/Controller Position Updates
    • Toggle Window List Updates
    • Toggle Window Move/Resize Updates
  • Constants
    • Window Attached Device
    • Window Types
    • Window Settings
    • New Transform
• Events
  • Window Opened
  • Window Closed
  • Window Mouse Enter/Leave
  • Message Received
• Notes

Methods

Setup

ovrt.setup(selector)

This function calls ovrt.setupLogging(selector) and populates the value of ovrt.totalMonitors

Argument	Type	Description
selector	String	A valid HTML selector

Setup Logging

ovrt.setupLogging(selector)

This library includes logging functions that will override the windows console.log method and error handlers and redirects their output to a DOM element. This means you can write regular console.log commands and the output of that and any errors will be appended to the innerHTML of the element you specify.

Argument	Type	Description
selector	String	A valid HTML selector

Example Output:

<!-- console.log -->
<p class="console-item log-item">
  <span class="timestamp">12:46:26:160</span>&nbsp;
  <span class="prefix">[LOG]</span>&nbsp;
  <span class="message">Console log test</span>
</p>

<!-- Error output -->
<p class="error-item log-item">
  <span class="timestamp">${time}</span>&nbsp;
  <span class="prefix">[ERROR]</span>&nbsp;
  <span class="message">${errorMsg}</span>
  &nbsp;-&nbsp;
  <span class="lineNumber">L${lineNumber}</span>
  &nbsp;-&nbsp;
  <span class="url">${url}</span>
</p>

Creating Windows

This library abstracts the window creation process with type-specific helper functions that accept a function definition for a callback instead of a string. These functions will also accept a data object that will be passed to the callback as a final parameter.

Web Window

ovrt.createWebWin(url, width, height, callback, data)

Argument	Type	Description	Optional
url	String	URL to open the web screen to
width	Number	The width of the screen in pixels
height	Number	The height of the screen in pixels
callback	Function	A function definition to callback once the window is created	True
data	Any	This value will be passed as a second parameter to the callback after the window uid	True

Desktop Window

ovrt.createDesktopWin(monitorId, callback, data)

Argument	Type	Description	Optional
monitorId	Number	Which physical display to capture
callback	Function	A function definition to callback once the window is created	True
data	Any	This value will be passed as a second parameter to the callback after the window uid	True

Application Window

ovrt.createWin(windowHandle, callback, data)

Argument	Type	Description	Optional
windowHandle	Number	A window handle from ovrt.windowTitles
callback	Function	A function definition to callback once the window is created	True
data	Any	This value will be passed as a second parameter to the callback after the window uid	True

Spawn Window

ovrt.requestWinSpawn(type, contents, callback, data, transform)

Makes a request to OVRToolkit for a new window to be spawned with the specified properties. type must match an OVR Toolkit window type constant.

Contents value is determined by the window type. Desktops require a Number monitorId, applicaitions require a Number windowHandle, and web screens require an OVRWebContents object. This method is used internally by createWin, createDesktopWin, and createWebWin.

Argument	Type	Description	Optional
type	Number	A window type as defined in ovrt.winTypes
contents	Any	This window contents, can be OVRWebContents or Number
callback	Function	A function definition to callback once the window is created	True
data	Any	This value will be passed as a second parameter to the callback after the window uid	True
transform	Object	An OVROverlayTransform to create the window with, if undefined then ovrt.newTransform is used	True

Using Windows

Get Window Details

ovrt.requestWinDetails(uid, callback, data)

Makes a request to OVR Toolkit for a windows OVROverlayTransform object.

Argument	Type	Description	Optional
uid	Number	The uid of the window to get a transform for
callback	Function	A function definition to callback once the window is created
data	Any	This value will be passed as a second parameter to the callback after the window details	True

Get Window Type

ovrt.getWinType(uid, callback, data)

Makes a request to OVR Toolkit for a windows overlay type.

Argument	Type	Description	Optional
uid	Number	The uid of the window to get a type for
callback	Function	A function definition to callback with the window type
data	Any	This value will be passed as a second parameter to the callback after the window type	True

Close Window

ovrt.closeWin(uid)

Close a window.

Argument	Type	Description
uid	Number	The uid of the window to close

Refresh Web Window

ovrt.refreshWin(uid)

Refresh the browser in a web window.

Argument	Type	Description
uid	Number	The uid of the window to refresh

Get Window Boundaries

ovrt.getWinBounds(uid, callback, data)

Get a windows boundaries. Returns an OVROverlayBounds object, which is a wrapper for the Unity's Bounds type.

Argument	Type	Description	Optional
uid	Number	The uid of the window to get boundaries for
callback	Function	A function definition to callback once the window is created
data	Any	This value will be passed as a second parameter to the callback after the window boundaries	True

Set Window Position

ovrt.setWinPosition(uid, pos)

Set the windows position in 3D space.

Argument	Type	Description
uid	Number	The uid of the window to update position for
pos	Object	An object containing the properties x, y, and z

Set Window Rotation

ovrt.setWinPosition(uid, rot)

Set the windows rotation in 3D space.

Argument	Type	Description
uid	Number	The uid of the window to update position for
rot	Object	An object containing the properties x, y, and z

Set Window Setting

ovrt.setWinSetting(uid, setting, value)

Set the setting of a window to value. See ovrt.winSettings or the list of OVR Tookit window settings.

Argument	Type	Description
uid	Number	The uid of the window to update position for
setting	Number	The number for the setting you want to change
value	Any	The new value for the setting

Messaging

Broadcast To All Web Windows

ovrt.broadcastMessage(event, data)

Broadcasts a message of type event with the payload data to all other open web windows. Only web windows will receive this event.

Argument	Type	Description
event	String	A unique identifier for the message
data	String	The payload to send with the message event

Send To A Specific Web Window

ovrt.sendMessage(event, data, senderId, targetId)

Sends a message of type event with the payload data to the window targetId. Only the window with whose uid matches targetId will receive this messaage. Only web windows will receive this event.

Argument	Type	Description
event	String	A unique identifier for the message
data	String	The payload to send with the message event
senderId	Number	The uid of the sender window
targetId	Number	The uid of the target window

Update Properties

Get Monitor Count

ovrt.requestMonitorCount(callback, data)

Get a count of the total number of physical displays. This is called automatically when this library is first loaded and the value is saved in ovrt.totalMonitors.

Argument	Type	Description	Optional
callback	Function	A function definition to callback once the monitor count is retreived
data	Any	This value will be passed as a second parameter to the callback after the monitor count	True

Get Window Titles

ovrt.requestWinTitles(callback, data)

Get a count of the total number of physical displays. This function is used internally to update ovrt.winTitles when ovrt.updateTitles is true. When called directly it will update the value of ovrt.winTitles on completion.

Argument	Type	Description	Optional
callback	Function	A function definition to callback once the monitor count is retreived	True
data	Any	This value will be passed as a second parameter to the callback after the window titles	True

Enable/Disable Updates

Toggle HMD/Controller Position Updates

ovrt.setDeviceUpdateFlag(enable)

Updates the value of ovrt.updateDeviceInfo. When set to true the ovrt.deviceInfo property will be automatically updated with HMD and controller position data.

Argument	Type	Description
enable	Boolean	Whether to allow device updates

Toggle Knuckles Finger Curl Updates

ovrt.setFingerUpdateFlag(enable)

Updates the value of ovrt.updateFingers. When set to true the ovrt.fingerCurls property will be automatically updated with the curls of each finger as read by Knuckles controllers.

Argument	Type	Description
enable	Boolean	Whether to allow finger curl updates

Toggle Window List Updates

ovrt.setTitlesUpdateFlag(enable)

Updates the value of ovrt.updateTitles. When set to true the ovrt.winTitles property will be automatically updated with the list of open windows.

Argument	Type	Description
enable	Boolean	Whether to allow window list updates

Toggle Window Move/Resize Updates

ovrt.setWinUpdateFlag(enable)

Updates the value of ovrt.updateWindows. When set to true the ovrt.onWinTransformChanged event will be called when the window is moved or resized.

Argument	Type	Description
enable	Boolean	Whether to allow window move/resize updates

Properties

The following properties are available for reading the state of the OVR Toolkit settings or window update toggles.

Data Properties

Total Monitors

ovrt.totalMonitors // Number

Contains the total number of attached physical displays. For use with ovrt.createDesktopWin.

Window List

ovrt.winTitles // Object

When ovrt.updateWindows is true this property Contains a list of all currently open windows.

Knuckles Finger Curls

ovrt.fingerCurls // Object

When ovrt.updateFingers is true this property contains a list of the curl of each finger as read by Knuckles controllers.

HMD/Controller Positions

ovrt.deviceInfo // Object

When ovrt.updateDeviceInfo is true this property contains the positions of the HMD and controllers.

Update Flags

Update Knuckles Finger Curls

ovrt.updateFingers // Default: false

When set to true with ovrt.setFingerUpdateFlag the values of the fingers for Knuckles controllers will be stored in ovrt.fingerCurls.

Update Window List

ovrt.updateTitles // Default: false

When set to true with ovrt.setTitlesUpdateFlag the list of open windows will be stored in ovrt.winTitles.

Window Move/Resize Updates

ovrt.updateWindows // Default: false

When set to true with ovrt.setWinUpdateFlag the ovrt.onWinTransformChanged event will be called whenever a window is moved or resized.

HMD/Controller Position Updates

ovrt.updateDeviceInfo // Default: false

When set to true the ovrt.deviceInfo property will be automatically updated with HMD and controller position data.

Constants

This library abstracts the integer constants from the wiki into objects with memorable keys.

Window Attached Device

ovrt.winDevices = {
  world: 0,
  hmd: 1,
  leftHand: 2,
  rightHand: 3
}

Wiki page on devices

Window Types

ovrt.winTypes = {
  web: 0,
  desktop: 1,
  window: 2
}

Wiki page on window types

Window Settings

ovrt.winSettings = {
  size: 0,
  opacity: 1,
  curvature: 2,
  framerate: 3,
  ecoMode: 4,
  lookHiding: 5,
  attachedDevice: 6
}

Wiki page on settings values

New Transform

ovrt.newTransform = {
  posX: 0.0,
  posY: 0.0,
  posZ: 0.0,
  rotX: 0.0,
  rotY: 0.0,
  rotZ: 0.0,
  size: 0.25, // Meters
  opacity: 1.0,
  curvature: 0.0,
  framerate: 60,
  ecoMode: true,
  lookHiding: false,
  attachedDevice: 0,
  shouldSave: false
}

Wiki page on OVROverlayTransform

This object is used if no transform is provided to ovrt.requestWinSpawn.

Events

These events are available for you to override with your own function definitions.

Window Moved/Resized

ovrt.onWinTransformChanged(transformUpdate)

Only triggers if ovrt.updateWindows is true. Sends an OVRTransformUpdate object.

Window Opened

ovrt.onWinOpened(uid)

uid is the ID of the newly opened window.

Window Closed

ovrt.onWinClosed(uid)

uid is the ID of the closed window.

Window Mouse Enter/Leave

ovrt.onWinInteractionChanged(isInteracting)

isInteracting is a boolean flag for whether or not the mouse is interacting with this window.

Message Received

ovrt.onMessageReceived(message)

message is a string containing the data sent by ovrt.broadcast or ovrt.sendMessage.

Error Thrown

ovrt.onLogError(errorData)

This function is called if ovrt.setupLogging was used to overried the windows logging outputs. errorData is an object that contains the data about the error that occured

Console Log

ovrt.onLog(message)

This function is called if ovrt.setupLogging was used to overried the windows logging outputs. message is a string that contains the contents of any calls to console.log.

Notes

• When using Virtual Desktop with Chrome remote debugger: It seems that after a while of taking the headset off VD returns control of the audio device to the PC. It also appears to be suspending input from SteamVR, which makes the OVRT functions no longer bound to the window object on a reload in the Chrome debugger. The fix is to just put on the headset and reload the page. This seems to happen even if the "suspend input on idle" setting is disabled in SteamVR.