SLABSPRI VOXEL EDITOR Notes: (Started: 06/25/1997, Last updated: 03/17/1999)

SLABSPRI programmed by Ken Silverman

------------------------------------------------------------------------------
Introduction:

There are several ways you can use SLABSPRI.EXE to create a .KVX voxel file:
1. Build your own brand new voxel using the SLABSPRI.EXE editor.
2. Convert from .ART & .PAL files containing 2-D rotations.
3. Convert from a .VOX file, which is a simple 3-D array of voxels.

------------------------------------------------------------------------------
Command line parameters:

if (argc == 1)
{
	C:\>SLABSPRI.EXE

	This will start up SLABSPRI with the default voxel and palette.
	My initials are "KJS" :)
}
if (argc == 2)
{
	C:\>SLABSPRI.EXE [.KVX / .VOX filename]

	This loads a voxel file that is already in 3-D format.  The 2 types of
	voxel files are:
		.KVX - compressed voxel object using vertical spans with 5 mip-maps
				 levels.  At the end of the KVX file is a 768 byte palette.
				 If you're really out to save space, you could strip this off
				 and the voxel will still look correct in the game.  Of course,
				 you'd have to re-attach the palette if you ever want to view
				 the KVX in slabspri again.
		.VOX - uncompressed voxel object

		  For you programmers out there, SLABSPRI.EXE can load from an
			  uncompressed voxel file.  For example you could easily write
			  a program to generate some kind of a colorful sphere.  Or if
			  there's a true hacker out there, maybe you could even write
			  a program that converts objects from a 3D modeler program
			  to voxel files!  (I'd like a copy if anyone does this!)

		  The .VOX format is so simple, I'll describe it right here:

					//char voxel[xsiz][ysiz][zsiz];
				read(fil,&xsiz,4);              //Dimensions of 3-D array of voxels
				read(fil,&ysiz,4);
				read(fil,&zsiz,4);
				read(fil,voxel,xsiz*ysiz*zsiz); //The 3-D array itself!
				read(fil,palette,768);          //VGA palette (values are 0-63)

					Color 255 is treated as empty space.  It is best to keep the
				inside of the object solid.  Otherwise, SLABSPRI will not be able
				to take advantage of back-face culling.

	Note: A transluscent table is required to create the lower mip-map levels.
		Since KVX / VOX files don't store the transluscent tables in them, and
		it would be slow to re-create them every time a KVX is loaded, SLABSPRI
		tries to load the transluscent table from PALETTE.DAT.  It's ok if
		PALETTE.DAT doesn't exist, however the voxels will go blank when
		switching to the lower mip levels.  I recommend keeping a copy of
		PALETTE.DAT with transluscent table sitting in your directory.
}
if (argc == 5)
{
	C:\>SLABSPRI.EXE [art&pal name][start tile][num tiles][total rotations]

	art&pal name:  You must prepare an .ART and .PAL file, such as "KEN.ART" and
		"KEN.PAL".  The filename (without extension) must be the same name.  For
		the palette file, you can rename your PALETTE.DAT file.  SLABSPRI uses
		a transluscent table for the painting stage of conversion.
	start tile: The tile index into the art file which is the first rotation of
		the object.
	num tiles:  The number of rotation images that will actually be processed from
		art file.  This number is usually 5 for objects that were not specially
		designed for voxels.
	total rotations:  This number is used to calculate the angle delta between
		successive rotation images in the art file.  Use 8 for 45 degree increments,
		12 for 30 degree increments, etc. increment = (360 degrees / #).  If this
		number is negative, then the rotations will be treated as counter-clockwise
		instead of clockwise.  Most games use positive numbers.
}

------------------------------------------------------------------------------
Keys inside SLABSPRI.EXE:

Keys everyone should know before using SLABSPRI.EXE:
	ESC - quit to DOS (first asks if you're sure)
	arrows - move
	A/Z - up/down
	PGUP/PGDN - look up/down
	<> - rotate voxel around its center (if mouse cursor is not in a window)
	L - load a KVX file.  Allows you to select files anywhere on the current
					 drive by simply using arrow keys, PGUP, PGDN, Home, End, and
					 L.Enter.  Press ESC to cancel.

Editor keys:
	Keyp.Enter - toggle edit windows.  If the mouse cursor is pointing on the
					 voxel when you press this key, the 2D cross sections will
					 be at the point where the mouse was over.
	L.ALT-S - save a KVX file.  If you specified a KVX file on the command line
					 it will use that filename.  Otherwise, it will save as a new
					 kvx file as VOXEL###.KVX.  Will automatically find first file
					 with number that doesn't exist.
	R.ALT-S - save as VOXEL000.VOX
	L.MouseButton - plot pixel
	R.MouseButton - drag 2D EDIT MODE window
	L.ENTER - Changes the "3-axes" window viewing mode.  There are 3 modes:
		0 - Cross-section mode (only shows 1 layer)
		1 - Show-through mode (Shows all layers from beginning of axes)
		2 - Show-through mode (Shows all layers from end of axes)
	Delete - In 3D view, this key shoots a laser beam through the mouse cursor
		 and chops off any voxels in its path.
	Backspace - changed current drawing color to 255
	F - Flood fill region using current drawing color
			If in Cross-section mode (0): Uses current color as border color
			If in Show-through mode (1,2): Uses color under cursor as follow color
	C - Change all colors from what's under cursor to current drawing color
		 if (showthough == 0) changes are made only in cross section,
		 otherwise entire voxel is changed.
	J - Junking function - Randomly changes about every 16th pixel of color
		 under mouse cursor to current drawing color.
	B - Press this key when the mouse is on the color bar to change the
		 background color.
	T - trail mode
	~ - toggle pivot adjustment mode.  Use arrow keys to adjust.
	/ - Center pivot in pivot adjustment mode
	<> - Darken / brighten rectangle (mouse cursor must be in a window).
		  Select first corner with 1.
	TAB - choose current drawing color
	SPACE - plot a pixel using current drawing color
	+,-   - (Both main keyboard & keypad) increment / decrement color
	Shift + Arrows - Change current drawing color
	Shift + Mouse - Limit mouse movement to either X or Y axis, depending
		  on which changes first.
	[ ] - Change current drawing color (left / right)
	Keyp. /,* - Zoom window in / out.  There are 4 zoom levels (1,2,4,8)
	PGUP/PGDN - select cross-section
	HOME/END - Push a rectangular region forward of backward.  Works in
		viewing mode 0 only.  Select first corner with 1.  2nd corner is
		where mouse cursor was, when Home/End was pressed. (Not fully
		programmed yet)
	CTRL+PGUP/PGDN - change voxel dimensions
	R - 2D Rotate - Press R to enter rotate mode.  Then use 4 arrow keys to
		 rotate the 2d cross section (viewing mode 0) or entire voxel (viewing
		 mode 1-2) by 1 pixel.  Press ESC, Enter or R to get out of rotate mode.
	ALT-R - 3D Rotate.  Rotates an entire voxel CCW upon the axis of the
		 window the mouse cursor is over.
	ALT-F - 3D Flip.  Do top/bottom flip on the window the mouse cursor is
		 over.
	ALT-C - Make a 2d cross section which has an almost circular shape look
		 perfectly circular.  This works great for those "octagony" voxels
		 that were chopped out using only 8 views.  If you press ALT-C when
		 viewing mode > 0, then all cross sections of that axis will be
		 circulized.
	ALT-H - De-hollowize tool.  This key fills in hollow parts of voxels
		 that can never be seen from outside.  Use it when the edit2d mode
		 windows are off.  This is useful for optimizing a voxel for
		 back-face culling.  Note that this won't work if there is a leak
		 into the hollow part.
	ALT-U - undo change - copies compressed 3D voxel over 2D views.
	Keyp.0 - accept changes in 2D windows - copies to compressed 3D voxel.
	1 - select first corner for copy&paste rectangular region
	2 - select second corner for copy&paste rectangular region
		 Unlike EDITART, it matters whether you select the top-left corner
		 first or not.  This is how you can flip the tile more easily without
		 having to use other special keys to do it.
	3 - paste rectangular region (from top left corner)
	ALT-P - re-maps current palette to the palette.dat file which you must put
			  in the current directory.
	Keyp. 2,4,6,8 - Change xrepeat & yrepeat.  These keys stretch and shrink
		the voxel in the x and y directions.  This will not be saved and is
		only included for fun.
	Keyp. 5 - Reset xrepeat & yrepeat
	Ctrl + Keyp.5 - Reset voxel to center position facing forward
	F1-F4,F9,F10 - slow x,y,ang movement.
	F12 - screen capture
	U - combine 2 Voxels.  First lets you select a KVX file like the 'L' key.
		 Then you can center the object by using the 1-6 keys on the keypad
		 like this:
			 Ŀ
			 (7)(8)(9)
			 Ĵ
			 x--y--z--
			 Ĵ
			 x++y++z++
			 
		 I was nice enough to duplicate my movement code so you could move
		 around the voxel as you center it.  After centering, press L.Enter to
		 accept or ESC to cancel.
