Graphics.UI.SpaceNavigator

Functions for managing input from a SpaceNavigator <http://www.3dconnexion.com/products/spacemouse/spacenavigator.html>, or a 3D mouse compatible with its protocols. OpenGL callbacks are provided, along with utilities for quantizing the input from the mouse or tracking its six degrees of freedom.

Here is a simple example illustating the use of this module:

main :: IO ()
main = do
  _ <- getArgsAndInitialize
  initialDisplayMode $= [WithDepthBuffer, DoubleBuffered]
  _ <- createWindow "SpaceNavigator OpenGL Example"
  depthFunc $= Just Less 
  -- Create the tracker.
  tracking <- newIORef $ def {spaceNavigatorPosition = Vector3 0 0 0}
  -- Register a callback which quantizes and tracks the 3D mouse input.
  spaceNavigatorCallback $=! Just ( quantizeSpaceNavigator defaultQuantization $ trackSpaceNavigator defaultTracking tracking)
  -- The display callback needs the tracker.
  displayCallback $= display tracking
  idleCallback $= Just (postRedisplay Nothing)
  mainLoop

display :: IORef SpaceNavigatorTrack -> DisplayCallback
display tracking =
  do
    clear [ColorBuffer, DepthBuffer]
    loadIdentity
    -- Get the tracking state.
    tracking' <- get tracking
    -- Update the matrix based on the tracking
    doTracking tracking'
    -- All of the rendering actions go here.
    renderPrimitive . . . 
    swapBuffers

This code has been validated with the following configuration of hardware and software:

• SpaceNavigator <http://www.3dconnexion.com/products/spacemouse/spacenavigator.html>
• spacenavd <http://spacenav.sourceforge.net/>, 0.5
• Ubuntu 15.04, 64-bit
• GHC 7.6.3
• OpenGL == 2.8.0.0
• GLUT == 2.4.0.0

Input

data SpaceNavigatorInput

Input received from a SpaceNavigator 3D mouse.

Constructors

Push

The mouse has been pushed.

Fields

• pushRightward :: GLfloat

  The amount of rightward push, from -1 to +1.

• pushUpward :: GLfloat

  The amount of upward push, from -1 to +1.

• pushBackward :: GLfloat

  The amount of backward push, from -1 to +1.

Tilt

The mouse has been tilted.

Fields

• tiltForward :: GLfloat

  The amount of forward tilt, from -1 to +1.

• tiltClockwise :: GLfloat

  The amount of clockwise twist, from -1 to +1.

• tiltRightward :: GLfloat

  The amount of rightward tilt, from -1 to +1.

Button

A mouse button has been pressed.

Fields

• buttonPress :: Button

  Which button has been pressed.

• buttonAction :: ButtonAction

  Whether the button has been pressed or released.

Instances

Eq SpaceNavigatorInput

Methods

(==) :: SpaceNavigatorInput -> SpaceNavigatorInput -> Bool

(/=) :: SpaceNavigatorInput -> SpaceNavigatorInput -> Bool

Read SpaceNavigatorInput

Methods

readsPrec :: Int -> ReadS SpaceNavigatorInput

readList :: ReadS [SpaceNavigatorInput]

readPrec :: ReadPrec SpaceNavigatorInput

readListPrec :: ReadPrec [SpaceNavigatorInput]

Show SpaceNavigatorInput

Methods

showsPrec :: Int -> SpaceNavigatorInput -> ShowS

show :: SpaceNavigatorInput -> String

showList :: [SpaceNavigatorInput] -> ShowS

data Button

Buttons on a SpaceNavigator 3D mouse.

Constructors

ButtonLeft

The left button.

ButtonRight

The right button.

ButtonOther Int

Neither the left nor the right button.

Instances

Eq Button

Methods

(==) :: Button -> Button -> Bool

(/=) :: Button -> Button -> Bool

Read Button

Methods

readsPrec :: Int -> ReadS Button

readList :: ReadS [Button]

readPrec :: ReadPrec Button

readListPrec :: ReadPrec [Button]

Show Button

Methods

showsPrec :: Int -> Button -> ShowS

show :: Button -> String

showList :: [Button] -> ShowS

data ButtonAction

Pressing and releasing actions on a SpaceNavigator 3D mouse.

Constructors

ButtonPress

The button has been pressed.

ButtonRelease

The button has been released.

Instances

Eq ButtonAction

Methods

(==) :: ButtonAction -> ButtonAction -> Bool

(/=) :: ButtonAction -> ButtonAction -> Bool

Read ButtonAction

Methods

readsPrec :: Int -> ReadS ButtonAction

readList :: ReadS [ButtonAction]

readPrec :: ReadPrec ButtonAction

readListPrec :: ReadPrec [ButtonAction]

Show ButtonAction

Methods

showsPrec :: Int -> ButtonAction -> ShowS

show :: ButtonAction -> String

showList :: [ButtonAction] -> ShowS

type SpaceNavigatorCallback = SpaceNavigatorInput -> IO ()

A callback for input from the SpaceNavigator 3D mouse.

spaceNavigatorCallback :: SettableStateVar (Maybe SpaceNavigatorCallback)

Register the callback for input from the SpaceNavigator 3D mouse.

Quantization

quantize

Arguments

:: (GLfloat, GLfloat)

The thresholds for pushing and titling, respectively, between 0 and +1.

-> SpaceNavigatorCallback

The callback for the mouse.

-> SpaceNavigatorCallback

A callback that receives quantized input {-1, 0, +1}.

Quantize the input from a SpaceNavigator 3D mouse according to whether the input exceeds a threshold. The quantized input is -1, +1, or 0, depending on whether a threshold is exceeded.

defaultQuantization :: (GLfloat, GLfloat)

A default quantization for the SpaceNavigator 3D mouse.

Tracking

data Track

Tracking information for a SpaceNavigator 3D mouse.

Constructors

Track

Fields

• trackMode :: TrackMode

  The tracking mode.

• trackPosition :: Vector3 GLfloat

  The coordinates for the position.

• trackOrientation :: Vector3 GLfloat

  The Euler angles for the orientation: yaw/heading, pitch/elevation, and roll/bank, relative an initial orientation where the -z axis is forward: see <https://en.wikipedia.org/wiki/Euler_angles#Alternative_names>.

• trackLeftPress :: Bool

  Whether the left button is pressed.

• trackRightPress :: Bool

  Whether the right button is pressed.

• trackLastPressed :: Maybe Button

  The last button pressed, if any.

Instances

Eq Track

Methods

(==) :: Track -> Track -> Bool

(/=) :: Track -> Track -> Bool

Read Track

Methods

readsPrec :: Int -> ReadS Track

readList :: ReadS [Track]

readPrec :: ReadPrec Track

readListPrec :: ReadPrec [Track]

Show Track

Methods

showsPrec :: Int -> Track -> ShowS

show :: Track -> String

showList :: [Track] -> ShowS

Default Track

Methods

def :: Track

data TrackMode

The mode for tracking a SpaceNavigator 3D mouse.

Currently only one mode is available, but other modes, such as flying and examining, will be implemented in the future.

Constructors

TrackPlatform

Track the mouse as a "platform" in 3D space:

push rightward

increment x position

push leftward

decrement x position

pull upward

increment z position

push downward

decrement z position

pull backward

increment z position

push forward

decrement z position

tilt leftward

increment first Euler angle, yaw/heading

tilt rightward

decrement first Euler angle, yaw/heading

twist counterclockwise

increment second Euler angle, pitch/elevation

twist clockwise

decrement second Euler angle, pitch/elevation

tilt backward

increment third Euler angle, roll/bank

tilt forward

decrement third Euler angle, roll/bank

Instances

Eq TrackMode

Methods

(==) :: TrackMode -> TrackMode -> Bool

(/=) :: TrackMode -> TrackMode -> Bool

Read TrackMode

Methods

readsPrec :: Int -> ReadS TrackMode

readList :: ReadS [TrackMode]

readPrec :: ReadPrec TrackMode

readListPrec :: ReadPrec [TrackMode]

Show TrackMode

Methods

showsPrec :: Int -> TrackMode -> ShowS

show :: TrackMode -> String

showList :: [TrackMode] -> ShowS

Default TrackMode

Methods

def :: TrackMode

defaultTracking :: (Vector3 GLfloat, Vector3 GLfloat)

Default tracking rates for the SpaceNavigator 3D mouse.

track

Arguments

:: (Vector3 GLfloat, Vector3 GLfloat)

The rates at which to push or tilt, respectively, based on the mouse input.

-> IORef Track

A reference to the tracking information.

-> SpaceNavigatorCallback

A callback for doing the tracking.

Track the movement of a SpaceNavigator 3D mouse.

doTracking

Arguments

:: Track

The tracking information.

-> IO ()

An action to track the mouse.

Return an action to track a SpaceNavigator 3D mouse via OpenGL matrices.

This simply calls glTranslate on the position, followed by calls to glRotate for the third Euler angle (roll/bank) around the x-axis, the second (pitch/elevation) around the y-axis, and then the first (yaw/heading) around the z-axis, relative to an initial orientation where the -z axis is forward.

doTracking'

Arguments

:: IORef Track

A reference to the tracking information.

-> IO ()

An action to track the mouse.

Return an action to track a SpaceNavigator 3D mouse via OpenGL matrices.

This simply calls glTranslate on the position, followed by calls to glRotate for the third Euler angle (roll/bank) around the x-axis, the second (pitch/elevation) around the y-axis, and then the first (yaw/heading) around the z-axis, relative to an initial orientation where the -z axis is forward.

Viewing

doPilotView

Arguments

:: Track

The tracking information.

-> IO ()

An action to set the view.

Return an action to create a "pilot-eye" view from tracking a SpaceNavigator 3D mouse via OpenGL matrices.

This simply calls glRotate for the third Euler angle (roll/bank) around the x-axis, then the second (pitch/elevation) around the y-axis, and then the first (yaw/heading) around the z-axis, relative to an initial orientation where the -z axis is forward, finalling calling glTranslate on the negated position.

doPilotView'

Arguments

:: IORef Track

A reference to the tracking information.

-> IO ()

An action to set the view.

Return an action to create a "pilot-eye" view from tracking a SpaceNavigator 3D mouse via OpenGL matrices.

This simply calls glRotate for the third Euler angle (roll/bank) around the x-axis, then the second (pitch/elevation) around the y-axis, and then the first (yaw/heading) around the z-axis, relative to an initial orientation where the -z axis is forward, finalling calling glTranslate on the negated position.

doPolarView

Arguments

:: Track

The tracking information.

-> IO ()

An action to set the view.

Return an action to create a "polar" view from tracking a SpaceNavigator 3D mouse via OpenGL matrices.

This simply calls glTranslate on along the z-axis negative norm of the position, followed by calls to glRotate for the negated third Euler angle (roll/bank) around the x-axis, the negate second (pitch/elevation) around the y-axis, and then the first (yaw/heading) around the z-axis, relative to an initial orientation where the -z axis is forward.

doPolarView'

Arguments

:: IORef Track

A reference to the tracking information.

-> IO ()

An action to set the view.

Return an action to create a "polar" view from tracking a SpaceNavigator 3D mouse via OpenGL matrices.

This simply calls glTranslate on along the z-axis negative norm of the position, followed by calls to glRotate for the negated third Euler angle (roll/bank) around the x-axis, the negate second (pitch/elevation) around the y-axis, and then the first (yaw/heading) around the z-axis, relative to an initial orientation where the -z axis is forward.