abandoned3d Files

  ______ ______
 /\  __ \\  __ \
 \ \ \L\ \\ \L\ \
  \ \____ \\  ___\
   \/___/\ \\ \__/
        \ \_\\_\ engine
         \/_//_/

-------------------------------------------------------------------------------
DESCRIPTION
-------------------------------------------------------------------------------
software 3d rasterizer.

this is prototype code, and is not slated to be a stand alone 3d engine. it's
a collection of test programs to figure out what can and can't be done in soft-
ware, workout math bugs, help make decisions about the graphics pipeline,
various interfaces, and for fun.


-------------------------------------------------------------------------------
COMPILE
-------------------------------------------------------------------------------
drivers are available for SDL and X11 API's, compile with:

  make sdl
  make x11

the SDL driver is used by default. 

if you have both, prefer the SDL drivers. if you dont have either, look at the
examples in driver and bake your own, or download the SDL source and/or binary
for free at 'www.libsdl.org'.

the engine uses 32bit color internally by default, but can write 8, 16, 24 or
32 bit surfaces regardless of internal settings.

successfully compiled under GCC 3.3.3
successfully compiled under GCC 4.7.1

uses C99 features. if you don't have a C99 compliant compiler, try a C++ build.
i've tried to keep the code ANSI compatable to the best of my ability.


-------------------------------------------------------------------------------
DIRECTIVE
-------------------------------------------------------------------------------
make directives and effects:

  NDEBUG:
    turn off debugging checks and messages.

  ANISOTROPIC_NICEST:
    use expensive anisotropic calculations.

  USE_THREADED_SPAN_RENDERING:
    accelerate rendering on multi-core systems (requires pthreads).
    (base test1 speedup is @ 1.5)

  E3D_MODE_INTERNAL_*:
    specify internal bitmode (8, 16, 32).

-------------------------------------------------------------------------------
COMMAND
-------------------------------------------------------------------------------
 --help - show command line options.

 -magfilter [MAGFILTER MODE]  -  set magnification filter.
 -minfilter [MINFILTER MODE]  -  set minification filter.
 -screendim [WIDTH] [HEIGHT]  -  set screen dimensions.
 -holdframe [FRAMES PER SEC]  -  limit framerate.

 -nomipmaps  -  turn off mipmap generation.
 -usecolmip  -  use high visiblility colored mip levels.
 -enablefly  -  enable flymode.
 -enablefog  -  enable fog for entire scene.
 -enablelit  -  enable lighting for entire scene.

 -tesselate [1 .. 20]  -  tesselate receivers (need enablelit).
 -hspecular  -  use high specular material (need enablelit, suggest tesselate).

magfilter modes:
  nearest, linear.

minfilter modes:
  nearest_lod_nearest, linear_lod_nearest, nearest_lod_linear, linear_lod_linear,
  anisotropic.

for fastest rendering:
  ./test1 -nomipmaps -magfilter nearest

for nicest rendering:
  ./test1 -magfilter linear -minfilter anisotropic -enablelit -tesselate 20

options are case insensitive.
default settings use unlit, trilinear filtering at 400x300 resolution.


-------------------------------------------------------------------------------
CONTROL
-------------------------------------------------------------------------------
controls are:

    up:     W
    down:   S
    left:   A
    right:  D
    pause:  P
    quit:   ESC

and the mouse looks around.


-------------------------------------------------------------------------------
FILE
-------------------------------------------------------------------------------
directories:

  demo       -  test programs.
  driver     -  drivers and interface.
  libcont    -  container library.
  libEZX     -  simple X11 interface library.
  libmath    -  math library.
  mbset      -  multibyte memory filling.
  main       -  main engine code.
  material   -  image resources (BMP).
  util       -  general utilities.


-------------------------------------------------------------------------------
NOTES
-------------------------------------------------------------------------------
this uses a custom coordinate system.

-y
 |  +z
 |  /
 | /
 |/
 +------ +x

the default projection will have you at position (0,0,0) looking up the
positive z axis (0,0,1) with negative unit y (0,-1,0) as the up vector.
vertex ordering is clockwise by default.

the initial reason for this break from convention was that i felt it was more
intuitive to have movement into the screen (forward) as positive, and although
every math text has positive y-axis going up, every computer screen has the y-
axis as positive going down (software conforming to hardware or something),
with winding order, again the idea that clockwise motion was more intuitively
forward motion. in retrospect this was probably a mistake.

the inverted axis' can be converted by pushing an inverting scale as the base
(identity) matrix. winding order can be reversed by selecting the appropriate
cull mode.

in it's current state, this is really only good at rendering world geometry.
the edge list used internally for hidden surface removal works best for
large polygons with few vertices. if you throw a model with a ton of tiny
triangles at it, it's gonna chug.

much of this code is experimental and is being constantly rewritten. since my
style is still evolving, there will be differences across new and old files.
hopefully it wont hurt readability too much.

some code is duplicated across files to eliminate dependencies in directories
designed to be 'stand alone' (libcont, libmath, libEZX, util).

code may be used without restriction.
code is provided 'as is', use at your own risk.

enjoy - HB;