VRwave 0.9 Source Code Distribution
===================================


This file contains instructions for building the VRwave source code in
Unix/X11 environments.



Contents
--------


- Requirements

        what you need to compile the source code

- Plug-in/Java-EAI Issues

        what you need to consider for netscape plugin

- Directory Structure

        what is where in the subdirectories

- Compiling Java classes

        make .class files form .java sources

- Compiling Native Code

        make an .so library form .c sources

- Running VRwave

        after compilation

- Compiling the netscape plug-in

        for VRML scenes <EMBED>ded into HTML



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


* Java JDK 1.0.2 or 1.1.x to compile the Java source code

* gcc or any other Ansi-C compiler to compile native C code

* OpenGL or Mesa (see README)

* optionally netscape plugin SDK for Unix (see below)

* basic knowledge of Java and makefiles will be helpful



Plug-in/Java-EAI Issues
-----------------------


VRwave 0.9 supports the VRML 2.0 Java-EAI interface -
see test/eaitest/VRwaveEAI.html for more information.

The usual way to use Java-EAI, is to use an <EMBED> tag for embedding
the VRML scene in HTML, which requires a netscape plugin.

To compile the netscape plug-in version of VRwave, you have to
download the netscape plug-in SDK. We used version 3.0b5 of the
plug-in SDK for Unix.

Use the following entry points with links to download pages and
documentation:

3.0: http://home.netscape.com/eng/mozilla/3.0/handbook/plugins/index.html
4.0: http://developer.netscape.com/library/documentation/plugins.html

Download location: ftp://ftp.netscape.com/pub/sdk/plugin/unix

When done, cd into directory native and create a link "SDK" to point
to the location of the plug-in SDK.

Be sure to use JDK 1.0.2 for netscape 3.x compatibility (we have not
yet got VRwave to run under netscape 4.x).



Directory Structure
-------------------


    .           readme files, compilation scripts

    javasrc     Java source files

    jdoc        javadoc generated documentation (HTML pages)

    test        execution scripts, sample data

    native      source code of native methods (C code)
        cfg         configuration files
        ge3d        GE3D includes
        pisrc       plug-in sources


packages under javasrc:

iicm/ge3d               rendering context (OpenGL/Mesa interface to GE3D)
iicm/ge3dsample         GE3D example application
iicm/utils3d            various 3D utilities (Vectors, Matrices, Quaternions etc.)
iicm/vrml/pw            VRML 2.0 parser pw ("parse world")
iicm/vrml/pwutils       utilities (data structures) needed by pw
iicm/vrml/pwsample      pw example application
iicm/vrml/vrwave        main classes of the VRwave VRML 2.0 browser
iicm/vrml/vrwave/pwdat  extra data for pw nodes stored by vrwave
iicm/widgets            GUI widgets
vrml/external           Java-EAI implementation: Browser, Node
vrml/external/exception Java-EAI exception classes
vrml/external/field     Java-EAI field types and event classes



Compiling Java Classes
----------------------


For unfortunate reasons (read: bad Java-EAI example files using
Javascript code instead of Browser.getBrowser() for obtaining a
browser handle), you have to make source code changes in some Java
files, unless you have downloaded the netscape plug-in SDK for
building the VRwave netscape plug-in.

To make the Java sources independent of netscape's Plugin class,
comment out the line "import netscape.plugin.Plugin" in file
javasrc/iicm/vrml/vrwave/VRwave.java. To get a Java-EAI version which
still works via the Browser.getBrowser() call, get rid of "extends
netscape.plugin.Plugin" in file javasrc/vrml/external/Browser.java.


In either case, just execute script "makeit" to compile the Java
sources.

* javac must be in your PATH
* CLASSPATH only needs to be be set to locate Java's own classes.
  VRwave package directories are set by the makeit script.

a new subdir classes will be created to hold the .class files.

"makeit" may take a few minutes to complete.



Compiling Native Code
---------------------


0. Why native code anyway?

The native code implements the rendering interface to the graphics
library. Native code is used both for performance reasons and due to
the current lack of a 3D API for Java (the Java3d draft specification
is now available).

With the upcoming Java3D package (and variants like Cosmo3D) it will
be possible to write a graphics application like VRwave entirely in
Java.

Currently we still use the (soon to be out of date) JDK 1.0.2 style
native interface, but we intend to port native code to JNI (JDK 1.1),
JRI (netscape) and/or RNI (MS IE).


1. Graphics Library

You need either the OpenGL headers/libraries for your system or a copy
of the Mesa 3D Graphics library.

OpenGL (http://www.sgi.com/Technology/openGL/) comes with SGI machines
and is available for other numerous other machines as well (e.g. part
of the Open3D package for Dec Alpha). Native OpenGL implementations
are generally optimized for particular platforms, including hardware
acceleration where available.

Mesa is a 3D graphics library (by brianp@ssec.wisc.edu) with an API
very close to the one of OpenGL, which renders in software and works
on any X display. Mesa is distributed under the GNU LGPL.

You can download Mesa from one of the locations listed at
http://www.ssec.wisc.edu/~brianp/Mesa.html and compile it according to
the instructions you find therein.

Make sure to have a compiler switch set (e.g. -fPIC for gcc, -KPIC for
cc) that allows linking of Mesa against a shared library; however it
is not necessary to build a shared version of the Mesa library itself.
E.g. clean all Mesa object files, build a shared Mesa library and
afterwards rebuild a static version.


2. CPU environment

Set the CPU environment variable according to your machine type
(please use the following conventions, some source files may have
ifdef'ed platform-specific code):

   $CPU value   machine       graphics  JDK version
   ----------   -----------------------------------
   SGI_GNU      SGI           OpenGL    1.0.2
   SGI_J112     SGI           OpenGL    1.1.2
   SGI_MESA     SGI/rem.dpy.  Mesa      1.0.2
   SUN5_GNU     Sun Solaris   Mesa      1.0.2
   SUN5_J113    Sun Solaris   Mesa      1.1.3
   ALPHA_GNU    Dec Alpha     Mesa      1.0.2
   ALPHA_OGL    Dec Alpha     OpenGL    1.0.2
   HPUX10_cc    HP-UX         Mesa      1.0.3
   LINUX_ELF    Linux/ELF     Mesa      1.0.2
   LINUX_J113   Linux/ELF     Mesa      1.1.3

If your system is not listed but meets the requirements, choose an
appropriate name.


3. Create your CPU dir

All machine-dependent stuff will be put into a separate subdir. This
allows you to compile for different platforms on one and the same
source tree.

  > cd native
  > mkdir $CPU
  > cp makefile.CPU $CPU/makefile


4. Adapt the configuration files

You'll have to make some changes to the config files under the native
directory:


4.1 config.defs

General, platform-independent settings. Uses gcc for compilation and
linkage of shared libraries. Anything defined here can be overridden
in file config.$CPU.


4.2 cfg/config.$CPU

Contains the platform-specific settings. You will have to set:

  JAVAINC ... include path for native java packages
    Both the path to general Java includes (e.g. native.h) and
    machine dependent files (e.g. typedefs_md.h)

  CCDEFS ... extra compiler flags/defines
    (GE3D_PROTOTYPES define is now hardcoded into ge3d/ge3d.h)

  LDSOLIBS ... extra linker libraries (if necessary)

If necessary, override the settings of config.def (see config.SGI_cc
and config.ALPHA_cc as examples for use of cc instead of gcc):

  CC_PIC ... compiler call (producing objects suitable for .so files)
  LDSO ... linker call for building shared libs (.so file)
  XLIBDIR ... location of the X11 libs
  XLIBS ... X11 libraries

To build the VRwave netscape plug-in check the name of

  NSJAVAHSYS ... subdirectory of SDK/bin with netscape's javah

At the end of config.$CPU include either config.OpenGL or
config.Mesa


4.3 config.OpenGL/config.Mesa

Especially for Mesa, you'll have to set your local paths:

  OGLINC ... path to graphics include files

  OGLLIB ... graphic libraries

If they vary on your platforms, set them at the end of config.$CPU
(*after* the include line), like the example in config.LINUX_ELF.

Note that we preferred to have the Mesa include files in a path
containing mesa/GL (this ensures all Mesa code to be compiled with its
own header files). Thus you'll have to remove the mesa/ part in the
include statements in gejcon.c and ge3d_mesa.c if you use a location
like /usr/local/include/GL/gl*.h.


4.4 rules.def

This file contains the actual rules and should need no changes. You
may need it to trace problems and set variables accordingly.


5. cd native ; make

When all files are properly set up, compilation itself takes only
about a minute. You get a libgejc.so link in native/$CPU that points
to either libgejcon-ogl.so or libgejcon-mesa.so.

If javah reports errors about classes it cannot find, check your
CLASSPATH environment variable as a possible reason. It should be
either unset or contain "." (makefiles make no assumptions on the kind
of shell used).



Running VRwave
--------------


Two things to watch for: CLASSPATH must include the classes
subdirectory and LD_LIBRARY_PATH must include the directory location
of the .so file you created in the above directory.

You may set these variables manually or cd into the test subdir and
call "run", which sets these directories relative to the current dir
($CPU must be set in this case).

The "main" java class executed is iicm.vrml.vrwave.VRwave

test/examples and test/testfiles contain some sample and test files.

Other scripts in the test subdir run specific functionality tests,
e.g. readtest calls the parser, travtest emulates a pw application,
ge3dtest shows the native window context. Some of them may require you
to set LD_LIBRARY_PATH yourself (don't panic ...).


VRwave can also be run under the Java VM of Java-enabled web browsers
(e.g. Netscape). VRwave's Java classes and shared libraries must be
available on the local file system (set your CLASSPATH and
LD_LIBRARY_PATH appropriately).

This feature is experimental. Try out the testns script for a demo.



Compiling the netscape plug-in (beta version)
------------------------------


0. caveats

There are some unlocated problems with netscape's Java VM running
VRwave native code (in detail, the HPUX and Linux versions did not
work in our environments). These problems should go away when we port
the native code of VRwave from JDK 1.0.2 style to JRI.


1. SYS environment

Set the SYS environment variable to `uname -s`.

[sh, ksh, bash]  SYS=`uname -s` ; export SYS
[csh, tcsh]      setenv SYS `uname -s`

Create a $SYS subdirectory under native/pisrc (will hold all system
dependent files) and under native/pilib (destination of npvrwave.so).


2. cd native/pisrc ; make

Normally, you need to make no changes to the makefile. It will use the
same C compiler etc. as defined for native code compilation (see 4.2
above).

If all went well, you got VRwavePlugin.class and VRwaveReader.class in
native/pisrc and npvrwave.so in native/pilib/$SYS.


3. testing Java-EAI and the plug-in

cd into directory test/eaitest and start the script "runns" to run
Java-EAI tests with the VRwave netscape plugin, or "runav" to test the
VRwave Java-EAI via appletviewer.

See the online help files (distributed with the binary release) for
installation of the VRwave netscape plug-in.



enjoy,

Michael Pichler              Sep 30, 1997.