engine.oculus Functions
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:
#ifdef HAS_APP_OCULUS
// engine.oculus functions
#endif
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.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
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:
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:
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:
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.
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:
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?
(or select a word/phrase and press Ctrl+Enter)