#include <IS3D.H> in your project to include all of the IS3D library headers.
The IS3D library depends heavily on Morgan McGuire's G3D library available at SourceForge.
Before IS3D, InSpace depended on Brown University's GLUE, or gluebase, library for its math library, EVENTs, FSAs, CONFIGval's, and device drivers. gluebase is NOT part of IS3D, all math is done through G3D's math library. IS3D has its own Fsa and Event architecture directly inspired by the the ideas in gluebase, although with some significant changes. The changes are not significant enough to make porting gluebase code to IS3D a huge, daunting project, but they are significant enough to require sitting down to rewrite your code. IS3D also provides support for glue-inspired ConfigVal's.
IS3D has been tested and is setup to run by default with the following compilers and versions:
| Architecture | Compiler-Version
|
| Windows | MSVC++ 6.0 with Service Pack 5 and the Processor Pack
|
| Linux | g++-3.3 |
To compile and install the library follow these steps:
/map/gfx0/tools/shared/man/get-started.txt and <a`href="http://vis.cs.brown.edu/resources/doc/gfxtools-docs/index.html"> on the web here. cd $G cvs up -d IS3D make depend-minimum from the IS3D directory. Alternately, if you plan to use VRPN or OPENAL you can use other make rules, like "depend-usual" or "depend-projects" to compile more of the possible IS3D dependencies. make all. make install.
The IS3D/tests directory contains several applications that test library functionality. In some cases these are good demos of how to use specific functionality in the library.
In addition the freeform3d project in $G/src/freeform3d is currently the most advanced project at Brown that uses IS3D. You can find some examples of how to use the library there.
key=value pairs where key and value are both originally std::strings. But, the value string can be easily reinterpreted by any class that overrides the stream >> and << operators. The ConfigVal() function figures out what type to try to convert to by the type of the second parameter to the function. This parameter also specifies the default value to return if the key is not found in the ConfigMap::_map table.
To use a config file, call ConfigMap::readFile() with the filename of a text file to read. (IS3D will do this for you if you specify the filename with a -f flag on the command line.) The format of each line of the file should be:
key value
where key has no spaces in it. value is everything after the space until the end of the line, so it can have spaces in it. Any line that *starts* with the character # is a comment and is ignored. A single \ character means cut the line here and continue on the next line. Everything after the \ is ignored and the text on the next line is appended to the text on the current line. You can escape the \ operator with a double slash \\ to get a single \ character.
Additionally, any value X appearing inside the special character sequence $(X) will be replaced by the value of the environment variable named X. If X is not defined, it will be replaced by a null string. If X takes the form of the path to a file and you're running in Windows under cygwin then X will be automatically converted from the form /cygdrive/c/blah/blah to the more Windows friendly form c:/blah/blah to stay compatible with the Visual C++ compiler.
Additionally, if you put a += after the key and the key has already been defined, then the value is appended to the key's current value. If you don't have the += and the same key is read in from a file, then the new value overwrites the old. For example:
mykey1 value1 mykey1 value2 mykey2 value3 mykey2+= value4
The value of mykey1 will be "<CODE>value2</CODE>". The value of mykey2 will be "<CODE>value3 value4</CODE>".
IS3D uses FSA's in almost the same way as Brown's glue or gluebase software. Here's a short intro to how this works and some notes about differences between IS3D and glue.
Input in the system happens through Events. All the device drivers, including hookups for keyboard and mouse input, produce these events. An Event can take on a different interpretation depending on the data that it carries. IS3D is different from gluebase in that there is only one IS3D::Event class. Within this class the Event is given a EventType specified by an enum. Based on this enum you can access data from the event with the Event::get*Data() methods. For example, Event::get1DData(), Event::get2DData(), Event::getCoordinateFrameData(), etc.. CoordinateFrames are used to store Events from 6DOF Trackers.
Another difference with gluebase is that there is no separate Event type for buttons. Up and Down events for buttons are generated by creating Events that just have different names. For example, clicking and releasing a mouse button would generate 2 events named "Mouse_Left_Btn_down" and "Mouse_Left_Btn_up".
FSA's, specified in IS3D::Fsa, respond to these Events and can call callback functions you specify when the events are received. Fsa's always have a current state. Arc's connect one state to the next.
If a FSA in your program is fairly complex, then you might want to draw it out rather than programming it. You may already find yourself drawing it on paper, so why not draw it on the computer and import it? We thought this was a reasonable thing to do, so now IS3D supports FSA drawings made with the qfsm program freely available via sourceforge at http://qfsm.sourceforge.net
IS3D needs to extract out names for each Arc in the FSA as well as trigger events that each arc responds to. While working with the qfsm program, put the name for each Arc inside qfsm's Input field. The events that trigger the arc should be specified in a space separated list entered into the Arc's description field. qfsm already has a field for naming each state. Fill this in, and IS3D will automatically extract the state names. In your program create a Fsa from the file using the Fsa::fromQFSMFile() method. If you want your program to respond via callback methods to any of the arc transition, state enter, or state exit events, then add callbacks as usual to the Fsa by referring to Arcs and States by name inside your program.
If you don't like to debug, then working with the $G via cygwin software setup in Windows is great. Just code in XEmacs or whatever your favorite editor is and compile as usual with make in a cygwin shell. Of course, this isn't necessarily the best setup, especially if you're a Windows programmer that is fiarly attached to the Visual C++ debugger. Here are some tips and tricks for getting the best of both worlds.
Perhaps the easiest way to to debug an IS3D program with Visual C++ is to place a debugAssert(); in your code that fails at a buggy place. When it fires tell the dialog window that pops up that you want to Debug and it will open up Visual C++ with the executable. You can then inspect variable values and see the call stack, etc..
You can also setup Visual C++ workspace and project files (.dsw and .dsp) and program and/or debug directly within the Microsoft Development Environment. However, this is a little tricky because you will still want to compile via cygwin and your Makefile. Remember the reason for this is so that your code will compile and run on multiple architectures. The way to set up Visual C++ is to create a new "Makefile Project". Some of the applications inside IS3D/tests provide examples of this. To set it up for your project, follow these steps:
<project-name> with the name of your project:
c:\gfx\tools\WIN32\bin\msvsmake.bat $G/src/<project-name> debug obj/projectname-d.exe -rebuild as the Rebuild All Switch, click Next <project-name> with the name of your project:
c:\gfx\tools\WIN32\bin\msvsmake.bat $G/src/<project-name> opt obj/projectname.exe -rebuild as the Rebuild All Switch, click Finish obj/<project-name>-d.exe
cvs add <project-name>.dsp <project-name>.dsw
cvs add -kb <project-name>.ncb <project-name>.opt
To make code written in XEmacs look good inside MSVS, inside Tools, then Options, set the Tab size to 8 and set indent size to 2.
Command line arguments work in conjuction with the ConfigVal framework. You can specify a file to load that contains ConfigVal key=value pairs. Or, you can specify a specific key=value pair. Value are stored in the order specified so if a key is repeated either in a file or in a command line only the value for the key will be the last one specified. Within your program, access these through the ConfigVal() function.
program-name.exe [-f filename [-f filename...]] [-c key=value [-c key=value...]]
options: (defaults in [...]'s )
-f filename Specifies a key/value config file to process. [null]
-c key=value Specifies a config key=value pair to process.
'value' overrides any ConfigVal for 'key'
specified in a config file. [null]
IS3D Depends upon the following libraries. Libraries that are listed in the table below, but not marked as required are only required for specific functionality within the IS3D library.
Library Description Required by IS3D Required by G3D
GLG3D G3D's OpenGL wrapper Yes Yes
G3D Base G3D types: math, std templates, etc.. Yes Yes
zlib Required by G3D for handling .JPG images Yes Yes
SDL Provides standard windowing, sound, mouse, joystick support across multiple architectures Yes Yes
SDLmain A second SDL library Yes Yes
OpenGL Indirectly required, most of your applications calls should go through the GLG3D OpenGL wrapper Yes Yes
OpenAL Only needed if you want to use SoundImpOpenAL no no
GHOST40 Only needed if you want to compile with support for SensAble's PHANToM device no no
ghost-stl Also required for PHANToM support no no
VRPN Only needed if you want to get device input through UNC's VRPN library no no
-
GLX Visual Errors. If you see something like this, then you are probably requesting a graphics video mode that your graphics card can't support. On linux, try the program
glxinfo to see what you card can support.
___________________________________________________
Critical Error
Unable to create OpenGL screen: Couldn't find matching GLX visual
Press any key for 'Quit'...
___________________________________________________
As an example, this can happen if you ask for 8 stencil bits when your card doesn't support a hardware stencil buffer. A request for a video mode gets sent to G3D and then on to SDL in src/IS3DEngine.cpp, look for GWindowSettings. You can adjust what you request by setting ConfigVals that are read there.
-
Unable to open audio: No available audio device This seems to occur on linux systems that don't have their sound card setup properly. Try running without sound support, or setting up your sound card.
-
Unable to open audio: Gamma correction not supported on this visual I don't know why the bit about Gamma correction is there. I think it is an incorrect error message from SDL, in any case, this is another Linux sound card error.
-
This esd sound message:
esd: Failed to fix mode of /tmp/.esd to 1777.
Try -trust to force esd to start.
esd: Esound sound daemon unable to create unix domain socket:
/tmp/.esd/socket
The socket is not accessible by esd.
Exiting...
This is yet another linux sound card error. Sometimes it comes up even when you run IS3D without sound support, but it doesn't seem to cause problems if you never actually use the sound.
Changes from version to version are listed here:
The details of a license for this software have not yet been worked out. Until a license is in place, this software is for use exclusively within the Brown Graphics group. Mail dfk@cs.brown.edu with questions regarding this policy.