HMD

Description

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

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

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 boolean

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: []

visionSqueezeRatioX number

The amount of vision squeeze for the x-axis when moving, range 0.01.0.

Default Value: 0.0

visionSqueezeRatioY number

The amount of vision squeeze for the y-axis when moving, range 0.01.0.

Default Value: 0.0

visionSqueezeTurningXFactor number

The additional amount of vision squeeze for the x-axis when turning, range 0.01.0.

Default Value: 0.51

visionSqueezeTurningYFactor number

Currently unused.

Default Value: 0.36

visionSqueezeUnSqueezeDelay number

The delay in undoing the vision squeeze effect after motion stops, in seconds.

Default Value: 0.2

visionSqueezeUnSqueezeSpeed number

How quickly the vision squeeze effect fades, once visionSqueezeUnSqueezeDelay has passed.

Default Value: 3.0

visionSqueezeTransition number

How tightly vision is squeezed, range 0.010.7.

Default Value: 0.25

visionSqueezePerEye number

1 if each eye gets a tube to see through, 0 if the face gets a tube.

Default Value: 1

visionSqueezeGroundPlaneY number

Adjusts how far below the camera the vision squeeze grid is displayed at.

Default Value: 0.0

visionSqueezeSpotlightSize number

The diameter of the circle of vision squeeze grid that is illuminated around the camera.

Default Value: 6.0

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
awayStateWhenFocusLostInVRChanged

Triggered when the altering the mode for going into an away state when the interface focus is lost in VR.

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

awayStateWhenFocusLostInVRChanged( enabled )
Returns: Signal

Triggered when the altering the mode for going into an away state when the interface focus is lost in VR.

Parameters

Name Type Description
enabled boolean

true if the setting to go into an away state in VR when the interface focus is lost is enabled, otherwise false.

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.