##############################################################################
# Copyright 2003 Jonathan Cohen, Nat Duca, David Luebke, Brenden Schubert    #
#                Johns Hopkins University and University of Virginia         #
##############################################################################
# This file is distributed as part of the GLOD library, and as such, falls   #
# under the terms of the GLOD public license. GLOD is distributed without    #
# any warranty, implied or otherwise. See the GLOD license for more details. #
#                                                                            #
# You should have recieved a copy of the GLOD Open-Source License with this  #
# copy of GLOD; if not, please visit the GLOD web page,                      #
# http://www.cs.jhu.edu/~graphics/GLOD/license for more information          #
##############################################################################

GLOD 1.0pre3                     Developer Kit                         6/13/04
                      http://www.cs.jhu.edu/~graphics/GLOD
==============================================================================

CONTENTS
  1  Quickstart
  2  Compiling GLOD for Win32,Linux,MacOS
  3  Developing with GLOD
  4  Hacking GLOD
  5  Compatibility
  6  Known issues
  7  Change log
  
==============================================================================

QUICKSTART

So you've downloaded GLOD and you want to see a cool demo.  OK. We
assume you've gotten the binary distribution.

First, you're going to need some PLY files so that you've got something to put
into GLOD. The binary and source distributions do not come with models. You
can download models from the GLOD web page
(http://www.cs.jhu.edu/~graphics/GLOD/download.html) or find a models online.

Once you've got a model "foo.ply":

   1) cd into the GLOD distribution directory
   2) cd bin
   3) simple -c foo.ply

            Note: if you use Linux or MacOS, you're going to have to set
                  up some additional variables before the programs will run.
                  See the COMPILING GLOD section below.

GLOD will generate a continuous multiresolution object from this ply file and
display it on your screen. The top left of the screen will tell the current
"adaptation parameters" of the object. 

A useful mode is "screen space error mode": press the 'e' key, then press the
'-' key until the error thresshold (the t= value) is around .1. Now, move the
model around the screen with your mouse. To zoom press the 'x' key, to rotate
press 'z', and to pan press 'c'.

To see what the offscreen-parts of the model are at, press 'l'. This stops the
mesh from adapting, allowing you to zoom out to look at the mesh in its refined
state.

There are a number of demos (with source code in glod/samples/) distributed
with GLOD. They use mostly the same interaction controls (z,x,c,v for camera
control, h for help):
  simple   :  builds and displays a multiresolution version of a ply file

  scene    :  displays a scene graph of multiresolution ply files 
              Note: sample scene graphs are in glod/data/scenes/. You
                    must be in glod/bin for this program to work.

  read_model:  creates a multiresolution object, but stores it in a 
               file rather than displaying it. You can pass this saved
               file back to read_model to display it. This demonstrates how
               the hierarchy-building process can be decoupled from the
               rendering process.

  read_cut:    after creating a multiresolution object or loading
               one of the files generated by read_model, this program
               allows you to display and interact with the model and then
               save a PLY file of the current adapted geometry. This
               demonstrates the cut-readback functionality of GLOD.
        
       WINDOWS USERS NOTE: these are all command line programs:

Now you've used GLOD. Perhaps you'd like to read about the system itself?
Check out glod/doc/index.html for API documentation and a limited tutorial, or
skim through the sample code in glod/samples/.

===========================================================================
COMPILING GLOD

Although we distribute binaries of GLOD for a variety of platforms, you can
also build it from the sources. We have successfully compiled GLOD on a
variety of Win32, Linux, and MacOS platforms of mixed hardware and software
versions.

------------------------------------------------------------------------------
WIN32 COMPILATION: MSDEV-6
  1) Open the glodlib.dsw project
  2) Pick debug or release build
  3) Set glodlib as the "active project"
  4) Build the project
  5) GLOD.dll and GLOD.lib will be placed in glod/lib

  As necessary (or if necessary), build some of the sample applications
  to test your installation.

  Keep in mind: Windows needs access to glod.dll  for a glod application to
                run. The GLOD compilation puts a copy of glod.dll into
                glod/bin to make debugging of programs faster, but you
                may have to place copies of the dll elsewhere as well.

  Keep in mind: To develop against the GLOD library:
                  1) The compiler msut have access to glod.h from glod/include
                  2) The linker must have access to glod.lib from glod/lib
                You can either:
                  1) Copy glod.h into the developer studio VC98/include
                     directory (a hacky way to do it)
                  2) Put the glod/include directory in Developer studio
                     search path (Tools menu/Options item/Directories tab)
                  3) Add the glod/include directory to your project settings
                     (C++ tab, preprocessor group, additional include
                      directories field)
                The glod.lib can be solved in a similar way. Note that the
                project-settings route uses the linker tab instead.

   New in 1.0pre4: If you are actively modifying GLOD and want to keep another
                   project in-sync with the most-current GLOD files, modify
                   util/post_build.bat to point at where you want
                   the GLOD.dll/lib/h files to be copied after every build.

------------------------------------------------------------------------------
LINUX AND MACOS-X COMMAND-LINE COMPILATION
  1) cd glod
  2) Run  "make release"  (or make debug)
  3) This places a libglod.so in glod/lib/ and compiles the sample
     applications (in glod/bin/). For MacOS, the file will be
     glod/libglod.dylib

  Setting up for RUNTIME : several approaches are possible

     1) Copy libglod.so into /usr/lib, /usr/local/lib or another globally
        accessible library directory.
     2) First, Append the absolute location of glod/lib to
        LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for OSX). Next, if you're
        going to be compiling programs that use GLOD, make sure you
        add -L<path to libglod.so> to your compiler flags.

  Setting up for GLOD DEVELOPMENT : set up your runtime paths as above
     1) Copy include/glod.h to /usr/include or /usr/local/include
     2) Add -I<path to glod>/include to your compiler flags
     3) Add -lglod to your flags for the link step

  See the COMPATIBILITY section for additional information on
  running GLOD on UNIX-like systems.

------------------------------------------------------------------------------
MacOSX XCODE COMPILATION
  1) open the glod.xcode project
  2) select libGLOD from the targets menu
  3) build it
  4) build the sample apps by selecting them from targets
  5) the glod libraries will be placed in glod/lib, binaries will be built in
     glod/bin

  To run the GLOD sample programs, you will need to open a terminal and follow
  the "Setting up for RUNTIME" directions from the LINUX directions above.


==============================================================================
DEVELOPMENT WITH GLOD

Please see glod/doc/index.html for further information.

If you're going to become a GLOD power-user, you're probably going to want to
know a few things:

   1) Access to the API reference: 
         a) glod/doc/index.html    
            contains the API guide
         b) If you're on a Unix-like system, glod/doc/man contains GLOD
            man-pages. You can:
                     i:   Set MAN_PATH to point at glod/doc/man
                     ii:  Copy the man folder and its contents to /usr/man

   2) How to compile against GLOD
         a) Look at glod/samples/simple   for a very simple GLOD application
         b) Read the documentation
         c) Bug the developers to write more about this.

==============================================================================
HACKING GLOD

If you've seen the GLOD source before, or want to learn it, here's a quick
tour:

 glod
   src              \
   include           > Source code for the GLOD library plus sample stuff
   samples          /

   bin              \
   lib               > Automatically generated code. Note that the html
   doc              /  and man pages in doc are made from src/doc
   
   glodlib.dsw      \
   glod.xcode        > Make's for various platforms. Makefile.conf is used
   Makefile.conf    /  by all UNIX-like compilations to build
   Makefile        /

   util              > Scripts used to build release archives


==============================================================================
COMPATIBILITY

GLOD has been tested on a limited variety of operating systems. The following
are known to work:

    > WIN32 w/ MSDEV6
    > RedHat 7.3, RedHat 8, RedHat 9
    > MacOSX 10.3 w/ GCC3.3

You may run into trouble but ultimately succeed with:
    > The project files for Win32 with .NET may slightly out-of-date

    > WIN32 and Cygwin (make sure you get the source ZIP not tar!)
                       (src/doc will not build unless you dos2unix the
                        src/doc directory beforehand)

    > *NIX with Mesa and hardware-GL: make sure that your compiler finds
      the hardware OpenGL drivers before it finds the MESA ones.


You will definitely have trouble running GLOD with:

    > MacOSX 10.2 (there is hope if you upgrade GCC)
    > DOS 3.1

==============================================================================
KNOWN ISSUES
	- Screen-space refinement mode fails to cull objects that lie in the
	  eye plane of the currently bound view.


==============================================================================
CHANGELOG

        - Added support for quadric error metrics
        - Added snapshot modes to control construction of discrete
          hierarchy levels
        - Compatibility with MSVisualStudio.net and gcc3.5
        - Fixed memory leaks in VDS, GLOD, Discrete
        - Bugfix to texture issue in Continuous mode
        - Discrete code cleanup
        - Half-edge-collapses use a single vertex array for rendering in
          Discrete mode.
        - Post-build step for Win32 environments (see util/post_build.bat)
          that copies GLOD files into a predefined destination
        - Better configured MSDEV6 workspace (simultaneous
          Debug/Release builds)
        - Major optimization vertex projection code (VDS::Mat4 rewrite)
        - Various cross-platform tweaks
        - Tiled-rendering support
        - Experimental support for discrete patch-LOD.
        
1.0pre3 (06/13/2004)
        - Changed method of screenspace error computation
        - Added BORDER_LOCK mode to hierarchy builder
        - Added MacOSX support
        - Optimized speed of vertex sharing for models > 100k vertices
        - Optimized speed of builder priority queue
        - Optimized speed of building discrete hierarchy for models
          with large number of patches
        - Bug fixes to triangle budget mode
        - Bug fixes to reading OpenGL vertex arrays
        - Bug fixes to instantiation
        - Bug fixes to continuous readback
        - Major directory restructuring
        - Better README :-)

1.0pre2 (10/23/2003)
        - Converted high-performance path from NV_VAR to VBO

1.0pre1 (7/25/2003)
        - Initial release

==============================================================================
        Email [email protected] with getting-this-working issues and bugs.
==============================================================================
                    http://www.cs.jhu.edu/~graphics/GLOD
GLOD 1.0pre3                     Developer Kit                         6/13/04