Overview:
---------

See the file doc/lib3d.html for an overview.

Mailing List
------------

The mailing list is dead.  If you can help rebuild it, please contact me.

Problems:
---------

See the file doc/low-level because it's the only other documentation.

If problems persist, send me the following information:
	
	- Exactly what the problem is.
	- The exact circumstances under which your problem occurs.
	- The version of lib3d you are using.
	- The output of xdpyinfo (important if you aren't using 8bpp)
	- The output of the configure script (see below) and the contents
	  of the file config.log.

Compiling:
----------

For UNIX:

1)	Run the configure script from this directory, eg:
	
	$ ./configure

	Under some (maybe many) systems, it is necessary to explicitly
	state the X paths.  I know this is the case on OSF/1 systems:

	$ ./configure --x-includes=/usr/X11/include --x-libraries=/usr/X11/lib

	you can also try:
 
	$ ./configure --help

2)	Run make from this directory:

	$ make

For DOS / djgpp:
	
	You need binutils 2.8.1 or better - version 2.7 does not work !
	You will also need the Allegro framebuffer library version 3.
	Color depths 8, 16 and 24 are supported (lib3d's 24-bit depth
	internally maps to Allegro's 32-bit).

1)      Simply run make:

        make -f Makefile.dj2 



Demo Programs:
--------------

These are the most interesting demos, and are built by the default target
in the makefile:

testnff:
	You should see a window showing a rotating teapot, initially quite
	close, and then a little further away.  Some timing statistics are
	printed.  The teapot model has 240 polygons, and is rendered 1024 times
	in each view.  The process is repeated with gouraud shading, wire frame
	and texture mapping.

testobj:
	Much like demo3d, but the teapot has 3751 polygons.  Makes for 
	much more impressive performance figures.  Also makes for
	much saner frame rates (44fps vs 200fps on my P100).  

testplg:
	A nice plant model.

testcube:
	Some rotating cubes.


Less interesting, but useful if you are working on lib3d:

	testmod - Rotate a 4 polygon pyramid.
	testvis - Put the rasterization engines through some simple tests.
	testdev - Test the interface to the underlying display mechanism.
	testmat - Maths maths maths.


Todo List:
----------

If you like the look of something here, feel free to join right in...

- The major concentration of effort has been on the rendering of an existing
  object hierarchy.  Work needs to be done in the areas of construction and
  ongoing manipulation of these hierarchies.  This includes:
	- Readers for popular file formats.
	- Structure sharing within the hierarchy, which is currently
	  a strict tree, but should be a DAG. 
	- Mechanisms for reparenting subtrees.
	- Reexamination of the restriction of a single pipeline (rendering 
	  style) to a model.  

- Mouse and keyboard abstractions.  

- Some neat demos.  Like a gyrating digital clock screensaver, for instance.
	  
- More substantial programs. 


Some known bugs:
----------------

- Objects close to the far clipping plane tend to self-obscure due to a
  bug with z calculation in the older viewports and the new flat-shaded code. 

- The wireframe pipeline can overdraw the boundaries of the viewport by
  a single pixel on the right and bottom, causing crashes in many
  circumstances.

- Texture buffers always represent pixels using 32 bits.  This is a
  waste of space and hurts cache consistency.  Use of 256 colours
  with a LUT where necessary might prove faster as well as more
  memory-efficient.

- Texture mapping could be faster.