From c67de337a8aaf52e36104c3f13e273aa19d21f1f Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Sat, 22 Feb 2014 08:05:42 +0100
Subject: Bug 927 - Multithreading (MT) - GLMediaPlayer.GLMediaEventListener:
 Remind that commands shall be off-loaded on another thread!

---
 .../classes/com/jogamp/opengl/util/av/GLMediaPlayer.java     |  8 +++++++-
 .../com/jogamp/opengl/util/texture/TextureSequence.java      | 12 ++++++------
 2 files changed, 13 insertions(+), 7 deletions(-)

(limited to 'src/jogl/classes/com/jogamp/opengl')

diff --git a/src/jogl/classes/com/jogamp/opengl/util/av/GLMediaPlayer.java b/src/jogl/classes/com/jogamp/opengl/util/av/GLMediaPlayer.java
index 9957f2093..5a455c8bd 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/av/GLMediaPlayer.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/av/GLMediaPlayer.java
@@ -30,6 +30,7 @@ package com.jogamp.opengl.util.av;
 import java.net.URI;
 
 import javax.media.opengl.GL;
+import javax.media.opengl.GLEventListener;
 import javax.media.opengl.GLException;
 
 import jogamp.opengl.Debug;
@@ -255,7 +256,12 @@ public interface GLMediaPlayer extends TextureSequence {
     /**
      * {@inheritDoc}
      * <p>
-     * See {@link TexSeqEventListener} for semantics and usage.
+     * As the contract of {@link TexSeqEventListener} requests,
+     * implementations of {@link GLMediaEventListener} shall also:
+     * <ul>
+     *   <li>off-load complex or {@link GLMediaPlayer} commands on another thread, or</li>
+     *   <li>simply changing a volatile state of their {@link GLEventListener} implementation.</li>
+     * </ul>
      * </p>
      */
     public interface GLMediaEventListener extends TexSeqEventListener<GLMediaPlayer> {
diff --git a/src/jogl/classes/com/jogamp/opengl/util/texture/TextureSequence.java b/src/jogl/classes/com/jogamp/opengl/util/texture/TextureSequence.java
index 6c2949c2b..ab9d1f8f0 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/texture/TextureSequence.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/texture/TextureSequence.java
@@ -31,6 +31,7 @@ import javax.media.opengl.GL;
 import javax.media.opengl.GLAutoDrawable;
 import javax.media.opengl.GLRunnable;
 import javax.media.opengl.GLEventListener;
+
 import com.jogamp.opengl.util.TimeFrameI;
 
 /**
@@ -133,17 +134,16 @@ public interface TextureSequence {
     /**
      * Event listener to notify users of updates regarding the {@link TextureSequence}.
      * <p>
-     * The implementation sending the events, and hence calling down to all listeners,
-     * does not necessarily make the user's OpenGL context current.
+     * Implementations sending events down to all listeners,
+     * while not necessarily making the user's OpenGL context current.
      * </p>
      * <p>
-     * Further more, the call may happen off-thread, possibly holding another, possibly shared, OpenGL context current.
-     * </p>
+     * Events may be sent from a 3rd-party thread, possibly holding another, maybe shared, OpenGL context current.<br/>
      * Hence a user shall not issue <i>any</i> OpenGL, time consuming
-     * or {@link TextureSequence} lifecycle operations directly.<br>
+     * or {@link TextureSequence} operations directly.<br>
      * Instead, the user shall:
      * <ul>
-     *   <li>issue commands off-thread via spawning off another thread, or</li>
+     *   <li>off-load complex or {@link TextureSequence} commands on another thread, or</li>
      *   <li>injecting {@link GLRunnable} objects via {@link GLAutoDrawable#invoke(boolean, GLRunnable)}, or</li>
      *   <li>simply changing a volatile state of their {@link GLEventListener} implementation.</li>
      * </ul>
-- 
cgit v1.2.3