Quick Start

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 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: When converting MAYA files for use with YG using standalone Polytrans:

Textures

The Performer library primarily uses textures stored in the RGB format, sometimes known as SGI format.

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:

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:

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

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