Rift¶

Attributes¶

Details¶

class psychopy.visual.Rift(fovType='recommended', trackingOriginType='eye', texelsPerPixel=1.0, headLocked=False, highQuality=True, nearClip=0.1, farClip=100.0, monoscopic=False, samples=1, mirrorRes=None, legacyOpenGL=True, warnAppFrameDropped=True, *args, **kwargs)¶

Class provides a display and peripheral interface for the Oculus Rift (see: https://www.oculus.com/) head-mounted display.

Parameters:

fovType (str) – Field-of-view (FOV) configuration type. Using ‘recommended’ auto-configures the FOV using the recommended parameters computed by the runtime. Using ‘symmetric’ forces a symmetric FOV using optimal parameters from the SDK. trackingOriginType (str) – Specify the HMD origin type. If ‘floor’, the height of the user is added to the head tracker by LibOVR. texelsPerPixel (float) – Texture pixels per display pixel at FOV center. A value of 1.0 results in 1:1 mapping. A fractional value results in a lower resolution draw buffer which may increase performance. headLocked (bool) – Lock the head position to the world origin. This cancels out any translation and rotation from the headset. Note, hand poses are NOT transformed accordingly (this will be addressed eventually). highQuality (bool) – Configure the compositor to use anisotropic texture sampling (4x). This reduces aliasing artifacts resulting from high frequency details particularly in the periphery. nearClip (float) – Location of the near clipping plane in GL units (meters by default) from the viewer. farClip (float) – Location of the far clipping plane in GL units (meters by default) from the viewer. monoscopic (bool) – Enable monoscopic rendering mode which presents the same image to both eyes. Eye poses used will be both centered at the HMD origin. Monoscopic mode uses a separate rendering pipeline which reduces VRAM usage. When in monoscopic mode, you do not need to call ‘setBuffer’ prior to rendering (doing so will do have no effect). samples (int) – Specify the number of samples for anti-aliasing. When >1, multi-sampling logic is enabled in the rendering pipeline. If ‘max’ is specified, the largest number of samples supported by the platform is used. If floating point textures are used, MSAA sampling is disabled. Must be power of two value. legacyOpenGL (bool) – Disable ‘immediate mode’ OpenGL calls in the rendering pipeline. Specifying False maintains compatibility with existing PsychoPy stimuli drawing routines. Use True when computing transformations using some other method and supplying shaders matrices directly. mirrorRes (list of int) – Resolution of the mirror texture. If None, the resolution will match the window size. warnAppFrameDropped (bool) – Log a warning if the application drops a frame. This occurs when the application fails to submit a frame to the compositor on-time. Application frame drops can have many causes, such as running routines in your application loop that take too long to complete. However, frame drops can happen sporadically due to driver bugs and running background processes (such as Windows Update). Use the performance HUD to help diagnose the causes of frame drops.

_prepareMonoFrame(clear=True)¶

Prepare a frame for monoscopic rendering. This is called automatically after ‘startHmdFrame’ if monoscopic rendering is enabled.

_resolveMSAA()¶

Resolve multisample anti-aliasing (MSAA). If MSAA is enabled, drawing operations are diverted to a special multisample render buffer. Pixel data must be ‘resolved’ by blitting it to the swap chain texture. If not, the texture will be blank.

NOTE: You cannot perform operations on the default FBO (at frameBuffer) when MSAA is enabled. Any changes will be over-written when ‘flip’ is called.

Returns:
Return type:	None

_setupFrameBuffer()¶

Override the default framebuffer init code in window.Window to use the HMD swap chain. The HMD’s swap texture and render buffer are configured here.

If multisample anti-aliasing (MSAA) is enabled, a secondary render buffer is created. Rendering is diverted to the multi-sample buffer when drawing, which is then resolved into the HMD’s swap chain texture prior to committing it to the chain. Consequently, you cannot pass the texture attached to the FBO specified by frameBuffer until the MSAA buffer is resolved. Doing so will result in a blank texture.

Returns:
Return type:	None

_startHmdFrame()¶

Prepare to render an HMD frame. This must be called every frame before flipping or setting the view buffer.

This function will wait until the HMD is ready to begin rendering before continuing. The current frame texture from the swap chain are pulled from the SDK and made available for binding.

Returns:
Return type:	None

_startOfFlip()¶

Custom _startOfFlip for HMD rendering. This finalizes the HMD texture before diverting drawing operations back to the on-screen window. This allows ‘flip()’ to swap the on-screen and HMD buffers when called. This function always returns True.

Returns:
Return type:	True

_updatePerformanceStats()¶

Run profiling routines. This just reports if the application drops a frame. Nothing too fancy yet.

_updateProjectionMatrix()¶

Update or re-calculate projection matrices based on the current render descriptor configuration.

Returns:
Return type:	None

_updateTrackingState()¶

Update the tracking state and calculate new eye poses.

The absolute display time is updated when called and used when computing new head, eye and hand poses.

Returns:
Return type:	None

absTime¶

Get the absolute time for this frame.

controllerConnected(controller='xbox')¶

Check if a given device is connected to the Haptics engine.

Parameters:	controller (str) – Name of the controller to check if connected.
Returns:	True if specified controller connected, else False.
Return type:	boolean

displayLost¶

Check of the display has been lost.

Returns:
Return type:	bool

displayRefreshRate¶

Get the HMD’s display refresh rate. This rate is independent of the monitor display rate.

Returns:	Refresh rate in Hz.
Return type:	float

firmwareVersion¶

Get the firmware version of the active HMD. Returns a tuple containing the major and minor version.

Returns:	Firmware major and minor version.
Return type:	tuple (int, int)

flip(clearBuffer=True)¶

Submit view buffer images to the HMD’s compositor for display at next V-SYNC. This must be called every frame.

Parameters:	clearBuffer (boolean) – Clear the frame after flipping.
Returns:
Return type:	None

getButtons(buttonNames, controller='xbox', edgeTrigger='continuous')¶

Returns True if any of the buttons in button_list are held down. All buttons are ORed together and tested. Edge triggering can be enabled by specifying either ‘rising’ or ‘falling’ to edge_trigger. When enabled, True is returned only when a button’s state changes. If button_list is empty, will return True when no buttons are pressed.

Valid button values are ‘A’, ‘B’, ‘RThumb’, ‘X’, ‘Y’, ‘LThumb’, ‘LShoulder’, ‘Up’, ‘Down’, ‘Left’, ‘Right’, ‘Enter’, ‘Back’, ‘VolUp’, ‘VolDown’, ‘Home’, ‘RMask’ and ‘LMask’.

Returns:
Return type:	bool

Examples

# check if the ‘Enter’ button on the Oculus remote was released isPressed = getButtons([‘Enter’], ‘remote’, ‘falling’)

getConectedControllers()¶

Get a list of connected input devices (controllers) managed by the LibOVR runtime. Valid names are ‘xbox’, ‘remote’, ‘left_touch’, ‘right_touch’ and ‘touch’.

Returns:	List of connected controller names.
Return type:	list

getHandTriggerValues(controller='xbox', deadzone=False)¶

Get the values of the hand triggers representing the amount they are being displaced.

Parameters:	controller (str) – Name of the controller to get hand trigger values. deadzone (bool) – Apply the deadzone to hand trigger values.
Returns:	Left and right index trigger values.
Return type:	tuple

getIndexTriggerValues(controller='xbox', deadzone=False)¶

Get the values of the index triggers representing the amount they are being displaced.

Parameters:	controller (str) – Name of the controller to get index trigger values. deadzone (bool) – Apply the deadzone to index trigger values.
Returns:	Left and right index trigger values.
Return type:	tuple

getThumbstickValues(controller='xbox', deadzone=False)¶

Get a list of tuples containing the displacement values (with deadzone) for each thumbstick on a specified controller.

Axis displacements are represented in each tuple by a floats ranging from -1.0 (full left/down) to 1.0 (full right/up). The SDK library pre-filters stick input to apply a dead-zone where 0.0 will be returned if the sticks return a displacement within -0.2746 to 0.2746. Index 0 of the returned tuple contains the X,Y displacement values of the left thumbstick, and the right thumbstick values at index 1.

Possible values for ‘controller’ are ‘xbox’ and ‘touch’; the only devices with thumbsticks the SDK manages.

Parameters:	controller (str) – Name of the controller to get thumbstick values. deadzone (bool) – Apply the deadzone to thumbstick values.
Returns:	Left and right, X and Y thumbstick values.
Return type:	tuple

getTouches(touchNames, edgeTrigger='continuous')¶

Returns True if any buttons are touched using sensors. This feature is used to estimate finger poses and can be used to read gestures. An example of a possible use case is a pointing task, where responses are only valid if the user’s index finger is extended away from the index trigger button.

Currently, this feature is only available with the Oculus Touch controllers.

Returns:
Return type:	None

getTrackingOriginType()¶

Get the current tracking origin type.

Returns:
Return type:	str

hasInputFocus¶

Check if the application currently has input focus.

Returns:
Return type:	bool

headLocked¶

Enable/disable head locking.

isHmdMounted¶

Check if the HMD is mounted on the user’s head.

Returns:	True if the HMD is being worn, otherwise False.
Return type:	bool

isHmdPresent¶

Check if the HMD is present.

Returns:	True if the HMD is present, otherwise False.
Return type:	bool

isIndexPointing(hand='right')¶

Check if the user is doing a pointing gesture with the given hand, or if the index finger is not touching the controller. Only applicable when using Oculus Touch controllers.

Returns:
Return type:	None

isThumbUp(hand='right')¶

Check if the user’s thumb is pointing upwards with a given hand, or if not touching the controller. Only applicable when using Oculus Touch controllers.

Returns:
Return type:	None

isVisible¶

Check if the app has focus in the HMD and is visible to the viewer.

Returns:	True if app has focus and is visible in the HMD, otherwise False.
Return type:	bool

manufacturer¶

Get the connected HMD’s manufacturer.

Returns:	UTF-8 encoded string containing the manufacturer name.
Return type:	str

multiplyProjectionMatrixGL()¶

Multiply the current projection matrix obtained from the SDK using glMultMatrixf(). The matrix used depends on the current eye buffer set by ‘setBuffer()’.

Returns:
Return type:	None

multiplyViewMatrixGL()¶

Multiply the local eye pose transformation matrix obtained from the SDK using glMultMatrixf(). The matrix used depends on the current eye buffer set by ‘setBuffer()’.

Returns:
Return type:	None

overlayPresent¶

pollControllers()¶

Update all connected controller states. This should be called at least once per frame.

Returns:
Return type:	None

productName¶

Get the HMD’s product name.

Returns:	UTF-8 encoded string containing the product name.
Return type:	str

projectionMatrix¶

Get the projection matrix for the current buffer.

raycastSphere(originPose, targetPose, targetRadius=0.5, rayDirection=None, maxRange=None)¶

Project an invisible ray of finite or infinite length from the originPose in rayDirection and check if it intersects with the targetPose bounding sphere.

Specifying maxRange as >0.0 casts a ray of finite length in world units. The distance between the target and ray origin position are checked prior to casting the ray; automatically failing if the ray can never reach the edge of the bounding sphere centered about targetPose. This avoids having to do the costly transformations required for picking.

This raycast implementation can only determine if contact is being made with the object’s bounding sphere, not where on the object the ray intersects. This method might not work for irregular or elongated objects since bounding spheres may not approximate those shapes well. In such cases, one may use multiple spheres at different locations and radii to pick the same object.

:param originPose ovrPosef: Origin pose of the ray. :param targetPose ovrPosef or: Pose of the target. :type targetPose ovrPosef or: obj:ovrVector3f’ :param targetRadius :obj:`float: The radius of the target. :param rayDirection ovrVector3f: Vector indicating the direction for the ray. If None is specified,

then -Z is used.

Parameters:	maxRange – The maximum range of the ray. Ray testing will fail automatically if the target is out of range. The ray has infinite length if None is specified.
Returns:	True if the ray intersects anywhere on the bounding sphere, False in every other condition.
Return type:	bool

Examples

# raycast from the head pose to a target headPose = hmd.headPose targetPos = rift.math.ovrVector3f(0.0, 0.0, -5.0) # 5 meters front isLooking = hmd.raycast(headPose, targetPos)

# now with touch controller positions rightHandPose = hmd.getHandPose(1) # 1 = right hand fingerLength = 0.10 # 10 cm pointing = hmd.raycast(rightHandPose, targetPos, maxRange=fingerLength)

recenterTrackingOrigin()¶

Recenter the tracking origin.

Returns:
Return type:	None

resolution¶

Get the HMD’s raster display size.

Returns:	Width and height in pixels.
Return type:	tuple (int, int)

serialNumber¶

Get the connected HMD’s unique serial number. Use this to identify a particular unit if you own many.

Returns:	UTF-8 encoded string containing the devices serial number.
Return type:	str

setBuffer(buffer, clear=True)¶

Set the active stereo draw buffer.

Warning! The window.Window.size property will return the buffer’s dimensions in pixels instead of the window’s when setBuffer is set to ‘left’ or ‘right’.

Parameters:	buffer (str) – View buffer to divert successive drawing operations to, can be either ‘left’ or ‘right’. clear (boolean) – Clear the color, stencil and depth buffer.
Returns:
Return type:	None

setDefaultView(clearDepth=True)¶

Return to default projection. Call this before drawing PsychoPy’s 2D stimuli after a stereo projection change.

Note: This only has an effect if using Rift in legacy immediate mode OpenGL mode by setting ~Rift.legacy_opengl=True.

Parameters:	clearDepth (boolean) – Clear the depth buffer prior after configuring the view parameters.
Returns:
Return type:	None

setHudMode(mode='Off')¶

setRiftView(clearDepth=True)¶

Set head-mounted display view. Gets the projection and view matrices from the HMD and applies them.

Note: This only has an effect if using Rift in legacy immediate mode OpenGL mode by setting ~Rift.legacy_opengl=True.

Parameters:	clearDepth (boolean) – Clear the depth buffer prior after configuring the view parameters.
Returns:
Return type:	None

setSize(value, log=True)¶

setTrackinOrigin(origin_type='floor', recenter=False)¶

Set the tracking origin type. Can either be ‘floor’ or ‘eye’. The effect of changing types is immediate.

Parameters:	origin_type (str) – Tracking origin type to use, can be either ‘floor’ or ‘eye’. recenter (boolean) – If True, the tracking origin is applied immediately.
Returns:
Return type:	None

shouldQuit¶

Check if the user requested the application should quit through the headset’s interface.

Returns:	True if user requested the application quit via some menu in the HMD, otherwise False.
Return type:	bool

shouldRecenter¶

Check if the user requested the origin be recentered through the headset’s interface.

Returns:	True if user requested the application recenter itself to reposition the origin, else False.
Return type:	bool

size¶

Size property to get the dimensions of the view buffer instead of the window. If there are no view buffers, always return the dims of the window.

trackingOriginType¶

Current tracking origin type.

viewMatrix¶

Get the view matrix for the current buffer.