Tutorial

Tutorial

Example—Programming Java for Cult3D objects

The completed WhiteCube object as well as all the files used in this tutorial are available in the …\Objects\ directory located in the Cult3D Designer folder.

The Main Class

The Main class must

be public

implement the com.cult3d.Cult3DScript interface

have a public constructor with no arguments

Hera is an example of a minimal Main class
public class MinClass implements Cult3DScript 
{ 
   public MinClass()
   { } 


   // From Cult3DScript interface 
   public void cult3dDestroy() 
   { } 
}
The Cult3DDevelop.jar file

The file Cult3DDevelop.jar can be found in the same directory as the Designer executeble file.

When compiling Java files that use the packages com.cult3d and com.cult3d.world the jar-file must be in the CLASSPATH for the Java compiler.

This file is only for compiling and and should not be in the CLASSPATH for a browser when viewing a Cult3D object. If the browser finds the jar-file strange Exception could be thrown and the java code in the object could stop working correctly.

The cult3dDestory method

The method cult3dDestroy must allways be implemented by the main class since it must implement the interface Cult3DScript.

This method is called when the Cult3D object wants to tell the java code that the Cult3D object soon will stop running. This gives a programmer the possibility to clean up and stop any java Threads that have been started.

Java in the Cult3D Designer

It is possible to configure the designer so that java files can be edited and compiled directly from the Designer. This is done from the preferences dialog under the File menu.

Under the Java-tab in the preferences dialog it is possible to select editor and Java compiler to use. The Compiler optins area is used for setting parameters to the compiler.

For Suns compiler javac, the parameters could look like: -g:none -O -verbose -classpath d:\cultjava\Cult3DDevelop.jar $(name)

White Cube Java Tutorial

When creating a Cult3D object that use Java it's important to choose good names when modeling the object. Names of both objects and textures are used in Java. Names should not contain any strange or none ASCII characters.

In this tutorial we are going to use the simplest possible model, a cube.

We start with creating a new Java thread that can run in the background. This thread will rotate our cube and then wait a few microseconds in a loop.

Since we want a new thread we decleare our class like this
public class WhiteCube extends Thread implements Cult3DScript
CultObjects are represented of type com.cult3d.world.CultObject inside Java. So for our cube we need to declare a new variable.
private CultObject whitecube;
We also need a variable to hold the status of our object. Lets make it a boolean that is true while the object is runnning.
 private boolean    going = true;
Then it's time for the Constructor. The constructor is going to initialize our CultObject and then start the new thread. In the model the cube where named "Cube" so thats the name we use when creating our object.

The constructor will look like this:
 public WhiteCube()
 {
   whitecube = new CultObject("Cube");
   start();
 }
When the start method is called a new thread is started an this thread calls the run method. Our run method rotates our cube a few degrees and then waits for 100 milliseconds and then start again from the beginning. This will continue as long as the variable going have the value true.
 public void run()
 {
   do {
     whitecube.rotate( whitecube.Z, (float)(10*Math.PI/180.0));
     whitecube.rotate( whitecube.Y, (float)( 5*Math.PI/180.0));
     try {
       sleep(100);
     } catch(InterruptedException e) { }
   } while(going);
 }
As allways we also need the cult3dDestroy method. since this method is called when the object is destrying itself we use it to set our variable going to false, and by doing so telling our thread to stop looping.
 public void cult3dDestroy()
 {
   going = false;
 }
This is all thats needed to get our cube rotating from java. The final java file should look similar to this.
import com.cult3d.Cult3DScript;
import com.cult3d.world.CultObject;


public class WhiteCube extends Thread implements Cult3DScript
{
	private CultObject whitecube;
	private boolean    going = true;
	
	public WhiteCube()
	{
		whitecube   = new CultObject("Cube");
		start();
	}

	public void run()
	{
		do {
			whitecube.rotate( whitecube.Z, (float)(10*Math.PI/180.0));
			whitecube.rotate( whitecube.Y, (float)( 5*Math.PI/180.0));
			try {
				sleep(100);
			} catch(InterruptedException e) { }
	        } while(going);
	}

	public void cult3dDestroy()
	{
		going = false;
	}
}
Now compile the Java file into a class file.

Start the Designer and load in the c3d file containing the cube object.

Then open the Java Actions window via the Windows menu.

In the Java Actions window click on the add button and then find the WhiteCube.class file in the file dialog that pops up.

Then write in WhiteCube.class as the Start-up class.

Then choose Save internet file under the File menu to save the new Cult3D object.

The Cult3D object with java is finished, try to view it in a browser with a Cult3D plugin installed.

Now to make the object a little more interesting lets add some interaction with the object. Now we will make the cube change color when someone click with a mouse button on it.

First add a Texture to our model, in this case with the name 'white'.
Then add some new variables to the java file. .
 private Texture    cubetexture;
 private Image      timage;
 private int tWidth, tHeight;
The cubetexture variable represents the texture itself. timage will be used to paint our new color on and then we paint the image on the texture itself. The two

integers are used for holding the size of the texture.

In the constructor the new variables need to be initialized which can be done with the following lines.
 cubetexture = new Texture("white");
 tWidth  = cubetexture.getWidth();
 tHeight = cubetexture.getHeight();
 timage  = Cult.createImage(tWidth, tHeight);
For the interactivity we need a method that can be called from the Designer. If a method takes one String as the argument it can be called from the Designer.

For every click we create a new random color that we paints on the temporary image timage. Then the image will be painted on the objects texture by a call to the method setTexture(). The finnished method will look like this.
public void mouseClick(String arg)
 {
   Color    c = new Color((float)Math.random(), (float)Math.random(), (float)Math.random());
   Graphics g = timage.getGraphics();
   g.setColor(c);
   g.fillRect(0,0, tWidth,tHeight);
   cubetexture.setTexture(timage);
 }
All thats left to make the new java code complete is to add the needed imports.
import com.cult3d.Cult;
import com.cult3d.Cult3DScript;
import com.cult3d.world.CultObject;
import com.cult3d.world.Texture;


import java.awt.Color;
import java.awt.Image;
import java.awt.Graphics;


public class WhiteCube extends Thread implements Cult3DScript
{
   private CultObject whitecube;
   private Texture    cubetexture;
   private Image      timage;

   private int tWidth, tHeight;

   private boolean    going = true;
	
   public WhiteCube()
   {
      whitecube   = new CultObject("Cube");
      cubetexture = new Texture("white");
      tWidth  = cubetexture.getWidth();
      tHeight = cubetexture.getHeight();
      timage  = Cult.createImage(tWidth, tHeight);

      start();
   }

   public void run()
   {
      do {
         whitecube.rotate( whitecube.Z, (float)(10*Math.PI/180.0));
         whitecube.rotate( whitecube.Y, (float)( 5*Math.PI/180.0));
         try {
            sleep(100);
         } catch(InterruptedException e) {
         }
      } while(going);
   }

   public void mouseClick(String arg)
   {
      Color c = new Color((float)Math.random(),
                (float)Math.random(),
                (float)Math.random());
      Graphics g = timage.getGraphics();
      g.setColor(c);
      g.fillRect(0,0, tWidth,tHeight);
      cubetexture.setTexture(timage);
   }

   public void cult3dDestroy()
   {
      going = false;
   }
}
Compile the java file into a class file.

Now it's time to start the Designer again.

In The Designer do exactly as last time. First load in the cube object into the Designer then open the Java Actions window and add the newly compiled WhiteCube.class file.

Remember to fill in WhiteCube.class as the Startup class.

When the class file is added this time the word mouseCLick can be found under the class. This is a Java Action that can be called from the Designer.

To add interactivity to the object we need to add some events and actions to the Event map.

First Drag a 'left mouse click on object' event to the event map.

Then drag the cube object from the scene graph to the new mouse event. A line should appear between the event and the object.

Then drag the Java action 'mouseClicked' from the Java Actions window to the same mouse event.