# $Id: README,v 1.9 2001/07/15 23:39:06 wes Exp $
# $Revision: 1.9 $
# $Log: README,v $
# Revision 1.9  2001/07/15 23:39:06  wes
# Changed version number from 1.4.0-beta1 to 1.4.0.
#
# Revision 1.8  2001/06/03 20:56:20  wes
# v140-beta1
#
# Revision 1.7  2001/03/31 17:13:47  wes
# v1.4.0-alpha-2 checkin
#
# Revision 1.6  2000/12/03 22:52:37  wes
# v1.4.0-alpha-1
#
# Revision 1.5  2000/08/31 02:13:57  wes
# Updated version number, 1.3.0 release date.
#
# Revision 1.4  2000/05/17 14:34:36  wes
# partial 1.3.0 update.
#
# Revision 1.3  2000/04/22 02:03:15  wes
# More OpenRM 1.2.1 updates.
#
# Revision 1.2  2000/04/20 17:54:11  wes
# OpenRM 1.2.1 info updates.
#
# Revision 1.1.1.1  2000/02/28 21:29:40  wes
# OpenRM 1.2 Checkin
#

Current Version: OpenRM 1.4.0, 15 July, 2001.

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)
   Irix
   Solaris
   Win32 (95/98/NT, W2K's OpenGL is almost not usable at this time)   

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. Find one that suits your needs and use it. Another compelling
reason to investigate OpenRM is the fact that OpenRM development
has been funded by SBIR Grants from the US Department of Energy,
Office of Science - this is a "serious" Open Source project.


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.

We want you to use OpenRM in commercial apps. In return, we ask
that you play by the rules outlined in the LGPL.


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
RM140/doc directory that can be run that will 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 will become available from
R3vis Corporation in the near future: a two-volume RM Scene Graph
programming series. These books will be the equivalent of the OpenGL
Red and Blue books. Those books will not be free (sorry), but will
be extremely useful to developers. We expect the first such publication
to occur around April, 2001.

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 four requirements for building OpenRM: (1) you need a C 
compiler, (2) you need OpenGL, (3) you need to have an implementation 
of Posix threads on your machine, and (4) you will need version 6b of
the JPEG library and header files.

On our Linux systems, we use Mesa (www.mesa3d.org) for OpenGL. We have
also done extensive testing with the OpenGL drivers from nVidia (nvidia.com).
These work well, within limits. See the RELEASENOTES for more information.

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 (watch out for W2K, our experience
with a late beta version was discouraging).

Our three test and development environments (Linux, Solaris and Irix) all
have an implementation of Posix threads included with the system. We assume
other Unix variants include a vendor-supplied implementation as well. 
Win32 users can download (for free) a version from:
	http://sources.redhat.com/pthreads-win32/
That version contains source and prebuilt binaries - no compilation is
required. This implementation works well - please drop Ross Johnson a
note of thanks (pthreads-win32 project leader).

Some systems (IRIX, Linux) include the JPEG headers and libraries
as part of the system. Others (Solaris, Win32) require that you
obtain and build the source. You can download the JPEG-6b library
source code for free from the Web by visiting:
	http://www.ijg.org/


OpenRM Installation
-------------------

Unix:

0. Unpack the distribution into some directory, like /home/rmdev/rm120,
   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. Possibly edit $RM/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 3 libraries in $RM/lib: librm.*, librmv.* and
     librmaux.*.

Win32:
Same steps as Unix, execpt/additionally:

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

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

   Note the following comments from a contributor (thanks, Hans!):

   >Date: Wed, 14 Feb 2001 13:52:02 +0100
   >From: "Hans Josef Classen" <hclassen@cae-gmbh.de>

   >In fact, the update is required in make.cfg in the win-32 and win-32-
   >dll section:

   >"GLINC=\"c:\programme\microsoft visual studio\vc98\include\GL\"" \

   >and

   >"CFLAGS = /c /nologo /MLd /W1 /Gm /GX /ZI /Od /D \"WIN32\" /D
   >\"_DEBUG\" /D \"_WINDOWS\" /D \"_MBCS\"  /FD /GZ -
   >I\"c:\programme\microsoft visual studio\vc98\include\" -I..\include /D
   >\"RM_WIN\" " \

   >Note the \" surrounding the path. windows.h is located in the
   >compiler's include subdirectory.

   >For the demos, I added the path to windows libraries to the line

   >RMLIBS=/LIBPATH:$(RMLIBROOT) /LIBPATH:$(GLLIBROOT)
   >librm.lib librmaux.lib librmv.lib

   [ the stuff that follows are suggestions for improvement and will
   be addressed in a later release - wes ]
   >As far I understand, GLLIBROOT shall specify the path to GL, not
   >the standard libraries, so the variable names could be improved, e.g.
   >by additionally defining
   >
   >MSLIBROOT="c:\programme\microsoft visual studio\vc98\lib"

   >and further

   >RMLIBS=/LIBPATH:$(RMLIBROOT) /LIBPATH:$(MSLIBROOT)
   >librm.lib librmaux.lib librmv.lib


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

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

What next? Try out the demo programs that use OpenRM available from
openrm.sourceforge.net.

Online Documentation
--------------------

OpenRM includes a facility that will construct browser-viewable
HTML "man pages" directly from the source code itself. There is
a README located in the $RM/doc directory that explains this
process and the documentation in more detail.


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 6.0/6.1/7.0, Mesa 3.2 and greater (s/w only)
   h/w: nVidia GeForce2 256 + nVidia libGL.so + glx.so (www.nvidia.com)
Win32: 95/98/NT/W2K, MSVC++ v6.0. 


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-2001, R3vis Corporation. 

--EOF--
