HMD

Description

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

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts

Properties

Name Type Summary
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 A scale factor applied to the ipd property value.

Default Value: 1.0

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 entity.
tabletScreenID Uuid The UUID of the tablet's screen entity.
homeButtonID Uuid The UUID of the tablet's "home" button entity.
homeButtonHighlightID Uuid The UUID of the tablet's "home" button highlight entity.
miniTabletID Uuid The UUID of the mini tablet's body model entity. null if not in HMD mode.
miniTabletScreenID Uuid The UUID of the mini tablet's screen entity. null if not in HMD mode.
miniTabletHand number The hand that the mini tablet is displayed on: 0 for left hand, 1 for right hand, -1 if not in HMD mode.
miniTabletEnabled bool true if the mini tablet is enabled to be displayed, otherwise false.

Default Value: true

playArea Rect The size and position of the HMD play area in sensor coordinates. Read-only.

Default Value: 0,0,0,0

sensorPositions Array.<Vec3> The positions of the VR system sensors in sensor coordinates. Read-only.

Default Value: []

Methods

Name Return Value Summary
activateHMDHandMouse None Causes the borders in HUD windows to be enlarged when the laser intersects them in HMD mode. By default, borders are not enlarged.
calculateRayUICollisionPoint Vec3 Calculates the intersection of a ray with the HUD overlay.
centerUI None Recenters the HMD HUD to the current HMD position and orientation.
closeTablet None Closes the tablet if it is open.
deactivateHMDHandMouse None 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.
getHUDLookAtPosition2D Vec2 Gets the position on the HUD overlay that your HMD is looking at, in HUD coordinates.
getHUDLookAtPosition3D Vec3 Gets the position on the HUD overlay that your HMD is looking at, in world coordinates.
isHandControllerAvailable boolean Checks whether there are HMD hand controllers available.
isHeadControllerAvailable boolean Checks whether there is an HMD head controller available.
isHMDAvailable boolean Checks whether there is an HMD available.
isKeyboardVisible boolean Checks whether the HMD-provided keyboard, if any, is visible.
isSubdeviceContainingNameAvailable boolean Checks whether there are specific HMD controllers available.
openTablet None 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).
overlayFromWorldPoint Vec2 Gets 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.
overlayToSpherical Vec2 Gets 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.
preferredAudioInput string Gets the name of the HMD audio input device.
preferredAudioOutput string Gets the name of the HMD audio output device.
requestHideHandControllers None Signals 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 None Signals that models of the HMD hand controllers being used should be displayed. The models are displayed at their actual, real-world locations.
shouldShowHandControllers boolean Checks whether any script wants models of the HMD hand controllers displayed. Requests are made and canceled using requestShowHandControllers and requestHideHandControllers.
sphericalToOverlay Vec2 Gets 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.
suppressKeyboard boolean Suppresses the activation of the HMD-provided keyboard, if any. Successful calls should be balanced with a call to unsuppressKeyboard within a reasonable amount of time.
unsuppressKeyboard None Unsuppresses the activation of the HMD-provided keyboard, if any.
worldPointFromOverlay Vec3 Gets 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.

Signals

Name Summary
displayModeChanged Triggered when Interface's display mode changes and when the user puts on or takes off their HMD.
IPDScaleChanged Triggered when the HMD.ipdScale property value changes.
miniTabletEnabledChanged Triggered when the ability to display the mini tablet has changed.
mountedChanged Triggered when the HMD.mounted property value changes.
shouldShowHandControllersChanged Triggered when a request to show or hide models of the HMD hand controllers is made using requestShowHandControllers or requestHideHandControllers.
showTabletChanged Triggered when the tablet is shown or hidden.

Method Details

(static) activateHMDHandMouse( )

Causes the borders in HUD windows to be enlarged when the laser intersects them in HMD mode. By default, borders are not enlarged.

(static) calculateRayUICollisionPoint( position, direction ) → {Vec3}
Returns: The point of intersection with the HUD overlay if it intersects, otherwise Vec3.ZERO.

Calculates 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.
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);
});
(static) centerUI( )

Recenters the HMD HUD to the current HMD position and orientation.

(static) closeTablet( )

Closes the tablet if it is open.

(static) 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.

(static) getHUDLookAtPosition2D( ) → {Vec2}
Returns: The position on the HUD overlay that your HMD is looking at, in pixels.

Gets the position on the HUD overlay that your HMD is looking at, in HUD coordinates.

(static) getHUDLookAtPosition3D( ) → {Vec3}
Returns: The position on the HUD overlay the your HMD is looking at, in world coordinates.

Gets the position on the HUD overlay that your HMD is looking at, in world coordinates.

(static) isHandControllerAvailable( nameopt ) → {boolean}
Returns: true if an HMD hand controller of the specified name is available, otherwise false.

Checks whether there are HMD hand controllers available.

Parameters

Name Type Attributes Default Value 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.
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"));
(static) isHeadControllerAvailable( nameopt ) → {boolean}
Returns: true if an HMD head controller of the specified name is available, otherwise false.

Checks whether there is an HMD head controller available.

Parameters

Name Type Attributes Default Value 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.
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"));
(static) isHMDAvailable( nameopt ) → {boolean}
Returns: true if an HMD of the specified name is available, otherwise false.

Checks whether there is an HMD available.

Parameters

Name Type Attributes Default Value 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.
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)"));
(static) isKeyboardVisible( ) → {boolean}
Returns: true if the current HMD provides a keyboard and it is visible, otherwise false.

Checks whether the HMD-provided keyboard, if any, is visible.

(static) isSubdeviceContainingNameAvailable( name ) → {boolean}
Returns: true if an HMD controller with a name containing the specified name is available, otherwise false.

Checks 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".
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"));
(static) 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 Value 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.
(static) overlayFromWorldPoint( position ) → {Vec2}
Returns: The point on the HUD overlay in HUD coordinates.

Gets 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.
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);
});
(static) overlayToSpherical( overlayPos ) → {Vec2}
Returns: The point on the HUD overlay in spherical coordinates.

Gets 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.
(static) preferredAudioInput( ) → {string}
Returns: The name of the HMD audio input device if in HMD mode, otherwise an empty string.

Gets the name of the HMD audio input device.

(static) preferredAudioOutput( ) → {string}
Returns: The name of the HMD audio output device if in HMD mode, otherwise an empty string.

Gets the name of the HMD audio output device.

(static) requestHideHandControllers( )

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

(static) requestShowHandControllers( )

Signals 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);
(static) shouldShowHandControllers( ) → {boolean}
Returns: true if any script is requesting that HMD hand controller models be displayed.

Checks whether any script wants models of the HMD hand controllers displayed. Requests are made and canceled using requestShowHandControllers and requestHideHandControllers.

(static) sphericalToOverlay( sphericalPos ) → {Vec2}
Returns: The point on the HUD overlay in HUD coordinates.

Gets 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.
(static) suppressKeyboard( ) → {boolean}
Returns: true if the current HMD provides a keyboard and it was successfully suppressed (e.g., it isn't being displayed), otherwise false.

Suppresses the activation of the HMD-provided keyboard, if any. Successful calls should be balanced with a call to unsuppressKeyboard within a reasonable amount of time.

(static) unsuppressKeyboard( )

Unsuppresses the activation of the HMD-provided keyboard, if any.

(static) worldPointFromOverlay( coordinates ) → {Vec3}
Returns: The point on the HUD overlay in world coordinates.

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

Signal Details

displayModeChanged( isHMDMode )
Returns: 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.
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( )
Returns: Signal

Triggered when the HMD.ipdScale property value changes.

miniTabletEnabledChanged( enabled )
Returns: Signal

Triggered when the ability to display the mini tablet has changed.

Parameters

Name Type Description
enabled boolean true if the mini tablet is enabled to be displayed, otherwise false.
mountedChanged( )
Returns: Signal

Triggered when the HMD.mounted property value changes.

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( )
Returns: Signal

Triggered when a request to show or hide models of the HMD hand controllers is made using requestShowHandControllers or requestHideHandControllers.

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);
showTabletChanged( showTablet )
Returns: Signal

Triggered when the tablet is shown or hidden.

Parameters

Name Type Description
showTablet boolean true if the tablet is showing, otherwise false.