# $Id: README,v 1.10 2004/02/23 03:00:56 wes Exp $ # $Revision: 1.10 $ # $Log: README,v $ # 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.5.1, January 2004 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 rm151/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, Mesa 3.5 (s/w only) h/w: nVidia GeForce2 DDR + nVidia's libGL.so + glx.so (www.nvidia.com, 1.0-4496 and 1.0-5328 drivers) 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-2002, R3vis Corporation.