Update and document org.freedesktop.gstreamer.event package.

Author: neilcsmith-net

src/org/freedesktop/gstreamer/event/BufferSizeEvent.java

@@ -1,4 +1,5 @@
 /* 
+ * Copyright (c) 2019 Neil C Smith
  * Copyright (c) 2008 Wayne Meissner
  * Copyright (C) 1999,2000 Erik Walthinsen <[email protected]>
  *                    2000 Wim Taymans <[email protected]>
@@ -18,92 +19,91 @@
  * You should have received a copy of the GNU Lesser General Public License
  * version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
  */
-
 package org.freedesktop.gstreamer.event;
 
 import org.freedesktop.gstreamer.Format;
 
-import org.freedesktop.gstreamer.lowlevel.GstEventAPI;
+import static org.freedesktop.gstreamer.lowlevel.GstEventAPI.GSTEVENT_API;
 
 /**
- * Notification of new latency adjustment.
+ * A buffersize event. The event is sent downstream and notifies elements that
+ * they should provide a buffer of the specified dimensions.
  * <p>
- * The event is sent upstream from the sinks and
- * notifies elements that they should add an additional latency to the
- * timestamps before synchronising against the clock.
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstEvent.html#gst-event-new-buffer-size"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstEvent.html#gst-event-new-buffer-size</a>
  * <p>
- * The latency is mostly used in live sinks and is always expressed in
- * the time format.
+ * When the async flag is set, a thread boundary is preferred.
  */
 public class BufferSizeEvent extends Event {
 
-    private static final GstEventAPI gst = GstEventAPI.GSTEVENT_API;
-    
     /**
      * This constructor is for internal use only.
+     *
      * @param init initialization data.
      */
-    public BufferSizeEvent(Initializer init) {
+    BufferSizeEvent(Initializer init) {
         super(init);
     }
-    
+
     /**
-     * Creates a new buffersize event. 
-     * <p> The event is sent downstream and notifies elements that they should 
+     * Creates a new buffersize event.
+     * <p>
+     * The event is sent downstream and notifies elements that they should
      * provide a buffer of the specified dimensions.
+     * <p>
+     * When the <tt>async</tt> flag is set, a thread boundary is preferred.
      *
-     * <p> When the <tt>async</tt> flag is set, a thread boundary is preferred.
-     * 
      * @param format buffer format
      * @param minsize minimum buffer size
      * @param maxsize maximum buffer size
-     * @param async thread behavior
+     * @param async thread behaviour
      */
     public BufferSizeEvent(Format format, long minsize, long maxsize, boolean async) {
-        super(initializer(gst.ptr_gst_event_new_buffer_size(format, minsize, maxsize, async)));
+        super(initializer(GSTEVENT_API.ptr_gst_event_new_buffer_size(format, minsize, maxsize, async)));
     }
-    
+
     /**
      * Gets the format of the buffersize event.
-     * 
+     *
      * @return the format.
      */
     public Format getFormat() {
         Format[] format = new Format[1];
-        gst.gst_event_parse_buffer_size(this, format, null, null, null);
+        GSTEVENT_API.gst_event_parse_buffer_size(this, format, null, null, null);
         return format[0];
     }
-    
+
     /**
      * Gets the minimum buffer size.
-     * 
+     *
      * @return the minimum buffer size.
      */
     public long getMinimumSize() {
-        long[] size = { 0 };
-        gst.gst_event_parse_buffer_size(this, null, size, null, null);
+        long[] size = {0};
+        GSTEVENT_API.gst_event_parse_buffer_size(this, null, size, null, null);
         return size[0];
     }
-    
+
     /**
      * Gets the maximum buffer size.
-     * 
+     *
      * @return the maximum buffer size.
      */
     public long getMaximumSize() {
-        long[] size = { 0 };
-        gst.gst_event_parse_buffer_size(this, null, null, size, null);
+        long[] size = {0};
+        GSTEVENT_API.gst_event_parse_buffer_size(this, null, null, size, null);
         return size[0];
     }
-    
+
     /**
      * Gets the preferred thread behaviour.
-     * 
+     *
      * @return <tt>true</tt> if a thread boundary is preferred.
      */
     public boolean isAsync() {
-        boolean[] async = { false };
-        gst.gst_event_parse_buffer_size(this, null, null, null, async);
+        boolean[] async = {false};
+        GSTEVENT_API.gst_event_parse_buffer_size(this, null, null, null, async);
         return async[0];
     }
 }

src/org/freedesktop/gstreamer/event/CapsEvent.java

@@ -1,4 +1,5 @@
 /*
+ * Copyright (c) 2019 Neil C Smith
  * Copyright (c) 2016 Christophe Lafolet
  *
  * This file is part of gstreamer-java.
@@ -15,30 +16,36 @@
  * You should have received a copy of the GNU Lesser General Public License
  * version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
  */
-
 package org.freedesktop.gstreamer.event;
 
-
 import org.freedesktop.gstreamer.Caps;
-import org.freedesktop.gstreamer.lowlevel.GstEventAPI;
-
+import static org.freedesktop.gstreamer.lowlevel.GstEventAPI.GSTEVENT_API;
 
+/**
+ * A CAPS event for {@link Caps}. The caps event can only travel downstream
+ * synchronized with the buffer flow and contains the format of the buffers that
+ * will follow after the event.
+ * <p>
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstEvent.html#gst-event-new-caps"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstEvent.html#gst-event-new-caps</a>
+ * <p>
+ */
 public class CapsEvent extends Event {
-	
-    private static final GstEventAPI gst = GstEventAPI.GSTEVENT_API;
 
     /**
      * This constructor is for internal use only.
+     *
      * @param init initialization data.
      */
-    public CapsEvent(Initializer init) {
+    CapsEvent(Initializer init) {
         super(init);
     }
 
     /**
      * Creates a new caps event.
      */
     public CapsEvent(final Caps caps) {
-        super(initializer(gst.ptr_gst_event_new_caps(caps)));
+        super(initializer(GSTEVENT_API.ptr_gst_event_new_caps(caps)));
     }
-}
+}

src/org/freedesktop/gstreamer/event/EOSEvent.java

@@ -1,4 +1,5 @@
 /* 
+ * Copyright (c) 2019 Neil C Smith
  * Copyright (c) 2008 Wayne Meissner
  * Copyright (C) 1999,2000 Erik Walthinsen <[email protected]>
  *                    2000 Wim Taymans <[email protected]>
@@ -18,42 +19,47 @@
  * You should have received a copy of the GNU Lesser General Public License
  * version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
  */
-
 package org.freedesktop.gstreamer.event;
 
-import org.freedesktop.gstreamer.lowlevel.GstEventAPI;
+import org.freedesktop.gstreamer.Bus;
+import org.freedesktop.gstreamer.FlowReturn;
+import static org.freedesktop.gstreamer.lowlevel.GstEventAPI.GSTEVENT_API;
 
 /**
- * End-Of-Stream. No more data is to be expected to follow without a {@link NewSegmentEvent}.
+ * End-Of-Stream event.
+ * <p>
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstEvent.html#gst-event-new-eos"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstEvent.html#gst-event-new-eos</a>
  * <p>
- * The eos event can only travel downstream
- * synchronized with the buffer flow. Elements that receive the EOS
- * event on a pad can return {@link org.gstreamer.FlowReturn#UNEXPECTED} when data after 
- * the EOS event arrives.
+ * The eos event can only travel downstream synchronized with the buffer flow.
+ * Elements that receive the EOS event on a pad can return
+ * {@link FlowReturn#EOS} when data after the EOS event arrives.
  * <p>
- * The EOS event will travel down to the sink elements in the pipeline
- * which will then post the {@link org.gstreamer.Bus.EOS} message on the bus after they have
+ * The EOS event will travel down to the sink elements in the pipeline which
+ * will then post the {@link Bus.EOS } message on the bus after they have
  * finished playing any buffered data.
  * <p>
- * When all sinks have posted an EOS message, an EOS message is
- * forwarded to the application.
+ * When all sinks have posted an EOS message, an EOS message is forwarded to the
+ * application.
+ * <p>
+ * The EOS event itself will not cause any state transitions of the pipeline.
  */
 public class EOSEvent extends Event {
 
-    private static final GstEventAPI gst = GstEventAPI.GSTEVENT_API;
-    
     /**
      * This constructor is for internal use only.
+     *
      * @param init initialization data.
      */
-    public EOSEvent(Initializer init) {
+    EOSEvent(Initializer init) {
         super(init);
     }
-    
+
     /**
-     * Creates a new EOS event. 
+     * Creates a new EOS event.
      */
     public EOSEvent() {
-        super(initializer(gst.ptr_gst_event_new_eos()));
+        super(initializer(GSTEVENT_API.ptr_gst_event_new_eos()));
     }
-}
+}

src/org/freedesktop/gstreamer/event/EventType.java

@@ -19,22 +19,24 @@
 
 package org.freedesktop.gstreamer.event;
 
-import org.freedesktop.gstreamer.lowlevel.EnumMapper;
+import org.freedesktop.gstreamer.Gst;
+import org.freedesktop.gstreamer.glib.NativeEnum;
 import org.freedesktop.gstreamer.lowlevel.annotations.DefaultEnumValue;
 
-import static org.freedesktop.gstreamer.lowlevel.GstEventAPI.GSTEVENT_API;
-import org.freedesktop.gstreamer.glib.NativeFlags;
-
 /**
  * The standard event types that can be sent in a pipeline.
  * <p>
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstEvent.html#GstEventType"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstEvent.html#GstEventType</a>
+ * <p>
  * The custom event types can be used for private messages between elements
  * that can't be expressed using normal GStreamer buffer passing semantics. 
  * <p>
  * Custom events carry an arbitrary {@link Structure}.  Specific custom events 
  * are distinguished by the name of the structure.
  */
-public enum EventType implements NativeFlags {
+public enum EventType implements NativeEnum<EventType> {
     /** Unknown event */
     @DefaultEnumValue UNKNOWN(0, 0),
 
@@ -67,6 +69,11 @@ public enum EventType implements NativeFlags {
      * running-time and stream-time.
      */
     SEGMENT(70, Flags.DOWNSTREAM | Flags.SERIALIZED | Flags.STICKY),
+    /**
+     * A new #GstStreamCollection is available (Since 1.10)
+     */
+    @Gst.Since(minor = 10)
+    STREAM_COLLECTION(75, Flags.DOWNSTREAM | Flags.SERIALIZED | Flags.STICKY | Flags.STICKY_MULTI),
     /**
      * A new set of metadata tags has been found in the stream.
      */
@@ -80,6 +87,13 @@ public enum EventType implements NativeFlags {
      * should be emitted in sync with rendering.
      */
     SINK_MESSAGE(100, Flags.DOWNSTREAM | Flags.SERIALIZED | Flags.STICKY | Flags.STICKY_MULTI),
+    /**
+     * Indicates that there is no more data for the stream group ID in the
+     * message. Sent before EOS in some instances and should be handled mostly
+     * the same. (Since 1.10)
+     */
+    @Gst.Since(minor = 10)
+    STREAM_GROUP_DONE(105, Flags.DOWNSTREAM | Flags.SERIALIZED | Flags.STICKY),
     /**
      * End-Of-Stream. No more data is to be expected to follow without a SEGMENT
      * event.
@@ -139,7 +153,11 @@ public enum EventType implements NativeFlags {
      * A request for a new playback position based on TOC entry's UID.
      */
     TOC_SELECT(250, Flags.UPSTREAM),
-
+    /**
+     * A request to select one or more streams (Since 1.10)
+     */
+    @Gst.Since(minor = 10)
+    SELECT_STREAMS(260, Flags.UPSTREAM),
     /* custom events start here */
     /**
      * Upstream custom event
@@ -167,25 +185,19 @@ public enum EventType implements NativeFlags {
     CUSTOM_BOTH_OOB(320, Flags.BOTH)
     ;
 
-    EventType(int num, int flags) {
+    private static final int SHIFT = 8;
+    
+    private final int value;
+    
+    private EventType(int num, int flags) {
         this.value = (num << SHIFT) | flags;
     }
 
-    /** Gets the native value of this enum */
+    @Override
     public int intValue() {
         return value;
     }
-    /** Gets a human-readable name for this value */
-    public String getName() {
-        return GSTEVENT_API.gst_event_type_get_name(this);
-    }
 
-    /** Gets the Enum for a native value */
-    public static final EventType valueOf(int type) {
-        return EnumMapper.getInstance().valueOf(type, EventType.class);
-    }
-    
-    private static final int SHIFT = 8;
     private static final class Flags {
         public static final int UPSTREAM       = 1 << 0;
         public static final int DOWNSTREAM     = 1 << 1;
@@ -194,5 +206,4 @@ private static final class Flags {
         public static final int STICKY_MULTI   = 1 << 4;
         public static final int BOTH = UPSTREAM | DOWNSTREAM;
     }
-    private final int value;
 }