Skip to content

Zetaphor/ovrt-helper

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

49 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

Table Of Contents

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.