engine.oculus Functions

This set of functions is available when the AppOculus plugin is loaded.

Notice

AppOculus plugin cannot be used in a Qt-based application

If the plugin is loaded together with the engine, the HAS_APP_OCULUS definition is set. This definition can be used, for example, to avoid errors if the plugin is not loaded: the code in which the plugin functions are executed can be wrapped around as follows:

Source code (UnigineScript)

#ifdef HAS_APP_OCULUS
	// engine.oculus functions
#endif

Notice

For more detailed information on application development with the Oculus Rift support, check also the following:

openvr File Reference
The Oculus Best Practices document and the Oculus Developer Guide document that can be downloaded from the official web site.

Methods:

Name	Description View: Sort by:
getAvailableHmdCaps	Returns HMD capability bits that the HMD currently supports.
getAvailableTrackingCaps	Returns tracking capability bits that the system currently supports.
getControllerAxis	Returns the coordinates of the specified controller axis along the X and Y axes.
getControllerButtonPressed	Returns the value indicating if the specified button is pressed.
getControllerButtonTouched	Returns the value indicating if the specified button is touched.
setControllerVibration	Sets the vibration of the given duration and amplitude.
getDefaultHmdCaps	Returns HMD capability bits that are default for the current HMD.
getDefaultTrackingCaps	Returns tracking capability bits that are default for the current system.
getDeviceAngularVelocity	Returns a device angular velocity, in radians per second.
isDeviceConnected	Returns a value indicating if the device connected to the slot.
getDevicePose	Returns a single pose for a tracked device.
getDeviceVelocity	Returns a device velocity in tracker space, in meters per second.
setEnabled	Toggles the VR mode.
isEnabled	Returns the value indicating if the VR mode is enabled or not.
getEyeFov	Returns the current field of view of the given eye.
getEyePosition	Returns the current position of the given eye.
getEyeRotation	Returns the current orientation of the given eye.
getHeadAngularAcceleration	Returns the current angular acceleration of the head.
getHeadAngularVelocity	Returns the current angular velocity of the head.
getHeadLinearAcceleration	Returns the current linear acceleration of the head.
getHeadLinearVelocity	Returns the current linear velocity of the head.
getHeadPosition	Returns the current position of the head.
setHeadPositionLock	Locks the head position.
isHeadPositionLocked	Returns the value indicating if the head position is locked.
getHeadRotation	Returns the current orientation of the head.
setHeadRotationLock	Locks the head rotation.
isHeadRotationLocked	Returns the value indicating if the head rotation is locked.
getHmdDefaultFov	Returns the recommended optical field of view for the specified eye.
getHmdFirmwareMajor	Returns the major version of the HMD firmware.
getHmdFirmwareMinor	Returns the minor version of the HMD firmware.
getHmdHeight	Returns the vertical resolution of the full HMD screen (both eyes) in pixels.
getHmdManufacturer	Returns the name of the HMD manufacturer (UTF-8 encoded identification string).
getHmdMaxFov	Returns the maximum optical field of view that can be practically rendered for the specified eye.
getHmdProductID	Returns the HID (USB) product identifier of the device.
getHmdProductName	Returns the name of the device (UTF-8 encoded product identification string).
getHmdSerialNumber	Returns the serial number of the HMD.
getHmdTrackerHFov	Returns the horizontal FOV (if present) of the tracking sensor frustum in degrees.
getHmdTrackerVFov	Returns the vertical FOV (if present) of the tracking sensor frustum in degrees.
getHmdTrackerZFar	Returns the distance from the tracking sensor to the tracking frustum far Z.
getHmdTrackerZNear	Returns the distance from the tracking sensor to the tracking frustum near Z.
getHmdType	Returns the type of the HMD: OCULUS_HMD_DK1, OCULUS_HMD_DKHD, OCULUS_HMD_DK2 or OCULUS_HMD_CB.
getHmdVendorID	Returns the HID (USB) vendor identifier of the device.
getHmdWidth	Returns the horizontal resolution of the full HMD screen (both eyes) in pixels.
getLeveledTrackerPosition	Returns position of the leveled sensor (aligned with gravity) relative to the tracking origin.
getLeveledTrackerRotation	Returns orientation (only sensor yaw, not roll and pitch) of the leveled sensor (aligned with gravity) relative to the tracking origin.
isPoseValid	Returns a value indicating if the device pose is valid.
setPositionScale	Sets a new scale for the world.
getPositionScale	Returns the current world scale.
getTrackerPosition	Returns the position of the sensor relative to the tracking origin.
getTrackerRotation	Returns orientation (sensor roll and pitch) of the sensor relative to the tracking origin.
getTrackingStatus	Returns the current status of the sensor tracking (OCULUS_STATUS_* variables).
getVersion	Returns the libOVRRT version.
getViewportMode	Returns a value indicating the current viewport mode, that determines the type of image to be displayed in the viewport.
setViewportMode	Sets the viewport mode, that determinss the type of image to be displayed in the viewport.
isVisible	Returns a value indicating if the process has VR focus and thus is visible in HMD.
resetTracking	Re-centers the sensor position and orientation: the (x,y,z) positional components and the yaw component of orientation.

Variables:

Name	Description
OCULUS_AXIS_HAND_TRIGGER	Left and right hand trigger values, in the range 0.0 to 1.0f. Hand trigger is often used to grab items. A value of 1.0 means that the trigger is fully depressed.
OCULUS_AXIS_HAND_TRIGGER_NO_DEADZONE	Left and right hand trigger values, in the range 0.0 to 1.0f, without a deadzone. Hand trigger is often used to grab items. A value of 1.0 means that the trigger is fully depressed.
OCULUS_AXIS_INDEX_TRIGGER	Left and right finger trigger values, in the range 0.0 to 1.0f. A value of 1.0 means that the trigger is fully depressed.
OCULUS_AXIS_INDEX_TRIGGER_NO_DEADZONE	Left and right finger trigger values, in the range 0.0 to 1.0f, without a deadzone. A value of 1.0 means that the trigger is fully depressed.
OCULUS_AXIS_THUMBSTICK	Horizontal and vertical thumbstick axis values, in the range -1.0f to 1.0f. The API automatically applies the deadzone, so developers don’t need to handle it explicitly.
OCULUS_AXIS_THUMBSTICK_NO_DEADZONE	Horizontal and vertical thumbstick axis values, in the range -1.0f to 1.0f, without a deadzone.
OCULUS_BUTTON_A	A button on the right Touch controller.
OCULUS_BUTTON_B	B button on the right Touch controller.
OCULUS_BUTTON_BACK	The Back button on the remote controller.
OCULUS_BUTTON_DOWN	The Down button on the remote controller.
OCULUS_BUTTON_ENTER	Enter button on the left Touch controller. This is equivalent to the Start button on the Xbox controller.
OCULUS_BUTTON_HOME	The Home button on the remote controller.
OCULUS_BUTTON_LEFT	The Left button on the remote controller.
OCULUS_BUTTON_LSHOULDER	Shoulder button on the left Touch controller.
OCULUS_BUTTON_LTHUMB	Thumb stick button on the left Touch controller.
OCULUS_BUTTON_RIGHT	The Right button on the remote controller.
OCULUS_BUTTON_RSHOULDER	Shoulder button on the right Touch controller.
OCULUS_BUTTON_RTHUMB	Thumb stick button on the right Touch controller.
OCULUS_BUTTON_UP	The Up button on the remote controller.
OCULUS_BUTTON_VOLDOWN	The Voldown button on the remote controller.
OCULUS_BUTTON_VOLUP	The Volup button on the remote controller.
OCULUS_BUTTON_X	X button on the left Touch controller.
OCULUS_BUTTON_Y	Y button on the left Touch controller.
OCULUS_DEVICE_CONTROLLER_LEFT	Left controller.
OCULUS_DEVICE_CONTROLLER_RIGHT	Right controller.
OCULUS_DEVICE_HMD	Oculus head-mounted display.
OCULUS_HMD_CB	The type of the HMD is Crescent Bay prototype (Oculus Rift CV1). It corresponds to the value of 8.
OCULUS_HMD_DK1	The type of the HMD is Oculus Rift DK1. It corresponds to the value of 3.
OCULUS_HMD_DK2	The type of the HMD is Oculus Rift DK2. It corresponds to the value of 6.
OCULUS_HMD_DKDH	The type of the HMD is Oculus Rift HD prototype. It corresponds to the value of 4.
OCULUS_STATUS_POSITION_TRACKED	A bit flag indicating that the sensor position is currently tracked (false if out of range).
OCULUS_STATUS_ROTATION_TRACKED	A bit flag indicating that the sensor orientation is currently tracked (connected and in use).
OCULUS_TOUCH_A	User is touching A button on the right controller.
OCULUS_TOUCH_B	User is touching B button on the right controller.
OCULUS_TOUCH_LINDEX_POINTING	User's left index finger is pointing forward past the trigger.
OCULUS_TOUCH_LINDEX_TRIGGER	User is touching the index finger trigger on the left controller.
OCULUS_TOUCH_LTHUMB	User has a finger on the thumb stick of the left controller.
OCULUS_TOUCH_LTHUMB_REST	User has a finger on the textured thumb rest of the left controller.
OCULUS_TOUCH_LTHUMB_UP	User's left thumb is up and away from buttons on the controller, a gesture that can be interpreted as left thumbs up.
OCULUS_TOUCH_RINDEX_POINTING	User's right index finger is pointing forward past the trigger.
OCULUS_TOUCH_RINDEX_TRIGGER	User is touching the index finger trigger on the right controller.
OCULUS_TOUCH_RTHUMB	User has a finger on the thumb stick of the right controller.
OCULUS_TOUCH_RTHUMB_REST	User has a finger on the textured thumb rest of the right controller.
OCULUS_TOUCH_RTHUMB_UP	User's right thumb is up and away from buttons on the controller, a gesture that can be interpreted as right thumbs up.
OCULUS_TOUCH_X	User is touching X button on the left controller.
OCULUS_TOUCH_Y	User is touching Y button on the left controller.
OCULUS_TRACKING_CAP_MAG_YAW_CORRECTION	A bit flag indicating that yaw drift correction via a magnetometer or other means is supported. See also OVR_CAPI.h file reference.
OCULUS_TRACKING_CAP_POSITION	A bit flag indicating that positional tracking is supported. See also OVR_CAPI.h file reference.
OCULUS_TRACKING_CAP_ROTATION	A bit flag indicating that orientation tracking is supported. See also OVR_CAPI.h file reference.

Oclulus Class

Members

int engine.oculus.getAvailableHmdCaps( )

Returns HMD capability bits that the HMD currently supports.

Return value

HMD capability bits.

int engine.oculus.getAvailableTrackingCaps( )

Returns tracking capability bits that the system currently supports.

Return value

Tracking capability bits.

vec3 engine.oculus.getControllerAxis( int device, int axis )

Returns the coordinates of the specified controller axis along the X and Y axes.

Arguments

int device - A device ID.
int axis - One of the following predefined constants:

Return value

X and Y in the range of [-1;1] ([0;1] for a trigger); Z is always zero.

int engine.oculus.getControllerButtonPressed( int device, int button )

Returns the value indicating if the specified button is pressed.

Arguments

int device - A device ID.
int button - A button, one of the following predefined constants:

Return value

1 if the button is pressed; otherwise - 0.

int engine.oculus.getControllerButtonTouched( int device, int button )

Returns the value indicating if the specified button is touched.

Arguments

int device - A device ID.
int button - A button, one of the following predefined constants:

Return value

1 if the button is pressed; otherwise - 0.

void engine.oculus.setControllerVibration( int device, unsigned short duration, float amplitude )

Sets the vibration of the given duration and amplitude.

Arguments

int device - ID if the device.
unsigned short duration - Duration of the vibration.
float amplitude - Amplitude of the vibration.

int engine.oculus.getDefaultHmdCaps( )

Returns HMD capability bits that are default for the current HMD.

Return value

Default HMD capability bits.

int engine.oculus.getDefaultTrackingCaps( )

Returns tracking capability bits that are default for the current system.

Return value

Default tracking capability bits.

vec3 engine.oculus.getDeviceAngularVelocity( int device )

Returns a device angular velocity, in radians per second.

Arguments

int device - A device ID.

Return value

Angular velocity.

bool engine.oculus.isDeviceConnected( int device )

Returns a value indicating if the device connected to the slot.

Arguments

int device - A device ID.

Return value

true - connected; false - not connected.

mat4 engine.oculus.getDevicePose( int device )

Returns a single pose for a tracked device.

Arguments

int device - A device ID.

Return value

Identity matrix.

vec3 engine.oculus.getDeviceVelocity( int device )

Returns a device velocity in tracker space, in meters per second.

Arguments

int device - A device ID.

Return value

Velocity.

void engine.oculus.setEnabled( int enabled )

Toggles the VR mode.

Arguments

int enabled - 1 to enable the VR mode; 0 to disable it.

int engine.oculus.isEnabled( )

Returns the value indicating if the VR mode is enabled or not.

Return value

1 if the VR mode is enabled; 0 if it is disabled.

vec4 engine.oculus.getEyeFov( int num )

Returns the current field of view of the given eye.

Arguments

int num - Eye: 0 for the left eye, 1 for the right eye.

Return value

Eye field of view.

vec3 engine.oculus.getEyePosition( int num )

Returns the current position of the given eye. The returned value was already multiplied by the current world scale.

Arguments

int num - Eye: 0 for the left eye, 1 for the right eye.

Return value

The eye position.

quat engine.oculus.getEyeRotation( int num )

Returns the current orientation of the given eye.

Arguments

int num - Eye: 0 for the left eye, 1 for the right eye.

Return value

The eye orientation.

vec3 engine.oculus.getHeadAngularAcceleration( )

Returns the current angular acceleration of the head.

Return value

Angular acceleration of the head in radians per second squared.

vec3 engine.oculus.getHeadAngularVelocity( )

Returns the current angular velocity of the head.

Return value

Angular velocity of the head in radians per second.

vec3 engine.oculus.getHeadLinearAcceleration( )

Returns the current linear acceleration of the head.

Return value

Linear acceleration of the head in meters per second squared.

vec3 engine.oculus.getHeadLinearVelocity( )

Returns the current linear velocity of the head.

Return value

Linear velocity of the head in meters per second.

vec3 engine.oculus.getHeadPosition( )

Returns the current position of the head. The returned value was already multiplied by the current world scale.

Return value

Position of the head.

void engine.oculus.setHeadPositionLock( int lock )

Locks the head position.

Arguments

int lock - 1 to lock the head position.

int engine.oculus.isHeadPositionLocked( )

Returns the value indicating if the head position is locked.

Return value

1 if the head position is locked; otherwise - 0.

quat engine.oculus.getHeadRotation( )

Returns the current orientation of the head.

Return value

Orientation of the head.

void engine.oculus.setHeadRotationLock( int lock )

Locks the head rotation.

Arguments

int lock - 1 to lock the head rotation.

int engine.oculus.isHeadRotationLocked( )

Returns the value indicating if the head rotation is locked.

Return value

1 if the head rotation is locked; otherwise - 0.

vec4 engine.oculus.getHmdDefaultFov( int num )

Returns the recommended optical field of view for the specified eye.

Arguments

int num - Eye: 0 for the left eye, 1 for the right eye.

Return value

Recommended field of view.

int engine.oculus.getHmdFirmwareMajor( )

Returns the major version of the HMD firmware.

Return value

The major version of the HMD firmware.

int engine.oculus.getHmdFirmwareMinor( )

Returns the minor version of the HMD firmware.

Return value

The minor version of the HMD firmware.

int engine.oculus.getHmdHeight( )

Returns the vertical resolution of the full HMD screen (both eyes) in pixels.

Return value

Vertical resolution in pixels.

string engine.oculus.getHmdManufacturer( )

Returns the name of the HMD manufacturer (UTF-8 encoded identification string).

Return value

The manufacturer name.

vec4 engine.oculus.getHmdMaxFov( int num )

Returns the maximum optical field of view that can be practically rendered for the specified eye.

Arguments

int num - Eye: 0 for the left eye, 1 for the right eye.

Return value

Maximum field of view.

int engine.oculus.getHmdProductID( )

Returns the HID (USB) product identifier of the device.

Return value

HID product identifier.

string engine.oculus.getHmdProductName( )

Returns the name of the device (UTF-8 encoded product identification string). For example: "Oculus Rift DK1".

Return value

The device name.

string engine.oculus.getHmdSerialNumber( )

Returns the serial number of the HMD.

Return value

HMD serial number.

float engine.oculus.getHmdTrackerHFov( )

Returns the horizontal FOV (if present) of the tracking sensor frustum in degrees.

Return value

Horizontal FOV of the tracking sensor frustum in degrees.

float engine.oculus.getHmdTrackerVFov( )

Returns the vertical FOV (if present) of the tracking sensor frustum in degrees.

Return value

Vertical FOV of the tracking sensor frustum in degrees.

float engine.oculus.getHmdTrackerZFar( )

Returns the distance from the tracking sensor to the tracking frustum far Z. The returned value was already multiplied by the current world scale.

Return value

Distance from the tracking sensor to the tracking frustum far Z in meters.

float engine.oculus.getHmdTrackerZNear( )

Returns the distance from the tracking sensor to the tracking frustum near Z. The returned value was already multiplied by the current world scale.

Return value

Distance from the tracking sensor to the tracking frustum near Z in meters.

int engine.oculus.getHmdType( )

Returns the type of the HMD: OCULUS_HMD_DK1, OCULUS_HMD_DKHD, OCULUS_HMD_DK2 or OCULUS_HMD_CB.

Return value

The HMD type.

int engine.oculus.getHmdVendorID( )

Returns the HID (USB) vendor identifier of the device.

Return value

Vendor ID.

int engine.oculus.getHmdWidth( )

Returns the horizontal resolution of the full HMD screen (both eyes) in pixels.

Return value

Horizontal resolution in pixels.

vec3 engine.oculus.getLeveledTrackerPosition( )

Returns position of the leveled sensor (aligned with gravity) relative to the tracking origin.

Return value

Position of the leveled sensor relative to the tracking origin.

quat engine.oculus.getLeveledTrackerRotation( )

Returns orientation (only sensor yaw, not roll and pitch) of the leveled sensor (aligned with gravity) relative to the tracking origin.

Return value

Orientation (yaw) of the sensor relative to the tracking origin.

bool engine.oculus.isPoseValid( int device )

Returns a value indicating if the device pose is valid.

Arguments

int device - A device ID.

Return value

true - valid; false - invalid.

void engine.oculus.setPositionScale( float scale )

Sets a new scale for the world. When increasing the scale, the objects get smaller when they are farther away.

Arguments

float scale - World scale.

float engine.oculus.getPositionScale( )

Returns the current world scale. When increasing the scale, the objects get smaller when they are farther away.

Return value

World scale.

vec3 engine.oculus.getTrackerPosition( )

Returns the position of the sensor relative to the tracking origin. The returned value was already multiplied by the current world scale.

Return value

Position of the sensor relative to the tracking origin.

quat engine.oculus.getTrackerRotation( )

Returns orientation (sensor roll and pitch) of the sensor relative to the tracking origin.

Return value

Orientation (roll and pitch) of the sensor relative to the tracking origin.

int engine.oculus.getTrackingStatus( )

Returns the current status of the sensor tracking (OCULUS_STATUS_* variables).

Return value

Status of the sensor tracking (OCULUS_STATUS_* variables).

string engine.oculus.getVersion( )

Returns the libOVRRT version.

Return value

The libOVR version (a UTF-8 encoded null-terminated version string).

int engine.oculus.getViewportMode( )

Returns a value indicating the current viewport mode, that determines the type of image to be displayed in the viewport.

Return value

Current viewport mode. One of the following values:

0 - no image (black screen)
1 - mono image
2 - stereo image (left and right eye)
3 - stereoscopic spherical image

void engine.oculus.setViewportMode( int mode )

Sets the viewport mode, that determinss the type of image to be displayed in the viewport.

Arguments

int mode - Viewport mode. One of the following values:
- 0 - no image (black screen)
- 1 - mono image
- 2 - stereo image (left and right eye)
- 3 - stereoscopic spherical image

int engine.oculus.isVisible( )

Returns a value indicating if the process has VR focus and thus is visible in HMD.

Return value

1 if the process is visible in the HMD; otherwise, 0.

void engine.oculus.resetTracking( )

Re-centers the sensor position and orientation: the (x,y,z) positional components and the yaw component of orientation. The roll and pitch components are always determined by gravity and cannot be redefined. See also ovr_RecenterTrackingOrigin method in the OVR_CAPI.h file reference.

Last update: 2018-12-27

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)