Libspnav is a C library for receiving input from 6 degrees-of-freedom (6dof) input devices, also known as spacemice, spaceballs, etc. 6dof input is very useful for fluidly manipulating objects or viewpoints in 3D space, and fundamendally comprises of relative movement (translation) across 3 axes (TX/TY/TZ), and rotation about 3 axes (RX/RY/RZ).
Libspnav is a counterpart to the free spacenav driver (spacenavd), which runs as a system daemon, and handles all the low level interfacing with the actual devices. However, it can also communicate with the proprietary 3Dconnexion driver (3dxsrv), with reduced functionality.
There are two modes of operation supported by libspnav:
It can use the native spacenav protocol, which works over UNIX domain
sockets, supports the whole feature set exposed by libspnav, but is only
compatible with spacenavd. This is used when spnav_open is called to
connect to the driver.
It can use the X11 magellan protocol, based on X ClientMessage events,
which is compatible with both spacenavd and the proprietary 3dxsrv, but
only supports a limited subset of features. Basically just receiving input
events and changing sensitivity, no queries, device information, or
configuration management. This is used when spnav_x11_open is called to
connect to the driver.
Since the 3Dconnexion driver is practically unmaintained for the last decade,
and never really worked very well to begin with (which was what led to the
development of spacenavd), and also since the magellan protocol introduces an
unnecessary dependency to the X window system, and provides very rudimentary
functionality, new applications are encouraged to use spnav_open.
Also, libspnav provides a magellan API wrapper on top of the libspnav API, which allows existing applications written for the official SDK to be transparently recompiled against libspnav and be free of the 3Dconnexion licensing conditions.
Libspnav, as of version 1.0 has been expanded, but really most applications will
only ever need to call a handful of functions to receive input events. A good
starting point is to read the heavily commented spnav.h header file, and the
simple example programs which come with libspnav, but this section will cover
the basics which most applications will need.
To use libspnav you need to include the header file <spnav.h> and link with
-lspnav.
The first thing to do, is to connect to the driver, which is done by calling
spnav_open:
if(spnav_open() == -1) {
/* failed to connect to spacenavd */
}
When it's time to stop talking to spacenavd, call spnav_close to close the
connection.
After connecting you can go straight to your event loop, or you can query some information about the device used by spacenavd:
char buf[256];
if(spnav_dev_name(buf, sizeof buf) != -1) {
printf("Device: %s\n", buf);
}
num_buttons = spnav_dev_buttons();
If you only want to receive input from libspnav, or if you have a dedicated thread for it, you can simply wait for events like so:
spnav_event sev;
while(spnav_wait_event(&sev)) {
switch(sev.type) {
case SPNAV_EVENT_MOTION:
/* translation in sev.motion.x, sev.motion.y, sev.motion.z.
* rotation in sev.motion.rx, sev.motion.ry, sev.motion.rz.
*/
break;
case SPNAV_EVENT_BUTTON:
/* 0-based button number in sev.button.bnum.
* button state in sev.button.press (non-zero means pressed).
*/
break;
}
}
Note that there is a set of helper utility functions provided by libspnav, for accumulating motion inputs into a position vector and an orientation quaternion, and for extracting a matrix from them suitable for manipulating 3D objects, or for manipulating the view to fly through a 3D scene. See the "cube" and "fly" example programs.
Alternatively an application can check for new events without blocking, by
calling spnav_poll_event. It's also worth noting that both functions work
exactly the same regardless of which protocol is in use.
Applications which need to integrate libspnav input to their main event loop,
can call spnav_fd() to retrieve the file descriptor corresponding to the
communication socket. This can be used in a regular select loop:
fd_set rdset;
int sock, count;
spnav_event sev;
FD_ZERO(&rdset);
FD_SET(sock, &rdset);
/* ... other file descriptors ... */
if(select(maxfd + 1, &rdset, 0, 0, 0) <= 0) {
return;
}
if(FD_ISSET(sock, &rdset)) {
while(spnav_poll_event(&sev)) {
/* ... handle spacenav event ... */
}
}
The "fly" example program also demonstrates how to integrate libspnav events in a select loop, which is also handling X events coming from the Xlib socket.
The level of functionality described in this section (minus the device queries),
can be achieved and works exactly the same with both protocols. The only
difference is in calling spnav_open for the native protocol, or calling
spnav_x11_open and passing your Window id for the magellan X11 protocol. To
see the differences clearly, check out the "simple" example program, and look
for the conditionally compiled blocks of code marked with #if
defined(BUILD_AF_UNIX) and #if defined(BUILD_X11).
This section will describe all the functions and structures in the libspnav API in detail.
Function prototype: int spnav_open(void)
Open connection to the driver via the native spacenav protocol (AF_UNIX socket).
The native protocol is not compatible with the proprietary 3dxsrv driver, but
provides the maximum level of functionality, and does not depend on X11 to
function. If you wish to remain compatible with 3dxsrv with a reduced feature
set, use spnav_x11_open instead.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_close(void)
Close the connection to the driver. No further events will be received.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_fd(void)
Returns the file descriptor of the socket used to communicate with the driver.
It can be used to integrate libspnav events in a standard select loop. If the
native protocol is in use, the spacenavd socket is returned. If the X11 magellan
protocol is in use, the socket used to communicate with the X server is
returned. In either case the file descriptor returned by spnav_fd can be used
to wait for events. If no connection has been established, or the connection has
been closed, -1 is returned.
Returns: file descriptor on success, -1 on failure.
Function prototype: int spnav_x11_open(Display *dpy, Window win)
Open a connection to the driver via the X11 magellan protocol. Events are
delivered to the window registered by this call. More windows can be registered
by calling spnav_x11_window.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_protocol(void)
Returns the spacenav protocol version used in the currently established connection. If there is no established connection, or if the connection is using the X11 magellan protocol, -1 is returned.
Returns: protocol version on success, -1 on failure.
Function prototype: int spnav_client_name(const char *name)
This is an optional request, which can be used to set the application name to spacenavd. Currently it's only used for logging. Only works over the spacenav protocol v1 or later.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_evmask(unsigned int mask)
Select the types of events the application is interested in receiving. Available
options, which can be or-ed together, are:
- SPNAV_EVMASK_MOTION: 6dof motion events (enabled by defualt).
- SPNAV_EVMASK_BUTTON: button press/release events (enabled by default).
- SPNAV_EVMASK_DEV: device change events (enabled by default for protocol v1 clients).
- SPNAV_EVMASK_CFG: configuration change events.
- SPNAV_EVMASK_RAWAXIS: raw device axis events (not useful for most apps).
- SPNAV_EVMASK_RAWBUTTON: raw device button events (not useful for most apps).
Event mask selection only works over the spacenav protocol v1 or later.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_sensitivity(double sens)
Sets the client sensitivity, which is used to scale all reported motion values to this application.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_x11_window(Window win)
For applications using the X11 magellan protocol (spnav_x11_open).
Register a window which will receive events by the driver.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_wait_event(spnav_event *ev)
Blocks waiting for spnav events. When an event is pending, it writes the event
through the ev pointer and returns a non-zero value. spnav_event is defined
as a union of structures, of all possible event types:
typedef union spnav_event {
int type;
struct spnav_event_motion motion;
struct spnav_event_button button;
struct spnav_event_dev dev;
struct spnav_event_cfg cfg;
struct spnav_event_axis axis;
} spnav_event;
See the heavily commented spnav.h file for details of all the different event
structures.
Returns: non-zero when it successfully received an event, 0 on failure.
Function prototype: int spnav_poll_event(spnav_event *ev)
Checks if there is a pending spnav event without blocking. If there are any
pending events, it removes one from the queue, writes it through the ev
pointer, and returns the event type. If there is no event pending, it returns 0.
See spnav_wait_event above for the definition of spnav_event.
Returns: event type if an event is pending, 0 if there are no available events.
Function prototype: int spnav_remove_events(int type)
Drops any pending events of the specified type, or all pending events if
SPNAV_EVENT_ANY is passed.
Returns: number of events removed from the queue.
Function prototype: int spnav_x11_event(const XEvent *xev, spnav_event *sev)
For applications using the X11 magellan protocol (spnav_x11_open).
Examines an X11 event to determine if it's an spnav event or not.
Returns: event type (SPNAV_EVENT_MOTION/SPNAV_EVENT_BUTTON) if it is an
spnav event, or 0 if it's not an spnav event.
The functions in this section only work over the native spacenav protocol v1 or later, and will fail if the connection is using the X11 magellan protocol, or the spacenav protocol v0 (spacenavd <= 0.8).
Function prototype: int spnav_dev_name(char *buf, int bufsz)
Retrieve a descriptive name for the currently active device used by spacenavd.
The name is written to the buffer passed as the first argument. No more than
bufsz bytes are written, including the zero terminator. The total length of
the complete device name is returned, even if it was truncated to fit in the
provided buffer. So to make sure you get the complete name you can use the
following code:
int len = spnav_dev_name(0, 0);
if(len > 0) {
char *buf = malloc(len + 1);
spnav_dev_name(buf, len + 1);
}
Returns: length of the device name, or -1 on failure.
Function protoype: int spnav_dev_path(char *buf, int bufsz)
Retrieve the path of the device file used by spacenavd to interface with the
actual device. See spnav_dev_name for a description of how retrieving strings
work in libspnav.
Returns: length of the path string, or -1 on failure.
Function prototype: int spnav_dev_buttons(void)
Returns the number of physical buttons present on the currently used device. If the query fails (due to incorrect protocol), the default value of 2 buttons is returned.
Returns: number of device buttons, or 2 (default) on failure.
Function prototype: int spnav_dev_axes(void)
Returns the number of physical device axes on the currently used device. If the query fails (due to incorrect protocol), the default value of 6 axes is returned.
Returns: number of device axes, or 6 (default) on failure.
Function prototype: int spnav_dev_usbid(unsigned int *vendor, unsigned int *product)
If the currently used device is a USB device, its USB vendor:product id is
written through the vendor and product pointers. Fails for non-USB devices,
of if no device is detected.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_dev_type(void)
Returns the device type (see SPNAV_DEV_* enumeration in spnav.h) for the
currently used device. If the device is not known, SPNAV_DEV_UNKNOWN is
returned.
Returns: device type on success, -1 on failure.
A number of helper utility functions for common tasks needed by most 3D programs using 6dof input.
Function prototype: void spnav_posrot_init(struct spnav_posrot *pr)
The spnav_posrot structure is used by a set of helper functions to accumulate
motion input from spnav motion events, and convert the result into a matrix. It
contains a position vector, and a rotation quaternion:
struct spnav_posrot {
float pos[3]; /* position vector (x, y, z) */
float rot[4]; /* orientation quaternion (x, y, z, w) w:real xyz:imaginary */
};
This function initializes the vector to 0, and the quaternion to an identity unit quaternion (1 + 0i + 0j + 0k), ready to start accumulating motion inputs.
Function prototype: void spnav_posrot_moveobj(struct spnav_posrot *pr, struct spnav_event_motion *ev)
Apply position and rotation inputs from an spnav motion event, in a way suitable
for manipulating a 3D object. Use in conjunction with spnav_matrix_obj to
later extract a model matrix from the accumulated position/rotation.
Function prototype: void spnav_posrot_moveview(struct spnav_posrot *pr, struct spnav_event_motion *ev)
Apply position and rotation inputs from an spnav motion event, in a way suitable
for manipulating the view for flying through a 3D scene. Use in conjunction with
spnav_matrix_view to later extract a view matrix from the accumulated
position/rotation.
Function prototype: void spnav_matrix_obj(float *mat, struct spnav_posrot *pr)
Construct a 4x4 homogeneous transformation matrix from the spnav_posrot
structure, suitable for use as a model/world matrix to position and orient a 3D
object. Use in conjunction with spnav_posrot_moveobj to accumulate motion
inputs.
The first argument is a pointer to an array of 16 floats, where the matrix is
written. The matrix is in the order expected by OpenGL.
Function prototype: void spnav_matrix_view(float *mat, struct spnav_posrot *pr)
Construct a 4x4 homogeneous transformation matrix from the spnav_posrot
structure, suitable for use as a view matrix for 6dof-controllef flight in 3D
space. Use in conjunction with spnav_posrot_moveview to accumulate motion
inputs.
The first argument is a pointer to an array of 16 floats, where the matrix is
written. The matrix is in the order expected by OpenGL.
The configuration API is of no use to regular libspnav applications. It's only
intended for writing configuration management tools like the spnavcfg program.
It is useful to facilitate writing better configuration management programs,
which is why these calls are part of libspnav, but it would be quite rude
towards the user for most 3D applications to modify spacenavd settings through
this interface. Please think twice before calling any of the spnav_cfg_*
functions.
The configuration functions change the active settings in the currently running
spacenavd. To make the changes persistent, they should be written back to the
spacenavd configuration file, which is done by calling spnav_cfg_save.
Finally these functions, similarly to the device queries above, only work over the native spacenav protocol v1 or later.
Function prototype: int spnav_cfg_reset(void)
Reset all settings to their default values.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_restore(void)
Re-read the spacenavd configuration file, and revert all settings to their values defined there.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_save(void)
Save all the current settings to the spacenavd configuration file. This is required to make any changes perists across spacenavd restarts.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_set_sens(float s)
Set the global sensitivity for all motion axes (default: 1.0).
Returns: 0 on success, -1 on failure.
Function prototype: float spnav_cfg_get_sens(void)
Get the global sensitivity for all motion axes.
Returns: sensitivity on success, < 0.0 on failure
Function prototype: int spnav_cfg_set_axis_sens(const float *svec)
Set the per-axis sensitivity for all 6 input axes (TX, TY, TZ, RX, RY, RZ). The function expects an array of 6 floats. The values are multiplied, so 1.0 means default sensitivity, values higher than 1 increase sensitivity, while values less than 1 decrease it.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_get_axis_sens(float *svec)
Expects an array of 6 floats, and writes the current per-axis sensitivity values for all 6 input axes there.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_set_invert(int invbits)
Expects a bitmask where bits 0 to 5 define which of the 6 input axes to invert. Bit 0 corresponds to TX, bit 1 to TY, and so on.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_get_invert(void)
Returns a bitmask where bits 0 to 5 define which of the 6 input axes are inverted. Bit 0 corresponds to TX, bit 1 to TY and so on.
Returns: invert bitmaks on success, -1 on failure.
Function prototype: int spnav_cfg_set_deadzone(int devaxis, int delta)
Sets the deadzone threshold (under which motion is considered to be noise and
discarded) for a specific device axis. Device axis numbers
range from 0 to the value returned by spnav_dev_axes-1, and are not affected
by remapping.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_get_deadzone(int devaxis)
Returns the deadzone threshold for a specific device axis. Device axis numbers
range from 0 to the value returned by spnav_dev_axes-1, and are not affected
by remapping.
Returns: deadzone on success, -1 on failure.
Function prototype: int spnav_cfg_set_axismap(int devaxis, int map)
Maps a device axis to an input axis. Both values are zero-based, device axes
range from 0 to the value returned by spnav_dev_axes-1, while input axes range
from 0 to 5 and correspond to the sequence: TX, TY, TZ, RX, RY, RZ. To unmap an
axis, you can map it to -1.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_get_axismap(int devaxis)
Returns the input axis mapping for the device axis devaxis. See
spnav_cfg_set_axismap for a description of axis numbers.
Returns: axis mapping on success, -1 on failure or if the axis in not mapped.
Function prototype: int spnav_cfg_set_bnmap(int devbn, int map)
Maps a device button to an input button. Both values range
from 0 to the value returned by spnav_dev_buttons-1. To unmap a button you can
map it to -1. Action mappings (spnav_cfg_set_kbmap) or keyboard mappings
(spnav_cfg_set_bnaction) for a given device button, override the regular
button mapping.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_get_bnmap(int devbn)
Returns the input button mapped to the device button devbn. See
spnav_cfg_set_bnmap for a description of button numbers.
Returns: button mapping on success, -1 on failure or if unmapped.
Function prototype: int spnav_cfg_set_bnaction(int devbn, int act)
Maps a device button to an action. Device button numbers range from 0 to the
value returned by spnav_dev_buttons-1. Actions are one of the following:
- SPNAV_BNACT_NONE: No action mapped, use as regular button (default).
- SPNAV_BNACT_SENS_RESET: reset sensitivity to 1.
- SPNAV_BNACT_SENS_INC: increase sensitivity.
- SPNAV_BNACT_SENS_DEC: decrease sensitivity.
- SPNAV_BNACT_DISABLE_ROT: disable rotation while held down.
- SPNAV_BNACT_DISABLE_TRANS: disable translation while held down.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_get_bnaction(int devbn)
Returns the action mapped to the device button devbn. See
spnav_cfg_set_bnaction for details.
Returns: action mapping on success, -1 on failure.
Function prototype: int spnav_cfg_set_kbmap(int devbn, int key)
Maps a device button to a keyboard key. Device button numbers range from 0 to
the value returned by spnav_dev_buttons-1. Key values are X11 KeySyms
defined in X11/keysymdef.h. You can use XStringToKeysym and
XKeysymToString to convert between a key name and a keysym if necessary.
Keyboard mappings only work spacenavd is compiled with X11 support (which is the default), and will be unreliable if spacenavd is compiled without XTEST support.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_get_kbmap(int devbn)
Returns the X11 keysym mapped to the device button devbn. See
spnav_cfg_set_kbmap for details.
Returns: keysym mapping on success, -1 on failure.
Function prototype: int spnav_cfg_set_swapyz(int swap)
Enable or disable swapping of the translation and rotation Y and Z axes.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_get_swapyz(void)
Returns: 0 if the Y-Z axes are not swapped, 1 if they are, -1 on failure.
Function prototype: int spnav_cfg_set_led(int mode)
Sets the LED mode for devices with LEDs around the puck. The mode value can be:
- SPNAV_CFG_LED_OFF
- SPNAV_CFG_LED_ON
- SPNAV_CFG_LED_AUTO
In "auto" mode, the LED is off by default, and turns on when one or more clients are connected to spacenavd.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_get_led(void)
Returns the LED mode for devices with LEDs around the puck. See
spnav_cfg_set_led for the possible modes.
Returns: LED mode on success, -1 on failure.
Function prototype: int spnav_cfg_set_grab(int grab)
Enable or disable exclusive device access. When grab is enabled, no other program can use the device. This is useful for stopping the X server for trying to use it as a regular mouse, but will interfere with programs which attempt to use 6dof devices directly, like google earth. Pass non-zero to enable the exclusive access grab setting, or 0 to disable it.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_get_grab(void)
Returns the exclusive device access grab setting. See spnav_cfg_set_grab for
details.
Returns: exclusive device grab setting on success, -1 on failure.
Function prototype: int spnav_cfg_set_serial(const char *devpath)
Set the device file path to use for opening serial 6dof devices. Serial devices cannot be detected automatically, the user needs to provide the device path explicitly. To not attempt to open a serial device, pass an empty string.
Note: for security reasons, the path set through this setting must correspond to a TTY character device, otherwise it is ignored.
Returns: 0 on success, -1 on failure.
Function prototype: int spnav_cfg_get_serial(char *buf, int bufsz)
Retrieve the currently configured serial device path. See spnav_dev_name for a
description of how to use string query functions like this.
Returns: serial device path length on success, -1 on failure.
No detailed documentation is currently available for the Magellan API wrapper.
It is however rather simple, so go ahead and browse through the
spnav_magellan.h header file if you want to know more.
New programs are discouraged from using the Magellan API wrapper. Everything that can be done with it, can also be done with the regular libspnav API; it is after all just as thin compatibility layer on top of the libspnav API.
It is not necessary to use the Magellan API to achieve compatibility with
the proprietary 3Dconnexion driver; using the libspnav API with spnav_x11_open
makes your program compatible with it.