HMD

Available in: Interface Scripts Client Entity Scripts

The HMD API provides access to the HMD used in VR display mode.
Methods

Signals

Properties:
Name Type Default Description
position Vec3 The position of the HMD if currently in VR display mode, otherwise Vec3.ZERO. Read-only.
orientation Quat The orientation of the HMD if currently in VR display mode, otherwise Quat.IDENTITY. Read-only.
active boolean true if the display mode is HMD, otherwise false. Read-only.
mounted boolean true if currently in VR display mode and the HMD is being worn, otherwise false. Read-only.
playerHeight number The real-world height of the user. Read-only. Currently always returns a value of 1.755.
eyeHeight number The real-world height of the user's eyes. Read-only. Currently always returns a value of 1.655.
ipd number The inter-pupillary distance (distance between eyes) of the user, used for rendering. Defaults to the human average of 0.064 unless set by the HMD. Read-only.
ipdScale number 1.0 A scale factor applied to the ipd property value.
showTablet boolean true if the tablet is being displayed, false otherwise. Read-only.
tabletContextualMode boolean true if the tablet has been opened in contextual mode, otherwise false. In contextual mode, the tablet has been opened at a specific world position and orientation rather than at a position and orientation relative to the user. Read-only.
tabletID Uuid The UUID of the tablet body model overlay.
tabletScreenID Uuid The UUID of the tablet's screen overlay.
homeButtonID Uuid The UUID of the tablet's "home" button overlay.
homeButtonHighlightID Uuid The UUID of the tablet's "home" button highlight overlay.

Methods

activateHMDHandMouse()
Causes the borders in HUD windows to be enlarged when the laser intersects them in HMD mode. By default, borders are not enlarged.
calculateRayUICollisionPoint(position, direction) → {Vec3}
Calculate the intersection of a ray with the HUD overlay.
Parameters:
Name Type Description
position Vec3 The origin of the ray.
direction Vec3 The direction of the ray.
Returns:
The point of intersection with the HUD overlay if it intersects, otherwise Vec3.ZERO.
Type: Vec3
Example

Draw a square on the HUD overlay in the direction you're looking.

var hudIntersection = HMD.calculateRayUICollisionPoint(MyAvatar.getHeadPosition(),
  Quat.getForward(MyAvatar.headOrientation));
var hudPoint = HMD.overlayFromWorldPoint(hudIntersection);

var DIMENSIONS = { x: 50, y: 50 };
var square = Overlays.addOverlay("rectangle", {
  x: hudPoint.x - DIMENSIONS.x / 2,
  y: hudPoint.y - DIMENSIONS.y / 2,
  width: DIMENSIONS.x,
  height: DIMENSIONS.y,
  color: { red: 255, green: 0, blue: 0 }
});

Script.scriptEnding.connect(function () {
  Overlays.deleteOverlay(square);
});
centerUI()
Recenter the HMD HUD to the current HMD position and orientation.
closeTablet()
Closes the tablet if it is open.
deactivateHMDHandMouse()
Causes the border in HUD windows to no longer be enlarged when the laser intersects them in HMD mode. By default, borders are not enlarged.
isHandControllerAvailable(nameopt) → {boolean}
Check whether there are HMD hand controllers available.
Parameters:
Name Type Attributes Default Description
name string <optional>
"" The name of the HMD hand controller to check for, e.g., "Oculus". If no name is specified then any HMD hand controller matches.
Returns:
true if an HMD hand controller of the specified name is available, otherwise false.
Type: boolean
Example

Report HMD hand controller availability.

print("Are any HMD hand controllers available: " + HMD.isHandControllerAvailable());
print("Are Oculus hand controllers available: " + HMD.isHandControllerAvailable("Oculus"));
print("Are Vive hand controllers available: " + HMD.isHandControllerAvailable("OpenVR"));
isHeadControllerAvailable(nameopt) → {boolean}
Check whether there is an HMD head controller available.
Parameters:
Name Type Attributes Default Description
name string <optional>
"" The name of the HMD head controller to check for, e.g., "Oculus". If no name is specified then any HMD head controller matches.
Returns:
true if an HMD head controller of the specified name is available, otherwise false.
Type: boolean
Example

Report HMD head controller availability.

print("Is any HMD head controller available: " + HMD.isHeadControllerAvailable());
print("Is an Oculus head controller available: " + HMD.isHeadControllerAvailable("Oculus"));
print("Is a Vive head controller available: " + HMD.isHeadControllerAvailable("OpenVR"));
isHMDAvailable(nameopt) → {boolean}
Check whether there is an HMD available.
Parameters:
Name Type Attributes Default Description
name string <optional>
"" The name of the HMD to check for, e.g., "Oculus Rift". The name is the same as may be displayed in Interface's "Display" menu. If no name is specified then any HMD matches.
Returns:
true if an HMD of the specified name is available, otherwise false.
Type: boolean
Example

Report on HMD availability.

print("Is any HMD available: " + HMD.isHMDAvailable());
print("Is an Oculus Rift HMD available: " + HMD.isHMDAvailable("Oculus Rift"));
print("Is a Vive HMD available: " + HMD.isHMDAvailable("OpenVR (Vive)"));
isKeyboardVisible() → {boolean}
Check whether the HMD-provided keyboard, if any, is visible.
Returns:
true if the current HMD provides a keyboard and it is visible, otherwise false.
Type: boolean
isSubdeviceContainingNameAvailable(name) → {boolean}
Check whether there are specific HMD controllers available.
Parameters:
Name Type Description
name string The name of the HMD controller to check for, e.g., "OculusTouch".
Returns:
true if an HMD controller with a name containing the specified name is available, otherwise false.
Type: boolean
Example

Report if particular Oculus controllers are available.

print("Is an Oculus Touch controller available: " + HMD.isSubdeviceContainingNameAvailable("Touch"));
print("Is an Oculus Remote controller available: " + HMD.isSubdeviceContainingNameAvailable("Remote"));
openTablet(contextualModeopt)
Opens the tablet if the tablet is used in the current display mode and it isn't already showing, and sets the tablet to contextual mode if requested. In contextual mode, the page displayed on the tablet is wholly controlled by script (i.e., the user cannot navigate to another).
Parameters:
Name Type Attributes Default Description
contextualMode boolean <optional>
false If true then the tablet is opened at a specific position and orientation already set by the script, otherwise it opens at a position and orientation relative to the user. For contextual mode, set the world or local position and orientation of the HMD.tabletID overlay.
overlayFromWorldPoint(position) → {Vec2}
Get the 2D HUD overlay coordinates of a 3D point on the HUD overlay. 2D HUD overlay coordinates are pixels with the origin at the top left of the overlay.
Parameters:
Name Type Description
position Vec3 The point on the HUD overlay in world coordinates.
Returns:
The point on the HUD overlay in HUD coordinates.
Type: Vec2
Example

Draw a square on the HUD overlay in the direction you're looking.

var hudIntersection = HMD.calculateRayUICollisionPoint(MyAvatar.getHeadPosition(),
  Quat.getForward(MyAvatar.headOrientation));
var hudPoint = HMD.overlayFromWorldPoint(hudIntersection);

var DIMENSIONS = { x: 50, y: 50 };
var square = Overlays.addOverlay("rectangle", {
  x: hudPoint.x - DIMENSIONS.x / 2,
  y: hudPoint.y - DIMENSIONS.y / 2,
  width: DIMENSIONS.x,
  height: DIMENSIONS.y,
  color: { red: 255, green: 0, blue: 0 }
});

Script.scriptEnding.connect(function () {
  Overlays.deleteOverlay(square);
});
overlayToSpherical(overlayPos) → {Vec2}
Get the spherical coordinates of a 2D point on the HUD overlay. 2D HUD overlay coordinates are pixels with the origin at the top left of the overlay. Spherical coordinates are polar coordinates in radians with { x: 0, y: 0 } being the center of the HUD overlay.
Parameters:
Name Type Description
overlayPos Vec2 The point on the HUD overlay in HUD coordinates.
Returns:
The point on the HUD overlay in spherical coordinates.
Type: Vec2
preferredAudioInput() → {string}
Get the name of the HMD audio input device.
Returns:
The name of the HMD audio input device if in HMD mode, otherwise an empty string.
Type: string
preferredAudioOutput() → {string}
Get the name of the HMD audio output device.
Returns:
The name of the HMD audio output device if in HMD mode, otherwise an empty string.
Type: string
requestHideHandControllers()
Signal that it is no longer necessary to display models of the HMD hand controllers being used. If no other scripts want the models displayed then they are no longer displayed.
requestShowHandControllers()
Signal that models of the HMD hand controllers being used should be displayed. The models are displayed at their actual, real-world locations.
Example

Show your hand controllers for 10 seconds.

HMD.requestShowHandControllers();
Script.setTimeout(function () {
  HMD.requestHideHandControllers();
}, 10000);
shouldShowHandControllers() → {boolean}
Check whether any script wants models of the HMD hand controllers displayed. Requests are made and canceled using requestShowHandControllers and requestHideHandControllers.
Returns:
true if any script is requesting that HMD hand controller models be displayed.
Type: boolean
sphericalToOverlay(sphericalPos) → {Vec2}
Get the 2D point on the HUD overlay represented by given spherical coordinates. 2D HUD overlay coordinates are pixels with the origin at the top left of the overlay. Spherical coordinates are polar coordinates in radians with { x: 0, y: 0 } being the center of the HUD overlay.
Parameters:
Name Type Description
sphericalPos Vec2 The point on the HUD overlay in spherical coordinates.
Returns:
The point on the HUD overlay in HUD coordinates.
Type: Vec2
suppressKeyboard() → {boolean}
Suppress the activation of the HMD-provided keyboard, if any. Successful calls should be balanced with a call to unspressKeyboard within a reasonable amount of time.
Returns:
true if the current HMD provides a keyboard and it was successfully suppressed (e.g., it isn't being displayed), otherwise false.
Type: boolean
unsuppressKeyboard()
Unsuppress the activation of the HMD-provided keyboard, if any.
worldPointFromOverlay(coordinates) → {Vec3}
Get the 3D world coordinates of a 2D point on the HUD overlay. 2D HUD overlay coordinates are pixels with the origin at the top left of the overlay.
Parameters:
Name Type Description
coordinates Vec2 The point on the HUD overlay in HUD coordinates.
Returns:
The point on the HUD overlay in world coordinates.
Type: Vec3

Signals

displayModeChanged(isHMDMode) → {Signal}
Triggered when Interface's display mode changes and when the user puts on or takes off their HMD.
Parameters:
Name Type Description
isHMDMode boolean true if the display mode is HMD, otherwise false. This is the same value as provided by HMD.active.
Returns:
Type: Signal
Example

Report when the display mode changes.

HMD.displayModeChanged.connect(function (isHMDMode) {
  print("Display mode changed");
  print("isHMD = " + isHMDMode);
  print("HMD.active = " + HMD.active);
  print("HMD.mounted = " + HMD.mounted);
});
IPDScaleChanged() → {Signal}
Triggered when the HMD.ipdScale property value changes.
Returns:
Type: Signal
mountedChanged() → {Signal}
Triggered when the HMD.mounted property value changes.
Returns:
Type: Signal
Example

Report when there's a change in the HMD being worn.

HMD.mountedChanged.connect(function () {
  print("Mounted changed. HMD is mounted: " + HMD.mounted);
});
   
shouldShowHandControllersChanged() → {Signal}
Triggered when a request to show or hide models of the HMD hand controllers is made using requestShowHandControllers or requestHideHandControllers.
Returns:
Type: Signal
Example

Report when showing of hand controllers changes.

function onShouldShowHandControllersChanged() {
  print("Should show hand controllers: " + HMD.shouldShowHandControllers());
}
HMD.shouldShowHandControllersChanged.connect(onShouldShowHandControllersChanged);

HMD.requestShowHandControllers();
Script.setTimeout(function () {
  HMD.requestHideHandControllers();
}, 10000);