home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d3xx / d321 / turtle.lha / Turtle / TurtleDocs < prev   
Encoding:
Text File  |  1990-02-27  |  5.8 KB  |  176 lines
  1. 1: FUNCTIONS
  2.  
  3. The Turtle Library contains the following functions for drawing with a Turtle
  4.  in a RastPort:
  5.  
  6.  
  7. CreateTurtle(RastPort:A0, xPos:D0.W ,yPos:D1.W ,Angle:D2.W ,Flags:D3.B):
  8.  This function takes the initial position, angle and flags of the Turtle
  9.  to be created and its RastPort. It returns a pointer to a TurtleHandle
  10.  structure, which is used by all Turtle functions.
  11.  
  12. ReturnTurtle(TurtleHandle:A0)
  13.  If you do not need a Turtle any more you should return it to the system
  14.  by calling this function.
  15.  
  16. TurnLeft(TurtleHandle:A0, Angle:D0.W)
  17.  This function turns a Turtle to the left. Angle may be positive or
  18.  negative. It is an integer value and given in degrees, not in radians.
  19.  
  20. TurnRight(TurtleHandle:A0, Angle:D0.W)
  21.  Same as TurnLeft(), but turns the Turtle to the right.
  22.  
  23. PenUp(TurtleHandle:A0)
  24.  This function lifts the Turtle "pen" from the RastPort, so subsequent
  25.  calls to Forward() will only move the Turtle to its new positions but
  26.  will not draw any lines.
  27.  
  28. PenDown(TurtleHandle:A0)
  29.  This function lowers the "pen" on the RastPort, so Forward() will draw
  30.  lines again.
  31.  
  32. HideTurtle(TurtleHandle:A0)
  33.  If this function is called the Turtle triangle indicating its position
  34.  and direction is not drawn any more. This will greatly speed up drawing.
  35.  
  36. ShowTurtle(TurtleHandle:A0)
  37.  After a call to ShowTurtle() the Turtle triangle is drawn again.
  38.  
  39. SetAngle(TurtleHandle:A0, Angle:D0.W)
  40.  By calling this function you can set the direction of the Turtle.
  41.  
  42. SetPosition(TurtleHandle:A0, xPos:D0.W ,yPos:D1.W)
  43.  By calling SetPosition() you can set the position of the Turtle.
  44.  
  45. ResetTurtle(TurtleHandle:A0)
  46.  A call to ResetTurtle() resets the Turtle to its initial state.
  47.  
  48. Forward(TurtleHandle:A0, Distance:D0.L)
  49.  Forward() moves the turtle Distance steps forward. Distance may also be
  50.  negative. It is a FFP floating point variable.
  51.  
  52.  
  53.  
  54. 2: TURTLEHANDLE STRUCTURE
  55.  
  56. The TurtleHandle structure looks this way:
  57.  
  58. struct TurtleHandle
  59. {
  60.     struct RastPort *RPort;
  61.     FLOAT xPosition, yPosition;
  62.     SHORT Angle;
  63.     SHORT xStart, yStart, aStart;
  64.     UBYTE Flags, FlagStart;
  65.     Point PointArray[3];
  66. };
  67.  
  68. RPort is a pointer to the RastPort the Turtle draws in.
  69. xPosition and yPosition contain the actual position of the Turtle.
  70.  They are FFP floating point numbers.
  71. Angle is the direction of the Turtle (in degrees, NOT in radians).
  72.  It is a 16 bit integer number in the range from 0 to 359.
  73. Flags is the current state of the Turtle flags.
  74. xStart, yStart, aStart and FlagStart are the initial values for position,
  75.  direction and flags.
  76. PointArray[] contains the three vertices of the Turtle triangle.
  77.  
  78. Never change the Turtle position and angle and the triangle vertices in the
  79.  TurtleHandle if the Turtle triangle is visible. If you do you will find
  80.  strange Turtle triangles in your RastPort. Better use the library functions.
  81.  
  82. The values for the initial positions may be altered freely.
  83.  
  84.  
  85.  
  86. 3: TURTLE FLAGS
  87.  
  88. There are the following flags in the TurtleHandle.Flags variable:
  89.  
  90. HIDETURTLE
  91. PENUP
  92. TXCOMP
  93. TYCOMP
  94. (TCX320Y200, TCX640Y200, TCX320Y400, TCX640Y400)
  95. TURTLEVALID.
  96.  
  97. If the HIDETURTLE flag is set the Turtle triangle will not be drawn. Never
  98.  clear it yourself but use the HideTurtle() function instead because the 
  99.  Turtle triangle will not be erased from the screen. Checking and setting
  100.  may be done without any danger (although I cannot see why you should set
  101.  it directly - just call ShowTurtle() ).
  102.  
  103. If the PENUP flag is set Forward() will not draw any lines. You can check
  104.  it, set it and clear it if you really like (but better use the PenUp() and
  105.  PenDown() functions).
  106.  
  107. If the TXCOMP or TYCOMP flags is set the Turtle triangle is compressed
  108.  along the x axis/ y axis. They are intended to make the Turtle triangle
  109.  look reasonable in all screen resolutions. Normally you use the resolution
  110.  flags (e. g. TCX320Y200) when calling CreateTurtle(). If you do have to
  111.  change them (why???) call HideTurtle(), change your flags and call
  112.  ShowTurtle(). 
  113.  
  114.  
  115.  
  116. 4: OTHER THINGS
  117.  
  118. The Turtle library needs the MathTrans library. So you should have this 
  119.  library in the LIBS: directory, too.
  120.  
  121. Of course you can have more than one Turtle in a RastPort.
  122.  
  123. The Turtle draws with the colors of its RastPort.
  124.  
  125. If you have a Turtle in a RastPort it is not affected by moving its cursor
  126.  or by other drawing operations.
  127.  
  128. The Turtle triangle is drawn and erased in COMPLEMENT mode. So take care
  129.  not to draw over it or you will find strange looking remnants of the
  130.  triangle in your RastPort.
  131.  
  132. There is no clipping done by the Turtle routines. If you have a RastPort
  133.  that does not support clipping you must perform it yourself.
  134.  
  135.  
  136.  
  137. 5: INCLUDES
  138.  
  139. The turtle.fd file contains the function definitions.
  140. The turtle.h include file contains the structure and flag definitions for
  141.  the C language.
  142. The turtle.i file contains the structure and flag definitions for assembler
  143.  language and the turtle.offsets file the offsets . 
  144. The turtle.proto file contains the prototypes for the Turtle library (for 
  145.  use with Lattice C V5.0).
  146. The turtle.lib file contains the stub routines for calling the library 
  147.  functions (if you do not wish to use #pragmas). They work with both the
  148.  Lattice -rr and the -rs option. They should also work with Aztec C but
  149.  I do not own the Aztec program so I could not test them.
  150.  
  151.  
  152.  
  153. 6: SOURCE CODE
  154.  
  155. The library was written with Devpac Assembler V2.0. If you wish to reassemble
  156.  it with other assemblers you should change the include directory after the
  157.  INCDIR directive in line 9.
  158.  
  159. The demo program was written with Lattice C V5.04. Compile with "lc -ff 
  160.  turtledemo", link with "blink from lib:cback.o turtledemo.o to turtledemo
  161.  lib lib:lcmffp.lib lib:lc.lib". If you with to recompile it with other
  162.  compilers you must specify the program to use FFP floating point numbers.
  163.  
  164.  
  165.  
  166. If you want to write me, this is my address:
  167.  
  168.  Thomas Albers
  169.  Brandenburger Str. 18
  170.  2930 Varel
  171.  West Germany
  172.  
  173.  
  174. Have fun! - Thomas
  175.  
  176.