Quick Start
-
Create a new directory and move into that directory (i.e. mkdir myYG)
-
Copy the file /usr/local/yg/RUN to the current directory
-
Make a sub-directory called data and place any models, textures, and sounds there
-
Edit a scene file in any text editor (i.e. gedit myscene.yg &)
-
Type ./RUN scene where scene is the name of your scene file
Models
Because Ygdrasil is built upon the Performer scene graph library, it can take advantage of the built-in model loaders provided with it.
Remember that textures associated with model files must be moved to the system running YG along with the model file itself.
The majority of the model loaders were written for Performer by the companies that promote the model format.
As a result, the converters do not always perform as expected:
- The OpenInventor loader has proven reliable at converting Open Inventor files (*.iv)
- is not normally distributed with Linux distributions
- can load VRML 1.0 files by changing the header to
- The OpenFlight loader has proven reliable at converting Multigen Creator files (*.flt)
- The VRML 2.0 loader will convert most VRML 2.0 files (*.wrl)
- will not load VRML 1.0 files
- has been known to reverse the normals on some polygons
- will often require that absolute path names are manualy changed in the *.wrl file
- is not normally distributed with Linux distributions
- The Alias Wavefront loader will convert files saved from MAYA (*.obj)
- it will not load textures and materials associated with the model
- The MAX loader will load 3D Studio Max files (*.3ds)
- it will not load textures associated with the model
The native model format of Performer is called PFB and is a binary format.
The PFA format, also used natively by Performer, is an ASCII format that can be edited.
If a model is not in PFB format before runtime, it will be converted when loaded.
Performer provides a tool, pfconv to convert models to PFB format if it is desired to avoid the time associated with runtime conversion.
When converting MAYA files for use with YG using Polytrans plug-in for MAYA:
- Polytrans is activated from within MAYA by typing pt into the command line interface
- choose to export as OpenInventor version 2.0 with the *.iv extension
- adjust the options to make sure that absolute path names are stripped from the front of texture files
- convert the file to OpenInventor format
- move the model file and any associated texture files to the computer running YG
When converting MAYA files for use with YG using standalone Polytrans:
- export MAYA selections as VRML2.0 files with *.wrl extension
- edit the VRML file to strip any absolute texture file paths
- import the VRML model into Polytrans
- choose to save as OpenInventor version 2.0 with the *.iv extension
- move the model file and any associated texture files to the computer running YG
Textures
The Performer library primarily uses textures stored in the RGB format, sometimes known as SGI format.
- Performer also requires that textures are stored in powers of 2 (i.e. 2x2,256x256,256x512,512x1024)
- Typically textures with dimensions of 256 are adequate, and textures of dimensions of 1024 are avoided because of their large size
- The model format loaders associated with Performer may handle other texture formats
- The VRML 2.0 loader will convert JPG and GIF textures into RGB textures with powers of 2 automatically
- The OpenFlight loader will convert RGB images that are not properly sized into powers of 2 automatically
Sounds
All sound nodes in Ygdrasil use the Bergen sound server.
To start the sound server, run the executable snerd located in one of the binary directories of the Bergen software.
Creating Scenes
In order to interact with a scene, you must include a User node,
with appropriate navigator, head, and wand(s) under it. Without a User,
you can see the scene, but not navigate or activate any triggers.
The Space class is the parent for any node class which covers
a volume (sounds, triggers, and environments). It provides a standard way
to define volumes, via the volume message; these can be boxes, spheres,
cylinders, infinite spaces (i.e. everywhere), or point volumes (mostly
useful for sounds).
Environment nodes are used to control the sky color, fog, and
clipping planes. Whichever environment volume the user is currently inside
of will define these attributes; if environments overlap, the result is
currently semi-random.
Here is an example scene:
User User0 ()
{
caveNavigator User0Nav (fly(off))
caveHead User0Head ()
caveTracker User0WandTracker (sensor(1))
{
caveWand User0Wand (when(button3, User0Nav.toggleFly))
}
keyboard User0KB (when(ckey, User0Nav.toggleCollide))
}
light sun ()
light sun2 (position(-.5 -1 1))
object (file(ground.pfb), floor, position(0 0 -5))
switch spinnerSwitch ()
{
spinner (position(-5 2 7))
{
object (file(banana.pfb))
}
}
Environment space0 (volume(box -1000 -1000 -1000 1000 10 1000),
skyColor(.5 .7 1))
Environment space1 (volume(box -1000 10 -1000 1000 1000 1000),
skyColor(0 0 0))
WandTrigger trigger0 (volume(sphere 0 5 5 3),
when (enter, print($user entered)),
when (button1, space0.skyColor(1 1 .2)),
when (button2, spinnerSwitch.toggle) )
Runtime Options
The default RUN file sets several environmental variables, starts the
snerd sound server, and runs the YG executable. The following environmental
variables can be set to control program behavior. All paths are a
colon-separated list of directories and include the current directory by
default:
-
YG_PATH - defines the search path where scene files and other media can be found
setenv YG_PATH data:/usr/local/yg/data
YG_DSO_PATH - defines the path to search for node DSO files
setenv YG_DSO_PATH dso:/usr/local/yg/dso
YG_DEBUG - lists various debugging flags which are to be set (multiple
flags are separated by spaces)
setenv YG_DEBUG "world.sentMessages *.volume"
YG_NET_SERVER - name of the host which is the "server" for a networked
environment. That is, the machine which is running ygrepeater for
the shared world that you want to join (or create). If this variable is
not set, the world will not be run networked.
setenv YG_NET_SERVER reeves.evl.uic.edu
YG_NET_PORT - port number for the network server's ygrepeater
(the default is 3500)
setenv YG_NET_SERVER 2700
YG_CPP_COMMAND - pre-processor command to run scene files through before
parsing them. On SGIs, the default pre-processor is "/bin/cc -E"; under
Linux, the default is "/usr/lib/CC". Use this variable if your pre-processor
is located somewhere else, or if you want to use a different pre-processor.
Files included in your scene using the #include directive are found by
including them in the pre-processor command line.
setenv YG_CPP_COMMAND "/usr/bin/CC -E -I/usr/local/yg/examples"
YG_PRELOAD_CLASSES - lists node classes whose DSOs should be pre-loaded,
before pfConfig() is called to fork all the Performer subprocesses. This
is necessary for any class which defines drawing callbacks; without it,
the DSO will be loaded after the fork, and only the main app process will
have access to the drawing functions.
setenv YG_PRELOAD_CLASSES "mirror clipper"
YG_PF_SHOW_TEXTURES - tells the yg main program to show texture maps as
it downloads them during startup. If this variable is not defined, this
will not be done.
setenv YG_PF_SHOW_TEXTURES
Creating Nodes
The majority of the nodes available for YG scripting are a Dynamic Shared
Object(DSO). Users can make their own DSO nodes for personal use
or submit them to the YG library for use by others. See the information
in the about section for information on including
DSO nodes in the code library.
In order to add new DSO nodes to your scene, do the following:
-
make a sub-directory called modules and place your DSO code there
-
copy the file Makefile from /usr/local/yg/modules to the modules
directory
-
change directories to modules and type make file.so where
file is the name of your DSO file
-
create a dependency file for your module if
it relies on another DSO node
The following is a skeleton of the C++ code for a basic Ygdrasil node class.
The script makeNode will generate something like this.
simpleNode.h
#ifndef _simpleNode_h_
#define _simpleNode_h_
#include "ygNode.h"
class simpleNode : public ygNode
{
public:
simpleNode(const char* name,bool master=true);
virtual void reset(void);
virtual void message(const ygMessage&);
virtual void app(void);
};
#endif
simpleNode.cxx
#include "simpleNode.h"
using namespace std;
extern "C" ygNode* construct_simpleNode(const char* name,bool master) { return new simpleNode(name,master); }
simpleNode::simpleNode(const char* name,bool master) : ygNode(name,master)
{
setClassName("simpleNode");
}
void simpleNode::reset(void)
{
ygNode::reset();
}
void simpleNode::message(const ygMessage& msg)
{
if (msg == "mymessage")
{
/* mymessage(msg.floatArg(0)); */
}
else
ygNode::message(msg);
}
void simpleNode::app(void)
{
ygNode::app();
}
All messages will be automatically parsed into ygMessage objects, which
contain the message name and a vector of the arguments, all as ygStrings.
For instance, position(1 0 2) becomes an ygMessage with the message
name "position" and 3 arguments - "1", "0", "2". The == operator is overloaded
for messages to compare message names with strings, as in the msg ==
"mymessage" above. There are also a number of convenience functions
for converting message arguments into various types:
-
msg.intArg(i) returns argument i as an int
-
msg.floatArg(i) returns argument i as a float
-
msg.boolArg(i) returns argument i as a bool; "true", "on",
or "1" are interpreted as true, everything else as false
-
msg.getVec2Args(v,i) fills in pfVec2 v with the values of
aruments i and i+1 (i defaults to 0)
-
msg.getVec3Args(v,i) fills in pfVec3 v with the values of
aruments i through i+2 (i defaults to 0)
-
msg.getVec4Args(v,i) fills in pfVec4 v with the values of
aruments i through i+3 (i defaults to 0)
-
msg.args[i] is the ygString argument itself
-
msg.args.size() will give the number of arguments
The Makefile in the /usr/local/yg/modules directory can be used to compile
a node class into a DSO (e.g. "make simpleNode.so" for the above). The
directory containing the DSO should be included in the YG_DSO_PATH environment
variable, and then the Ygdrasil executable will automatically load it if
it encounters the node type name in a scene file.
Dependencies
If your new class is derived from another node class that is not built-in
(that is, from some other DSO class), the DSO for the parent class must
be loaded before the derived class's DSO. Otherwise, the derived class's
DSO will have unresolved symbols, and it will fail to load. To tell Ygdrasil
about other classes to load before a given class, list them in a ".ygdep"
dependencies file. For example, if the class fancySpinner is derived
from spinner, then in the same directory that contains fancySpinner.so
there should be a text file named fancySpinner.ygdep, with a line that
says
spinner
If there is more than one dependency, list each one on a separate line.
You do not need to list any dependencies of the parent class - those will
be found recursively as the parent class is loaded.
Networking
The built-in node classes automatically share their state when running
networked. Remote users can join an existing world by simply connecting
to a server, without needing the scene file for the world, just a scene
describing their user. As with normal YG scenes, the nodes related to each
user should have unique names.
In order to start a networked scene, do the following:
-
start the process ygrepeater (on a separate machine if possible)
-
adjust the YG_NET_SERVER environmental variable to reflect the address where ygrepeater is running
-
start your scene as usual (i.e. ./RUN myscene.yg)
-
wait for the scene to finish downloading to the server
- start a scene containing only a user on another machine (i.e. ./RUN User2)
Downloads
Ygdrasil runs under both IRIX and Linux and requires the SGI OpenGL Performer software library.
The Performer software library can be downloaded from www.sgi.com.
Ygdrasil Version 0.4
Ygdrasil has recently been upgraded from version 0.1.11 to version 0.4.
Applications using version 0.1.11 cannot be networked with the newer version.
User modules developed using the 0.1.11 architecture must be modified to work with version 0.4.
A listing of the enhancements to version 0.4 can be found here.
A tar file containing the full distribution can be downloaded here:
yg_0.4.tar.gz
The distribution includes binaries for GCC 2.9x environments using Performer 3.x.
This version has been compiled against CAVElib 3.0.3 and requires a valid CAVE license.
The software comes statically linked against QUANTA version 0.4.
When rebuilding, a tar file containing the full distribution of QUANTA version 0.4 can be downloaded here:
QUANTA-0.4.tar.gz
Ygdrasil Version 0.1.11
A tar file containing the full distribution can be downloaded here:
yg_0.1.11.tar.gz
Due to licensing restrictions, binaries for IRIX and Linux are not included in the distribution.
EVL students can obtain binaries from the internal EVL website:
yg_0.1.11_binaries.tar.gz
Other collaborating researchers can obtain binaries by contacting Daniel Sandin at dan@uic.edu.
IRIX binaries have been compliled under Performer 2.4 on IRIX 6.5.
Linux binaries have been compiled under Peformer 3.0.2 on Redhat Linux 7.3 (gcc 2.96).
Ygdrasil uses two libraries developed at EVL, the CAVE library and CAVERN G2, a library for telecollaborative networking.
The binaries distributed with Ygdrasil have been staticaly linked to both the CAVE and CAVERN G2 libraries.
However, these two libraries must be installed before recompiling or relinking Ygdrasil.
Although the current binaries use CAVE_2.7.2, most versions of the CAVE library can be used to recompile and relink Ygdrasil.
The CAVE library can be purchased at www.vrco.com.
A tar file containing the full distribution of CAVERN G2 version 1.2.2 can be downloaded here:
CAVERNG2_1.2.2.tar.gz
The sound related nodes distributed with Ygdrasil use the Bergen Sound Library.
The current version leven of Bergen is 0.5 and was recently upgraded to provide up to 4 channel directional sound.
The distribution includes binaries for both IRIX 6.5 and Linux Redhat 7.3 (OSS).
A tar file containing the full distribution can be downloaded here:
bergen_0.5.tar.gz
The OpenQuicktime library verision 1.0b is required for the movieTexture node on Linux:
www.openquicktime.org
The RAT Robust Audio Tool is used frequently for audio conferencing.
A version pre-compiled for IRIX 6.5 can be found here:
rat_4.2.23.tar.gz