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

6 files changed, 75 insertions, 35 deletions

diff --git a/src/jogl/classes/jogamp/opengl/android/av/AndroidGLMediaPlayerAPI14.java b/src/jogl/classes/jogamp/opengl/android/av/AndroidGLMediaPlayerAPI14.java
index 38faf62a6..35084f1c5 100644
--- a/src/jogl/classes/jogamp/opengl/android/av/AndroidGLMediaPlayerAPI14.java
+++ b/src/jogl/classes/jogamp/opengl/android/av/AndroidGLMediaPlayerAPI14.java
@@ -433,7 +433,7 @@ public class AndroidGLMediaPlayerAPI14 extends GLMediaPlayerImpl {
     protected final TextureSequence.TextureFrame createTexImage(GL gl, int texName) {
         sTexFrameCount++;
         if( 1 == sTexFrameCount ) {
-            singleSTexFrame = new SurfaceTextureFrame( createTexImageImpl(gl, texName, width, height, true), new SurfaceTexture(texName) );
+            singleSTexFrame = new SurfaceTextureFrame( createTexImageImpl(gl, texName, width, height), new SurfaceTexture(texName) );
         }
         return singleSTexFrame;
     }
diff --git a/src/jogl/classes/jogamp/opengl/util/av/EGLMediaPlayerImpl.java b/src/jogl/classes/jogamp/opengl/util/av/EGLMediaPlayerImpl.java
index ec375406d..31af8e4db 100644
--- a/src/jogl/classes/jogamp/opengl/util/av/EGLMediaPlayerImpl.java
+++ b/src/jogl/classes/jogamp/opengl/util/av/EGLMediaPlayerImpl.java
@@ -85,7 +85,7 @@ public abstract class EGLMediaPlayerImpl extends GLMediaPlayerImpl {
 
     @Override
     protected TextureSequence.TextureFrame createTexImage(GL gl, int texName) {
-        final Texture texture = super.createTexImageImpl(gl, texName, width, height, false);
+        final Texture texture = super.createTexImageImpl(gl, texName, width, height);
         final Buffer clientBuffer;
         final long image;
         final long sync;
diff --git a/src/jogl/classes/jogamp/opengl/util/av/GLMediaPlayerImpl.java b/src/jogl/classes/jogamp/opengl/util/av/GLMediaPlayerImpl.java
index ab0e2eebd..205642eb0 100644
--- a/src/jogl/classes/jogamp/opengl/util/av/GLMediaPlayerImpl.java
+++ b/src/jogl/classes/jogamp/opengl/util/av/GLMediaPlayerImpl.java
@@ -165,6 +165,10 @@ public abstract class GLMediaPlayerImpl implements GLMediaPlayer {
     protected Ringbuffer<TextureFrame> videoFramesFree =  null;
     protected Ringbuffer<TextureFrame> videoFramesDecoded =  null;
     protected volatile TextureFrame lastFrame = null;
+    /**
+     * @see #isGLOriented()
+     */
+    protected boolean isInGLOrientation = false;
 
     private ArrayList<GLMediaEventListener> eventListeners = new ArrayList<GLMediaEventListener>();
 
@@ -203,12 +207,6 @@ public abstract class GLMediaPlayerImpl implements GLMediaPlayer {
     public final void setTextureWrapST(int[] wrapST) { texWrapST[0] = wrapST[0]; texWrapST[1] = wrapST[1];}
     public final int[] getTextureWrapST() { return texWrapST; }    
     
-    private final void checkStreamInit() {
-        if(State.Uninitialized == state ) {
-            throw new IllegalStateException("Stream not initialized: "+this);
-        }        
-    }
-    
     private final void checkGLInit() {
         if(State.Uninitialized == state || State.Initialized == state ) {
             throw new IllegalStateException("GL not initialized: "+this);
@@ -339,6 +337,23 @@ public abstract class GLMediaPlayerImpl implements GLMediaPlayer {
     protected abstract boolean pauseImpl();
     
     @Override
+    public final State destroy(GL gl) {
+        return destroyImpl(gl, 0);
+    }
+    private final State destroyImpl(GL gl, int event_mask) {
+        synchronized( stateLock ) {
+            streamWorker.doStop();
+            streamWorker = null;
+            destroyImpl(gl);
+            removeAllTextureFrames(gl);
+            textureCount=0;
+            changeState(event_mask, State.Uninitialized);
+            return state;
+        }
+    }
+    protected abstract void destroyImpl(GL gl);
+    
+    @Override
     public final int seek(int msec) {
         synchronized( stateLock ) {
             final State preState = state;
@@ -458,7 +473,7 @@ public abstract class GLMediaPlayerImpl implements GLMediaPlayer {
     public final void initStream(URI streamLoc, int vid, int aid, int reqTextureCount) throws IllegalStateException, IllegalArgumentException {
         synchronized( stateLock ) {
             if(State.Uninitialized != state) {
-                throw new IllegalStateException("Instance not unintialized: "+this);
+                throw new IllegalStateException("Instance not in state unintialized: "+this);
             }
             if(null == streamLoc) {
                 throw new IllegalArgumentException("streamLock is null");
@@ -485,7 +500,7 @@ public abstract class GLMediaPlayerImpl implements GLMediaPlayer {
                 if( null != rawPath && rawPath.length() > 0 ) {
                     // cut-off root fwd-slash 
                     cameraPath = rawPath.substring(1);
-                    final URIQueryProps props = URIQueryProps.create(streamLoc);
+                    final URIQueryProps props = URIQueryProps.create(streamLoc, ';');
                     cameraProps = props.getProperties();
                 } else {
                     throw new IllegalArgumentException("Camera path is empty: "+streamLoc.toString());
@@ -528,10 +543,12 @@ public abstract class GLMediaPlayerImpl implements GLMediaPlayer {
     @Override
     public final void initGL(GL gl) throws IllegalStateException, StreamException, GLException {
         synchronized( stateLock ) {
-            checkStreamInit();
+            if(State.Initialized != state ) {
+                throw new IllegalStateException("Stream not in state initialized: "+this);
+            }        
             final StreamException streamInitErr = streamWorker.getStreamErr();
             if( null != streamInitErr ) {
-                streamWorker = null;
+                streamWorker = null; // already terminated!
                 destroy(null);
                 throw streamInitErr;
             }
@@ -559,6 +576,7 @@ public abstract class GLMediaPlayerImpl implements GLMediaPlayer {
                 }
                 changeState(0, State.Paused);
             } catch (Throwable t) {
+                destroyImpl(gl, GLMediaEventListener.EVENT_CHANGE_ERR); // -> GLMediaPlayer.State.Uninitialized
                 throw new GLException("Error initializing GL resources", t);
             }
         }
@@ -602,7 +620,7 @@ public abstract class GLMediaPlayerImpl implements GLMediaPlayer {
     }
     protected abstract TextureFrame createTexImage(GL gl, int texName);
     
-    protected final Texture createTexImageImpl(GL gl, int texName, int tWidth, int tHeight, boolean mustFlipVertically) {
+    protected final Texture createTexImageImpl(GL gl, int texName, int tWidth, int tHeight) {
         if( 0 > texName ) {
             throw new RuntimeException("TextureName "+toHexString(texName)+" invalid.");
         }
@@ -649,7 +667,7 @@ public abstract class GLMediaPlayerImpl implements GLMediaPlayer {
                      texName, textureTarget,
                      tWidth, tHeight,
                      width,  height,
-                     mustFlipVertically);        
+                     !isInGLOrientation);        
     }
         
     protected void destroyTexFrame(GL gl, TextureFrame frame) {
@@ -1251,20 +1269,19 @@ public abstract class GLMediaPlayerImpl implements GLMediaPlayer {
         attributesUpdated(event_mask);
     }
 
-    @Override
-    public final State destroy(GL gl) {
-        synchronized( stateLock ) {
-            streamWorker.doStop();
-            streamWorker = null;
-            destroyImpl(gl);
-            removeAllTextureFrames(gl);
-            textureCount=0;
-            changeState(0, State.Uninitialized);
-            return state;
+    protected void setIsGLOriented(boolean isGLOriented) {
+        if( isInGLOrientation != isGLOriented ) {
+            if( DEBUG ) {
+                System.err.println("XXX gl-orient "+isInGLOrientation+" -> "+isGLOriented);
+            }
+            isInGLOrientation = isGLOriented;
+            for(int i=0; i<videoFramesOrig.length; i++) {
+                videoFramesOrig[i].getTexture().setMustFlipVertically(!isGLOriented);
+            }
+            attributesUpdated(GLMediaEventListener.EVENT_CHANGE_SIZE);
         }
     }
-    protected abstract void destroyImpl(GL gl);
-
+    
     @Override
     public final URI getURI() {
         return streamLoc;
@@ -1322,6 +1339,11 @@ public abstract class GLMediaPlayerImpl implements GLMediaPlayer {
     }
 
     @Override
+    public final boolean isGLOriented() {
+        return isInGLOrientation;
+    }
+    
+    @Override
     public final int getWidth() {
         return width;
     }
@@ -1342,7 +1364,7 @@ public abstract class GLMediaPlayerImpl implements GLMediaPlayer {
         return "GLMediaPlayer["+state+", vSCR "+video_scr+", frames[p "+presentedFrameCount+", d "+decodedFrameCount+", t "+videoFrames+" ("+tt+" s)], "+
                "speed "+playSpeed+", "+bps_stream+" bps, "+
                "Texture[count "+textureCount+", free "+freeVideoFrames+", dec "+decVideoFrames+", tagt "+toHexString(textureTarget)+", ifmt "+toHexString(textureInternalFormat)+", fmt "+toHexString(textureFormat)+", type "+toHexString(textureType)+"], "+
-               "Video[id "+vid+", <"+vcodec+">, "+width+"x"+height+", "+fps+" fps, "+frame_duration+" fdur, "+bps_video+" bps], "+
+               "Video[id "+vid+", <"+vcodec+">, "+width+"x"+height+", glOrient "+isInGLOrientation+", "+fps+" fps, "+frame_duration+" fdur, "+bps_video+" bps], "+
                "Audio[id "+aid+", <"+acodec+">, "+bps_audio+" bps, "+audioFrames+" frames], uri "+loc+camPath+"]";
     }
     
diff --git a/src/jogl/classes/jogamp/opengl/util/av/NullGLMediaPlayer.java b/src/jogl/classes/jogamp/opengl/util/av/NullGLMediaPlayer.java
index 6fa7c7a54..1cddaa9cf 100644
--- a/src/jogl/classes/jogamp/opengl/util/av/NullGLMediaPlayer.java
+++ b/src/jogl/classes/jogamp/opengl/util/av/NullGLMediaPlayer.java
@@ -57,6 +57,7 @@ public class NullGLMediaPlayer extends GLMediaPlayerImpl {
     
     public NullGLMediaPlayer() {
         super();
+        
     }
 
     @Override
@@ -143,7 +144,7 @@ public class NullGLMediaPlayer extends GLMediaPlayerImpl {
     }    
     @Override
     protected final void initGLImpl(GL gl) throws IOException, GLException {
-        // NOP
+        isInGLOrientation = true;
     }
     
     /**
@@ -159,7 +160,7 @@ public class NullGLMediaPlayer extends GLMediaPlayerImpl {
     
     @Override
     protected final TextureSequence.TextureFrame createTexImage(GL gl, int texName) {
-        final Texture texture = super.createTexImageImpl(gl, texName, width, height, false);
+        final Texture texture = super.createTexImageImpl(gl, texName, width, height);
         if(null != texData) {
             texture.updateImage(gl, texData);
         }                      
diff --git a/src/jogl/classes/jogamp/opengl/util/av/impl/FFMPEGMediaPlayer.java b/src/jogl/classes/jogamp/opengl/util/av/impl/FFMPEGMediaPlayer.java
index 2737a0b6a..c329e880f 100644
--- a/src/jogl/classes/jogamp/opengl/util/av/impl/FFMPEGMediaPlayer.java
+++ b/src/jogl/classes/jogamp/opengl/util/av/impl/FFMPEGMediaPlayer.java
@@ -293,7 +293,8 @@ public class FFMPEGMediaPlayer extends GLMediaPlayerImpl {
         
         final boolean isCameraInput = null != cameraPath;
         final String resStreamLocS;
-        int rw=640, rh=480, rr=15;
+        // int rw=640, rh=480, rr=15;
+        int rw=-1, rh=-1, rr=-1;
         String sizes = null;
         if( isCameraInput ) {
             switch(Platform.OS_TYPE) {
@@ -424,7 +425,7 @@ public class FFMPEGMediaPlayer extends GLMediaPlayerImpl {
     }    
     @Override
     protected final TextureFrame createTexImage(GL gl, int texName) {
-        return new TextureFrame( createTexImageImpl(gl, texName, texWidth, texHeight, true) );
+        return new TextureFrame( createTexImageImpl(gl, texName, texWidth, texHeight) );
     }
     
     /**
@@ -521,10 +522,10 @@ public class FFMPEGMediaPlayer extends GLMediaPlayerImpl {
      * @param audioChannels
      * @param audioSamplesPerFrameAndChannel in audio samples per frame and channel
      */
-    void updateAttributes2(int vid, int pixFmt, int planes, int bitsPerPixel, int bytesPerPixelPerPlane,
-                           int tWd0, int tWd1, int tWd2, int vW, int vH,
-                           int aid, int audioSampleFmt, int audioSampleRate, 
-                           int audioChannels, int audioSamplesPerFrameAndChannel) {
+    void setupFFAttributes(int vid, int pixFmt, int planes, int bitsPerPixel, int bytesPerPixelPerPlane,              
+                          int tWd0, int tWd1, int tWd2, int vW, int vH,
+                          int aid, int audioSampleFmt, int audioSampleRate, 
+                          int audioChannels, int audioSamplesPerFrameAndChannel) {
         // defaults ..
         vPixelFmt = null;
         vPlanes = 0;
@@ -612,6 +613,21 @@ public class FFMPEGMediaPlayer extends GLMediaPlayerImpl {
     }
     
     /**
+     * Native callback
+     * @param isInGLOrientation
+     * @param pixFmt
+     * @param planes
+     * @param bitsPerPixel
+     * @param bytesPerPixelPerPlane
+     * @param tWd0
+     * @param tWd1
+     * @param tWd2
+     */
+    void updateVidAttributes(boolean isInGLOrientation, int pixFmt, int planes, int bitsPerPixel, int bytesPerPixelPerPlane,              
+                             int tWd0, int tWd1, int tWd2, int vW, int vH) {
+    }
+    
+    /**
      * {@inheritDoc}
      * 
      * If this implementation generates a specialized shader,
diff --git a/src/jogl/classes/jogamp/opengl/util/av/impl/OMXGLMediaPlayer.java b/src/jogl/classes/jogamp/opengl/util/av/impl/OMXGLMediaPlayer.java
index faa6a56c4..a5a701a4f 100644
--- a/src/jogl/classes/jogamp/opengl/util/av/impl/OMXGLMediaPlayer.java
+++ b/src/jogl/classes/jogamp/opengl/util/av/impl/OMXGLMediaPlayer.java
@@ -119,6 +119,7 @@ public class OMXGLMediaPlayer extends EGLMediaPlayerImpl {
     @Override
     protected final void initGLImpl(GL gl) throws IOException, GLException {
         // NOP
+        isInGLOrientation = true;
     }
     
     @Override