|f2|c7|t1The Enhanced Blit Utility|f1|c3|t0

The Enhanced Blit Utility (|c7|-EBU|c3|-) is a tool to help you 
generate Director
commands, and in some instances, complete scripts.  Like the original
Blit Utility provided on the Director disk, it can be used to automatically
generate coordinate values for |c7BLIT|c3 commands.  In addition, 
|c7EBU|c3 has a 
vastly improved user interface utilizing another tool provided on the 
Director ToolKit disk, the file requester.|r1

|c7EBU|c3 futher improves over the original Blit Utility's capabilities 
by also generating |c7DISSOLVE|c3 and |c7WIPE|c3 commands.  |c7EBU|c3 also 
allows
you to specify a command or two to be added to multiple |c7BLIT|c3 commands,
a feature indispensable when you are doing several |c7BLIT|c3 commands and
would like to do, say, a |c7PAUSE|c3 after each one.
|e

Beyond these basic command generation capatilities, |c7EBU|c3 allows you to
configure movement of an object over a background, generating a complete
working script.  Further, you can create an animated object, or 
|c7character|c3 to be moved.|r1

It may be important to note that the |c7EBU|c3 utilities are of limited 
usefulness with |c7HAM|c3 images.  While all of the functions will 
work, |c7HAM|c3 
screens tend to exhibit visible side effects due to the way the |c74096|c3 
color capability is provided in the hardware.  |c7HAM|c3 paint programs that 
you may be familiar with resolve such problems via a time-consuming 
computation that resolves the edges of a |c7"brush"|c3 with the background 
at the time it is placed.  
|e

Unfortunately, this edge resolving operation is slow and cannot take place 
at animation speeds, so the Director does not attempt to perform such 
an operation.  This will likely result in visible |c7HAM|c3 "fringing" 
effects when you use the |c7EBU|c3 on |c7HAM|c3 images.  Certain 
operations can be performed
successfully however, though it depends greatly on the effect desired
and your familiarity with the characteristics of |c7HAM|c3 images.  While a 
|c7HAM|c3 characteristics tutorial is beyond the scope of the
Director ToolKit,
it never hurts to experiment.  You may wish to cut your teeth on 
the |c7EBU|c3 with non-|c7HAM|c3 images first however, so you can 
see how it works without potentially distracting |c7HAM|c3 side effects.
|e


In addition, you may have to be a little careful when using |c7Hi-Res|c3
screens.
The object move script generated requires 4 |c7CHIP|c3 buffers, and 
you will be 
unable to load |c74 Hi-Res 16 color|c3 buffers into 
|c7512K|c3 of |c7CHIP RAM|c3|-.  You can
drop down to fewer colors, but tread with caution, as |c7EBU|c3 itself, 
written 
in the Director, will abort if an out-of-memory error occurs.
|e

Let's explore |c7EBU|c3|-'s main screen.  Below the title area are three 
long buttons, labeled:|r1

|c7|+8|t1|f2Generate BLIT/WIPE/DISSOLVE
|+8Generate A Moving Object
|+8Build A Character|t0|c3|f1

These buttons select the three main |c7EBU|c3 functions.|r1

Below the selection buttons, there is a text |c7"gadget"|c3 labeled 
|c7"Background File"|c3|-.  At any time, you can click on this gadget and
a file requester will appear allowing you to select an |c7IFF|c3 image
file to be used as a background image for your movement or |c7BLIT|c3
command.
|e

In the upper right corner of the gadget, is a box that displays the
buffer number to be used by the background image.  You can click in
this box to change the buffer number if desired.  If you are starting
a new Director script, you can probably just leave this alone as it
will already contain a default value which should work fine for a new
script.|r1  

If you are going to be incorporating the |c7EBU|c3|-'s output 
commands into an 
existing script, you may wish to select buffer numbers that will not 
conflict with any you may wish to keep, or in the case of |c7BLIT|c3 command
generation, the actual buffer numbers the |c7IFF|c3 images will be 
loaded into by your existing script.
|e

|c7EBU|c3 object move scripts use 
buffers |c728|c3 and |c729|c3 to double buffer.  This is
easy to change by modifying these two values at the beginning of the 
script that is produced if there is a conflict with buffers you may already
be using.
|e

Below the |c7"Background File"|c3 gadget, is a similar gadget labeled
|c7"Object File"|c3|-.  Like the |c7Background File|c3 gadget, you can click 
on this at any time to select an object file to be used.   Also like 
the |c7Background File|c3 gadget, there is a box in the upper right corner 
that displays the buffer number to be used by the object image.|r1

Below the |c7"Object File"|c3 gadget, is the |c7"Output File"|c3 gadget.  
This gadget contains the file name of the script file to be 
output by |c7EBU|c3|-.
The default file name for the output file is |c7"ram:ebuout"|c3|-.  You 
can click on this gadget to change the output file name.  
|e

Connected to the lower part of the |c7"Object File"|c3 gadget are two 
buttons labeled |c7APPEND|c3 and |c7CLEAR|c3|-.|r1  

Clicking on the |c7CLEAR|c3 button will erase any previous script file 
information in the file by the name appearing in the |c7Object File|c3 
gadget.  You can use this button to clear out the output file in the
event you make a mistake and want to start completely over, or if
you change your mind about what you wanted to do.  When you click on
the |c7CLEAR|c3 button, an |c7"Are you sure?"|c3 message will 
appear and you are
then required to click on the |c7YES|c3 or |c7NO|c3 button, to make 
sure you
really want to delete all the information contained in the Output File.
|e

Clicking on the |c7APPEND|c3 button will cause an |c7asterisk|c3 to be 
displayed
next to the |c7APPEND|c3 button, indicating you are in the append mode.  In
this mode, |c7EBU|c3 output commands will be added to the end of any existing
output file, instead of a new file started from scratch as is the case
when you are not in the append mode.  This can be useful if you want
to add more |c7BLIT|c3 commands to the end of a file you had created in an
earlier session with |c7EBU|c3|-.  Be careful though; when used with object
move generation, it can produce confused scripts that will not run
directly.
|e

In the lower left corner of the |c7EBU|c3 screen, the number of 
|c7BLIT|c3|-'s and MOVEs
generated are counted and displayed.|r1

In the lower right corner of the |c7EBU|c3 screen, is the |c7DONE|c3 
button.  Click on
this button when you have finished using |c7EBU|c3|-.
|e

Now let's explore the main selection buttons.|r1

You will notice that when you click on any of the three main selection
buttons, the menu button area will change, displaying new buttons for
use within the chosen selection.  From these new button |c7"menus"|c3|-,
you can always return to the main button screen by clicking on the button
in the upper left labeled |c7MAIN MENU|c3|-.
|e

The top three buttons in all of the main selections are all the same,
these are:|r1

|+6|c7MAIN MENU|+5PICK OBJECT|+4TRANSPARENT|c3|r1

We've described |c7MAIN MENU|c3 above.  |c7PICK OBJECT|c3 is used to select a
rectangular area that outlines your object to be used.  |c7TRANSPARENT|c3
will toggle transparent mode on and off.  
|e

When in |c7PICK OBJECT|c3|-, if an object file has not been 
selected, |c7EBU|c3
will pop up the file requester so one can then be selected.  Once
an object file is available, |c7EBU|c3 will then display the file, allowing
you to place a box defining the rectangular area that encompasses your
selected object.  Note that you do not |c7click-and-drag|c3 the mouse to 
place your box, you should use |c7two specific clicks|c3|-, one for the upper
left and one for the lower right corner of the box.  Once the box appears,
you can readjust either corner of the box by clicking near the corner to
be adjusted.  The box will be redrawn to reflect the new clicked upon
location.
|e

When in |c7TRANSPARENT|c3 mode, the buttons lettering will become pink.  
In |c7TRANSPARENT|c3 mode, any pixels that are color |c70|c3 in the 
rectangular 
object area, are treated as |c7"transparent"|c3|-, that is, they are not 
transferred with the image.  When doing a move, the Director's 
|c7TRANSPARENT|c3 command is added to the script automatically. 
When using 
the |c7Generate BLIT/DISSOLVE/WIPE|c3 capabilities which do |c7not|c3
generate a complete script, it is assumed that the
|c7TRANSPARENT|c3 command will be added appropriately to your script by you.
See the Director's manual for more details on the |c7TRANSPARENT|c3 command.
|e

|c7|f2Generate BLIT/WIPE/DISSOLVE|f1|c3|r1

If an object has not yet been |c7"picked"|c3|-, the lower three buttons in 
this mode will be blank.  This indicates that these selections are not
available until an object has been picked.  After you have used 
|c7PICK OBJECT|c3 to select an object, the button labels 
|c7DISSOLVE|c3|-, |c7BLIT|c3|-, and |c7WIPE|c3 appear.|r1  

Below these buttons, the word |c7Postfix:|c3 is displayed.  If you wish to 
have |c7EBU|c3 automatically add a command or two to the end of 
your |c7BLIT|c3|-, |c7DISSOLVE|c3 or |c7WIPE|c3 commands, you can 
click on this area and type the command(s) in.
|e

For example, if you type |c7"pause p"|c3 in the |c7Postfix:|c3 area, all 
commands you generate will look something like this:|r1

|+8|c7BLIT 3,23,75,88,90,12,22:pause p|c3|r1

If you then plan to generate several related |c7BLIT|c3 commands, all with 
pauses, you can then set the variable |c7p|c3 to adjust the delay 
time between |c7BLIT|c3|-s.  Or you could use |c7GOSUB 100|c3 to add 
a gosub to a double buffering
routine or other routine you wish to run after every |c7BLIT|c3|-.
|e



You can add multiple commands by typing in the |c7Postfix:|c3 area 
something like:

|+8|c7pause p:frame=frame+1|c3|r1
|e

When you are ready to generate a |c7DISSOLVE|c3|-, |c7BLIT|c3|-, or 
|c7WIPE|c3 command, just
click on the designated button.  |c7EBU|c3 will then display the background
file image and wait for you to click the mouse to place the object
in position.  You can re-click to adjust the position further, or
use the arrow keys to move the object around |c71|c3 pixel at a time.
The object will flash indicating it's registration over the background
and allowing for exact positioning.|r1 
|e

Once the object is positioned as you like it, you have two options,
|c71)|c3 hit the |c7return key|c3 to keep the position, or |c72)|c3 hit the 
|c7space bar|c3
to keep the position but immediately place the same object in another
position.  Option |c72|c3 allows for quick placement of the same object in
several positions.  Either way, when you are finished placing the
object, the return key will return you to the |c7EBU|c3 screen for your
next operation.  The |c7DONE|c3 button will then exit |c7EBU|c3 and 
allow you to enter your editor for inclusion of the output file.
|e

In |c7ED|c3|-, to add the output file to the middle of an existing script,
use |c7ED|c3 on the existing script, position the cursor to where you
want to insert the generated commands.  Then hit the |c7ESC|c3 key.  
|c7ED|c3 will display an |c7asterisk|c3 at the bottom of the 
screen for further command information.  Type:|r1

|+8|c7*if/ram:ebuout/|c3|r1

and hit return.  The |c7if|c3 (Insert File) command will read the file
specified between the slashes and insert it at the current cursor
location.
|e

|c7|f2Generate A Moving Object|c3|f1|r1

The |c7LOAD CHAR|c3 button on this screen is used to load a 
character previously
saved with the |c7SAVE CHAR|c3 selection in the |c7"Build A Character"|c3
section 
described later.  When you click on this button, a file requester will
appear allowing you to select the character file previously saved.
|e

The |c7MOVE|c3 button will take you to the background screen, where you 
will use the mouse to place your object in first the starting, and then the
ending location of the move.  Like using the |c7"Generate BLIT"|c3 section, 
you click to place in the approximate position, use the |c7arrow keys|c3
for fine
tuning, and hit the |c7return key|c3 when the object is correctly positioned.
In the case of |c7MOVE|c3|-, you will do this twice before |c7EDU|c3 will 
return you to
the |c7EDU|c3 main screen.  If you want to move the object again, select 
|c7MOVE|c3 again, and you will find that the ending position of the previous 
|c7MOVE|c3 is saved on the screen.  This will allow you to position the 
starting
point of the next move to be in the same location so that your second
move can be a continuation of the first.
|e

If you want to position an object off screen for either the starting and/or
the ending locations of a move, you can use the |c7arrow keys|c3 to shove 
the object off screen.  If you hit the |c7SHIFT|c3 key along with the 
|c7arrow keys|c3|-,
the |c7arrow keys|c3 will move the object |c710|c3 pixels instead of 
|c71|c3 for quicker moving of objects off screen.|r1

Remember to hit |c7TRANSPARENT|c3 if you don't want the a rectangular 
background area transferred along with the object.
|e

The |c7CONTINUOUS|c3 button will toggle pink like the |c7TRANSPARENT|c3
button, and
when in |c7CONTINUOUS|c3 mode (pink) the object will not remain on the 
screen
in it's final |c7MOVE|c3 location, but will continue on via the next 
|c7MOVE|c3|-.
In fact, the final location of any given move is not actually reached
when in |c7CONTINUOUS|c3|-, as it is expected that the first position of the 
next move will be equivalent and the final position of the previous 
move redundant.|r1

If you want the last move of a series of continuation moves to stop
on the actual final position of the last move, be sure to switch off
|c7CONTINUOUS|c3 before specifying the final move.
|e



Hit |c7DONE|c3 when you have specified all your |c7MOVE|c3|-s.  At this 
point, a
complete commented Director script has been generated into the Output File.
|e


|f2|c7Build A Character|f1|c3|r1

The idea behind building a character is to cut a series of objects out
of one or more |c7IFF|c3 files and register them in place on top 
of each other.
For example, a running man can be built so he runs in place, and when
moved in the |c7MOVE|c3 section, he will then run correctly across 
the screen.
|e

After you |c7PICK OBJECT|c3 in this section, the middle button, 
|c7ADD OBJECT|c3
will appear.  When you select |c7ADD OBJECT|c3|-, a clear screen will appear
where you can place the first object for your character by clicking
the mouse.  Place the first object anywhere on the screen that is
convenient.  Hit the |c7return key|c3 to exit the |c7ADD OBJECT|c3
screen.  Do another 
|c7PICK OBJECT|c3 and get the next image of your character.  Another 
|c7ADD OBJECT|c3 and you can place the new image on top of the previous 
character so that it is correctly registered for his animation.  You 
can use the arrow keys to adjust the object's position in |c71|c3 pixel 
increments.  Again, use the |c7return key|c3 to exit 
the |c7ADD OBJECT|c3 screen.|r1

If at any time you make a mistake and wish to delete one or more of
the previous objects in your character, click on |c7DEL OBJECT|c3 and the
most recently added object will be deleted from your character 
definition.
|e

Once you have finished defining your character, you may want to click
on |c7SAVE CHAR|c3 to save out the character definition for later re-use.
While this is not required, you may decide to re-do your object
movements, or re-use the character over different backgrounds at a later
date.  After defining your character you can go right over to the
|c7"Generate A Moving Object"|c3 section and do the |c7MOVE|c3 just as 
you would with a non-moving object.
|e

While defining your character, you can select as many object images as 
you like.  If you need to get an object from another |c7IFF|c3 file, 
click on 
the |c7Object File|c3 gadget and select the file you need.  You can use as 
many object files as you like though you must keep in mind that all 
the image files you are using must fit in |c7CHIP RAM|c3 while running in 
order for the animation to operate without out-of-memory errors.  
A move normally uses |c73|c3 buffers that are the resolution of the 
background image, |c7NOT|c3 including any of the object 
buffers.  |c72|c3 of these are used for double 
buffering, and the third holds an unmodified copy of the background.  
|e

The unmodified background's buffer can easily be placed in |c7FAST|c3 memory 
if you have any, which frees up a little more |c7CHIP RAM|c3 at the expense 
of a slight amount of speed.  You can do this simply by changing the
first |c7LOAD|c3 command in the generated script to a |c7LOADFAST|c3 
command and see how it operates.|r1

You could also decide to move some of the object files into 
|c7FAST RAM|c3|-,
though speed would be further impacted, and it will require an extra
|c7COPY|c3 command and some buffer management adjustments to the script.
This is not really recommended, and left as an exercise for the fanatic.
|e

|c7|f2Conclusion|c3|f1|r1

Included in the |c7"pictures"|c3 directory on this disk are a couple of 
sample
images designed for experimenting with the character building and object
moving capabilities of |c7EBU|c3|-.  The files |c7char1|c3 and 
|c7char2|c3 contain an |c78|c3
frame running |c7"character"|c3|-.  In order to register the character frames
with themselves, cut out the character frames including the |c7ground|c3
lines, register the head positions in order to get the character
lined up left-to-right, but then move the new character image vertically
until the ground lines are level with each other before exiting each
|c7ADD OBJECT|c3 operation.  
|e



After the 
character is built and used in a movement script, you can then
decide to go back into the character images with a paint program
and remove the ground lines if you desire, causing them to disappear
from the final animation.  An overscan background image to be used with
this character is in the |c7pictures|c3 directory and 
called |c7bkgndforchar|c3|-.
|e

This example is also an opportunity to try out the |c7shift-arrow|c3 method
of moving the position of an object off-screen.  When you are ready to
move the newly defined character over the screen, you can place him as
far to the left as possible, then use the |c7shift|c3 combined with 
the |c7left arrow|c3 key to shove him completely off screen to the 
left for his initial
position.  Similarly use the |c7shift|c3 combined with the 
|c7right arrow|c3 to adjust
his final position.  We've found that a number of frames from 
|c712|c3 to |c714|c3 is
optimal for this character's running across the entire screen.
|e

So have fun.  We found that object movements over backgrounds was something
that we were asked about more often than anything else.  While the Director
was not originally specifically designed to do this, it was doable though 
a little complicated to work out, thus this utility.  It is expected 
that future Director's will provide further enhanced capabilities in this 
area. (among other things)|r1