pyopenvr

To use pyopenvr, ensure you have the following prerequisites installed:

1. Python 3.5+
2. HTC Vive SteamVR

Then, install the bindings using pip or by downloading the installer from the official releases page.

pip install openvr

When OpenVR functions return a failure code, pyopenvr raises specific Python exceptions derived from OpenVRError. Instead of catching a generic Exception, you can catch OpenVRError or more specific error subclasses to handle different failure modes precisely.

To convert a raw error value (integer) into its corresponding Python exception class, use the check_error_value class method on an ErrorCode subclass.

from openvr.error_code import TrackedPropertyError

# Example of checking an error value returned from an OpenVR call
try:
    # Assume error_val is an integer returned by a C++ binding
    TrackedPropertyError.check_error_value(error_val, "Failed to read property")
except TrackedPropertyError as e:
    print(f"OpenVR Tracked Property Error: {e}")
except OpenVRError as e:
    print(f"General OpenVR Error: {e}")

To use the OpenVR API, you must first initialize the runtime. Use init(applicationType, pStartupInfo=None) to find the active installation and initialize it. This returns a VRSystem instance. To release resources and unload the library, call shutdown().

Note on pStartupInfo: If provided, this must be an absolute or relative path to the "root" of the VR API install (the directory containing the drivers directory and a platform directory, not just the DLL location).

import openvr

# Initialize OpenVR
system = openvr.init(openvr.EVRApplicationType.VRApplication_Application)

# ... use system ...

# Shutdown OpenVR
openvr.shutdown()

To use pyopenvr, you must initialize the VR system using openvr.init() with an appropriate application type (e.g., openvr.VRApplication_Scene). After performing your VR operations, always call openvr.shutdown() to release resources.

In the main loop, you can use openvr.VRCompositor().waitGetPoses() to retrieve device poses, such as the HMD pose, which can be accessed via the openvr.k_unTrackedDeviceIndex_Hmd index.

import sys
import time
import openvr

openvr.init(openvr.VRApplication_Scene)
poses = []  # will be populated with proper type after first call
for i in range(100):
    poses, _ = openvr.VRCompositor().waitGetPoses(poses, None)
    hmd_pose = poses[openvr.k_unTrackedDeviceIndex_Hmd]
    print(hmd_pose.mDeviceToAbsoluteTracking)
    sys.stdout.flush()
    time.sleep(0.2)
openvr.shutdown()

The Overlay interface allows you to create and manage 2D elements in the VR space. You can set textures, handle mouse/laser intersections, and manage cursors.

Key Tasks:

• Set Texture: Use setOverlayTexture to provide a texture for the overlay. Note that this can only be called by the overlay's creator or renderer process.
• Intersection Testing: Use computeOverlayIntersection to find where a ray intersects the overlay in pixel coordinates.
• Cursor Management: Use setOverlayCursor to change the default blob to a custom cursor, and setOverlayCursorPositionOverride to manually position the cursor.
• Haptics: Trigger haptic feedback on the laser mouse controller using triggerLaserMouseHapticVibration.

Dashboard overlays are special overlays that appear when the user opens the SteamVR dashboard.

Key Tasks:

• Create Dashboard Overlay: Use createDashboardOverlay(overlayKey, overlayFriendlyName) to create a new dashboard overlay. It returns a mainHandle and a thumbnailHandle.
• Visibility: Check if the dashboard is visible using isDashboardVisible() or if a specific overlay is the active one using isActiveDashboardOverlay(overlayHandle).
• Process Focus: Use setDashboardOverlaySceneProcess(overlayHandle, processId) to ensure the overlay only appears when a specific process has scene focus.

The IVROverlayView interface allows you to acquire read privileges over an overlay's contents to sample them.

Workflow:

1. Acquire: Call acquireOverlayView(overlayHandle) to get a VROverlayView_t and a VRNativeDevice_t.
2. Sample: Use the acquired view to sample contents via native APIs.
3. Release: You must call releaseOverlayView() to release the acquired resources. Failure to do so will leak GPU resources.

The IVRRenderModels interface is used to load and interact with 3D models representing tracked devices (like controllers).

Key Tasks:

• Load Models: Use loadRenderModel_Async(renderModelName) to load a model. It returns a RenderModel_t pointer. The method returns VRRenderModelError_Loading while the model is still loading.
• Manage Memory: Always call freeRenderModel(renderModel) when finished to prevent memory leaks.
• Component Interaction: Models are composed of 'components' (e.g., buttons, triggers). Use getComponentCount(renderModelName) and getComponentName(renderModelName, componentIndex) to iterate through them.
• Component State: Use getComponentStateForDevicePath(renderModelName, componentName, devicePath, state) to query the current state (position, motion, etc.) of a specific component.

Retrieves the next event from the OpenVR event queue.

• pollNextEvent(event): Fills the provided event struct with the next event. Returns True if an event was available, False otherwise.
• pollNextEventWithPose(origin, event): Fills the event and also provides the pose of the associated tracked device in a provided pose struct. Note that this pose will be older than the call time and should not be used for rendering.
• pollNextEventWithPoseAndOverlays(origin, event): An efficient way to poll both system events and overlay-specific events (like button presses on an overlay). If an event is targeted at a specific overlay, pulOverlayHandle will be set.

# Example: Polling for a standard event
event = VREvent_t()
if vr_system.pollNextEvent(event):
    print(f"Event type: {vr_system.getEventTypeNameFromEnum(event.eventType)}")