Cult3D Java API Documentation Threads

Threads with Cult3D

When doing multi-threaded Java in Cult3D, you should think of some important issues. Load all heavy things in a separate thread, such as resources and textures, in other case your Cult3D scene may freeze.

If you are looping in your run method, check a boolean variable if the Cult3D Viewer is about to die, set this boolean in the method cult3dDestroy().

When you are inside the run method you should catch the exception java.lang.IllegalStateException, it will be thrown if the Java code tries to do anything meanwhile the Cult3D Viewer is about to die.

In a multi-threaded Java program you can in some cases end up with different versions of the same variable in a multi-threaded Java, due to the JIT compiler introduced by Sun in Java 1.1. This can be true in Cult3D Viewer were different viewer threads calls your Java methods. To avoid this you should use the keyword volatile, please understand that a variable declared volatile is less efficient than it's counterpart. It is strongly recommended to declare your "thread death" variable volatile.

EXAMPLE CODE

>     import com.cult3d.Cult3DScript;

>     public  ThreadSnippet  implements Cult3DScript, Runnable
>     {
>         // Declare this variables volatile to ensure
>         // it is always holds the correct value
>         private volatile boolean  stillRunning;
>         private volatile boolean  finishedLoading;

>         // Standard constructor
>         public  ThreadSnippet()
>         {
>             stillRunning = true;
>             finishedLoading = false;

>             new Thread(this).start();
>         }

>         // This class thread-run method.
>         public void run()
>         {
>             // Load some resources or other heavy stuff

>             // State the loading is done
>             finishedLoading = true;

>             while (stillRunning)
>             {
>                 // do something repeatedly
>                 try
>                 {
>                     Thread.currentThread().sleep(100);
>                 }
>                 catch (InterruptedException e)
>                 {
>                 }
>             }
>         }

>         // Some method you call from the Cult3D Designer
>         public void methodX(String arg)
>         {
>             // If all has not been loaded return
>             if (!finishedLoading)
>             {
>                 return;
>             }

>             // Do something
>         }

>         // This method is called when the
>         // Cult3D viewer is being shutdown.
>         public void cult3dDestroy()
>         {
>             try
>             {
>             	// Tell the thread to stop working
>             	stillRunning = false;
>             }
>             catch (Exception e) // Catch all exceptions silently while stopping threads
>             {
>             }
>         }
>     }

Try to use an absolute minimum of extra threads. Cult3D as well as Java are cross platform and there are systems and web browsers which do poorly multi-threading. It is strongly recommended to just have two threads in you Cult3D Java, your main thread and an extra thread that you create to load resources.

You can simulate threads in Cult3D Designer. One way to do this is to have a Timer event which activates a Java method, the Timer resets itself after been triggered.