GLMediaPlayer: Add Class / Package API doc incl. detailed info in the implementations.

4 files changed, 88 insertions, 5 deletions

diff --git a/src/jogl/classes/jogamp/opengl/android/av/AndroidGLMediaPlayerAPI14.java b/src/jogl/classes/jogamp/opengl/android/av/AndroidGLMediaPlayerAPI14.java
index f6189f03c..23f9161d4 100644
--- a/src/jogl/classes/jogamp/opengl/android/av/AndroidGLMediaPlayerAPI14.java
+++ b/src/jogl/classes/jogamp/opengl/android/av/AndroidGLMediaPlayerAPI14.java
@@ -44,8 +44,17 @@ import android.net.Uri;
 import android.view.Surface;
 
 /***
- * Android API Level 14: {@link MediaPlayer#setSurface(Surface)}
- * Android API Level 14: {@link Surface#Surface(android.graphics.SurfaceTexture)}
+ * Android implementation utilizes API level 14 (4.0.? ICS) features
+ * as listed below.
+ * <p>
+ * We utilize the {@link MediaPlayer} with direct to texture streaming.
+ * The MediaPlayer uses <code>libstagefright</code> to access the OpenMAX AL implementation
+ * for hardware decoding.
+ * </p>
+ * <ul>
+ *   <li>Android API Level 14: {@link MediaPlayer#setSurface(Surface)}</li>
+ *   <li>Android API Level 14: {@link Surface#Surface(android.graphics.SurfaceTexture)}</li>
+ * </ul>
  */
 public class AndroidGLMediaPlayerAPI14 extends GLMediaPlayerImpl {
     static final boolean available;
diff --git a/src/jogl/classes/jogamp/opengl/util/av/NullGLMediaPlayer.java b/src/jogl/classes/jogamp/opengl/util/av/NullGLMediaPlayer.java
index fe2aeaf19..3d740d6b2 100644
--- a/src/jogl/classes/jogamp/opengl/util/av/NullGLMediaPlayer.java
+++ b/src/jogl/classes/jogamp/opengl/util/av/NullGLMediaPlayer.java
@@ -44,7 +44,8 @@ import com.jogamp.opengl.util.texture.TextureIO;
 import com.jogamp.opengl.util.texture.TextureSequence;
 
 /***
- * A dummy null media player implementation using a static test frame (if available).
+ * A dummy null media player implementation using a static test frame
+ * available on all platforms.
  */
 public class NullGLMediaPlayer extends GLMediaPlayerImpl {
     private TextureData texData = null;
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 d24961b68..7d10cff4d 100644
--- a/src/jogl/classes/jogamp/opengl/util/av/impl/FFMPEGMediaPlayer.java
+++ b/src/jogl/classes/jogamp/opengl/util/av/impl/FFMPEGMediaPlayer.java
@@ -49,15 +49,56 @@ import jogamp.opengl.gl4.GL4bcProcAddressTable;
 import jogamp.opengl.util.av.EGLMediaPlayerImpl;
 
 /***
- * Currently only YUV420P and the usual packed RGB formats are supported.
+ * Implementation utilizes <a href="http://libav.org/">Libav</a>
+ * or  <a href="http://ffmpeg.org/">FFmpeg</a> which is ubiquitous
+ * available and usually pre-installed on Unix platforms. Due to legal 
+ * reasons we cannot deploy binaries of it, which contains patented codecs.
+ * Besides the default BSD/Linux/.. repositories and installations,
+ * precompiled binaries can be found at the listed location below. 
+ * <p>
+ * Implements YUV420P to RGB fragment shader conversion 
+ * and the usual packed RGB formats.
+ * The decoded video frame is written directly into an OpenGL texture 
+ * on the GPU in it's native format. A custom fragment shader converts 
+ * the native pixelformat to a usable RGB format if required. 
+ * Hence only 1 copy is required before bloating the picture 
+ * from YUV to RGB, for example.
+ * </p> 
+ * <p>
+ * Utilizes a slim dynamic and native binding to the Lib_av 
+ * libraries:
+ * <ul>
+ *   <li>libavutil</li>
+ *   <li>libavformat</li>
+ *   <li>libavcodec</li>
+ * </ul> 
+ * </p>
+ * <p>
+ * http://libav.org/
+ * </p>
  * <p> 
  * Check tag 'FIXME: Add more planar formats !' 
  * here and in the corresponding native code
  * <code>jogl/src/jogl/native/ffmpeg/jogamp_opengl_util_av_impl_FFMPEGMediaPlayer.c</code>
  * </p>
  * <p>
- * TODO: Audio Output
+ * TODO:
+ * <ul>
+ *   <li>Audio Output</li>
+ *   <li>Off thread <i>next frame</i> processing using multiple target textures</li>
+ *   <li>better pts sync handling</li>
+ *   <li>fix seek</li>   
+ * </ul> 
  * </p>
+ * Pre-compiled Libav / FFmpeg packages:
+ * <ul>
+ *   <li>Windows: http://ffmpeg.zeranoe.com/builds/</li>
+ *   <li>MacOSX: http://www.ffmpegx.com/</li>
+ *   <li>OpenIndiana/Solaris:<pre>
+ *       pkg set-publisher -p http://pkg.openindiana.org/sfe-encumbered.
+ *       pkt install pkg:/video/ffmpeg
+ *       </pre></li>
+ * </ul> 
  */
 public class FFMPEGMediaPlayer extends EGLMediaPlayerImpl {
     public static final VersionNumber avUtilVersion;
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 7c812ce1c..aef98fcde 100644
--- a/src/jogl/classes/jogamp/opengl/util/av/impl/OMXGLMediaPlayer.java
+++ b/src/jogl/classes/jogamp/opengl/util/av/impl/OMXGLMediaPlayer.java
@@ -1,3 +1,30 @@
+/**
+ * Copyright 2012 JogAmp Community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ * 
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ * 
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ * 
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
 
 package jogamp.opengl.util.av.impl;
 
@@ -13,6 +40,11 @@ import com.jogamp.opengl.util.texture.TextureSequence;
 import jogamp.opengl.egl.EGL;
 import jogamp.opengl.util.av.EGLMediaPlayerImpl;
 
+/**
+ * OpenMAX IL implementation. This implementation is currently not tested
+ * due to lack of an available device or working <i>software</i> implementation.
+ * It is kept alive through all changes in the hope of a later availability though.
+ */
 public class OMXGLMediaPlayer extends EGLMediaPlayerImpl {
     static final boolean available;