engine.oculus Functions (C++)

List of functions:

List of Variables:

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

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:

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

int OCULUS_DISTORTION_CAP_CHROMATIC

Description

Bit flag indicating that the chromatic aberration correction is supported. See also OVR_CPI.h file reference.

int OCULUS_DISTORTION_CAP_COMPUTE_SHADER

Description

Bit flag indicating that that using compute shader (DX11+ only) is supported. See also OVR_CPI.h file reference.

int OCULUS_DISTORTION_CAP_FLIP_INPUT

Description

Bit flag indicating that flipping the vertical texture coordinate of input images is supported. See also OVR_CPI.h file reference.

int OCULUS_DISTORTION_CAP_HQ_DISTORTION

Description

Bit flag indicating that high-quality sampling of distortion buffer for anti-aliasing is supported. See also OVR_CPI.h file reference.

int OCULUS_DISTORTION_CAP_LINUX_DEV_FULLSCREEN

Description

Bit flag indicating that the window is in fullscreen on the device. The SDK will automatically rotate the distortion mesh if it is required. See also OVR_CPI.h file reference.

int OCULUS_DISTORTION_CAP_NO_RESTORE

Description

Bit flag indicating that saving and restoring the graphics state is not supported when rendering distortion. See also OVR_CPI.h file reference.

int OCULUS_DISTORTION_CAP_OVERDRIVE

Description

Bit flag indicating that overdriving brightness transitions to reduce artifacts on DK2+ displays is supported. See also OVR_CPI.h file reference.

int OCULUS_DISTORTION_CAP_PROFILE_NO_TIMEWARP_SPINWAITS

Description

Bit flag indicating that removing false positives when profiling with timewarp is supported. See also OVR_CPI.h file reference.

int OCULUS_DISTORTION_CAP_SRGB

Description

Bit flag indicating that input images are assumed in sRGB gamma-corrected color space. See also OVR_CPI.h file reference.

int OCULUS_DISTORTION_CAP_TIMEWARP

Description

Bit flag indicating that the timewarp is supported. See also OVR_CPI.h file reference.

int OCULUS_DISTORTION_CAP_VINGETTE

Description

Bit flag indicating that vignetting around the edges of the view is supported. See also OVR_CPI.h file reference.

int OCULUS_HMD_CAP_AVAILABLE

Description

Bit flag indicating that the HMD and its sensor are not owned by another application. This variable cannot be modified (read-only). See also OVR_CPI.h file reference.

int OCULUS_HMD_CAP_CAPTURED

Description

Bit flag indicating that the HMD ownership is captured. This variable cannot be modified (read-only). See also OVR_CPI.h file reference.

int OCULUS_HMD_CAP_DIRECT_PENTILE

Description

Bit flag indicating that writing directly in the pentile color mapping format is supported. See also OVR_CPI.h file reference.

int OCULUS_HMD_CAP_DISPLAY_OFF

Description

Bit flag indicating that the HMD screen and output is turned off. This variable can be modified only when OCULUS_HMD_CAP_EXTEND_DESKTOP is set to 0. See also OVR_CPI.h file reference.

int OCULUS_HMD_CAP_DYNAMIC_PREDICTION

Description

Bit flag indicating that prediction must be adjusted dynamically based on the device latency. This variable can be modified. See also OVR_CPI.h file reference.

int OCULUS_HMD_CAP_EXTEND_DESKTOP

Description

Bit flag indicating that the display driver is in compatibility mode. This variable cannot be modified (read-only). See also OVR_CPI.h file reference.

int OCULUS_HMD_CAP_LOW_PERSISTENCE

Description

Bit flag indicating that the low persistence mode is supported. This variable can be modified. See also OVR_CPI.h file reference.

int OCULUS_HMD_CAP_NO_MIRROR_TO_WINDOW

Description

Bit flag indicating that the HMD output will not be mirrored to the display. This variable can be modified only when OCULUS_HMD_CAP_EXTEND_DESKTOP is set to 0. See also OVR_CPI.h file reference.

int OCULUS_HMD_CAP_NO_VSYNC

Description

Bit flag indicating that rendering without VSync for debugging is supported. See also OVR_CPI.h file reference.

int OCULUS_HMD_CAP_PRESENT

Description

Bit flag indicating that the HMD is plugged in and detected by the system. This variable cannot be modified (read-only). See also OVR_CPI.h file reference.

int OCULUS_HMD_DK1

Description

The type of the HMD is Oculus Rift DK1. It corresponds to the value of 3. See also OVR_CPI.h file reference.

int OCULUS_HMD_DK2

Description

The type of the HMD is Oculus Rift DK2. It corresponds to the value of 6. See also OVR_CPI.h file reference.

int OCULUS_HMD_DKDH

Description

The type of the HMD is Oculus Rift HD prototype. It corresponds to the value of 4. See also OVR_CPI.h file reference.

int OCULUS_STATUS_CAMERA_POSE_TRACKED

Description

Bit flag indicating that the external camera pose is currently tracked. This variable is set after the initial camera calibration. See also OVR_CPI.h file reference.

int OCULUS_STATUS_HMD_CONNECTED

Description

Bit flag indicating that the HMD hardware is available and connected. See also OVR_CPI.h file reference.

int OCULUS_STATUS_POSITION_CONNECTED

Description

Bit flag indicating that the position tracking camera is connected and functioning properly. See also OVR_CPI.h file reference.

int OCULUS_STATUS_POSITION_TRACKED

Description

Bit flag indicating that the sensor position is currently tracked (false if out of range). See also OVR_CPI.h file reference.

int OCULUS_STATUS_ROTATION_TRACKED

Description

Bit flag indicating that the sensor orientation is currently tracked (connected and in use). See also OVR_CPI.h file reference.

int OCULUS_TRACKING_CAP_IDLE

Description

Bit flag indicating that the application doesn't take into account the tracking settings. See also OVR_CPI.h file reference.

int OCULUS_TRACKING_CAP_MAG_YAW_CORRECTION

Description

Bit flag indicating that yaw drift correction via a magnetometer or other means is supported. See also OVR_CPI.h file reference.

int OCULUS_TRACKING_CAP_POSITION

Description

Bit flag indicating that positional tracking is supported. See also OVR_CPI.h file reference.

int OCULUS_TRACKING_CAP_ROTATION

Description

Bit flag indicating that orientation tracking is supported. See also OVR_CPI.h file reference.

int engine.oculus.configureTracking (int supported, int required)

Configures tracking capabilities: starts sensor sampling, enabling the specified tracking capabilities.

Notice

If you pass 0 for both function arguments, tracking will be disabled.

Arguments

int supported - Tracking capabilities (OCULUS_TRACKING_CAP_* variables) to enable. The function will succeed even if the specified capabilities are not available (sensor or camera is unplugged). The capabilities will be enabled if the device is plugged in later.
int required - Tracking capabilities (OCULUS_TRACKING_CAP_* variables) that must be supported by the HMD at the current function call. If the specified capabilities are not available, the function will fail. You can pass 0 if the required tracking capabilities are not necessary.

Return value

1 if the tracking capabilities has been configured successfully; otherwise, 0.

Examples

Source code(UnigineScript)

engine.oculus.configureTracking(OCULUS_TRACKING_CAP_ROTATION | OCULUS_TRACKING_CAP_POSITION | OCULUS_TRACKING_CAP_MAG_YAW_CORRECTION, 0);

int engine.oculus.dismissHSWDisplay ()

Dismisses the HSW (Health and Safety Warning) display if the warning can be dismissed and the earliest dismissal time has occurred.

Return value

1 if the HSW display is valid and can be dismissed; otherwise, 0.

vec3 engine.oculus.getCameraPosition ()

Returns the current position of the position tracking camera (if it is presented) relative to the tracking origin. The returned value was already multiplied by the current world scale.

Return value

Position of the position tracking camera.

quat engine.oculus.getCameraRotation ()

Returns the current orientation of the position tracking camera (if it is presented) relative to the tracking origin. The orientation is represented by the camera roll and pitch.

Return value

Orientation of the position tracking camera.

int engine.oculus.getDistortionCaps ()

Returns the distortion capabilities (OCULUS_DISTORTION_CAP_* variables) that are currently enabled.

Return value

Distortion capability bits (OCULUS_DISTORTION_CAP_*).

Examples

To check whether a specific bit flag (one of the OCULUS_DISTORTION_CAP_* bit flags) is enabled, use bitwise comparison:

Source code(UnigineScript)

if (engine.oculus.getDistortionCaps() & OCULUS_DISTORTION_CAP_CHROMATIC) {
	log.message("The bit flag is set\n");
}

int engine.oculus.getEnabledCaps ()

Returns the HMD capabilities (OCULUS_HMD_CAP_* variables) that are currently enabled.

Return value

HMD capability bits (OCULUS_HMD_CAP_*).

Examples

To check whether a specific bit flag (one of the OCULUS_HMD_CAP_* bit flags) is enabled, use bitwise comparison:

Source code(UnigineScript)

if (engine.oculus.getEnabledCaps() & OCULUS_HMD_CAP_LOW_PERSISTENCE) {
	log.message("The bit flag is set\n");
}

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.

int engine.oculus.getHSWDisplayState ()

Returns the current state of the HSW (Health and Safety Warning) display. For application-based rendering of the HSW display, this function is used to indicate that the warning should be displayed.

Return value

Current state of the HSW display.

vec3 engine.oculus.getHeadAngularAcceleration ()

Returns the current angular acceleration of the head.

Return value

Angular acceleration of the head.

vec3 engine.oculus.getHeadAngularVelocity ()

Returns the current angular velocity of the head.

Return value

Angular velocity of the head.

vec3 engine.oculus.getHeadLinearAcceleration ()

Returns the current linear acceleration of the head.

Return value

Linear acceleration of the head.

vec3 engine.oculus.getHeadLinearVelocity ()

Returns the current linear velocity of the head.

Return value

Linear velocity of the head.

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.

quat engine.oculus.getHeadRotation ()

Returns the current orientation of the head.

Return value

Orientation of the head.

float engine.oculus.getHmdCameraHFov ()

Returns the horizontal FOV of the position tracking camera frustum in degrees.

Return value

Horizontal FOV of the position tracking camera frustum in degrees.

float engine.oculus.getHmdCameraVFov ()

Returns the vertical FOV of the position tracking camera frustum in degrees.

Return value

Vertical FOV of the position tracking camera frustum in degrees.

float engine.oculus.getHmdCameraZFar ()

Returns the distance from the position tracking camera to the far frustum bounds. The returned value was already multiplied by the current world scale.

Return value

Distance from the position tracking camera to the far frustum bounds.

float engine.oculus.getHmdCameraZNear ()

Returns the distance from the position tracking camera to the near frustum bounds. The returned value was already multiplied by the current world scale.

Return value

Distance from the position tracking camera to the near frustum bounds.

int engine.oculus.getHmdCaps ()

Returns HMD capability bits (OCULUS_HMD_CAP_* variables) reported by the device.

Return value

HMD capability bits.

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

Optical field of view.

int engine.oculus.getHmdDisplayID ()

Returns the system specific ID of the display device.

Return value

The display device ID.

string engine.oculus.getHmdDisplayName ()

Returns the system specific name of the display device.

Return value

The display device name.

int engine.oculus.getHmdDistortionCaps ()

Returns distortion capabilities (OCULUS_DISTORTION_CAP_* variables) reported by device.

Return value

Distortion capability bits.

int engine.oculus.getHmdFirmwareMajor ()

Returns the major version of the sensor firmware.

Return value

The major version of the sensor firmware.

int engine.oculus.getHmdFirmwareMinor ()

Returns the minor version of the sensor firmware.

Return value

The minor version of the sensor 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 device manufacturer.

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 optical field of view.

int engine.oculus.getHmdPositionX ()

Returns the X coordinate of the monitor window location on the screen.

Return value

X coordinate of the monitor window location.

int engine.oculus.getHmdPositionY ()

Returns the Y coordinate of the monitor window location on the screen.

Return value

Y coordinate of the monitor window location.

int engine.oculus.getHmdProductID ()

Returns the Product ID reported by the headset USB device.

Return value

Product ID.

string engine.oculus.getHmdProductName ()

Returns the name of the device. For example: "Oculus Rift DK1".

Return value

The device name.

int engine.oculus.getHmdTrackingCaps ()

Returns tracking capabilities (OCULUS_TRACKING_CAP_* variables) reported by the device.

Return value

Tracking capability bits.

int engine.oculus.getHmdType ()

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

Return value

The HMD type.

int engine.oculus.getHmdVendorID ()

Returns the Vendor ID reported by the headset USB 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.getLeveledCameraPosition ()

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

Return value

Position of the leveled position tracking camera.

quat engine.oculus.getLeveledCameraRotation ()

Returns the orientation of the leveled position tracking camera relative to the tracking origin. The orientation is represented by yaw of the camera.

Return value

Orientation of the leveled position tracking camera.

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.

mat4 engine.oculus.getProjection (vec4 fov, float znear, float zfar)

Generates a projection matrix used during left and right eye scene rendering. Note that the right-handed coordinate system is used.

Arguments

vec4 fov - Field of view in tangent of the angle units (see ).
float znear - Near clipping plane.
float zfar - Far clipping plane.

Return value

Projection matrix.

int engine.oculus.getTrackingStatus ()

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

Return value

Status of the sensor (OCULUS_STATUS_* variables).

string engine.oculus.getVersion ()

Returns the libOVR version.

Return value

The libOVR version.

void engine.oculus.resetTracking ()

Re-centers the sensor orientation: the (x,y,z) translation components and the yaw component of orientation.

void engine.oculus.setDistortionCaps (int distortion)

Sets the distortion capabilities (OCULUS_DISTORTION_CAP_* variables) enabled.

Arguments

int distortion - Distortion capability bits (OCULUS_DISTORTION_CAP_*).

Examples

To set several bit flags, use bitwise inclusive OR operator:

Source code(UnigineScript)

engine.oculus.setDistortionCaps(OCULUS_DISTORTION_CAP_CHROMATIC | OCULUS_DISTORTION_CAP_VINGETTE);

void engine.oculus.setEnabled (int enabled)

Toggles the VR mode.

Arguments

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

void engine.oculus.setEnabledCaps (int caps)

Sets the HMD capabilities (OCULUS_HMD_CAP_* variables) enabled.

Notice
				You can set only capabilities that can be modified. 
			

Arguments

int caps - HMD capability bits (OCULUS_HMD_CAP_*).

Examples

To set several bit flags, use bitwise inclusive OR operator:

Source code(UnigineScript)

engine.oculus.setEnabledCaps(OCULUS_HMD_CAP_LOW_PERSISTENCE | OCULUS_HMD_CAP_DYNAMIC_PREDICTION);

void engine.oculus.setLeftModelview (mat4 left_modelview)

Sets a modelview matrix used during left eye scene rendering.

Arguments

mat4 left_modelview - Modelview matrix for the left eye.

void engine.oculus.setLeftProjection (mat4 left_projection)

Sets a projection matrix used during left eye scene rendering.

Arguments

mat4 left_projection - Projection matrix for the left eye.

void engine.oculus.setModelview (mat4 modelview)

Sets a modelview matrix that will be used during left and right eye scene rendering.

Arguments

mat4 modelview - Modelview matrix.

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.

void engine.oculus.setProjection (mat4 projection)

Sets a projection matrix that will be used during left and right eye scene rendering.

Arguments

mat4 projection - Projection matrix.

void engine.oculus.setRightModelview (mat4 right_modelview)

Sets a modelview matrix used during right eye scene rendering.

Arguments

mat4 right_modelview - Modelview matrix for the right eye.

void engine.oculus.setRightProjection (mat4 right_projection)

Sets a projection matrix used during right eye scene rendering.

Arguments

mat4 right_projection - Projection matrix for the right eye.

Last update: 2017-07-03

Help improve this article

Was this article helpful?

Report a problem related to this article

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