(* Copyright (C) 1995 UNICAMP.  See notice at the end of this file.  *)

INTERFACE ScreenPlotVBT;

(*
  A VBT that displays a list of self-painting 3D items,
  with perspective transformation.
*)

IMPORT VBT, LR4; 

<* PRAGMA LL *>

TYPE 
  T <: Public;
  Public = VBT.Leaf OBJECT METHODS

      (* DISPLAY LIST UPDATE METHODS *)
      <* LL.sup < VBT.mu.SELF *>
      (*
        These methods may be called asynchronously 
        by the user program.  Note that they may NOT be called 
        with VBT.mu held, e.g. from within a VBT repaint 
        or mouse event method.
      *)
      
      init(): T;
      
      alive(): BOOLEAN;
        (*
          TRUE after initialization and until the underlying VBT 
          is destroyed. The methods below will will be ineffective, 
          and will return immediately, if the VBT is not alive. *)

      setItem(id: ItemId; item: Item);
        (*
          Sets item number "id" in the display list to "item" (may be NIL). *)

      setItems(start: ItemId; READONLY item: ARRAY OF Item);
        (*
          Sets items with numbers "start", "start+1", ...
          in the display list to "item[0]", "item[1]", .... *)

      getItem(id: ItemId): Item;
        (*
          Gets item number "id" from the display list.
          Will return NIL if the item has not been set, or 
          if the VBT is no longer alive. *)

      setPainting(state: BOOLEAN);
        (*
          Turns painting on (TRUE) or off (FALSE).
          Useful supressing repaints while doing a batch of updates. *)
          
      forceRepaint();
        (*
          Requests a repaint of the whole drawing (but 
          does NOT wait for the painting to be finished). *)

      waitDone();
        (*
          Waits until the complete display list has been drawn onto the
          screen, or the VBT is dead or iconic. *)

      enableInput(state: BOOLEAN);
        (*
          If "state=TRUE" enables user input, if "state=FALSE" disables it
          and discards any unprocessed events.  While input events are
          disabled, keyclicks are discarded with a flash. *)
      
      waitKey(): VBT.KeySym;
        (*
          Waits until user types any key, or the VBT is not alive. 
          
          If events are enabled, and there is some keyclick in the
          buffer, clears the buffer and return imemdiately; else
          waits.
          
          If events are disabled, temporarily enables them until a
          keyclick is received. *)
          
      <* LL.sup = VBT.mu.SELF *>
      (* 
        The following methods should be called only from within the
        painting methods of "Item" objects, which are called 
        by the "painter" thread:
      *)

      dot(READONLY ctr: LR4.T; size: CARDINAL);
        (*
          Draws a dot with center "ctr", assumed to be in the "plot" coordinate
          system, [-1 _ +1]^3.  Clips, rotates, and scales according to the
          current viewing parameters. *)

      line(READONLY p, q: LR4.T; width: CARDINAL);
        (*
          Draws a line from "p" to "q", assumed to be in the "plot" coordinate
          system, [-1 _ +1]^3.  Clips, rotates, and scales according to the
          current viewing parameters. *)

    END;

TYPE
  ItemId = CARDINAL; 
    (* 
      Identifies an item in the display list, for 
      deletion purposes. *)
  
  Item = OBJECT METHODS

      paintSelf(v: T);
        (*
          Should paint the object on window "v". 
          Called with VBT.mu held. *)

    END;
    
  Items = ARRAY OF Item;

END ScreenPlotVBT.