README -- 08-Sep-95 -- WebSpace Navigator 1.0 for Win32

Copyright (C) 1995, Template Graphics Software Inc.
All Rights Reserved.


    *---------------------------------------------*
    *                                             *
    *  This is Release 1.0 for Windows NT.        *
    *                                             *
    *  This is Release 1.0 BETA2 for Windows 95.  *
    *                                             *
    *---------------------------------------------*


Software Requirements:

    To run WebSpace Navigator 1.0 for Win32 under:

    Windows NT  you must have
    ----------

        + Windows NT 3.5 or 3.51

        + WebSpace Navigator 1.0 for Win32
          (see WEBSPC10.EXE on our ftp site).


    Windows 95  you must have
    ----------

        + Windows 95

	  WebSpace also requires Microsoft OpenGL, which is provided in
	  the installation as a pre-release version.  Contact Microsoft
	  for availability of the release version.  Also see note below
          about known problems with the OpenGL DLLs.

        + WebSpace Navigator 1.0 for Win32
          (see WEBSPC10.EXE on our ftp site).


    NOTE: There are *two* directories on our ftp site (WinNT and Win95),
          but there is only *one* version of WebSpace for Win32!
          It runs on both Windows NT and Windows 95.


Hardware Requirements:

    To run WebSpace for Win32 you should have at least:

        + A 486/66 processor

        + 8 MB memory

        + 256 color graphics card

    You will soon want to have:

        + A Pentium processor

        + 16 MB memory (more if you're running NT)

        + Fast, high resolution, 24bit TrueColor graphics card

    You will be able to take advantage of:

        + All display resolution/color combinations supported by Windows

        + Multi-processor machines

        + OpenGL accelerator cards (Accel, Oki, various GLint-based, etc.)


Size Requirements and Information:

    For Self Extracting Archive:

        The self extracting archive (WEBSPC10.EXE) is approximately 4.5 MB.
            (If necessary you can delete this file after extracting the
            installation files.)

        The installation directories (disk1, disk2, ...) are also 4.5 MB.

        The complete installation is approximately 8.5 MB.

        You will need *at least* enough room to contain the installation
        files, and the final installation.  We recommend around 15 MB free
        disk space before extracting the installation files.

        Note: You can delete the self extracting archive file and the
        installation directories (disk1, disk2, ...) when done.  See the
        installation section below for more information.

    For Diskette Installation:

        WebSpace comes on 4 diskettes.  Same disk space requirements.

    Total Size:

        After the installation is finished, WebSpace and associated files
        will take up about 8.5 MB.

        Note1: About 2.6 MB of the installation is sample VRML and Open
               Inventor files which you may delete if you need the space.

        Note2: About 2.4 MB of the installation is standard Microsoft
               DLLs (eg. MFC30, MFCANS32, ...) which you may already have
               on your system.  Please check the size/date of "MSVCRT20.DLL"
               before you delete it!  WebSpace requires the VC++ 2.2 version
               of this file (which has the same name) and yours may be older.


Installation:

    Follow these steps to install:


    Floppy Disk Installation:

        1) Insert disk 1 in the diskette drive.
           Run setup.exe from that drive.

        2) Proceed to step 9 below.

    
    Self Extracting Archive installation:

        1) Download the self extracting program WEBSPC10.EXE to your system.


        2) Create a temporary directory on a disk with some room.
           For example:

               mkdir \wsinstl

           This directory will only be required for installation and can be
           removed, with its contents, after installation. 


        3) Change the active directory to the temporary directory.
           For example:

               cd wsinstl

        4) Run the program to extract the contents:

               webspc10

           At this point, you can delete the self extracting archive, if
           you need the disk space (be sure to make a backup).

        5) Change directory to the newly created "Disk1" directory and
           run setup:

	       cd Disk1
               setup

        6) Follow the instructions in the setup program.

           Note1: If you are running under Windows 95, you will need to
           install the OpenGL DLLs.  The setup program will inform you of
           the need to do this and handle it automatically.

           *************************************************************
           *
           * Note2: The default (top level) installation directory for
           * WebSpace is "Program Files", per the new Microsoft Windows 95
           * conventions.  However... setting this directory name for a
           * helper application may cause problems for some HTML browsers!
           *
           * This works correctly with Netscape Navigator 1.2 (which uses
           * "Program Files" by default itself).  For other browsers you
           * want to choose a different top level installation directory!
           *
           * Please see section "Installation Directory Name Issues"
           *
           *************************************************************
           
        7) Test WebSpace by opening the program group and clicking on the
           WebSpace icon.  Once WebSpace is running, pull down the "File"
           menu and select the "Open File..." item.  The resulting dialog
           box should display the files in the WebSpace VRML examples
           directory.  Click on a file name then click "OK" (or just
           double-click the file name).  Once the scene is visible, move
           the cursor onto the T-shaped 3D joystick (this is part of what
           WebSpace calls the "dashboard"), press the left mouse button
           and move the mouse to begin navigating through the scene.
           There may be a short delay before you start moving, while
           WebSpace builds geometry caches and optimizes the scene.

        8) You can now delete the temporary install directory and all its
           contents.  You can use the file manager to do this, or you can
           issue the following commands (using the example directory name):

               cd \
               rmdir /s \wsinstl

           BE CAREFUL with the 'rmdir /s' command.  Make sure you are only
           deleting what you want!

        9) IMPORTANT: You will need to logoff and log back in for certain
           environment variables to take effect.  The installation will not
           be complete until you do this.

           Actually WebSpace will work fine without this step *except*
           for the following limitations:

             + On all platforms -- WebSpace will not be able to find its
               font files until the environment variables are defined.
               Therefore the text may be missing from VRML files using
               the AsciiText node until you logoff and login.
               This limitation will be corrected in the next release.

             + On Windows 95 -- Netscape will not be able launch WebSpace
               until the environment variables are defined.  Specifically
               until the WebSpace "system" directory, where its DLLs live,
               has been added to the global PATH variable.  This is the
               Windows 95 convention, that required system DLLs live in
               the application's "system" directory, not as often done 
               previously, in the same directory as the executable.  The
               Windows 95 "AppPaths" feature allows this to work.  And it
               works fine for starting WebSpace from the "Start" menu, the
               command line, the Explorer and so on.  It does *not* work
               when WebSpace is launched by Netscape.  We don't know yet
               why this is a problem.


Recommended Browser:

    NetScape Navigator 1.2 from NetScape Communications.

    Configuring Netscape for WebSpace:

        1) Select the "Options/Preferences" menu item.

        2) Select the "Helper Applications" item in the pulldown.

        3) Click the "New Type" button.

        4) In the Configure New MIME Type dialog enter:

           For MIME Type   : x-world
           For MIME Subtype: x-vrml

        5) In the "Extensions" field enter: .wrl

        6) In the "Action" group box click "Launch Application"

        7) In text entry field enter: <WebSpaceInstallDir>\WebSpace

           or click the Browse button, click your way to the WebSpace
           installation directory and click on WebSpace.exe.  The
           default installation directory is:

               \Program Files\TGS\WebSpace\program

        8) Repeat Steps 1 through 7 for the following MIME types:

	   MIME Type       : application
	   MIME Subtype    : x-inventor
	   Extension       : .iv

	   MIME Type       : application
	   MIME Subtype    : x-gzip
	   Extension       : .gz     (see note 8 below)

    Other Browsers

      Any browser should be able to start WebSpace and pass it a single VRML
      scene (once WebSpace is configured as a helper application).  However
      WebSpace may not be able to fetch URLs associated with WWWAnchor
      nodes, WWWInline nodes, or texture files in the VRML scene.
      Also, if the browser does not support the DDE protocol then each time
      you select a VRML link in the browser, it will start a new copy of
      WebSpace.

      TGS is working with browser makers to enhance the communications
      capabilities between the browsers and WebSpace.  Browser vendors
      may want to check out our HTML/VRML browser interaction testbed.
      Go to the TGS Home Page (http://www.sd.tgs.com/~template), click
      the WebSpace link, then click the "IPCTestBed" link.


Help Files

    Help files are provided in the WebSpace installation directory.
    They are in HTML format and may be viewed with your Web browser.


Example Files

    Example VRML files and example Open Inventor files are provided with
    the WebSpace installation (see <installdir>\TGS\WebSpace\Data\VRML
    and <installdir>\TGS\WebSpace\Data\Models).

    They may be loaded through your Web browser or directly into WebSpace 
    using any of the following methods:

        - Start WebSpace from the command line using a filename argument.

          For example: WebSpace urlHouse.wrl

        - Use the "File / Open File..." menu in WebSpace.

        - Drag files from File Manager (or Explorer) into a WebSpace window.

        - Double click on files in File Manager (or Explorer).


Example Sites

    We have provided a path to the SDSC VRML Repository in the history list.
    If you wish to use this feature, copy the WebSpace.ini file from
    the WebSpace directory to your system directory (eg. <disk>:winnt35\)
    before running WebSpace.  Note that if you already had a VRML history
    list associated with WebSpace, it will be replaced by copying.


Tips

    1) Viewers

       WebSpace provides two different 3D viewers:

       Walk Viewer (the default): For 3D scenes
       Examiner Viewer          : For 3D objects

       VRML files should contain a "Viewer" hint that tells WebSpace which
       viewer to use by default.  But in some cases it may be necessary to
       change viewers manually using the "View" menu.  You can also set
       the default viewer (to be used the scene does not have a viewer
       hint) from the "Options" menu.

       You can tell which viewer is active by looking in the window banner
       or by looking at the dashboard.  The Walk viewer has a "T bar" type
       joystick for maneuvering and the Examiner viewer has a track ball.

    2) The Mouse

       In WebSpace, the mouse button (with no modifier keys) is used only
       to select "hot" objects (links) and to manipulate the dashboard.
       See the Help file (HTML format) for details on the dashboard controls,
       mouse buttons, modifier keys and keyboard shortcuts.

       Open Inventor users note!  This is different from the default mouse
       action in standard Open Inventor viewers.  Holding down the "Ctrl"
       key makes the mouse button work like what you're used to doing with
       the left mouse button.

    3) Hot Objects

       Hot objects are no longer highlighted - instead, the cursor changes
       to a "hot" cursor when it passes over a hot object.  We will be
       looking for further ways to enhance hot objects in the future.
       Note also that WebSpace now displays the object's Description field
       by default.  If there is no description field, then it displays the
       actual URL.

       These "hot objects" are just like the links in an HTML document.
       Click on the "hot object" while it is selected to go to that URL.

       Note however that hot objects are *not* highlighted while you are
       moving in the Walk viewer (have the mouse button down), rotating the
       object in the Examimer viewer (have the mouse button down) or while
       the object is spinning in the Examiner viewer (hint: click the blue
       trackball to stop spinning).

    4) Inline Objects

       Sometimes you will see "empty boxes" when a scene first comes up.
       Usually these are "inline objects" (WWWInline nodes).  Inlined objects
       are defined in separate VRML files which are referenced from the main
       VRML file.  They display as a bounding box until the viewer finishes
       fetching the contents of the file.  The effect of this is similar to
       the way some HTML viewers display the text of a page while they are
       still fetching the images.

       If an inline object is also a link (a "hot object"), its bounding box
       will highlight just like any other hot object and you can click on the
       bounding box to follow that link.

    5) ViewPoints

       WebSpace supports the VRML "Cameras" hint which allows a VRML author
       to predefine named camera positions, or viewpoints.  The WebSpace
       "ViewPoints" menu is dynamically created every time a VRML scene is
       loaded and allows you to select any of the predefined viewpoints.
       This is particularly helpful in a complex scene where "walking"
       around using the viewer controls is too slow.

       By default WebSpace will "jump" to the selected viewpoint.  This was
       selected as the default because it works better on slower machines.
       You can change this behavior by disabling the "View/Jump Cuts" menu
       item.  Then WebSpace will attempt to move "smoothly" to the selected
       viewpoint by interpolating the camera position along a spline.

    6) Inventor Files

       WebSpace also supports the full Open Inventor file format.  These
       files are identified by the extension ".iv" and may contain nodes
       that are not (or at least not yet) allowed in VRML files.  Inventor
       nodes include 2D text, 3D text and "engines" that define various
       types of predefined motion in the scene.  Some examples are included
       with the WebSpace distribution.

    7) Texture Maps

       This version of WebSpace supports texture maps (we have included
       a texture mapped VRML file, "gasbldg.wrl" for your perusal).  This
       feature is *very* cpu intensive.  We support "Degrade on Motion",
       which turns off texture mapping when you move.  However, be
       aware that after you move, you need to sit tight until the texture
       maps come back before you can move again.  This can take a while,
       depending on the number and complexity of the maps, the VRML file,
       your cpu speed and graphics acceleration (if any).

       Note also that in the Examiner viewer, you may think you have
       stopped movement, but it may be rotating imperceptibly and the
       texture maps won't be redrawn.  The status bar indicates when
       movement has stopped completely.  Click the mouse in the picture
       area but not on the trackball to stop movement.

       Texture map formats currently supported: GIF (.gif) and JPEG (.jpg).

    8) GZipped files

       This version of WebSpace supports gzipped files.  Unfortunately,
       the browsers do not handle secondary hand-off processing well.
       For this feature to work, you have to nominate WebSpace as the
       server for the "application/x-gzip" MIME type, with extensions
       of ".gz" (see MIME type and helper configuration notes above).
       WebSpace checks incoming files to see if they are gzipped, and
       launches a gzip process to handle decompression.  We provide a
       gzip executable.  Make sure this is in your path, or WebSpace
       will not be able to launch the process.

       Spurious Warning Dialog: GZipped VRML files, eg. foo.wrl.gz, are
       typically served with the standard VRML MIME Type but with the
       "Encoding Type" set to "x-gzip".  Current versions of Netscape
       (ie. 1.1 and 1.2) always pop up a "warning" dialog box when they
       see this encoding type.  It's really annoying, but it's harmless.
       Just click the OK button and everything will work -- Netscape
       passes the file along and WebSpace always checks for the magic
       GZip header bytes anyway.  We've reported this to Netscape, but
       apparently there's nothing we can do at this point.  The worst
       part is that you will get the "warning" dialog even for GZip'd
       inlines and texture files, so it can popup a lot...

    9) Utilities

       The following utilities are provided in the WebSpace directory:

	    VrmlLint.exe - verifies VRML files for correctness.

	    IvToVrml.exe - converts Open Inventor files to VRML files.

       These are command line utilities and take a varying number of
       arguments to modify their behavior.  Run each program with -h
       (help) to determine the valid arguments and effects.

       Note if you don't specify a filename, VrmlLint will read from
       standard input.  Enter control-z (CTL+Z) to exit.

   10) LOD (Level Of Detail)

       Note that "Degrade on Move" is selected by default (View menu).
       In this mode, WebSpace automatically forces the lowest level of
       detail while you are moving.  This means you will *not* see the
       level of detail changing while you are moving.  The correct
       level of detail will be displayed as soon as you stop moving.
       Or you can unselect this option in the View menu.

   11) Walking Speed

       WebSpace will use the VRML scene author's suggested walking
       speed if the scene contains a "ViewerSpeed" hint.  Otherwise
       WebSpace will choose a speed (move increment) based on the total
       size of the scene.  You can increase and decrease the walking
       speed using the "View" menu or the Ctrl-K and Ctrl-J keys.


Initial URL

    Some of the browsers we have tested so far have the problem that they do
    not pass the URL of the first link to the helper application (only the
    name of the temporary local file).  As a result WebSpace has no base
    URL to use to resolve relative URLs in the VRML scene.

    If you are using a browser that supports the Spyglass DDE protocol, e.g.
    Enhanced Mosaic 2.0, you can work around this problem by selecting the
    same link a second time in the browser.  This works because all links
    after the first one are passed to WebSpace using the DDE protocol.

    We have fixed this problem with NetScape.  Working on it for others.
    Encourage your browser vendor to pass URLs to helper applications!


Messages

    "WWW_RegisterViewer returned fail status."

        This normally means that no HTML browser is running or at least
        WebSpace does not recognize the browser as a candidate for the
        DDE protocol.  WebSpace will still work as a standalone viewer for
        local files.


VRML Hints

    WebSpace currently supports (what we believe are) all the commonly
    used hints in VRML files.  Specifically:

        BackgroundColor: Sets background color to an RGB value

        Viewer         : Selects Walk or Examiner viewer

        ViewerSpeed    : Sets default movement rate

        Title          : Sets title for window banner

        SceneInfo      : Text to be displayed by the "File/Document Info"
                         menu item.  Typically author name, copyright, etc.

    We recommend that all VRML files contain a standard set of hints to
    ensure the file ends being viewed the way the author intended and
    so the person viewing the file can see who created it and so on.
    A standard set of hints might look like:

        DEF InfoGroup Group {
            DEF BackgroundColor Info {
                string "0.0 0.0 0.0"
            }
            DEF Viewer Info {
                string "walk"    # or examiner
            }
            DEF Title Info {
                string "Your File's Title"
            }
            DEF SceneInfo Info {
                string "Authored by YourNameHere"
            }
            DEF ViewerSpeed Info {
                string "30"      # or some appropriate value
            }
        }


Compared to WebSpace on UNIX:

    1) WebSpace for Windows does not currently fetch URLs directly, but
       relies upon a Web browser that supports the Netscape/Mosaic DDE
       protocol.  Therefore WebSpace cannot be used as a standalone Web
       browser (although it can be used standalone to view local files).
       One advantage however is that inlined VRML files and texture map
       images are fetched "in the background", allowing you to navigate
       through the scene even while parts of it are still being fetched.
       This is similar to way HTML browsers (generally) can display the
       text while the images are still loading.

       Another advantage is that by fetching URLs through a general purpose
       Web browser, WebSpace provides the ability to handle many types of
       URLs linked through the VRML scene.  For example, if a link in a
       VRML scene is to an audio file URL, WebSpace will request the Web
       browser to fetch the file and the Web browser will route it to an
       appropriate helper application.  This means that you only have to
       configure your helper applications once -- in your HTML browser.

    2) The default setting for "Jump Cuts" is TRUE in WebSpace for Windows.

    3) Bookmarks are maintained by WebSpace, not by the HTML browser.

    4) The "Options" menu has an additional item "Show Anchor Desc" which
       allows you to toggle between displaying the description (default)
       and the actual URL for a WWWAnchor (a linked object in the scene).

    5) The "Options" menu has an additional item "Default Viewer" which
       allows you to specify the Viewer type, either Walk or Examiner,
       that WebSpace should use when the scene does not contain a viewer
       hint.

    6) When the "View/Degrade on Move" option is selected (which it is by
       default), WebSpace automatically forces flat shading to increase
       rendering speed.  This is in addition to automatically turning off
       textures and forcing the lowest level of detail for LOD nodes.

    7) The location of a few menu items in the View and Options menus is
       slightly different.


Installation Directory Name Issues

    1) The default top-level installation directory name "Program Files"
       may cause some minor inconvenience when using a command prompt
       window.  Remember that when you specify a directory name that
       contains space characters, you must enclose the name in quotes.

           For example: cd \"Program Files"

    2) A more subtle problem is that under Windows NT 3.5, the command
       prompt (CMD.EXE) does not handle directory names with space 
       characters correctly when you are in a subdirectory below it.
       For example, the following will *not* work:

           cd \"Program Files"\TGS\WebSpace\Program
           start WebSpace

       The start command will fail claiming that there is no such file
       named "WebSpace".  Of course there is, but it gets confused by
       the name "Program Files" when it builds the full pathname.

       --> There is no problem starting WebSpace from the Program Manager.
           Just open the "TGS WebSpace" program group and double click on
           the WebSpace icon.

       --> This is not a problem under Windows 95.

    3) Using this directory name in the path for a helper application may
       cause problems for some HTML browsers!

       For example, you may get an error "Helper application not found".

       --> There is no problem using Netscape Navigator 1.2 (which uses
           "Program Files" by default itself).

       With some browsers, for example Netscape Navigator 1.1, you can
       can work around the problem by setting the WebSpace path to:

           \Progra~1\TGS\WebSpace\Program\WebSpace.exe

           Note the use of the "short mangled name" instead of the
           full name "Program Files".  The short name for "Program Files"
           is not necessarily "Progra~1".  Use "dir" to see what it is.

       For other browsers you may have to choose a different top level
       installation directory or move the WebSpace files to a different
       directory.  (Remember to move the DLLs too if you do that.)

    4) NOTE: This particular directory name is the standard Microsoft
       convention for Windows 95 and probably will be in the future for
       Windows NT as well.  Already, for example, Netscape 1.2 uses this
       directory name for both Windows 95 and Windows NT.


Known Problems:

    1) Windows 95:
       Texture maps are initially rendered outside the drawing window.
       This appears to be a problem with the current version of the
       pre-release Microsoft OpenGL DLL's.  We are investigating.

    2) Windows 95:
       When the cursor moves onto a WWWAnchor (a link) it should change
       to a sort of lightning-bolt/arrow thingy (run it on Windows NT to
       see what I mean :-), but instead it changes to the "seek" cursor.
       At least it changes, that's the important thing.  We'll work on it.

    3) Windows 95;
       We've set up a "file association" so that double clicking on a
       VRML (.wrl) file should automatically invoke WebSpace to view it.
       This works fine on Windows NT, but currently crashs WebSpace on
       Windows 95.  We'll keep working on it, but it's not critical for
       using WebSpace with Netscape to view VRML files from the network.
       In any case, you can always start WebSpace and use the "File/Open
       File..." menu to view local files.

    4) Windows 95:
       Occasionally WebSpace will lose the color palette focus and not
       recover it (ie. realize its palette) automatically.  This works
       fine on Windows NT.  We're working on it.  In the meantime you
       can recover by clicking on another window then clicking on the
       WebSpace window.



-----------------------------------------------------------------------------

Registration for WebSpace v1.0 Support


    Template Graphics Software has partnered with Silicon Graphics Inc.
    in the development of WebSpace.  WebSpace v1.0 is available free
    for personal use from various ftp sites.  This is an unsupported
    version.  Comments may be mailed to:

        webspace@tgs.com

    but do not expect a reply to these messages.

    If you would like to purchase support for WebSpace for $49.00 per copy,
    please contact Template Graphics Software at 619.457.5359 x233, or mail
    a check or money order, payable to Template Graphics Software, Inc., to:

        WebSpace Support
        Template Graphics Software
        9920 Pacific Heights Blvd., Suite 200
        San Diego, CA 92121

    A secure transaction form will be added to the TGS home page located
    at http://www.sd.tgs.com/~template/WebSpace eventually.

    WebSpace Support is $49.00 per copy for all platforms.  Once you have
    registered, you will be entitled to the following:

        + 30 days 2-way email technical support
          (TGS Hotline will call you if needed)

        + Access to password-protected VRML pages
          (For verification and fun)


-----------------------------------------------------------------------------

Thanks for using WebSpace!
-- The TGS WebSpace Team

