VR Lua Functions
Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE |
You can use Lua bindings to interact programmatically with head-mounted display (HMD) devices that provide Virtual Reality (VR) experiences.
For general information on configuring your Lumberyard game project for VR, see Create virtual reality projects in Lumberyard.
Global Functions
The following functions provide programming interfaces for HMD devices.
Function | Description |
---|---|
HMDDeviceRequestBusSender HMDDeviceRequestBusSender(EntityId) |
Returns an HMDDeviceRequestBusSender object that is connected to the
specified entity. For more information, see HMDDeviceRequestBus. |
ControllerRequestBusSender ControllerRequestbusSender(EntityId) |
Returns a ControllerRequestBusSender object that is connected to the
specified entity. For more information, see ControllerRequestBus. |
HMDDeviceRequestBus
Contains functions that return information about an HMD and control its pose and tracking level.
Function | Description |
---|---|
Bool IsInitialized() |
Returns true if an HMD has
successfully initialized on the bus. Returns
false if no HMD is connected or
failed to initialize. |
Void RecenterPose() |
Causes the direction that the HMD is currently facing to be considered forward’. |
Void OutputHMDInfo() |
Outputs the information about the currently connected HMD (contained in the HMDDeviceInfo object) to the console and log file. |
Void SetTrackingLevel(int) |
Sets the tracking level for the HMD. 0 specifies head level tracking (the player is standing); 1 is floor level tracking (the player is seated or on the floor). |
HMDDeviceInfo GetDeviceInfo() |
Returns an HMDDeviceInfo object that
contains device information about a connected HMD. For
more information, see
struct HMDDeviceInfo. |
TrackingState GetTrackingState() |
Returns a TrackingState object that
contains the most recent tracking information about a
connected HMD. For more information, see
struct TrackingState. |
ControllerRequestBus
Returns status information about an HMD controller.
Function | Description |
---|---|
Bool IsConnected(int controllerIndex) |
Returns true if the given controller is connected, false if a controller is not connected. Pass 0 for the left controller, pass 1 for the right controller. |
TrackingState GetTrackingState(int controllerIndex) |
Returns a TrackingState object that
contains tracking info about a connected controller. Pass
0 for the left controller, pass 1 for the right
controller. For more information, see
struct TrackingState. |
struct HMDDeviceInfo
Contains information about a device that displays on the screen when the device is detected.
Field | Description |
---|---|
String productName |
Name of the connected HMD. The default is
nullptr . |
String manufacturer |
Name of the company that manufactured the connected HMD.
The default is nullptr . |
Int renderWidth |
The render width for the HMD in pixels. This is normally
half the full resolution of the device (rendering is per
eye). The default is 0 . |
Int renderHeight |
The render height in pixels for a single eye of the HMD.
The default is 0 . |
Float fovH |
The horizontal field of view for both eyes in radians. The
default is 0.0f . |
Float fovV |
The vertical field of view in radians. The default is
0.0f . |
struct TrackingState
Stores position and connection state information about the HMD.
When an HMD is in use, certain parts of the device can go offline
or online. For example, a controller can be disconnected, or the
HMD can temporarily lose rotational tracking. You can use the
TrackingState
to determine what part of the
pose is currently valid.
Field | Description |
---|---|
PoseState pose |
The position and orientation in object space of the HMD. For more information, see struct PoseState. |
DynamicsState dynamics |
Contains the current state of the physics dynamics for the current device such as linear velocity, angular velocity, and acceleration. For more information, see struct DynamicsState. |
Int statusFlags |
Bit field that describes the current tracking state. For bit flags, see the enum HMDStatus. |
struct PoseState
A specific pose of the HMD device. Each HMD device has its own way of representing its current pose in three dimensional space. This structure acts as a common data set between a connected device and the rest of the system. All data is in a local coordinate space.
Field | Description |
---|---|
Quaternion orientation |
A quaternion representing the current orientation in object space of the HMD. |
Vector3 position |
A three dimensional vector representing the current position of the HMD in object space as an offset from the centered pose. |
struct DynamicsState
Dynamics (accelerations and velocities) of the current HMD. Many HMDs have the ability to track the current movements of VR devices for prediction. Not all devices support velocities and accelerations. All data is in a local coordinate space.
Field | Description |
---|---|
Vector3 angularVelocity |
A three dimensional vector representing angular velocity in object space. |
Vector3 angularAcceleration |
A three dimensional vector representing angular acceleration in object space. |
Vector3 linearVelocity |
A three dimensional vector representing linear velocity in object space. |
Vector3 linearAcceleration |
A three dimensional vector representing linear acceleration in object space. |
enum HMDStatus
The following code shows the status flags for HMDStatus.
enum HMDStatus { HMDStatus_OrientationTracked = BIT(1), HMDStatus_PositionTracked = BIT(2), HMDStatus_CameraPoseTracked = BIT(3), HMDStatus_PositionConnected = BIT(4), HMDStatus_HmdConnected = BIT(5), HMDStatus_IsUsable = HMDStatus_HmdConnected | HMDStatus_OrientationTracked, HMDStatus_ControllerValid = HMDStatus_OrientationTracked | HMDStatus_PositionConnected, };