nba-hangtime/DOC/WIMP.DOC

			    W i l l i a m s
			    I m a g e  
			    M a n a g e m e n t
			    P r o g r a m 


			    A User's Manual



	     Copyright (c) 1987 Williams Electronics Games, Inc.
			    All Rights Reserved

			      Warren B. Davis
			      George N. Petro	

I.	Before starting WIMP

A> MOUSE

	Is your mouse connected and working? Has the mouse driver been
	installed? (If not, type "mouse" followed by ENTER while in your
	root directory (C:\))
	WIMP requires a mouse.

	If you start WIMP and your mouse is not installed, you can use keys
	to exit so you can install your mouse. First press ESC to get into
	the menu bar at the top of the screen. Next press the left and right
	arrow/cursor keys to get to the menu labelled GENERAL. Finally press
	the down arrow key to get to "Exit from WIMP" and press ENTER.

B> ENVIRONMENT VARIABLES, IMGDIR and VDADIR

	These variables are optional. 

	IMGDIR represents a directory where all WIMP image libraries are
	stored and can be found.

	VDADIR represents a directory where all .vda images (that is, images
	generated by the AT&T Image Capture Board, then translated to .vda
	format)	can be found and will be stored.

	If not defined, both of these are assumed to be the current directory.
	(i.e. the directory you were in when you invoked WIMP).

	To define either/both of these, include a line/lines as follows
	in your	AUTOEXEC.BAT file.

	SET IMGDIR=c:\some directory
	  and/or	
	SET VDADIR=c:\the same or another directory

	It is recommended that you set up separate directories for both
	of these. 

C> GSP ART PROGRAM

	WIMP runs on the PC. It communicates with the target system
	through	a program called ART which must be running on the target
	system.  You don't have to do anything to get this program running.
	WIMP will automatically	invoke it.

	HOWEVER, you DO have to make sure this program exists in the
	directory where WIMP expects to find it. That directory is one
	of two places...

	IF you have NOT defined the environment variable IMGDIR, WIMP expects
	the ART program to be in the current directory.

	IF you HAVE defined the environment variable IMGDIR, WIMP expects
	the ART program to be in that directory.

	ALSO, you have to make sure that the program sdbl2.exe is somewhere
	in your PATH. (Seek help if you are unsure what this means).

II.	Starting WIMP

A>	Invoking wimp

	Type "wimp" followed by ENTER. You must be in the directory that
	contains the WIMP program unless that directory is part of your PATH.
	The screen will clear, there will be a menu bar across the top, and
	some status information on bottom.

	WIMP Command Line Options

	/out=<filename>
		<filename> = The art program that is to be downloaded to the
			     GSP. This can be either a full path name or just
			     the filename if it exists in the current
			     directory.
			     Note: This option overrides the variable IMGDIR.	

	/r=<resolution option>
		<resolution option> = A number denoting the desired resolution
					0 = 400x512 25Khz non-interlaced
					1 = 256x395 16Khz non-interlaced
					2 = 400x512 16Khz interlaced
		example: wimp /r=1
				this would invoke wimp with 256x395 16Khz res.

B>	Using the mouse

	The mouse cursor appears as a solid block and should move smoothly
	around the PC screen. If you move the mouse cursor to the left,
	right or bottom edges and beyond, the cursor scrolls onto the target
	system screen.  If you move the cursor to the top, it sticks to the
	menu bar. You will remain stuck to the menu bar until you CLICK the
	left mouse button.

	While stuck at the top, moving left or right will select different
	menus. 	You can move down and up through the selected menu or left
	and right to and from any submenus.

	To select an item from the menu, click the left mouse button.

   1)	Using the Keyboard

	Whenever the cursor is on the target system's screen certain keyboard
	keys will duplicate mouse functions.  These keys help with finite 
	cursor movements such as moving 1 pixel while in Zoom 4X mode.

	<enter>		=	Mouse left button
	<Backspace> 	=	Mouse right button
	Arrow Keys	=	Move the Cursor in the respective direction.
	F1 - F8		=	Select draw colors 0-7 respectively.
	Shift F1 - Shift F8 =	Select draw colors 8-15 respectively.

	Move the DRAW color select highlite with the following keys:
	Grey Home	=	up 	(current color - 16)
	Grey End	=	down	(current color + 16)
	Grey Delete	=	left	(current color - 1)
	Grey Page Down	=	right	(current color + 1)


C>	Status information

	At the bottom left of the PC screen, the following information
	is displayed...

	- Current image library (i.e. last one loaded), Number of images
	  currently defined, amount of available memory.
	
	- At bottom right, the following is displayed...
	  DR:  n1 (r1, g1, b1)	ER:	n2  (r2, g2, b2)

	  DR: stands for DRAW COLOR, n1 is the color number, and r1,g1,b1
	  represents the color value.  ER: stands for ERASE COLOR.

	- WIMP verion is the version number of the PC side program.	
	  ART version is the version number of the GSP side program.

	- When the cursor is scrolled onto the target system screen, another
	  display appears above the draw and erase color information. This is
	  the cursor position (X, Y) followed by the color number of the pixel
	  pointed to by the cursor and the R, G, and B values of that color.

III. Some Basic WIMP Concepts

	An Image Library (.IMG) file is a workfile containing up to 256
	images.

	Each image has a palette associated with it. Many images can share a
	single palette, or each can have a separate palette. A palette
	contains only the colors used in the images which are associated
	with it.  The target system has a 256 color capacity. A palette may
	contain UP TO 256 colors.  It should be clear that two images using
	separate 256 color palettes can not appear on the target system
	screen simultaneously.	However two images using the SAME 256
	color palette can.

	Images are created by importing them from another source (Amiga or
	AT&T VDA format) or by saving an area of the target system screen.

	An image consists of pixel numbers. These numbers are pointers to
	colors in the associated palette. When an image is downloaded to
	the target system, its palette is loaded as well. WIMP determines
	where in color ram to put the palette. It will pack as many
	palettes as it can contiguously	and adjust the pixel data as it
	loads the image.
	K E E P   T H I S   I N   M I N D ! ! !

	There are two ways images exist...

		1) on the PC (either on disk or in the PC memory)

		3) in target system Image Ram (these are called frames)

	Images which have been previously saved are taken from the hard disk
	until they are modified. Then they remain in PC memory until
	the image library is saved. Modifying happens by...
		-	changing an image with a directory range command
			(i.e. flip),
		-	saving an area of the screen as an image, or
		-	uploading an edited frame upon exiting animation mode

	Once an image is put on the screen, it is no longer an "image" but is
	just a part of the screen.  

	Images which are part of animation sequences used in an animation
	buffer are downloaded to the target system Image Ram when animation
	mode is entered.
	They are now considered "frames" and can be edited independently of
	the way they are stored on the PC.
	Changes to frames occur in the target system only. They must be
	uploaded to the PC upon leaving animation mode or they will
	be lost.

	Changes to images occur on the PC only. They must be saved to disk
	with the Image Library before leaving WIMP or they will be lost.

IV.  Menu 1 - GENERAL	

A>	Clear Screen

	This clears the target system screen to color 0.

B>	Load Image File

	A window appears listing all valid Image Library files (.IMG) in the
	default directory (IMGDIR).

	To change directory, left click on the directory name and retype.

	To select an image library, left click on the name. The selected
	image library is loaded.

	To cancel, left click on CANCEL.

	An asterisk next to a name means that library has already been loaded.
	The last one to be loaded has two asterisks next to the name.

	Up to 8 libraries can be loaded at one time. HOWEVER, once more than
	one library is loaded, WIMP sees the combination of the two as ONE
	library. If you save an image file (.IMG) before you leave wimp,
	ALL images are saved into a single file regardless of the library
	they came from originally.

C>	Save Image File

	A window appears listing all LOADED image library files in the
	default	directory (IMGDIR).

	To change directory, left click on the directory name and retype.

	To select an image library, left click on the name. The fully defined
	image library filename appears beneath the window. Click on this name
	to save the current state of WIMP (images, palettes and animation
	setup).

	To give the saved library a new name, left click on "Name:" and type 
	one in. The fully defined library filename appears beneath the window.
	Click on this name to save.

	To cancel, left click on CANCEL.

D>	Make mouse SLOW (or FAST)

	Click on this to change mouse sensitivity. There are two possible
	states,	SLOW and FAST. The menu will show the one which is NOT
	in effect.  The sensitivity affects mouse motion on the target
	screen only!


E>	Do Some DOS

	Create a DOS shell.  Allows you to do DOS commands without altering
	the state of WIMP. Beware of memory contraints! Don't do this unless
	you have at least 100K of memory left.  (Available memory appears on
	the bottom of the PC screen during WIMP operation.)

	When you complete your DOS stuff, type EXIT and you will miraculously
	return to the land of WIMP.


F>	EXIT WIMP

	Exits from WIMP.  All changes are lost, so if you want to save
	something, use SAVE IMAGE FILE before you exit!

V. 	Menu 2 - IMAGES


A>	Import Image

	Gets an image from a place outside of wimp (i.e amiga or vda), and adds
	it to the images currently defined.

	AMIGA - 	The parallel connector coming out of the target system 
			interface card should be connected to the AMIGA's
			parallel port. The appropriate AMIGA program should
			be used to initiate the transfer. 
			Initially, you will get the message...
			"Waiting for Sync"

			To CANCEL at this point, press capital C.  You will
			then get the option of Retrying or Forgetting it.
			Use the mouse and click on your choice.
			
			Otherwise, when the transfer is done, give the image
			a name.	 The palette name will be amigaxxx where
			xxx is the number of colors transferred.

	vda - 	Enter a name for the vda image. This name must correspond to
			an existing vda image file residing in the VDADIR
			directory.  An extension of ".vda" is assumed so
			you only need to enter the filename part. The name
			given the image will be "ffffffff.vda" and the
			palette will be named "ffffffff" where ffffffff
			is the filename.


B>	Directory

	This command will put you in directory mode, which has many facets.
	The screen is taken up by a list of images on the right, a list of
	palettes on the left, and some function boxes in the middle. 
	Upon entering directory mode, one image is always highlighted. It
	is the highlighted (or selected) image which is affected by a
	function.
	
	To execute a function, left click inside the function box.

	To scroll within the image list, left click on HOME, PGUP, PGDN or END

	To scroll within the palette list, left click on the U (for up) or 
	D (for down) which appears on either side of the word PALETTE at the
	top of the palette list.

	To select an image, left click on its name.

	To select a palette, left click on its name.

|===========================================================================
|  MAIN DIRECTORY FUNCTIONS...
|			(unless otherwise specified, click means left click) 
|			(any images or palettes required by the command       
|			 should be selected FIRST)                            
|===========================================================================
|
|  LOAD IMAGE
|		Click on this, then bring the cursor to the target system
|		screen, and left click. The image is placed on the screen.
|		The cursor must be positioned so that the entire image
|		fits on the screen.
|		To cancel, bring the cursor to the target system screen and
|		right click.
|		When an image is loaded, its palette is also loaded
|		This can be done with transparency on or off. See Menu 3,
|		Turn Transparency ON or OFF.
|
|  RENAME IMAGE
|		The selected images name becomes blank. Type in a new one.
|
|  COPY IMAGE
|		The selected image is duplicated. The new image is added to
|		the bottom of the image list.  It will have the same name
|		as the original and will be associated with the same
|		palette.
|
|  CHANGE PALETTE
|		The selected palette becomes associated with the selected
|		image.
|
|  DELETE IMAGE
|		The selected image is deleted from the image list.
|		YOU CAN NOT GET IT BACK WITHOUT RELOADING THE IMAGE 
|		LIBRARY. 
|
|  TO VDA FMT
|		The selected image is converted to .vda format and
| 		a file written to VDADIR. The name of the file is the
| 		name of the image (up to 8 chars and ignoring a period
| 		or anything following a period) followed by .vda
|
|  RANGE OPTIONS 1
|		Enter Range Mode 
|
|  RANGE OPTIONS 2
|		Enter Range Mode with a different set of functions
|
|  PALETTE OPTIONS
|		Enter Palette Mode	
|
|============================================================================

|============================================================================
|  RANGE MODE FUNCTIONS...
|			(These functions operate on more than one image at a
|			 time. Specifically, those which are MARKED)
|			(The image list now highlights all MARKED images)
|			(To MARK an image, click on its name, or use one of
|			 the first 3 Range functions)
|============================================================================
|	
|  MARK ALL
|	     	All images are MARKED
|
|  UNMARK ALL
|		NO images are MARKED
|
|  MARK CURRENT PALETTE	ONLY
|		images which use the selected palette are MARKED
|
|  COPY RANGE
|		All MARKED images are duplicated. The duplicated are added
|		to the end of the image list.
|
|  CHANGE PALETTE
|		All MARKED images become associated with the selected
|		palette.
|
|  SORT RANGE
|		All MARKED images are alphabetized and placed at the top
|		of the image list. This is a purely visual change and does
|		not affect image or palette data in any way. However it
|		can be used to keep images together visually.
|
|  FLIP HORZ
|		All MARKED images are flipped horizontally
|
|  FLIP VERT
|		All MARKED images are flipped vertically
|	
|  ROTATE CW
|		All MARKED images are rotated 90 degrees clockwise
|
|  ROTATE CCW
|		All MARKED images are rotated 90 degrees counterclockwise
|
|  PIXEL REPLACE
|		You are prompted for a source and destination color.
|		To choose a source color, move onto the target screen and
|		left click on the pixel you wish to replace.
|		Right click to the pixel you wish to replace it with.
|		Click on OK to perform the replacement or CANCEL to cancel.
|		NOTE: The marked images should all use the same palette.
|			 If the source or destination color are not part of
|			 the palette of a marked image, no change will be
|			 made to that image.
|  TO SRC FILE
|		All marked images are written to a file called IMAGES.ASM
|		in the current directory. They are in source file format
|		ready to be assembled by the GSP assembler.
|============================================================================

|============================================================================
|  PALETTE FUNCTIONS...
|
| 			These functions operate on palettes.
|
|============================================================================
|
|  SHOW IMAGES
|		All images in the image list using the selected palette
|		are highlighted.
|
|  SUB-MERGE
|		The selected palette will be merged into a master palette.
|		This means that the master palette and images using it will
|		not change. Colors in the original palette will be mapped
|		into the CLOSEST color of the master palette.
|		You are prompted to click on the name of the master 
|		palette. The original palette is deleted, and all images
|		using it are made to use the master. NOTE: The data
|		on all images using the original palette is changed to
|		fit the master palette!  Duplicate those images and the
|		original palette first if you are experimenting.
|
|  MERGE
|		The selected palette is merged with another palette.
|		You are prompted to click on the name of a second
|		palette. The original is deleted, and all images using it
|		are made to use the second.
|		The second palette is modified to include colors from the
|		first.
|		NOTE: The data on all images using the first palette
|		is changed to fit the second.
|		Duplicate those images and the first palette 
|		if you are experimenting.
|
|  CONDENSE
|		Colors are deleted from the selected palette based
|		on a threshhold which you set.  The threshhold represents
|		the number of pixels which must exist of any color in order
|		for that color to remain in the palette. If the number of
|		pixels of a color is less than the threshhold, those pixels
|		are mapped into a similar color. If no similar color can
|		be found, then the color is allowed to remain.
|		To change the threshhold, click on U to increase a digit
|		or D to decrease a digit.  OK accepts the displayed number.
|
|  DELETE
|		The selected palette is deleted IF AND ONLY IF there
|		are no images currently defined which use it.
|
|  COPY
|		The selected palette is duplicated and placed at the end
|		of the palette list. You must give it a name.
|
|  RENAME
| 		The selected palette's name is removed. Type in a new one.
|
|============================================================================

C>	Save Work Area as Image

	This item is valid only when a "Work Area" is defined on the screen. 
	(see Menu 2 - GRAPHICS).  The Work Area appears as a box on the
	screen, and with this item, you can save what's inside as an image.

	First you must decide how you wish to save the contents of the
	Work Area.

	The choices are...	1) Create a new image
				2) Replace an existing image
				3) Replace the last image loaded.

	Choice 3 is actually a subset of choice 2 and is included for
	convenience.

	To make a choice, click on the choice, then click OK.
	If you choose (1), you must give the image a name.
	If you choose (2), the image list appears and you must click on an
		image then click on OK. That image will be replaced by the
		contents of the	Work Area.

	Next, you must decide how you wish to save the color information.
	The choices are...  1) Create a new palette
 			    2) Merge into an existing palette
			    3) Use the palette which was
			       originally downloaded.
			       (...if one exists for the
			       contents of the Work Area)

	Choice 3 exists only if you downloaded an existing image, modified
		it, and now want to save the changes. It will not be
		available if the new image uses more colors than the original.

	Choice 2 is the same as a SUB-MERGE palette command. The contents
		of the Work Area are modified to fit as closely as possible
		into an existing palette.

	To make a choice, click on the choice, then click OK.
	If you choose (1), you must give the palette a name.
	If you choose (2), the palette list appears and you must click on a
		palette then click on OK.  The threshhold box appears.
		You can	change the threshhold if you like or not.

	Saving the Work Area can be done with Transparency ON or OFF.	
	(see Menu 3 - Turn Transparency ON/OFF)
	When transparency is ON, the Least Square around the Work Area
	is computed and saved. That is, the size of the area saved is
	modified so that any padding of color 0 around the edges is not
	included. 
	
VI.	Menu 3 - GRAPHICS


A>	Define/Undefine Work Area

	To define a Work Area, scroll onto the target system screen.
	A left click fixes a corner of a box.  You can now scroll around
	changing the size and shape of the box. 
	A right click removes the box, letting you start again.
	Another left click sets the diagonal corner.

	When you select the Undefine Work Area item, the box disappears and
	all Work Area items become unavailable.

	To change the Work Area once it has been used, you don't need to
	undefine it. Select Define Work Area again. The first left click
	will start the box again.


B>	Fill Work Area

	These items are pretty self-explanatory. You fill either the
	inside or the outside of the box with either the Draw color, the
	Erase color or Zeros. (see Menu 4 - COLORS for an explanation of the
	Draw and Erase Colors)


C>	Edit Work Area

	Pixel Replace - You are prompted for a source and destination color
				which are selected as follows...

				Scroll onto the target system screen.
				A LEFT click on	a pixel sets the color under
				that pixel as the source color. A RIGHT click
				on a pixel sets the destination	color.
				You can choose one of 4 types of replacements.
				Left click on the one you want, then on OK.

	Flip Vertically - The inside of the box is flipped around the
			  horizontal axis.

	Flip Horizontally - The inside of the box is flipped around the
			    vertical axis.


D>	Copy Work Area

	For all of these commands, you must scroll onto the target system
	screen and left click at the place where you want to place the
	copy. If you hold down the left button, you can effectively use
	the Work Area as a brush and paint with it.  The copying can be
	done with Transparency ON or OFF.

	NOTE: If you overwrite the original Work Area, funky results will
		 occur! (Try it. You might like it)

E>	Turn Transparency ON or OFF

	Color 0 is considered a transparent color when Transparency is ON.
	If you Load an Image with transparency, 0 pixels will not be written.
	The same is true for Copying the Work Area. When Saving the Work Area
	as an Image, Transparency ON causes a least square function to happen
	to the contents of the Work Area.
	
	When Transparency is ON, the item will read... Turn Transparency OFF
	and vice versa.

F>	Draw Mode

	See Section II.B.1  --  Using the Keyboard. 

	This is a general purpose mode to allow you to modify what is on the
	screen.  From here you can go into Zoom mode and back, or you can
	draw circles and lines, or you can do some of the previously
	mentioned work area commands.
	Also available are such commands as Display/Remove Color Block, Turn
	Transparency On/Off, and Make Mouse Fast/Slow

	Some DRAW MODE commands are...

	Freehand Dots - Draw dots with the mouse by holding down the left
				 (for the Draw Color) or right (for the Erase
				 Color) mouse button.

	Freehand Lines - Same as above, only you draw a line as you move
			 the mouse.
	
	Define/Undefine Work Area - As described under A> above.

	Display Color Block - Move mouse onto target system and click where
		you want the color block to be.  The color block shows you
		color ram as it is currently defined. The current draw and
		erase colors are shown underneath the color block.
		The HIGHLITED color also denotes the current draw color.
		You may select a DRAW color by moving this highlite around
		the color block using the following keys:

		Grey Home	=	up 	(current color - 16)
		Grey End	=	down	(current color + 16)
		Grey Delete	=	left	(current color - 1)
		Grey Page Down	=	right	(current color + 1)

	Filled Circ/Unfilled Circ/Rubber Line  -  Move onto the target screen
		and left click to set the first point. Then move the mouse
		and left click again to complete the line/circle. This
		also resets the first point. A right click will cancel the
		first point. You should make sure the first point is
		cancelled before you leave the target screen to do
		something else.	The line/circle is always drawn in
		the DRAW Color.

	ZOOM - When you click on this, the Filled Circ/Unfilled Circ/Rubber
		Line commands are disabled. You must move the zoomer
		(a box) onto the target screen and left click over the
		area you wish to zoom.	Once this happens, you can zoom
		in or out, or scroll the zoomer.  You will probably want
		to change the mouse sensitivity to SLOW. One note of
		caution. If you define a work area, then zoom such that
		the work area is off screen, the work area will undefine
		itself.