                     The rubric for the GNUbik cube program.


          The  program is separated into several distinct libraries of
          routines.   Library  routines  are  called  as  required  by
          main.   The  only library which does any rendering is drw-
          Block.c .  Select.c uses  Xt  routines and a  few  glu  com-
          mands,   and  there is state parameter  maintenance and ini-
          tialisation done in main.  blocks.c  and  txfm.c  is  kept
          free of any Mesa/OpenGL reliance.  The libraries interact as 
	  follows:

          blocks.c

          The most complexity of the program   lies  in  the  blocks.c
          library.   This library provides a mechanism for maintaining
          a record of the locations and  orientations  of  the  blocks
          which comprise the cube.

          The most complex routine in the library is the create_blocks
          routine.  (This would be the constructor if we were program-
          ming objectively.)  It creates an array of matrices describ-
          ing the initial positions of the blocks,  and  also  the  an
          array  of matrices to be used to describe the transformation
          of each block from its original  position.  The  blocks  are
          created  dynamically,  since the cube dimension is chosen at
          run time.

          The centre of the cube is at location (0,0,0).   The  blocks
          are  of  dimensions  2x2x2.  This arrangement means that the
          position of a block's centre and its extremities may  always
          be   described by an integer value, regardless of whether an
          odd or even cube dimension is specified.

          get_block_transform is used to retrieve the current trans-
          formation of a given block.

          The  rotate_slice  function  performs transformations upon
          all the blocks in a particular slice  identified  for  rota-
          tion.   The  txfm.c  library is used to do this.  The txfm.c
          functions  perform basic matrix multiplication on 4x4  homo-
          geneous matrices.

          Other  routines  exist  within the blocks.c library, and are
          primarily used for diagnostic purposes.

          drwBlock.c

          The drwBlock.c file contains one main  routine,  which  uses
          Mesa/OpenGL  to  display a block on the screen.  Note that as
          far as drwBlock is concerned, the  block  is  drawn  in  its
          original  ( solved ) position.  Main transforms the model-
          view matrix by the  current  transformation  of  the  block,
          before  displaying  it.   When  the  block  is rendered, the
          colour of the outline is specified.  This is used  to  indi-
          cate a block which the user has selected to be rotated.

          select.c

          The select.c library provides a means for the user to pick a
          block using the  mouse.  Xt  callbacks  are  used  for  this
          purpose.   A  block is picked, if the mouse comes to rest on
          it.  This is  achieved  with  two  callbacks, a timer call-
          back  which is invoked at the hold off period ( the time for
          which the mouse must have ceased motion  ),  and  a  passive
          motion callback.  A flag is set in one callback, and cleared
          in the other.  Thus, if the timer callback sees a set  flag,
          then  it  knows  that the mouse has not moved since the last
          timer callback event.  The block at the current cursor posi-
          tion  is  then  determined,  using  the methods described in
          Chapter 13 of the OpenGL Programming Guide.  Having selected
          a  block  the  select.c  library,  performs  a predetermined
          action, in our case, it redisplays the image,  so  that  the
          selected block can be indicated.

          The  remaining  functions of interest, are turn_indicator,
          which displays a 3/4 circle, with an arrowhead, to  indicate
          which  way  the  next  move  will be, and the mouse callback
          function, mouse, which determines what  happens  when  the
          user presses a mouse button.


          Sources of Reference:

               Woo M., Neider J. & Davis, T., "OpenGL Programming
               Guide", Second Edition, Addison Wesley, 1997.

               Kempf R. & Frazier C., "OpenGL Reference  Manual",
               Second Edition, Addison Wesley, 1996.

               Kilgard  M. J.,  "OpenGL  Programming for the X window System",
               Addison Wesley, 1996.
