                       +------------------------------+
                       | VOXED voxel editor reference |
                       +------------------------------+

-------------------------------- INTRODUCTION --------------------------------

   The user interface isn't so easy right now - there are a lot of keys you
need to memorize. There are a lot of weird combinations that are useful, but
sometimes it's not so obvious, so please explore and try to be creative.
   In my documentation, when I use the word "box", I am referring to a cube,
where the lengths of the 3 sides aren't necessarily of equal length. I prefer
to reserve the word "rectangle" for 2D primitives only. Also, any controls
that have a prefix of "KP" means that I'm talking about the key on the KeyPad.
   One of the most confusing things are the 3 different types of cursors. You
should try to understand this before reading the rest of the documentation.

  Screen-cursor: This is the dot that's ALWAYS in the center of the screen.

Numbered-cursor: These are the "spheres" that appear when you press SPACE bar.
                 They have a number in the middle of them, starting with 0 and
                 incrementing as you insert more of them (up to 100). They are
                 intended mainly for editing functions which require 3 or more
                 points as input (for example, the sector & lathe tools) These
                 cursors can only be moved by dragging them with the mouse.
                 These are usually used BEFORE you insert an object.

    Mini-cursor: These are smaller "spheres" that get inserted automatically
                 after you insert an object, such as a box or sphere. They
                 have no numbers inside them. Mini-cursors must be moved with
                 the keypad controls: (1,2,3,4,5,Enter)
                 These are usually used AFTER you insert an object.

------------------------------- GETTING AROUND -------------------------------

ESC             Quit
M		Map
Mouse X/Y       Turn left/right, Look up/down (Press 'Y' to invert)
Arrows          Move Forward/Backward/Left/Right
R.CTRL          Move Up
KP0             Move Down
R.SHIFT         Hold down to speed up movement (by 4 times)
L.SHIFT         Hold down to slow down movement (by 4 times)
KP*, KP/        Zoom in/out. Use the other / (next to SHIFT) to reset
R.MouseBut      Hold this down and move mouse left/right to tilt screen.

------------------------------- SIMPLE EDITING -------------------------------

  (These functions don't require an understanding of the cursor types)

Home            Insert sphere (mini-cursor becomes center)
End             Delete sphere (mini-cursor becomes center)
ALT+Home        Voxel spray (hold it down) - works like spraypaint, but
                   inserts voxels instead of changing color.
ALT+End         Voxel suck (hold it down): works like spraypaint, but deletes
                   voxels instead of changing color.

[ and ]         Decrease/increase radius of sphere, ellipsoid, or cylinder
; and '         Change superquadric power (p) of sphere (default:p=2)
                     abs(x)^p + abs(y)^p + abs(z)^p = r^p
                   Notice when p=2 in this equation, it's a sphere.
                   Sounds complex, but it really isn't. Try it!
                These keys also change the brightness of the flash function

X               Paint color onto individual voxel permanently
Tab             Select current drawing color to color under screen-cursor
KP+ and KP-     Change procedural texture. There are 7 currently defined:
                   0:cur   Solid color from the color bar
                   1:floor Set to first color below position (default)
                   2:jit   Take current color and randomize a little
                   3:many  A funny looking RGB color cube
                   4:sph   Use this one for shading spheres
                   5:wood  An interesting wood pattern
                   6:png   Enabled when you load a PNG file using 'V' key,
                              otherwise it acts like the "0:cur" mode.

\               Undo/Redo most recent modification

------------------------------ COLOR SELECTION -------------------------------

   Color can be selected before you insert an object, but it is best to select
it afterwards, so you don't end up changing the color of the previous object.

L.Enter         Activate/Deactivate color bar
L.MouseBut      Select color (when color bar is activated)
R.MouseBut      Hold and move mouse up/down. Use this to change the palette
                    brightness (when color bar is activated)

--------------------------- LIGHTING MANIPULATION ----------------------------

   I recommend you saving the map BEFORE you go nuts with the lighting. This
is because the lighting functions tend to deteriorate the colors of the map
if you use them too much.

F               Flash! This is the main lighting function. Press it and
                   everything you can see (within a distance) will brighten.
ALT+F           Old flash. Use in the same way as F, but this uses an older
                   lighting algorithm which has moire pattens on the curves.
Caps Lock       Darken all intensities on map by 25% Useful before a flash.
Z               Hold to blend nearby intensities. Use this to remove the
                   aliasing you see after a "flash".
SHIFT+Z         Hold to blend nearby voxel colors.
S               Hold to delete thin voxels. By thin voxel, I mean any voxel
                   with air on opposite sides. If you use this before a
                   "flash", you can improve the lighting. (It removes the
                   possibility of a voxel getting brightened on one side and
                   it appearing bright on the back side as well.)
L.CTRL          Hold to brighten area slowly, randomly, & smoothly. This is a
                    different effect from "flash", and also a lot slower.
L.CTRL+L.ALT    Hold to darken area slowly, randomly, and smoothly.

-------------------------- MINI-CURSOR MANIPULATION --------------------------

KP1,KP2,KP3,KP5 Move mini-cursor Forward/Backward/Left/Right 1 unit
KP4             Move mini-cursor Up 1 unit
KPEnter         Move mini-cursor Down 1 unit
KP.             If .KV6 sprite is selected, this x-flips the object (so the
                   writing is backwards). This is a good way to save memory.
KP9             Toggle between 1 mini-cursor and all mini-cursors. When you
                   see only 1 mini-cursor, dragging that point will move just
                   that 1 point. When you see more than 1 mini-cursor, the
                   keypad controls will move the entire object without
                   changing its size. When you switch back to the 1 mini-
                   cursor, the vertex selected is the one closest to the
                   voxel under the screen-cursor. Has no effect for objects
                   that use only 1 mini-cursor.

   NOTE: Some of these keys also let you manipulate numbered cursors.

------------------------ NUMBERED-CURSOR MANIPULATION ------------------------

Space           Insert numbered-cursor. A sphere with a number inside it is
                   inserted at the point under the screen-cursor.
Backspace       Remove last numbered-cursor
/               Remove ALL numbered-cursors. Also resets zoom & angle mode.

L.MouseBut      Drag numbered-cursor (direction restricted to the arrows)
L+R MouseButs   When dragging numbered-cursors around, use this to change the
                   axes. You should see the "arrows" change orientation.
                   Note: You must have BOTH mouse buttons held down!
PGUP/PGDN       Raise lower ceiling/floor of sector object. You must have at
                   least 3 numbered-cursors for this to take effect.

------------------------------ ADVANCED EDITING ------------------------------

Insert/Delete:
   Less than 2 numbered-cursors active:
                Insert/Delete box. The box starts out as an individual voxel
                   (1*1*1) where both mini-cursors are at the same point. To
                   incease the size, use the mini-cursor controls:
                   (1,2,3,5,4,Enter on keypad)
   2 or more numbered-cursors active:
                Fills the selected volume with solid voxels (Insert) or air
                   (Delete).
                Special mode: if you have 3 or more numbered-cursors, and
                   you select .PNG procedural texturing, then it will treat
                   the alpha channel as a signed-char height offset for 3D
                   bump-mapping.

E / SHIFT+E     Insert/Delete Ellipsoid (The mini-cursors are the foci)
L / SHIFT+L     Insert/Delete Cylinder/Line (The mini-cursors are endpoints)
W / SHIFT+W     Insert/Delete Walls. You must have at least 3 numbered-
                   cursors first to use this. Then you must use PGUP/PGDN.
C / SHIFT+C     Insert/Delete Ceiling. Requires >= 3 numbered-cursors.
T / SHIFT+T     Insert/Delete Rotational sweep. Requires >= 3 numbered-
                   cursors. Cursors #0 and #1 become axis of rotation.
                   Everything on the right side of a clockwise-drawn loop
                   will be included as part of the object. It's ok to have
                   points on the left side of the axis, but that area will be
                   ignored.
H / SHIFT+H     Insert/Delete a randomly generated convex hull.
B / SHIFT+B     Insert/Delete Blobs. Requires numbered-cursors. (Not fully
                   working yet)
3               Insert triangle. You must have at least 3 numbered cursors.

4               3D floodfill, starting at camera's location. Floodfill is
                   restricted to numbered-cursor boxes if there are 2 cursors.
5               Lassoo tool. This tool is for filling in cracks - polygons
                   that don't have coplanar points. Press '5' with the mouse
                   cursor on each point of a loop and you should see a path
                   connecting from the previous point. Make sure there is a
                   relatively short path (< ~128 voxels) along the surface
                   between each pair of points. When you complete the loop,
                   press '6' to fill in the gaps.
6               Used in conjunction with '5'. See '5'.

D               Duplicate box. First specify source box using two numbered-
                   cursors. Then press D at the point where you want
                   numbered-cursor #0 to be copied to.
Shift+D         Same as 'D' but doesn't copy air voxels.

U               Insert .KV6/.KVX/.VOX file. If you select a .KV6 file, then
                   the object will stay separated from the map. If you select
                   a .KVX/.VOX file, then the object will permanently become
                   a part of the map.

                You can use 'U' to insert a dummy "DOT" sprite. To do this,
                   type any invalid filename, such as "ASDF" at the openfile
                   dialog and it will be saved as "DOT" in the .SXL file.

                You can use 'U' to insert a dummy "BOX" sprite. To do this,
                   first make a box with 2 numbered cursors, then press 'U'.
                   It uses the vx5sprite .s field for the first corner,
                   vx5sprite .h for the second corner, and .p for the
                   "sphere" handle in VOXED. You can use this info too.

V               Set procedural texture to .PNG file.
P               Paints selected .PNG file onto the voxel map, projected in
                   exactly the same way as what you're looking at.
=               First select a box with 2 numbered cursors. This key then
                   re-calculates all colors inside the box, preserving the
                   state of air or solid.

KP6             For .KVX/.VOX: Rotate object (Switches between x,y,z axis)
KP7,KP8,KP9     For .KVX/.VOX: Flip/Mirror axis (I don't remember which key
                   does what, but I know all 48 possible 90 cases are in
                   there. Keep pressing on the keys until it looks right.)

KP7,KP8         For .KV6: Rotate object left/right
KP6,KP9         For .KV6: Rotate object up/down (depends on your orientation)

-------------------- MODES & OTHER MISCELLANEOUS CONTROLS --------------------

`               Toggle global shading mode:
                   0: no shading (default)
                   1: normal estimation, light sources (in this mode,
                         pressing 'F' inserts a temporary light source)
                   2: normal estimation, no light sources (brighter!)
KP.             Toggle shading (default) / no shading on cube faces (if
                   .KV6 sprite is not selected).
, and .         Select raycast resolution (1-16), 1:best quality&default
R               Toggle smart raycast resolution mode (lower quality when
                   turning quickly, higher quality when still) Default is
                   disabled.
Numlock         Toggle raycasting cut-off distance: 256 (default) or no limit
                   (slow, especially if you're outside)
A               Toggle anglemode (horizon correction (default) vs. free
                   direction)
G               Toggle grid and grid alignment size (16 or 32)

2               Shoot an invisible fireball (just a toy)
F10             Enable MIP-MAPPING.

Scroll lock     Panic Quit (DOS version only): Use to escape from lock-ups.
                   Try to avoid using this key whenever possible.

------------------------------ LOADING & SAVING ------------------------------

ALT+F2          Load .VXL map.
ALT+F3          Save .VXL map. (NOTE: Use F3 to save .SXL separately)
F3              Save .SXL file. (Game data: sky, sprite locations, etc...)
F5              Load new sky from file.
F6              Edit global user string (stored in .SXL files)
F7              Save floating object to .KV6 (put cursor on object)

F12             Screencapture exactly what you see to VXL5####.PNG
ALT+F12         Surroundcapture to VXL5####.PNG (2560*1024 resolution)

   NOTE: Both F12 and ALT-F12 create valid .PNG files, but I use absolutely
   NO COMPRESSION when storing them! You can reduce their size A LOT if you
   are willing to re-compress them with another utility.

------------------------ Known Limitations / Problems ------------------------

Pentium III only!  A lot of my new sprite & z-buffer code uses the new
   Pentium III instructions. If you don't have a Pentium III or compatible
   processor, then the engine will give an invalid opcode exception. It
   would probably take a few hours to get the code working again on an
   MMX-capable machine (with a noticable decrease in frame rate).

Memory: You WILL need at least 128MB of RAM to run this. Do not attempt to run
   it on anything less.

"alloc: vbuf full". Right now, I allocate 64MB of memory to store the voxel
   map. If voxlap5 suddenly exits out with this message, it means the board
   is too complex - too much surface area for the board map to fit within
   this limit, or the memory is too fragmented. In the future, I might
   implement a way of defragmenting the cache, or a better warning, or maybe
   even a disk cacheing system so this never happens.

The following issue applies to the DOS version only:

VESA 2.0 linear mode crashes under NT. I don't know why, but I know how to
   replace the code with slower VESA code that doesn't crash.

-------------------------------- COMMAND LINE --------------------------------

   >voxed [SXL/VXL/DTA/BSP map name] [/(xdim)x(ydim)] [/win]
       (options can be listed in any order)

   If you do not specify a Master sprite file (.SXL), Voxlap5 format (.VXL),
Comanche format (.DTA), or Quake 3 format (.BSP), then voxlap5 tries to load
VXL/DEFAULT.SXL. If that doesn't exist, then it loads a built-in map, with a
gray plain, called "UNTITLED.VXL". You start inside a box in the middle.
   Voxlap5 supports all 32-bit color modes where xdim<=640 and ydim<=480.
Default is 320*200 fullscreen mode. If the mode isn't found, then the DOS
version defaults to true-color emulation mode (320x400 8 bit color which
should work on all VGA compatible video cards). The windows version has no
emulation mode and just exits with an error message.

Some examples:
   >voxed /640x480
      Use hi-res VESA mode (640x480x32) To specify resolution, you must have
      a lowercase 'x' separating the x- and y- dimensions and there can't be
      any spaces in between.
   >voxed /480x360 /win
      Set resolution to 480x360 and use windowed mode instead of fullscreen.
   >voxed 1
      If you have Novalogic's classic game Comanche Maximum Overkill, then
      copy (C1.DTA & D1.DTA) into the voxlap directory and it will load them.
   >voxed c:\games\id\q3ademo\demoq3\q3dm17.bsp
      If you extract *.BSP from Quake3's PAK0.PK3 file, then it will convert
      the geometry from a Quake map. No textures are converted, so the best
      way to view the map is to go wild and press 'F' everywhere.
   >voxed asdf
      Force loading of boring gray plain (assuming asdf doesn't exist)
   >voxed /0
      Forces truecolor emulation (DOS version only)

------------------------ Documentation Update History ------------------------

11/20/2000: VOXLAP5 documentation first written
11/21/2000: Documentation revised for clarity
02/25/2001: Added windows command line info
03/19/2001: Made DOS command line same as windows version
03/28/2001: Added documentation for P & =
05/16/2001: Updated for .KV6 keys (KP6-KP9)
06/23/2001: Updated limitations, added 3D bump & Q3 info
03/05/2002: Added some info about .SXL files & new keys related to lighting
05/14/2002: Added info about 4,5,6,Shift+D, and dummy sprite info with 'U'

------------------------------------------------------------------------------
VOXLAP5 programmed by Ken Silverman (http://www.advsys.net/ken)
Modified by Ben Aksoy (http://www.ace-spades.com)
