
     Mandel(1)             AM*GA Programmer's Manual              Mandel(1)



     1mCREDITS for Mandelbrot Generator 

          0mThis  document  describes  some  of the many features of the
          1mMandelbrot 0mgeneration program (revision #180), as written by 

               Olaf Seibert, KosmoSoft
               Beek 5                      or  Vossendijk 149
               5815 CS  Merselo                6534 TN  Nijmegen
               The Netherlands                 The Netherlands

     1mHi0m!  

               I assume that you are familiar with  the  operation  of
          the  Amiga with respect to windows, gadgets, screens and all
          other Intuition features.   (And  if  not,  just  go  RTFM).
          Therefore,   I  will  3mnot  0mlist  everything  in  menu-order.
          Rather, I will only make some comments  at  some  (most)  of
          them.  

               When  1mMandel  0mstarts  up, it opens a screen of the same
          size as your current Workbench screen, but in lo-res with  5
          planes.  
          1mNOTE0m: There seems to be a (software) graphics bug when I try
          to  open  a hires screen with a size of 672x266 (x4) pixels.
          The part below about  line  213  is  simply  not  displayed,
          though it is 'there'. Lores screens are not affected by this
          bug  (It's  gotta  be Dale's :-) I suspect the problem is in
          the system function MrgCop() (in the  graphics.library),  or
          something  related  to  that,  since other programs have the
          same problem.  (Maybe the problem will go away with  Release
          1.4 of Kickstart/Workbench.) Therefore, I forcibly make wide
          hi-res  screens a bit smaller, which may surprise you if you
          are unaware of the reason.  


     1mMOUSE OPERATIONS 
          0mWith the mouse, you can select a  rectangular  part  of  the
          picture that  you  may  later  enlarge  or reduce.  To start
          selecting, you click the mouse in  the  inner  part  of  the
          window.   Then  you  can  click  two opposite corners of the
          desired rectangle.  You may also double-click  to  select  a
          middle point of the rectangle.  Then you only have to select
          one corner.    If  you dislike the resulting flashing frame,
          you can remove it by clicking in the  sizing  gadget.    The
          area you selected in the picture will remain valid until you
          begin  reselecting  or  change the coordinates of the entire
          picture.  

               You will notice that as  soon  as  the  flashing  cross
          appears,  a  window  pops  up  with  the  coordinates of the
          current position.    Normally  it  stays  there  until   the
          flashing rectangle disappears.  In fact, it is updated every
          time the  lines  flash.    Since  this  takes some time, the
          flashing may become aestetically unpleasant.  Therefore  the
          3mRe and Im 0mwindow has a close box, which you are free to use,
          and which will speed up the flashing.  



     5 May 1989                       -1-


     Mandel(1)             AM*GA Programmer's Manual              Mandel(1)


               Sometimes  a  function  will use a point as selected by
          the mouse.  This will work  from  the  moment  the  flashing
          lines  appear until they disappear, even if you close the 3mRe
          and Im 0mwindow in the meantime.  

     1mProject0m: 1mNew 
          0mWith this submenu you can create new pictures.    They  will
          always  fill  your  window,  even  if the ratio of width and
          height is ridiculous.  The 3mratio 0mnumber that appears in  the
          coordinates  requester  should  be about 1.00. If it is much
          more  or  less  than  this,  your  picture   will   be   not
          representative of  the  1mMandelbrot  set0m.    If  it  is,  for
          example, 2.00, this means that the  height  of  the  current
          window is  twice  the  size  it normally should be.  It also
          says you to select a wider  area  from  the  complex  plane.
          This  number is updated each time you press return in one of
          the string gadgets.  You may have resized the window in  the
          meantime.  

          With  1menlarge  0myou can enlarge a part of the current picture
          as you indicated with the mouse.  

          With 1mreduce 0myou can reduce the current picture to an area as
          large as the area you indicated, which is  located  at  that
          place.   This  is  useful to see some of the surroundings of
          the current picture.  

          The 1mshift 0msubitem is somewhat special.  A value of 0.5 means
          that the new range you want to see is  shifted  0.5  of  the
          size of the current range.  

          With  1mzoom  in  0mor  1mzoom out 0myou can zoom in or out around a
          center with a certain (linear) factor.  The center point  is
          either given with the mouse (the position from the 3mRe and Im
          0mwindow)  or  otherwise  the center of the current picture is
          taken.  This value is not saved with the picture because  if
          you  just  zoomed in it is in the center of the picture, and
          if you have not yet zoomed in, it would  be  pretty  useless
          information.  

               When  you  hit  the 3mcontinue 0mgadget to start drawing, a
          separate task is started to do the real work.    This  means
          that  the main program (or task) of 1mMandel 0mruns concurrently
          with the drawing task, so you  can  continue  selecting  the
          palette, for  example.  All other things besides the drawing
          is done in the main task, so  you  cannot  use  the  palette
          while at  the  same  time  setting  the  pen  table.   Also,
          changing some parameters  (such  as  the  pen  table)  takes
          effect  immediately,  which  will change your picture in the
          middle.  

               When the picture is being  drawn,  you  must  view  the
          window  as  a  part  of the complex plane (that is the plane
          formed by the real and imaginary axes).  The formula that is
          selected in the functions menu is applied (for C the complex
          value is filled in that corresponds to the  current  pixel),
          with  Z  =  0,  and  the result is put into Z, recalculated,
          until the absolute value reaches at least a  certain  value.


     5 May 1989                       -2-


     Mandel(1)             AM*GA Programmer's Manual              Mandel(1)


          The  number  of  calculations  (or  iterations, or depth) is
          counted, and the color to be drawn is looked up in  the  pen
          table.   If  the  threshhold  value  is  not  reached in the
          maximum number of iterations, entry #0 from the pen table is
          used.  
          Ideally, there should be an infinite iteration  to  find  if
          the  value  ever  reaches infinity, but of course this is in
          reality an impossible task.  Therefore, the higher  you  set
          the  maximum  iteration  count, the better the drawn picture
          will approximate  the  'real'  Mandelbrot  set.    In  fact,
          Mandelbrot's  set  consists  of  those  complex numbers that
          3mdon't   0mreach   infinity,   even   after   infinitely   many
          iterations.   But  the  prettiest  pictures are usually from
          near the border of Mandelbrot's set.  

     1mProject0m: 1mOpen 
          0mYou can read any IFF picture (type FORM ILBM)  into  1mMandel0m.
          This  is  most useful if it is indeed a picture generated by
          1mMandel0m.  The pictures can  be  of  any  size,  and  will  be
          clipped to  the current window as appropriate.  If it is too
          small, the part of the window that is  not  covered  is  not
          changed.  This is also true with extraneous bitplanes.  
          Compatibility  with  files saved from V1.0 and V1.2 has been
          insured.  

     1mProject0m: 1mSave 
          0mIf you have saved the current picture before, you  can  save
          it again.    That  is  also possible if you only changed the
          current picture, that is, used 1mfill in0m.  

     1mProject0m: 1mSave As 
          0msaves the contents of the  Mandelbrot  Construction  Window.
          Together  with  the  picture,  some important information is
          saved, such as the  area  of  the  1mMandelbrot  set  0mthat  is
          contained  in  the  picture,  and the rainbow color palette.
          (Previously, the 3mscreen 0mwas simply  dumped  into  the  file.
          Also,  the  saved coordinate information was only correct if
          you saved your pictures borderless and moved into the  upper
          left corner.    These  misfeatures  have  been  corrected in
          V1.1.) During a save, the drawing of a picture is suspended,
          to prevent creating corrupt IFF files.  

     1mProject0m: 1mStop 
          0mIf there is currently a picture  being  drawn,  the  drawing
          stops.  Otherwise, nothing happens.  

     1mProject0m: 1mQuit 
          0mYou may quit the program this way.  This can also be done by
          clicking in  the  close  gadget.  1mMandel 0mwill ask you if you
          are sure, when you  have  not  saved  the  current  picture.
          Sometimes, when memory is tight, the requester cannot be put
          up, and  you would not be able to quit for this reason.  For
          this case, an extra keyboard command (CTRL-Q) was added that
          does NOT ask you if you are sure.  

     1mOptions0m: 1mColors 
          0mWith this submenu, you can play  with  the  colors  and  the
          coloration of pictures.  


     5 May 1989                       -3-


     Mandel(1)             AM*GA Programmer's Manual              Mandel(1)


     1mOptions0m: 1mColors0m: 1mSelect 
          0mIt  is  a way to individually select the pen number used for
          each iteration count.  Currently, the values you select this
          way are not yet saved with the picture.  You could, however,
          write a batch file to set and restore the pen table.  Beware
          that when you select one of the other ways of filling in the
          pen table, the values you have selected here are lost.  
          There is no way to undo accidental changes you made  to  the
          pen table with this command, apart from the standard Amiga-Q
          before you press Return.  

     1mOptions0m: 1mColors0m: 1mModulo 
          0mmeans  that  the pen color used for a pixel is calculated by
          taking the iteration  count  MOD  the  number  of  available
          colors.  This is the default mode of operation.  

     1mOptions0m: 1mColors0m: 1mRanges 
          0mis a  slightly  modified version of modulo.  The range width
          is user selectable.   This  is  the  number  of  consecutive
          iteration counts  that  produce the same pen number.  If you
          set this to 1 you get  excactly  the  effect  you  get  with
          modulo.   Starting from version 1.1, the pen table mode used
          to generate a picture is saved with it.  

     1mOptions0m: 1mColors0m: 1mPalette 
          0mA real color  palette,  that  you  may  recognise  from  the
          Intuition  reference  Manual  and  Thomas  Wilcox's and =RJ=
          Mical's Mandelbrot program.  I have  extended  it  somewhat,
          and put a  hidden gadget to work.  Try hitting the RGB!  You
          then meet the  1mrainbow  mode0m.    Almost  everything  in  the
          palette changes its function.  Try and have fun!  

     1mOptions0m: 1mResolution 
          0mThis  submenu enables you to change two types of resolution:
          the screen resolution, and the drawing resolution.   If  you
          select  1m10m/1m20m, 1m10m/1m30m, or 1m10m/1m40m, you may use 1mfill in 0mto fill in the
          missing pixels.  1mBorderless 0mis another  Special  Feature  of
          1mMandel0m: it can make the window borderless to gain some extra
          pixels for  your  picure.  While you can't see them, all the
          normal window gadgets are still functional in the  same  way
          they were before.  So to start selecting a window frame, you
          must 3mstill  0mclick  in  the inner part of the window.  If you
          select borderless, the picture will be preserved.  When  you
          change  display  resolution,  your  current  picture will be
          lost.  However, the size and location of your 3mwindow 0mwill be
          preserved as well as possible.  Note that this can't be done
          correctly in all cases.  Also note that  it  is  unavoidable
          that the menus and requesters change in size and position if
          you switch between Hi-res and Lo-res.  

     1mOptions0m: 1mParameters 
          0mThis  puts  up  a requester to change some parameters of the
          program.  Currently these  are  the  range  width  used  for
          3mranges 0mand  the maximum iteration count for every pixel.  It
          may not be wise to alter parameters while a picure is  being
          drawn.  
          You  can  also  select  the size of the screen to be used by
          1mMandel0m.  The coordinates are expressed in default  Workbench


     5 May 1989                       -4-


     Mandel(1)             AM*GA Programmer's Manual              Mandel(1)


          measures (hires  and non-interlaced).  The values you supply
          are advisory only; a certain  minimum  size  is  taken  into
          account.  

     1mOptions0m: 1mPriority 
          0mWith  this  submenu  you  can  select two priorities for the
          drawing task.  Normal means that the drawing  has  the  same
          priority  as  the  main  task, low means that it is lower by
          five.  This has the advantage  that  you  can  leave  1mMandel
          0mdrawing  in  the  background, without slowing down any other
          programs you would like to run.  

     1mDraw 
          0mThis menu and its submenus let you choose what exactly  gets
          drawn.   First, you can select the what calculation is to be
          performed in the 1mDraw0m: 1mFunc 0mmenu.  Then there are two  kinds
          of  plotting  functions  possible:  the first is called just
          after each iteration of the  calculation  function,  and  is
          therefore  called  1miplot0m,  and the other is called after the
          end of all iterations and is thus  called  1meplot0m.    To  the
          1meplot 0mfunction is available the reached iteration count, the
          end  value of Z, and the pixel we are currently considering.
          To the 1miplot  0mfunction  is  only  the  current  value  of  Z
          available.  

     1mDraw0m: 1mFunc 
          0mHere  you  can  select what function is used while iterating
          complex values.  Only the first function is 'real',  (ie  it
          is   1mMandelbrot0m'1ms   function0m),   the   others  may  be  less
          interesting and certainly also slower.  You  may  try  them,
          however, if  you  like.  If you want to experiment, also see
          the section on user-programmed functions  below.    Starting
          from  version  1.1,  the  function number used to generate a
          picture is saved with it.  
          Only the functions marked 1miplot  0mcall  the  iplot  function.
          Especially  the  first Mandelbrot function does not call the
          1miplot 0mfunction, just to be slightly faster.  

     1mDraw0m: 1mIplot 
          0mThis is the function that may be called during iterating the
          calculation.  There are  currently  two  possibilities:  the
          'empty'  function  that does nothing, and one that plots the
          current value of Z on its proper place in the window.   This
          is  done  by  incrementing  the color, so you can seen which
          values of Z are plotted multiple times.  

     1mDraw0m: 1mEplot 
          0mThis is the function that alwas is  called  after  iterating
          the calculation.   You can either plot the current iteration
          count (or depth), which is what you usually  would  want  to
          do.   You  can  also  plot  the  value  of Z that caused the
          iteration to terminate.  If it is  within  the  circle  with
          radius  sqrt(8),  the  iteration  was  terminated because it
          reached the maximum iteration count.  

     1mSOURCE 
          0mYou should have gotten this program together with the source
          in C. If you didn't, somebody somewhere along the path  from


     5 May 1989                       -5-


     Mandel(1)             AM*GA Programmer's Manual              Mandel(1)


          me to you illegally left it out.  The document called 1mNotice
          0mspells out the redistribution criteria, one of which is that
          the  source  must  always  be given with the program itself.
          Another is, that when you use any part of  my  source  in  a
          program  of  your  own, you must 3malso 0malways give the entire
          source of your program with it.  

     1mPRECISION 
          0mIt is important to know  that  there  are  two  versions  of
          1mMandel 0m(or  MbCS,  as  some  like to call it).  The one uses
          single-precision, Motorola Fast Floating  Point,  the  other
          uses double-precision,  IEEE  floating  point.   That is the
          only difference between these versions.  The FFP version has
          these letters in the screen title bar, and the  IEEE  Double
          Precision  shows  DP  to  indicate  that  it  is the exacter
          version of the two.  Using Fast Floating  Point  (FFP),  you
          may    notice    (at   high   magnifications)   some   large
          irregularities in lines that ought to be smooth.    Or  even
          worse,  around  the  point 2.0 with a picture hight of about
          1e-6, you go below the significance of single precision.  If
          you see such distortions, you know it is time to start using
          the double-precision version.  In  that  case,  remember  to
          have the mathieeedoubbas.library in your LIBS: directory, or
          1mMandel 0mwill abort even before it really starts up.  

     1mREVISION 
          0mThis  manual  describes 1mMandel 0mversion 1.3, revision 180. If
          your version indicates a higher  number,  (in  the  ©  About
          Mandel   menu)   it  presumably  has  been  upgraded/patched
          officially.  A lower number indicates a version that is  out
          of date.   For you source hackers: please select some random
          negative revision number, and stick to it.  This  way  there
          won't be any confusion about which version is which.  

     1mBATCH MODE 
          0mUp  until  now,  I  have been discussing some pretty obvious
          things.  But that changes right here:  now  come  the  3mbatch
          mode   0mand  for  the  really  daring,  the  3muser  programmed
          functions.  

          0mIf you invoke 1mMandel 0mwith a filename as argument, that  file
          is   read  and  executed  after  1mMandel  0mopens  its  screen.
          Alternatively, you can start a batch  file  from  the  BATCH
          menu.  

     1mBatch0m: 1mWait 
          0mIf  you  invoke  this  during execution of a batch file, its
          execution will be suspended,  just  as  if  a  batch  'wait'
          command was executed.  This also implies that the batch will
          continue as soon as a picture finishes drawing.  

     1mBatch0m: 1mContinue 
          0mThis will  simulate  finishing  a picture.  It will continue
          the batch if it was waiting due to a wait  command  or  menu
          selection.  





     5 May 1989                       -6-


     Mandel(1)             AM*GA Programmer's Manual              Mandel(1)


     1mBatch0m: 1mAbort 
          0mIf  the  batch  is  running, it is aborted after the current
          command finishes.  

          You can write a batch file with any normal text  editor  you
          like,  as  long  as  it is able to write normal ASCII files.
          The following batch commands are implemented: 

          3mdraw, fillin 

          0mstart the drawing.  The batch continues  while  the  drawing
          takes place.  

          3mwait 

          0mstops the  batch  until  the drawing finishes.  It gives the
          user a chance to operate 1mMandel 0min the mean time.    If  the
          drawing   is   aborted,   the   batch   does   not  continue
          automatically, but must be restarted with the batch continue
          menu item.  

          3mleftedge, rightedge, topedge, bottomedge <real: value> 

          0mwhich take a single  real  argument,  and  set  the  obvious
          thing.  

          3mstop 

          0mstops the drawing.  

          3mshift <real: hshift> <real: vshift> 

          0mtakes  two  real  arguments  (horizontal  and vertical shift
          amount)  and  does  the  same  thing  as  the  project-shift
          requester.  

          3mopen, saveas <string: filename> 

          0mtake  a string argument to load a picture from or to save it
          in.  There is no save command with a default file name.  The
          file name starts with the first  non-blank  character  after
          the  command  and  includes  the  entire  rest  of  the line
          (including spaces etc.), unless it is enclosed in single  or
          double quotes (which cannot be escaped).  

          3mpixelstep, numcolors, maxdepth, rangewidth, wbwidth, 
          wbheight <integer: value> 

          0mwhich take a single integral argument.  
          3mPixelstep 0mis the checkmarked menu items Normal (1), 2, 3 and
          4, but  is  not limited to those values.  Be sure not to set
          it to any value less than 1!  
          3mNumcolors 0mis not very useful; the value should be equal to 2
          to the power (the number of planes), i.e.  16,  32,  or  64.
          Maybe  interesting  to  change temporarily to affect the pen
          table calculated by the modulo or ranges commands.  
          3mMaxdepth 0mand 3mrangewidth 0mare from the  parameters  requester,
          and so are 3mwbwidth 0mand 3mwbheight.  


0m     5 May 1989                       -7-


     Mandel(1)             AM*GA Programmer's Manual              Mandel(1)


          3mborderless <integer: doit> 

          0mtakes  an  integral argument and makes the 1mMandel 0mwindow not
          borderless when the value is 0 and borderless otherwise.  

          3mhires, interlace, halfbrite <integer: doit> 

          0mwork like borderless, but only take action when the  command
          3mfixdisplay 0mis given.  

          3mraindist, rainrmax, raingmax, rainbmax <integer: value> 

          0mtake  an integral argument, and select the appearance of the
          rainbow palette.  The values must  not  exceed  the  current
          number of available color registers (i.e. 16 or 32 depending
          on screen   mode).    They  take  effect  when  the  command
          3mfixrainbow 0mis executed.  

          3mcolor <integer: register> <integer: r> <integer: g> 
          <integer: b> 

          0mtakes 4 integral arguments: the color  register  number  and
          the red, green and blue values.  It immediately changes that
          color register.  

          3mdrawpri <integer: priority> 

          0mits integral argument is the amount to raise the priority of
          the  drawing  task,  relative  to  the  priority of the main
          task.  Only negative values are recommended.  It  is  unwise
          to raise the drawing priority above the priority of the main
          program, since in that case the main program, the batch, and
          many  other  programs you might have running won't run until
          the picture is finished.  If this command is given after the
          drawing has started, it takes effect immediately.  

          3mselect <integer: depth> <integer: pen number> 

          0mtakes two values: the depth, and the corresponding pen color
          to be set in the pen table.  This also sets the  "pen  table
          mode" to select.  

          3mmodulo 

          0msets the pen table mode to modulo, and also recalculates the
          pen table accordingly.  

          3mranges 

          0msets the pen table mode to ranges, and also recalculates the
          pen  table  according to the currently selected range width,
          as set with the 3mrangewidth 0mcommand.  

          3mfunction iplot eplot <integer: function number> 

          0mFunction  selects  which  function   you   want   to   draw.
          Mandelbrot's  function  is number 1, and the other functions
          from  the  menu  are  2  through  5,  respectively   (pretty


     5 May 1989                       -8-


     Mandel(1)             AM*GA Programmer's Manual              Mandel(1)


          obvious!).  The User Programmed Function is number 4.  Iplot
          and  eplot  select the iteration plot and end plot function,
          respectively, also in the order as shown on the menu.  

          3mquit 

          0mExits 1mMandel 0mafter the batch file finishes, is  aborted,  or
          executes a 3mwait.  

          program, prelude 

          0mstart  the  definition  of a little program, to calculate an
          alternative function.  The program or prelude  ends  with  a
          line   with  only  3mend  0mon  it,  which  translates  into  an
          end-of-program marker.  You must  always  define  a  prelude
          before the  main  program.   If you re-define a main program
          and a prelude  has  also  been  defined  earlier,  then  the
          prelude  is  not  replaced  unless  you  (first)  explicitly
          re-defined it.  For a description of the actual "programming
          language" see its own section in this manual.  The  function
          number you need to select (with the 3mfunction 0mcommand) is 4.  

          3mreg <integer: register number> <real: value> 

          0mSet a  register  of  the calculator to the given value.  You
          could use this to supply some value for a parameter in  your
          user programmed  function.  You can only set a real value so
          the valid range  of  register  numbers  is  from  0  to  31,
          inclusive.  

          3mbatch <string: file name> 

          0mends  processing the current batch file, and starts with the
          named file.  [With ARexx, it is supposed to start the  given
          rexx-macro asyncronously, but see the ARexx section.] 

          3m# ; / 

          0mcomment commands.   Any  remaining  text  is  ignored.  Both
          shell and assembler comment symbols are supported, and the /
          is included so you can write nice C-style /* comments */.  

          Batch peculiarities: 
          - Error messages are not very helpful, and you don't  always
          see  them  because  they  go  into a window on the Workbench
          screen.  
          - No range checking is done on supplied numeric values;  use
          this freedom wisely.  
          - Excess  arguments  or trailing spaces are usually ignored,
          but don't count on this.  

     1mUSER PROGRAMMED FUNCTIONS 
          0mIn addition to  the  three  functions  selectable  from  the
          Draw:Func  menu,  you  can  program  your  own  in the batch
          language.  This feature has been added just to be  uselessly
          over-complete.  

               The  environment  for your function is exactly the same


     5 May 1989                       -9-


     Mandel(1)             AM*GA Programmer's Manual              Mandel(1)


          as for the other functions:  you  need  not  (and  in  fact,
          cannot)  specify  the  iterations,  or  the test against the
          termination value.  

               To enable you to calculate your function, you can write
          a program for a simple calculator.  That calculator  has  16
          registers  for  complex  numbers (or you can use them for 32
          real values), and real and complex operators for  assignment
          (copy),  addition,  subtraction,  multiplication, and it can
          put whole numbers into registers.  There is no provision  to
          divide, since you could run the risk of dividing by zero.  
          The  actual  procedure  followed to calculate a picture with
          user programmed function is: 

             For each pixel in the window: 
                - Initialize registers 0, 2 and 3 to Z, C and Mouse 
                respectively.  
                - Execute the prelude.  
                - Then, while abs(Z) < some value, repeat: 
                   - Register 1 has been initialized.  
                   - Execute the main program.  
                   - Call the iplot function.  
                - Call the eplot function, in which usually the number 
                of iterations decides which color the current pixel 
                should get.  

          The syntax for a single step in the computation is described
          by the following regular expression: 

          { "r", "c" } 3mdest 0m"=" 3mopnd1 0m[ { "i", "+", "-", "*" } 3mopnd2 0m] 

          where  {  and  }   indicate   a   choice   between   several
          alternatives,  stuff  between  [  and ] is optional, 3mitalics
          0mindicate a number to fill in, and text in  quotes  indicates
          literal text that is required at that point.  
          There  may  be  a  maximum  of  62  steps in the prelude and
          program together.  

          The "r" or  "c"  select  the  type  of  operation:  3mreal  0mor
          3mcomplex.   0mIn  case  of  3mreal  0moperations,  the  16  3mcomplex
          0mregisters can be viewed as 32 3mreal 0mregisters, with registers
          0-15 containing the 3mreal  parts,  0mand  registers  16-31  the
          corresponding 3mimaginary parts.  

          0mAs  said,  every line in the program is a single step in the
          computation of your function.  Every step describes a simple
          operation (*, + or -) on the values in  two  registers,  and
          the  result  is  put  in  the  designated register after the
          calculation.  3mDest 0mis the number of the register to put  the
          result of  the operation.  Likewise, 3mopnd1 0mand 3mopnd2 0mare the
          numbers of the registers which give both  operands  for  the
          operation (with the exception of the "i" operator).  So, for
          example, the following program will be acceptable: 







     5 May 1989                       -10-


     Mandel(1)             AM*GA Programmer's Manual              Mandel(1)



               3mprogram         
               0mc 3 = 0 * 0
               c 0 = 3 - 2
               c 0 = 0 + 1
               end

          Note  that the 3mprogram 0mnot really belongs to the program; it
          is the batch command that indicates that a program  follows.
          The 'end' on the other hand is a real instruction.  

          The *,  - and + do the obvious thing.  Remember, all numbers
          here are the numbers of the registers involved.  

          With the "i" operator, you can form a  complex  number  from
          two small  integral numbers.  (Small means ranging from -128
          to +127, inclusive.) The first number is the real part,  and
          the second  number  becomes  the  imaginary  part.    If the
          operation is real instead of complex, the second  number  is
          ignored, but  still required.  For future compatibility, you
          should use 0 there.  

               There are four registers  with  a  predefined  meaning.
          You can  use  the other 12 registers any way you like.  They
          are not initialized to any particular value,  and  therefore
          they  should  not  be  used  unless  you  set  them yourself
          before.  

               Register 0 is meant as place  for  Z  in  the  formula.
          Before  the  prelude it is initialized to 0 + i*0, and it is
          not changed between iterations.  It is, however, examined to
          see if the calculation is finished.    Therefore,  you  must
          leave the result of your calculation here.  

               Register 1  is changed before each iteration.  The real
          part contains the square of the real  part  of  Z,  and  the
          imaginary  part contains the square of the imaginary part of
          Z. These are calculated during the iteration check, so there
          is no cost in making it available to you.  

               Register 2 contains C. It  is  initialized  before  the
          prelude, and  it is not changed between iterations.  You may
          change it if you feel this is necessary, though it is useful
          if you use the provided value at least once.  You may notice
          now that if you leave the  last  line  (before  the  3mend  0mof
          course) off the above supplied example, you get a program to
          calculate Mandelbrot's  function.    In fact, if you wish to
          use it, you will find that it is not extremely  slower  than
          what  you  would  get from using the optimized function from
          the menu.  

               Register 3 contains the mouse position, as it was  last
          shown  in  the  3mRe and Im 0mwindow (or if you closed it, could
          have been shown  there).    It  is  initialized  before  the
          prelude, and  it is not changed between iterations.  You may
          change it if you feel this is of no value to you.   You  can
          produce  interesting  formulas  which  depend  on  the mouse
          position.  Such a picture would be difficult  to  reproduce,


     5 May 1989                       -11-


     Mandel(1)             AM*GA Programmer's Manual              Mandel(1)


          unless  you  arrange  to  save  the value in a high numbered
          register in one prelude, and can use another  prelude  later
          to retrieve the old value.  

               Registers 4 through 15 are free for you to use.  

               Another example.    It  is possible to define a prelude
          and program to draw the Julia set belonging to a point.  For
          those not familiar with Julia sets,  I'll  briefly  describe
          their relations and differences with Mandelbrot's set.  
          Both  sets  are based on the same function, Z = Z*Z - C. But
          where in  Mandelbrot's  case  the  initial  value  of  Z  is
          constant  (0)  and  C  varies  with  (corresponding to) each
          pixel, for a  Julia  set  the  initial  value  of  Z  varies
          corresponding to   each  pixel  and  C  is  constant.    For
          different  values  of  C  you  get  different  pictures,  of
          course.  

               The following prelude and program calculate a Julia set
          with  for  C  the  location of the mouse when you select the
          menu item to start drawing.  The value is visible in the  3mRe
          and Im 0mwindow.  

               3mprelude         
               0m# This sets the initial value of Z
               # to the current pixel
               c 0 = 2
               # Save C for later
               c 15 = 3
               end
               # The following part is iterated:
               3mprogram         
               0m# Calculate Z*Z
               c 4 = 0 * 0
               # Calculate [Z*Z] - C
               # Remember register 3 is the mouse position
               c 0 = 4 - 3
               end

               If  you  later want to re-use the same value for C, you
          simply load another batch file with 'c 3 = 15' to restore  C
          instead of  the  line  'c  15  =  3'.    It is currently not
          possible to use floating point constants  in  your  program;
          the  only  way  to  input them is with the mouse or with 3mreg
          0mcommands in a batch file.  

               Currently, the user programmed function  is  not  saved
          with  the  picture,  only  the  fact  that  it  used  a user
          programmed function.  This is no fatal  disadvantage,  since
          is  no  way  to  look  at (or change) the function using the
          menus of 1mMandel0m.  The standard  procedure  is  to  supply  a
          batch  file  with  the  saved  picture which re-programs the
          function used.  

     1mSLIGHTLY TESTED AREXX INTERFACE 
          0mKnowing Rexx from VM/CMS systems [please note that Rexx  was
          not  originally  invented by I*M], I wanted to make an ARexx
          interface.  But there was one problem: I  don't  have  ARexx


     5 May 1989                       -12-


     Mandel(1)             AM*GA Programmer's Manual              Mandel(1)


          myself.   But  then  along  came  MinRexx  [on Fish #188] by
          Radical Eye Software (also known as  Tomas  Rokicki),  which
          looked so  utterly  easy to use.  And necessary header files
          and glue routines were supplied with DME [on Fish #168/169].
          So, after examination of Tomas' code,  I  easily  added  the
          MinRexx  interface  to  Mandel. It compiles, links, and even
          runs.  Without ARexx. It creates a named message port, so at
          least that part works.  But the rest?  I  didn't  know.    I
          simply didn't know.  I asked someone with ARexx to give it a
          try, and  he  told  that  it works.  But I cannot personally
          guarantee that, nor give any hints about proplems one  might
          experience.  

               Maybe somebody would care to donate me ARexx?  Because,
          if it  does  not  work,  I cannot fix it.  May be I secretly
          hope it does not work :-) 

               The intention is, by the  way,  that  batch  files  you
          start  up,  either  via the Batch menu, or as a command line
          parameter, are fed though ARexx, [and  if  that  fails,  are
          done  the  same way as they are without ARexx interface] and
          that  all  normal  batch  commands  are  accessible  through
          ARexx.  

     1mREVISION HISTORY 
          0mV1.3    2 Mar 1989 - 16 Apr 1989 
          Added  batch  commands  prelude,  reg,  iplot,  eplot, stop.
          Initialization of register #3. Zoom menu actions  (suggested
          by Peter Larsen). Slightly tested ARexx interface.  
          Supported when time permits.  

          V1.2    23 Jan 1989 - 29 Jan 1989 
          Added user programmable functions, priority submenu (idea of
          Peter Larsen).  Made string part in MAND chunk larger: Files
          saved from V1.1 will work as if they were V1.0 files (and so
          the info that was added in V1.1 is lost in the transition).  
          Released. Not supported anymore.  

          V1.1    06 Jan 1989 - 22 Jan 1989 
          Added  batch  mode,  selection  of screen size; removed most
          annoying features of save from a  window  and  load  into  a
          differently  sized  window than originally saved from; fixed
          annoying  deadlock/crash  when  attempting  to  save  before
          anything  had  been  drawn;  fixed incorrect IFF file format
          with respect to MAND chunk; added more information  in  MAND
          chunk  (function  number,  pen  table  mode, selected screen
          size); finally did the select menu item.  
          Not released.  Never supported.  

          V1.01   16 Sep 1987 
          Quick check for graphics bug made a bit better.  
          Not released.  No longer supported.  

          V1.0    15 Sep 1987 
          Quick check for graphics bug.  
          Released on Fish disk #111. No longer supported.  




     5 May 1989                       -13-

