Bug 1494: Add SubTextureEvent & SubEmptyEvent; Add SubtitleEvent.release() provided by owner to take back borrowed resources (texture of bitmap subtitle)

5 files changed, 220 insertions, 31 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/util/av/ASSEventLine.java b/src/jogl/classes/com/jogamp/opengl/util/av/SubASSEventLine.java
index 6389df773..bd99122a9 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/av/ASSEventLine.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/av/SubASSEventLine.java
@@ -28,28 +28,13 @@
 package com.jogamp.opengl.util.av;
 
 /**
- * ASS/SAA Event Line of subtitles
+ * ASS/SAA Event Line of {@link SubtitleEvent}
  * <p>
  * See http://www.tcax.org/docs/ass-specs.htm
  * </p>
  */
-public class ASSEventLine {
-    public enum Format {
-        UNKNOWN,
-        /** FFMpeg output w/o start, end:
-         * <pre>
-           0    1      2      3     4        5        6        7       8
-           Seq, Layer, Style, Name, MarginL, MarginR, MarginV, Effect, TEXT
-         * </pre>
-         */
-        FFMPEG,
-        /** Just the plain text part */
-        TEXT
-    };
-    public final Format source;
+public class SubASSEventLine extends SubtitleEvent {
     public final int seqnr;
-    public final int pts_start;
-    public final int pts_end;
     public final int layer;
     public final String style;
     public final String name;
@@ -60,19 +45,19 @@ public class ASSEventLine {
 
     /**
      * ASS/SAA Event Line ctor
-     * @param fmt input format of {@code ass}, currently only {@link ASSEventLine.Format#FFMPEG} and {@link ASSEventLine.Format#TEXT} is supported
+     * @param fmt input format of {@code ass}, currently only {@link SubASSEventLine.Format#ASS_FFMPEG} and {@link SubASSEventLine.Format#ASS_TEXT} is supported
      * @param ass ASS/SAA compatible event line according to {@code fmt}
-     * @param pts_start pts start in ms, provided for {@link ASSEventLine.Format#FFMPEG} and {@link ASSEventLine.Format#TEXT}
-     * @param pts_end pts end in ms, provided for {@link ASSEventLine.Format#FFMPEG} and {@link ASSEventLine.Format#TEXT}
+     * @param pts_start pts start in ms, provided for {@link SubASSEventLine.Format#ASS_FFMPEG} and {@link SubASSEventLine.Format#ASS_TEXT}
+     * @param pts_end pts end in ms, provided for {@link SubASSEventLine.Format#ASS_FFMPEG} and {@link SubASSEventLine.Format#ASS_TEXT}
      */
-    public ASSEventLine(final Format fmt, final String ass, final int pts_start, final int pts_end) {
-        this.source = fmt;
+    public SubASSEventLine(final Format fmt, final String ass, final int pts_start, final int pts_end) {
+        super(fmt, pts_start, pts_end);
         int seqnr = 0;
         int layer = 0;
         String style = "Default";
         String name = "";
         String text = "";
-        if( Format.FFMPEG == fmt ) {
+        if( Format.ASS_FFMPEG == fmt ) {
             final int len = null != ass ? ass.length() : 0;
             int part = 0;
             for(int i=0; 9 > part && len > i; ) {
@@ -102,12 +87,10 @@ public class ASSEventLine {
                 }
                 ++part;
             }
-        } else if( Format.TEXT == fmt ) {
+        } else if( Format.ASS_TEXT == fmt ) {
             text = ass;
         }
         this.seqnr = seqnr;
-        this.pts_start = pts_start;
-        this.pts_end = pts_end;
         this.layer = layer;
         this.style = style;
         this.name = name;
@@ -126,10 +109,12 @@ public class ASSEventLine {
             this.lines = lc;
         }
     }
-    public int getDuration() { return pts_end - pts_start + 1; }
+
+    @Override
+    public void release() {} // nothing to be released back to the owner
 
     @Override
     public String toString() {
-        return "ASS["+source+", #"+seqnr+", l_"+layer+", ["+pts_start+".."+pts_end+"] "+getDuration()+" ms, style "+style+", name '"+name+"': '"+text+"' ("+lines+")]";
+        return getStartString()+", #"+seqnr+", l_"+layer+", style "+style+", name '"+name+"': '"+text+"' ("+lines+")]";
     }
 }
diff --git a/src/jogl/classes/com/jogamp/opengl/util/av/SubEmptyEvent.java b/src/jogl/classes/com/jogamp/opengl/util/av/SubEmptyEvent.java
new file mode 100644
index 000000000..e97128a71
--- /dev/null
+++ b/src/jogl/classes/com/jogamp/opengl/util/av/SubEmptyEvent.java
@@ -0,0 +1,47 @@
+/**
+ * Copyright 2024 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 com.jogamp.opengl.util.av;
+
+/** Empty {@link SubtitleEvent}, used for PGS bitmap subtitle signaling end of previous {@link SubTextureEvent}. */
+public class SubEmptyEvent extends SubtitleEvent {
+
+    /**
+     * Empty event ctor
+     */
+    public SubEmptyEvent(final int pts_start, final int pts_end) {
+        super(Format.EMPTY, pts_start, pts_end);
+    }
+
+    @Override
+    public void release() {} // nothing to be released back to the owner
+
+    @Override
+    public String toString() {
+        return getStartString()+"]";
+    }
+}
\ No newline at end of file
diff --git a/src/jogl/classes/com/jogamp/opengl/util/av/SubTextureEvent.java b/src/jogl/classes/com/jogamp/opengl/util/av/SubTextureEvent.java
new file mode 100644
index 000000000..86da736d6
--- /dev/null
+++ b/src/jogl/classes/com/jogamp/opengl/util/av/SubTextureEvent.java
@@ -0,0 +1,87 @@
+/**
+ * Copyright 2024 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 com.jogamp.opengl.util.av;
+
+import com.jogamp.math.Vec2i;
+import com.jogamp.opengl.util.texture.Texture;
+
+/**
+ * {@link Texture} event of {@link SubtitleEvent}
+ * <p>
+ * Consider {@link SubtitleEvent#pts_end} and {@link SubEmptyEvent}.
+ * </p>
+ */
+public class SubTextureEvent extends SubtitleEvent {
+    /** To be implemented by the {@link Texture} owner to release the texture. */
+    public static interface TextureOwner {
+        /** The given {@link Texture} is to be released by the owner. */
+        void release(Texture tex);
+    }
+    /** Subtitle texture position */
+    public final Vec2i position;
+    /** Subtitle texture dimension */
+    public final Vec2i dimension;
+    /** Subtitle texture or {@code null} if unused */
+    public Texture texture;
+    private final TextureOwner owner;
+
+    /**
+     * Texture Event ctor
+     * @param pos texture position
+     * @param dim texture dimension
+     * @param tex the {@link Texture} or {@code null} if unused
+     * @param pts_start pts start in ms, provided for {@link SubTextureEvent.Format#ASS_FFMPEG} and {@link SubTextureEvent.Format#ASS_TEXT}
+     * @param pts_end pts end in ms, provided for {@link SubTextureEvent.Format#ASS_FFMPEG} and {@link SubTextureEvent.Format#ASS_TEXT}
+     * @param owner {@link Texture} owner code-stub to release the texture
+     */
+    public SubTextureEvent(final Vec2i pos, final Vec2i dim, final Texture tex, final int pts_start, final int pts_end, final TextureOwner owner) {
+        super(Format.TEXTURE, pts_start, pts_end);
+        position = pos;
+        dimension = dim;
+        texture = tex;
+        this.owner = owner;
+    }
+    /**
+     * {@inheritDoc}
+     * <p>
+     * The {@link #texture} is released back to the owner
+     * </p>
+     */
+    @Override
+    public void release() {
+        final Texture t = texture;
+        texture = null;
+        if( null != t ) {
+            owner.release(t);
+        }
+    }
+    @Override
+    public String toString() {
+        return getStartString()+", pos "+position+", dim "+dimension+", "+texture+"]";
+    }
+}
diff --git a/src/jogl/classes/com/jogamp/opengl/util/av/SubtitleEvent.java b/src/jogl/classes/com/jogamp/opengl/util/av/SubtitleEvent.java
new file mode 100644
index 000000000..ffae7542b
--- /dev/null
+++ b/src/jogl/classes/com/jogamp/opengl/util/av/SubtitleEvent.java
@@ -0,0 +1,65 @@
+package com.jogamp.opengl.util.av;
+
+/**
+ * Generic subtitle event
+ * <p>
+ * It is mandatory that the receiver {@link #release()} this instance
+ * after processing, allowing the resource owner to free or reuse it.
+ * </p>
+ */
+public abstract class SubtitleEvent {
+    public enum Format {
+        /** Denoting an {@link SubEmptyEvent}, usually used for PGS bitmap subtitle signaling end of previous {@link SubTextureEvent}. */
+        EMPTY,
+        /** Denoting {@link SubASSEventLine} using FFMpeg output w/o start, end:
+         * <pre>
+           0    1      2      3     4        5        6        7       8
+           Seq, Layer, Style, Name, MarginL, MarginR, MarginV, Effect, TEXT
+         * </pre>
+         */
+        ASS_FFMPEG,
+        /** Denoting {@link SubASSEventLine}, just the plain text part */
+        ASS_TEXT,
+        /** Denoting {@link SubTextureEvent}, a bitmap'ed subtitle requiring a texture */
+        TEXTURE
+    };
+
+    /** {@link Format} of this subtitle event. */
+    public final Format type;
+    /** PTS start time to start showing this subtitle event. */
+    public final int pts_start;
+    /**
+     * PTS start time to end showing this subtitle event.
+     * <p>
+     * PGS {@link SubTextureEvent} have an infinite end-time, i.e. ({@link Integer#MAX_VALUE},
+     * and shall be overwritten by the next one or {@link SubEmptyEvent}.
+     * </p>
+     * @see #isEndDefined()
+     */
+    public final int pts_end;
+
+    public SubtitleEvent(final Format fmt, final int pts_start, final int pts_end) {
+        this.type = fmt;
+        this.pts_start = pts_start;
+        this.pts_end = pts_end;
+    }
+
+    /** Release the resources, if any, back to the owner. */
+    public abstract void release();
+
+    public final int getDuration() { return pts_end - pts_start + 1; }
+
+    /** See {@link #pts_end}. */
+    public final boolean isEndDefined() { return pts_end < Integer.MAX_VALUE; }
+
+    public final boolean isASS() { return Format.ASS_FFMPEG == type || Format.ASS_TEXT == type; }
+    public final boolean isTexture() { return Format.TEXTURE == type; }
+    public final boolean isEmpty() { return Format.EMPTY == type; }
+
+    public final String getStartString() {
+        final boolean ied = isEndDefined();
+        return "Sub["+type+", ["+pts_start+".."+(ied?pts_end:"undef")+"] "+(ied?getDuration():"undef")+" ms";
+    }
+
+
+}
\ No newline at end of file
diff --git a/src/jogl/classes/com/jogamp/opengl/util/av/ASSEventListener.java b/src/jogl/classes/com/jogamp/opengl/util/av/SubtitleEventListener.java
index 3baf6b69c..d319e6dc0 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/av/ASSEventListener.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/av/SubtitleEventListener.java
@@ -28,8 +28,13 @@
 package com.jogamp.opengl.util.av;
 
 /**
- * {@link ASSEventLine} Listener
+ * {@link SubtitleEvent} Listener
+ * <p>
+ * It is mandatory that the receiver {@link SubtitleEvent#release()} the instance
+ * after processing, allowing the resource owner to free or reuse it.
+ * </p>
  */
-public interface ASSEventListener {
-    void run(ASSEventLine e);
+public interface SubtitleEventListener {
+    /** Performing custom tasks with given {@link SubtitleEvent}. */
+    void run(SubtitleEvent e);
 }