WorldView Developer's Guide

This guide is for developers of VRML content for use with WorldView 2.0. It contains information for both WorldView for Netscape Navigator and WorldView for Internet Explorer. It is divided into five sections:

• Support for VRML 2.0 provides details about WorldView's implementation of VRML 2.0 nodes.
• Support for JavaScript details the support for JavaScript.
• Support for the Java EAI describes the current support for the Java External Authoring Interface.
• Support for Java in Script Nodes describes the current support for Java, including the security model.
• Using the EMBED tag in HTML documents describes the ways you may control WorldView user interface settings from within an HTML document.

Please be sure to consult the WorldView for Netscape Navigator Release Notes and the WorldView for Internet Explorer Release Notes for information about known bugs and important changes.

Support for VRML 2.0

This section describes details of WorldView's VRML 2.0 implementation, including known bugs.

WorldView 2.0 is fully compliant with the Minimum Conformance requirements in the ISO/IEC DIS 14772-1 VRML 2.0 specification, dated 4 April 1997. Fields considered optional according to the Minimum Conformance requirements are supported unless they are specifically mentioned below.

Anchor

Only the first URL specified is used.

In WorldView for Internet Explorer only, URLs that refer to files located on the local disk and contain viewpoint names do not work.

Collision

When the "Prevent Collisions" user option is OFF, users will pass through geometry regardless of Collision nodes. This option is ON by default. To ensure that users will be blocked by geometry, use NavigationInfo type NONE.

ColorInterpolator

The interpolation of colors is performed in RGB color space, not HSV color space.

DirectionalLight

The effect of the color field is only visible when WorldView is in full color mode. (See WorldView's Full Color Setting, below.)

ElevationGrid

In full color mode, vertex colors are supported, but an ElevationGrid with vertex colors is not affected by lights. When full color is off, the vertex colors are averaged to compute face colors, which are affected by lights. (See WorldView's Full Color Setting, below.)

Fog

The fogType is ignored and always assumed to be "LINEAR". Fog is only visible when WorldView is in full color mode. (See WorldView's Full Color Setting, below.)

FontStyle

The family field may include the names of any installed Windows fonts, in addition to "SERIF", "SANS" and "TYPEWRITER". If none of the specified fonts are available on the viewer's system, "SERIF" is used instead.

IndexedFaceSet

In full color mode, vertex colors are supported, but an IndexedFaceSet with vertex colors is not affected by lights. When full color is off, the vertex colors are averaged to compute face colors, which are affected by lights. (See WorldView's Full Color Setting, below.)

IndexedLineSet

Fully supported in full color mode. With full color off, the color field is ignored; the emissiveColor of the Material node is used to color the line set. (See WorldView's Full Color Setting, below.)

ImageTexture

Supported file types are GIF, BMP, JPG, RAS, PPM and PNG.

The repeatS and repeatT fields are ignored.

Intermediate alpha opacities are not supported. Pixels with alpha less than 0.5 appear fully transparent, and pixels with alpha greater than or 0.5 appear fully opaque.

Material

The ambientIntensity field is not supported.

MovieTexture

Supported file types are MPEG, AVI, and QuickTime. Audio is supported in all formats.

The repeatS and repeatT fields are ignored. Negative values in the speed field are ignored.

Intermediate alpha opacities are not supported. Pixels with alpha less than 0.5 appear fully transparent, and pixels with alpha greater than or equal to 0.5 are opaque.

NavigationInfo

The speed field is not supported.

The first value of the avatarSize field is used to determine the allowable distance between the user and geometry during collision detection. Other values in this field are ignored.

Because WorldView's navigation types do not map directly to those described in the VRML specification, the user's ability to change navigation modes is not restricted based on the type field, except in the case of NONE.

The NONE type disables both toolbars, the right-button pop-up menu, and the ability to navigate using the mouse.

The WALK, FLY, and EXAMINE types set the initial navigation mode when the world is loaded. WorldView does not support gravity, so type FLY is the same as WALK.

If the type is ANY, viewpoint transitions triggered by Anchor nodes or the loadURL() scripting method are animated and trigger sensors.

PixelTexture

The repeatS and repeatT fields are ignored.

Intermediate alpha opacities are not supported. Pixels with alpha less than 0.5 appear fully transparent, and pixels with alpha greater than or equal to 0.5 are opaque.

PointLight

The effect of the color field is only visible when WorldView is in full color mode. (See WorldView's Full Color Setting, below.)

The radius field is emulated using quadratic attenuation. If the attenuation field is set to something other than the deffault (1 0 0), the radius field is ignored.

PointSet

When full color is off, the color field is ignored; the emissiveColor of the Material node is used to cpprotocol for including olor the point set. (See WorldView's Full Color Setting, below.)

PointSets that contain thousands of points may not render completely.

Script

Script nodes may contain Java or Javascript. (VRMLScript is supported to the extent that it overlaps with JavaScript.) If the url field does not specify a file, it must begin with one of the following:

• "javascript:
• "vrmlscript:

The "javabc:" protocol for including Java classes directly in .wrl files does not work. Use the url field to specify an external class file instead.

The JavaScript eval() function does not work.

If there is an error in a Script node, the browser sends a notification to the VRML Console. Further events to the Script node are ignored.

A line number of "0" is incorrectly reported when an error occurs on the last line of a script contained within a Script node.

The loadURL scripting method uses only the first specified URL.

See Support for JavaScript and Support for Java in Script Nodes, below.

Sound

The sound model is spherical rather than ellipsoidal. Values in the maxFront and maxBack fields are averaged to determine the radius of the outer sphere; minFront and minBack are averaged to determine the radius of the inner sphere.

SpotLight

The effect of the color field is only visible when WorldView is in full color mode. (See WorldView's Full Color Setting, below.)

Text

Extremely long text strings may not render completely.

TouchSensor

The hitTexCoord_changed eventOut outputs the average of the texture coordinates in the polygon under the pointing device.

Viewpoint

If a Viewpoint node has both

• jump set to FALSE, and
• a string in the description field

the user's position will change if they choose the Viewpoint from the menu in the WorldView user interface. Changes to this Viewpoint that occur via any other mechanism will not cause the user's position to change, because jump is FALSE. To avoid this behavior, prevent the Viewpoint from appearing the menu by not providing a description for it.

WorldView's Full Color Setting

There are several features in VRML that are only visible in WorldView when the Full color setting is on. Full color is off by default, but may be controlled on a per-session basis from the "Graphics" item on the right mouse button pop-up menu. The default may be changed permanently by choosing "Options..." from the right mouse button pop-up menu and changing the setting of the "Full color" check box in the Options dialog.

The Full color setting has a significant effect on navigation speed.

This list summarizes VRML 2.0 nodes that are affected when Full color is OFF:

• The color field for PointLight, DirectionalLight, and SpotLight is ignored.
• Fog does not appear.
• IndexedFaceSet vertex colors are averaged to compute face colors, if colorPerVertex is set to TRUE.
• ElevationGrid vertex colors are averaged to compute face colors, if colorPerVertex is set to TRUE.
• The color field for IndexedLineSet is ignored; the emissiveColor of the Material node is used to specify the line color.
• The color field for PointSet is ignored; vertex colors are averaged to compute face colors.

These nodes and fields are fully visible when Full color is ON.

Support for JavaScript

WorldView's JavaScript implementation conforms to the JavaScript specification included in Annex C of the ISO/IEC DIS 14772-1 VRML 2.0 specification, dated 4 April 1997.

JavaScript and the VRML Console

Javascript trace statements are routed to WorldView's VRML Console. (Select "Show VRML Console" from the right-button Help menu.)

Variable Scoping

Variables declared with the var keyword are local to the function in which they are declared. Variables not declared with the var keyword are global to the Script node in which they are used and are visible in all functions of the Script node, but not in functions of other script nodes. Script node fields and events are in the same name space as global variables.

Type Conversion in JavaScript Expressions

JavaScript automatically converts between data types when necessary while evaluating expressions. The following table describes how WorldView 2.0's JavaScript implementation performs conversion from each data type to each other data type.

Find the source data type in the leftmost column, then find the cell in that row whose column corresponds to the destination data type. "NS" indicates that the conversion is currently not supported by WorldView. Conversion of any non-object into an object is not supported.

Support for the Java EAI

The Java EAI is now fully supported according to the Proposal for a VRML 2.0 Informative Annex dated 21 January 1997. It is believed compatible with the EAI classes from other browsers.

WorldView uses the vrml.external.* naming convention, not the old vrml.* naming convention.

Requirements for Internet Explorer

To access the Java EAI with WorldView for Internet Explorer, a Java applet must be considered a "trusted applet." This can be done in two ways:

• Place the applet in a digitally signed cabinet file. This can be done using the CabDevKit provided with the Microsoft Java SDK. The Microsoft Web site contains additional information on using signed CAB files to distribute EAI applets.
• Put the applet's class files in your CLASSPATH environment variable. This is useful for development purposes. Microsoft Visual J++ does this automatically when debugging.

The following example demonstrates using WorldView's Java EAI in Microsoft Internet Explorer. The VBScript methods "window_onLoad" and "window_onUnLoad" are required to initialize applets that use the Java EAI. These methods are not required for Netscape Navigator.

*********************************************************
*********************************************************
HTML FILE:

<HTML>
<HEAD>
<TITLE>WorldView ActiveX Control Example</TITLE>
</HEAD>
<BODY>

<CENTER>
<HR>

<APPLET name=MyApplet code=MyApplet.class width=700 height=140 MAYSCRIPT>
<!-- for CAB users -->
<PARAM NAME="cabbase" VALUE="SmartConnectors.cab">

</applet>
</CENTER>

<HR>
<CENTER>
<OBJECT ID="WorldView" CLASSID="clsid:b0d7d800-4ebf-11d0-9490-00a02494d8a5"
HEIGHT=400 WIDTH=500>
<PARAM NAME="World" VALUE="MyWorld.wrl">
</OBJECT>
</CENTER>

<SCRIPT language="VBScript">
<!--
sub window_onLoad
document.MyApplet.SetControl WorldView
end sub
sub window_onUnLoad
document.MyApplet.FreeControls
end sub
-->
</SCRIPT>

</BODY>
</HTML>


*************************************************
*************************************************
JAVA FILE:

import java.applet.Applet;
import vrml.external.*;


/***********************************************/
public class MyClasses extends Applet {

public void SetControl(Object oc)
{
WorldViewControl.SetControl(oc, this);
InitVrml(); // NOW do the vrml stuff
}
public void FreeControls()
{
WorldViewControl.FreeControls();
}

public void init()
{

setLayout(new FlowLayout());
add(new Button("My Button"));
// other awt stuff etc...
// NO VRML STUFF! SetControl HAS NOT BEEN CALLED YET!
// BROWSER API WON'T WORK!
}

public void InitVrml()
{
Browser browser = Browser.getBrowser(this);
Node node = browser.getNode();
// etc...
}

public void run() {}

// Other Methods ..
}

Support for Java in Script Nodes

The Java in Script nodes implementation is according to Annex B of the ISO/IEC DIS 14772-1 VRML 2.0 specification, dated 4 April 1997.

System.out and System.err

Java's System.out and System.err streams are routed to the WorldView VRML Console. (Select "Show VRML Console" from the right-button Help menu.)

Security

For Java in Script nodes, WorldView provides an environment similar to Netscape or Internet Explorer for running Java code. Script nodes have the following restrictions, which are similar to Java applets:

• Scripts cannot read, write or delete files
• Scripts cannot execute programs (i.e. Runtime.exec)
• Scripts cannot create ServerSockets
• Scripts cannot link to native code (i.e. System.loadLibrary)
• Scripts cannot create ClassLoaders
• Scripts may bring up AWT top-level windows
• Scripts may make socket connections only to their host of origin.

Java classes loaded from the CLASSPATH are considered 'trusted code' and can perform operations ordinarily not allowed by the security manager, such as reading/writing files and making access to any network host.

Using the EMBED tag in HTML documents

You may use the HTML EMBED tag to specify user interface settings that will be used in WorldView when a VRML world is embedded in an HTML document. The following tags are supported: