QBALL(2)                                                 QBALL(2)

     NAME
          qball - 3-d rotation controller

     SYNOPSIS
          #include <draw.h>
          #include <geometry.h>

          void qball(Rectangle r, Mouse *mousep,
               Quaternion *orientation,
               void (*redraw)(void), Quaternion *ap)

     DESCRIPTION
          Qball is an interactive controller that allows arbitrary 3-
          space rotations to be specified with the mouse.  Imagine a
          sphere with its center at the midpoint of rectangle r, and
          diameter the smaller of r's dimensions.  Dragging from one
          point on the sphere to another specifies the endpoints of a
          great-circle arc.  (Mouse points outside the sphere are pro-
          jected to the nearest point on the sphere.)  The axis of
          rotation is normal to the plane of the arc, and the angle of
          rotation is twice the angle of the arc.

          Argument mousep is a pointer to the mouse event that trig-
          gered the interaction.  It should have some button set.
          Qball will read more events into mousep, and return when no
          buttons are down.

          While qball is reading mouse events, it calls out to the
          caller-supplied routine redraw, which is expected to update
          the screen to reflect the changing orientation.  Argument
          orientation is the orientation that redraw should examine,
          represented as a unit Quaternion (see quaternion(2)). The
          caller may set it to any orientation.  It will be updated
          before each call to redraw (and on return) by multiplying by
          the rotation specified with the mouse.

          It is possible to restrict qball's attention to rotations
          about a particular axis.  If ap is null, the rotation is
          unconstrained.  Otherwise, the rotation will be about the
          same axis as *ap. This is accomplished by projecting points
          on the sphere to the nearest point also on the plane through
          the sphere's center and normal to the axis.

     SOURCE
          /sys/src/libgeometry/qball.c

     SEE ALSO
          quaternion(2)
          Ken Shoemake, ``Animating Rotation with Quaternion Curves'',
          SIGGRAPH '85 Conference Proceedings.