--------------------------------
SLABSPRI Help Reference
Original Docs By Ken Silverman
Edited By Keith Schuler
(c) 1997 3D Realms Entertainment
--------------------------------

This is a very brief reference guide to help you use the SLABSPRI program,
which you will find in the \GOODIES\TOOLS directory on your Shadow Warrior
CD. Use SLABSPRI to create voxels (3D sprites) for Shadow Warrior.

Refer to these documents in the \GOODIES\DOC directory on your Shadow
Warrior CD for other important information:

ADVANCED.TXT - Brief explanations of room-over-room, sector objects, and
other advanced Shadow Warrior mapping topics.
EDITART.TXT  - Instructions and reference for using the EDITART program.
EXAMPLE.TXT  - Documentation to accompany EXAMPLE.MAP, which includes
demonstrations of almost all of Shadow Warrior's map functionality.
SLABSPRI.TXT - Instructions and reference for using the SLABSPRI program.
SWSOUNDS.TXT - An index of the sound effects and ambient sounds.
SPRITAGS.TXT - Sprite tagging reference. Your guide to all the special
sprites in Shadow Warrior and how to use them.
SWBUILD.TXT  - A tutorial and reference guide to using the BUILD editor.
WALLTAGS.TXT - Wall and sector tagging reference. These are all the wall and
sector tags used in Shadow Warrior.
-----------------------------------------------------------------------------


--------------------------------
1.      Command line parameters:
--------------------------------

There are three different ways to access SLABSPRI on the command line:

1. Build your own brand new voxel using the SLABSPRI.EXE editor.
2. Load an existing .KVX or .VOX file and edit it.
3. Convert from .ART & .PAL files containing 2-D rotations.

1.1     SLABSPRI

If you type "SLABSPRI" on the command line with no arguments, this will start
up SLABSPRI with the default voxel and palette.	My initials are "KJS" :)

1.2     SLABSPRI [.KVX / .VOX filename]

        This loads a voxel file that is already in 3-D format. For instance,
        type "SLABSPRI RAILGUN.KVX" to load the railgun voxel. 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! -Ken)

        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 okay 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.

1.3     SLABSPRI.EXE [art&pal name][start tile][num tiles][total rotations]

        This is the easiest way to create a new voxel. You make rotations
        of a sprite (perhaps by rendering it with some 3D package.) And
        then create an .ART file using EDITART. Place the rotations in the
        art file sequentially, turning clockwise. Then copy the .ART file
        to your SLABSPRI directory, along with PALETTE.DAT.

        1.3.1 [art&pal name]

                Prepare an .ART and .PAL file with same name, 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.

        1.3.2 [start tile]

                This is the tile index into the art file which is the first
                rotation of the object. For instance, if in EDITART you
                placed your object at tile #0, then that is the number you
                would use here.

        1.3.3 [num tiles]

                The number of rotation images that will actually be processed
                from art file. This number is usually at least 5 for objects
                that were not specially designed for voxels.

        1.3.4 [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. Usually this number will be the same
                as [num tiles], unless for some reason the rotation images
                equal more or less than a single rotation.


----------------------------
2.      Keys Inside SLABSPRI
----------------------------

These are the keys everyone should know before using SLABSPRI.EXE.

2.1     Main Screen Keys:

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.

2.2     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. It will automatically find the first
          file with a number that doesn't exist.

R.ALT-S - Saves the voxel as VOXEL000.VOX

L.MouseButton - Plot a pixel.

R.MouseButton - Drag the 2D EDIT MODE window.

L.ENTER - Change the viewing mode. There are 3 viewing modes.

        0: Shows the current cross-section only
        1: Shows the full non-perspective view starting from beginning of
           axes
        2: Shows the full non-perspective view starting from end of axes

Backspace - Changes the current drawing color to 255. Essentially this is
            "erase" mode.
            
F - Flood fill the region using the current drawing color as the border.

C - Change all colors from what's under cursor to current drawing color.
    If showthough is "0", changes are made only in cross section, otherwise
    the entire voxel is changed.

J - Junking function. Randomly changes about every 16th pixel of color
    under the mouse cursor to the current drawing color.

B - Press this key when the mouse is on the color bar to change the
    background color.

T - Trail mode. The mouse cursor will leave a "trail" of the current color.

~ - Toggle the pivot adjustment mode. Use the arrow keys to adjust.

/ - Center the pivot in pivot adjustment mode

<> - Darken / brighten rectangle (mouse cursor must be in a window).
     Select the first corner of the rectangle with the "1" key.

TAB - Choose the current drawing color

SPACE - Plot a pixel using the 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 the 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 or 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 the 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 2D edit 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.
