From a2325b71e4b3197e797f2079e02be09060639998 Mon Sep 17 00:00:00 2001 From: Robert Osfield Date: Sat, 20 Apr 2002 15:49:28 +0000 Subject: [PATCH] Reorginising the docs so that data source, dependencies and installation istrucions sit in the doc directory as html files. --- doc/data.html | 52 ++++++++ doc/dependencies.html | 135 ++++++++++++++++++++ doc/install.html | 287 ++++++++++++++++++++++++++++++++++++++++++ doc/introduction.html | 23 ++-- 4 files changed, 487 insertions(+), 10 deletions(-) create mode 100644 doc/data.html create mode 100644 doc/dependencies.html create mode 100644 doc/install.html diff --git a/doc/data.html b/doc/data.html new file mode 100644 index 000000000..24cc3a977 --- /dev/null +++ b/doc/data.html @@ -0,0 +1,52 @@ + + + + + + OSG Distribution + + + +

+Data Sources

+ + + + + diff --git a/doc/dependencies.html b/doc/dependencies.html new file mode 100644 index 000000000..8d5041ced --- /dev/null +++ b/doc/dependencies.html @@ -0,0 +1,135 @@ + + + + + + OSG Distribution + + + + +

+Windows dependency archive

+

As windows doesn't natively come with a rich set of developments libraries like Unix, one is likely to need to +download most of the dependancies below. However, to make life easier for Windows users, we have put together +a .zip archive with all the required dependancies which can be download and installed somewhere in you system, +you'll need to set VisualStudio to pick up on the include and libs, and the PATH set to pick up in the dll's. +Alternatively, a more hacky but simpler solution is to unpack this archive inside you OpenSceneGraph distribution, +so that all the include files drop into OpenSceneGraph/include, and the libs drop into OpenSceneGraph/lib, and +all the dll's drop into OpenSceneGraph/bin, this way VisualStudio will pick up the files simpler through the +paths set up inside the workspace and project files. The archive can be downloaded here: . . +

+ +
+ +

+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. +

+ + + + + + diff --git a/doc/install.html b/doc/install.html new file mode 100644 index 000000000..e582857af --- /dev/null +++ b/doc/install.html @@ -0,0 +1,287 @@ + + + + + + + +The following is a very basic intro of how to get the OSG going under Linux, +FreeBSD, IRIX, Windows and Mac.  Each intro mentions OpenSceneGraph-Data, +it is recommended that you also download it alongside this source distribution. +

The scene graph depends upon Standard C++, STL and OpenGL so you need +a C++ compiler up to the task and OpenGL or Mesa installed. The viewer +depends upon GLUT which you'll need to download and install from the GLUT +website. The OSG has it own native ascii file format, and .rgb image reader +inbuilt which allows you read the example data with any dependencies other +than C++, STL and OpenGL. +

The new osgText library adds the dependency of the freetype library +for support of true type fonts, however it is not essential to the core +library, so you can comment it out from compilation by modifying the src/Makefile, +and src/Demos/Makefile. I you wish to use fonts then you can download freetype +from www.freetype.org. The osgText library also requires an up to date +GLU implementation which supports GLU1.2 tessellation routines. If you +your current GLU is out of date you'll need to download the latest, for +instance the sgi's sample implementation for GLU from the www.opengl.org +website. +

The OSG also has a set of plug-ins which support non-native 3d database +and image formats, several have no dependencies on external libraries (flt,3ds,obj, +lwo,dw, tga & pic), while others (pfb,jpeg,gif,tiff) require other +libraries to be installed to compile them. If you don't already have them +installed then don't worry, you'll still be able to use the OSG, just comment +out the plugins you can't compile from the src/osgPlugins/Makefile. The +core osg library and viewer has been designed to load the plug-ins at run-time +only and if they are required to load a specific data set. If you don't +need them for your datasets then it won't matter that you haven't been +able to compile all the plug-ins. A full list of dependencies and where +to download the required libraries are listed in the index.html. +

If you're coming across the OSG for the first time and want to get started +quickly, go right ahead and follow the compilation instructions. You can +always later download the libraries which the plug-ins require if you eventually +need them. If you haven't already checked it out, for a list of distribution +contents, contacts and links to documentation check out index.html. +

+Compiling under all UNIX (including CYGWIN) Platforms

+Building the OSG requires 'gmake', due to the extensive use of gmake directives +in the Makefiles. You can get gmake from here if you don't already have +it installed: http://www.gnu.org/software/make/ +

+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 +for your system. And if you wish to install the OSG type: +
% make install
+or +
% make instlinks
+To get full details of make options, type: +
% make help
+(highly recommended) +

The osgText library now depends upon GLU1.3 functionality, and only +the recent Mesa version have this as stanadard. Unfortnately not all Linux +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. +

+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 +for your system. And if you wish to install the OSG type: +
% make install
+or +
% make instlinks
+To get full details of make options, type: +
% make help
+(highly recommended) +

+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 +unwildy to support and is very rarely used in the OSG commiunity. It is +recommended to use MIPSPro7.3.1.1m. +

Compile, from the OSG root directory, ('%' is UNIX csh prompt) type: +

% make
+Note, make should automatically detect linux and build optimized targets +for your system. And if you wish to install the OSG type: +
% make install
+or +
% make instlinks
+To get full details of make options, type: +
% make help
+(highly recommended) +
  +
  +

+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 +for your system. And if you wish to install the OSG type: +
% make install
+or +
% make instlinks
+To get full details of make options, type: +
% make help
+(highly recommended) +
  +
  +

+Compiling under Windows

+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 its recommended that you use Service Pack +4 to fix MS compiler bugs which affect the OSG. Even Service Pack 4 does +not completely fix MSVC bugs associated with STL, so it is recommended +that you also use STLPort which can be downloaded from http://www.stlport.org +since they actually know how to write a STL library and have done a rather +good job at it. Notes on using STLport at the bottom of this file. +

The OSG is composed of a number of libraries and executables, to get +running you'll need at least to compile osg,osgUtil,osgDB,osgGLUT, dot_osg +and sgv. The rest of the libraries and executables are optional and can +be compiled if you need them, however for simplicity I would recommend +doing a batch build of all the libraries and executables in the distribution, +some of the plug-ins which support non native file formats may not compile +due to dependencies on other libraries (such as libpng), you can ignore +these compilation errors unless you need to load the related file types. +

To execute the viewer the file path for the .dll's and .exe, both compiled +into the OSG's bin directory, need to be setup, such as by adding the PATH +to your autoexec.bat, its also useful to add the OSGFILEPATH to your autoexec.bat +to help the location of datafiles. For example : +

SET OSGFILEPATH=D:\OpenSceneGraph-Data;D:\OpenSceneGraph-Data\Images +
SET PATH=C:\WINDOWS;C:\WINDOWS\COMMAND;D:\osg-0.8.43\bin; +

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. +

+Compiling under MacOS 9

+The Microwerks Codewarrior workspace files can be found under the Microwerks +directory. Further details to be fleshed out since Mac port is in its early +stages and is not uptodate with the current release. To get it compiling +you will have to use these Codewarrior files as a starting place. If you +get it running and have time to maintian the port please email robert@openscenegraph.org. +

+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 +for free with OS X. This gives you compilers, headers, frameworks - stuff +like GLUT and Carbon for developers. +

Everything is done command-line, so you need to get to the underlying +OS rather than the Aqua gloss. The Mac comes with an app in Applications/Utilities +called Terminal - open up any Finder window (e.g double-click on your hard +disk icon), click on the Applications icon at the top right of the window, +then click on the Utilities folder to get access to all the grubby apps +which give away the real OS roots underneath the shiny paintwork. Anyone +developing will need Terminal so much they should put it in their Dock. +You do that by grabbing the icon of the app in the Utilities folder and +dragging it to the bottom of your screen, at which point the other app +icons in the Dock slide away to leave a gap which when you release the +mouse button leaves Terminal permanently available, just a mouse click +away on your desktop. When you start Terminal it brings you up a csh running +under Darwin (which is the BSD-with-knobs-on that underlies OS X), and +does a cd to ~ (otherwise /Users/username of whoever you are logged in +as, as far as the Finder in OS X is concerned you are in the Users/username +folder of the harddisk the machine booted from). +

Then you are in Unix land, and it's all very familiar. +

You will need a .cshrc file with $OSGHOME (as above), and this is a +filename that the Mac won't let you see from the Finder or in fact generate +from an app, so I used vi to create that. Then I just went +

cd $OSGHOME +

% make clean +
% make macosx
+ +


And it sounds too good to be true but it is that simple. It's worth +doing some editing on the Makefiles in the Plugins and Demos directories +so that it only tries to build a subset, otherwise the developer will have +to dig out the support projects like jpeg etc. I have only built up to +now sgv, hangglide, osgcube, osgreflect, osgviews and in the Plugins have +built osg rgb 3ds and a couple others - will check and get back to you. +

Tricky bit : +

Installing the libdl.a is more trouble, as you have to enable the root +account on the machine, which by default is switched off as the machines +ship for security reasons. Rather than typing in and risking error through +paraphrase, here is a link to a site which tells you how to do this - +

http://www.macos.utah.edu/Documentation/macosx/security/enablerootuser.html
+Or alternately, +
http://www.thinkmacintosh.com/osxfaq.html
+ +


One you have a root account enabled, you have to su root you cd +to the directory which the Fink installer generates, and it puts libdl.a +and the associated .h files in sensible system places so the compiler just +finds them. +

There is one oddball problem - if you rely on Path to find the resulting +executables, a weird Core Graphics error occurs - so even though I set +up my path to include $(OSGHOME)/bin, and when I cd to $OSGHOME and type +for example hangglide, the application starts fine (so it is in the path), +but at the point it tries to use GLUT to open a window it falls over with +a CGS error (which is I think Core Graphics System). If you explicitly +go bin/hangglide it works fine. Weird, it may be an OS X 10.04 issue which +is gone in 10.1 or it may be a weirdy in the Mac GLUT implementation, but +forewarned is forearmed. +

+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 +links don't seem to work under cygwin, so a make instlinks will simply +copy files just like make install. 'make install' places all files in /usr/local/OpenSceneGraph +under appropriate subdirectories. To get full details of make options, +type: make help (highly recommended) +

OSGFILEPATH environmental variable +

For the OSG to locate file data files easily an environmetal variable +OSGFILEPATH is used at run-time by the osgDB library. Note, for examples +below substitute in the ${OSGDATA} directory with your own path where appropriate) +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) +

+Plug-in dependencies

+You may have compile errors if you don't have all the required libraries, +especially for the plugins. As long as the core libraries osg, osgUtl, +osgGLUT and sgv have compiled you won't have any problems running the osg +itself but may not be able to use some non-native data formats. To get +the problematic plugins working you may need to download support libraries +such as libtiff, libjpeg etc. For further details see index.html. +

+Using STLport under Windows

+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. +The key configuration that the OSG needs to do is to enable the wrapping +of MS's own iostreams, than using STLport's own implementation. The later +is not required because this has not be problematic under Windows, it is +only the container classes and algorithms that need replacing (thanks to +MS's utterly hopeless implementation of these). Using the iostream wrappping +option means the STLport can just be used on your include path, there is +no need to compile STLport itself, or link into any special libraries. +To configure STLport simply comment IN (its commented out by default), +the follwing line from STLport-4.5/stlport/stl_user_config.h so it should +look: # define _STLP_NO_OWN_IOSTREAMS 1 Then configure the includes path +in Visual Studio to pick up on STLport: Select the "Tools" menu. Select +"Options" In the Options dialog, select the "Directories" tab Under the +"include" option, add the path to STLport4.5, something like: D:/STLport4.5/stlport +Then press the up array to move the entry all the way to the top of the +list, thus overriding MS's own STL implementations. +

+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: +

English +

1) Untar the tarball. It will create a directory called fixosg/ +
2) Change to the ReadHat7.2_fixglu/ directory +
3) Become root +
4) Run the script called fixglu
+Cmd line +
tar xvzf ReadHat7.2_fixglu.tar.gz +
cd ReadHat7.2_fixglu/ +
su (your root password) +
./fixglu +
exit
+You should then be able to do a "make" in your OSG directory and everything +will build as it should. Let me know if this doesn't work and I will try +to improve it. Email me directly for help instead of posting here. There's +a README in the tarball with some info on what the script actually does. +There's nothing wrong with OSG itself; the problem with Redhat 7.2 is that +it doesn't have GLU 1.3 by default, which OSG is now dependent on (for +osgText.) Good luck everyone. - Clay +

+
  + + diff --git a/doc/introduction.html b/doc/introduction.html index 928975aa0..ad444cffe 100644 --- a/doc/introduction.html +++ b/doc/introduction.html @@ -11,7 +11,7 @@

Welcome to OpenSceneGraph project!

-

The OpenSceneGraph is an Open Source, Cross Platform (Widows, Linux, Mac OSX, FreeBSD, Irix, Solaris), +

The OpenSceneGraph is an Open Source (LGPL), Cross Platform (Widows, Linux, Mac OSX, FreeBSD, Irix, Solaris), Standard C++ and OpenGL based graphics development library, uses range from visual simulation, games, virtual reality, sceintific visualization and graphics research. This pages introduces a what scene graphs are, why graphics developers use them, and details about the OpenSceneGraph, @@ -25,7 +25,7 @@ April 2002.

What is a Scene Graph?

-

Its a tree! Quite simply one the best and most reusable datastructures invented.Typically drawn schematically as +

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 into hierachy of nodes representing either a spatial grouping of objects, @@ -34,7 +34,7 @@ the various states of a traffic light.The leaves of the graph represent the phyi themselves, the drawable geometry and their material properties.

-

A scene graph isn't a complete game or simulation engine, although may be one of the main +

A scene graph isn't a complete game or simulation engine, although may be one of the main components of such an engine, it's primary focus is representing your 3d worlds, and rendering it efficiently. Physics models, collision detection and audio are left to other development libraries that a user will integrate with.. The fact that scene graphs don't typically integrate all these features is actually a really good thing, it aids interoprability with clients own applications @@ -47,7 +47,7 @@ programs.

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

-

Performance - scene graphs provide an excellent framework for maximize graphics +

Performance - scene graphs provide an excellent framework for maximize graphics performance. A good scene graph employs two key techinques - culling of the objects that won't be seen on screen, and state sorting of properties such as textures and materials so that all similar objects are drawn together. Without culling the CPU, buses and @@ -58,7 +58,7 @@ states, stalling the graphics and destroying graphisc throughout. As GPU's get stalling the graphics is also going up, so scene graph are become ever more important.

-

Productivity - scene graphs take much of the hardwork required to develop +

Productivity - scene graphs take much of the hardwork required to develop high perftomance graphics applications. The scene graphs manage all the graphics for you, reducing what would be thousands of lines of OpenGL down to a few simple calls..Furthermoe, one of most powerfukl concepts in Object Orientated programming is that of object @@ -71,13 +71,15 @@ a great deal with very little coding.A dozen lines of code can be enough to load and create an interactive viewer!

-

Portability - scene graphs encapsulate much of the lower level tasks of rendering +

+Portability - scene graphs encapsulate much of the lower level tasks of rendering graphics and reading and writing data, reducing or even eradicating the platform specific coding that you require in your own application. If the underlying scene graph is portable then moving from platform to platform can be a simple as recompiling your source code.

-

Scalability - along with being able to dynamic manage the complexity of scenes +

+Scalability - along with being able to dynamic manage the complexity of scenes automatically to account for differences in graphics performance across a range of machines, scene graphs also make it much easier to manage complex hardware configurations, such as clusters of graphics machines, or multiprocessor/multipipe systems such as SGI's Onyx. A good scene graph @@ -106,13 +108,14 @@ source or support which once you get stuck in you grow to appreciate.

The project itself is written entitely in Standard C++ and OpenGL, makes full use of STL and Design Patterns, and leverages the open source development model to provide clean, highly portable, -and flexible scene graph. The project is current in alpha, which means part of the API are still to be +and flexible scene graph. The project is current in alpha, which means parts of the API are still to be developerd, or subjec to change, but the vast majority of the scene graph is there, and a beta will be published within the next few months, wiht a 1.0 release in late summer. Despite the alpha development status, the project has alrady earned the reputation as one of the leading -open source scene graph, and is establishing itself a vialbe alternative to the commericial +open source scene graphs, and is establishing itself a vialbe alternative to the commericial scene graphs. Numerous companies, university researchers and graphics enthusasts have -already adopted their project, and a from all over the world.

+already adopted their projects, and are from all over the world. +