| 2 |
- |
1 |
.TH QBALL 2
|
|
|
2 |
.SH NAME
|
|
|
3 |
qball \- 3-d rotation controller
|
|
|
4 |
.SH SYNOPSIS
|
|
|
5 |
.B
|
|
|
6 |
#include <draw.h>
|
|
|
7 |
.br
|
|
|
8 |
.B
|
|
|
9 |
#include <geometry.h>
|
|
|
10 |
.PP
|
|
|
11 |
.B
|
|
|
12 |
void qball(Rectangle r, Mouse *mousep,
|
|
|
13 |
.br
|
|
|
14 |
.B
|
|
|
15 |
Quaternion *orientation,
|
|
|
16 |
.br
|
|
|
17 |
.B
|
|
|
18 |
void (*redraw)(void), Quaternion *ap)
|
|
|
19 |
.SH DESCRIPTION
|
|
|
20 |
.I Qball
|
|
|
21 |
is an interactive controller that allows arbitrary 3-space rotations to be specified with
|
|
|
22 |
the mouse. Imagine a sphere with its center at the midpoint of rectangle
|
|
|
23 |
.IR r ,
|
|
|
24 |
and diameter the smaller of
|
|
|
25 |
.IR r 's
|
|
|
26 |
dimensions. Dragging from one point on the sphere to another specifies the endpoints of a
|
|
|
27 |
great-circle arc. (Mouse points outside the sphere are projected to the nearest point
|
|
|
28 |
on the sphere.) The axis of rotation is normal to the plane of the arc, and the
|
|
|
29 |
angle of rotation is twice the angle of the arc.
|
|
|
30 |
.PP
|
|
|
31 |
Argument
|
|
|
32 |
.I mousep
|
|
|
33 |
is a pointer to the mouse event that triggered the interaction. It should
|
|
|
34 |
have some button set.
|
|
|
35 |
.I Qball
|
|
|
36 |
will read more events into
|
|
|
37 |
.IR mousep ,
|
|
|
38 |
and return when no buttons are down.
|
|
|
39 |
.PP
|
|
|
40 |
While
|
|
|
41 |
.I qball
|
|
|
42 |
is reading mouse events, it calls out to the caller-supplied routine
|
|
|
43 |
.IR redraw ,
|
|
|
44 |
which is expected to update the screen to reflect the changing orientation.
|
|
|
45 |
Argument
|
|
|
46 |
.I orientation
|
|
|
47 |
is the orientation that
|
|
|
48 |
.I redraw
|
|
|
49 |
should examine, represented as a unit Quaternion (see
|
|
|
50 |
.IR quaternion (2)).
|
|
|
51 |
The caller may set it to any orientation.
|
|
|
52 |
It will be updated before each call to
|
|
|
53 |
.I redraw
|
|
|
54 |
(and on return) by multiplying by the rotation specified with the mouse.
|
|
|
55 |
.PP
|
|
|
56 |
It is possible to restrict
|
|
|
57 |
.I qball's
|
|
|
58 |
attention to rotations about a particular axis.
|
|
|
59 |
If
|
|
|
60 |
.I ap
|
|
|
61 |
is null, the rotation is unconstrained.
|
|
|
62 |
Otherwise, the rotation will be about the same axis as
|
|
|
63 |
.IR *ap .
|
|
|
64 |
This is accomplished by projecting points on the sphere to
|
|
|
65 |
the nearest point also on the plane through the sphere's center
|
|
|
66 |
and normal to the axis.
|
|
|
67 |
.SH SOURCE
|
|
|
68 |
.B /sys/src/libgeometry/qball.c
|
|
|
69 |
.SH SEE ALSO
|
|
|
70 |
.IR quaternion (2)
|
|
|
71 |
.br
|
|
|
72 |
Ken Shoemake,
|
|
|
73 |
``Animating Rotation with Quaternion Curves'',
|
|
|
74 |
.I
|
|
|
75 |
SIGGRAPH '85 Conference Proceedings.
|