VRML 2.0 EAI FAQ

• What is the EAI?
• What is the difference between internal Script Nodes and External Authoring Interface?
• Is the External Authoring Interface a standard protocol?
• Is the EAI static?
• Which browsers support EAI?
• What else is necessary when installing?
• Which classes are necessary in CLASSPATH?
• Where can I find the packages beginning with "vrml" and "netscape"?
• What are the CLASSPATH settings for specific browser combinations?
• How do I use EAI classes with an IDE?
• Which languages can I use to program to EAI?
• How do I work with multiple browsers?
• What tags do I add to HTML file containing VRML .wrl file and applet?
• How do I make Nodes in .wrl file available to external interface?
• What are EAI specifics for Java?
• How do I make External Applet?
• How do I connect to Browser plugin instance?
• How do I access nodes from applet?
• How do I handle events to and from nodes?
• How do I receive events from VRML world in applet?
• How do I createVrmlFromString()?
• How do I get access to nodes that are added to scene after scene creation?
• Why are DEF names in createVrmlFromString(), createVrmlFromURL(), and Inline nodes not accessible from the getNode() method?
• How do I create PROTO from String using EAI?
• How do I shoot trouble?
• How do I stop EAI from crashing browser?
• Where can I see examples with source?
• Where can I get more information or sites that use VRML EAI?
• Where can I get or add EAI FAQ information?

"Both the internal Java Script Node and the External Authoring Interface allow programmers to control the nodes in the scene graph from within Java. The choice between them is largely down to the taste of the programmer though many follow a fish bowl metaphor, using the script node for behaviours purely within the world and the external interface for behaviours linking outside. Within a WWW browser the EAI provides simple access from an applet on the same page as the VRML browser, currently using Live Connect."

"You can check out a paper I wrote on the subject:

http://www.marrin.com/vrml/papers/InternalExternal/Chris_Marrin_1.html

Executive summary of that paper: "Use Java in a Script node when you want to add composable behavior to individual objects in a VRML world. Use the EAI when you want to create integrated multi-media presentations, of which VRML is one media type of many."

import vrml.external.Browser;
import vrml.external.Node;
import java.applet.Applet;

public class AnApplet extends Applet{

    Browser browser=Browser.getBrowser(this);

    Node rootnode=browser.getNode("ROOT");

}

• Netscape Communicator 4.04 for Macintosh
• Netscape Communicator 4.04 for Win32
• Netscape Communicator 4.04 for IRIX
• Microsoft Internet Explorer 4.0 for Win32
• Netscape Navigator 3.01 for Win32
• Netscape Navigator 3.01S for IRIX
• Microsoft Internet Explorer 3.0 for Win32

• Cosmo Software Cosmo Player 2.1 or later for Macintosh
• Cosmo Software Cosmo Player 1.0 beta 3 or later for Win32
• Cosmo Software Cosmo Player 1.0.2b3 or later or 2.1 for IRIX
• Intervista WorldView 2.0 or later for Win32
• VRwave
• blaxxun interactive CC3D

• vrml.external.Browser;
• vrml.external.Node;
• vrml.external.field.*;
• vrml.external.exception.*;

• netscape.javascript.JSObject;
• netscape.plugin.Plugin;
• netscape.javascript.JSException;

set CLASSPATH=C:\java\lib\classes.zip;C:\Program Files\Netscape\Navigator\Program\java\classes;C:\java\classes\vrml\;

setenv CLASSPATH="/usr/local/java/lib/class.zip:/usr/CosmoPlayer/classes:/usr/local/lib/netscape/java301"

I was able to get the EAI working w/ Cosmoplayer 1.0.2 on an Indy R5k,
so if anyone is interested, here's what i did:
1. Intall the SGI version of Netscape 3.01, called Netscape 3.01S from
http://www.sgi.com/Products/Evaluation/evaluation.html
2. Install CosmoPlayer 1.0.2 from http://vrml.sgi.com/cosmoplayer
3. Now for a hack:  as root, copy the directory
/usr/CosmoPlayer/classes/vrml to /usr/local/lib/netscape/plugins
        cp -r /usr/CosmoPlayer /usr/local/lib/netscape/plugins
This will create a directory called /usr/local/lib/netscape/plugins/vrml
with all the appropriate vrml.external.* files.
Moving files here means Netscape can find the classes by default without
having to set the CLASSPATH variable to something special, and without
having to play with java_301.
If you do not have access to /usr/local/lib/netscape, here is a
workaround:
3a. Create a directory called ~/.netscape/plugins, unless it already
exists (it does not by defalut).
3b. Copy the files from the CP dir to there:
        cp -r /usr/CosmoPlayer ~/.netscape/plugins
4. Make sure your CLASSPATH env variable is not set.
5. Quit netscape, and restart.
You should get the new version of netscape w/ the SGI logo.  Only the
EAI stuff works, no java script nodes.  (test with
http://vrml.sgi.com/moving-worlds/spec/RGBTest/)  If the applet does
not load, try reloading the page.  You can also get it to work by
setting the CLASSPATH env variable, but I prefer not to mess with that.
good luck!

SET CLASSPATH=%CLASSPATH%;C:\Program Files\Netscape\Communicator\Program\Java\Classes
SET CLASSPATH=%CLASSPATH%;C:\Program Files\Netscape\Communicator\Program\Plugins\Npcosmop.zip

The Microsoft Java VM looks for java classes in the directories
specified in the registry key :

HKLM\Software\Microsoft\Java VM\Classpath

So you have to append D:\Cosmo\npcosmop.zip; to that entry.

- don't set your CLASSPATH in the shell
- compile using javac -classpath /usr/local/lib/netscape/java_301:/usr/CosmoPlayer/classes:/usr/java/classes:. foo.java

i use netscape's classes is because i'm using jdk 1.1 and compiling
against jdk's classes may issue warnings about 1.0-style use of AWT,
and may generate incompatible code.  you can also use
/usr/local/communicator/java/classes/java40.jar instead if you like.

my makefile looks something like this:

SHELL = /bin/sh

JAVAC = javac
JFLAGS =  -classpath /usr/local/lib/netscape/java_301:/usr/CosmoPlayer/classes:/usr/java/classes:.

                                   ..., the way I got the EAI to work
under Ns4.04 and Irix CP1.0.2 is to have the CLASSPATH unset and either
copy the /usr/CosmoPlayer/classes directory into the
/usr/local/lib/netscape/plugins directory, or make a symlink.  (i.e.,)

cp -r /usr/CosmoPlayer/classes/* /usr/local/lib/netscape/plugins
or 
ln -s /usr/CosmoPlayer/classes/vrml /usr/local/lib/netscape/plugins/vrml 

I'm finding that I *must* use the java_301 file, because I get lots of
error messages if I try to put the java40.jar file in my CLASSPATH or
specify it in the javac command line classpath.

On the MAC, you need to explicitly "include" in your project the jar
file containing the vrml classes, when compiling a new EAI applet which
contains those classes. The jar file is CosmoPlayer.jar and is contained
in the Netscape plugins directory. 

Amit 

Tchavdarov Ludmil wrote:
> 
> we've recently installed Cosmo Player 2.1a on our MacOS8.1. EAI works
> fine but when we try to compile new classes importing vrml.external.*
> and
> netscape.javascript.JSObject the compiler doesn't find them. We've also
> tried to set the Class Path but it doesn't work anyway. Does anybody
> know
> how this whole procedure works on Mac?Thanks for your help!
> - Massimo

The vrml.external.XXX classes can't be found by the Symantec compiler and
also it issues numeric underflow errors for many of the float constants
used in those sources... Just changing the compiler option at
Project/Settings/Build to "Use Sun's javac compiler" compiles fine!!!

... Thus,
Put the following line (or change it) into config.sys:

    SHELL=c:\windows\command.com C:\ /E:4096 /P

SHELL tells witch shell dos is using (c:\command.com?) and the /E:4096
tells it how much memory it should reserve. (C:\ = root; /P = Permanent
shell [~UNIX login])

There should be nothing special that needs to be done to enable the
EAI. Of course you need to have JAVA enabled in the browser. And
if you have a CLASSPATH set (which you should not need at all) but
if you do then you need to make sure these items are on the path in
this order:

/var/netscape/communicator/java/classes:
/var/netscape/communicator/java/classes/java40.jar:
/var/netscape/communicator/java/classes/npcosmop.jar

I have found that even if the jar files are in the same directory
they have to listed explicitly.

	<EMBED SRC="VRMLFile.wrl" >

	<APPLET code="ExternalApplet.class" MAYSCRIPT>
	</APPLET>

	#VRML V2.0 utf8

	DEF NODE Transform{}

To be safe, only access DEF names in the root world and outside any PROTOs. Also, if the root world has duplicate DEF names, only the last one is accessible.

	import vrml.external.Browser;

	import vrml.external.node.Node;
	import vrml.external.field.EventInSFVec3f;
	import vrml.external.exception.InvalidEventInException;

	import vrml.external.*;
	import vrml.external.field.*;
	import vrml.external.exception.*;

	public class ExternalApplet extends Applet{

		Browser browser;

		browser= Browser.getBrowser(this);

		Browser.getBrowser(Applet applet, String frame, int index)

	JSObject win = JSObject.getWindow(this);
	JSObject doc = (JSObject) win.getMember("document");
	JSObject embeds = (JSObject) doc.getMember("embeds");
	browser = (Browser) embeds.getSlot(0);

Kent Sandvik wrote:

Paul Ingalls wrote:
>
> Where can I find some up to date docs on the JSObject package?  The
> stuff on Netscape's site is out of date.  I want to have a java applet
> in one frame talk to a vrml file in another frame using the EAI.  Any
> help would be appreciated...

You could actually avoid using JSObjects now, at least in CP 1.0
forward, as the Browser.getBrowser(applet) API (see
http://vrml.sgi.com/moving-worlds/spec/ExternalInterface.html) is
supported.

As for getting access to an EMBED VRML tag in another frame,
Browser.getBrowser supports this at least in the API level, but as for
how well it works, I've never tried this myself (tend to have applet and
the vrml world in the same frame, if accessing the browser from another
frame does not work, one possible clumsy workaround is to have two
applets communicating, and the one tied to the frame/EMBED tag is an
invisible one).

	Node somenode;

	try{
		somenode=(Node) browser.getNode("NODE");
	} catch (InvalidNodeException e){
		System.out.println("Invalid Node Exception");
	}

	// instance EventIn

	EventInSFVec3f setnewtranslation;

	// random values to set

	float[] valuetoset={0, 0, 0};

	// here get EventIn of Node 

	try{
		setnewtranslation=(EventInSFVec3f) somenode.getEventIn("set_translation");
	} catch (InvalidEventInException e){
		System.out.println("Invalid EventIn Exception");
	}

	// here set value of EventIn to Node

	setnewtranslation.setValue(valuetoset);

	public TheEventOutObserver extends Object implements EventOutObserver{

	public void callback(EventOut event, double timestamp, Object someobject){

		//cast values and use them to do something

		int four=4;
		if (four ==((Integer)someobject).intValue()){function()}

	}

	TheEventOutObserver theeventoutobserver;

	EventOutSFVec3f theeventout;

	try{
		theeventout=(EventOutSFVec3f) somenode.getEventOut("translation_changed");
	} catch (InvalidEventOutException e) {
		System.out.println("Invalid EventOut Exception");
	}

	theeventout.advise(theeventoutobserver, null);

	eventout.advise(this, new Integer(4));

	public void callback(EventOut event, double timestamp, Object someobject) {
		Integer x=(Integer)someobject;
	}

Basically you have to get a handle on an initial transform or group in
the scene, and then add the Node[] you create with
"createVrmlFromString" to the scene.

Node root = browser.getNode("ROOT")

try {
  Node[] tmp = browser.createVrmlFromString("Transform { translation "+
                "0 10 0 children Shape { appearance Appearance { " +
                "material Material { diffuseColor 1 1 1 } } geometry "+
                "Box { size 2 2 2 } } }");
  EventInMFNode addChildren  = (EventInMFNode) root.getEventIn("addChildren");
  addChildren.setValue(tmp);
}
catch (InvalidVrmlException e) {
  System.out.println("Bad vrml...");
}

A: The DEF name capability in VRML is a syntactic construct which allows nodes to be USE'd and routes to be defined between nodes in the same VRML file scope. It was never intended as a runtime name dictionary facility. The EAI presented a problem to VRML in that it has no implicit knowledge of any nodes in the world, and it exists outside any file scope, so it has no access to any nodes by name. It was decided to overload the semantics of DEF names to allow the EAI to get access to named nodes using the getNode() browser method. This was limited to nodes named in the base file (the file used to construct the original world or the file loaded with loadURL). Allowing DEF names created in any other scope (i.e., createVrmlFromString, createVrmlFromURL or Inline nodes) to add to the names accessible from the EAI would cause several problems:

- Since there is no name dictionary management facilities, there is no way to remove names once they are added. Over time, thousands of named nodes may be created, which would cause the dictionary to grow without possibility of ever shrinking.

- If two nodes are added with the same name (which is legal in VRML) undefined results will occur when the EAI attempts to access this name. Since VRML does not define the order of execution of scripts or the order of loading of Inlines, different browsers would present different nodes at different points in time. There would be no way to control this ambiguity.

- In the case of Inlines, the data hiding feature of VRML would be broken, because the EAI would be able to gain access to the internals of the Inline scene.

- Optimizations would be made very difficult because the EAI would have potential access to much more of the scene. Even though the EAI will probably NOT attempt to access most of the DEF'ed nodes (many nodes are simply DEF'ed so they can be routed or reused) that access MAY occur. Therefore, Inlines could not be unloaded for efficiency, and parts of the scene graph cannot be simplified.

The VRML statements passed to createVrmlFromString() must be self-contained; the string is its own, separate scope. So, if you want to instantiate a prototype named Foo, you will have to use an EXTERNPROTO declaration in the string, like this:

    nodes = browser.createVrmlFromString(
    "EXTERNPROTO Foo [ ] \"#Foo\"
     Foo { }");

You can't use a PROTO from the file in a createVrmlFromString call. You
would have to either include the text for the entire PROTO in the string
or put the PROTO into another file and include it in the string as an
EXTERNPROTO (since this is a short PROTO the former solution is probably
best).

> Q:What methods have to be called in the start
> method to reload the page of an EAI applet and world?  Do you have to get
> the browser instance again?  Do you have to get each of the nodes again?  In
> general, which elements have to be called on public void start() to allow
> for clean reload?

The init() method of your applet gets called only once, when the applet is first loaded into the JVM. When you reload or come back to the page, only start() method is called.

The reason most applets lose their "connection" to the browser is they call getBrowser() in init().

If you call getBrowser() and the EAI specific initialization methods (initializing some variables by getNode and etc.) in start(), then the applet works fine even if you change pages and come back or reload the page.

>i got this in my java console:
>
>AppAccelerator(tm) 1.0.2a for Java, x86 version.
>Copyright (c) 1996 Borland International. All Rights Reserved.
>java.lang.NoSuchFieldError: native method specified an invalid field
># Applet exception: exception: java.lang.NullPointerException
>java.lang.NullPointerException

Brant Chamberlain wrote:
> I have found that the getBrowser function fails when
>
> embeds = (JSObject)doc.getMember("embeds");
>
> is called.
>
> What's even more infuriating is that this problem dissapears on
> other machines I've tested at my office. Is this a configuration issue?
> Has anybody had similar experiences. Any help REALLY appreciated...
>
> Using Netscape 4.04 and Cosmo 1.02

Your system classpath does contains references to either the cosmo
player zip file or to the netscape class implementation. Remove them.
Also, use the proscribed method of getting the browser reference with
the Browser.getBrowser() methods.

TMP=C:\WINDOWS\TEMP
TEMP=C:\WINDOWS\TEMP

• EAI Examples: site at Cosmo Software
• TestExternal4 Example: simple node traversal.
• NowTV Examples: callback examples
• Paulitsch Examples: synch move and others
• gcPoser Example: kinetic animation
• Tic-Tac-Toe: ancient game

• Cosmo Software has a good site at http://cosmosoftware.com/developer/eai.html.
• Bret Dahlgren's Crazy Eights 3D.
• Justin Couch's JVerge VRML Class Libraries
• WorldView 2.0 Developer's Guide
• news:comp.lang.vrml newsgroup
• sgi.cosmoplayer and sgi.dev.cosmoplayer newsgroups
• Claudio Riva's Java and VRML Report
• SGI's VRML Content Developer : EAI
• Matthew Lewis' Sanbaso: humanoid keyframe animation system
• Vrml, Java, Eai, a site in Italian
• VRML - Welcome from The Mining Company has many VRML examples.
• AltaVista Search
• VRML Primer and Tutorial
• Javier Cuesta VRML & Java Consulting
• Java Documentation
• Bob Crispen has created a VRML Galleries and Worlds page with several EAI examples from other sources.

Java (TM) is a copyright of Sun Microsystems, Inc., Netscape Navigator(TM) is a copyright of Netscape Communications Corporation, Cosmo(TM) Player is a copyright of PLATINUM technology IP, inc., WorldView 2.0(TM) is a copyright of PLATINUM technology IP, inc. MSIE ActiveX and MS Internet Explorer are trademarks or registered trademarks of Microsoft Corporation. Disclaimer. All rights reserved. © Finlayson Consulting VRML Group