^CYBERMATE
See specific subjects.  See EFX,FORTH, OBJECTS,IMAGE,SEQUENCE,
SEQ-LOOP,STEREO-IMAGE,STEREO-SEQUENCE,SOUND,OPERATORS,FREE?
for a general overview of CyberMate.
^ME
Please be more specific.  See CYBERMATE, FORTH.
^FORTH
Forth is the core language that CyberMate is built around.
It is powerful, extensible and interactive.  But it can
be arcane as well.  Leo Brodie's books "Starting Forth" and
"Thinking Forth", both available in technical sections of good
bookstores, can help quite a bit in getting you over the learning
curve.

Forth is a stack-oriented language, and uses a stack like
HP calculators.  It also uses Reverse Polish Notation like those
calculators.

In this help file, most entrys are followed by a set of parentheses
that may look like:  ( src.l dest.l -- f ).

This describes what the function expects to receive on the STACK
and what it returns after it operates on the data it gets.  It is
quite similar to the notation in C when defining a subroutine:

int copy(src,dest)

Where the returned value is declared to be an integer, and two
operands are passed to the copy() function.

FORTH stack-notation for a similar function would look like:

COPY  ( src.l dest.l --- n )  Meaning that it expects 2 longs
on the stack and returns a result.

A FORTH "stack picture" like ( n1 n2 n3 ) means that n3 is on the
TOP of the stack, n2 is the next down, and so on.

To aid in understanding what the notation inside the parentheses means,
here is a list of Forth conventions.

             Stack Abbreviation       Meaning

		f			boolean, 16-bit value.  True=-1
					false =0
		n			signed 16-bit number
		u			unsigned 16-bit number
		chr			character.  16 bits; only lower
					8 are significant
		addr			address, relative to FORTH
					basepage (FORTH variables will
					use it)
		addr32			32-bit address; absolute address.
		d			32-bit signed number
		ud			32-bit unsigned number(same as
					addr32)
		var			Forth variable-address.
					(Single precision)
		2var			Forth variable-addrss.  Address
					contains a 32-bit value.

	NOTE:  sometimes, to make the significance of input values
	       clearer, the notation may look like:
	       ( src.l dest.l )  which means that two LONG values are
	       expected, which should be source and destination
	       addresses for the function to operate upon.

	A MORE COMPLETE EXAMPLE

         ZAP-DELTA     ( dest.l 2var n -- f )  This function expects
			an absolute 32-bit address, which is a
                       32-bit address (destination of frame-update), a
			variable that contains a 32-bit
                       address (contains a 32-bit pointer to
			source-data) and a signed
			16-bit offset, used to offset the frame-update
			in the display.
			The function returns a flag; TRUE (-1) if a
			frame update was performed, FALSE (0) if not.
			The only time the flag = FALSE is if the
			source-pointer is pointing at the end
			of the delta file when the function is called.


NOTES ON THIS FORTH IMPLEMENTATION
The Forth substrate currently being employed by Cybermate is a 16-bit
FORTH.  It is relocatable because all of it's internal addresses
are relative to the program's basepage address.  Thus, a variable
will have an "address" ranging from 0 to something less than
65536.  This has the advantage of not needing a special loader, and the
disadvantage of limiting the size of any application to smaller than
65536 bytes.

Because it is impossible to predict where the program will be loaded,
any machine-code routines linked to it MUST be
written in position-independent code.  This also introduces problems
when trying to access absolute addresses, like the palette
registers.  To allow this, Cybermate provides some special "absolute"
addressing modes.  These are:

         LC!  ( chr addr32 -- )  Stores a character or byte at the
         32-bit address.
         LC@  ( addr32 -- chr )  Fetches a character from 32-bit
         address.
         L!   ( n addr32 -- )    stores 16-bit value at 32-bit
         address.

NOTE: 16 and 32-bit accesses MUST
occur on even address boundaries.  NO error checking is done...that's up
to you.

         L@   ( addr32 -- n )   fetches 16-bit value from addr32
				location
         L2!  ( d addr32 -- )    stores 32-bit value at addr32
         L2@  ( addr32 -- d )    fetches 32-bit value from addr32.
         ADD-BASE ( addr --- addr32 )  Adds the base-address of FORTH
         to the 16-bit value on the stack.  Will
         convert relative addresses to absolute ones.
         Useful for doing I/O, etc.
By the way, a backslash in FORTH source-code tells the compiler that
the rest of the line is a comment.  Similar to /* ... */ in C,
REM or ' or ! in basic, depending on what flavor you use.
^OBJECT  See OBJECTS.
^OBJECTS
CyberMate has the capability of creating new object-types
like IMAGE, SEQUENCE, etc.  The method of creating new
"generic" objects will follow this general pattern:

         TYPE> newobject    \ define a generic object-type
         2 TVAR var1   \ define an internal 2-byte variable
         2 TVAR var2   \ etc.  you can define longer variables,
			\ arrays, etc, by preceding TVAR with larger
			\ numbers.  They MUST be even!
	...more variable declarations...
         : INIT object-initialization code ;  \ INIT is executed
whenever 'newobject' is used to create a specific instance of the object.

\ now, define operators that the new object will recognize as
\ valid.  For the object-type IMAGE, the operators SHOW1, etc, would be
\ defined here.
         : op1  your code ;
	 : op2  some more code ;
\ etc

         ENDTYPE> newobject  \ seal off the object so it's internal
\ definitions are hidden.

After all this is entered, you will get a 

" newobject NOT UNIQUE"
report, which is normal.  All the special operators and data-definitions
have been "sealed" inside a newobject....newobject pair in the
forth dictionary. But now, to create a specific instance of the
new object:

	newobject newinstance  <cr>

So, now "newinstance" is a specific instance of the newobject type.
It has it's own variable-storage area, so all the variables you
declared using TVAR will be unique to "newinstance".  INIT has run, so
any initialization will have been performed on that specific object's
variables.

Here's a concrete example:

	TYPE>  COMPLEX   \ define a generic object called COMPLEX
	2 TVAR REAL	\ define one variable called REAL
	2 TVAR IMAG	\ define another variable called IMAG
	: INIT 0 REAL ! 0 IMAG ! ;  \ initialization for object
	: COM! ( real imag -- ) IMAG ! REAL ! ;  \ complex store defined
	: COM@ ( -- real imag ) REAL @ IMAG @ ;  \ complex fetch def'd
	ENDTYPE> COMPLEX

Usage:  COMPLEX FFT
	FFT COM@ . .  ( to show that INIT has run.  CyberMate will
			print 2 0's )
	5 -1 FFT COM!
	FFT COM@ . .  ( at this point, CyberMate should print out
-1 5 ) to show that the operators COM@ and COM! work ).

This object-defining mechanism is the core of Cybermate's
IMAGE, SOUND, SEQUENCE, DELTA, SCRATCH-IMAGE, SEQ-LOOP,STEREO-IMAGE
and STEREO-SEQUENCE objects.  You can create your own
object-types, too, if you wish.

There are a few additional commands that are useful.  You can
create a "child" object by using the phrase

INCLUDE> parentobject  \ SEQUENCE uses:  INCLUDE> IMAGE, for instance.

immediately following the TYPE> command.  It will allow the child
to access all the functions and generic variables in it's parent;
but the parent cannot access the child's new functions or variables.

"parentobject" is a previously defined object-type, which can contain
it's own INCLUDE> statement, too.  Only one per object-definition is
allowed....but as you can see, a hierarchal pattern can be
established from more-primitive to more-sophisticated objects.  A type
of object evolution, from more primitive object to more sophisticated
ones.

The INIT command is executed every time a specific instance of an
object is created.  It is very useful for initializing data
structures, loading data from disk, etc.  It is very heavily used in
Cybermate, to load in all the necessary data for an image, sequence,
and so on.
^FREE?  ( -- )
Reports how much memory is available for animations.  It is
called whenever a CyberMate object is created.  If you want
to turn off the free-memory report (if, for instance, you show
a title screen while everything else is loading), do this:
' NOOP IS FREE? and the report will be disabled.  To reenable
it, do this:  ' (FREE?) IS FREE?. 

A note on.....
MEMORY-ALLOCATION...
When booted up, CyberMate requests all but about 8K of
available memory.  This is the memory that is available for
animation data. It includes all the object-types
(IMAGE,SEQUENCE,etc).  If you are so lucky as to have a computer with
4 megabytes, you can use ALL of the 4M, minus that used by the operating
system and accessorys minus 8,000.  That's a lot of animation!

In keeping with the interactive nature of FORTH, it is possible to
delete those objects and make the RAM available for more use later.
But there are some things you should know: indiscriminate usage
of some of the object functions ( RELEASE in particular) can
cause problems.  FORTH programmers will be familiar with the word
FORGET. It will simply erase a word, and all subsequently-defined
words, from the FORTH dictionary.  So if you enter:

	: JUNQUE ." THIS IS JUNK" ;
	: MORE-JUNQUE ." SO IS THIS " ;
	FORGET JUNQUE

You will have created two new entries ("words") in FORTH,
then deleted JUNQUE from the dictionary.  But because MORE-JUNQUE
was defined after JUNQUE, MORE-JUNQUE will also be deleted.
The RELEASE word in CyberMate is a similar beast.  If you create
two image-objects, let's say IMAGE1 then IMAGE2, and then enter:
IMAGE1 RELEASE you have shifted the free-memory
pointer that CyberMate keeps back to the location that was
occupied by IMAGE1.  But because IMAGE2 was defined later, it's data is
now suspect; ANY new object would cause it's data to be corrupted.

To get around this somewhat, the NEW! and FREEZE commands
were defined. The NEW! command deletes ALL objects up to the
last-executed FREEZE command, and releases their RAM back to
the memory-handler. FREEZE just sets the limits of NEW!  But it
still is possible to use RELEASE and get into trouble;
Releasing an already-released object won't cause any problems,
but releasing an earlier-defined object and then a later-defined
object would cause a problem. It would move the free-memory pointer
back, then forward, but leave the earlier-defined object in it's
released state.  An attempt to use that object would produce unpredictable
results.
^STEREO-IMAGE  ( -- )
An object-defining word.  It acts exactly like IMAGE, but if
ENABLE-STEREO and STEREO ON have been called successfully,
the image will be shown in stereo...if the viewer has 3D glasses.
See IMAGE
^STEREO-SEQUENCE ( -- )
An object-defining word.  It acts exactly like SEQUENCE but in stereo,
if the viewer has 3D glasses.  No check is done to see if that is
the case.  See SEQUENCE.
^SEQUENCE        ( -- )
An object-defining  word. It
takes care of all memory allocation and data initialization.
For valid operators, see OPERATORS and the separate entrys for each
operator.
^BUFFERING-ON ( -- )
Initializes double-buffering mode.
Allocates an additional 32K buffer that serves as the "logical"
graphics output-area. 
NOTE:  until a BUFFERING-OFF call is made,
<<<ALL>>> GRAPHICS OUTPUT IS TO THE BUFFER.  NO output will be
seen in this mode  until an UPDATE-DISPLAY call is
made, which copys the display buffer to the output buffer area.
So if you enter BUFFERING-ON from the keyboard, the system will
appear to "hang"; but it is really still working but directing
all output to the buffer.
See BUFFERING-OFF, UPDATE-DISPLAY, DISP-PTR.
^BUFFERING-OFF ( -- )
Disables double-buffering.  Does
not release the second display buffer.
^UPDATE-DISPLAY ( -- )
Copys the contents of the logical-display buffer created by
BUFFERING-ON to the display area currently being used for video output.
(the physical display address).
^DISP-PTR   ( -- addr )
A double-precision variable that
contains the address of the display buffer, when double-
buffering is enabled.  To release the memory back
to the memory handler, this sequence will work:
DISP-PTR RELEASE-MEM <cr>.
^DELTA          ( -- )
An object-defining word.  It loads in a .DLT file ONLY.
Valid operators:  NEXT-FRAME,UPDATE,START,STOP,RATE,RESET,RELEASE,
TO-NTH-FRAME,OFFSET.
^NEXT-FRAME( -- f )
An object operator for SEQUENCE,SEQ-LOOP,DELTA,STEREO-SEQUENCE.
Does a frame-update, if the data-pointer for that object
is pointing at a valid frame.  The data-pointer is handled internally
by the object. The only user command that affects it directly is
RESET, which sets it back to the start of the animation data.  It returns
TRUE if the next-frame operation went ok, FALSE if it hit the end
of the animation data.
^TO-NTH-FRAME ( N -- ) 
An operator for DELTA objects.
Sets the internal data-pointer to the nth frame.
If N > total # of frames, no action is taken.
^SCRATCH-IMAGE ( -- )
An object-defining word.  All IMAGE operators work for SCRATCH-IMAGE.
One additional operator is just for SCRATCH-IMAGE.  It is XFER,
and is used to copy all palette-data,image-data and color-cycling
data from an IMAGE or any object that contains an image.

EXAMPLE:

		SHIP PALETTE-DATA \ source-image
		JUNK PALETTE-DATA \ scratch-image
		XFER		  \ transfer all image-data to 'JUNK'

SCRATCH-IMAGE creates a buffer the same size as an IMAGE object.  Used
for expanding .PC? files or for image manipulation.  See EXPAND-IMAGE.
^EXPAND-IMAGE ( addr32 -- )
Expands a .PC1 or .PC3 image. Expects a 32-bit destination address;
uses the next word in the input stream as the sourcefile name.
		EXAMPLE:

		SCRATCH-IMAGE PUP  \ define a destination
		PUP PALETTE-DATA   \ get the destination-address
		EXPAND-IMAGE PUPPY \ expand PUPPY.PCx from
\				     currently-selected
\				     data path, where n is 1 or
\				     3, depending on the
\				     display-resolution.
^NEW!  ( -- )
Forgets all objects defined since the last FREEZE command, and
releases their memory back to the system where it can be reused.
Also removes any dictionary definitions introduced since the last
FREEZE.  See OBJECTS?, FREEZE,FORGET.
^FREEZE ( -- )
Sets a limit for NEW!  After a FREEZE, any objects defined prior
to it will be safe from a NEW!.
Cannot be reversed, so use with care.
^MAKE-BOOT ( -- )
Used to produce a runtime-only package, for standalone animations.
^SEQ-LOOP ( -- )
Object-defining word whose parent is SEQUENCE.
Operators unique to SEQ-LOOP are:
REPEAT,LOOP-MODE.  SETUP-LOOP, which is NOT an operator, can
be used to define the start and stop frames of a SEQ-LOOP
during it's creation.
^REPEAT ( N -- )
Operator for SEQ-LOOP. Set # of times the loop should
repeat. If the seq-loop is set to run forwards and
backwards, N sets the number of full first-last-first
cycles. See LOOP-MODE.
^LOOP-MODE ( mode -- )
Operator for SEQ-LOOP. Tell the UPDATE routine for seq-loop whether to
go forward, then back,(f=0)  or forward-only ( f=-1).
^SETUP-LOOP  ( n1 n2 -- )
Defines the start (n1) and stop (n2) frame for a SEQ-LOOP.  It
is NOT an operator, but the two numbers will be used in the
NEXT SEQ-LOOP created.
^OFFSET->COORD ( n -- x y )
Converts an offset to it's x and y pixel address equivalent.  Does not
produce proper value for monochrome.
COORD->OFFSET ( x y -- n )
Converts x & y coordinates to offset value.

NOTE:  the offset value and the x & y values will be treated as
offsets from the original frame-update location on the
screen, NOT as the absolute location for frame-update to occur.
^VIEW   ( -- )
A simple preview facility.  But is is complex enough that you are
directed to the discussion about it in the full CyberMate Doc file.
^ADVANCE ( addr32 -- )
?????
^SOUND ( -- )
An object-defining word.  It uses .SND files created by GIST
for generating sound effects.  Valid operators are:
RELEASE, VOLUME, PITCH, STOP, START,RESET.  SOUND objects have
a different creation-mode than any other objects, because it
was thought that they would be re-used several times in an
animation.  SOUND checks the stack during object-definition for up
to 5 trigger-points (in Cybertime).  So if you wished a sound to
be triggered at, say, 0,50,100 and 200 (in ticks), you would enter:
            200 100 50 0 SOUND WHAM
Also, a sound object will cause an exit from a TICK...TOCK loop
if it is the last-executed object before TOCK and the cyber tick
number is greater than the STOP value for the sound.  This is
identical to what a SEQUENCE,SEQ-LOOP,or STEREO-SEQUENCE object
does.  To figure out if your sound is a sound-effect or a
pitch, see SOUND-VS-PITCH.
^VOLUME ( n -- )
n= 0-255
Set volume of sound.  If volume = -1 (default), it
is determined by the sound-effect parameters set by GIST.
^PITCH  ( n -- )
Set pitch of sound effect.  If -1, it is assumed to be a sound effect,
not a tone; if pitch is >0, the sound will decay to the sustain-value
designed by GIST and stay there until the sound is turned off.
Then the sound volume will decay at a rate determined by the release
parameters (also created by GIST). Default value: -1.
^PRIORITY ( n -- )
n=0-255.
Higher priority-sounds will play "on top of" lower priority sounds.  On
initialization, the priority of a sound is set to 128.
^VOICE ( n -- )
n=0-2.
Choose which voice to use for the sound effect.  if voice= -1
(initial value), the sound driver chooses the next-available
voice. Default value: -1.
^START ( n -- )
An opeator, sets the start of an object's action, in cybertime (ticks).
^STOP  ( n -- )
An operator, sets the end of an object's action in cybertime;
Sets the point at which the release-mode of a pitch-tone begins.
Not valid for sound EFFECTS, because the duration of a sound-effect
is set by the parameters in the .SND file for the effect.
NOTE:  see TOCK.
^RESET ( -- )
Resets an internal pointer in a SOUND object so it can be replayed.
See SOUND-VS-PITCH.
^SOUND-VS-PITCH
The GIST sound-effects driver can operate in
two distinct modes.  The first is the straight sound-effects
mode, which takes ALL necessary data from the .SND file...including total
duration of the sound effect.  The second is the synthesizer mode, which
acts like a keyboard instrument:  the attack and sustain levels are set
by the .SND file, but the sustain length is set by the user...in this
case the START and STOP values.  Since it is likely that a sound
EFFECT may be used several times in an animation, the SOUND
object is defined in a unique way.  In fact, it is the only one
that checks the depth of the stack before doing some things.
If the stack has nothing on it, the sound object is treated like
a synthesizer-sound:  the user can define the duration.
BUT if the stack has up to 5 values on it, the
sound INIT routine takes those values as TICK numbers: when
Cybertime equals one of those values, the sound-effect is triggered.
Just to keep things confusing, the times are assumed to be in reverse
order: the last item on the stack is the FIRST trigger-time, and so
on.  This is a consequence of FORTH's stack-oriented approach, and
programmer laziness.  The RESET command simply sets an internal pointer
back tothe first entry in the trigger-array.
^OBJECTS? ( -- )
Prints a list of currently-defined objects.  Will be incorrect if a
RELEASE was done to an object. See NEW!, FREE?
^TOCK  ( -- )
TOCK is the terminating section of a loop.  It checks the state
of the variable END-FLAG.  If it is TRUE, the loop is exited.
END-FLAG can be set TRUE by two conditions:  a keypress or
a cyber-time tick# past an object's STOP value.  Each object in a
TICK...TOCK loop will set END-FLAG to TRUE or FALSE depending on
the tick# and the STOP value.  So the last-executed object before
TOCK will be the one that forces an exit from the loop.  So, if
you have several objects with different STOP times, order them so
that the one you wish to force an exit from that loop is just
before TOCK.  See TICK,CYBERTIME,KEY-BRK
^KEY-BRK ( -- addr )
A variable that is checked by TOCK.  If it is
TRUE, the keyboard is checked and the loop is exited if any key has been
pressed.  This will work even if END-FLAG is FALSE.  USAGE:
		KEY-BRK OFF  \ disable keyboard-break, for
			     \ standalone animations.
		KEY-BRK ON   \ reenable keyboard-break function.
^CYBERTIME
Cybermate keeps track of time by using "tick" numbers.  Each pass
through a TICK ..... TOCK loop is one tick.  Since the routines that
produce a new frame execute very quickly, this usually means that
Cybermate must slow things down.  This is where the RATE operator
comes in.  It defines how many ticks must go by before the next frame
of a sequence or seq-loop is generated.  This seems more complicated than
necessary, but it allows the animator to run different animations
at different rates....SIMULTANEOUSLY.  Obviously, if a frame-update
for one animation sequence takes a while, it will affect overall
loop time; so cyber-time is somewhat relative.
Cybermate increments the tick number in the TOCK word, and in fact
you can access cybertime, yourself; it is kept in a variable called
TICK#.  There are several additional functions for using or manipulating
Cybertime.  See TICK:, <TICK, =TICK, >TICK, and ZERO-CLOCK
^TICK ( -- )
Marks the beginning of a loop.
It is the same as the Forth BEGIN statement, but
it also sets END-FLAG to FALSE.  This
word is a compile-only; it cannot be used in an immediate
mode.  TICK-TOCK loops can be nested.
^FIND-END ( -- n addr32 )
A SEQUENCE operator. addr32 is the address of the end of the
last frame, and n is the number of frames-1.  For special animation
effects.  SQUENCE,SEQ-LOOP,STEREO-SEQUENCE operator.
#FRAMES ( -- n )
N is the number of frames-1 for
the sequence.  SEQUENCE,SEQ-LOOP,STEREO-SEQUENCE operator.
^RESET ( -- )
Set the frame-pointer back to the first frame.
SEQUENCE,SEQ-LOOP,STEREO-SEQUENCE operator.
^RATE ( n -- )
Set the frame-rate to 1 frame for every n Cyber clock "ticks".  Thus, a
rate value of 100 will run 1/10th as fast a rate of 10.
SEQUENCE,SEQ-LOOP,STEREO-SEQUENCE operator.
^UPDATE-MODE ( addr -- )
Sets the frame-update mode.  The address is the execution address
of an update routine, which is  obtained with the ' (tick)
function.  USAGE EXAMPLE:
		' ZAP-DELTA HOOPS UPDATE-MODE \ immediate mode.
sets update-mode for HOOPS to ZAP-DELTA.
: SETUP ['] ZAP-DELTA HOOPS UPDATE-MODE   ; \ compiled mode example.
Any frame update routine will be passed the following data on the stack:
		( dest32 addr offset )
and must remove them, then place a TRUE or FALSE value on the stack.
TRUE is for the case of a successful frame-update
and  FALSE for an unsuccessful update (perhaps the last frame has been
reached).
Dest32 is the 32-bit address where the frame-update will occur
and "addr" is the address of a variable which contains the frame-update
address.  This variable is automatically updated in the
frame-update routines supplied with Cybermate.
The last parameter, "offset", specifys an x-y offset that will
be added to the update-address; so to move the frame-update
location up by one line you could specify an offset
of 0,-1.
^FRAME-DATA ( -- addr32 )
A SEQUENCE,SEQ-LOOP,STEREO-SEQUENCE operator. Returns a pointer to it's
next-frame data.
^DELTA-DATA ( -- addr32 )
Returns a pointer to the first frame.  Useful for advanced animation
and add-ons to CyberMate.
^FRAME ( addr32 -- )
Sets the next-frame pointer to
addr32 value. (WARNING:  if misused, can easily cause system crashes!)
^NEXT-FRAME ( -- flag )
Executes the frame-update function, advancing the frame-pointer.
Flag = TRUE if frame-update was possible, otherwise false.  This
operator functions the instant it is called, unlike UPDATE.
Does not set END-FLAG.
^UPDATE ( -- )
Frame-update operator used in animation sequences.  It uses the value set
by RATE to establish a frame-rate, and the values set by START and STOP
( see IMAGE ) to define the beginning and ending tick# for the
sequence.  It sets END-FLAG if the Cybermate tick# is greater
than the value set by STOP, or if the frame of the animation
has been reached.
^SETUP? ( -- )
Prints # of frames encompassed by the START and STOP values, The STARTing
tick# and the RATE.
^SETUP ( start stop# rate  -- )
Sets the RATE and adjusts STOP and START for start frame and end-frame.
This will set the ending frame of the sequence to n, and it will
begin on the STARTth tick#.
^END-FRAME ( n -- )
Sets the end-frame of the sequence to the nth one.  Uses the value defined
by START as the beginning tick#. Non-destructive, it can be
changed "on the fly".
^RELEASE ( -- )
Releases all object storage to the CyberMate memory handler.
The object still appears in the dictionary and
in an OBJECTS? call, but it's mostly gone.  To completely 'zap' it,
enter FORGET obname <cr>   <<<AFTER>>> releasing it.
^CHAIN-WITH ( -- )
Takes the next word as the name of another delta file to
chain with a sequence.  The data MUST be contiguous
with the frame-update data for the seqence so the CHAIN-WITH
function must be used immediately after defining
the primary sequence.  No other objects can be created inbetween.
It checks for this, too.   EXAMPLE:

	SEQUENCE HOOPS  \ create primary object HOOPS
	HOOPS CHAIN-WITH HOOPSB \ chain HOOPS with delta file
\				  HOOPSB.DLT

^CLONE-AS ( -- )
A very powerful operator.  Most of the sequence information
(set by RATE, STOP, START, etc ) is copied into a new object, then
given a different name (the one immediately following the CLONE-AS
operator). The image data and frame-update data are NOT copied, so the
result is another sequence object that uses the animation
data, but can run at different rates, witH different update-modes,
starting and ending tick numbers, etc.  Because only a relatively
small amount of memory is needed to define the cloned object, this
is a method to increase the apparent complexity of an animation at
low memory cost.

	EXAMPLE            HOOPS CLONE-AS WHOOPS
			   ' ZAP-DELTA WHOOPS UPDATE-MODE
			   50 WHOOPS START
			   ' SMEAR-DELTA HOOPS UPDATE-MODE
			   : BLUR ZERO-CLOCK HOOPS RESET WHOOPS RESET
			     HOOPS SHOW1 TICK HOOPS UPDATE
			     WHOOPS UPDATE TOCK ;

This example shows an application that simulates motion blur.
The cloned object (WHOOPS) is delayed in time, so it follows the
parent object. The update modes are chosen so that the parent object
leaves a trail, which is then 'zapped' by the cloned object.
This method is not very faithful to true motion blur, but it does
produce an interesting and useful effect.
^IMAGE ( -- )
An object-defining word.  The parent of SEQUENCE, SEQ-LOOP, etc.
It has no parent. See OPERATORS for valid operators.
^START ( n -- )
Defines the tick# that will begin object operation in a TICK...TOCK
loop.  For an image object, the proper operator would be:
imagename REVEAL.  For a sequence type object, it would be
UPDATE.
^STOP ( n -- )
Defines the tick# at which a sequence type animation will terminate.
If an image-object is used (as in imagename REVEAL), it will define the
tick# at which the image-mode function will again run.  If the image mode
is an xor-type function, this will cause the image to disappear.  See
XOR-COPY, XOR-DISSOLVE,DDA-DISSOLVE (all EFX devices).
^IMAGE-MODE ( addr -- )
Sets the function used to copy image data of an object to the currently
selected logical-output screen.  It expects the execution address
of a copying effect on the stack.  USAGE:

		' COPY PUPPY IMAGE-MODE  \ image object is PUPPY
		' XOR-DISSOLVE PUPPY IMAGE-MODE \ use a dissolve
\						  function

		: INSIDE ['] OR-COPY PUPPY IMAGE-MODE ; \ define the
\ image mode inside a colon definition.
See EFX.
^EFX
IMAGE, SEQUENCE, DELTA, SCRATCH-IMAGE, SEQ-LOOP, STEREO-IMAGE,and
STEREO-SEQUENCE objects use image effects for generating the actual
image.  For images, various types of copy functions are used, including
xor-copy, opaque copys, transparent copys, dissolves, etc.
These copy functions are available for any object that includes an image
as part of it's data (all the above objects).  To define which type of
image effect will run when any SHOW or REVEAL word is used, the following
is used:
		' effect obname IMAGE-MODE
so if you have loaded in an IMAGE called PUPPY and wish to use
XOR-DISSOLVE for the image effect, enter this......
		' XOR-DISSOLVE PUPPY IMAGE-MODE.
To do this inside a colon definition remember that ' must be replaced
by ['] .

The same holds true for objects that contain animation data.  You can
define different kinds of frame-update effects for different objects,
and more are being created all the time.  Useful additions include
wipe functions, expansion routines for compressed animations,
.SEQ expanders, etc.  Here is a list of image and animation effects that
currently reside in CyberMate.  NOTE:  the functions given here really
expect some data on the stack, but the objects pass it transparently.
You only need to worry about it if the effect requires some additional
information.  Only a few do.

Image-effects:

COPY	( -- )	An opaque copy. Completely replaces every pixel in
		the screen with the new image.

OR-COPY	( -- )	Merges the image with what was already there.

XOR-COPY ( -- ) XORs the image with the currently-displayed image

COPY-CLIP ( x y -- )  Xor-copys an image, but displaced by x & y
		coordinates.  X coordinates are clipped to multiples
		of 16 so that the OFFSET function for animations will
		work.  With this, you can create animations of things
		that are displaced from their original "compiled"
		locations.  Very useful for cloned objects.

DISSOLVE (-- ) Like COPY, but uses a pseudo-random technique to copy
		individual pixels to the screen.  Completely replaces
		every pixel in the screen with the new image.

XOR-DISOLVE ( -- ) Like XOR-COPY but XORs individual pixels to the screen.
		If used twice on the same image, it will dissolve-in,
		then dissolve-out.

DDA-DISSOLVE ( seed rate -- )  Allows some customization of dissolves.
		The 'seed' will produce different pseudo-random dissolves
		at a speed given by 'rate'.  The seed value, due to the
		algorithm used, must be an odd value (1,3,5...).  It
		also dissolves bytes rather than individual pixels, so
		it executes faster than the other dissolve routines.

Because COPY-CLIP and DDA-DISSOLVE require more data than the other
image effects, it is necessary to use them in a different way.
You must write a simple routine that places the additional data on the
stack, then calls it.  An example:

	: NEW-DISSOLVE 17 32 DDA-DISSOLVE ;
	' NEW-DISSOLVE HOOP IMAGE-MODE

So you have defined NEW-DISSOLVE to be the image effect for HOOP, and
"fed" DDA-DISSOLVE the necessary information inside NEW-DISSOLVE.

Frame-update effects:

DO-DELTA ( -- f ) The core frame-update routine. An xor
		operation is done on the destination so that the
		animation can run backwards if wished (used in
		SEQ-LOOP objects ). f= TRUE if the frame-update was
		successful, otherwise FALSE.

DO-DELTA1 ( --f ) Updates all bitplanes except the most-significant.  An
		attempt at producing fainter images of a main animation.
		Returns a flag like DO-DELTA.

SMEAR-DELTA  ( --f )   Uses an OR type of logical operation so animations
		leave a trail".

ZAP-DELTA  ( -- f ) Uses the data in the .DLT file to "zap" locations in
		the image where the animation goes.  Used behind
		SMEAR-DELTA, it will clean up after and produce the effect
		of afterimages disappearing behind the main object.  A
		simple motion "blur" effect.
^SHOW1 ( -- )
Sets resolution to LOW, copys the image palette data to the palette
hardware registers and the image data to the currently- selected LOGICAL
screen location.  Uses the copying mode set by IMAGE-MODE.  SHOW1 clears
the screen because it calls an Xbios routine to set the resolution, and
that function clears the screen.
^SHOW2 ( -- )
Copys the image data to the logical screen location using
the copy function defined by IMAGE-MODE. Does not set resolution
or palette, so the screen is not cleared.
^SHOW3 ( -- )
Sets palette and copys the image but does NOT set the resolution.
^SET-PALETTE ( -- )
Just sets the hardware palette registers.
^CYCLE ( -- )
Uses color-cycling information (DEGAS ELITE format) to begin color-cycling
animation. To turn the color cycling off, use CYCLING-OFF.
CYCLING-OFF can be executed as a standalone word; it is not an operator.
^CYCLING-OFF ( -- )
Turns color cycling off.
^ZERO-CLOCK ( -- )
Sets the contents of TICK# to zero. ( Resets Cybertime to zero.)
^TICK:      ( -- n )
Places current cybertime, in ticks, on stack.
^<TICK      ( n -- flag )
Returns TRUE if n is less than current cybertime.
^>TICK      ( n -- flag )
Returns TRUE if n is greater than current cybertime.
^=TICK      ( n -- flag )
TRUE if n equals cybertime
^TYPE>      ( -- )
Begins an object type-definition.
^ENDTYPE>   ( -- )
Ends object type-definition.
^INIT       ( -- )
When defined inside a TYPE> ...ENDTYPE> ( as in  : INIT init-code ;  )
pair, this word will be called whenever a specific instance of the object
is created.
^INCLUDE>  ( -- )
Allows inclusion of a parent object's operator and data repertoire
so that common data types and functions can be inherited, rather than
redefined.  Allows evolutionary growth of more-complex objects from
simpler objects.
^TVAR ( n -- )
Sets up a generic variable for an object.  It reserves n bytes of storage.
^OPERATORS
In CyberMate, objects that have been created using object-creating
words like IMAGE, SEQUENCE, etc, can only be manipulated by specific
operators.  Any attempt to use the objects in a non-standard way will
produce an error message.  But the real power of operators is not in
error-checking but in hiding the messy parts of the implementation...
and making the functions easier and more intuitive to use.
The following table is a list of all the operators and which objects
they work with.  A column entry with a * indicates that the operator
is valid.

SND=SOUND; IMG= IMAGE SEQ=SEQUENCE ST-IMG = STEREO-IMAGE
ST-SEQ = STEREO-SEQUENCE DLT = DELTA.
NOTE:  ALL IMAGE FUNCTIONS FOR IMG WORK FOR SCRATCH-IMAGE.

_____________| SND | IMG | SEQ | SEQ-LOOP | ST-IMG | ST-SEQ |  DLT | 
  SHOW1      |     |  *  |  *  |    *     |   *    |   *    |	   |
  SHOW2      |     |  *  |  *  |    *     |   *    |   *    |      |
  SHOW3      |     |  *  |  *  |    *     |   *    |   *    |	   |
  REVEAL     |     |  *  |  *  |    *     |   *    |   *    |	   |
  IMAGE-MODE |     |  *  |  *  |    *     |   *    |   *    |	   |
  START      |  *  |  *  |  *  |    *     |   *    |   *    |	*  |
  STOP       |  *  |  *  |  *  |    *     |   *    |   *    |	*  |
  CLONE-AS   |  *  |  *  |  *  |    *     |   *    |   *    |	*  |
  CYCLE      |     |  *  |  *  |    *     |   *    |   *    |	   |
  PITCH      |  *  |     |     |          |        |        |	   |
  VOLUME     |  *  |     |     |          |        |        |	   |
  VOICE      |  *  |     |     |          |        |        |	   |
  OFFSET     |     |  *  |  *  |    *     |   *    |   *    |	*  |
  CHAIN-WITH |     |     |  *  |          |        |        |	*  |
  NEXT-FRAME |     |     |  *  |    *     |   *    |   *    |	*  |
  UPDATE     |     |     |  *  |    *     |   *    |   *    |   *  |       
  RATE       |     |     |  *  |    *     |   *    |   *    |	*  |
  SETUP?     |     |     |     |    *     |        |        |	*  |
  MODE       |     |     |     |    *     |        |        |	   |
  REPEAT     |     |     |     |    *     |        |        |	   |
  #FRAMES    |     |     |  *  |    *     |   *    |   *    |	*  |
  TO-NTH-FRAME|    |     |     |          |        |        |    * | 	
^THE-END
Thaaaaaats all folks!!!!!!!
^ 
