# $Id: README,v 1.11 2005/06/12 21:30:52 wes Exp $
# $Revision: 1.11 $
# $Log: README,v $
# Revision 1.11  2005/06/12 21:30:52  wes
# Updates for 1.6.0-alpha2.
#
# Revision 1.10  2004/02/23 03:00:56  wes
# *** empty log message ***
#
# Revision 1.9  2004/01/17 03:57:59  wes
# 1.5.1 beta updates..more to come.
#
# Revision 1.8  2002/09/22 22:58:34  wes
# Updates for v1.4.3 distribution.
#
# Revision 1.7  2002/06/17 00:49:56  wes
# Updated copyright line.
#
# Revision 1.6  2001/07/15 23:00:41  wes
# Updated for v1.4.0-FCS.
#
# Revision 1.5  2001/06/03 20:16:09  wes
# Spotlight demo, JPEG stuff.
#
# Revision 1.4  2001/03/31 16:56:53  wes
# Update date, current arch.
#
# Revision 1.3  2001/03/31 16:55:18  wes
# Added procmode.h, which defines an RMpipe processing mode used in
# most demonstration programs. The default processing mode is
# RM_PIPE_MULTISTAGE_VIEW_PARALLEL.
#
# Revision 1.2  2000/12/02 17:24:32  wes
# Version 1.4.0-alpha-1 checkin. See the RELEASENOTES file for
# a summary of changes. With this checkin, these demo programs
# are no longer compatible with versions of the OpenRM API that
# are pre-1.4.0.
#
# Revision 1.1.1.1  2000/02/28 21:55:30  wes
# OpenRM 1.2 Release
#

Current Version: OpenRM 1.6.0-alpha2, June 2005

Overview
--------

OpenRM Scene Graph is set of tools and utilities that implement a
high performance, flexible and extendible scene graph API. Underneath
OpenRM, OpenGL(tm) is used as the graphics platform for rendering,
so OpenRM is highly portable and can deliver blazing rendering speeds.
OpenRM can be used on any platform that has OpenGL, and has been
built and tested on:
   x86 Linux (s/w via Mesa, h/w via Mesa+native drivers, eg. nVidia)
   FreeBSD
   Irix
   Solaris
   Win32 (95/98/ME/NT/2K/XP)

OpenRM is a derivative work of RM Scene Graph (tm), a commercial
scene graph product from R3vis Corporation. Late in 1999, R3vis announced
the release of OpenRM into the Open Source community, with the
OpenRM debut occuring on 1 March 2000. R3vis continues to maintain
and develop RM Scene Graph, which contains additional features not
present in OpenRM. R3vis placed OpenRM into the Open Source community
in order to promote graphics technology, with sensitivity towards
the high performance research and scientific community, where performance
and economics are important.

Why should you use OpenRM, rather than a commercial scene graph API?
There are four reasons. First, the price is right. Second, inside
OpenRM, you'll find technology and a design that is superior in many
respects (but not all) to what is available in the commercial market.
Third, you get source code. Fourth, OpenRM has a bright future, with
support from leading research institutions and universities.

Why should you use OpenRM rather than some other Open Source scene
graph API? This question is more difficult, since there are several
good ones out there. It depends upon your application, ultimately.
OpenRM doesn't impose an event processing model on you: you can use
the rmaux library for event management, or you can use your own or
someone else's. OpenRM's focus is upon a high performance scene graph
model, period. Unfortunately, there is no "scene graph standard", so
there will continue to be a proliferation of scene graph products
and projects floating around, each with their own flavor and
emphasis. OpenRM is implemented as a high performance, and general
purpose scene graph API. Other Open Source scene graph implementations
tend to focus on narrow application domains, such as first-person
shooter game engines. Find one that suits your needs and use it.


Licensing
---------

OpenRM is being distributed under the terms of the LGPL license.
See the LICENSE.html file included with the distribution; it contains
the text of the LGPL license in HTML form, and was snarfed from
the GNU.ORG website.


Documentation
-------------

Scene graph APIs can be complicated critters. There are three forms of
documentation available with this project. First is the code itself.
Study the demonstration programs. Second, there is a csh script in the
rm160/doc directory you can be run to generate HTML pages
containing "man page" style documentation for the subroutines in
OpenRM. Those derived HTML pages will be posted on the OpenRM.sourceforge.net
website for your convenience, and updated with new code releases.
Third, there will be links to release notes and such from the
OpenRM website.

Another alternative form of documentation is a lengthy tome called the
RM Programming Guide that may be purchased from the R3vis website.
Since OpenRM is an Open Source project, we have to make a few bucks
somehow. We have put a lot of effort into the RM Programming Guide, so
it is of high quality and well worth the low purchase price.

OpenGL documentation is available from a number of sources. We suggest
the OpenGL Red and Blue books, published by Addison-Wesley. There are
a number of other sources of OpenGL information, including www.opengl.org.

The OpenRM project is not intended to provide support for OpenGL. Those
of you working on h/w accelerated Linux projects can appreciate the
issues involved.


Requirements
------------

There are two requirements for building OpenRM: you need a C compiler
and you need OpenGL. That's it.

On our Linux systems, we use Mesa (www.mesa3d.org) for OpenGL as well
as nvidia-accelerated workstations.

On Win32, check your documentation for OpenGL. We use MSVC++ 6.0
which includes the OpenGL headers and libs as part of the
distribution. Typically, we build on NT boxes - those executables
run on all other Win32 platforms.


Installation of OpenRM
----------------------

Unix:

0. Unpack the distribution into some directory, like /home/rmdev/rm151,
   we'll now call that directory $RM for brevity (you don't need an
   environment variable):
   % cd /home/rmdev
   % gunzip -dc <OpenRM-tarball-filename> | tar xvf -

1. Examine $RM/make.cfg:
   - (Note - you shouldn't have to modify make.cfg)
   - Find your target (linux, linux-debug, irix6-n32, etc.)
   - Make sure all *INC lines are OK. E.g. does GLINC point to
     the location of OpenGL/include on your machine?
   - Make sure all *LIB* defines have valid paths for your machine.

   For solaris & Irix, you probably won't have to make any changes.
   For Linux & Win32, you will probably need to make changes.

2. Build:
   - from $RM, type:
     % make <target>        (where target is "linux", "solaris-debug", etc)

3. All done?
   - make sure there are 4 libraries in $RM/lib: librm.*, librmv.*,
     librmaux.* and librmi*.

Win32:
Same steps as Unix, execpt/additionally:

0. Grab, install and configure for use the Posix threads for Win32
   package (see below). OpenRM uses Posix threads and related
   mechanisms in order to implement a high performance, multistage
   and multithreaded rendering engine.

1. Use Winzip (www.winzip.com) to unpack the OpenRM tarball.

2. The pathnames in $RM/make.cfg can be tricky..did you install your
   compiler to C:\Program Files\...? If so, good luck. We put our
   compilers in places where there are no spaces in the pathnames.

3. Build -
   - from $RM, type:
    % nmake win-32-static

   Note: if you're using MSVC++, be sure to run the vcvars32.bat script
   before building OpenRM, otherwise nmake will fail.

   Note 2: win-32-static builds static libs, win-32-dynamic builds DLLs.

Installation of Posix Threads for Win32
---------------------------------------

Starting with OpenRM v1.4.0, OpenRM *requires* an implementation
of Posix threads. For Win32 platforms, there is a freely available
version available (all Unix variants we have tested provide some
sort of native implementation of pthreads). We have used this version
extensively during development and testing, and are quite happy with
the results.

Installation and configuration is straightforward.

0. Grab the distribution (pre-built DLLs, headers and sources) from:
	http://sources.redhat.com/pthreads-win32/
   If sources.redhat.com is busy, you can grab a copy from the
   R3vis website at:
	http://www.r3vis.com/sourceForgeMirror/pthreads-2001-06-06.exe

1. Unpack the distribution. In our development, we unpacked the
   distribution into a directory called C:\pthreads-win32

2. MSVC++ users - modify your VCVARS32.BAT file to include
   c:\pthreads-win32\DLL in the PATH. This is needed in order for
   the linker and runtime loader to find the pthreads-win32 DLLs.

   There are actually many different ways to "get DLLs into your
   path." We prefer this way because it requires the least amount
   of effort.

Installation of JPEG
--------------------

New in OpenRM v1.4.0, OpenRM includes support for raster
image input and output (PPM & JPEG). While PPM support is completely
native, JPEG support in OpenRM requires that you have version 6b
of the JPEG library and header files installed on your build machine.
Some systems (SGIs, and most Linux systems) include these headers
and libs as part of the system, while other platforms (Solaris, Win32)
do not.

To obtain the source code for the JPEG library, go to www.ijg.org
and follow the links to download the source code. In our experience,
it was a fairly painless process to download and build.

On Unix systems, just run the ./configure script in the unpack
directory, then type "make."

On Win32 systems with MSVC++, in the jpeg-6b unpack directory,
copy the file jconfig.vc to jconfig.h, then type nmake to build
the library.

The RMDEMO configure script adds a new parameter that is used to
specify the location of the JPEG distribution. Use the
"-jpeg=/dir/to/jpeg-stuff" flag to specify a location to the
JPEG distribution on your build machine.  We make the
following assumptions inside the makefiles: (1) that if you are
building the libs from the jpeg-6b src distribution, that the
headers and resulting libjpeg.a (or libjpeg.lib on Win32) live
in the jpeg-6b directory, or (2) that if your build machine
includes JPEG headers and libs as part of the system, that
headers and libs are in separate directories, such as /usr/include
and /usr/lib.

Note that the RMDEMO configure script is only for Unix-based
systems. On Win32, you will have to swim through the Makefile.w32
file to update the path to the JPEG libs and hdrs (look at the
comments inside Makefile.w32).

By default, the OpenRM distribution builds to include support
for JPEG i/o. Therefore, by default, the RMDEMO programs will not
link unless you have the JPEG headers and libs on your build machine.
If, for some reason, you wish to exclude JPEG support from OpenRM
(perhaps so that you can avoid the hassle of downloading and
building the JPEG library), you can quickly disable all support in
OpenRM for JPEG by modifying the file $RM/include/rmi/rmi.h
and changing RM_JPEG from 1 (one) to 0 (zero) and rebuilding the
librmi.a/.so/.lib libraries.


Installation & Building the Demo Programs
-----------------------------------------

First, make sure that you have OpenRM installed and built. In the discussion
that follows, we'll call the OpenRM home $RM, and we'll call the directoy
where you've unpacked the OpenRM Demo Programs $RMDEMO.

Unix/Win32:

0. Unpack the RMDEMO distribution.

   Win32: use Winzip (www.winzip.com)
   Unix: gunzip -dc <OpenRM Demo Program Tarball filename> | tar xvf -

1.a Configure: (Unix only) Run the configure script
    This isn't GNU's autoconf thing, this is home brew. The $RMDEMO/configure
    script needs to know 3 things:
    a. Where is OpenRM installed?
    b. Where is OpenGL installed?
    c. Where is X11?

    in addition, the following two parameters might be useful:
    d. What level of optimization to use? (eg, -g, -O3, etc.)
    e. Which flavor of Irix to use? (eg, 32, n32 or 64)

    Specify it like this:
    ./configure -rm=/path/to/openrm -opengl=/path/to/opengl \
        -x11=/path/to/x11

    X11: You shouldn't have to specify anything for -x11, configure has pretty
    good defaults for that.
    OpenGL: Mesa users will point to the root directory of the Mesa install.
       Otherwise (on vendor-supplied OpenGL), configure has good defaults for
       the "supported" architectures.
    OpenRM: you'll probably have to specify something for this parameter.

    Running "configure -foo" will print something helpful.

    Note: the parser inside this script is brain-dead. Don't embed spaces
    in the arguments. E.g.,
	-rm=/tmp/foo   is good, while
	-rm = /tmp/foo is bad.

1.b Configure (Win32)
    Sorry, but you have to swim in Makefile.w32. It's not that bad, you
    just need to provide pathnames for three values:
	(a) MSLIBROOT is the location of the development libaries,
	(b) RMROOT is the location of the $RM libraries (librm.lib, etc.)
	(c) PTHREADSROOT is the location of the pthreads-win32 installation.
	(d) JPEGHOME is the location of the JPEG 6b headers and libraries.

2. Build the demo programs.

   Unix: make -f Makefile.x11
   Win32: nmake /f Makefile.w32

3. Run the demo programs.
   See openrm.sourceforge.net for more detailed information about the
   demonstration programs.

   Win32 - the demo programs will not run unless the pthreads-win32
   DLLs are in your $PATH.


Current Architectures
---------------------

We've built and tested OpenRM on these architectures:

Solaris 2.5.1/2.6/2.7 + Solaris OpenGL 1.2
Irix 6.X (o32,n32,64) + Irix OpenGL
x86 Linux RH 7.X/8.0/9.0, SuSE 9.2Pro/9.3Pro, Mesa 3.5 (s/w only)
   h/w: nVidia GeForce2 DDR + nVidia's libGL.so + glx.so (www.nvidia.com, 1.0-71.67)
Win32: 95/98/NT/2K/XP, MSVC++ v6.0 (only) on an assortment of Matrox, i810/i815
   and nVidia accelerators.

Trademarks
----------

RM Scene Graph and RM are registered trademarks of R3vis Corporation.
OpenGL is a registered trademark of SGI.


Copyright
---------

OpenRM is Copyright (C) 1999-2005, R3vis Corporation.