Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/542.lha/Xl_v1.0_Demo/xl.doc.pp/xl.doc

Text File | 1991-08-10 | 43KB | 1,729 lines

xl  version 1.00DEMO

a cel animation engine

by Dr. Kees



Copyright (c) 1991 by Martin C. Kees

ALL RIGHTS RESERVED



Introduction



xl is a drawing system that creates single bit-plane animations. The
user can control the drawing process by traditional interactive
methods using the mouse as a brush or can issue drawing commands from
a macro program. The set of drawing modes is rich in both modalities.
User definable Bezier curves, random dot generation, logic controlled
bitmap transformations, as well as the common line, box, oval, and
polygon objects can be drawn interactively or from ARexx macros. The
anim file created by xl can be imported to other animation packages
for colorization such as Deluxe Paint III, The Disney Animation
Studio, and the yet to be released pxl.



xl may be launched from WorkBench by double-clicking on it's icon or
from a CLI by 'run xl'. From the CLI the current directory should be
set to the directory containing the xl.config file. This is commonly
the same directory as the xl program. If the user wants function key
macros to be loaded then a macro file, xl.macros, should also reside
in this directory.

xl is terminated by the q key.







Installation


For xl to run the user needs to copy the req.library file to the libs:
directory. The InstallReq icon does this for you. For ARexx support,
libs:rexxsyslib.library must also exist and the resident ARexx process
should be launched. When using Workbench 2.0 you should set the mouse
screen drag in IControl to multiple qualifier keys not just the Amiga
key.



CONFIGURATION FILE



When xl is started it uses options set by the xl.config file. The
first line of this file should be:



XL CONFIG



Configuration commands and format are as follows:



DISPLAY   LORES | HIRES | LOLACE | HILACE

          sets drawing window resolution



BEZIER    #points #segs

          #points can be in the range 3-8. #segs in the range 4-512.



FRAMES    #frames

          sets the number of frames to be allocated on start-up.
          A minimum of 4 frames will be allocated.



ATFRAME   #currentframe
          Sets the current frame to edit. Frames are numbered 1-N.



FRAMEDELAY ticks

           Sets the interframe delay duration on animation play back.
           Range is 0-60.



COLOR      reg# r g b

           registers 0-4 control the drawing window.

           0   background
           1   frame 2 previous
           2   frame 1 previous
           3   current frame
           4   next frame
           registers 5-8 control the ToolBox colors.



USERKEY    NONE

           required command



PASSKEY    NONE

           required command



Of the commands listed above the xl.config file MUST contain the
XL, USERKEY, and PASSKEY commands.





ToolBox Tour



On startup you will see a blank screen in the upper 4/5 of the display
and a ToolBox screen on the lower 1/5. The ToolBox displays
information about the current state of xl and allows various mode
selections by clicking on the mode and tool gadgets.



The top line gives the current drawing mode name. If a capture file is
open CAP will appear in this line.  Bezier state and controlpoint info
will be displayed here also. An A will be displayed if autoaspect is
ON for polygon entry.



The left hand box gives coordinate info and frame info. The X Y
coordinates are relative to the upper left of the display with Y
values increasing in the downward direction and X increasing to the
right. The f number is the current frame and the F number is the total
number of frames currently allocated.



There are two rows of gadgets that either set the current drawing mode
or perform some control function.



PIXEL BRUSH TOOL ( . - = keys )

The top row starts with a pixel brush box that is really nine tiny
gadgets for each of the 9 built-in brush sizes. Clicking on any of
these sets the current brush size. Brushes may also be selected from
the keyboard using the -, = and . keys.



LINE TOOL   ( l key )

Next right is the line mode gadget. Clicking on it selects line mode.
Line will be displayed on the info bar. When in line mode drawing to
the frame display will done be in lines. Lines are started by a mouse
click. If the left button is used then the line will eventually be
DRAWN. If the right button clicked then the line will be ERASED.
Rubberbanding occurs with mousemovements until the user is ready to
select the end of the line by either a left or right click. The last
click can be modified by certain keys:



      LEFT-SHIFT click cancels the line draw operation or
                 'regrabs' the last line drawn on entry.

      LEFT-AMIGA 'grabs' the line as a brush. A subsequent click will
                 draw the line. Subsequent clicks can also be modified
                 by the Left-Shift and Left-Amiga keys so that the
                 line can be stamped at different locations on this
                 frame.



Note that if the ToolBox is visible an ending click with the right
mouse button will draw through the toolbox to the drawing area below
while a left mouse click on the toolbox area will be ignored. While
rubberbanding the toolbox screen can be moved by dragging on the
thin black line at the top of the info bar. Prior to starting a line
the toolbox may be toggled to the back/front by the F10 function key.





RECTANGLE TOOL   ( r R key )

Next right is the rectangle/block gadget. It selects rectangle or
filled rectangle mode as the current drawing mode. As in the line mode
the initial mouse button determines whether the box is drawn or
erased. The first click selects a corner of the rectangle. Then
rubberbanding occurs until the opposite corner is selected by a mouse
click. The last click can be modified in the same manner as in line
mode to cancel, grab, or regrab the last rectangle.





CIRCLE TOOL      ( c C key )

Next is the circle mode gadget. It selects circle mode for the current
drawing mode if clicked in the upper half and filled-circle mode if
clicked in the lower half. Circles are drawn in the current resolution
so when in non-square modes the circles will nat be aspect adjusted
but will be pixel unit circles. Circle mode starts with a mouse click
to select center of the circle the the circle will rubberband with
movement of the mouse to set the radius. The initial click right/left
determines whether the circle is drawn or erased. The last click can
be modified with the keyboard (as in line mode) to 'grab' the circle
or to cancel the drawing operation.





CLIPBRUSH TOOL    ( b key )

Next is the brush tool. Clicking on it selects brush clipping mode. A
rectangular area of the current frame can be selected just as if a
rectangle were being drawn. The selection area can be grabbed by using
the Left-Amiga key and moved over the display to any area. When
finally selected a transparent brush of that portion of the screen
will be attached to the mouse and the mode will change to StampBrush.

If the left mouse button is clicked the image will be stamped to the
frame in a transparent mode. That is: nothing will be erased from the
screen, just areas in the brush that are solid will overprint. If
the right button is used then blitter logic will be used to determine
the result. The default logic is to erase the screen in any solid
areas of the brush. The logic can be changed by macros to achieve 16
different effects.

While holding a brush the x and y keys can be used at any time
to flip the brush in the horizontal or vertical directions. This can
also be done with macro commands. The ( key on the numeric pad rotates
the brush about the x=y axis. The numeric pad can be used to change
the grab point of the brush. The corner and center numbers move the
grab point to the analogous position. That is: 3 moves to lower right
and 5 centers. The 4, 6, 8, and 2 keys move the grab point in pixel
steps or BRUSHADJ size steps if shifted.

StampBush mode is one of the few modes that keeps the toolbox and
keyboard active so that frame changes may be made while holding a
brush. Once a brush is grabbed it may be recalled by the Shift-B
keyboard command.



FONT select

This gadget calls the font requester to select the current font for
text operations.





FRAME SELECT    ( 1 2 keys )

Next is the frame forward/backward tool. Clicking the corresponding
arrow changes the current frame displayed. If the current frame has
been modified there will be a delay while it is updated to memory.
These gadgets perform the same action as the 1 and 2 keys on the main
keyboard.





ADD FRAME       ( a key )

The plus gadget adds a duplicate of the current frame as the next
frame in the animation. To add a blank frame use the add gadget then
advance to the next frame then clear it.





MEM FRAME

The MEM gadget saves the contents of the current frame in the
tempframe buffer. It may be recalled by using the RCL gadget below.





CLR FRAME/ALL FRAMES

The CLR gadget clears the current frame. Before the clear, the frame
is copied to the tempframe buffer. This erases the previous contents
of that buffer! The clear can be undone by using the RCL gadget. This
gadget has a different effect when the LEFT-SHIFT key is down when
clicked. Then ALL frames will be cleared if the requester is accepted.





PALETTE TOOL

Next right is the palette gadget. Clicking it opens a palette
requester on the drawing window. Since the drawing window is designed
to be able to show four frames of the animation in an onion skin view
16 colors are required if each of the four frames is in a separate
bitmap plane. To change the colors of the current frame all eight
colors on the left half of the display need to be modified to the same
value. This can be done in a single step using xl's macro commands. If
the colors are set to different values then pixels on in overlapping
frames will be made apparent. Feel free to experiment. The default
settings make the current frame appear on top of the display, then
going deeper is the next previous, the second previous and last is the
next frame after the current one.





SKETCH MODE  ( s key )

This is the tool gadget located on the second row just under the
pixel-brush selector. This is the startup drawing mode. It is the only
mode that uses clickdown-drag-upbutton protocol. Using the left button
causes a DRAW response, using the right causes an ERASE. The currently
selected pixel-brush is used when drawing/erasing.





BEZIER MODE  ( z key )

The next tool is the bezier tool that sets bezier-curve mode. This
mode draws very nice curved line segments.  The curve is controlled by
a set of control points. Using the BEZIER macro command or the numeric
keypad one can set the number of control points to be in the range 3-
8.  The curve is drawn by a series of line segments relating to the
control points selected. More segments can smooth the curve generated.
The number of segments can be set by macro or by using the keyboard
SHIFT-Z.  The current settings are displayed in the toolbox info bar.


Drawing a curve is a multistep process. First the endpoints are
selected in the same manner as in LINE mode. At this point the curve's
controlpoints will be set for the two endpoints. All other points are
defaulted to the last point. The next phase is setting the
intermediate control points. Moving the mouse rubberbands the curve
using the current control point. The current control point number is
displayed in the toolbox info bar.  A mouse click locks that control
point and selects the next control point in the curve until the end-
point is reached. Then the curve is drawn.


The process of selecting control points does not have to be
sequential. At any time the keyboard z/x or left-arrow/right-arrow
keys can be used to go back and forth from control point to control
point. This allows stepwise definition of the curve in an interactive
manner. The shifted key will select the first or last control point.
Note that the current control point is NOT changed until a MOUSEMOVE
occurs. This enables one to keep a particular control point fixed.



The currently displayed version of the curve can be drawn at any time
by using the space bar. A SHIFTED-space bar keypress will cancel the
curve.  A LEFT-SHIFT click will recall the last bezier curve defined
on entry. The curve will be DRAWN if the starting point was selected
by the left button and ERASED if selected with the right button.



There are two bezier methods available by macro.  BEZNORMAL selects
the standard bezier curve. The control points define a convex polygon
that will enclose the generated curve. In this method each control
point will be a fair distance from the displayed curve.  BEZADJUST
causes a scaling of the control points so that the curve follows the
control points more closely. It does not produce curves that lie
within the convex hull of the control point polygon and does not scale
them in a symmetric way ( points toward the end are scaled with
heavier weights).  The default mode is BEZADJUST.  Experiment with the
two methods to determine which is best for your task.





POLYGON TOOL   ( p P key )

The polygon tool enters polygon mode. Polygons with up to 125 segments
can be drawn/erased. The polygon is entered  in a continuous line
mode but with the head of the next segment attached to the tail of the
previous segment. The polygon is ended and drawn if the starting
point is selected. DRAW/ERASE is determined by the initial left/right
button click.  Auto closure is made with the LEFT-ALT key. The
LEFT-SHIFT key cancels the polygon and LEFT-AMIGA grabs it for
stamping.  A CTRL click grabs the polygon without closing it. A LEFT-
SHIFT click on entry to this mode will REGRAB the last polygon
defined.



During the polygon point entry mode the current scaling and rotation
angle are ignored. If AUTOASPECT is set to ON the the points
entered will be scaled to the current POLYASPECT settings. If
AUTOASPECT is OFF the when the polygon is grabbed it might change
shape depending on the current POLYAPSECT setting.



Once defined the polygon may change its size and orientation depending
on the current state of SCALE, ANGLE, ASPECT and CENTER options for
polygon control. The arrow pad keys affect scaling with the left and
right keys controlling horizontal scale and the up and down arrows
affecting vertical scale. This scaling is relative to the original
orientation of the polygon so that if a 90 degree rotation angle
is current the up and down arrows will change the vertical size.
The DEL and HELP keys change the current rotation angle with HELP
causing a clockwise rotation and DEL a counterclockwise rotation.
When SHIFTED all keys cause coarse changes in larger increments
than when unshifted. Note that negative scale values have the effect
of flipping the polygon around the scaling axis. The 4, 6, 8, and 2
keys on the numeric pad move the center of rotation and the grab point
of the polygon. Shifted keys step in larger increments set by
POLYSTEP.





OVAL TOOL      ( o key )

Oval mode is the same as circle mode except that both a horizontal and
a vertical semi-radius are determined during rubberbanding.



FILL MODE    ( f key )

Next is the fill tool. When selected the pointer becomes a fill
spigot.  The drip is the hot spot of the fill tool. If the left button
is clicked  the fill tool fills with solid ink until an outline is
encountered. If the right button is clicked an area is erased until
cleared screen is encountered.  The fill causes a frame memorize
before the fill takes place so that leaks can be undone by clicking on
the RCL gadget. However this also causes loss of any previous MEM
frame information.


MAGNIFY tool

Clicking on this gadget cycles it's image thru lo, hi, and no
magnification. The magnifying glass icon is replaced by a pixel view
centered on the current cursor position. In LO mode a 5x3 pixel
display is shown and in HI mode a 10x6 view is displayed. The
highlighted block represents the cursor position. It is white if
that pixel is OFF and blue if ON. Having Magnify ON will slow down
drawing operations, especially in sketch mode.



VIEW TOOL      ( 4 key )

The eye gadget displays the animation in a loop until a mousemove
event occurs.  This is the same action that the 4 main keyboard key
produces. For Ping-Pong display use the 6 main keyboard key.





DELETE FRAME TOOL  ( A key )

The minus gadget deletes the current frame from the animation. At
least four frames must exist so this gadget has no effect if there
are only four frames.





RCL TOOL     ( u key )

Clicking the RCL gadget updates the current frame to the current
tempframe buffer contents. That buffer can be set by previous
CLR or MEM gadget usage. Note that on startup the tempframe buffer is
the "about" message.





AREXX GADGET  ( m key )

This gadget starts the process of executing a macro command. There are
four types of macros in xl. The first two are AREXX macros and require
AREXX by W. Hawes. These are indicated on the requester by the AREXX
and 'AREXX' buttons. The AREXX type is the name of an Arexx program
that contains commands for xl to execute.  When this type of macro is
given the user is expected to give the name of the Arexx program that
xl is to submit to the ARexx server to execute. Arexx will search for
this program (if a full path name isn't given) starting in the current
directory and if not found in the system REXX: directory. It will
search for the exact name as entered if it has a file extension. If
no file extension is given it will search for both the plain named
file and if not found will append .xl and search again.



The second type of macro is the 'AREXX' macro. The string entered in
the macro requester will be sent to ARexx to execute as if it were
a program.  The string requester will allow programs up to 384
characters long. Each program line in the string is separated by a
semi-colon. In this mode the usual beginning /* comment */ line is NOT
needed.



The two other types of macros are selected with the SCRIPT button.
Script macros do not require ARexx but are limited to literal
commands. The first script type is a SCRIPT file request. The user
gives the filename of a text file containing xl macro commands. The
file name must include  a path relative to xl's current directory. If
the name given is REQ, then a file requester will appear for script
file selection. The script file will then be loaded and executed just
as if those commands had been sent from ARexx.



The last macro type is the @Command macro. It is entered in the script
string requester with the first character as @ and the rest of the
line asa single macro command statement. For example: @FIRST would
execute the FIRST macro which moves the current frame to frame 1 of
the animation.



In script macros there is no evaluation of the command arguments so
numeric arguments must be given absolutely. Quotes are not stripped
in script argument strings as they are from ARexx. The command set
used in scripts is the same as in ARexx macros except that commands
that return results have no meaning or effect in scripts.



Note that a separate buffer retains the last macro entered for AREXX
and SCRIPT macros. This allows retention of an 'AREXX' program but
still macro control with @Commands.



Any of the four types of macro invocation can be attached to a
FUNCTION KEY.  Using i from the keyboard starts a dialogue to select a
macro to attach to a function key. Unshifted keys can range from F1 to
F9.  F11 to F30 are selected by SHIFT ( F11 - F20 )and ALT ( F21 - F30
). The current macro key assignments can be saved and/or loaded by the
LOADMACROS and SAVEMACROS commands.



The Arexx interface in xl is not normally open to external control. To
allow external tasks to send xl macro commands one would have to
invoke an ARexx program that stayed active while commands are sent to
the XLPORT. The external task would have to signal that macro when it
was finished so it could terminate. The public port xl opens will be
named XLPORT ... XLPORT0 ... XLPORT9 depending on what ports are open
at startup. Errors occurring in this arrangement would have to be
handled carefully. The external task would need to respond to error
returns and clean-up result strings and make sure it signaled the
active macro before terminating (even from a halt request).



ARexx and Script macro programs may be halted by the holding down
the ESC key.





CAPTURE TOOL

The capture gadget is of help in debugging Arexx macro programs or
in preparing script files. When clicked a file requester appears
waiting for the name of a file. That file will be opened and the
CAP indicator will appear on the toolbox info bar. Any ARexx
commands received will be written to that file until it is
closed by clicking on the capture gadget again. Examining that
file in a text editor will show the actual command strings received
from Arexx. The file will be in the correct format to execute
in the Script macro mode.  For many programs this will be a much
faster way to repeat an exact sequence of commands if the file
is in ram: or on a hard-drive.





BACK/FRONT gadgets

The back and front gadgets are special gadgets that push and pop the
drawing screen to the back and front but leave the toolbox accessible.
Standard screen back/front gadgets would cause display problems when
using mixed LACE NON-LACE modes.









KEYBOARD COMMAND Summary



Key       Function



q         QUIT XL   ( The only way to EXIT xl )

e         clearframe

E         clear all frames

r         rectangle mode

R         block mode

u         update display from tempframe buffer

i         install macro to function key

o         oval mode

O         oval-fill mode

p         polygon mode

a         add duplicate frame after current frame

A         delete current frame

s         sketch mode

d         select Frame Delay

f         fill mode

l         line mode

z         bezier mode

Z         select number of bezier segments

c         circle mode

C         circle-fill mode

b         clipbrush mode

B         stampbrush mode

m         start macro invocation, user is prompted for type

M         start 'AREXX' macro

LeftAltm  start SCRIPT macro

RightAltm start AREXX macro

.         select single pixel brush

-         cycle to 'smaller' pixel brush

=         cycle to 'bigger' pixel brush

1         goto previous frame

2         goto next frame

3         goto selected frame

4         play anim in loop until mousemove

6         play anim in ping-pong loop until mousemove

F10       toggles toolbox

F1-30     executes current attached macro



Bezier Control

SHIFT-click     recalls last curve if done before point entry

z         select next control point toward start

x         select next control point toward end

Z         select start control point

X         select end control point

LEFT-ARROW          same as z/Z

RIGHT-ARROW         same as x/X

SPACE               draws displayed curve

SHIFT-SPACE         cancels curve

LAMIGA-SPACE        stamps displayed curve but continues rubberbanding

3-8 on numeric pad  selects the number of control points to use in

                    bezier mode





Modifiers to clicks during drawing modes



LEFT-SHIFT   cancels mode draw operation if in define mode
             or recalls last line, curve, polygon or rectangle
             if at entry to mode.

LEFT-AMIGA   grabs drawing object as a brush (closes polygon)

LEFT-ALT     closes polygon and stamps it

CTRL         grabs polygon without closing it



Polygon control

ARROW keys   scales polygon in x and y directions in fine steps

SHIFT-ARROW  scales polygon in x and y directions in coarse steps

DEL          rotates polygon counterclockwise in 1 degree steps

HELP         rotates polygon clockwise in 1 degree steps

SHIFT-DEL    rotates polygon counterclockwise in POLYSTEP increments

SHIFT-HELP   rotates polygon clockwise in POLYSTEP increments

0 (num pad)  sets polyangle to 0 and polyscale to 100 100

2 8          moves CENTER of polygon in Y direction

SHIFT 2 8    moves CENTER in POLYSTEP increments in Y

4 6          moves CENTER of polygon in X direction

SHIFT 4 6    moves CENTER in POLYSTEP increments in X





Brush Control



x            horizontal flip of brush

y            vertical flip of brush

Numeric Pad Keys

(            x=y axis flip of brush

1            grab handle to lower left corner

3            grab handle to lower right corner

7            grab handle to upper left corner

9            grab handle to upper right corner

5            grab handle to center of brush

4, 6         horizontal shift of handle

8, 2         vertical shift of handle





AREXX MACRO COMMAND FORMAT SUMMARY



  COMMAND     [agr1 arg2 ag3 ... $argN]
              [result= arg1 ... agrN]

              Comment to command

              Arguments starting with $ are string arguments.
              String arguments must pass enclosing double-quotes
              if embedded blanks are present. If case is to be
              preserved the $arg should be quoted.
              Other arguments are numeric INTEGERS.
              Coordinate values will be clipped to the frame so
              negative coordinates are legal. Spaces delimit
              arguments in xl but leading minus signs will confuse
              Arexx expression evaluation.



  LINE        x1 y1 x2 y2

              draws line from x1 y1 to x2 y2
              using current ink setting and current
              pixel brush



  BLINE3      x1 y1 x2 y2 x3 y3

              draws 3 controlpoint bezier curve
              using current bezier method, segments, ink and
              pixel brush.



  BLINE4      x1 y1 x2 y2 x3 y3 x4 y4



  BLINE5      x1 y1 ... x5 y5



  BLINE6      x1 y1 ... x6 y6



  BLINE7      x1 y1 ... x7 y7



  BLINE8      x1 y1 ... x8 y8



  DOT         x y

              turns pixel at x y ON/OFF
              by current ink setting



  INK         0|1

              0 erases 1 draws on subsequent commands



  CIRCLE      x y radius



  DISK        x y radius



  OVAL        x y h-radius y-radius



  ODISK       x y h-radius  y-radius



  BOX         x1 y1  x2 y2

              2 opposite corners define the box



  BLOCK       x1 y1  x2 y2

              solid box in ink color



  TEXT        x  y  $text

              uses x y to place text string relative to the baseline
              uses ink setting to draw/erase
              uses current font and style



  FLOOD       x y

              fills with ink from x y to outline
              presaves current frame in tempframe buffer



  LINEPTRN    mask|OFF

              sets the 16 bit pattern for lines according to the value
              of mask. Mask can be a string of * and . where the *
              represent ON pixels and the . represent OFF pixels.
              Example:

              LINEPTRN '*.*.*.*.*.*.*.*.'

              or mask can be a 16 bit integer value:

              LINEPTRN 65534

              or

              LINEPTRN OFF

              returns to normal line mode.



  AREAPTRN    ON|OFF|FREE

              Turns on/off area pattern mode for subsequent fill
              modes. An area pattern must be previously defined by
              INITAREA and PUSHPTRN commands. The FREE option
              reclaims memory used for the pattern and turns off
              area pattern mode.



  INITPTRN    size

              Allocates memory for an area pattern. Size must
              be a power of 2.



  PUSHPTRN    mask

              adds the pattern defined by mask to the current
              area pattern memory area. Mask can be a string
              of * and . as in LINEPTRN or an integer value.



  USEBRUSH    0|8

              selects pixel brush
              0 = single pixel
              8 = 3x3 pixels



  CUT

              deletes frame and copies to tempframe



  PASTE

              stamps tempframe as full frame



  SCROLL      dx dy x y width height

              scrolls rectangular area of frame by dx dy
              from position x y. dx and dy are signed values
              that indicate the amount to move toward
              the x y position.



  STAMP       x y

              stamps opaque tempframe at x y offset



  TRANSSTAMP  x y

              transparent stamp of tempframe at x y



  STAMPM      x y minterm

              stamp of tempframe with blitter logic



  COPY

              copies current to tempframe



  NEXT

              move to next frame



  PREV

              move to previous frame



  FIRST

              move to first frame



  LAST

              move to last frame



  GOTO        frame#

              move to frame frame#



  ADD

              add a duplicate frame after current frame



  ADDFRAMES   frames

              add frames # of duplicates after current



  CLEARFRAME

              erase current and copies to tempframe



  CLEARALLFRAMES

              erase all frames



  DELETE

              delete current frame



  DELETES     frames

              delete frames # of frames starting at current



  XFLIP

              flips the current frame horizontally



  YFLIP

              flips the current frame vertically



  COLOR       reg r g b

              set color register to rgb value



  SETPOS      x y

              set turtle position



  PENUP

              set no draw on turtle movement



  PENDOWN

              set draw on turtle movement



  SETH        angle

              set turtle heading



  FW          distance

              move turtle distance pixels in current heading



  BW          distance

              move turtle -distance pixels in current heading
              ( or distance pixels in opposite heading)



  RT          angle

              add angle to heading to get new heading.



  LT          angle

              subtract angle from heading to get new heading.



  LINETO      x y

              draw a line from current turtle position
              to the point x y. Use current penstate.
              New position is x y.



  TURTLE      x y angle 0|1

              setpos seth penup/pendown



  BEZNORMAL

              use normal bezier method



  BEZADJUST

              use adjusted bezier method



  SAVEANIMBRUSH $filename

                save animation in animbrush format
                disabled in DEMO version



  SAVESCREEN    $filename

                save drawing window as 4 bitplane ilbm
                disabled in DEMO version



  LOADANIMBRUSH $filename

                load animbrush file as current animation
                disabled in DEMO version



  SAVEFRAME     $filename

                saves ILBM of current frame
                disabled in DEMO version



  LOADFRAME     $filename

                loads plane 0 of ILBM file to current frame.
                Will accept different sizes than frame but
                places at upper left corner.



  LOADMACROS    $filename

                loads F-key macro file



  SAVEMACROS    $filename

                saves current F-key macros



  RANDOMBLOCK   x y width height

                fills area with random dots using current randdepth
                ratio. sequences can be repeated by getting and
                setting the random seed.
                dots are drawn if ink = 1
                and erased if ink = 0



  RANDDEPTH     dots total

                sets ratio of dots/totaldots
                used in randomblock



  GETSEED

                result= seed1 seed2
                returns current random seeds



  SETSEED       seed1 seed2

                sets current random seeds



  GRAB          x y width height

                clips a brush from current frame
                called grab



  XFLIPGRAB

                flips the current grab-brush horizontally



  YFLIPGRAB

                flips the current grab-brush vertically



  XYFLIPGRAB

                flips the current grab-brush about x=y axis



  SETMINTERM    minterm

                sets right-click stampbrush blitter logic



  TRANSBLIT     x y

                transparent stamp of grab
                to current frame



  BLIT          x y

                opaque stamp of grab to current frame



  BLITM         x y minterm

                stamp of grab to current frame
                with blitter logic



  BLITINVERSE   x y

                blits inverted grab brush



  BLITINVERSEBK x y

                inverts background and ignores grab brush





  BLITSIEVE     x y

                turns ON pixels common to grab and background
                others are turned OFF



  CLIPBLIT      xoffset yoffset w h x y

                blits a rectangular section of the grab brush
                w wide by h high offset from the upper left
                corner of the grab brush by xoffset yoffset
                to the current frame at position x y.



  CLIPBLITM     xoffset yoffset w h x y minterm



  CLIPTRANSBLIT xoffset yoffset w h x y



  ROTGRABPLANES

                If a grab brush is loaded that contains
                multiple bit-planes this command rotates
                them in a cyclic manner. A six bit-plane
                brush can cycle through the six planes.
                The current 0 plane will be displayed.



  GRABHANDLE    xoff yoff

                Sets the handle for the current grab brush.
                Offsets are relative to the upper-left corner.



  GRABSTEP      size

                Sets the increment for the shifted 2, 8, 4, 6 keys
                in moving the grab handle.



  FREEGRAB

                frees memory used by grab brush



  SAVEGRAB      $filename

                disabled in DEMO version



  LOADGRAB      $filename



  POLYSCALE     x% y%

                sets scaling for polygons

                100 100 sets scaling to defined size
                 50  50 sets scaling to half size
                -100 100 flips x axis



  POLYANGLE     angle

                sets polygon rotation angle



  POLYCENTER    x y

                Sets center of rotation for polygon.
                The x and y values are relative to
                the first point of the polygon. The polygon
                will be drawn relative to the center.



  POLYASPECT    x% y%

                sets an aspect scaling in percent for the
                x and y dimensions of the screen.
                This helps to preserve the shape of
                rotated polygons in various display modes



  AUTOASPECT    ON|OFF

                During point entry if autoaspect is on
                points will be prescaled to current aspect setting.



  POLYSTEP      size

                sets step size of scale and rotation increments



  POLY          x y

                draws current polygon at x y using
                current scale, rotation and aspect settings.
                The polygon will be drawn relative to the CENTER
                setting.



  AREAPOLY      x y

                draws  FILLED current polygon at x y using
                current scale, rotation and aspect settings



  POLYSTART     x y

                Starts a polygon defintion



  POLYNEXT      x y

                Adds a point to the current polygon definition



  POLYCLOSE

                Ends polygon definition and closes it. If
                the 'polygon' is to be non-closed the this command
                need not be used.



  GETPOLYXY     point# x y

                result= x y

                returns the screen position of the given point
                as if the polygon had been drawn at position x y.
                Uses current scale, rotation and aspect settings.
                Points are numbered from 0 to N.



  GETPOLYCENTER

                result= x y

                returns the current center setting of the polygon.





  GETXY

                result= x y

                waits for a mouse click then returns
                x y position of click



  OKAY1         $string

                displays string in requester
                ` is used in string for the " character
                ~ is used for a newline character



  OKAY2         $string

                result= 0|1

                displays string then returns 0 if cancel hit
                or 1 if OK hit



  GETSTRING

                result= $string

                gets a string from  a requester



  GETINT

                result= integer

                gets a number from requester



  GETFRAME

                result= current frame number



  GETFRAMES

                result= number of frames in animation



  GETPOS

                result=  x y
                current turtle position



  GETH

                result= angle
                current turtle heading



  GETPEN

                result= 0|1
                0 if penup or 1 if pendown



  GETBRUSH

                result= 0-8
                current pixel brush setting



  GETCOLOR      reg

                result= r g b



  READPIXEL     x y

                result= 0|1
                0 if pixel OFF 1 if pixel ON



  SCANPIXELON   x y

                result= boolean(0|1) x
                if on pixel exists to right of x y: returns x
                position of next ON pixel to right



  SCANPIXELOFF  x y

                result= boolean(0|1) x
                scans for OFF pixel



  CHOOSE        number

                result= randnumber
                return number in range 0 to number-1



  TRANSPARENT

                sets colors to those saved by opaque



  OPAQUE

                sets colors of non-current frames to background
                and saves current colors



  LOADFONT      $fontname size

                Loads requested disk font



  FONTREQ

                Uses font requester for font load
                (Select both a fontname and size)



  FREEFONT

                Frees font from memory



  STYLE         $PBIU

                sets font to Plain Bold Italic or Underline
                if that upper case letter occurs in argument





BLITTER LOGIC



Values for blitter minterm logic should be of the form N*16 where N
ranges from 0 to 15. The destination of blits is always the current
frame. The source may be various objects, the grab-brush or the
tempframe buffer.  Rather than try to explain each minterm effect the
follow macro program gives a graphic example. This macro is designed
for a HIRES screen. It blits overlapping filled circles using the 16
different minterms. The output is much like Venn diagrams modeling the
blitter logic used.



/* blitm demo */



signal on error



first
clearframe
do j= 1 to 4
   do k= 1 to 4
      odisk 128*j 40*k 40 15
      end
   end

add
next
minterm= 0
do j= 0 to 3
   do k= 0 to 3
   grab 80+j*128 20+k*40 120 40
   blitm 64+j*128 20+k*40 minterm*16
   text  64+j*128 30+k*40 minterm*16
   minterm= minterm +1
   end
  end
exit

error:
 exit sigl





For more information or comments/problems contact:

    Martin C. Kees
    c/o SoftWare on a ShoeString
    1116 Road 68
    Pasco, Wa 99301


    bix:mkees