Contact 4.2

Release Notes

Updated 9 July 1999 - Holger Grahn




Introduction

This document provides information about the new features and improvements in the 4.0 and 4.1 releases of Contact. It also describes some known limitations and difficulties.








New Features (Version 4.1)

NURBS Technology

As part of our development efforts for Pentium III support, we have implemented NURBS technology in BS Contact 4.1. With NURBS, complex 3D curves can be represented with a minimum of data, allowing a new level of visual display and animation quality for Internet-delivered 3D graphics.

To learn about Contact's NURBS development, including NURBS-related settings in BS Contact, sample content, project results and our proposed NURBS extension for VRML97, see the NURBS project overview and the VRML NURBS proposal.

Intel Pentium III ISSE Instruction support

System Requirements

To take advantage of BS Contact's Pentium III support, you'll need a Pentium III PC running Windows 95/98 and Microsoft DirectX 6 or higher. You'll also need Microsoft Internet Explorer (version 3 or higher) or Netscape Navigator (version 3 or higher). Graphics cards with Intel i740, Matrox G200 or Riva TNT are recommended; best results can be seen with the latter.

Settings

The Pentium III acceleration works best with the DirectX HAL driver, but can be also used with the "high-quality" RGB emulation driver.

Edit the settings in the Preferences dialog. To get there, right-click in the 3D window of BS Contact, then select Settings and Preferences. Or simply press Ctrl-F9. The settings of interest for Pentium III acceleration are described below; these settings can be made in the "Direct3D - more options" and "General" tabs.

Direct3D - more options
You can make the following settings:
Software-Lighting enables the software lighting, disabling the Direct3D lighting, i.e. BS Contact computes lighting using the VRML specification's formulas. Only in this mode the Pentium III acceleration can be used by checking the "Use Pentium III instructions" box. Enabling the "Use Direct3D Culling" option gives a further performance boost if your graphics board supports this feature.

General
You can make the following settings in the General tab:

Enable the "run fullspeed setting" and in the DirectX section the HAL Driver.

Enabling "dither" and "smooth textures" usually yields a better visual appearance and shouldn't cause a reduction of frame rate with today's graphics boards. Generally, we recommend a high setting, e.g. 150, for "Amount of disk space to use" (set in "Cache Settings").

Some advanced features can only be set directly in the registry:

Direct3D.dxlevel - number (3 for Direct X 3, 5 for Direct X 5, 6 for Direct X 6, default 0)

Direct3D.maxverts - maximum number of vertices passed in a block to Direct3D (default setting is 1020)

Implemented ISSE (Katmai) Support

Transform and Lighting as well as matrix operations are done with the ISSEi New Instruction set The VRML light model has been implemented. Supported lights are DirectionalLight, PointLight and SpotLight. The number of lights is limited to 64.

The performance gain depends enormously on the VRML scene. In scenes with a low number of polygons where transform and lighting require only a marginal amount of computation time, the acceleration of these computations can't result in an appreciable boost in system performance. However, the KNI can speed up BS Contact by as much as 50% if the CPU gets a heavy load.

"Ideal" VRML Content

Ideal content should contain larger meshes with full vertex sharing. Full vertex sharing can be achieved by setting the following fields in an IndexedFaceSet node:

creaseAngle 3.14
coordIndex ...    as usual with coordinates referenced several times
coord Coordinate {... }

(optional)

texCoord
normal

(With the other fields at their defaults, ie. normalPerVertex TRUE )

As soon as a node contains normalIndex / texCoordIndex / colorIndex  or the default creaseAngle 0, sharing can get lost because each separate instance of the tuple (colorIndex, normalIndex, texCoordIndex, colorIndex) forms an internal vertex.
There is no limit on the number of vertices.

Two-sided lighting has been implemented (solid FALSE flag in IndexedFaceSet). Of course this setting affects performance, because no backface culling can be applied and the vertex normals are oriented toward the viewer for correct lighting.
 

Known Limitations

The following aspects of lighting are currently not implemented :


With small datasets and depending on the graphics driver, frame rate will not increase over some limit like 100 FPS using the i740 because the display.drv waits for display sync. This problem doesn't occur with the Matrox G200.

Using the Intel PIII-optimized Microsoft DirectX 6.1 release, we have seen some speed-up using the standard Direct3D transform/light code path in BS Contact.



Raw Mouse & Keyboard input

Beginning with Contact 4.1, raw mouse and keyboard input can be intercepted from javascript or an EAI eventOutObserver.

Events are reported via an SFNode Event node.

   
Event
{
    
           eventOut SFString               type
           eventOut SFBool                 cancelBubble
           eventOut SFBool                 returnValue
           
           eventOut SFVec2f                screen
           eventOut SFVec2f 		   client
           eventOut SFVec2f 		   position


           eventOut SFBool		   altKey
           eventOut SFBool                 ctrlKey
           eventOut SFBool                 shiftKey
           eventOut SFInt32                keyCode

           eventOut SFInt32                button
           
}

Attributes
type
The type property represents the event name as a string property.
cancelBubble
The cancelBubble property is used to control the bubbling phase of event flow. If the property is set to true, the event will cease bubbling at the current level. If the property is set to false, the event will bubble up to its parent. The default value of this property is determined by the event type.
returnValue
If an event is cancellable, the returnValue property is checked by the DOM implementation after the event has been processed by its event handlers. If the returnValue is false, the DOM implementation does not execute any default actions associated with the event.
screen
screen.x indicates the horizontal coordinate at which the event occurred relative to the origin of the screen coordinate system. screen.y indicates the vertical coordinate at which the event occurred relative to the origin of the screen coordinate system.
client
client.x indicates the horizontal coordinate at which the event occurred relative to the DOM implementation's client area.
client.y indicates the vertical coordinate at which the event occurred relative to the DOM implementation's client area.
position
position.x indicates the horizontal coordinate at which the event occurred relative to the DOM implementation's normalized client area.
position.y indicates the vertical coordinate at which the event occurred relative to the DOM implementation's normalized client area.
 
altKey
altKey indicates whether the 'Alt' key was depressed during the firing of the event.
ctrlKey
ctrlKey indicates whether the 'Ctrl' key was depressed during the firing of the event.
shiftKey
shiftKey indicates whether the shift key was depressed during the firing of the event.
keyCode
The value of keyCode holds the virtual key code value of the key which was depressed if the event is a key event. Otherwise, the value is zero. Currently the raw Win32 keycode is reported.
button
During mouse events caused by the depression or release of a mouse button, button is used to indicate which mouse button changed state. This is a bitmask with the values 1 for left button, 2 for right and 4 for middle. During a buttonup event, the mask of the button causing the event is reported.

This extension is modeled after the W3C DOM Events.

Event types
click
The click event occurs when the pointing device button is clicked over an element. This attribute may be used with most elements.
dblclick
The dblclick event occurs when the pointing device button is double-clicked over an element. This attribute may be used with most elements.
mousedown
The mousedown event occurs when the pointing device button is pressed over an element.
mouseup
The mouseup event occurs when the pointing device button is released over an element.
mouseover
The mouseover event occurs when the pointing device is moved onto an element.
mousemove
The mousemove event occurs when the pointing device is moved while it is over an element.
mouseout
The mouseout event occurs when the pointing device is moved away from an element.
keypress
The keypress event occurs when a key is pressed and released.
keydown
The keydown event occurs when a key is pressed down.
keyup
The keyup event occurs when a key is released.
resize
The resize event occurs when a document is resized.

 

Setting an observer requires the addition of a route or an eventOutObserver to the browser's SFNode eventOut event_changed. This is a code fragment for adding the event observer:

function initialize() {
	// tell what events 
	m=Browser.eventMask; 
	oldMask=m;    
	m = m | (1<<4) | 1; // mouse up & down 
	Browser.eventMask = m;    
	// add event observer 
	Browser.addRoute(Browser,'event_changed',inputHandler,'onEvent');    
}

The following are the supported mask values:

mousedown = 1
mousemove = 1<<1
mouseout = 1<<2
mouseover = 1<<3
mouseup = 1<<4
keydown = 1<<5
keyup = 1<<6
keypress = 1<<7
click = 1<<8,
dblclick = 1<<9


This is a code fragment for the event callback handler:

DEF inputHandler Script { 
eventIn SFNode onEvent 
url "javascript: 
function    onEvent(e,t) { 
if (e.type == 'mousemove' && e.button == 0) {
	 return; // to    many prints 
} 

print('Event type='+e.type+' at='+t); 
print(' button='+e.button+'    shiftKey='+e.shiftKey+' ctrlKey='+e.ctrlKey+' altKey='+e.altKey); 
print(' position='+e.position+'    keyCode='+e.keyCode+' ctrlKey='+e.ctrlKey+' altKey='+e.altKey); 

if (e.type ==    'mouseup' && e.button == 2) { // test we want to handle rbutton menu 
	e.returnValue    = 0; 
} 
} " 
} 

All input event properties are reported using only one Event node. The default Browser eventHandling for that event can be turned off by setting the returnValue to 0. The event types keypress, click, mouseover, and mouseout are currently not supported.

Test Example: Mouse / Keyboard Input Test

 

Support for javascript-based vertex animation

In order to support full-body mesh animation for avatars, BS Contact supports an arithmetic helper function for javascript. Instead of animating a nested hierarchy of transform nodes, a nested hierarchy of vertices of a Coordinate node can be animated. This results in smoother, more realistic avatar motions and avoids rendering artifacts at joints. The API function setByVertexTransform is described in the Extensions section.



Universal Media URN Support

BS Contact uses URNs (Uniform Resource Names) to reference media elements such as textures, sounds and objects according to a mechanism proposed by the Universal Media Working Group. Details of the proposal can be found here.


New Features (Version 4.0)

Caching

In addition to HTML browser caching, BS Contact supports a mechanism to cache VRML files and referenced media such as textures, sounds and movies on the local hard disk. Caching is controlled by the "Caching" and "Cache Settings" tabs in the Preferences dialog of BS Contact (press Ctrl-F9).

With the default Setting "Verify once per session", VRML files are retrieved using the HTML browser's functions. All files retrieved by BS Contact are written to the cache with the server timestamp. The next time the files are needed, the current VRML server file date is compared with the VRML cache file timestamp. If the dates are identical, all referenced media files are read directly from the cache without further HTTP requests. This greatly improves loading performance if the world is revisited frequently.

If an author modifies an individual texture, the referring VRML file should also be touched in order to be refreshed by BS Contact. Media placed in locations containing "/cgi-bin" or "/no-cache" in the URL are retrieved each time.

The lastModified Date for an URL from the HTTP server is set as the creation time for the cache file; the modified date is the timestamp of last retrieval or cache storage. Applications can install VRML content directly to the Contact 3D cache, or can add a directory to the list of read-only directories. The cache is automatically cleaned from time to time.

 

Transparency handling

Transparency is supported in the following forms :
Direct3D software drivers: stippled alpha (simulated alpha transparency via pixel pattern), with DirectX 6 some support
OpenGL, Direct3D hardware: blended alpha transparency, some boards implement dithered alpha only
Shape nodes with a fully transparent material are not drawn.

Transparent shapes are rendered after opaque objects, in order of the distance of their bounding boxes from the viewer. Currently a minor limitation is that transparent shapes are affected by global lights and top-level directional lights, but not by local directional lights. Shapes are sorted with respect to the distance of the bounding box to the viewer. In some configurations this results in unexpected rendering results. It is recommend to break up transparent objects in smaller parts, so that a better sort and drawing order can be achieved.

A transparent color index in GIF Textures or GIF MovieTexture is fully supported in all drivers. Support for textures with an alpha channel is driver-dependent: OpenGL, most Direct3D hardware drivers and the Direct3D RGB emulation driver support alpha formats;  the Direct3D Ramp and MMX driver do not.

Lighting

Lighting in version 4.0 is more compatible between OpenGL and Direct3D (RGB or hardware mode). The range parameter in light sources is ignored. OpenGL has a limit on the number of simultaneously active light sources. Ambient light in Direct3D is a global property and derived from the ambientIntensity of the light sources.

Third-Person Viewing Mode

In third-person viewing mode, the user's avatar is displayed at the viewing position; the "rendering camera" displays an image from a new viewing position behind the avatar. The 'A' key  or the context menu option "View my Avatar"  toggles third-person viewing mode. The following keys (on the main keyboard, not the numeric keypad) control movement of the camera:

Contact retrieves the avatar definition (e.g. VRML file, VRML URL) from one of the following places: The first node of the VRML file can be an instance of a PROTO supporting some or all of the blaxxun avatar interface elements. (See blaxxun World and Avatar authoring.)

VRML viewpoints, navigation, ProximitySensors etc. are all relative to the position of the avatar, not to the third-person mode's camera.

The avatar VRML implementation can support certain animations on browser events like moving to a new position, begin/end of navigation action, world entering event.

The VRML ProximitySensor will report positions relative to the avatar position, not relative to the rendering camera. "Misuses" of the ProximitySensor as a helper to implement HUD displays will currently position the HUD in front of the avatar. For this reason an extra HUD node has been implemented as helper node.

Navigation Panel

The navigation panel gives access to the walk navigation mode, viewpoint selection function and a slide function. The panel visibility can be toggled in the menu and in the Preferences dialog or via the embed / object parameter VRML-DASHBOARD=FALSE in the HTML page.

On some OpenGL display systems, display of the navigation panel reduces rendering performance.

Culling

Geometry objects are tested for visibility against the view frustrum. If the author specifies a bboxSize>=0 at a Group node level, a bounding box culling check is done for rendering, selection, terrain following and collision detection. Wrong bounding box values will result in wrong calculations, BS Contact currently does not update or re-compute the bounding boxes. The CullGroup Group extension node automatically computes internally a bounding box for the children scene graph.

Collision Detection and Terrain Following

New in version 4.0 is a geometric collision detection based on a box around the old and new avatar positions, and the scene graph geometry. The collision box is computed from the NavigationInfo collision distance, avatar height, and step-over height. In the third-person mode these values are computed from the bounding box of the avatar geometry and can also be specified in the avatar prototype interface. The collision detection algorithm is very fast, but needs some additional one-time preprocessing and memory the first time the avatar approaches the object. Ground detection is done by firing a ray towards ground.



Tips, Known Problems and Workarounds

 



Direct3D Notes

BS Contact is optimized for the Microsoft Direct3D immediate mode rendering engine. Support includes DirectX 3, DirectX 5, DirectX 6, DirectSound, Direct3D Sound and DirectShow. Using low-cost Direct3D accelerator cards, exceptional VRML 3D speed and quality could be achieved. The DirectX interfaces are very close to the hardware, graphics boards and drivers are quickly evolving.

Windows 98 comes with DirectX 5 pre-installed.
Windows NT 5 Beta 2 supports DirectX 5 including hardware driver support.
Windows NT 4 with Service Pack 3 installed supports DirectX 3 (but without hardware driver support).
Windows NT 4 without Service Pack 3 does not support Direct3D, only OpenGL.

In general, OpenGL software rendering runs faster on Windows NT than on Windows 95/98.

There are different Direct3D drivers available; features may vary and some drivers may not supply all rendering capabilities described in the VRML lighting model.

Hardware

Direct3D hardware is installed if there is a checkmark next to the "Hardware" entry in the popup menu. BS Contact will also prompt for the use of a hardware device. If hardware works with your current desktop and graphics card configuration, it can be made the default setting by selecting it in the Direct3D tab of the Preferences dialog: press Ctrl-F9 or right-click in the 3D window, select Settings, then Preferences and, in the Direct3D tab, select "Hardware" in the Direct3D Driver drop-down box.

For a 16-bit desktop setting, enabling the Dither option in the Direct3D tab will usually improve display quality; for maximum speed, the "High speed" setting in the General tab needs to be enabled.

Most accelerators today support 3D only in a 16-bit (32000 or 65000) color setting. With this setting, the Windows dialog Settings->Control Panel->Display->Settings->Color palette would display "High Color (16-Bit)."

Mip-mapping can be activated by checking the "Mip Mapping" option in the Direct3D tab; after a resize or a reload, the hardware will automatically switch between different scaled-down versions of a texture (the mip-levels), making textures flicker less.

Trilinear mip-mapping can be enabled by selecting the settings "Smooth Textures" and "Mip Mapping". For a given pixel, the hardware first interpolates two color values in each of the two selected mip-levels and then interpolates between the two.

Newer graphics boards (e.g. those based on the Riva TNT chipset) support sort-independent scene antialiasing. This can increase visual quality along sharp edges of geometry and text.

Software Drivers

The speed of software rendering depends on the size of the rendering window and the CPU speed.

Microsoft Direct3D Ramp Emulation Driver (Setting "High Speed")

This driver is optimized for speed, not for quality. Limitations:

Microsoft Direct3D RGB Emulation Driver (Setting "High Speed")

The Driver is optimized for quality not for speed; beginning with DirectX 6, there are many quality improvements and code paths for different CPU types.

Microsoft Direct3D MMX-Emulation driver (Setting "MMX Speed")

Limitation: internally supports only 8-Bit palette Textures, BS Contact needs to reduce all textures.

Enabling the Direct3D rendering options Dither, Mip Mapping, Smooth Textures and Anti Alias will have a negative impact on rendering speed of software drivers.

Limitations for all other Microsoft Direct3D Drivers

Specific Direct3D Hardware Driver Limitations

Some hardware drivers are have limitations depending on type of chip set or version of the driver. In general, color per face, geometry shapes with more then 1024 vertices are getting inefficient, especially if animated. Because in the current implementation information is cached at the geometry level, it is currently not possible to animate a given shape from an unlit to a lit state.
The following settings make a shape unlit:

 

Tips for Using Direct3D Hardware Acceleration

Successful use of Direct3D hardware acceleration is directly related to the graphics card's memory, current screen mode, and size of the 3D window. Using low-resolution screen modes like 640*480*32K colors leaves more memory available for 3D buffers and textures. If Direct3D can't use the hardware because of too high memory requirements, BS Contact falls back to the Direct3D ramp software driver.

(Typical BS Contact error messages: "Create Surface for Z-Buffer failed" or "Create Surface for Window BackBuffer failed")

Recommended display settings for hardware use (Hardware == Direct3D HAL Driver):

As a rule of thumb, the required graphics board memory can be computed as

(pixel width of desktop * pixel height of desktop * 2)
+
(pixel width of 3D window * pixel height of 3D window * 2) *2

+ size of used textures in VRML scene  (for non AGP boards)

(2 Bytes per pixel for a 16 bit color setting, a window backbuffer and a z-buffer need to be allocated)

If Direct3D hardware runs out of texture memory for storing all the textures, BS Contact automatically reduces texture bit formats and scales down textures, resulting in a "blockier" appearance of the images. More elegant solutions include switching to software rendering for a scene, releasing some memory on the graphics board by using a smaller window or lower desktop resolution, or upgrading to a graphics board with more memory (8 MB, 16 MB) or an AGP-based system.

Another issue is the number of different texture pixel formats a board supports and whether it only supports square textures. For example, for a board supporting only square texture formats, BS Contact scales up non-square textures. With a board that does not support palette 8 textures, BS Contact needs to expand GIF textures to a RGB format. Detailed information of a board's capabilities is provided by the DXView program part of the DirectX SDK.

On systems equipped with Intel AGP and a Direct3D AGP graphics board, much more texture memory is available. The amount of video memory is displayed in the Direct3D settings tab. This number should be much larger then the memory on the graphics board, otherwise the AGP support is not properly set up. On older Win95 systems, AGP support can be installed using the usbsup Windows update.

The default Direct3D start configuration can be specified in the "Settings->Preferences" dialog. Direct3D drivers evolve quickly, so it's a good idea to check the board vendor's website for graphics driver updates. Information about the installed driver version is available in the Windows Control Panel, Icon DirectX -> DirectDraw > Installed Drivers.

Running software modes on hardware is slow, and requires you to turn off the option "Use Video Memory" in the Direct3D settings tab of BS Contact. Rendering is then performed in the PC's main memory.

Preliminary support for Direct3D full-screen rendering is available. Ideally the VRML world should be displayed full-screen in the HTML browser with menu, tool and status bars disabled. Pressing F5 will toggle between full-screen and window mode. The full-screen display mode can be selected from the Direct3D Fullscreen Mode drop-down box in the Direct3D settings tab; the default is 640x480x16.

If there are display problems, try downloading an updated DirectX driver from the graphics board vendor's website. The drivers shipped with graphics boards are often out of date.

On systems equipped with an MMX CPU, the DirectX 3 "RGB Emulation Driver" provides MMX-specific acceleration. With DirectX 5 there is a separate "MMX speed" Direct3D driver. With DirectX 6 the "RGB Emulation Driver" automatically uses MMX specific codepaths.

Secondary Direct3D boards (3Dfx Voodoo and Voodoo2 etc.) which can only render full-screen and not inside a window are currently not supported.

 

Media Issues

Sound Support

BS Contact supports two different sound subsystems, Intel RSX 3D Sound and Microsoft DirectSound.

Intel RSX 3D Sound
This sound system provides high-quality spatialized sound and does not require the presence of Microsoft DirectX. WAV and MIDI file formats are supported, only one MIDI  sound can play at a time.

Microsoft DirectSound
DirectX provides basic sound support, DirectX 5 adds sound spatialization via Direct3D sound. DirectSound depends on up-to-date sound drivers for the sound card. Currently only uncompressed PCM WAV file formats are supported; sound files can be gzip compressed.

Sound system configuration is done using the Sound tab in the Preferences dialog.

Real Player G2 Streaming Video & Sound

If RealPlayer G2 / RealPlayer Plus G2 is installed, RealAudio and RealVideo media are supported. The URL information is passed directly to the Real G2 subsystem and is played streamed.

The URL protocols pnm:// and rtsp:// are treated as Real Media URLs.

If the URL starts with the URN urn:inet:blaxxun.com:rma: then the string after the URN gets passed to Real G2 as URL. This allows media types to be passed to Real G2 instead of DirectShow.

If the URL starts with the URN urn:inet:blaxxun.com:rma_cached: then the string after the URN is treated as a normal HTTP/FTP URL and the URL is downloaded first to the local hard disk and then passed to Real G2. This method is advised if media are to be played several times or looped in order to avoid looped network streaming.

Sound is decoded and played by RealPlayer G2, so no spatialization or mixing with VRML sounds is supported. Only one Real G2 stream can play and parallel usage of Real Player is currentlly not working. No Real status message are displayed, usually the media starts playing after a while, once the the buffering phase is completed.

In oder to synchronize animations with streamed content, MovieTexture node is extended with an eventOut SFTime mediaTime, where mediaTime reports the G2 current play position time information. Monitoring this event could be used to start animations, once the content starts playing after the buffering phase.

Test Examples:





Required Files

The following files should be present in the installation directory:

These files are optional: The following files should be present in the $(windows) directory if the Java EAI for Internet Explorer is being used: The following files should be present in the $(windows)\system or NT $(windows)\system32 directory: The following files should be present in the Netscape plug-in directory (normally \program files\netscape\navigator\program\plugins) if BS Contact is to handle VRML files in Netscape: To use a different VRML plug-in in Netscape, rename npbx3d.dll to _npbx3d.dll and rename the vrml directory below Java\classes or choose the custom installation option.

Even if the Netscape plug-in is being used, BS Contact references some DLLs which are only installed if a version of Microsoft Internet Explorer is being installed on the system.

If the installation fails, the recommended steps are:

BS Contact does not need to be installed as default VRML viewer for use with BS Contact multi-user worlds.
 



Embedding a VRML World into a Web Page

BS Contact can be registered during installation as the default player for the MIME types model/vrml and x-world/x-vrml and is associated with the filename extensions .wrl, .wrz and .vrml. The registration for the .gz file extension has been removed in version 4.0.

Internet Explorer or Netscape Navigator will open a control registered for VRML with the following EMBED tag:

<EMBED SRC="test.wrl" HEIGHT=300 WIDTH=400></EMBED>

or if the user clicks on a link to a file with the .wrl extension:

<A HREF="http://www.myserver.com/test.wrl">Show VRML world</A>

In Internet Explorer the following OBJECT tag will work:

<OBJECT TYPE="model/vrml" HEIGHT=300 WIDTH=400>

<PARAM NAME="SRC" VALUE="test.wrl">

</OBJECT>

If multiple plug-ins are available for the mime type, the BS Contact 3D control can be directly specified in the Internet Explorer OBJECT tag by using BS Contact's classid.

<OBJECT CLASSID="clsid:4B6E3013-6E45-11D0-9309-0020AFE05CC8" HEIGHT=100% WIDTH=100% ID=world>
<PARAM NAME="World" VALUE="http://www.bitmanagement.de/vrml/home/home2.wrl" >
<EMBED src="http://www.bitmanagement.de/vrml/home/home2.wrl" height="100%" width="100%">
</OBJECT>

BS Contact can be reregistered using the command

regsvr32 blaxxunCC3D.ocx

and unregistered using

regsvr32 /u blaxxunCC3D.ocx

Switching between the different versions of BS Contact or other VRML controls for IE is also possible using regsvr32, which usually resides in \windows\system.

For the Netscape Environment in addition the BS Contact Netscape plug-in DLL npbx3d.dll needs to be present in the Netscape/Navigator/Program/plugins directory. If there are already other plug-ins installed that handle the MIME type model/vrml, the corresponding DLLs need to be moved to another directory. Entering about:plugins in the URL input field of Navigator will list all currently installed plug-ins.
 
 

VRML 2.0 Compatibility

BS Contact supports  VRML 97 and VRML 1.0 for backward compatibility.

A list of known issues is in the Tips, Known Problems and Workarounds section.

Script Node

The Script Node implements VrmlScript and a JavaScript subset as defined in Annex C of the VRML97 specification and http://cosmosoftware.com/developer/moving-worlds/spec/vrmlscript.html.

Supported Script node URL strings are strings that begin with the VrmlScript identifier tag "vrmlscript:" or strings that begin with the JavaScript identifier tag "javascript:". The latter is treated internally as "vrmlscript:".

Java in the Script node is currently not supported.

VRML 2.0 EAI

BS Contact supports the VRML 2.0 external authoring interface proposal.

EAI for Microsoft Internet Explorer

The Java classes are installed in $(windows)\Java\classes\vrml. If there are problems compiling or running VRML EAI applets, remove any other VRML classes from the classpath. The classpath can be edited using regedit and editing the key HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\Classpath

EAI for Netscape Navigator / Communicator

The Java classes are installed in $(Netscape directory)\program\Java\classes\vrml. If there are problems compiling or running VRML EAI applets, remove any other VRML classes from the classpath.

EAI for C++ and other COM-capable languages

The EAI can be accessed via the COM-Interfaces defined in blaxxunCC3D.ocx and blaxxunVRML.tlb.

Some additional EAI calls like Browser.beginUpdate / endUpdate / saveWorld() are provided. Scripts running in the HTML page can directly send / retreive events to/from the scene graph, without the requirement of using an additional Java EAI applet.

For EAI developer information and sample programs see the Bitmanagement Developer EAI information.
 



BSP Tree (Binary Space Partitioning Tree)

BS Contact supports a BspTree node for optimal rendering performance of large worlds. For technical information see the Bitmanagement Developer BSP-Tree information.
 



Extensions

BS Contact supports several VRML extensions.

vrmlscript Browser object extensions

additional member functions

float getCurrentTime() - gets the computer's current system time
float getTime() - gets the browser's current simulation time
float getWorldStartTime() - gets the time the world was loaded
 

void print(string);  - print the string to the console. A typical use would be to debug scripts.

function x(value) { Browser.print(' value is '+value); }

In order to print timeStamps more easily, the following code fragment could be used:
Browser.print('Time = '+ (timeStamp - Browser.getWorldStartTime()));

For compatibility with other VRML browsers, the built-in functions print(string); and trace(string); are supported.

void setMyAvatar(node) - sets the avatar for third-person mode display

bool showMyAvatar(flag) - toggles third-person mode on/off

void setRenderMode(string) - changes rendering mode; supported values are Flat, Gouraud, Wireframe, Vertices. In addition, the OpenGL version supports Solid NonLighted BoundingBoxes.

void setNavigationMode(string) - changes navigation mode
string getNavigationMode() - gets the navigation mode (4.0)

void setCollisionDetection(flag) - changes collision detection mode
bool getCollisionDetection()
void setGravity(flag) - changes gravity, terrain following mode
bool getGravity()
void setHeadlight(flag) - changes headlight mode
bool getHeadLight() - returns current state of headlight
void setViewpointAnimation(flag) - If TRUE, viewpoint changes are animated; if FALSE, viewpoint changes are immediate.
bool getViewpointAnimation() - returns current state of viewpoint animation
void setAvatarHeight(float value) - sets the avatar height, used for computing distance of viewpoint to ground
void setCollisionDistance(float value) - changes the collision distance
float getCollisionDistance()
void setVisibilityLimit(float value) - changes visibility limit
float getVisibilityLimit()
void setWalkSpeed(float value) - changes walk speed

int getWindowSizeX() - returns the horizontal size in pixels of the rendering window
int getWindowSizeY() - returns the vertical size in pixels of the rendering window
float getWindowAspect() - get the aspect ratio (width/height) of the rendering window, useful to adjust HUD display

float getAvatarHeight()
float getStepOverSize()
float getZNear()
float getZFar()

Node   computeRayHit (SFVec3f startPoint,SFVec3f endPoint, startingNode optional)

Computes an intersection of a ray with the scene graph. Result is null if no intersection found or a PseudoNode RayHitInfo with the following information stored:
 


PROTO RayHitInfo [ 
eventOut MFNode hitPath // the chain of grouping nodes, to the geometry node intersected eventOut SFVec3f hitNormal // normal at point of intersection eventOut SFVec3f hitPoint // point of intersection in global, world coordinates eventOut SFVec2f hitTexCoord // texture coordinate at point of intersection (without any texture matrix applied) eventOut SFMatrix hitMatrix // matrix transforming shape local coordinates to world coordinates eventOut SFVec3f hitNormalLocal eventOut SFVec3f hitPointLocal // intersection point in the shape's local coordinate system eventOut MFInt32 hitInfo // vertex index information ]

Example: rayhittest.wrl Navigate so that an object is in the center of the view and click the cylinder, information on hit will be displayed in the console.

setUnloadMode(int minNotActiveInlines, float percentage factor to purge)

set strategy for purging inlines from memory:
if the number of inlines currently not rendered is greater minActiveInlines,
purge up to (number * percentage ) inlines from memory
if percentage < 0 its an absolute number of inlines to purge

example:
setUnloadMode(100,0.05)
if (more than 100 inlines are currently not rendered)
delete 5 % of the inlines not used for the longest time
 

setBspMode(order) - set bsp Traversal order
setBspLoadingMode( order) - set bsp inline Traversal order

 TRAVERSE_NORMAL 0
 TRAVERSE_BACK_TO_FRONT 1
 TRAVERSE_FRONT_TO_BACK 2
 
New in Version 4.0

getCap(what) - return browser capability information.

Example usage: adapt content to client platform, check if a certain feature like alpha blending is present.

Example: captest.wrl All available browser information is displayed in the console.

New in Version 4.1

boolean isKeyPressed(int keyCode) - determines if the virtual key determined by keyCode is down

string getWorldBaseURL() - returns the base URL of the toplevel world

string getBaseURL() - get the base URL for the script node

loadURLrel(MFString url,MFString parameters) - same as loadURL - but URL is relative to getBaseURL()

setViewpointByValue(SFVec3f position,SFRotation orientation, int mode) - set current viewpoint position to position / orientation

getViewpointByValue(SFVec3f position,SFRotation orientation, int mode) - get current viewpoint position

void setSoundEnabled(flag) - if set to false lock the usage of the sound device for this scene

flag getSoundEnabled() - returns current state of sound enabled state

The Browser object itself is a VRML node with certain events and fields. By adding ROUTEs from vrmlscript or eventOut Observers from the EAI, these events can be observed.

Access from vrmlscript: Browser.xxxx
Access from EAI: Browser.getEventIn(xxx) Browser.getEventOut(xxx)

eventIn MFNode set_myAvatarNodes - set my avatar nodes (for createVrmlFromURL callback)
eventIn SFString set_myAvatarURL - set my avatar URL
eventIn SFString set_myAvatarName - set my avatar nickname
eventIn SFBool set_showMyAvatar - toggle third-person mode
exposedField SFString myAvatarURL - current avatar URL
exposedField SFNode boundAvatar - the bound (displayed) avatar node (may contain wrapper around myAvatar)
exposedField SFNode myAvatar - node currently used as myAvatar node
exposedField SFString myAvatarName - current avatar nickname
exposedField SFVec3f followDolly - x,y,z relative translation distance for third-person viewing mode
exposedField SFVec3f followOrbit - x,y rotation value for third person viewing mode
exposedField SFVec3f followPan - x,y pan rotation value for third person viewing mode


// observable eventOuts
eventOut SFTime time_changed - the master clock


eventOut SFVec3f viewpointPosition - global viewer postion
eventOut SFRotation viewpointOrientation
eventOut SFVec2f windowSize - rendering window width height
eventOut SFFloat windowAspect - aspect ratio of rendering window


exposedField MFNode viewpoints


exposedField SFNode boundViewpoint - the current bound viewpoint (top of stack)
exposedField MFNode boundViewpointStack - the other stacked viewpoint (if any)
exposedField SFNode boundNavigationInfo - the currently bound navigation info
exposedField MFNode boundNavigationInfoStack
exposedField SFNode boundFog - the currently bound fog
exposedField MFNode boundFogStack
exposedField SFNode boundBackground - the currently bound background node
exposedField MFNode boundBackgroundStack


exposedField SFString name
exposedField SFString version
exposedField SFString worldUrl - URL of the currently loaded world (set observer to get a world changed notification)


exposedField MFNode overTouchSensors - list of TS the mouse is over
exposedField MFNode activeVisibilitySensors - list of VisibilitySensores and Occlusion nodes currently assumed to be visible


exposedField MFNode protoScenes - list of scenes with prototypes (loaded via EXTERNPROTO URL ..)

Extensions to vrmlscript SFNode object

Methods

string getType() - get the type of the node as VRML nodeType or prototype name

string getName() - get the node's DEF name if available

node copy() - creates a copy off the node (no deep copy on SFNode / MFNode fields)

fieldObject getEventIn(string eventInName) - get eventIn object of Node

boolean hasEventIn(string eventInName) - returns true if Node has an eventIn namved eventInName

fieldObject getEventOut(string eventOutName) - get eventOut object of Node

boolean hasEventOut(string eventOutName) - returns true if Node has an eventOut namved eventOutName

 

MFTime object

supports same members and methods as MFFloat object

Extensions to vrmlscript MFVec3f object

Methods:


setByVertexTransform(MFVec3f srcPoints, MFInt32 srcIndex,MFVec3f translation,MFRotation rotation,MFVec3f scale, MFRotation scaleOrientation,MFVec3f center)

This assignment function performs a series of transformations to coordinates in srcPoints and assigns the result to the object. The operation is comparable to a nested Transform scene graph used to animated a hierarichal model like an Avatar.

up to the last 5 parameters can be omitted, in order to speed up the operation

 

The operation expressed in pseudo code:

VrmlMatrix matrixStack[]; 
for(var index=0; index<srcIndex.length;index+=3) {
var level=srcIndex[index]; // get the nesting level
var startIndex=srcIndex[index+1]; // start vertex index var endIndex=srcIndex[index+2]; // end vertex index
 	// compute transformation, right most arguments could be omitted
	matrixStack[level]=m.setTransform(translation[i], rotation[i], scaleFactor[i],    scaleOrientation[i], center[i]) ;  
	if (level!=0) matrixStack[level].MultiplyRight( matrixStack[level-1]); // combine    with parent
	for(var i=startIndex;i<endIndex;i++) { 
this[i] = matrixStack[level] * srcPoints[i]; }
} 
Extensions to vrmlscript Math object 


double atan2(double dy, double dx)  - arc tangent -PI .. PI
double cosh(double x)
double sinh(double x)
double tanh(double x)
double randomGaussian()  - gaussian random number  -1 ..1

double noise(double x) - evaluates solid noise function on x

 
Controlling download
BS Contact fetches URL objects and EXTERNPROTO's  in the order encountered during scene graph traversal, in the order top to bottom of file, depth first. Currently not needed objects, because not "visible" due to a Switch, LOD or BspTree node are only retreived if they become part of the visible scene graph.

Loading of Textures in the appearance node of a shape max be delayed until the shape's geometry becomes visible.

In order to preload currently unneeded objects, ImageTexture / MovieTexture / AudioClip nodes can be directly specified as children of Groups. The ordering of the nodes with url controls the download sequencing of the assets. The Appearance / Sound node references the asset by USE.

The BspTree or BspGroup node traverses child nodes nearer to the viewer first. This would mean Inline parts nearer to the viewer are earlier loaded then further away parts. Bsp - tree Parts outside the visibilityLimit (the viewing pyramid) are not fetched. The drawback is that once a new section of the world becomes visible there is some halting due to the decoding of image texture from harddisk to video memory.

The LOD node display lower levels if the requested level is an Inline node, currently not loaded.

A common request from content developers is to have more control over Resource loading notification and unloading capabilities.

The inline nodes behaves as a group-node, the children field is exposed to access the nodes of the inline. By observing children_changed a notification is sent, once an Inline node is loaded and processed.
The additional eventOut SFBool isLoaded indicates loading success, TRUE is sent if the inline node is loaded and children are loaded, FALSE is sent if the inline node's url couldn't be retreived or there was some other problem with the data. In addition set_unload can be used to unload an Node from memory, however the application should normally use this if its shure that the node is currentlly not part of the visible node subsets (i.e. out of viewfrustrum, not in traversed scene graph etc.)

This extened Inline version is described by the following prototype :

Inline {
   field SFVec3f bboxSize -1 -1 -1
   field SFVec3f bboxCenter 0 0 0
   exposedField MFString url []
   exposedField MFNode children []
   eventIn MFNode addChildren
   eventIn MFNode removeChildren
   eventOut SFBool isLoaded

   eventIn SFBool set_unload # new in 4.1, send TRUE to unload Inline from memory
}

ImageTexture {

... standard fields

eventOut SFBool isLoaded # new in 4.1
eventIn SFBool set_unload # new in 4.1, send TRUE to unload from memory
}

This node extension is not VRML97 compatbile, so it should be used with care.
It is possible to add an proper Externproto definition or using script code checking the browser version :

EXTERNPROTO InlineEx[
   field SFVec3f bboxSize -1 -1 -1
   field SFVec3f bboxCenter 0 0 0
   exposedField MFString url []
   exposedField MFNode children []
   eventIn MFNode addChildren
   eventIn MFNode removeChildren
   eventOut SFBool isLoaded

   eventIn SFBool set_unload # new in 4.1

] ["urn:inet:bitmanagement.de:node:Inline","nodes.wrl#InlineEx"]

 

For textures one method is to use a MovieTexture and observe the duration_changed eventOut. Oberving the "last" asset, in file order can give a hint of a world completely loaded event. A new method in Version 4.1 is the additional eventOut SFBool isLoaded forImageTexture.

Extension Nodes:

Extensions nodes are native implemented EXTERNPROTO's. For VRML 97 conformance, a PROTO definition for the extension node can be added in the following way (using the MenuSensor node as an example):

EXTERNPROTO MenuSensor[
exposedField SFBool enabled
exposedField SFString title
exposedField MFInt32 choices
exposedField MFString descriptions
exposedField SFString position
eventOut SFBool isActive
eventOut SFInt32 choice ] ["urn:inet:bitmanagement.de:node:MenuSensor","http://www.bitmanagement.de/vrml/protos/nodes.wrl#MenuSensor"]

If possible most nodes have an usefull fallback implementation.

List of Nodes:

Discussed in BspTree section :


BspTree  {
 exposedField SFRotation plane 0 0 1 0  
 field SFNode front NULL
 field SFNode overlap NULL
 field SFNode back NULL
}

BspGroup { # new BS Contact 3.051
   field SFVec3f bboxSize -1 -1 -1
   field SFVec3f bboxCenter 0 0 0
   exposedField MFNode children []
   eventIn MFNode addChildren
   eventIn MFNode removeChildren
   eventOut SFNode bspTree
}

Occlusion {
   field SFVec3f bboxSize -1 -1 -1
   field SFVec3f bboxCenter 0 0 0
   exposedField SFBool enabled TRUE
   exposedField SFNode proxy NULL
   exposedField MFNode children []
   eventIn MFNode addChildren
   eventIn MFNode removeChildren
   eventOut SFBool isActive
   eventOut SFTime enterTime
   eventOut SFTime exitTime
}

Inclusion {
   field SFVec3f bboxSize -1 -1 -1
   field SFVec3f bboxCenter 0 0 0
   exposedField SFBool enabled TRUE
   exposedField SFNode proxy NULL
   exposedField MFNode children []
   eventIn MFNode addChildren
   eventIn MFNode removeChildren
   eventOut SFBool isActive
   eventOut SFTime enterTime
   eventOut SFTime exitTime
}
 

MenuSensor displays a VRML defined Menu in the BS Contact right mouse button popup menu
on activation of a menu entry, the corresponding choice value will be sent as eventOut choice
a choices value of -1 indicated a menu separator

MenuSensor {
 exposedField SFBool enabled TRUE    # TRUE menu enabled, FALSE disabled
 exposedField SFString title ""      # title for submenu entry
 exposedField MFInt32 choices []     # list of numbers
 exposedField MFString descriptions []    # description for each menu entry
 exposedField SFString position "" # "TOP" menu appears at the top of the BS Contact menu
 eventOut SFBool isActive
 eventOut SFInt32 choice             # associated choices number for user selected menu entry
}

Example : menutest.wrl

New Nodes in version 3.051

Cullgroup is a group with an automatic bounding box computation for the children scene graph. Usefull for early render culling of complex scene graphs (e.g. Avatars)

CullGroup {
   field SFVec3f bboxSize -1 -1 -1
   field SFVec3f bboxCenter 0 0 0
   exposedField MFNode children []
   eventIn MFNode addChildren
   eventIn MFNode removeChildren
}

new in 3.05

Fog2 is like fog with the additional parameter visiblityStart for linear fog

Fog2 {
 exposedField SFColor color 1 1 1
 exposedField SFString fogType "LINEAR"
 exposedField SFFloat visibilityRange 0
 exposedField SFFloat visibilityStart 0
 exposedField SFFloat density 1
 eventIn SFBool set_bind
 eventOut SFBool isBound
}
 

new in 4.00

HUD {
   field SFVec3f bboxSize -1 -1 -1
   field SFVec3f bboxCenter 0 0 0
   exposedField MFNode children []
   eventIn MFNode addChildren
   eventIn MFNode removeChildren
}

This node equivalent to a VRML HUD construct using a Transform, ProximitySensor, and Collision { collide FALSE }.
Children are displayed relativ to the viewer and not relative to the avatar position in 3rd person viewing mode.
 
 

Related links:

Developer info

BS Contact user guide

VRML 97 Specification

VRML 1.0 + 97 Specification