libspnav manual =============== Table of contents ----------------- - [About libspnav](#about-libspnav) - [Quick start](#quick-start) - [Libspnav API](#libspnav-api) - [Initialization and cleanup](#initialization-and-cleanup) - [Application requests](#application-requests) - [Input events](#input-events) - [Device information](#device-information) - [Utility functions](#utility-functions) - [Configuration management](#configuration-management) - [Magellan API](#magellan-api) About libspnav -------------- 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: 1. 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. 2. 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. Quick start ----------- 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 `` 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)`. Libspnav API ------------ This section will describe all the functions and structures in the libspnav API in detail. ### Initialization and cleanup #### spnav\_open 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. #### spnav\_close 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. #### spnav\_fd 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. #### spnav\_x11\_open 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. #### spnav\_protocol 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. ### Application requests #### spnav\_client\_name 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. #### spnav\_evmask 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. #### spnav\_sensitivity 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. #### spnav\_x11\_window 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. ### Input events #### spnav\_wait\_event 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. #### spnav\_poll\_event 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. #### spnav\_remove\_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. #### spnav\_x11\_event 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. ### Device information 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). #### spnav\_dev\_name 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. #### spnav\_dev\_path 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. #### spnav\_dev\_buttons 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. #### spnav\_dev\_axes 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. #### spnav\_dev\_usbid 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. #### spnav\_dev\_type 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. ### Utility functions A number of helper utility functions for common tasks needed by most 3D programs using 6dof input. #### spnav\_posrot\_init 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. #### spnav\_posrot\_moveobj 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. #### spnav\_posrot\_moveview 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. #### spnav\_matrix\_obj 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. #### spnav\_matrix\_view 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. ### Configuration management 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. #### spnav\_cfg\_reset Function prototype: `int spnav_cfg_reset(void)` Reset all settings to their default values. Returns: 0 on success, -1 on failure. #### spnav\_cfg\_restore 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. #### spnav\_cfg\_save 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. #### spnav\_cfg\_set\_sens 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. #### spnav\_cfg\_get\_sens Function prototype: `float spnav_cfg_get_sens(void)` Get the global sensitivity for all motion axes. Returns: sensitivity on success, < 0.0 on failure #### spnav\_cfg\_set\_axis\_sens 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. #### spnav\_cfg\_get\_axis\_sens 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. #### spnav\_cfg\_set\_invert 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. #### spnav\_cfg\_get\_invert 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. #### spnav\_cfg\_set\_deadzone 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. #### spnav\_cfg\_get\_deadzone 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. #### spnav\_cfg\_set\_axismap 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. #### spnav\_cfg\_get\_axismap 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. #### spnav\_cfg\_set\_bnmap 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. #### spnav\_cfg\_get\_bnmap 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. #### spnav\_cfg\_set\_bnaction 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. #### spnav\_cfg\_get\_bnaction 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. #### spnav\_cfg\_set\_kbmap 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 `KeySym`s 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. #### spnav\_cfg\_get\_kbmap 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. #### spnav\_cfg\_set\_swapyz 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. #### spnav\_cfg\_get\_swapyz 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. #### spnav\_cfg\_set\_led 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. #### spnav\_cfg\_get\_led 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. #### spnav\_cfg\_set\_grab 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. #### spnav\_cfg\_get\_grab 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. #### spnav\_cfg\_set\_serial 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. #### spnav\_cfg\_get\_serial 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. Magellan API ------------ 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.