Copyright	(c) 2015 Brian W Bush
License	MIT
Maintainer	Brian W Bush <consult@brianwbush.info>
Stability	Stable
Portability	Portable
Safe Haskell	None
Language	Haskell2010

Graphics.UI.SpaceNavigator

Contents

Input
Quantization
Tracking
Viewing

Description

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

Synopsis

Input

data SpaceNavigatorInput a Source

Input received from a SpaceNavigator 3D mouse.

Constructors

Push	The mouse has been pushed.
Fields pushRightward :: a The amount of rightward push, from -1 to +1. pushUpward :: a The amount of upward push, from -1 to +1. pushBackward :: a The amount of backward push, from -1 to +1.
Tilt	The mouse has been tilted.
Fields tiltForward :: a The amount of forward tilt, from -1 to +1. tiltClockwise :: a The amount of clockwise twist, from -1 to +1. tiltRightward :: a 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

Functor SpaceNavigatorInput Source
Eq a => Eq (SpaceNavigatorInput a) Source
Read a => Read (SpaceNavigatorInput a) Source
Show a => Show (SpaceNavigatorInput a) Source

data Button Source

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

Enum Button Source
Eq Button Source
Read Button Source
Show Button Source

data ButtonAction Source

Pressing and releasing actions on a SpaceNavigator 3D mouse.

Constructors

ButtonPress	The button has been pressed.
ButtonRelease	The button has been released.

Instances

Enum ButtonAction Source
Eq ButtonAction Source
Read ButtonAction Source
Show ButtonAction Source

type SpaceNavigatorCallback a = SpaceNavigatorInput a -> IO () Source

A callback for input from the SpaceNavigator 3D mouse.

spaceNavigatorCallback :: forall a. Fractional a => SettableStateVar (Maybe (SpaceNavigatorCallback a)) Source

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

Quantization

quantize Source

Arguments

:: RealFloat a
=> (a, a)	The thresholds for pushing and titling, respectively, between 0 and +1.
-> SpaceNavigatorCallback a	The callback for the mouse.
-> SpaceNavigatorCallback a	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 :: RealFloat a => (a, a) Source

A default quantization for the SpaceNavigator 3D mouse.

Tracking

data Track a Source

Tracking information for a SpaceNavigator 3D mouse.

Constructors

Track

Fields

trackMode :: TrackMode: The tracking mode.
trackPosition :: Vector3 a: The coordinates for the position.
trackOrientation :: Vector3 a: 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

Functor Track Source
Eq a => Eq (Track a) Source
Read a => Read (Track a) Source
Show a => Show (Track a) Source
RealFloat a => Binary (Track a) Source
Num a => Default (Track a) Source

data TrackMode Source

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

Enum TrackMode Source
Eq TrackMode Source
Read TrackMode Source
Show TrackMode Source
Default TrackMode Source

defaultTracking :: RealFloat a => (Vector3 a, Vector3 a) Source

Default tracking rates for the SpaceNavigator 3D mouse.

track Source

Arguments

:: Num a
=> (Vector3 a, Vector3 a)	The rates at which to push or tilt, respectively, based on the mouse input.
-> IORef (Track a)	A reference to the tracking information.
-> SpaceNavigatorCallback a	A callback for doing the tracking.

Track the movement of a SpaceNavigator 3D mouse.

doTracking Source

Arguments

:: (MatrixComponent a, Num a)
=> Track a	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' Source

Arguments

:: (MatrixComponent a, Num a)
=> IORef (Track a)	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 Source

Arguments

:: (MatrixComponent a, Num a)
=> Track a	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' Source

Arguments

:: (MatrixComponent a, Num a)
=> IORef (Track a)	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 Source

Arguments

:: (MatrixComponent a, RealFloat a)
=> Track a	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' Source

Arguments

:: (MatrixComponent a, RealFloat a)
=> IORef (Track a)	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.