From 7a76be4465ffb8e30012553c58fd15fb5845b84d Mon Sep 17 00:00:00 2001 From: Robert Osfield Date: Wed, 24 Apr 2002 14:14:37 +0000 Subject: [PATCH] Updates to the documentation. --- README | 7 +- doc/contents.html | 23 ++- doc/data.html | 26 ++- doc/demos.html | 21 +- doc/dependencies.html | 15 ++ doc/documentation.html | 26 ++- doc/index.html | 99 ++++++---- doc/install.html | 65 +++--- doc/introduction.html | 31 ++- doc/sgv.html | 35 +++- doc/stereo.html | 29 ++- index.html | 435 ++++++----------------------------------- 12 files changed, 323 insertions(+), 489 deletions(-) diff --git a/README b/README index 3e1f16851..11840cf48 100644 --- a/README +++ b/README @@ -1,8 +1,9 @@ Welcome to the OpenSceneGraph (OSG). -Documention is located in doc/, this includes documention on compiling -and installing, the OpenSceneGraph. +For information on the project, this distribtion, how to compile and +run libraries and demos, and for documention see open up index.html +in your perfered html browser. Robert Osfield. robert@openscenegraph.com -May 2001. +April 2002. diff --git a/doc/contents.html b/doc/contents.html index 5f3a05097..0afba7fc6 100644 --- a/doc/contents.html +++ b/doc/contents.html @@ -7,13 +7,24 @@ -
Installation    Contents -of Distribution    Documentation   Plugin -Dependencies   Data Sources   -Contacts -

-Contents of distribution

+ + + + + + + + + + + + + +
Index Introduction Contents Install Dependencies Demos Data Viewer Stereo Reference Guides
+ + +

Contents of distribution

./        Root directory.
README     text bare bones readme file. diff --git a/doc/data.html b/doc/data.html index 75a4ed6f6..bee4ac207 100644 --- a/doc/data.html +++ b/doc/data.html @@ -7,8 +7,24 @@ -

-Data Sources

+ + + + + + + + + + + + + + +
Index Introduction Contents Install Dependencies Demos Data Viewer Stereo Reference Guides
+ + +

Data Sources

-

-Compiling under Windows with Visual Studio.

+

+Compiling under Windows with Visual Studio.

The Microsoft Visual C++ 6.0 workspace file is VisualStudio.dsw located in the VisualStudio below the OSG this root directory. The OSG will compile with the basic VisualC++6.0, but, and this is a big but, the STL version which @@ -126,14 +140,14 @@ to help the location of datafiles. For example :

To help compilation of the image reader plugins, various image libraries have been zipped up for your convienice, your find these on the OSG release download directory. -

-Using Visual Studio .NET

+

+Using Visual Studio .NET

Looks like Microsoft have eventually got their act together on the compiler front, the compiler looks Standard C++ compilient with a solid STL implement, so this is the recommend route.

-

-Using Dinkumware STL

+

+Using Dinkumware STL

The basic jist is that you'll need to download their STL implementation, and follow their instructions of how toforce VisualStudio to pick up the new STL implementation. More details @@ -148,8 +162,7 @@ The #ifdef is smart enough to do this automatically when using VIsualStudio .NET modification by hand won't be required. Unfortunately there doesn't seem to be a special define associated with the Dinkumware STL for the #ifdef to pick up on.

-

-Using STLport

+

Using STLport

The OSG has been tested under Windows with STLport-4.5, which allows the users to configure the type of STL support required for STLport itself. @@ -172,7 +185,7 @@ list, thus overriding MS's own STL implementations.
-

Compiling under Linux

+

Compiling under Linux

Compile, from the OSG root directory, ('%' is UNIX csh prompt) type:
% make
Note, make should automatically detect linux and build optimized targets @@ -189,8 +202,8 @@ distribtions are upto date even recent ones. If you have problems compiling osgText due to GLU problems then check out the details at the bottom of this file, under the title RedHat7.1 & GLU1.3 for a quick way of installing GLU1.3 in the right place. -

-RedHat 7.2 & GLU1.3

+

+RedHat 7.2 & GLU1.3

I have posted a simple fix for those of us who have been unable to correctly build OSG 0.8.43 on Redhat 7.2. You can download it at http://www.openscenegraph.org/download/dependencies/ReadHat7.2_fixglu.tar.gz To install it, follow these steps: @@ -217,7 +230,7 @@ osgText.) Good luck everyone. - Clay
-

Compiling under FreeBSD

+

Compiling under FreeBSD

Compile, from the OSG root directory, ('%' is UNIX csh prompt) type:
% make
Note, make should automatically detect linux and build optimized targets @@ -233,7 +246,7 @@ To get full details of make options, type:
-

Compiling under IRIX

+

Compiling under IRIX

Since the OSG uses Standard C++ features such as STL it is important to have an up to date version of the MIPSPro compilers, ie. 7.3 or later. Support for MIPSPro7.2.1 has now been dropped since it was becoming to @@ -253,7 +266,7 @@ To get full details of make options, type:
-

Compiling under Solaris

+

Compiling under Solaris

Compile, from the OSG root directory, ('%' is UNIX csh prompt) type:
% make
Note, make should automatically detect linux and build optimized targets @@ -268,7 +281,7 @@ To get full details of make options, type:
-

Compiling under MacOS X (instructions written by Phil Atkin)

+

Compiling under MacOS X (instructions written by Phil Atkin)

For anyone who's ever used a Unix box for development it really is so simple it's insane.

You need to have installed the Developer tools from the CD that comes @@ -331,7 +344,7 @@ forewarned is forearmed.

-

Compiling under Cygwin

+

Compiling under Cygwin

To compile, from the OSG root directory, type: make Note, make should automatically detect your system and build optimized targets for your system. And if you wish to install the OSG type: make install Note that make symbolic @@ -347,22 +360,6 @@ Add the following to your .cshrc (note paths seperated by colon's): setenv OSGFILEPATH ./:${OSGDATA}:${OSGDATA}/Images Or the following if you're using a sh compatible shell : export OSGFILEPATH=./:${OSGDATA}:${OSGDATA}/Images: Or under windows (note paths seperated by semi-colon's) : SET OSGFILEPATH=./:${OSGDATA};${OSGDATA}/Images -
-
-
- -

-Running the demos

-To run the viewer demo type (you made need to type rehash first under Unix) -: -
%sgv cow.osg sgv lz.rgb or sgv Spinnercar.flt sgv Alley.3ds sgv town_ogl_pfi.pfb -or sgv -stereo cow.osg (see doc/stereo.html for further details) or sgv --stencil cow.osg (to turn on use of the stencil buffer and enable the overdraw -stats mode.) or sgv (with no arguments prints out usage to console.) Other -run other demos type osgcube or hangglide hangglide master.flt or osgreflect -cow.osg or osgconv Alley.3ds Alley.osg or osgtexture lz.rgb tree.rgb or -osgimpostor cow.osg or osgviews glider.osg (Note: the file is picked up -by checking the directories pointed to by $OSGFILEPATH) diff --git a/doc/introduction.html b/doc/introduction.html index e95ba711a..962b76f93 100644 --- a/doc/introduction.html +++ b/doc/introduction.html @@ -7,7 +7,22 @@ -

Introduction to the OpenSceneGraph

+ + + + + + + + + + + + + +
Index Introduction Contents Install Dependencies Demos Data Viewer Stereo Reference Guides
+ +

Introduction to the OpenSceneGraph

Welcome to OpenSceneGraph project!

@@ -18,13 +33,15 @@ what scene graphs are, why graphics developers use them, and details about the O project, how to learn how to use it and contribute to the OpenSceneGraph community.

+

Robert Osfield, Project Lead. April 2002. +

-

What is a Scene Graph?

+

What is a Scene Graph?

Its a tree! Quite simply one the best and most reusable data structures invented.Typically drawn schematically as root at the top, leaves at the bottom. It all starts with a topmost root node which encompasses your whole virtual world, be it 2D or 3D. The world is then broken down @@ -45,7 +62,7 @@ programs.

-

Why use a Scene Graph - Performance, Productivity, Portability and Scalability.

+

Why use a Scene Graph - Performance, Productivity, Portability and Scalability.

  1. @@ -98,7 +115,7 @@ framework of the scene graph handles the differnt underlying hardware configurat
    -

    So what about the OpenSceneGraph project?

    +

    So what about the OpenSceneGraph project?

    The OpenSceneGraph is an Open Source Scene Graph, and our goal is make the benifits @@ -199,7 +216,7 @@ already adopted their projects, and are from all over the world.

    -

    Getting started

    +

    Getting started

    The first thing is to select the distribution which suits you, there are binary, development and @@ -235,7 +252,7 @@ libraries that parts of the OpenSceneGraph is dependant upon such as glut, check

    -

    How to learn to use the OpenSceneGraph

    +

    How to learn to use the OpenSceneGraph

    The OpenSceneGraph distribution comes with a reference guide for each of the componet libraries - osg, osgDB, @@ -265,7 +282,7 @@ and OpenGL reference guide 'Blue Book'. The main openscenegraph-news mailing list, diff --git a/doc/sgv.html b/doc/sgv.html index 641fd193f..c548c4f67 100644 --- a/doc/sgv.html +++ b/doc/sgv.html @@ -2,15 +2,29 @@ - + + OSG Documentation - + -

     
    + -
    -

    -Scene Graph Viewer (sgv) keyboard bindings:

    + + + + + + + + + + + + + +
    Index Introduction Contents Install Dependencies Demos Data Viewer Stereo Reference Guides
    + +

    osgGLUT::Viewer / Scene Graph Viewer (sgv) keyboard bindings:


    @@ -220,12 +234,19 @@ x and mouse y position and delete the nearest interesected geoset. + + + + +
    -
    'o'
    +
    'o'
    		 Output the loaded scene to 'saved_model.osg'.
    +
    'O'
    +    		Snap a screen shot image and write it out 'screenshot.bmp'.
    '?'/'h'
    diff --git a/doc/stereo.html b/doc/stereo.html index 53bd9c6ea..cfd0bdd1d 100644 --- a/doc/stereo.html +++ b/doc/stereo.html @@ -1,15 +1,30 @@ - + - stereo - - + + + OSG Documentation - + - + -

    Native Support for Stereo

    + + + + + + + + + + + + + +
    Index Introduction Contents Install Dependencies Demos Data Viewer Stereo Reference Guides
    + +

    Native Support for Stereo

    The OSG has support for anaglyphic stereo (i.e. red/green or red/cyan glasses), quad buffered stereo (i.e. active stereo using shutter glasses, diff --git a/index.html b/index.html index 1415f420b..cb29dd8a0 100644 --- a/index.html +++ b/index.html @@ -1,396 +1,79 @@ - + - - OSG Distribution + + OSG Documentation - - -
    Installation    Contents -of Distribution    Documentation   Plugin -Dependencies   Data Sources   -Contacts -

    The Open Scene Graph (OSG) is an Open Source (LGPL), Standard C++, OpenGL -based scene graph for cross platform 3D real-time visualisation.  -The OSG is simply a scene graph and by design does not attempt to encompass -application frame works and user interface, the design is kept focused -on the issues of representing a 3D scene and rendering it in real-time. -The OSG currently supports Linux, IRIX, Windows and FreeBSD platforms with -the potential of support for further platforms. A Mac port is already underway. -

    The OSG is composed of a core scene graph library (osg) which is the -basis for all osg apps, an optional scene graph utility library (osgUtil) -which can be used for higher level functionality such cullers and renderers -and a database utility library (osgDB) coupled with a set of plug-ins -(osgPlugins) which are dynamically loaded by the osgDB library to support -the reading and writing of file formats or node toolkits. Support for -rendering of true type fonts is supplied by the osgText library, this -is optional, you only need to compile it if you require font rendering. + -

    There are also support libraries such as osgGLUT for bringing up a basic -UI, however this is not the focus of the OSG. For more sophisticated -user interfaces it is recommended to integrate the OSG graphics with a -fully fledge UI toolkit, this has already been done by users for most of the -leading UI toolkits, see the bazaar section on the -http://www.openscenegraph.org/download -for examples of SDL,QT,FLTK,MFX and WX viewers. + + + + + + + + + + + + + + +
    Index Introduction Contents Install Dependencies Demos Data Viewer Stereo Reference Guides
    -

    For the purpose of demonstating the functionality of the osg, ten demo -apps are provided, sgv (a scene graph viewer), osgconv (a command line -utility for converted multiple input files into a native .osg target file), -hangglide (a flight simulation demo over small hang gliding site), osgcube -(a very simple demo of an animated cube) and osgreflect (a demo of how planar -reflections can be achieved), osgtexture (a demo of some of the various -texture modes that the OSG supports), osgimpostor (a demo of impostors in -action) and osgviews (a demo of using mulitple viewports on the same or -multiple scenes). Finally there is the osgtext demo which illustrates -the different types of font rendering support by the osgText library. +

    +Index

    -

    This release is a ALPHA version, and is under continuous development -with the API and features subject to change. Although this disclaimer sounds -severe you'll probably find the OSG pretty competitive feature and maturity -wise, even with well established commericial scene graphs. If you plan to use the OSG -then please join the mailing list and provide us with feedback on how -you're getting on or the problems that you come across. This helps keep -the OSG development going in the right direction and ensures the problems -are fixed as early on in the development as possible.

    + + + + + -

    For instructions of how to compile, install the osg libraries and to -run the demos please read the INSTALL file. +

    + + + + + + + -

    Robert Osfield. -

    robert@openscenegraph.com. -
    Feburaru 2002. -

    -

    -

    Contacts -

    The OSG's web site is http://www.openscenegraph.org/ -

    The OSG's mailing list and mirror of downloads can be accessed at -
    source forge -  http://sourceforge.net/projects/openscenegraph -

    Bugs, patches, queries can be sent to the robert@openscenegraph.com -or to the mailing list. -

    Patches are best sent as complete files, as tarball if numerous file -changes have been made. -

    -

    -

    -Contents of distribution

    -./        Root directory. -
    README     text -bare bones readme file. -
    INSTALL    text file -containing guide of how to get the OSG compiling, and running the demos. -
    COPYING    text  -file containing the details of the OSG's Open Source LGPL license. -
    AUTHORS    text file -containing names of contributors to the osg. -
    NEWS       text -file listing coarse grained changes between releases. -
    ChangeLog  text file listing -fine grained changes between releases. -
    TODO       text -file listing  left to implement/extend/rewrite. -
    FAQ         -text file listing Frequently asked questions. -
    Makefile   Unix makefile. -
    index.html This file!
    + + + + -


    doc/   Documentation directory -

    index.html       -Documentation index -
    osg/             -Scene graph reference guide. -
    osgUtil/         -Scene graph utilities reference guide. -
    osgDB/           -Scene graph database utilities reference guide. -
    osgText/         -Scene graph text reference guide. -
    osgGLUT/         -Simple GLUT based viewer base classes reference guide.
    + + + + + + + + -

    include/     External includes -(i.e. files which would be installed in /usr/include) -

    include/osg/       -The OSG library header files. -
    include/osgUtil/  The OSG -Util library header files. -
    include/osgDB/    The -OSG Database library header files. -
    include/osgText/  The -OSG text library header files. -
    include/osgGLUT/  The OSG -GLUT utiltiy library header files.
    + + + + + + + + -

    src/    source files (including internal -includes) -

    src/osg       -The OSG library source files. -
                  -Contains all core osg classes, including reader/writer support for -
                  -the .osg ascii format, and sgi's rgb image format. -

    src/osgUtil  The OSG utility -library source files. -
                  -Contains useful utility classes such as for setting -
                  -up and rendering/draw. -

    src/osgDB    The OSG -database utility library source files. -
                  -Contains useful utility classes such as for reading -
                  -and writing 3D databases and image files. -

    src/osgText  The OSG -text library source files. -
                  -Contains true type font rendering classes. -

    src/osgGLUT  The OSG GLUT library -source files. -
                  -Contains basic GLUT viewer base classes used by -
                  -demo programs to bring up window and provide keyboard -
                  -and mouse interaction. -

    src/osgPlugins/     -Import/Export/Node kit plug-ins to the OSG. -
               osg/     -.osg native ASCII reader/write plugin. -
               flt/     -.flt Open Flight reader plugin. -
               lib3ds/  -.3ds Auto Studio Maxx reader plugin. -
               lwo/     -.lwo Light Wave binary (.lwo,.lw & .geo) reader plugin. -
               obj/     -.obj Alias Wavefront reader plugin. -
               pfb/     -.pfb (and others) Performer reader and writer plugin. -
               dw/      -.dw Design Workshop reader plugin. -
               rgb/     -.rgb RGB image file format reader plugin. -
               png/     -.png PNG image file format reader plugin. -
               gif/     -.gif GIF image file format reader plugin. -
               jpeg/    -.jpg JPEG image file format reader plugin. -
               pic/     -.pic PIC image file format reader plugin. -
               tga/     -.tga TGA image file format reader plugin. -
               tiff/    -.tif TIFF image file format reader plugin. -

    src/Demos/ sgv/           -A basic scene graph viewer for the OSG which is loads .osg files and -above formats. -
               osgconv/       -A program which reads input files into a single scene graph and outputs -the results. -
               hangglide/     -A program which of creates a flying site and allows users to fly over -the scene. -
               osgtexture/    -A simple program which demonstrates how to use various textures modes. -
               osgcube/       -A basic animation of an oscillating cube. -
               osgreflect/    -A demonstration of multi-pass stencil buffer based planar reflections. -
               osgimpostor/   -A basic demo to show how to use the osg::Impostor node. -
               osgviews/      -A demo of multiple views of the same or multiple scenes. -
               wxsgv/         -A demo of wxWindows viewer integrated with the OSG. -
               wxsgv/         -A demo of true type fonts support provided by osgText. -

    + + + + -


    lib/             -The local repository for the OSG library and plugins (files to be -installed in /usr/lib/ or /usr/local/lib) -

    lib/osgPlugins/  The local -repository for the OSG plugins (files to be installed in /usr/lib/osgPlugins -or /usr/local/lib/osgPlugins) -

    bin/             -The local repository for the OSG binary files (files to be installed -in /usr/bin or /usr/local/bin) -

    Make/            -Unix platform specific make rules and dependencies. -

    VisualStudio/    MS -VisualC++ 6.0 Make/Workspace files for Windows. -

    Metrowerks/      -CodeWarroir's Make/Workspace files for Mac. -

    dist/            -Distribution make files for RedHat Linux and IRIX. -
    . -
    -

    -

    -Scene graph dependencies

    -Currently the only dependancy of the core scene graph libraries (osg,osgUtil -and osgDB) is Standard C++ and OpenGL. The osgText library, osgGLUT -have the following dependancies, these arn't core libraries so arn't needed -to be compiled unless you need that feature. The demos do however require -osgGLUT so its likely that you will typically need it when trying out the osg. -The osgtext demo adds an osgText dependancies as well, you only need to compile -them if you need to a demo of those features. - - - -
    -
    -
    -

    -Plug-in dependencies

    -Follows is the list of depedencies which some of the osgPlugins require, -note the core osg and viewer do not need the following dependencies, you -only need the following if you require each specific plugin.  Note, -the flt, 3ds, pic, tga, do not have any dependencies other than Standard -C++ so will compile straight of the bag.  Under Linux the majority -of the depedancies below come as standard -
    with distributions so you may not need to download them at all.  -Its best to try out a straight compile of the osg, if you get missing includes/libs -errors then chase up the below. -
      -
    • -src/osgPlugins/pfb
      • - -
      There is a Performer plugin in this distribution for converting from -Performer to OSG and from OSG to Performer.  This plugin requires -Performer to be installed and therefore is not compiled by default. If -you have Performer (available under Linux and IRIX) then edit src/osgPlugins/Make -to compile under the plugin.  Performer can be downloaded from : - - -
    • -src/osgPlugins/png
      • - -
      The png plugin depends upon the libpng and zlib (for compression) libraries, -if you don't already have it installed, you'll need to download, compile -and install it. Project home pages are: - - -
    • -src/osgPlugins/gif
      • - -
      The gif plugin depends upon the libungif library, if you don't already -have it installed, you'll need to download, compile and install it. Project -home page is: - -Ftp download at : - - -
    • -src/osgPlugins/jpeg
      • - -
      The jpeg plugin depends upon the libjpeg library, if you don't already -have it installed, you'll need to download, compile and install it. Project -home page is: - - -
    • -src/osgPlugins/tiff
      • - -
      The tiff plugin depends upon the libtiff library, if you don't already -have it installed, you'll need to download, compile and install it. Project -home page is: - - -
    • -src/osgPlugins/zip
      • - -
      The zip compressed archive plugin depends upon the unzip executable -being available on your system.  If it is not then you'll be able -to find binaries at: - - -
    • -src/osgPlugins/tgz
      • - -
      The tgz compressed archive plugin depends upon the unzip executable -being available on your system.  If it is not then you'll be able -to find binaries at: - - -
    • -src/osgPlugins/osgtgz
      • - -
      Has the same dependencies as the tgz plugin above.
    - -


    -

    -

    -Data Sources

    - - +
    Introduction Introduction to Scene Graph in general, the OpenSceneGraph project itself and how to use it.
    Contents A list of the directories in the distribution.
    Install A guide of how to compile and install on all the supported platforms.
    Dependencies Listing of all the dependancies of the project, with links of where to download them.
    Demos Thumbnails and info on all the demo applications which come with this distribution.
    Data List of websites where one can download interesting and useful data from.
    Viewer List of key bindings support by the osgGLUT::Viewer and hence sgv and the rest of demos.
    Stereo Documentation on the commandline paramters and environmential variables which control stereo.
    Reference Guides Reference guides of the core libraries.