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