Spotlight BACKContentsNext
Introduction to LiveConnect & Live3D
by Adrian Scott
This article first appeared in Java Report Magazine.

LiveConnect is Netscape's new architecture for communicating between Java applets, JavaScript functions and Netscape Plug-ins. LiveConnect is included in Netscape Navigator 3.0. This new functionality lets you create Java applets that start playing MIDI files embedded in an HTML page, move objects in 3-D VRML worlds with Java applets or JavaScript functions, use cookies in Java applets and more. In this article, we'll work through several examples using LiveConnect from JavaScript.

If you try these examples and they don't work, you may need to make the following adjustment. Unix and Windows users should set the environment variable NS_ENABLE_MOJA=1. Macintosh users should edit the Navigator resources by adding the resource type 'MOJA' with ID 128. (I haven't had this trouble, but I've read that this may occur.)

Note that you will need Netscape 3.0 to be able to use these examples.

Accessing an Applet from JavaScript

With LiveConnect, you can use JavaScript to call public methods in a Java applet. To do this, you first name the applet with a name field in the <APPLET> tag, and then use JavaScript functions like "document.appletname.methodname();". If you don't name the applet, you can still access the applets with the new applets[] array of the document object in JavaScript. Similarly, for plug-ins there is an embeds[] array. As arrays, both applets[] and embeds[] have the property length.

Example 1: Starting and Stopping an Animation

For starters, let's take Sun's infamous Animator applet, and add some HTML form buttons to control it. In this example, you can go to the java/demo/Animator directory of the Java Developer's Kit, and copy example1.html to a new filename. We'll make two changes to the HTML, adding in "name=animator" inside the <APPLET> tag, and adding a form with buttons to activate the LiveConnect control of the applet.

The form contains two buttons, each with an onclick field. The first button, named "start", will call the start() method of the Animator class using the syntax "document.animator.start()". (Remember that animator is the name of this applet property of the document object.) Similarly, the second button calls the stop() method, with a button which has the onclick field value of "document.animator.stop()".

Listing 1:

<html>
<head>
<title>The Animator Applet - example 1</title>
<!-- Changed by: Herb Jellinek, 18-Apr-1996 -->
</head>

<body>

<hr>

<applet name="animator" code=Animator.class width=460 height=160>
<param name=imagesource value="images/Beans">
<param name=backgroundcolor value="0xc0c0c0">
<param name=endimage value=10>
<param name=soundsource value="audio">
<param name=soundtrack value=spacemusic.au>
<param name=sounds value="1.au|2.au|3.au|4.au|5.au|6.au|7.au|8.au|9.au|0.au">
<param name=pause value=200>
</applet>

<form name="form1">
<input type=button value="start" onclick="document.animator.start()">
<input type=button value="stop" onclick="document.animator.stop()">
</form>
	
<hr>
<a href="Animator.java">The source.</a>
</body>
</html>
The new version of example1.html is given in Listing 1. Once you've typed it in and saved it, try clicking on the buttons and see what happens. If you look at the source of the Animator applet, you'll be reminded that the start() and stop() methods control the thread that drives the animation. Since both of these methods are public, we can access them from JavaScript.

Accessing a Plug-In from JavaScript

Next we'll look at how to communicate requests to Netscape Navigator plug-ins, such as LiveAudio, LiveVideo and Live3D. We can name the instances of the plug ins inside the <EMBED> tag, or else use the embeds[] array of the document object in JavaScript.

Here is a list of methods that can be used with LiveAudio and LiveVideo. I've had some difficulty with LiveAudio and LiveVideo. When I tried referring to the instance of LiveAudio with a name field in the <EMBED> tag, it didn't work. However, when I referenced the audio file using the embeds[] array, it worked fine. There is an example of this at the small Aereal LiveConnect Page.

LiveAudio and LiveVideo LiveConnect methods

LiveAudio LiveVideo
play() plays audio from current position plays video from current frame
stop() stops audio; rewinds to beginning stops video
rewind() rewinds audio to beginning rewinds video to beginning
seek(x) sets current position to time x (in seconds) frame number x sets current video frame to frame number x
file formats supported AIFF, AU, WAV, MIDI AVI
Note: frame refers to the position in the video file, not a document frame.

Live3D's LiveConnect API

We'll use Live3D, Netscape's VRML plug-in, to show how plug-ins can be accessed from JavaScript with LiveConnect. VRML is Virtual Reality Modeling Language, the open standard for virtual reality on the Internet. Netscape purchased Paper Software Inc., the developer of the WebFX VRML plug-in, and incorporated Paper's team into Netscape as the Live3D team. Netscape has published an initial specification for the Live3D LiveConnect API, available at http://www.paperinc.com/plugapi. The specification gives information on which parts of the API are currently implemented. You may need to download the latest version of Live3D to get LiveConnect to work with it. Refer to http://www.netscape.com/eng/live3d or ftp://www.paperinc.com for the latest version. The API lets you make all sorts of changes to VRML worlds, giving you the ability to add movement and simple interactivity to LiveConnected VRML 1.0 worlds.

Example 2: Changing the Background Color of a VRML World

As a simple example of Live3D and LiveConnect, we'll change the background color of the VRML world. To make things more sophisticated than previous examples, we'll let you type in the color values for the background in a form, and then use a button to update the VRML world. In VRML, colors are given by three numbers which represent the amount of red, green and blue in the color. The numbers can have values between 0 and 1. If you are used to color values between 0 and 255, just divide by 255.

As before, we add a name field to the <EMBED> tag in the HTML, naming it "vrmlworld". Then we add a form named "form1" which has inputs for red, green and blue, plus a button that updates the VRML world using LiveConnect. The onclick value of the button will use the L3DPlugin object's setBackgroundColor() method and also JavaScript's parseFloat() method to turn the color input values into floats that the setBackgroundColor() method can read. The final HTML and JavaScript is given in Listing 2, and there is a screen shot in Figure 1.

Figure 1

Listing 2

<html>
<head>
<title>
Aereal Live3d LiveConnect Color Change
</title>
</head>
<body bgcolor="#FFFFFF">

<p>
<embed name="vrmlworld" src="http://www.aereal.com/home.wrl.gz" height=300 width=400>


<form name="form1">
red:<input type="text" size="4" name="red" value="1">

green:<input type="text" size="4" name="green" value="1">

blue:<input type="text" size="4" name="blue" value="0">



<p>

<input type="button" value="change background color" 
   onclick="document.vrmlworld.setBackgroundColor(
	parseFloat(document.form1.red.value),
	parseFloat(document.form1.green.value),
	parseFloat(document.form1.blue.value))">


<p>
<p>

</form>

</body>
</html>

Example 3: Scaling an Object in a VRML World

Example 2 used one of the methods associated with the L3DPlugin object. In addition there is another set of methods available for use on L3DObject objects inside the world. In this example, we use the scale() method to change the size of a sphere. Similarly you can use the rotate() and translate() methods to rotate or move an object. But before you can use the L3DObject methods, you need a reference to a L3DObject. You can get this by using the L3DPlugin getObject() method and supplying a String with the name of the VRML object. The name of the VRML object is the name given to the object using "DEF" in the VRML source.

Listing 3: bubble.wrl

#VRML V1.0 ascii
Separator {

	DEF BackgroundColor Info { string "1 1 1" }
	PerspectiveCamera { position 0 0 5 }
      Material { diffuseColor .7 0 0 }

	DEF Bubble Sphere { radius .4 }

	Material { diffuseColor 0 .7 0 }
	Cube { width .1 height 15 depth .1 }
	Cube { width .1 height .1 depth 15 }
	Cube { width 15 height .1 depth .1 }
}
The VRML Source for "bubble.wrl" is given in Listing 3, and the HTML Source is given in Listing 4. In the VRML file, the name of the Sphere is Bubble, so we supply the string "Bubble" to L3DPlugin's getObject() method, and then apply the scale() method to the resulting L3DObject. The scale method takes five arguments. The first three arguments are floats representing the amount of scaling to apply to the x, y, and z coordinates. The fourth number, 2, indicates that the newly scaled object will replace the previous version. The final number, 1, indicates that the scaling is only to be applied locally to this sphere.

Listing 4

<html>
<head>
<title>
Aereal Live3D Object Scaling
</title>
</head>

<body bgcolor="#FFFFFF">

<h1>
Aereal Live3D Object Scaling
</h1>

<embed name=bubble src=bubble.wrl height=300 width=400>

<form>

<input type=button value="scale up" 
onclick="document.bubble.getObject('Bubble').scale(10,3,3,2,1)">
</form>

</body>
</html>
Figures 2 and 3 show the VRML World before and after the "scale up" button is pressed.

Figure 2: Before Figure 3: After

With LiveConnect, Netscape is breaking down the barriers between different media and data types. In the future we can expect to see JavaScript in VRML, Java applets textured onto 3D objects in VRML worlds, and more!


Adrian Scott (adrian@aereal.com), is founder and CEO of Aereal Inc. (http://www.aereal.com), a leading Java/VRML company. He is a co-author or contributing author to five Internet books, Editor of SIGS' Java Professional Book Series, and keeper of the VRML/Java/JavaScript FAQ.

Relevant URLs:

BACKContentsNext
© 1996 Aereal, Inc. Please send suggestions to suggest@vrmlsite.com.