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

author: Sven Gothel <[email protected]> 2012-04-18 10:45:41 +0200
committer: Sven Gothel <[email protected]> 2012-04-18 10:45:41 +0200
commit: 1152d3c3cb5d13b4e5543387bff7a73e78e27a71 (patch)
tree: 0f3e34a08311a879c8e67d7a1cd6eb919be532c1 /src/jogl/classes
parent: 1e16a4cd123aafe41d51f01b41fad5a77c4ffbe3 (diff)
6 files changed, 122 insertions, 5 deletions
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 8430d6137..3eca01986 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/av/GLMediaPlayer.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/av/GLMediaPlayer.java
@@ -48,6 +48,15 @@ import com.jogamp.opengl.util.texture.TextureSequence;
  *   <tr><td>{@link #destroy(GL)}</td>                     <td>ANY</td>                 <td>Uninitialized</td></tr>
  * </table>
  * <p>
+ * Current implementations (check each API doc link for details):
+ * <ul>
+ *   <li>{@link jogamp.opengl.util.av.NullGLMediaPlayer}</li>
+ *   <li>{@link jogamp.opengl.util.av.impl.OMXGLMediaPlayer}</li>
+ *   <li>{@link jogamp.opengl.util.av.impl.FFMPEGMediaPlayer}</li>
+ *   <li>{@link jogamp.opengl.android.av.AndroidGLMediaPlayerAPI14}</li> 
+ * </ul>
+ * </p>
+ * <p>
  * Variable type, value range and dimension has been chosen to suit embedded CPUs
  * and characteristics of audio and video streaming.
  * Milliseconds of type integer with a maximum value of {@link Integer#MAX_VALUE} 
diff --git a/src/jogl/classes/com/jogamp/opengl/util/av/package.html b/src/jogl/classes/com/jogamp/opengl/util/av/package.html
new file mode 100644
index 000000000..249db7d30
--- /dev/null
+++ b/src/jogl/classes/com/jogamp/opengl/util/av/package.html
@@ -0,0 +1,25 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+  <title>Public Audio/Video Utility Package</title>
+</head>
+  <body>
+   
+<h2>Public <i>Audio/Video</i> Utility Package</h2>
+   
+<h3>Disclaimer</h3>
+  <p>
+  We are currently refining and completing this new API and it's implementation.
+  Feel free to comment and help using our public channels.
+  </p>
+<h3>Revision History<br>
+  </h3>
+   
+<ul>
+<li> Early Draft Review, April 17th 2012</li>
+</ul>
+  <br>
+  <br>
+ <br>
+</body>
+</html>
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;
author	Sven Gothel <[email protected]>	2012-04-18 10:45:41 +0200
committer	Sven Gothel <[email protected]>	2012-04-18 10:45:41 +0200
commit	1152d3c3cb5d13b4e5543387bff7a73e78e27a71 (patch)
tree	0f3e34a08311a879c8e67d7a1cd6eb919be532c1 /src/jogl/classes
parent	1e16a4cd123aafe41d51f01b41fad5a77c4ffbe3 (diff)