unreal.HeadMountedDisplayFunctionLibrary

class unreal.HeadMountedDisplayFunctionLibrary(outer=None, name='None')

Bases: unreal.BlueprintFunctionLibrary

Head Mounted Display Function Library

C++ Source:

  • Module: HeadMountedDisplay

  • File: HeadMountedDisplayFunctionLibrary.h

classmethod calibrate_external_tracking_to_hmd(external_tracking_transform)None

Called to calibrate the offset transform between an external tracking source and the internal tracking source (e.g. mocap tracker to and HMD tracker). This should be called once per session, or when the physical relationship between the external tracker and internal tracker changes (e.g. it was bumped or reattached). After calibration, calling UpdateExternalTrackingPosition will try to correct the internal tracker to the calibrated offset to prevent drift between the two systems

Parameters

external_tracking_transform (Transform) – The transform in world-coordinates, of the reference marker of the external tracking system

classmethod clear_xr_timed_input_action_delegate(action_path)None

/ Clear a delegate to get an OpenXR action event with action time.

Parameters

action_path (Name) –

classmethod configure_gestures(gesture_config)bool

Specify which gestures to capture.

Parameters

gesture_config (XRGestureConfig) –

Returns

Return type

bool

classmethod connect_remote_xr_device(ip_address, bit_rate)XRDeviceConnectionResult

Connect to a remote device

Parameters
  • ip_address (str) –

  • bit_rate (int32) –

Returns

Return type

XRDeviceConnectionResult

classmethod disconnect_remote_xr_device()None

Disconnect remote AR Device

classmethod enable_hmd(enable)bool

Switches to/from using HMD and stereo rendering.

Parameters

enable (bool) – (in) ‘true’ to enable HMD / stereo; ‘false’ otherwise

Returns

(Boolean) True, if the request was successful.

Return type

bool

classmethod enable_low_persistence_mode(enable)None

Switches between low and full persistence modes. deprecated: This functionality is no longer available. HMD platforms that support low persistence will always enable it.

Parameters

enable (bool) – (in) ‘true’ to enable low persistence mode; ‘false’ otherwise

classmethod enumerate_tracked_devices(system_id='None', device_type=XRTrackedDeviceType.ANY)

Cross XR-System query that will list all XR devices currently being tracked.

Parameters
  • system_id (Name) – (Optional) Specifies an explicit system to poll devices from (use if you want only devices belonging to one explicit XR ecosystem, e.g. ‘OculusHMD’, or ‘SteamVR’)

  • device_type (XRTrackedDeviceType) – Specifies the type of device to query for - defaults to ‘Any’ (meaning ‘All’).

Returns

A list of device identifiers matching the query. Use these to query and operate on the device (e.g. through GetDevicePose, AddDeviceVisualizationComponent, etc.)

Return type

Array(XRDeviceId)

classmethod get_controller_transform_for_time(world_context, controller_index, motion_source, time)(time_was_used=bool, orientation=Rotator, position=Vector, provided_linear_velocity=bool, linear_velocity=Vector, provided_angular_velocity=bool, angular_velocity_rad_per_sec=Vector) or None

Get the transform and potentially velocity data at a specified time near the current frame in unreal world space. This is intended for use with sub-frame input action timing data from SetXRTimedInputActionDelegate, or future support for timestamps in the core input system. The valid time window is platform dependent, but the intention per OpenXR is to fetch transforms for times from, at most, the previous few frames in the past or future. The OpenXR spec suggests that 50ms in the past should return an accurate result. There is no guarantee for the future, but the underlying system is likely to have been designed to predict out to about 50ms as well. On some platforms this will always just return a cached position and rotation, ignoring time. bTimeWasUsed will be false in that case.

Parameters
  • world_context (Object) –

  • controller_index (int32) –

  • motion_source (Name) –

  • time (Timespan) –

Returns

time_was_used (bool):

orientation (Rotator):

position (Vector):

provided_linear_velocity (bool):

linear_velocity (Vector):

provided_angular_velocity (bool):

angular_velocity_rad_per_sec (Vector):

Return type

tuple or None

classmethod get_device_pose(xr_device_id) -> (is_tracked=bool, orientation=Rotator, has_positional_tracking=bool, position=Vector)

Cross XR-System query that returns a specific device’s tracked position and orientation (in tracking space).

Parameters

xr_device_id (XRDeviceId) – Specifies the device you’re querying for.

Returns

is_tracked (bool): [out] Details if the specified device is tracked (i.e. should the rest of the outputs be used)

orientation (Rotator): [out] Represents the device’s current rotation - NOTE: this value is not late updated and will be behind the render thread

has_positional_tracking (bool): [out] Details if the specified device has positional tracking (i.e. if the position output should be used)

position (Vector): [out] Represents the device’s current position - NOTE: this value is not late updated and will be behind the render thread

Return type

tuple

classmethod get_device_world_pose(world_context, xr_device_id) -> (is_tracked=bool, orientation=Rotator, has_positional_tracking=bool, position=Vector)

Cross XR-System query that returns a specific device’s position and orientation in world space.

Parameters
  • world_context (Object) –

  • xr_device_id (XRDeviceId) – Specifies the device you’re querying for.

Returns

is_tracked (bool): [out] Details if the specified device is tracked (i.e. should the rest of the outputs be used)

orientation (Rotator): [out] Represents the device’s current rotation - NOTE: this value is not late updated and will be behind the render thread

has_positional_tracking (bool): [out] Details if the specified device has positional tracking (i.e. if the position output should be used)

position (Vector): [out] Represents the device’s current position - NOTE: this value is not late updated and will be behind the render thread

Return type

tuple

classmethod get_hmd_data(world_context)XRHMDData

Cross XR-System query that returns critical information about the HMD display (position, orientation, device name)

Parameters

world_context (Object) –

Returns

hmd_data (XRHMDData):

Return type

XRHMDData

classmethod get_hmd_device_name()Name

Returns the name of the device, so scripts can modify their behaviour appropriately

Returns

FName specific to the currently active HMD device type. “None” implies no device, “Unknown” implies a device with no description.

Return type

Name

classmethod get_hmd_worn_state()HMDWornState

Returns the worn state of the device.

Returns

Unknown, Worn, NotWorn. If the platform does not detect this it will always return Unknown.

Return type

HMDWornState

classmethod get_motion_controller_data(world_context, hand)XRMotionControllerData

Cross XR-System query that returns critical information about the motion controller (position, orientation, hand/finger position)

Parameters
Returns

motion_controller_data (XRMotionControllerData):

Return type

XRMotionControllerData

classmethod get_num_of_tracking_sensors()int32

If the HMD has multiple positional tracking sensors, return a total number of them currently connected.

Returns

Return type

int32

classmethod get_orientation_and_position() -> (device_rotation=Rotator, device_position=Vector)

Grabs the current orientation and position for the HMD. If positional tracking is not available, DevicePosition will be a zero vector

Returns

device_rotation (Rotator): (out) The device’s current rotation

device_position (Vector): (out) The device’s current position, in its own tracking space

Return type

tuple

classmethod get_pixel_density()float

Returns the current VR pixel density. Pixel density sets the VR render target texture size as a factor of recommended texture size. The recommended texture size is the size that will result in no under sampling in most distorted area of the view when computing the final image to be displayed on the device by the runtime compositor.

Returns

(float) The pixel density to be used in VR mode.

Return type

float

classmethod get_play_area_bounds(origin=HMDTrackingOrigin.STAGE)Vector2D

Get the bounds of the area where the user can freely move while remaining tracked centered around the specified origin

Parameters

origin (HMDTrackingOrigin) –

Returns

Return type

Vector2D

classmethod get_positional_tracking_camera_parameters() -> (camera_origin=Vector, camera_rotation=Rotator, hfov=float, vfov=float, camera_distance=float, near_plane=float, far_plane=float)

If the HMD has a positional sensor, this will return the game-world location of it, as well as the parameters for the bounding region of tracking. This allows an in-game representation of the legal positional tracking range. All values will be zeroed if the sensor is not available or the HMD does not support it. deprecated: Use new GetTrackingSensorParameters / GetNumOfTrackingSensors

Returns

camera_origin (Vector):

camera_rotation (Rotator):

hfov (float): (out) Field-of-view, horizontal, in degrees, of the valid tracking zone of the sensor

vfov (float): (out) Field-of-view, vertical, in degrees, of the valid tracking zone of the sensor

camera_distance (float): (out) Nominal distance to sensor, in world-space

near_plane (float): (out) Near plane distance of the tracking volume, in world-space

far_plane (float): (out) Far plane distance of the tracking volume, in world-space

Return type

tuple

classmethod get_screen_percentage()float

Get Screen Percentage deprecated: Use GetPixelDensity instead

Returns

Return type

float

classmethod get_tracking_origin()HMDTrackingOrigin

Returns current tracking origin type (eye level or floor level).

Returns

Return type

HMDTrackingOrigin

classmethod get_tracking_sensor_parameters(index=0) -> (origin=Vector, rotation=Rotator, left_fov=float, right_fov=float, top_fov=float, bottom_fov=float, distance=float, near_plane=float, far_plane=float, is_active=bool)

If the HMD has a positional sensor, this will return the game-world location of it, as well as the parameters for the bounding region of tracking. This allows an in-game representation of the legal positional tracking range. All values will be zeroed if the sensor is not available or the HMD does not support it.

Parameters

index (int32) – (in) Index of the tracking sensor to query

Returns

origin (Vector): (out) Origin, in world-space, of the sensor

rotation (Rotator): (out) Rotation, in world-space, of the sensor

left_fov (float): (out) Field-of-view, left from center, in degrees, of the valid tracking zone of the sensor

right_fov (float): (out) Field-of-view, right from center, in degrees, of the valid tracking zone of the sensor

top_fov (float): (out) Field-of-view, top from center, in degrees, of the valid tracking zone of the sensor

bottom_fov (float): (out) Field-of-view, bottom from center, in degrees, of the valid tracking zone of the sensor

distance (float): (out) Nominal distance to sensor, in world-space

near_plane (float): (out) Near plane distance of the tracking volume, in world-space

far_plane (float): (out) Far plane distance of the tracking volume, in world-space

is_active (bool): (out) True, if the query for the specified sensor succeeded.

Return type

tuple

classmethod get_tracking_to_world_transform(world_context)Transform

Returns a transform that can be used to convert points from tracking space to world space. Does NOT include the set WorldToMeters scale, as that is added in by the backing XR system to their tracking space poses.

Parameters

world_context (Object) –

Returns

Return type

Transform

classmethod get_version_string()str

Returns name of tracking system specific version string.

Returns

Return type

str

classmethod get_vr_focus_state() -> (use_focus=bool, has_focus=bool)

Returns current state of VR focus.

Returns

use_focus (bool): (out) if set to true, then this App does use VR focus.

has_focus (bool): (out) if set to true, then this App currently has VR focus.

Return type

tuple

classmethod get_world_to_meters_scale(world_context)float

Returns the World to Meters scale, which corresponds to the scale of the world as perceived by the player

Parameters

world_context (Object) –

Returns

How many Unreal units correspond to one meter in the real world

Return type

float

classmethod get_xr_system_flags()int32

Returns the flags for the device, so scripts can modify their behaviour appropriately

Returns

IsAR, IsTablet, IsHeadMounted. Returns false

Return type

int32

classmethod has_valid_tracking_position()bool

If the HMD supports positional tracking, whether or not we are currently being tracked

Returns

Return type

bool

classmethod is_device_tracking(xr_device_id)bool

Cross XR-System query that returns whether the specified device is tracked or not.

Parameters

xr_device_id (XRDeviceId) – Specifies the device you’re querying for.

Returns

Return type

bool

classmethod is_head_mounted_display_connected()bool

Returns whether or not the HMD hardware is connected and ready to use. It may or may not actually be in use.

Returns

(Boolean) status whether the HMD hardware is connected and ready to use. It may or may not actually be in use.

Return type

bool

classmethod is_head_mounted_display_enabled()bool

Returns whether or not we are currently using the head mounted display.

Returns

(Boolean) status of HMD

Return type

bool

classmethod is_in_low_persistence_mode()bool

Returns true, if HMD is in low persistence mode. ‘false’ otherwise. deprecated: This functionality is no longer available. HMD platforms that support low persistence will always enable it.

Returns

Return type

bool

classmethod is_spectator_screen_mode_controllable()bool

Return true if spectator screen mode control is available.

Returns

Return type

bool

classmethod reset_orientation_and_position(yaw=0.0, options=OrientPositionSelector.ORIENTATION_AND_POSITION)None

Resets orientation by setting roll and pitch to 0, assuming that current yaw is forward direction and assuming current position as a ‘zero-point’ (for positional tracking).

Parameters
  • yaw (float) – (in) the desired yaw to be set after orientation reset.

  • options (OrientPositionSelector) – (in) specifies either position, orientation or both should be reset.

classmethod set_clipping_planes(near, far)None

Sets near and far clipping planes (NCP and FCP) for stereo rendering. Similar to ‘stereo ncp= fcp’ console command, but NCP and FCP set by this call won’t be saved in .ini file.

Parameters
  • near (float) – (in) Near clipping plane, in centimeters

  • far (float) – (in) Far clipping plane, in centimeters

classmethod set_social_screen_mode(mode)

deprecated: ‘set_social_screen_mode’ was renamed to ‘set_spectator_screen_mode’.

classmethod set_social_screen_texture(texture)

deprecated: ‘set_social_screen_texture’ was renamed to ‘set_spectator_screen_texture’.

classmethod set_spectator_screen_mode(mode)None

Sets the social screen mode.

Parameters

mode (SpectatorScreenMode) – (in) The social screen Mode.

classmethod set_spectator_screen_mode_texture_plus_eye_layout(eye_rect_min, eye_rect_max, texture_rect_min, texture_rect_max, draw_eye_first=True, clear_black=False, use_alpha=False)None

Setup the layout for ESpectatorScreenMode::TexturePlusEye.

Parameters
classmethod set_spectator_screen_texture(texture)None

Change the texture displayed on the social screen

Parameters

texture (Texture) –

classmethod set_tracking_origin(origin)None

Sets current tracking origin type (eye level or floor level).

Parameters

origin (HMDTrackingOrigin) –

classmethod set_world_to_meters_scale(world_context, new_scale=100.0)None

Sets the World to Meters scale, which changes the scale of the world as perceived by the player

Parameters
  • world_context (Object) –

  • new_scale (float) – Specifies how many Unreal units correspond to one meter in the real world

classmethod set_xr_disconnect_delegate(disconnected_delegate)None

Set XRDisconnect Delegate

Parameters

disconnected_delegate (XRDeviceOnDisconnectDelegate) –

classmethod set_xr_timed_input_action_delegate(action_name, delegate)None

Hook up a delegate to get an OpenXR action event with action time. For a boolean input the the ‘value’ parameter of the delegate will be 1.0 for a press and 0.0 for a release. For an analog input the value’s range is action and platform specific. Use in combination with GetControllerTransformForTime for potentially improved temporal transform precision and velocity data. “Left Grip” is an example of a valid ActionName. Note: this is likely to be replaced by native support for event times in the core input system at some time in the future.

Parameters
classmethod update_external_tracking_hmd_position(external_tracking_transform)None

Called after calibration to attempt to pull the internal tracker (e.g. HMD tracking) in line with the external tracker (e.g. mocap tracker). This will set the internal tracker’s base offset and rotation to match and realign the two systems. This can be called every tick, or whenever realignment is desired. Note that this may cause choppy movement if the two systems diverge relative to each other, or a big jump if called infrequently when there has been significant drift

Parameters

external_tracking_transform (Transform) – The transform in world-coordinates, of the reference marker of the external tracking system