---------------------------------------------------------------------------
                               Picture Edit v1.2
---------------------------------------------------------------------------
                           Lance Ewing, 15 Sept. 97
---------------------------------------------------------------------------

0.0 WHATS NEW

 15 Sept 97:
   - Step tool error fixed
   - Fill tool error fixed
   - View data display problem fixed
   - New keyboard shortcuts (see section 4.0)

 Thank you to Peter Kelly for picking up on the Step tool error and
 suggesting the keyboard shortcuts.


1.0 INTRODUCTION

 This program was designed to create and edit AGI picture resources. An AGI
picture resource is the background image format that Sierra On-Lines early
graphic adventure games used (1984-1989). Existing pictures can be extracted
from AGI games with utilities such as VOLX or XV3. I originally began work
on this program after discussing with a few people how one would go about
designing an editor for such a data format. The result has turned out a lot
better than I expected. The following information describes how to use this
program most effectively.


1.1 COMMAND LINE PARAMETERS

  PICEDIT <background-PCX>

  background-PCX: Image to use for background tracing. More on this later
  on in the document.


1.2 BEFORE YOU START

 If you want to get stuck straight in without reading the following text,
you need to know two important things: the ESC key takes you to the menu and
clicking with the right mouse button on the picture surface turns a tool off.
The TAB key lets you switch between the visual and priority screens. Make
sure you look at the help screen because it will tell you some of the basics.


2.0 FEATURES

 When you execute PICEDIT, you will be presented with the editor screen. This
consists of the following:

 - A status line.

     Tool:  (Line, Pen, Step, Fill, Brush, or nothing)
     V:     Current visual colour (o = off)
     P:     Current priority colour (o = off)
     X:     Current X position of mouse cursor
     Y:     Current Y position of mouse cursor
     Pri:   Priority band that corresponds to the current Y position.

 - The PICTURE surface.

 - The Tool interface.

     Tool buttons (Line, Pen, Step, Fill, and Brush)
     Palette buttons
     Off button
     Brush state interface
     Navigation buttons
     Buffer position edit field
     Delete button
     Buffer contents display field


2.1 THE TOOL INTERFACE

 The tool interface is part of the screen that does most of the work. Each
of its components are now discussed in detail.


2.1.1 THE TOOL BUTTONS

Line: This line tool is what has been called the absolute line in the AGI
picture documentation. It draws a line from one point to any other point
on the screen. Once you click on the picture surface, a virtual line
follows the mouse cursor until you click on the next point. This is very
much how most graphics packages work. The virtual line will continue this
behaviour until you press the right hand mouse button on the picture
surface. This has the effect of turning off the tool and the status line
reflects this by showing no tool as being selected. The AGI picture code
used is 0xF6.

Pen: The pen tool is what has been called the relative line in the AGI
picture documentation. I called it pen firstly because its nice and short,
and secondly because when you think about it, the relative line is used for
finer details, which is what I associate with pen drawing. The pen tool
operates very much like the line tool except that it has a restriction on
the length of the line which is reflected by the fact that the virtual line
will only follow the cursor to its boundary. Right clicking turns the tool
off as was mentioned for line above. The AGI picture code used is 0xF7.

Step: A strange name for a strange tool. This tool is what I called the
x-corner and y-corner in the AGI picture documentation for want of a better
name. I called it step because the nature of this tool makes it very easy
to draw 'steps'. The behaviour of this tool is a bit different from the
previously mentioned tools in that the destination point must lie on a
certain line. The virtual line once again reflects this and will only let
you draw a line to an acceptable destination. I have combined both the
0xF4 and the 0xF5 picture codes into this one tool. The codes used depends
of the direction taken by the first line. This means that initially you
have a choice of going vertical OR horizontal, but once that first click
is made, the program restrict you to one plane from then on. Right clicking
once again turns the too off.

Fill: This needs no explanation. Choose a colour, click on a white spot and
it fills it in for you. Right clicking on the picture surface once again
turns the tool off. The AGI picture code used is 0xF8.

Brush: This tool is the most involved tool. It corresponds with codes 0xF9
and 0xFA. An artist will set up the desired brush characteristics with the
brush state interface, select the brush tool, and then start using it. It
doesn't necessarily have to be done in this order, the program is quite
robust in this respect. You can even change the brush characteristics half
way through using the brush tool and every thing will be taken care of. Once
again, right clicking on the picture surface disables the tool. AGI picture
code 0xF9 is used to say what characteristics to give the brush, and code
0xFA gives the positions and pattern if it is needed.


2.1.2 THE PALETTE BUTTONS

 The palette buttons are used to change the colour of the visual colour and
the priority colour. Left clicking on the palette bar changes the visual
colour. Right clicking on the palette bar changes the priority colour. The
AGI picture codes used are 0xF0 for visual colour, and 0xF2 for priority
colour.

2.1.3 THE OFF BUTTON

 The off button is directly related to the palette buttons. It turns off
visual or priority drawing depending on which mouse button is pressed. The
left mouse button disabled visual drawing, the right mouse button disables
priority drawing. It is important to realise that even though both the
visual and priority colours may be turned off, the buffer still accepts
drawing actions and places them in the buffer, they just won't be able to
be seen on the picture surface or in AGI when you final incorporate it 
into an AGI program. Usually the off button is used to turn off one of
the colours so that work can be done on only one of the screens. The AGI
picture codes used are 0xF1 for disabling the visual colour and 0xF3 for
disabling the priority colour.


2.1.4 THE BRUSH STATE INTERFACE

 This was briefly mentioned in the brush tool section. What it does is allow
you to set the size of the brush (with the up and down arrows), set the
shape of the brush (either square or circle), and set whether it is solid
or like a spray. The brush state interface lies between the off button and
the navigation buttons. When the brush tool is used, the state shown by this
interface is what is used.


2.1.5 THE NAVIGATION BUTTONS AND BUFFER POSITION EDIT FIELD

 The navigation buttons allow the artist to navigate backwards and forwards
through the picture code action by action. You cannot end up in the middle
of the data for a drawing action because this could potentially cause all
sorts of problems. The four navigation buttons operate as follows:

 Home (<<): This button takes you to the start of the picture code buffer.
 Left (<) : This button takes you back to the start of the previous drawing
            action.
 Right (>): This button take you to the start of the next drawing action.
 End (>>) : This button takes you to the end of the picture code.

 As the navigation buttons are used, the value in the buffer position edit
field will change. This field gives the offset in bytes from the start of
the picture code. You can click on this field and enter a value to go
directly to this position in the buffer. This means that you don't have to
waste time using the navigation buttons. Of course, the value you enter might
be in the middle of a drawing action. For this reason, the program searches
backwards from the position entered until it finds the start of the drawing
action that includes the entered position as part of its data. It would not
do to allow data to be added to the picture code in the middle of an existing
drawing action.

 The navigation buttons and buffer position edit field allow you to go back
and make changes to existing data or insert something that you forgot to
draw. As we shall see by the next section, in combination with the delete
button, these features can be very powerful.


2.1.6 THE DELETE BUTTON

 We all make mistakes and this button is provided because of that fact. If
you make a mistake and want to remove it, all you have to do is go back to
that point in the picture code and push the delete button. Warning!! This
will delete the whole action. This means that if the mistake is only in
part of the action, you will have to redraw the whole action to fix it up.
It is probably a good idea to split big actions up into smaller segments
because of this. Most actions are reasonably short anyway. This editor is
very much drawing action based as you have probably gathered by now.

 The power of using this button is that you can experiment with various
things such as the colour of an object like a table top. All you would do is
navigate to the 0xF0 code that sets the colour of the table top, push the
delete button, and the push the desired new colour on the palette bar. To see
the change, move back to the end of the picture.


2.1.7 THE BUFFER CONTENTS DISPLAY FIELD

 You are probably asking how you are supposed to know what action you are
currently at when you are navigating through the picture code buffer. The
purpose of the buffer contents display field is to make this known to you.
Of course, the picture surface also reflects where you are since it only
draws up to the point that you are at in the buffer. However, knowing exactly
where you are requires a look at the actual data itself which is what this
field displays. The drawing action that you are currently at is the one that
starts at the left hand side of the buffer contents display field. The field
shows six bytes. For this reason, it is sometimes possible to see the start
of the next action. This is why I've made the distinction that the current
drawing action is the one that starts at the left hand side. You can also
use the "View Data" option in the menu system to look at the data currently
in the picture code buffer.


3.0 THE MENU SYSTEM

 Picture Edit has a menu system that can be activated by pushing the ESC key.
The arrow keys are used to select from the available options. These options
are as follows:

 Info     -  About
             Help

 File     -  New Picture
             Save Picture
             Load Picture
             Quit

 View     -  View Data

 Special  -  Background

 Most of these options are self explanatory, but a few will be discussed in
the following sections.


3.1 LOADING AND SAVING FILES

 Although this is relatively straight forward, I should point out that only
file names of the format "PICTURE.#", where # = 0-999, can be used. I
thought about taking this restriction out, but the more I though about it,
the more I was convinced that this way is better because it encourages the
development of AGI pictures to be done as a set that can then easily be
stored in a VOL file with a program like AGIGLUE by Floating Hills Software.
Using names like FOREST.PIC would create further work down the track when it
came time to integrate the pictures into a VOL file. This way you know what
the picture number is and the LOGIC coder can get to writing the code.


3.2 VIEW DATA

 The View Data option is quite useful. It allows you to browse through the
data contained in the picture code buffer with the arrow keys and PgUp/Dn
keys. Drawing action codes are coloured red, the end of picture code is
coloured bright red, and the current position is coded pink. You can use this
option to get a better idea of where abouts you currently are in the picture
code.


3.3 THE BACKGROUND TRACING OPTION

 This option has the potential to save artists a lot of time, and can make
artists out of laymen. You can specify a PCX file to use as the background
in order to trace varous details on it when drawing a picture. This facility
treats the white visual colour and red priority colour as a transparent
colour. All other colours are drawn on top of this image. Initially you start
with the whole image being displayed on both the visual and priority screens.
As you draw the trace the background image, it will gradually disappear until
only the white parts of your final picture will be showing the background
PCX.

 It is a requirement that the PCX image be 8-bit because Picture Edit uses
an 8-bit mode. It is also a requirement that it have a width of 320 pixels.
The height can be any value, but anything over 168 is cut off. Because the
bottom sixteen palette registers are used by Picture Edit itself, the
background PCX is more suited to being a 240 colour image. This is not a
requirement though because Picture Edit will handle 256 colour images quite
well by finding the closest match for colours that can't have their own
palette register assigned to them. For most 256 colour images, the difference
is hard to spot.

 To recap, a 320x168x240 image is most suited, but a 320x168x256 image is
acceptable. It all depends on what graphics utilities you have available to
manipulate the images you want to use as a background. If you use a program
like LView, then you can set the number of colours to 240 quite easily. Most
programs will let you resize or crop an image, so the 320x168 size shouldn't
be a problem but remember that 320x200x256 (a standard size) is also
acceptable if you don't mind having the bottom cut off.

 To load a background PCX file, you have to specify the name of the file as
a command line option (e.g PICEDIT MEKA.PCX). The background image will not
show up immediately. You have to select the "Background" option from the
menu system to activate the transparent screen update. At any stage you can
switch back to normal to see the white parts of the screen as they should
be.


4.0 USING THE EDITOR

 ESC : Brings up the menu system (you can also click on the status bar).
 TAB : Switches between the visual and priority screens
 Right Click : On the picture surface turns off the selected tool.

 L, l, F1: Line tool
 P, p, F2: Pen tool
 S, s, F3: Step tool
 F, f, F4: Fill tool
 B, b, F5: Brush tool

 Home, Left, Right, and End keys:  Same as the navigation buttons.

 Del key: Same as the delete button

 F10: Toggle the background picture


5.0 BUGS

 I have fixed all known bugs in the program but there are probably a few
still lying around somewhere. If you find a bug in the program, please let
me know by sending an email to the address at the bottom of this document.
Also, I'd be glad to hear what you think of the program.


NOTES:

(1) If you have a tool selected, start using that tool, and then change
the colour, there is no need to reselect the tool. Whatever is shown on
the status line will be used again when you click on the picture surface.

(2) The palette and off buttons are the only buttons that add picture codes
to the buffer immediately. All other codes are added when the mouse
interacts with the picture surface.

---------------------------------------------------------------------------
THE AUTHORS INTERNET DETAILS

 Email: Lance Ewing <be@ihug.co.nz>
 WWW: http:\\crash.ihug.co.nz\~be\sierra.htm
---------------------------------------------------------------------------
