optimized context switchingrel-2-8-0-0-prerelease-3

1 files changed, 129 insertions, 0 deletions

diff --git a/gl4java/GLRunnable.java b/gl4java/GLRunnable.java
new file mode 100644
index 0000000..ca66af5
--- /dev/null
+++ b/gl4java/GLRunnable.java
@@ -0,0 +1,129 @@
+/**
+ * @(#) GLRunnable.java
+ */
+package gl4java;
+
+import java.lang.*;
+
+/**
+ * This is the interface for a threaded renderer (animator thread).
+ *
+ * If an animation class, e.g. {@link gl4java.awt.GLAnimCanvas},
+ * implements {@link gl4java.drawable.GLDrawable} and this interface,
+ * you will benefit from the new context handling {@link gl4java.GLContext#gljFree}.
+ *
+ * @see gl4java.GLContext
+ * @see gl4java.drawable.GLDrawable
+ * @see gl4java.awt.GLAnimCanvas
+ */
+public interface GLRunnable extends Runnable
+{
+        /** 
+         *  This creates and start one singleton unique thread !
+         */
+        public void start();
+
+        /** 
+         *  This stops and destroys (deferred) our singleton unique thread !
+         */
+        public void stop();
+
+	/**
+	 * Identifies this object with the given thread ..
+	 * If this object owns this thread, it must return true !
+	 */
+	public boolean ownsThread(Thread thread);
+
+        /** 
+         *  The running loop for animations
+         *  which initiates the call of display
+         *
+	 *  Be sure to force freeing the GL context 
+	 *  with {@link gl4java.GLContext#gljFree}(true), if:
+	 *  <pre>
+	 	- you exit this run loop
+		- you suspend your thread -> wait
+		- you kill your thread ..
+	 *  </pre>
+	 *
+	 *  Also be sure, to implement this Runnable as Java2 does recomends !
+	 *  Look at the example implementation {@link gl4java.awt.GLAnimCanvas#run} !
+	 *
+         * @see gl4java.awt.GLAnimCanvas#run
+         * @see #setSuspended
+         */
+        public void run();
+
+        /** 
+         *  Here we can (re)start or suspend animation ...
+	 *
+	 * If the thread should be (re)started and is not alive -> killed, 
+	 * or never be started, it will be started !
+	 *
+	 * @param suspend  if true the thread will be suspended,
+	 *                 if false, the thread will be (re)started
+	 *
+         * @see #isAlive
+         * @see #start
+         */
+        public void setSuspended(boolean suspend);
+
+        /** 
+         *  Here we can (re)start or suspend animation ...
+	 *
+	 * If the thread should be (re)started and is not alive -> killed, 
+	 * or never be started, it will be started !
+	 *
+	 * @param suspend  if true the thread will be suspended,
+	 *                 if false, the thread will be (re)started
+	 *
+	 * @param reInit   if true the ReInit will be called additionally,
+	 *                 where the user can set additional initialisations
+	 *
+         * @see #ReInit
+         * @see #isAlive
+         * @see #start
+         * @see #run
+         */
+        public void setSuspended(boolean suspend, boolean reInit);
+
+        /**
+         * is the thread alive, means is started and not died ?
+         *
+         * @see #run
+         * @see #setSuspended
+         * @see #start
+         * @see #stop
+         */      
+        public boolean isAlive();
+
+        /**
+         * is the thread suspended, means is started but waiting, 
+	 * or not alive (ok :-| - but it is practical)
+         *
+         * @see #run
+         * @see #setSuspended
+         * @see #start
+         * @see #stop
+         */      
+        public boolean isSuspended();
+
+        /**
+         * ReInit should be overwritten by you,
+         * to enter your re-initialisation within setSuspended(false) 
+         * 
+         * @see #setSuspended
+         */
+        public void ReInit();
+
+        /** 
+         * Forces this thread to release it's GLContext !
+	 * 
+	 * To ensure this, this thread enables itself,
+	 * and calls gljFree(true) to force the release !
+         *
+         * @see #setSuspended
+         * @see #run
+         */
+	public void freeGLContext();
+}