From 4cb3763415bb5f82520fd02f56412076f80a84e6 Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Fri, 30 Aug 2013 17:31:34 +0200
Subject: GLMediaPlayer enhancements: State, Camera options, detect and act on
 orientation change (flipped), API-doc,

- State
  - Fix state transition (initGL() error)

- Camera options
  - options uses ';' as query separator
  - don't use 'default' options, driver should know

- Detect and act on orientation change (flipped)
  - ffmpeg impl detects if flipped changes and triggers a SIZE update event.
    This allows application to react, i.e. re-init GL and use new TextureCoord's.
    Test: Works well on Windows w/ rawvideo dshow camera driver/codec.

- API-doc
  - TexSeqEventListener/GLMediaEventListener usage / constraints (GL, ..)
  - State transition fix
---
 .../opengl/util/texture/TextureSequence.java       | 23 +++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

(limited to 'src/jogl/classes/com/jogamp/opengl/util/texture/TextureSequence.java')

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 8b6cc1bf9..5c6b63535 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/texture/TextureSequence.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/texture/TextureSequence.java
@@ -28,7 +28,9 @@
 package com.jogamp.opengl.util.texture;
 
 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;
 
 /**
@@ -128,6 +130,25 @@ public interface TextureSequence {
         protected final Texture texture;
     }
 
+    /**
+     * 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.
+     * </p>
+     * <p>
+     * Further more, the call may happen off-thread, possibly holding another, possibly shared, OpenGL context current.
+     * </p>
+     * Hence a user shall not issue <i>any</i> OpenGL, time consuming 
+     * or {@link TextureSequence} lifecycle operations directly.<br>
+     * Instead, the user shall:
+     * <ul>
+     *   <li>issue commands off-thread via spawning off 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> 
+     * </p>
+     * */
     public interface TexSeqEventListener<T extends TextureSequence> {
         /** 
          * Signaling listeners that a new {@link TextureFrame} is available.
-- 
cgit v1.2.3