Skip to content

Commit 7a6371e

Browse files
jtsiombjtsiomb
committed
updated readme, added documentation links
1 parent 6693918 commit 7a6371e

6 files changed

Lines changed: 225 additions & 64 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ examples/fly/fly
1111
examples/simple/simple_af_unix
1212
examples/simple/simple_x11
1313
spnav.pc
14+
doc/manual.html

‎README.md‎

Lines changed: 48 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,30 +3,65 @@ libspnav
33

44
About
55
-----
6+
Libspnav is a C library for receiving input from 6 degrees-of-freedom (6dof)
7+
input devices, also known as spacemice, spaceballs, etc. 6dof input is very
8+
useful for fluidly manipulating objects or viewpoints in 3D space, and
9+
fundamendally comprises of relative movement (translation) across 3 axes
10+
(TX/TY/TZ), and rotation about 3 axes (RX/RY/RZ).
611

7-
The libspnav library is provided as a replacement of the magellan library. It
8-
provides a cleaner, and more orthogonal interface. libspnav supports both the
9-
original X11 protocol for communicating with the driver, and the new
10-
alternative non-X protocol. Programs that choose to use the X11 protocol, are
11-
automatically compatible with either the free spacenavd driver or the official
12-
3dxserv, as if they were using the magellan SDK.
12+
Libspnav is a counterpart to the free spacenav driver (spacenavd), which runs as
13+
a system daemon, and handles all the low level interfacing with the actual
14+
devices. However, it can also communicate with the proprietary 3Dconnexion
15+
driver (3dxsrv), with reduced functionality.
1316

14-
Also, libspnav provides a magellan API wrapper on top of the new API. So, any
15-
applications that were using the magellan library, can switch to libspnav
16-
without any changes. And programmers that are familiar with the magellan API
17-
can continue using it with a free library without the restrictions of the
18-
official SDK.
17+
There are two modes of operation supported by libspnav:
18+
19+
1. It can use the native spacenav protocol, which works over UNIX domain
20+
sockets, supports the whole feature set exposed by libspnav, but is only
21+
compatible with spacenavd. This is used when `spnav_open` is called to
22+
connect to the driver.
23+
24+
2. It can use the X11 magellan protocol, based on X `ClientMessage` events,
25+
which is compatible with both spacenavd and the proprietary 3dxsrv, but
26+
only supports a limited subset of features. Basically just receiving input
27+
events and changing sensitivity, no queries, device information, or
28+
configuration management. This is used when `spnav_x11_open` is called to
29+
connect to the driver.
30+
31+
Also, libspnav provides a magellan API wrapper on top of the libspnav API, which
32+
allows existing applications written for the official SDK to be transparently
33+
recompiled against libspnav and be free of the 3Dconnexion licensing conditions.
34+
35+
Documentation
36+
-------------
37+
To learn how to use libspnav in your programs, refer to the [manual](doc/manual.md),
38+
which is available in markdown format under the `doc` directory of the libspnav
39+
distribution. The manual is also available online in HTML format on the free
40+
spacenav project website: http://spacenav.sourceforge.net/man_libspnav
41+
42+
Also make sure to check out the example programs which come with libspnav under
43+
the `examples` directory.
44+
45+
![examples](http://spacenav.sourceforge.net/images/exbar.png)
1946

2047

2148
Installation
2249
------------
50+
To build and install libspnav, simply run:
51+
52+
./configure
53+
make
54+
make install
2355

24-
Configure, make, and make install as usual.
56+
Most likely the `make install` part will need to be executed as root, if you're
57+
installing libspnav system-wide, which is the common case
58+
(default prefix is: `/usr/local`).
59+
60+
Running `./configure --help` prints available build options.
2561

2662

2763
License
2864
-------
29-
3065
Copyright (C) 2007-2022 John Tsiombikas <nuclear@member.fsf.org>
3166

3267
libspnav is free software. Feel free to use, modify, and/or redistibute it

‎doc/Makefile‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.PHONY: all
2+
all: manual.html
3+
4+
%.html: %.md man_head.html
5+
cat man_head.html >$@
6+
markdown $< >>$@
7+
echo '</body></html>' >>$@

‎doc/man_head.html‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
<html>
2+
<head>
3+
<title>libspnav manual</title>
4+
<link rel="stylesheet" type="text/css" href="manual.css"/>
5+
</head>
6+
<body>

‎doc/manual.css‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
body {
2+
background-color: #222;
3+
color: #ddd;
4+
font-family: "Palatino", Georgia, serif;
5+
max-width: 56em;
6+
padding: 1em;
7+
margin: 0 auto;
8+
font-size: 110%;
9+
}
10+
11+
p {
12+
text-align: justify;
13+
}
14+
15+
h1, h2 {
16+
font-family: sans-serif;
17+
/*text-shadow: 3px 3px 3px black;*/
18+
}
19+
20+
/*img {
21+
display: block;
22+
margin: 0 auto;
23+
max-width: 100%;
24+
height: auto;
25+
}*/
26+
27+
img.fullsize {
28+
max-width: initial;
29+
}
30+
31+
img.inline {
32+
display: inline;
33+
}
34+
35+
pre, code {
36+
background-color: #191919;
37+
color: #edb;
38+
font-size: 0.95em;
39+
font-family: noto mono, droid mono, monaco, consolas, fixed;
40+
}
41+
42+
tt {
43+
color: #fff;
44+
font-size: 1.1em;
45+
}
46+
47+
code .comment { color: #9db; }
48+
code .keyword { color: #d93; }
49+
code .literal.string { color: #d88; }
50+
51+
a:link { color: #8af; }
52+
a:visited { color: #88f; }
53+
a:hover { color: #f8f; }
54+
a:active { color: #faf; }
55+
56+
57+
h1 { color: #db9; }
58+
h2 { color: #9bd; }
59+
h3 { color: #79b; }
60+
h4 { color: #bd9; }
61+
.center { text-align: center; }
62+
63+
blockquote {
64+
border-radius: 1em;
65+
padding-left: 1em;
66+
padding-right: 1em;
67+
padding-top: 0.1em;
68+
padding-bottom: 0.1em;
69+
color: #aaa;
70+
background: #111;
71+
font-style: italic;
72+
}
73+
74+
tr:nth-child(even) { background: #191919 }
75+
tr:nth-child(odd) { background: #222 }
76+
td {
77+
font-family: sans-serif;
78+
padding: 0.25em;
79+
}
80+
81+
table {
82+
margin: 0 auto;
83+
}
84+
85+
table.left {
86+
margin: 0 0;
87+
}

0 commit comments

Comments
 (0)