home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 505a.lha / Gwin_v1.1 / Gwin.doc < prev    next >
Text File  |  1991-05-05  |  79KB  |  2,045 lines

  1.      15 July 1990                     GWIN            by Howard C. Anderson
  2.  
  3.  
  4.                        GWIN GRAPHICS SYSTEM - Version 1.1
  5.                 Update for MANX AZTEC C Compiler (Version 5.0b)
  6.      
  7.                           Author:  Howard C. Anderson
  8.                                1895 E. Auburn Dr.
  9.                                 Tempe, Az 85283
  10.                                  (602) 897-7425
  11.      
  12.      GWIN V1.1 (c) Copyright 1989 Howard C. Anderson  All rights reserved.
  13.      Software may be distributed for non-profit only.  This software is NOT
  14.                      shareware, i.e., don't send me money.
  15.      
  16.      
  17.      The  Amiga  is  a  great  computer  but  don't  you think the graphics
  18.      interface involves a lot of drudgery?    I  mean  it  takes  almost  a
  19.      hundred  lines  of  code to set up enough trash and trivia to draw one
  20.      straight line segment.  (Refer to "Inside the Amiga"  by  John  Thomas
  21.      Berry - the example in the "Using Intuition" chapter, "The Creation of 
  22.      a Window in a Custom Screen".) 
  23.      
  24.      If  you  encapsulate  the  low-level  routines,  you  can simplify the
  25.      interface and still provide access to most of the low-level  features.
  26.      In addition, you can eliminate the possibility of GURUs. The trade-off 
  27.      of  course  is  ease-of-use,  virtual  windowing,  automatic clipping,
  28.      greatly simplified mouse and keyboard interaction, freedom from GURUs, 
  29.      automatic menu generation,  speed  of  application  development,  etc.
  30.      versus speed  of  execution.    If  your application needs extra speed
  31.      though, you can still call the Amiga low-level routines while in GWIN. 
  32.      You at least save yourself a lot of setup time because you can get any 
  33.      of five types of Amiga screens and a  window  up  by  using  just  ONE
  34.      PROCEDURE CALL.  
  35.      
  36.      Who needs GWIN?    I  do.   I am a mathematician who's been a software
  37.      engineer for quite some time.  The first machine I worked on  was  the
  38.      Philco  2000.  It was one of the largest and most powerful machines in
  39.      existence at the time (It had 1/5 the memory of the Amiga 2000 here on 
  40.      my desk and was probably slightly faster than the Amiga  for  floating
  41.      point calculations.) Graphics on the Philco 2000 consisted exclusively 
  42.      of assembly  language  programs  to produce plots on printers.  At two
  43.      runs per day maximum for compiling - and debugging  provided  for  via
  44.      200 page  core  dumps  it was all drudgery and I loved it.  I loved it
  45.      less as time went  on  but  there  is  great  mystique,  glamour,  and
  46.      prestige  associated  with  writing  programs  that  no  one  else can
  47.      understand or debug.  Is it the desire  for  such  past  glories  that
  48.      accounts for  the  sorts  of interfaces we have these days???  Perhaps
  49.      there is not enough time to neatly package things???  Perhaps the only 
  50.      possible   flexible   software    interfaces    are    of    necessity
  51.      mind-warpers???   Maybe  everyone  but  me  has  time  to  muck around
  52.      endlessly wondering from whence the next  GURU  or  screen  shattering
  53.      misunderstanding will arise???  
  54.      
  55.      I  agree that you lose flexibility when you go up one level but you do
  56.      gain development efficiency.  The applications  I  have  in  mind  are
  57.      scientific  applications  such  as  interactive  graphing and mapping.
  58.      Several years ago, I used a system called the  Graphics  Compatibility
  59.      System (GCS)  that  was  developed by the government.  That system was
  60.      not particularly fast but it certainly made development of  scientific
  61.      graphics applications  MUCH easier and faster.  The source code of GCS
  62.  
  63.  
  64.                                       -1-
  65.  
  66.  
  67.      15 July 1990                     GWIN            by Howard C. Anderson
  68.  
  69.  
  70.      (in FORTRAN) is available through the National  Technical  Information
  71.      Center. It is a very large system.  Trying to compile it and run it on 
  72.      an  Amiga  would probably allow you to relive some of the past glories
  73.      mentioned above.  Instead,  I  designed  a  system  with  capabilities
  74.      similar  to  GCS but with additional Amiga-specific features and wrote
  75.      this simple graphics system in the  C  language.    The  result  is  a
  76.      graphics system  that  I  refer  to  as  GWIN  (Graphic WINdow).  GWIN
  77.      includes many of the virtual windowing features that were part of  the
  78.      GCS  philosophy  and  also  includes and simplifies use of many of the
  79.      strictly Amiga features such as menus and requesters.  The  underlying
  80.      architecture   of  GWIN  has  much  in  common  with  most  high-level
  81.      two-dimensional graphics  systems.    "Fundamentals   of   Interactive
  82.      Graphics  Computer  Graphics",  the classic text by Foley and Van Dam,
  83.      describes well the  sort  of  mathematical  transformations,  clipping
  84.      algorithms, etc.  that are part of the GWIN system.  
  85.      
  86.      Over  the  years  there  have been many higher level graphics systems:
  87.      PLOT10, GCS, GKS, CORE, etc.  Most of them presumably  have  been  too
  88.      massive to  adapt  for  use  on the Amiga system.  I am unaware of any
  89.      high-level graphics system that provides the range of features on  the
  90.      Amiga system that is provided by GWIN.  
  91.      
  92.      The  goal of GWIN is to allow a person to write interactive scientific
  93.      graphics applications programs in C without having to master  all  the
  94.      complexities of the Amiga graphics system.  
  95.      
  96.      Here  is  a  program  that  draws  one straight line segment in a high
  97.      resolution interlaced window using GWIN and then waits for the user to 
  98.      press the left mouse button before exiting: 
  99.      
  100.          main()
  101.          {
  102.          float x,y;
  103.             ustart("high2",0.,100.,0.,100.);
  104.             umove(20.,20.);
  105.             udraw(50.,50.);
  106.             ugrin(&x,&y);
  107.             uend();
  108.          }
  109.      
  110.      Ahhhh... Isn't that better???  
  111.      
  112.      Other examples are provided in the GWIN EXAMPLES directory.  
  113.      
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                                       -2-
  131.  
  132.  
  133.      15 July 1990                     GWIN            by Howard C. Anderson
  134.  
  135.  
  136.                             GWIN THEORY OF OPERATION
  137.      
  138.      
  139.      
  140.      FLOATING POINT 
  141.      
  142.      GWIN is intrinsically floating point.  Most of the  parameters  passed
  143.      to and from GWIN routines MUST BE FLOATING POINT. There are exceptions 
  144.      however  so  I  have  provided  the  type  of  each parameter with the
  145.      description of the calling sequence of each routine.  
  146.      
  147.      
  148.      
  149.      COORDINATE SYSTEM 
  150.      
  151.      Normal mathematical xy coordinate system  is  assumed  with  larger  x
  152.      values  to  the  right of the screen and larger y values at the top of
  153.      the screen.  (The machine manufacturers tend to put the small y values 
  154.      at the top of the  screen  because  that  is  where  the  raster  scan
  155.      starts.    This   is   an  unfortunate  accident  of  the  history  of
  156.      television.  If they had started the  raster  at  the  bottom  of  the
  157.      screen  and  gone  up  instead  of  vice-versa it would have been much
  158.      nicer.  (Surely you don't REALLY want to work in quadrant  IV  -  with
  159.      NEGATED  Y  values???) GWIN corrects for this historical, perpetuated,
  160.      accident.  
  161.      
  162.      
  163.      
  164.      STARTUP 
  165.      
  166.      Graphics operations are begun with a USTART procedure  call.    USTART
  167.      will  allow  you  to open any size window you choose on a screen whose
  168.      type you may choose.  Screen types are: 
  169.      
  170.      low1  - 320x200 pixel, low resolution, non-interlaced, 32 colors.
  171.      low2  - 320x400 pixel, low resolution, interlaced, 16 colors.
  172.      high1 - 640x200 pixel, high resolution, non-interlaced, 32 colors.
  173.      high2 - 640x400 pixel, high resolution, interlaced, 16 colors.
  174.      ham   - 320x200 pixel, hold and modify, [4096 colors].
  175.      
  176.      low1.backdrop - Same as low1 but active region fills screen.
  177.      low2.backdrop - Same as low2 but active region fills screen.
  178.      high1.backdrop - Same as high1 but active region fills screen.
  179.      high2.backdrop - Same as high2 but active region fills screen.
  180.      ham.backdrop - Same as ham but active region fills screen.
  181.      
  182.      
  183.      
  184.      ACTIVE REGION 
  185.      
  186.      When you open a screen and window with USTART, the  active  region  of
  187.      the Amiga  window is everything inside the borders.  This full area is
  188.      always thought of as running from 0.0 to 100.0 in both  the  x  and  y
  189.      directions.  
  190.      
  191.      You  may  use  UDAREA to select some subset of this area as the active
  192.      region.  UDAREA calls are always relative to the original 0.0 to 100.0 
  193.      bounds.  Drawing is always restricted to the active region by internal 
  194.  
  195.  
  196.                                       -3-
  197.  
  198.  
  199.      15 July 1990                     GWIN            by Howard C. Anderson
  200.  
  201.  
  202.      clipping routines unless you have turned internal clipping  off  using
  203.      uset("ncli").   (See  "Fundamentals of Interactive Computer Graphics",
  204.      Foley and  Van  Dam,  section  on  "Viewports"  if  you  need  further
  205.      information.) 
  206.      
  207.      
  208.      
  209.      VIRTUAL WINDOWING 
  210.      
  211.      Virtual windowing  is  automatic.    The  UWINDO command allows you to
  212.      change the size of the virtual window.  The default virtual window  is
  213.      from  0.0  to  100.0  in  the  x  direction  and 0.0 to 100.0 in the y
  214.      direction.  
  215.      
  216.      Whatever is in  the  virtual  window  is  expanded  or  contracted  as
  217.      necessary  and  mapped  onto the active region determined with UDAREA.
  218.      By changing UWINDO and redrawing, you can pan and zoom.  (Clearly,  we
  219.      are  not  talking  real-time  pan  and  zoom  here  of  course.)  (See
  220.      "Fundamentals of Interactive Computer Graphics", Foley  and  Van  Dam,
  221.      section on "Windows and Clipping" if you need further information.) 
  222.      
  223.      
  224.      
  225.      ROTATION OF COORDINATES 
  226.      
  227.      The coordinate system may be rotated through an angle theta (value 0.0 
  228.      through  360.0)  relative to any point in the virtual coordinate space
  229.      through use of the UROTATE call.  The point about which the coordinate 
  230.      space is rotated is ALWAYS with  respect  to  the  ORIGINAL  UNROTATED
  231.      COORDINATE  SYSTEM.  This  point becomes the new origin, (0,0), of the
  232.      new rotated coordinate system.  There is no  way  provided  to  rotate
  233.      Amiga text.    The  position  at  which  the text is to appear will be
  234.      rotated and the text will begin at the new position but it will  still
  235.      be horizontal like this line you are now reading.  
  236.      
  237.      
  238.      
  239.      DRAWING 
  240.      
  241.      UMOVE,  UDRAW,  UCRCLE,  URECT,  and  UPLYGN  are the primary line and
  242.      polygon drawing tools.  UMOVE moves the beam to the specified  virtual
  243.      point.   UDRAW  draws a line from the current virtual beam position to
  244.      the virtual beam position given  in  the  UDRAW  call.    Clipping  is
  245.      performed as  necessary.    URECT draws a rectangle and has some speed
  246.      advantages over UPLYGN.  UPLYGN  draws  a  polygon  of  the  specified
  247.      number  of  sides within a circumscribing circle of radius provided in
  248.      the call.  The optional "fill"  switch  set  via  a  USET  call  cause
  249.      polygons  or  rectangles  to  be  filled  when drawn and causes UMOVE,
  250.      UDRAW, UDRAW, UDRAW,... UMOVE sequences to be filled.  Setting  "nofi"
  251.      with  a USET call turns off the filling operation and closes and fills
  252.      immediately any UDRAW sequence that has not yet been closed by a UMOVE 
  253.      call.  
  254.      
  255.      
  256.      
  257.      TEXT 
  258.      
  259.      UFONT establishes the font that will be used for subsequent UPRINT and 
  260.  
  261.  
  262.                                       -4-
  263.  
  264.  
  265.      15 July 1990                     GWIN            by Howard C. Anderson
  266.  
  267.  
  268.      UPRNT1 calls.  Any font that you have on your system may be used.  The 
  269.      default is the standard Amiga default font  which  at  the  moment  is
  270.      Topaz. Its default size is selected by you with the Preferences tool.  
  271.      
  272.      UPRINT  will  print a line of text at the given location in accordance
  273.      with the USET options "inte", "real", and "text". UPRNT1 prints a line 
  274.      of text at the current beam location and allows  you  to  set  "inte",
  275.      "real", and "text" for the duration of the call.  
  276.      
  277.      
  278.      
  279.      COLOR 
  280.      
  281.      The current drawing color is established by a UPSET("colo",color) call 
  282.      where  color  is a real number between 0 and the maximum color for the
  283.      particular screen type you are using.  (GWIN does a modulus  operation
  284.      if  you  forget  and  exceed  the maximum color.) The "colo" option to
  285.      UPSET sets the A pen and the O pen so that lines, fills, and  outlines
  286.      are all  set to the designated color.  The "bcol" option to UPSET sets
  287.      the B pen so that  the  background  color  for  text  may  be  set  as
  288.      desired.  The "ccol" option to UPSET sets the color that will fill the 
  289.      screen when the UERASE screen clearing call is issued.  
  290.      
  291.      
  292.      
  293.      CLIPPING 
  294.      
  295.      Line and   polygon  clipping  are  automatic.    These  are  sometimes
  296.      suppressed if the item being drawn such as a polygon or  rectangle  is
  297.      seen to  fall  completely  inside  the  virtual  boundaries.   You may
  298.      suppress clipping for speed IF YOU ARE ABSOLUTELY CERTAIN THAT NONE OF 
  299.      THE THINGS YOU DRAW WILL FALL OUTSIDE OF THE CURRENT  VIRTUAL  WINDOW.
  300.      If  you  blow  it,  ANYTHING can happen - loss of screen synch, GURUs,
  301.      etc.  Clipping is disabled by the "ncli" option of USET.  Clipping  is
  302.      reenabled by the "clip" option of USET.  
  303.      
  304.      
  305.      
  306.      RECTANGLE INTERIOR ONLY FILL 
  307.      
  308.      If  you have a rectangle whose color you wish to change but you do not
  309.      wish to change the color of the bounding box,  use  USET("rint").  Use
  310.      USET("rext") to include the exterior bounding box if you wish.  
  311.      
  312.      
  313.      
  314.      GRAPHICS INPUT 
  315.      
  316.      UGRIN, UGRINC, UGRINL, UGRINA, and UIGRINA are provided.  
  317.      
  318.      Each  of these responds to the window close gadget by calling UEND and
  319.      exiting IMMEDIATELY. (Unless the USET option "nclo" is set for  UGRINC
  320.      and UGRINL in which case the CLOSEWINDOW event is returned to you.) 
  321.      
  322.      UGRIN  (GRaphic INput) returns the x and y location of the cursor when
  323.      the left mouse button is pressed.  
  324.      
  325.      UGRINC (GRaphic INput Character) returns the x and y location  of  the
  326.  
  327.  
  328.                                       -5-
  329.  
  330.  
  331.      15 July 1990                     GWIN            by Howard C. Anderson
  332.  
  333.  
  334.      cursor, the event type, and the keyboard character that was pressed if 
  335.      the   event   type  was  "VANILLAKEY".  Event  types  may  be  one  of
  336.      MOUSEBUTTONS,  VANILLAKEY,  CLOSEWINDOW  (only  if  you  have   called
  337.      uset("nclo")), or    REFRESHWINDOW.      If   the   event   type   was
  338.      "MOUSEBUTTONS", the key returned is an "a" if it was a left mouse  key
  339.      "down"  event  code  and  an "A" if it was a left mouse key "up" event
  340.      code.  MOUSEMOVE events are NOT monitored by UGRINC.  
  341.      
  342.      UGRINL (GRaphic INput Locator) returns the x and  y  location  of  the
  343.      cursor, the event type, and the keyboard character that was pressed if 
  344.      the event type was "VANILLAKEY". If the event type was "MOUSEBUTTONS", 
  345.      the key returned is an "a" if it was a mouse key "down" event code and 
  346.      an "A"  if  it  was a mouse key "up" event code.  MOUSEMOVE events ARE
  347.      monitored by UGRINL and you are notified immediately of the  last  one
  348.      in the current message stack.  
  349.      
  350.      UGRINA  (GRaphic INput All) is identical with UGRINL except it returns
  351.      even if no event occurred.  This allows you  to  continuously  monitor
  352.      user activity  while  in a processing loop.  You can use this to allow
  353.      the user to interrupt a process if  he  desires  (maybe  he  wants  to
  354.      change his mind regarding the 30 hour Mandelbrot drawing...) 
  355.      
  356.      UIGRINA  (Integer  GRaphic  INput All) is identical with UGRINA except
  357.      that  it  returns  integer  mouse  coordinates  with   no   coordinate
  358.      transformations performed.    This  allows  greatest  speed  since  it
  359.      bypasses all floating point  operations.    If  you  need  speed,  use
  360.      UIGRINA.  Coordinates  returned  are normal Amiga coordinates with the
  361.      origin at the top left corner of the screen.  (For  a  high-resolution
  362.      screen,  640x400 pixels, the x coordinate will be an integer from 0 to
  363.      639 and the y coordinate will be an integer from 0 to 399.) 
  364.      
  365.      
  366.      EASY AMIGA MENUS 
  367.      
  368.      With a one line call (UAMENU), you can set up  each  menu  item  of  a
  369.      hierarchical menu  structure.   GWIN creates all necessary structures,
  370.      allocates all necessary space.  You pass  a  "function  pointer"  that
  371.      tells  which  of  your  functions will be called when the user selects
  372.      that menu item.  
  373.      
  374.      
  375.      
  376.      EASY AMIGA YES/NO REQUESTER 
  377.      
  378.      With a one line  call  (UYORN),  you  can  put  up  an  AMIGA  boolean
  379.      requester containing  your  text.  When the user makes his choice, you
  380.      will receive a TRUE/FALSE return code.  
  381.      
  382.      
  383.      
  384.      EASY AMIGA STRING REQUESTER 
  385.      
  386.      With a one line call (UGETSTRING), you can  put  up  an  amiga  string
  387.      requester containing  your  prompt  text.  The requester will wait for
  388.      the user to enter a text string.  The requester exits when a  carriage
  389.      return is received.  
  390.      
  391.      
  392.  
  393.  
  394.                                       -6-
  395.  
  396.  
  397.      15 July 1990                     GWIN            by Howard C. Anderson
  398.  
  399.  
  400.      
  401.      SCREEN DUMP TO PRINTER 
  402.      
  403.      If  you have an Epson LQ series printer, you can dump the screen image
  404.      to the printer using UPRSCR.  
  405.      
  406.      
  407.      
  408.      ABORT 
  409.      
  410.      GWIN has its own  abort  handler  so  that  GWIN  can  be  aborted  if
  411.      desired.    The   abort  is  graceful,  i.e.,  all  memory  areas  are
  412.      deallocated, all libraries released,  etc.    If  you  have  your  own
  413.      cleanup  handler  (via USETCLEANUP) it will receive control after GWIN
  414.      completes its cleanup after an abort condition occurs.  
  415.      
  416.      Note: The above is true for MANX compiler.  I've accomplished this  by
  417.      overlaying  the  _abort() function described on page lib68.ap.1 of the
  418.      version 3.6 Manx compiler manual.   Within  the  Lattice  environment,
  419.      Glen  Fullmer  (my  good friend and associate who compiled the LATTICE
  420.      versions using his LATTICE  compiler)  used  the  SIGNAL  function  to
  421.      attempt to catch the "SIGINT" signal.  Neither of us is impressed with 
  422.      either compiler's abilities in this area.  
  423.      
  424.      
  425.      
  426.      USER CLEANUP HANDLER 
  427.      
  428.      The  routine USETCLEANUP allows you to pass a function pointer to GWIN
  429.      that points to your  own  cleanup  routine.    When  GWIN  exits,  for
  430.      whatever  reason,  if you specified a cleanup routine, control will be
  431.      passed to your cleanup routine after GWIN  completes  deallocation  of
  432.      its memory  allocations,  release  of  its  libraries,  etc.   In your
  433.      cleanup routine, you  may  then  release  any  storage  you  may  have
  434.      allocated, close any files, etc.  
  435.      
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.                                       -7-
  461.  
  462.  
  463.      15 July 1990                     GWIN            by Howard C. Anderson
  464.  
  465.  
  466.                                     EXAMPLES
  467.      
  468.      Examples  of the use of GWIN routines are located in the gwin/examples
  469.      directory.  Execute these examples and study their source code to  see
  470.      how to use GWIN calls.  
  471.      
  472.      The examples and a brief description of each are as follows: 
  473.      
  474.           clipdemo 
  475.           
  476.                Demonstrates setup of a GWIN clipping window within an Amiga 
  477.                window.   (Object  code  was deleted to make this all fit on
  478.                one disk.  You must recompile before running this program.) 
  479.                
  480.           
  481.           colormap2 
  482.           
  483.                Demonstrates changing the colormap.  Place cursor  inside  a
  484.                triangle,  depress left mouse button and move cursor around.
  485.                The points of the triangles correspond  to  Red,  Green  and
  486.                Blue.  Distance  from  the  center  determines how much Red,
  487.                Green or Blue.  
  488.                
  489.           
  490.           placeobject 
  491.           
  492.                Demonstrates moving  and  placing  a  rectangle  of  various
  493.                colors.  
  494.                
  495.           
  496.           
  497.           rubberbandline 
  498.           
  499.                Demonstrates a  rubberband  line.  Simple demo intended only
  500.                to illustrate how a rubberband line is generated.    (Object
  501.                code was deleted to make this all fit on one disk.  You must 
  502.                recompile before running this program.) 
  503.                
  504.           
  505.           
  506.           text 
  507.           
  508.                Demonstrates  use of font selection and various text display
  509.                options.  (Object code was deleted to make this all  fit  on
  510.                one disk.  You must recompile before running this program.) 
  511.                
  512.           
  513.           
  514.           graph 
  515.           
  516.                Accepts  a  list of numbers either from the keyboard or from
  517.                standard input.    The  numbers  are   assumed   to   be   Y
  518.                coordinates.    Integer   X  coordinates  are  automatically
  519.                assigned.  A graph is drawn.  Menu options  allow  switching
  520.                between line graph and bar graph modes.  If you place a list 
  521.                of  numbers  in  a  file  (say file1) then issue the command
  522.                "graph <file1", the numbers will be graphed.  
  523.                
  524.  
  525.  
  526.                                       -8-
  527.  
  528.  
  529.      15 July 1990                     GWIN            by Howard C. Anderson
  530.  
  531.  
  532.           
  533.           
  534.           request 
  535.           
  536.                Shows how to use a  requester  to  ask  the  user  a  yes/no
  537.                question.  
  538.                
  539.           
  540.           
  541.           screentypes 
  542.           
  543.                Demonstrates  all  10  types  of  screens supported by GWIN.
  544.                (Object code was deleted to make this all fit on  one  disk.
  545.                You must recompile before running this program.) 
  546.                
  547.           
  548.           
  549.           three-d 
  550.           
  551.                Allows construction of three-dimensional figures.  You would 
  552.                need  red/blue  glasses  to see the three-dimensional effect
  553.                however.  (Object code was deleted to make this all  fit  on
  554.                one disk.  You must recompile before running this program.) 
  555.                
  556.           
  557.           
  558.           menu 
  559.           
  560.                Demonstrates how to build and use menus in GWIN.  
  561.                
  562.           
  563.           
  564.           rubberbandbox 
  565.           
  566.                Demonstrates building boxes using a rubberband box.  
  567.                
  568.           
  569.           
  570.           spiceplot 
  571.           
  572.                For you Electrical Engineers who have access to some version 
  573.                of the "SPICE" program.  Spiceplot reads a SPICE output file 
  574.                from standard input, i.e., type: "spiceplot <spiceoutput" to 
  575.                see it  plot curves contained in the spiceoutput file.  Note
  576.                the format of the data in the spiceoutput file.    Spiceplot
  577.                is looking  for  the  lists  of node data.  Depress the left
  578.                mouse button and hold, drag, and release.  A rubberband  box
  579.                will  have appeared and the selected region will be expanded
  580.                to fill the screen.  Use the menu to restore the  curves  to
  581.                their original  scale.  As the cursor moves, the coordinates
  582.                are displayed.  
  583.                
  584.           
  585.           
  586.           geomap 
  587.           
  588.                A geographic mapping system.  Geomap asks for  latitude  and
  589.                longitude  coordinates  of  where you wish the center of the
  590.  
  591.  
  592.                                       -9-
  593.  
  594.  
  595.      15 July 1990                     GWIN            by Howard C. Anderson
  596.  
  597.  
  598.                map to be.  I used some  simple  coordinate  transformations
  599.                that allow  a lot of power without a lot of work.  Note that
  600.                the cursor reads latitude and  longitude  as  it  is  moved.
  601.                Note menu  options.    We  have  orthographic  and  Mercator
  602.                projections  available  with  oblique  Mercator  projections
  603.                thrown in  for  free.    Note  that the cursor also provides
  604.                accurate  latitude  and  longitude  data  when  an   oblique
  605.                projection is  displayed.    I  have  untransformed (back to
  606.                latitude and longitude values)  one  of  the  map  databases
  607.                contained  in the "WorldDataBank" directory on Fish disk 262
  608.                for use with geomap.  Mike Groshart and Bob Dufford are  the
  609.                authors  of WorldDataBank and are members of the Amiga Users
  610.                of the Heartland in Omaha Nebraska.  
  611.                
  612.                The "ortho2" menu option simply draws the back side  of  the
  613.                globe in blue and the front side in red.  "Ortho" only draws 
  614.                the front   side.    The  "cspec"  menu  option  illustrates
  615.                cylindrical projection.  (Object code was  deleted  to  make
  616.                this all fit on one disk.  You must recompile before running 
  617.                this program.) 
  618.                
  619.           
  620.           
  621.           speedy 
  622.           
  623.                Demonstrates how Amiga calls can be used within a screen and 
  624.                window  initiated  by  GWIN. GWIN saved all of the effort of
  625.                bringing up a special screen and window while allowing  full
  626.                use of  all standard Amiga graphics functions.  Speedy makes
  627.                use of direct Amiga graphics function calls to  provide  the
  628.                fastest possible  graphics  operations.  This means that for
  629.                special purposes, it is  possible  to  bypass  the  floating
  630.                point  world/screen  coordinate  transformations  that are a
  631.                part of normal GWIN operation.    The  function  uigrina  is
  632.                provided  to  allow  transformationless  return  of  x and y
  633.                cursor coordinates for greatest possible speed.  The slowest 
  634.                thing in "speedy" is perhaps the call to the  random  number
  635.                generator, "ran".  
  636.                
  637.      
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.                                       -10-
  659.  
  660.  
  661.      15 July 1990                     GWIN            by Howard C. Anderson
  662.  
  663.  
  664.                                    USING GWIN
  665.      
  666.      I am using the MANX C compiler.  When I began this project I foolishly 
  667.      assumed that compilers on the Amiga produced compatible object modules 
  668.      as  is  done  on  Sun, Apollo, Multics, IBM, etc., computer systems so
  669.      that they could be linked together with  object  modules  produced  by
  670.      other compilers.    Alas,  Amiga  does  not  have a standard linker so
  671.      Lattice and Manx each apparently wrote their own and defined their own 
  672.      standards so Lattice C object modules cannot be  linked  with  MANX  C
  673.      object modules.  
  674.      
  675.      I  also  did  not  expect  the  compiled objects to become obsolete so
  676.      quickly.  You cannot link MANX release 5.0 produced object files  with
  677.      MANX release  3.6 object files.  The reason for this re-release of GIN
  678.      is to provide release 5.0 compatible graphics object  files  that  you
  679.      may  use  to create GWIN applications under the release 5.0 version of
  680.      the MANX AZTEC C compiler.  
  681.      
  682.      I am still considering organizing GWIN as an "Amiga library".  
  683.      
  684.      I am very happy with release 5.0 of the MANX AZTEC C compiler.    They
  685.      have  provided  tools  to  greatly  simplify  the  creation  of "Amiga
  686.      libraries".  If I can find time, I will attempt to make GWIN an "Amiga 
  687.      library".  This is really the way to go.  
  688.      
  689.      I still have concerns  regarding  areas  such  as  transmitting  error
  690.      messages from  within  an  Amiga  library to the user.  For example if
  691.      someone blows the USTART or UDAREA parameters, how does one notify the 
  692.      developer from within the library?  (If you said GURU, you still don't 
  693.      understand what I've been trying to say about making things easier for 
  694.      the developer...   Please  read  the  previous  paragraphs  again.)  I
  695.      haven't had time yet to test what does and does not work.  
  696.      
  697.      
  698.      LATTICE NOTES 
  699.      
  700.      I have a  MANX  compiler.    I  don't  have  a Lattice compiler.  Glen
  701.      Fullmer, my good friend and associate, does have  a  Lattice  compiler
  702.      (release  5)  and graciously offered to create Lattice-compatible GWIN
  703.      object modules.  I am not a Lattice guru so  what  we'll  do  for  you
  704.      Lattice  users is list the names of the Lattice-compatible GWIN object
  705.      modules here, show a tiny bit of makefile data here and tell you  that
  706.      everything  works in a manner similar to the way the Manx versions are
  707.      used.  The Lattice-compatible GWIN object modules are: 
  708.      
  709.              gwinl.ff.o
  710.              gwinl.ffCD.o
  711.              gwinl.fiCD.o
  712.      
  713.      The ff, ffCD, and fiCD labels have the same meaning as given below  in
  714.      the  descriptions  of  the  corresponding  MANX-compatible versions of
  715.      GWIN.  
  716.      
  717.      Glen  says  he  believes  gwinl.fiCD.o  can  be  used  in   place   of
  718.      gwinl.ffCD.o.  
  719.      
  720.      The  makefile  entry used to compile the GWIN object module gwinl.ff.o
  721.      looked like this: 
  722.  
  723.  
  724.                                       -11-
  725.  
  726.  
  727.      15 July 1990                     GWIN            by Howard C. Anderson
  728.  
  729.  
  730.      
  731.       gwinl.ff.o: gwin.v1.c gwin.h 
  732.           lc -ff -cw -ogwinl.ff.o gwin.v1.c 
  733.      
  734.      
  735.      The makefile used to link gwinl.ff.o with  the  example  placeobject.c
  736.      looked like this: 
  737.      
  738.       CFLAGS = -ff -O 
  739.       LIBTYPE = ffp 
  740.       COMPILETYPE = f 
  741.      
  742.       placeobject: placeobject.o gwinl.f$(COMPILETYPE).o 
  743.            blink lib:c.o placeobject.o 
  744.                   gwinl.f$(COMPILETYPE).o 
  745.                   lib lib:lcm$(LIBTYPE).lib 
  746.                   lib:lc.lib lib:amiga.lib 
  747.      
  748.       placeobject.o: placeobject.c 
  749.            lc $(CFLAGS) placeobject.c 
  750.      
  751.      
  752.      NOTE: The  "blink" line above has been folded to fit on this page.  it
  753.      and the next three lines should all be on one line.  
  754.      
  755.      Now just one more thing...   I  have  not  been  having  a  good  time
  756.      figuring  out  what  sort  of  "wierding  way"  was  used by the Amiga
  757.      designers to handle font loading.  Nothing seems to be exactly  right.
  758.      Rather  than  put  Glen through another painful compilation process, I
  759.      have made a small change to the MANX version  that  is  not  currently
  760.      reflected in  the  Lattice version.  The MANX version always reads the
  761.      font from the disk.  This is slower but always gets exactly  what  you
  762.      ask for  with respect to size and style.  The Lattice version tries to
  763.      read the font from the system first then from the disk if  the  system
  764.      read failed.    The  read  from  the  system often is satisfied if the
  765.      resultant font is "close" to what you want.    Reading  from  disk  is
  766.      slower  and  each  time  a  font  is read from disk, memory appears to
  767.      disappear.  This memory does not reappear  after  termination  of  the
  768.      program.   A note from someone on USENET indicated that this memory is
  769.      not really "gone" however and will be recovered as soon as some memory 
  770.      allocation request asks for more than appears to  be  left.    I  have
  771.      tried this and  they  are  right.    Its  REALLY  goofy.    I've tried
  772.      "AvailFonts" - It doesn't seem to update the "system font list".  I've 
  773.      tried a lot of things but a lot of "smart" interaction is  built  into
  774.      the Amiga  font  loading  processes  apparently.  Perhaps a little too
  775.      smart.  Hopefully I will figure this out  eventually  and  provide  an
  776.      updated version some time in the future.  
  777.      
  778.      Thats it regarding Lattice. Now back to MANX.  
  779.      
  780.      
  781.      
  782.      MANX NOTES 
  783.      
  784.      To  use  the  GWIN  library,  you  must  write  a C program that calls
  785.      procedures in the GWIN library, compile it with the Manx compiler  and
  786.      link the  object module with the GWIN object module.  (The makefile in
  787.      the gwin/examples directory  shows  many  examples  of  compiling  and
  788.  
  789.  
  790.                                       -12-
  791.  
  792.  
  793.      15 July 1990                     GWIN            by Howard C. Anderson
  794.  
  795.  
  796.      linking with GWIN.) 
  797.      
  798.      Fortunately  or  unfortunately  depending  on  the degree to which you
  799.      appreciate simplification,  there  are  four  floating  point  formats
  800.      allowed  by  the  Manx  compiler,  the  "Motorola Fast Floating Point"
  801.      format, the "Amiga IEEE Double  Precision  Floating  Point  Emulation"
  802.      format,  the  Manx  IEEE  floating  point  functions,  and  the "68881
  803.      Floating Point" format.  In addition, there are "large  code  /  small
  804.      code" and  "large  data / small data" compiler options.  We could have
  805.      compiled 12 versions but we didn't.  We chose to make  three  versions
  806.      of  the  object  code,  a fast floating point, small code / small data
  807.      version, a fast floating point large code / large data version and  an
  808.      IEEE large  code / large data version.  The compiler options for these
  809.      are, respectively, "-ff", "-ff -mc md", and "-fm -mc -md".  A  version
  810.      of  GWIN  has therefore been compiled for each of these formats so you
  811.      may link the one that is compatible with your mainline program and the 
  812.      capabilities of  your  machine.    The  three  versions  of  GWIN  are
  813.      "gwin.ff.o", "gwin.ffCD.o", and "gwin.fiCD.o".  
  814.      
  815.      For  the greatest speed, you should use "gwin.ff.o" unless the size of
  816.      your data or code requires use of the  slower  "gwin.ffCD.o"  version.
  817.      Version  "gwin.fiCD.o"  should  be  used  if  you  need high precision
  818.      arithmetic.  Remember that YOUR object segments must be compiled so as 
  819.      to be compatible with the version you select.  
  820.      
  821.      There is also a potential problem with the default size  of  integers.
  822.      The  three  versions  of  GWIN  were compiled with the MANX C compiler
  823.      default which in release 5 default to long integers.  That means  that
  824.      the GWIN routines expect to link up with the "lm" and "lc" libraries.  
  825.      
  826.      So  that  you  will  not be in the dark, the GWIN object segments were
  827.      compiled with these statements: 
  828.      
  829.              cc -ff -o gwin.ff.o gwin.v2.c
  830.              cc -ff -mc -md -o gwin.ffCD.o gwin.v2.c
  831.              cc -fm -mc -md -o gwin.fiCD.o gwin.v2.c
  832.      
  833.      
  834.      Assume you have a program named "prog.c" that calls GWIN routines such 
  835.      as "ustart", "umove", etc.  Then to compile and  link  it,  you  would
  836.      execute the statements: 
  837.      
  838.              cc -ff prog.c 
  839.      
  840.      
  841.      This will  result  in an object segment called "prog.o".  To link GWIN
  842.      in with your object segment, issue the link command: 
  843.      
  844.           ln prog.o gwin.ff.o -lmf -lc 
  845.      
  846.      This will result in the executable graphics module "prog".  
  847.      
  848.      
  849.      
  850.      Similarly, to use the fast floating point format large code and  large
  851.      data version, you would compile your program with: 
  852.      
  853.           cc -fm -mc -md prog.c 
  854.  
  855.  
  856.                                       -13-
  857.  
  858.  
  859.      15 July 1990                     GWIN            by Howard C. Anderson
  860.  
  861.  
  862.      
  863.      You would link this with GWIN by using the command: 
  864.      
  865.           ln prog.o gwin.ffCD.o -lm -lc 
  866.      
  867.      
  868.      
  869.      Similarly,  to  use  the  MANX  IEEE  format,  large code / large data
  870.      version, you would compile your program with: 
  871.      
  872.           cc -fm -mc -md prog.c 
  873.      
  874.      You would link this with GWIN by using the command: 
  875.      
  876.           ln prog.o gwin.fi.o -lm -lc 
  877.      
  878.      
  879.      
  880.      Now if you wish to simplify further for day-to-day use, you  can  make
  881.      one  of  the GWIN object modules a "library" module (this is the OTHER
  882.      type of "library", like the ones in "sys:lib".) For the  "ff"  version
  883.      of GWIN this would be done by issuing the statement: 
  884.      
  885.           lb sys:Aztec/lib/gwin.lib gwin.ff.o 
  886.      
  887.      Linking your program, prog.o, would then be done with the statement: 
  888.      
  889.           ln prog.o -lgwin -lm32 -lc32 
  890.      
  891.      The  advantage  is  that  you don't have to remember where you put the
  892.      GWIN object module.  
  893.      
  894.      
  895.      
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.                                       -14-
  923.  
  924.  
  925.      15 July 1990                     GWIN            by Howard C. Anderson
  926.  
  927.  
  928.                                 PROCEDURE CALLS
  929.      
  930.      ustart(mode,xmin,xmax,ymin,ymax);
  931.      char mode[255];
  932.      float x1,x2,y1,y2;
  933.      
  934.           Starts everything.  Creates a screen  and  a  window  within  the
  935.           screen within which all graphics operations will occur.  
  936.           
  937.           Mode  is  "low1",  "low2",  "high1",  "high2", or "ham" or any of
  938.           these with a ".backdrop" appended.  
  939.           
  940.           low1  - 320x200 pixel, low resolution, non-interlaced, 32 colors.
  941.           low2  - 320x400 pixel, low resolution, interlaced, 16 colors.
  942.           high1 - 640x200 pixel, high resolution, non-interlaced, 32 colors.
  943.           high2 - 640x400 pixel, high resolution, interlaced, 16 colors.
  944.           ham   - 320x200 pixel, hold and modify, [4096 colors].
  945.           
  946.           low1.backdrop - Same as low1 but active region fills screen.
  947.           low2.backdrop - Same as low2 but active region fills screen.
  948.           high1.backdrop - Same as high1 but active region fills screen.
  949.           high2.backdrop - Same as high2 but active region fills screen.
  950.           ham.backdrop - Same as ham but active region fills screen.
  951.           
  952.           
  953.           xmin determines the window x-pixel minimum value on the screen.
  954.           xmax determines the window x-pixel maximum value on the screen.
  955.           ymin determines the window y-pixel minimum value on the screen.
  956.           ymax determines the window y-pixel maximum value on the screen.
  957.           
  958.           EXAMPLES: 
  959.           
  960.           ustart("high2",0.0,640,0.0,400.0); 
  961.           
  962.           will create an Amiga window that fills the screen.  
  963.           
  964.           
  965.           ustart("high1",0.0,320.0,0.0,100.0); 
  966.           
  967.           will create an Amiga window that fills the lower left quarter  of
  968.           the screen.  
  969.           
  970.           
  971.           ustart("high2.backdrop",0.0,640.0,0.0,400.0); 
  972.           
  973.           will create  a  Amiga  window  that  fills the entire screen.  No
  974.           borders will be shown.  You can draw on the entire screen.  
  975.           
  976.           
  977.           
  978.      
  979.      uend(); 
  980.      
  981.           Stops everything.    Call  this  when  you  are   through   doing
  982.           graphics.   UEND  closes  the  window,  the  screen, the graphics
  983.           libraries, frees storage allocated by GWIN, etc.  Be sure to call 
  984.           this routine before exiting your application program.  
  985.           
  986.  
  987.  
  988.                                       -15-
  989.  
  990.  
  991.      15 July 1990                     GWIN            by Howard C. Anderson
  992.  
  993.  
  994.           
  995.           
  996.      
  997.      udarea(xmin,xmax,ymin,ymax);
  998.      float xmin,xmax,ymin,ymax;
  999.      
  1000.           Default active region boundaries if UWINDO is  not  called:  Full
  1001.           active window region selected by USTART.  
  1002.           
  1003.           Determines the  active  region  of  the full display region.  The
  1004.           minimum and maximum values are expressed as percents of the x and 
  1005.           y full screen limits.  UDAREA may be called  at  any  time  after
  1006.           USTART  and  may  be  used  to  define the active sub-area of the
  1007.           screen.  All input values to this procedure must be in the  range
  1008.           [0.0,100.0].  The xmin value must be less than the xmax value and
  1009.           the ymin value must be less than the ymax value.  
  1010.           
  1011.           EXAMPLES: 
  1012.           
  1013.           udarea(0.0,100.0,0.0,100.0); 
  1014.           
  1015.           Allows use of the entire graphics region of the window.  
  1016.           
  1017.           udarea(10.,20.,10.,20.); 
  1018.           
  1019.           Allows use of a square sub-region of  the  full  graphics  region
  1020.           defined by USTART. All graphics operations are clipped and scaled 
  1021.           to this region unless you turned clipping off with uset("ncli").  
  1022.           
  1023.           
  1024.           
  1025.      
  1026.      uwindo(xmin,xmax,ymin,ymax);
  1027.      float xmin,xmax,ymin,ymax;
  1028.           
  1029.           Default   virtual   window   boundaries  if  UWINDO  not  called:
  1030.           [0.0,100.0] x and [0.0,100.0] y.  
  1031.           
  1032.           Determines the virtual window boundaries.  Everything inside  the
  1033.           bounds  will be mapped and plotted into the current active region
  1034.           of the screen as determined by USTART or UDAREA. Any real  values
  1035.           may be used for the values input to this procedure.  Xmin must be 
  1036.           less than  xmax  and  ymin must be less than ymax.  Calls to this
  1037.           procedure allow pan  and  zoom  operations  (not  like  real-time
  1038.           smooth pan  and  zoom  however.    You  must clear the screen and
  1039.           redraw everything to see the panned or zoomed image.) 
  1040.           
  1041.           EXAMPLES: 
  1042.           
  1043.           uwindo(0.,100.,0.,100.); 
  1044.           
  1045.           Sets the virtual window  to  [0.0,100.0]  x  and  [0.0,100.0]  y.
  1046.           Every  part  of your image that has coordinates falling into this
  1047.           square will be mapped and plotted to the active graphics region.  
  1048.           
  1049.           uwindo(-50.,150.,-50.,150.); 
  1050.           
  1051.           Backs away  or  zooms  out  from  the  previous  window  setting.
  1052.  
  1053.  
  1054.                                       -16-
  1055.  
  1056.  
  1057.      15 July 1990                     GWIN            by Howard C. Anderson
  1058.  
  1059.  
  1060.           Everything  that was drawn with the previous window setting would
  1061.           be drawn twice as small in the center of  the  screen  with  this
  1062.           window setting.  
  1063.           
  1064.           
  1065.           
  1066.      
  1067.      umove(x,y);
  1068.      float x,y;
  1069.      
  1070.           Moves  the  beam  (invisibly) to the specified virtual coordinate
  1071.           point (with respect to the virtual window set up  in  UWINDO.)  X
  1072.           and y may assume any legal floating point values.  
  1073.           
  1074.           
  1075.           
  1076.      
  1077.      udraw(x,y);
  1078.      float x,y;
  1079.      
  1080.           Draws  a  line  using  the  current  color  from the current beam
  1081.           position to the new beam position designated in the  UDRAW  call.
  1082.           Updates the  current  beam position to the new position.  X and y
  1083.           are floating point numbers and are with respect  to  the  virtual
  1084.           window set  up  in  UWINDO.    They may assume any legal floating
  1085.           point values.  The resulting line will be  clipped  as  necessary
  1086.           unless you turned clipping off with uset("ncli").  
  1087.           
  1088.           
  1089.           
  1090.      
  1091.      uwhere(&x,&y);
  1092.      float x,y;
  1093.      
  1094.           Returns  the  virtual  coordinates  of the current beam position.
  1095.           Note that this procedure uses ADDRESSES of the variables.  
  1096.           
  1097.           
  1098.           
  1099.      
  1100.      urect(x1,y1,x2,y2);
  1101.      float x1,y1,x2,y2;
  1102.      
  1103.           Draws a rectangle outline in the  current  color  whose  opposite
  1104.           corner  points  are (x1,y1) and (x2,y2). Fills the rectangle with
  1105.           the current color if the USET "fill" option is in effect.    This
  1106.           routine  is  much  faster  than calling a four-sided polygon with
  1107.           uplygn.  
  1108.           
  1109.           
  1110.           
  1111.      
  1112.      uplygn(x,y,n,r);
  1113.      float x,y,n,r;
  1114.      
  1115.           Draws a regular n-sided polygon whose circumscribing circle is of 
  1116.           radius "r" and whose center is at (x,y). Fills the polygon if the 
  1117.           USET "fill" option is in effect.  Current color  (previously  set
  1118.  
  1119.  
  1120.                                       -17-
  1121.  
  1122.  
  1123.      15 July 1990                     GWIN            by Howard C. Anderson
  1124.  
  1125.  
  1126.           by the UPSET "colo" option) is applied.  
  1127.           
  1128.           
  1129.           
  1130.      
  1131.      ucrcle(x,y,r);
  1132.      float x,y,r;
  1133.      
  1134.           Draws  a  circle  of radius "r" centered at (x,y). Uses the Amiga
  1135.           Ellipse or AreaEllipse routine  unless  the  circle  exceeds  the
  1136.           bounds of  the  viewing  area.    When this occurs, the circle is
  1137.           merely a clipped  30  sided  polygon.    If  you  need  a  higher
  1138.           resolution circle in this case, call uplygn with more sides.  
  1139.           
  1140.           
  1141.           
  1142.      
  1143.      uoutln(); 
  1144.      
  1145.           Draws  a  border around the current active graphics region in the
  1146.           current color.  If the USET "fill" option is on,  the  region  is
  1147.           filled with the current color.  
  1148.           
  1149.           
  1150.           
  1151.      
  1152.      uerase(); 
  1153.      
  1154.           Erases  the  current active graphics region as defined by UDAREA.
  1155.           The region is filled with the "ccol" or "clear  color"  that  was
  1156.           set with UPSET. (The default is black.) 
  1157.           
  1158.           
  1159.           
  1160.      
  1161.      uadjust(x,y,&xadj,&yadj);
  1162.      float x,y,xadj,yadj;
  1163.      
  1164.           This  converts  the  coordinate (x,y) to display coordinates then
  1165.           converts the display coordinates  back  to  our  current  virtual
  1166.           coordinates  and  provides  them to you as (xadj,yadj). Since the
  1167.           display coordinates are discrete and the virtual coordinates  are
  1168.           not,  there  are  times when you need to know what the mapping is
  1169.           doing with  your  coordinates.    This  allows  you  to  "adjust"
  1170.           coordinates to  the  discrete coordinate space.  An example would
  1171.           be if you wanted two lines side by side and didn't want to try to 
  1172.           calculate the  mapping  from  your  virtual  coordinates  to  the
  1173.           display's discrete  coordinates.    UADJUST can be used to figure
  1174.           out the mapping since it "adjusts" your  virtual  coordinates  to
  1175.           the  virtual  equivalent of the nearest discrete point in display
  1176.           space.  
  1177.           
  1178.           
  1179.           
  1180.      
  1181.      urotate(x,y,theta);
  1182.      float x,y,theta;
  1183.      
  1184.  
  1185.  
  1186.                                       -18-
  1187.  
  1188.  
  1189.      15 July 1990                     GWIN            by Howard C. Anderson
  1190.  
  1191.  
  1192.           Rotates the virtual coordinate  system  through  an  angle  theta
  1193.           (value  0.0  through  360.0)  relative  to the point (x,y) in the
  1194.           virtual coordinate space.  (x,y) is ALWAYS with  respect  to  the
  1195.           ORIGINAL  UNROTATED  COORDINATE  SYSTEM.  The  origin  of the new
  1196.           coordinate system (0,0) is  located  at  (x,y)  of  the  original
  1197.           unrotated coordinate  system.  There is no way provided to rotate
  1198.           Amiga text.  The position at which the text is to appear will  be
  1199.           rotated  and  the text will begin at the new position but it will
  1200.           still be horizontal like this line you are reading.  
  1201.           
  1202.           
  1203.           
  1204.      
  1205.      ugrin(&x,&y);
  1206.      float x, y;
  1207.      
  1208.           Graphic input routine for responding to MOUSEBUTTONS.  When  this
  1209.           procedure is called, your application waits for the user to press 
  1210.           the left  mouse  button.    When  he  does, UGRIN returns to your
  1211.           program with the virtual coordinates of the point selected by the 
  1212.           user.  Use this for selecting things with the mouse button.  Also 
  1213.           use this if you want the display to pause long enough for you  to
  1214.           see what you have drawn!  
  1215.           
  1216.           
  1217.           
  1218.      
  1219.      ugrinc(&x,&y,&event,&key);
  1220.      float x, y;
  1221.      long event;
  1222.      char key;
  1223.      
  1224.           Graphic   input   routine  for  responding  to  MOUSEBUTTONS  and
  1225.           VANILLAKEY.  UGRINC returns the x and y location of  the  cursor,
  1226.           the event type, and the keyboard character (KEY) that was pressed 
  1227.           if  the  event  type  was  "VANILLAKEY".  If  the  event type was
  1228.           "MOUSEBUTTONS", the KEY returned is an "a" if it was a mouse  key
  1229.           "down"  event  code  and  an "A" if it was a mouse key "up" event
  1230.           code.  MOUSEMOVE events are NOT monitored by UGRINC.  
  1231.           
  1232.           Note that  the  definition  of  the  variables  MOUSEBUTTONS  and
  1233.           VANILLAKEY     reside     in     the     Amiga    include    file
  1234.           "intuition/intuition.h" and this file should be included  if  you
  1235.           wish to  check  the  EVENT for these types.  (For what its worth,
  1236.           MOUSEBUTTONS  is  defined  as  "8",  VANILLAKEY  is  defined   as
  1237.           "0x00200000L".) 
  1238.           
  1239.           UGRINC  also  informs  you of the "WINDOWCLOSE" event if the USET
  1240.           option "nclo" is in effect.    (If  its  opposite,  "clos",  (the
  1241.           default)  is  in  effect,  the  program  closes  everything  down
  1242.           automatically and exits.) 
  1243.           
  1244.           UGRINC also informs you of "REFRESHWINDOW" events.  If  the  user
  1245.           resizes the  window, the display is destroyed.  You should redraw
  1246.           the entire display upon receiving this event.  
  1247.           
  1248.           
  1249.           
  1250.  
  1251.  
  1252.                                       -19-
  1253.  
  1254.  
  1255.      15 July 1990                     GWIN            by Howard C. Anderson
  1256.  
  1257.  
  1258.      
  1259.      ugrinl(&x,&y,&event,&key);
  1260.      float x, y;
  1261.      long event;
  1262.      char key;
  1263.      
  1264.           Same  as  UGRINC  above  except  UGRINL  also  reports  MOUSEMOVE
  1265.           (locator) events.    If  the  user  moves  the  mouse,  the (x,y)
  1266.           coordinate of the current mouse  position  in  virtual  space  is
  1267.           provided to  you.    This is useful for making running coordinate
  1268.           displays on the  screen.    (I  have  been  doing  speech  signal
  1269.           processing  and  find  it useful for displaying microseconds from
  1270.           the beginning of a segment of speech as I move the cursor  within
  1271.           the waveform.   The microsecond display updates in real-time as I
  1272.           move the cursor.) Now not EVERY MOUSEMOVE event is provided - you 
  1273.           wouldn't have time to respond to them all  -  but  the  last  one
  1274.           reported in  a series is reported to you.  It provides all of the
  1275.           ones that you could hope to use.  
  1276.           
  1277.           
  1278.           
  1279.      
  1280.      ugrina(&x,&y,&event,&key);
  1281.      float x, y;
  1282.      long event;
  1283.      char key;
  1284.      
  1285.           Same as ugrinl except that ugrina does not enter  a  wait  state.
  1286.           Ugrinc returns immediately with whatever events were generated by 
  1287.           the user  if  any.  Ugrina can be used within processing loops to
  1288.           give the user the option to abort a 5 hour Mandelbrot drawing for 
  1289.           example.  
  1290.           
  1291.           
  1292.           
  1293.      
  1294.      uigrina(&ix,&iy,&event,&key);
  1295.      int ix, iy;
  1296.      long event;
  1297.      char key;
  1298.      
  1299.           Same as ugrina except that uigrina does  not  make  a  coordinate
  1300.           transformation  of  the  returned  ix,  and  iy cursor coordinate
  1301.           data.   They  are  returned  as  integers  that  are  the  cursor
  1302.           coordinate   position  data  normally  reported  by  Amiga.  This
  1303.           increases the speed with which cursor tracking can occur.    This
  1304.           is  useful  if  you are calling Amiga graphics functions directly
  1305.           for speed.  
  1306.           
  1307.           
  1308.           
  1309.      
  1310.      ufont(name,size);
  1311.      char name[255];
  1312.      float size;
  1313.      
  1314.           Sets the current font and font size that will be used  by  UPRINT
  1315.           and UPRNT1.   FONTNAME may be the name of a font in the directory
  1316.  
  1317.  
  1318.                                       -20-
  1319.  
  1320.  
  1321.      15 July 1990                     GWIN            by Howard C. Anderson
  1322.  
  1323.  
  1324.           "sys:fonts" that you wish to use or it may be the full path  name
  1325.           of a font on any disk you have mounted.  An example of the former 
  1326.           would be  ufont("topaz",11.0).  An example of the latter would be
  1327.           ufont( "df1:SlavicFonts/cyrillic/moskva.font", 11.0 ); from  Fish
  1328.           disk 202.   You  can  use  any  font that is in Amiga form.  Many
  1329.           fonts are available on the Fish disks for example.  
  1330.           
  1331.           GWIN searches the sys:fonts directory first.   If  the  requested
  1332.           font is  not  found,  GWIN  then  searches  the  disks.    If the
  1333.           requested font is still not found, GWIN  blinks  the  screen  and
  1334.           writes  an  error message to the window in which you started your
  1335.           application.  
  1336.           
  1337.           Fonts provided by Amiga are in "sys:fonts".  Available font sizes 
  1338.           can be obtained by listing the directory of the same name as  the
  1339.           font.   For example allowable sizes for the "ruby" font are 12.0,
  1340.           15.0, and 8.0  as  can  be  seen  when  you  list  the  directory
  1341.           sys:fonts/ruby.   The  numbers that are printed are the allowable
  1342.           font sizes.  
  1343.           
  1344.           For example, the ones on my system are: 
  1345.           
  1346.           FONT                           AVAILABLE SIZES
  1347.           
  1348.           sys:fonts/curtools             16.0
  1349.           sys:fonts/frettools            10.0
  1350.           sys:fonts/ruby                 12.0, 15.0, 8.0
  1351.           sys:fonts/timetools            15.0
  1352.           sys:fonts/diamond              12.0, 20.0
  1353.           sys:fonts/garnet               16.0, 9.0
  1354.           sys:fonts/sapphire             14.0, 19.0
  1355.           sys:fonts/topaz                11.0
  1356.           sys:fonts/emerald              17.0, 20.0
  1357.           sys:fonts/opal                 12.0, 9.0
  1358.           sys:fonts/tab                  8.0
  1359.           
  1360.           
  1361.           
  1362.      
  1363.      uprint(x,y,data);
  1364.      float x,y;
  1365.      char data[255];
  1366.      
  1367.           Prints the data in  "data"  beginning  at  the  virtual  location
  1368.           (x,y).  "data"  may  be a character string or a real number.  The
  1369.           USET options "text", "real", and "inte" determine how "data" will 
  1370.           be interpreted.  If "text" is in effect, "data" is expected to be 
  1371.           a character string.  If "real" or "inte" are in effect, "data" is 
  1372.           expected to be a real number.  It will be converted to  a  string
  1373.           and  printed  as either a real number or an integer in accordance
  1374.           with whether "real" or "inte" is in effect.  
  1375.           
  1376.           
  1377.           
  1378.      
  1379.      uprnt1(option,data);
  1380.      char option[4],data[255];
  1381.      
  1382.  
  1383.  
  1384.                                       -21-
  1385.  
  1386.  
  1387.      15 July 1990                     GWIN            by Howard C. Anderson
  1388.  
  1389.  
  1390.           Same as UPRINT except it prints at the current beam  position  as
  1391.           set by  UMOVE or some other drawing operation.  OPTION is "text",
  1392.           "real", or "inte". The provided  option  is  in  effect  for  the
  1393.           duration of  the  UPRNT1  call  only.  Data must be either a text
  1394.           string or a real number.  (The "inte" option truncates  the  real
  1395.           number  and  prints  an integer.) The beam position is updated to
  1396.           the position of the end of the string that was printed.    It  is
  1397.           positioned properly for the beginning of the next string that you 
  1398.           may  wish  to  print  with UPRNT1. You can use UWHERE to find the
  1399.           virtual location of this point if you need  to  know  where  that
  1400.           point is.  
  1401.           
  1402.           
  1403.           
  1404.      
  1405.      uprscr(); 
  1406.      
  1407.           Dumps the screen image to the printer.  Works for an Epson LQ-850 
  1408.           and presumably  will  work for other similar printers.  Output is
  1409.           sent to "par:", the parallel port.  
  1410.           
  1411.           
  1412.           
  1413.      
  1414.      uzvtodconv(x,y,&xt,&yt,&ix,&iy);
  1415.      float x,y;
  1416.      float xt,yt;
  1417.      long ix,iy;
  1418.      
  1419.           Converts virtual coordinates (x,y) to screen display  coordinates
  1420.           yielding floating point (xt,yt) and fixed point (ix,iy) values.  
  1421.           
  1422.           
  1423.           
  1424.      
  1425.      uzdtovconv(ix,iy,&x,&y);
  1426.      long ix,iy;
  1427.      float x,y;
  1428.      
  1429.           Converts   screen   display   coordinates   (ix,iy)   to  virtual
  1430.           coordinates (x,y).  
  1431.           
  1432.           
  1433.           
  1434.      
  1435.      uyorn(bodytext,positivetext,negativetext,width,height);
  1436.      char bodytext[],positivetext[],negativetext[];
  1437.      float width,height;
  1438.      
  1439.           Puts up yes/no requester.  Returns true/false value depending  on
  1440.           the choice  made by the user.  Bodytext is the text of the yes or
  1441.           no question you wish to ask the user.  Positivetext is  the  text
  1442.           that   will   be  displayed  with  the  positive  selection  box.
  1443.           Negativetext is the text that will be displayed with the negative 
  1444.           selection box.  Width and height are  the  width  and  height  in
  1445.           "percentage  coordinates",  i.e.,  a width and height of 100 will
  1446.           fill the whole screen.  A width and height of 50.0 will fill  the
  1447.           upper left  quarter of the screen.  The requester is always drawn
  1448.  
  1449.  
  1450.                                       -22-
  1451.  
  1452.  
  1453.      15 July 1990                     GWIN            by Howard C. Anderson
  1454.  
  1455.  
  1456.           beginning at the upper lefthand corner of the screen so width and 
  1457.           height are measured from that point.  
  1458.           
  1459.           
  1460.           
  1461.      
  1462.      uimove(ix,iy);
  1463.      long ix,iy;
  1464.      
  1465.           If you wish to bypass floating point and know exactly  where  you
  1466.           want your  pixels  to begin, use this command.  (Or you could use
  1467.           the Amiga "Move" command because GWIN merely calls Move with  the
  1468.           coordinates you pass in.) 
  1469.           
  1470.           
  1471.           
  1472.      
  1473.      uidraw(ix,iy);
  1474.      long ix,iy;
  1475.      
  1476.           If  you know exactly where you want your pixels to fall, use this
  1477.           command.  If you get it wrong though anything can  happen.    The
  1478.           Amiga  does  not respond well to data drawn outside of the bounds
  1479.           of the screen.  It is  possible  to  overwrite  important  things
  1480.           accidentally and  cause  GURUs.    This command merely passes the
  1481.           integer data (ix,iy) to the Amiga "Draw" command.  
  1482.           
  1483.           
  1484.           
  1485.      
  1486.      uamenu(gwinmenu0,gwinmenu1,gwinmenu2,text,comchr,mutex,flags,routine);
  1487.      long gwinmenu0,gwinmenu1,gwinmenu2,mutex;
  1488.      USHORT flags;
  1489.      char comchr;
  1490.      char text[255];
  1491.      long routine();
  1492.      
  1493.           Uamenu makes creating menus easy.   The  first  three  parameters
  1494.           define the  menu that you are setting up.  Amiga menus have three
  1495.           levels.  The top level (I'm calling it level 0)  appears  in  the
  1496.           title bar  when  the  right  mouse  button is depressed.  The top
  1497.           level merely gives the NAME of the menu.  It is highlighted  when
  1498.           the mouse  is  placed  over it.  A level 0 menu cannot select any
  1499.           activity.  It is there to allow you to  select  a  level  1  menu
  1500.           item.  A level 1 menu item can either cause an action to occur or 
  1501.           cause  a  level 2 menu to appear depending upon whether a level 2
  1502.           menu is  attached.    Lets  consider  the   triplet   (gwinmenu0,
  1503.           gwinmenu1, gwinmenu2).    If  the  values  are  (1,  0, 0) we are
  1504.           referring to the first level 0 menu in the title bar.  (2, 0,  0)
  1505.           refers  to  the  second level 0 menu in the title bar, and so on.
  1506.           If the values are (3, 1, 0) we are referring to the first level 1 
  1507.           item in the third level 0 menu.  If the values are (3, 2,  4)  we
  1508.           are  referring  to  the fourth level 2 item in the second level 1
  1509.           menu in the third level zero  menu.    (Please  see  the  example
  1510.           program "testmenu.c".) 
  1511.           
  1512.           Menus items  can  be referred to in any order.  GWIN will fill in
  1513.           with "dummy" names and actions if necessary.  GWIN allocates  all
  1514.  
  1515.  
  1516.                                       -23-
  1517.  
  1518.  
  1519.      15 July 1990                     GWIN            by Howard C. Anderson
  1520.  
  1521.  
  1522.           storage necessary for the menus - and cleans up when you exit.  
  1523.           
  1524.           Text is the text that will appear in the menu bar.  
  1525.           
  1526.           Comchr is an Amiga "command character."  This is a character that 
  1527.           allows  the  menu item to be selected by depressing the character
  1528.           while holding down the right "Amiga" key.   Saves  the  user  the
  1529.           trouble  of  having to actually use the menus if he remembers the
  1530.           "command character."  If "comchr" is chosen to be '  ',  i.e.,  a
  1531.           blank,  there  will be no "command character" associated with the
  1532.           designated menu item.  A command character appears to  the  right
  1533.           of  the text within the menu item preceded by a symbol indicating
  1534.           the right Amiga key.  
  1535.           
  1536.           Mutex contains mutual exclusion bits.  These bits may be  set  to
  1537.           indicate  which  other  menu  items  on this same level should be
  1538.           deselected when this menu item is selected.  If mutex is  set  to
  1539.           0, no  mutual exclusion occurs.  For most normal menus you should
  1540.           set mutex to 0. Setting bit 0 to 1 means that the first  item  in
  1541.           the menu  list is excluded by selecting this item.  Setting bit 5
  1542.           to 1 means that the fifth item in the menu list  is  excluded  by
  1543.           selecting this item, etc.  
  1544.           
  1545.           Flags  contains  flag  bits  that provide additional control over
  1546.           menus and menu items.  If you are addressing a level  zero  menu,
  1547.           only two flag bits are active: 
  1548.           
  1549.                MENUENABLED  -  When  set  means  that the menu is ready for
  1550.                action.  When not set the menu and its items are disabled.  
  1551.                
  1552.                MIDRAWN - When set means that the menu is display.  The menu 
  1553.           is not displayed when MIDRAWN is not set.  
  1554.           
  1555.           If you are  addressing  a  level  one  or  level  two  menu,  the
  1556.           following flags have meaning: 
  1557.           
  1558.           CHECKIT  -  Places  a  check  mark in front of an item when it is
  1559.                selected.  If you use this flag, you should leave  room  for
  1560.                the check mark by having 3 or 4 leading blanks in the "text" 
  1561.                parameter.  
  1562.                
  1563.           CHECKED  -  Places a check mark in front of an item when the menu
  1564.                first comes up.  
  1565.                
  1566.           ITEMTEXT - Indicates that the  menu  item  is  text  rather  than
  1567.                graphics.   The  current  version  of GWIN allows text only.
  1568.                You must set this flag.  
  1569.                
  1570.           COMMSEQ - Indicates that there is a command  key  sequence.    If
  1571.                comchr  is set non-blank, you should set COMMSEQ if you wish
  1572.                the command key to appear in the menu bar.  
  1573.                
  1574.           ITEMENABLED - Enables menu item.  You  must  set  ITEMENABLED  in
  1575.                this version of GWIN.  
  1576.                
  1577.                One of the following three menu highlighting flags must be set: 
  1578.                
  1579.           HIGHCOMP - Complements all bits of this menu item's menu bar when 
  1580.  
  1581.  
  1582.                                       -24-
  1583.  
  1584.  
  1585.      15 July 1990                     GWIN            by Howard C. Anderson
  1586.  
  1587.  
  1588.                it is selected.  Gives a visual indication to the user.  
  1589.                
  1590.           HIGHBOX - Draws a box outside this item's select box.  
  1591.                
  1592.           HIGHNONE - Specifies no highlighting.  
  1593.                
  1594.           
  1595.           Routine  is  a  function pointer that points to the function that
  1596.           you wish control transferred to when this menu item is  selected.
  1597.           This  is  a function in your program that you design to carry out
  1598.           the activity selected by the user.  
  1599.           
  1600.           
  1601.           UAMENU EXAMPLES: 
  1602.           
  1603.           The following are examples of valid uamenu calls: 
  1604.           
  1605.         uamenu(1,0,0,"test1",' ',0,MIDRAWN|MENUENABLED,0); 
  1606.           
  1607.         uamenu(1,1,0,"test2",' ',0,MIDRAWN|ITEMTEXT|HIGHCOMP 
  1608.                   |ITEMENABLED,function110); 
  1609.           
  1610.         uamenu(1,1,1,"test3",'B',0,MIDRAWN|ITEMTEXT|HIGHCOMP 
  1611.                   |COMMSEQ|ITEMENABLED,function111); 
  1612.           
  1613.         uamenu(1,2,0," test4",'C',0,MIDRAWN|ITEMTEXT|HIGHCOMP 
  1614.                   COMMSEQ|CHECKIT|ITEMENABLED,function120); 
  1615.           
  1616.           
  1617.           
  1618.      
  1619.      usetrgb(colorindex,redvalue,greenvalue,bluevalue);
  1620.      float colorindex,redvalue,greenvalue,bluevalue;
  1621.      
  1622.           Sets the color register indirectly pointed to  by  colorindex  to
  1623.           have the  designated red, green and blue values.  See appendix to
  1624.           see  which  Amiga  color  registers  are  pointed   to   by   the
  1625.           colorindex.   The  red  green  and  blue  values are converted to
  1626.           integers and each must be in the range 0 to 15.  
  1627.           
  1628.           
  1629.           
  1630.      
  1631.      ugetrgb(colorindex,&redvalue,&greenvalue,&bluevalue);
  1632.      float colorindex;
  1633.      float redvalue,greenvalue,bluevalue;
  1634.      
  1635.           Retrieves the red, green and blue values of  the  color  register
  1636.           indirectly pointed to by colorindex.  
  1637.           
  1638.           
  1639.           
  1640.      
  1641.      ugetstring(x,y,width,prompt,text);
  1642.      float x,y,width;
  1643.      char prompt[],text[];
  1644.      
  1645.           Puts  a requester on the screen and waits for the user to type in
  1646.  
  1647.  
  1648.                                       -25-
  1649.  
  1650.  
  1651.      15 July 1990                     GWIN            by Howard C. Anderson
  1652.  
  1653.  
  1654.           a string.  X and y gives the coordinates of the upper  left  hand
  1655.           corner of  the  requester  box.    These  coordinates are virtual
  1656.           coordinates.  Width gives the width of the  requester  box  as  a
  1657.           virtual x  coordinate distance.  Prompt is a text string that you
  1658.           provide that lets the user know what sort of  data  (string)  you
  1659.           are expecting  from  him.    "Text"  should  be  declared in your
  1660.           calling program as a length 255 character array.  Prompt  may  be
  1661.           up to 255 characters.  (They probably won't all fit on the screen 
  1662.           if  you  use  them all.) The font assumed within the requester is
  1663.           "topaz.font", size 8. (It comes with the machine, I expect it  to
  1664.           be available...) 
  1665.           
  1666.           
  1667.           
  1668.      
  1669.      usetcleanup(cleanup_routine);
  1670.      long cleanup_routine();
  1671.      
  1672.           This allows you to have your own cleanup routine.  It is possible 
  1673.           for  the user to exit a GWIN-based application by clicking on the
  1674.           close window gadget.   (Unless  the  "nclo"  uset  option  is  in
  1675.           effect.) If you had done memory allocation in your application or 
  1676.           left  the  sound  on, etc, having your own cleanup routine allows
  1677.           you to clean those things up.  When the close  window  gadget  is
  1678.           selected,  GWIN  cleans  up all of its storage allocation, window
  1679.           and screen allocations, closes libraries it opened, etc.  Control 
  1680.           is then passed to your cleanup routine if you specified one via a 
  1681.           usetcleanup call.  Cleanup_routine is a function pointer to  your
  1682.           cleanup routine.    For  an example, see routines in the examples
  1683.           directory.  
  1684.           
  1685.           
  1686.           
  1687.      
  1688.      uset(option);
  1689.      char option[4];
  1690.      
  1691.           
  1692.           OPTION: 
  1693.           
  1694.           "fill"    Turns on polygon fill mode.
  1695.           
  1696.           "nofi"    Turns off polygon fill mode.  Closes and fills
  1697.                current polygon. (DEFAULT)
  1698.           
  1699.           "text"    Sets text mode for UPRINT.  UPRINT assumes input
  1700.                was a character string.  (DEFAULT)
  1701.           
  1702.           "inte"    Sets "integer" mode for UPRINT.  UPRINT assumes
  1703.                input was a floating point number that should be
  1704.                truncated and displayed as an integer.
  1705.           
  1706.           "real"    Sets "real" mode for UPRINT.  UPRINT assumes input
  1707.                was a floating point number that should be displayed
  1708.                as a floating point number.
  1709.           
  1710.           "clip"    Turns polygon and line clipping on.   (DEFAULT)
  1711.           
  1712.  
  1713.  
  1714.                                       -26-
  1715.  
  1716.  
  1717.      15 July 1990                     GWIN            by Howard C. Anderson
  1718.  
  1719.  
  1720.           "ncli"    Turns polygon and line clipping off.  Use this
  1721.                only when you are absolutely certain that your
  1722.                drawing will be confined to the active graphics
  1723.                region!
  1724.           
  1725.           "rint"    If polygon "fill" mode is on and "rint" is on,
  1726.                then only the interior of rectangles plotted
  1727.                using URECT will be filled.  Their borders will
  1728.                be unchanged.
  1729.           
  1730.           "rext"    If polygon "fill" mode is on and "rext" is on,
  1731.                then the whole polygon including the border will
  1732.                be filled with the current color when URECT is called.
  1733.           
  1734.           "clos"    Allows UGRIN, UGRINL, and UGRINC to close down
  1735.                the GWIN graphics system and exit back to the
  1736.                system if the user selects the close window
  1737.                gadget.  (DEFAULT)
  1738.           
  1739.           "nclo"    Allows UGRINL, UGRINC and UGRINA to report the
  1740.                CLOSEWINDOW event to your program.  No shutdown
  1741.                of the GWIN system results.  It is then up to
  1742.                you to issue the UEND() call.  This option allows
  1743.                you to handle the problem of freeing storage
  1744.                areas you may have allocated in your main
  1745.                program among other things.  NOTE:  UGRIN
  1746.                exits any time the CLOSEWINDOW gadget is
  1747.                selected by the user.  The "nclo" option has
  1748.                no effect on UGRIN.
  1749.           
  1750.           "comp"    Color "complement" mode.  The color with which to
  1751.                draw is selected by calling upset("colo",xx).  The
  1752.                number xx is mapped to an Amiga "color register".
  1753.                Let's say that xx maps to color register rr.
  1754.                (See appendix for GWIN color mapping information.)
  1755.                Each color register contains red/green/blue values
  1756.                that determine the color drawn when that color register
  1757.                is used.  When "comp" is in effect, instead of using
  1758.                color register rr for drawing, each pixel in the
  1759.                display bitmap that would have been drawn using rr is
  1760.                examined to see what color register generated it and
  1761.                then the complement of that register number is
  1762.                substituted for that pixel.  Each pixel that would
  1763.                have been drawn using rr changes color.  If you draw
  1764.                a line or an object once using complement mode, the
  1765.                line or object appears.  If you draw it again, it
  1766.                disappears and the screen image returns to its exact
  1767.                original state.  Complement mode is used for drawing
  1768.                rubberband lines, rubberband boxes, and placing objects.
  1769.                I have arranged the color map so that if the background
  1770.                color of the region over which you are drawing in
  1771.                complement mode is black (the default), then the
  1772.                colors drawn in complement mode will be what you expect,
  1773.                i.e., red will be red, blue will be blue, etc.
  1774.                This requires black to be assigned to color register
  1775.                zero and the current drawing color to be placed in register
  1776.                15 or 31 depending upon the number of colors allowed for
  1777.                the type of screen you have chosen.  This is why certain
  1778.  
  1779.  
  1780.                                       -27-
  1781.  
  1782.  
  1783.      15 July 1990                     GWIN            by Howard C. Anderson
  1784.  
  1785.  
  1786.                colors (such as red) are repeated in the colormap.
  1787.           
  1788.           "ncom"    Turns complement mode off.
  1789.           
  1790.           
  1791.           
  1792.      
  1793.      upset(option,value);
  1794.      char option[4];
  1795.      float value;
  1796.      
  1797.      
  1798.           
  1799.           OPTION    VALUE                   ACTION
  1800.           
  1801.           "colo"    0.0 through 31.0        Set current color for drawing.  See
  1802.                                        Appendix 1 for color map.  (Sets
  1803.                                        "A" pen and "O" pen.)
  1804.           
  1805.           "acol"    0.0 through 31.0        Set current color for A pen only.
  1806.           
  1807.           "ocol"    0.0 through 31.0        Set current color for O pen only.
  1808.           
  1809.           "bcol"    0.0 through 31.0        Set current color for background
  1810.                                        color.  Background refers to text
  1811.                                        background.
  1812.           
  1813.           "ccol"    0.0 through 31          Set current color for clearing
  1814.                                        active graphics region when UERASE
  1815.                                        is called.
  1816.           
  1817.           "fsty"    0.0 through 16.0        Set font style.  Amiga allows
  1818.                                        the following font style settings
  1819.                                        to be applied to font sets that
  1820.                                        allow such settings:
  1821.           
  1822.                                        0.0 = DEFAULT
  1823.                                        1.0 = Underlined
  1824.                                        2.0 = bold
  1825.                                        4.0 = italic
  1826.                                        8.0 = wider
  1827.           
  1828.                                        Add the values of each of the above
  1829.                                        that you wish to choose and use
  1830.                                        the result as "VALUE" when you
  1831.                                        call UPSET with the "fsty" option.
  1832.           
  1833.           
  1834.           
  1835.           
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.                                       -28-
  1847.  
  1848.  
  1849.      15 July 1990                     GWIN            by Howard C. Anderson
  1850.  
  1851.  
  1852.                                    APPENDIX 1
  1853.      
  1854.      
  1855.             GLOBAL VARIABLES AND CONSTANTS IN GWIN MODULE ACCESSIBLE
  1856.                       FROM PROGRAMS WHICH LINK WITH GWIN:
  1857.      
  1858.      #define SCR_MAX 2
  1859.      #define WIN_MAX 50
  1860.      #define MAXVECTORS 1000
  1861.      
  1862.      struct RastPort *rport1;
  1863.      struct Window *win[WIN_MAX];
  1864.      struct Screen *scr[SCR_MAX];
  1865.      
  1866.      struct GfxBase *GfxBase;
  1867.      struct IntuitionBase *IntuitionBase;
  1868.      struct DiskfontBase *DiskfontBase;
  1869.      
  1870.      Rport1 is the raster port pointer that you would  use  if  you  issued
  1871.      your own  Amiga  graphics  routine  call.  It is possible while in the
  1872.      GWIN system to call Amiga graphics routines.  You must then of  course
  1873.      insure  that your graphics figures do not exceed the established pixel
  1874.      boundaries.  You should not find it necessary to make such  calls  and
  1875.      they  are discouraged generally - but if you need to, want to, and are
  1876.      willing to assume the GURU risks, feel free.  
  1877.      
  1878.      Win[0] is the pointer to the window that GWIN  is  using.    (Multiple
  1879.      windows are  not  allowed  within  GWIN  at  present.   You could open
  1880.      another window  of  your  own  for  your  own  purposes  using  Scr[0]
  1881.      presumably  -  at  your risk.) It is available for use if you need it.
  1882.      Hopefully you won't.  Don't close the window  yourself  in  any  case.
  1883.      GWIN  closes everything and releases all allocated space when you call
  1884.      UEND() or when you select the close gadget.  
  1885.      
  1886.      Scr[0] is the pointer to the screen that GWIN  is  using.    (Multiple
  1887.      screens  are  not  allowed at present.) It is available for use if you
  1888.      need it.  Hopefully you won't.  Don't close the screen yourself in any 
  1889.      case.  GWIN closes everything it opened  and  releases  all  space  it
  1890.      allocated when you call UEND().  
  1891.      
  1892.      The MAX_VECTOR variable refers to the maximum number of sides that can 
  1893.      be handled by  uplygn.    You  will NOT need a 1000 sided polygon.  It
  1894.      will merely look like a VERY slowly  drawn  circle  and  a  100  sided
  1895.      polygon is  a  nearly  perfect  approximation.  You could also bump up
  1896.      against this limit if you do too many UDRAWS in a row without doing  a
  1897.      UMOVE while in fill mode.  
  1898.      
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.                                       -29-
  1913.  
  1914.  
  1915.      15 July 1990                     GWIN            by Howard C. Anderson
  1916.  
  1917.  
  1918.                             COLOR TRANSLATION TABLE.
  1919.      
  1920.      Use these values for color_value in upset("colo",color_value) calls to 
  1921.      obtain the corresponding color.  
  1922.      
  1923.      black = 0.0;
  1924.      red = 1.0;
  1925.      green = 2.0;
  1926.      blue = 3.0;
  1927.      cyan = 4.0;
  1928.      yellow = 5.0;
  1929.      magenta = 6.0;
  1930.      white = 7.0;
  1931.      darkred = 8.0;
  1932.      darkgreen = 9.0;
  1933.      darkblue = 10.0;
  1934.      orange = 11.0;
  1935.      lime = 12.0;
  1936.      forestgreen = 13.0;
  1937.      aqua = 14.0;
  1938.      red2 = 15.0;
  1939.      violet = 16.0;
  1940.      brickred = 17.0;
  1941.      grey = 18.0;
  1942.      goldorange = 19.0;
  1943.      skyblue = 20.0;
  1944.      redorange = 21.0;
  1945.      brown = 22.0;
  1946.      pink = 23.0;
  1947.      purple = 24.0;
  1948.      tann = 25.0;
  1949.      bluegreen = 26.0;
  1950.      darkbrown = 27.0;
  1951.      lightaqua = 28.0;
  1952.      cadyellow = 29.0;
  1953.      white2 = 30.0;
  1954.      red3 = 31.0;
  1955.      
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.                                       -30-
  1979.  
  1980.  
  1981.      15 July 1990                     GWIN            by Howard C. Anderson
  1982.  
  1983.  
  1984.                    ACTUAL COLOR REGISTER ASSIGNMENTS IN GWIN
  1985.      
  1986.      Normally you     would't     use     these.        You    would    use
  1987.      upset("colo",(float)color_number) where color_number is given  in  the
  1988.      color translation table above.  The "actual color register" numbers in 
  1989.      this  table  would  be  used  only  if  you  wished  to  directly call
  1990.      SetAPen(rport1,number)  or  other   similar   Amiga   call   directly.
  1991.      (Allowable but discouraged.) 
  1992.      
  1993.       black = 0;
  1994.       blue = 1;
  1995.       red = 2;
  1996.       green = 3;
  1997.       cyan = 4;
  1998.       magenta = 5;
  1999.       lime= 6;
  2000.       yellow = 7;
  2001.       aqua = 8;
  2002.       darkblue = 9;
  2003.       darkgreen = 10;
  2004.       darkred = 11;
  2005.       forestgreen = 12;
  2006.       orange = 13;
  2007.       white = 14;
  2008.       red2 = 15;
  2009.      
  2010.       violet = 16;
  2011.       brickred = 17;
  2012.       grey = 18;
  2013.       goldorange = 19;
  2014.       skyblue = 20;
  2015.       redorange = 21;
  2016.       brown = 22;
  2017.       pink = 23;
  2018.       purple = 24;
  2019.       tann = 25;
  2020.       bluegreen = 26;
  2021.       darkbrown = 27;
  2022.       lightaqua = 28;
  2023.       cadyellow = 29;
  2024.       white2 = 30;
  2025.       red3 = 31;
  2026.      
  2027.      
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.                                       -31-
  2045.