26 KiB

Czysty Bezpośredni odnośnik Wina Historia

libspnav manual

About libspnav
Quick start
Libspnav 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:

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.

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 <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).

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 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.

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.

26 KiB Czysty Bezpośredni odnośnik Wina Historia

libspnav manual

Table of contents

About libspnav

Quick start

Libspnav API

Initialization and cleanup

spnav_open

spnav_close

spnav_fd

spnav_x11_open

spnav_protocol

Application requests

spnav_client_name

spnav_evmask

spnav_sensitivity

spnav_x11_window

Input events

spnav_wait_event

spnav_poll_event

spnav_remove_events

spnav_x11_event

Device information

spnav_dev_name

spnav_dev_path

spnav_dev_buttons

spnav_dev_axes

spnav_dev_usbid

spnav_dev_type

Utility functions

spnav_posrot_init

spnav_posrot_moveobj

spnav_posrot_moveview

spnav_matrix_obj

spnav_matrix_view

Configuration management

spnav_cfg_reset

spnav_cfg_restore

spnav_cfg_save

spnav_cfg_set_sens

spnav_cfg_get_sens

spnav_cfg_set_axis_sens

spnav_cfg_get_axis_sens

spnav_cfg_set_invert

spnav_cfg_get_invert

spnav_cfg_set_deadzone

spnav_cfg_get_deadzone

spnav_cfg_set_axismap

spnav_cfg_get_axismap

spnav_cfg_set_bnmap

spnav_cfg_get_bnmap

spnav_cfg_set_bnaction

spnav_cfg_get_bnaction

spnav_cfg_set_kbmap

spnav_cfg_get_kbmap

spnav_cfg_set_swapyz

spnav_cfg_get_swapyz

spnav_cfg_set_led

spnav_cfg_get_led

spnav_cfg_set_grab

spnav_cfg_get_grab

spnav_cfg_set_serial

spnav_cfg_get_serial

Magellan API

26 KiB

Czysty Bezpośredni odnośnik Wina Historia