1: FUNCTIONS

The Turtle Library contains the following functions for drawing with a Turtle
 in a RastPort:


CreateTurtle(RastPort:A0, xPos:D0.W ,yPos:D1.W ,Angle:D2.W ,Flags:D3.B):
 This function takes the initial position, angle and flags of the Turtle
 to be created and its RastPort. It returns a pointer to a TurtleHandle
 structure, which is used by all Turtle functions.

ReturnTurtle(TurtleHandle:A0)
 If you do not need a Turtle any more you should return it to the system
 by calling this function.

TurnLeft(TurtleHandle:A0, Angle:D0.W)
 This function turns a Turtle to the left. Angle may be positive or
 negative. It is an integer value and given in degrees, not in radians.

TurnRight(TurtleHandle:A0, Angle:D0.W)
 Same as TurnLeft(), but turns the Turtle to the right.

PenUp(TurtleHandle:A0)
 This function lifts the Turtle "pen" from the RastPort, so subsequent
 calls to Forward() will only move the Turtle to its new positions but
 will not draw any lines.

PenDown(TurtleHandle:A0)
 This function lowers the "pen" on the RastPort, so Forward() will draw
 lines again.

HideTurtle(TurtleHandle:A0)
 If this function is called the Turtle triangle indicating its position
 and direction is not drawn any more. This will greatly speed up drawing.

ShowTurtle(TurtleHandle:A0)
 After a call to ShowTurtle() the Turtle triangle is drawn again.

SetAngle(TurtleHandle:A0, Angle:D0.W)
 By calling this function you can set the direction of the Turtle.

SetPosition(TurtleHandle:A0, xPos:D0.W ,yPos:D1.W)
 By calling SetPosition() you can set the position of the Turtle.

ResetTurtle(TurtleHandle:A0)
 A call to ResetTurtle() resets the Turtle to its initial state.

Forward(TurtleHandle:A0, Distance:D0.L)
 Forward() moves the turtle Distance steps forward. Distance may also be
 negative. It is a FFP floating point variable.



2: TURTLEHANDLE STRUCTURE

The TurtleHandle structure looks this way:

struct TurtleHandle
{
    struct RastPort *RPort;
    FLOAT xPosition, yPosition;
    SHORT Angle;
    SHORT xStart, yStart, aStart;
    UBYTE Flags, FlagStart;
    Point PointArray[3];
};

RPort is a pointer to the RastPort the Turtle draws in.
xPosition and yPosition contain the actual position of the Turtle.
 They are FFP floating point numbers.
Angle is the direction of the Turtle (in degrees, NOT in radians).
 It is a 16 bit integer number in the range from 0 to 359.
Flags is the current state of the Turtle flags.
xStart, yStart, aStart and FlagStart are the initial values for position,
 direction and flags.
PointArray[] contains the three vertices of the Turtle triangle.

Never change the Turtle position and angle and the triangle vertices in the
 TurtleHandle if the Turtle triangle is visible. If you do you will find
 strange Turtle triangles in your RastPort. Better use the library functions.

The values for the initial positions may be altered freely.



3: TURTLE FLAGS

There are the following flags in the TurtleHandle.Flags variable:

HIDETURTLE
PENUP
TXCOMP
TYCOMP
(TCX320Y200, TCX640Y200, TCX320Y400, TCX640Y400)
TURTLEVALID.

If the HIDETURTLE flag is set the Turtle triangle will not be drawn. Never
 clear it yourself but use the HideTurtle() function instead because the 
 Turtle triangle will not be erased from the screen. Checking and setting
 may be done without any danger (although I cannot see why you should set
 it directly - just call ShowTurtle() ).

If the PENUP flag is set Forward() will not draw any lines. You can check
 it, set it and clear it if you really like (but better use the PenUp() and
 PenDown() functions).

If the TXCOMP or TYCOMP flags is set the Turtle triangle is compressed
 along the x axis/ y axis. They are intended to make the Turtle triangle
 look reasonable in all screen resolutions. Normally you use the resolution
 flags (e. g. TCX320Y200) when calling CreateTurtle(). If you do have to
 change them (why???) call HideTurtle(), change your flags and call
 ShowTurtle(). 



4: OTHER THINGS

The Turtle library needs the MathTrans library. So you should have this 
 library in the LIBS: directory, too.

Of course you can have more than one Turtle in a RastPort.

The Turtle draws with the colors of its RastPort.

If you have a Turtle in a RastPort it is not affected by moving its cursor
 or by other drawing operations.

The Turtle triangle is drawn and erased in COMPLEMENT mode. So take care
 not to draw over it or you will find strange looking remnants of the
 triangle in your RastPort.

There is no clipping done by the Turtle routines. If you have a RastPort
 that does not support clipping you must perform it yourself.



5: INCLUDES

The turtle.fd file contains the function definitions.
The turtle.h include file contains the structure and flag definitions for
 the C language.
The turtle.i file contains the structure and flag definitions for assembler
 language and the turtle.offsets file the offsets . 
The turtle.proto file contains the prototypes for the Turtle library (for 
 use with Lattice C V5.0).
The turtle.lib file contains the stub routines for calling the library 
 functions (if you do not wish to use #pragmas). They work with both the
 Lattice -rr and the -rs option. They should also work with Aztec C but
 I do not own the Aztec program so I could not test them.



6: SOURCE CODE

The library was written with Devpac Assembler V2.0. If you wish to reassemble
 it with other assemblers you should change the include directory after the
 INCDIR directive in line 9.

The demo program was written with Lattice C V5.04. Compile with "lc -ff 
 turtledemo", link with "blink from lib:cback.o turtledemo.o to turtledemo
 lib lib:lcmffp.lib lib:lc.lib". If you with to recompile it with other
 compilers you must specify the program to use FFP floating point numbers.



If you want to write me, this is my address:

 Thomas Albers
 Brandenburger Str. 18
 2930 Varel
 West Germany


Have fun! - Thomas