Buffer api (#97)

* add methods to Buffer for setPresentationTimestamp() setDuration(), setOffset(), and setFlags()

* new MainLoop constructor that takes a GMainContext as an argument (needed for things like gst-rtsp-server framework)

* add more setters/getters for the GstBuffer representation; plus a unit test

* rewrite BufferFlag.java to match the GstBufferFlags enum from gstreamer 1.12.3

* rewrite MiniObjectFlags.java to match the GstMiniObjectFlags enum from gstreamer 1.12.3

Author: mutantbob

src/org/freedesktop/gstreamer/Buffer.java

@@ -168,6 +168,15 @@ public ClockTime getDecodeTimestamp() {
 		return (ClockTime)this.struct.readField("dts");
     }
 
+    /**
+     * Set the decode timestamp of the Buffer
+     * @param val a ClockTime representing the timestamp or {@link ClockTime#NONE} when the timestamp is not known or relevant.
+     */
+    public void setDecodeTimestamp(ClockTime val)
+    {
+        this.struct.writeField("dts", val);
+    }
+
     /**
      * Gets the timestamps of this buffer.
      * The buffer PTS refers to the timestamp when the buffer content should be presented to the user and is not always monotonically increasing.
@@ -178,4 +187,98 @@ public ClockTime getPresentationTimestamp() {
 		return (ClockTime)this.struct.readField("pts");
     }
 
+    /**
+     * Set the presentation timestamp of the Buffer
+     * @param val a ClockTime representing the timestamp or {@link ClockTime#NONE} when the timestamp is not known or relevant.
+     */
+    public void setPresentationTimestamp(ClockTime val)
+    {
+        this.struct.writeField("pts", val);
+    }
+
+    /**
+     * Gets the duration of this buffer.
+     *
+     * @return a ClockTime representing the timestamp or {@link ClockTime#NONE} when the timestamp is not known or relevant.
+     */
+    public ClockTime getDuration() {
+        return (ClockTime)this.struct.readField("duration");
+    }
+
+    /**
+     * Set the duration of this buffer.
+     * @param val a ClockTime representing the duration or {@link ClockTime#NONE} when the timestamp is not known or relevant.
+     */
+    public void setDuration(ClockTime val)
+    {
+        this.struct.writeField("duration", val);
+    }
+
+    /**
+     * Get the offset (media-specific) of this buffer
+     * @return a media specific offset for the buffer data. For video frames, this is the frame number of this buffer. For audio samples, this is the offset of the first sample in this buffer. For file data or compressed data this is the byte offset of the first byte in this buffer.
+     */
+    public long getOffset()
+    {
+        return (Long)this.struct.readField("offset");
+    }
+
+    /**
+     * Set the offset (media-specific) of this buffer
+     * @param val a media specific offset for the buffer data. For video frames, this is the frame number of this buffer. For audio samples, this is the offset of the first sample in this buffer. For file data or compressed data this is the byte offset of the first byte in this buffer.
+     */
+    public void setOffset(long val)
+    {
+        this.struct.writeField("offset", val);
+    }
+
+    /**
+     * Get the offset (media-specific) of this buffer
+     * @return a media specific offset for the buffer data. For video frames, this is the frame number of this buffer. For audio samples, this is the offset of the first sample in this buffer. For file data or compressed data this is the byte offset of the first byte in this buffer.
+     */
+    public long getOffsetEnd()
+    {
+        return (Long)this.struct.readField("offset_end");
+    }
+
+    /**
+     * Set the offset (media-specific) of this buffer
+     * @param val a media specific offset for the buffer data. For video frames, this is the frame number of this buffer. For audio samples, this is the offset of the first sample in this buffer. For file data or compressed data this is the byte offset of the first byte in this buffer.
+     */
+    public void setOffsetEnd(long val)
+    {
+        this.struct.writeField("offset_end", val);
+    }
+
+    /**
+     * get the GstBufferFlags describing this buffer
+     * @return a bit mask whose values can be interpreted by comparing them with {@link BufferFlag}
+     */
+    public int getFlags()
+    {
+        return GstBufferAPI.GSTBUFFER_API.gst_buffer_get_flags(this);
+    }
+
+    /**
+     * set some of the GstBufferFlags describing this buffer.  This is a union operation and does not clear flags that are not mentioned in val
+     * @param val a bit mask of flags to be set on the buffer.  bits which are zero in val do not get cleared in this buffer.
+     * @return true if flags were successfully set on this buffer
+     * @see BufferFlag
+     */
+    public boolean setFlags(int val)
+    {
+        return GstBufferAPI.GSTBUFFER_API.gst_buffer_set_flags(this, val);
+    }
+
+    /**
+     * unset the GstBufferFlags describing this buffer.  This is a difference operation and does not clear flags that are not mentioned in val
+     * @param val a bit mask of flags to be cleared on the buffer.  bits which are zero in val do not get cleared in this buffer.
+     * @return true if flags were successfully cleared on this buffer
+     * @see BufferFlag
+     * */
+    public boolean unsetFlags(int val)
+    {
+        return GstBufferAPI.GSTBUFFER_API.gst_buffer_unset_flags(this, val);
+    }
+
 }

src/org/freedesktop/gstreamer/BufferFlag.java

@@ -27,39 +27,74 @@
  * A set of buffer flags used to describe properties of a {@link Buffer}.
  */
 public enum BufferFlag implements IntegerEnum {
-    /** 
-     * The {@link Buffer} is read-only.
-     * This means the data of the buffer should not be modified. The metadata 
-     * might still be modified.
-     */
-    READONLY(MiniObjectFlags.READONLY.intValue()),
-    
+
     /**  
-     * The {@link Buffer} is part of a preroll and should not be displayed.
+     * the {@link Buffer} is live data and should be discarded in the PAUSED state.
+     */
+    LIVE(MiniObjectFlags.LAST.intValue() << 0),
+
+    /**
+     * the {@link Buffer} contains data that should be dropped
+     * because it will be clipped against the segment
+     * boundaries or because it does not contain data
+     * that should be shown to the user.
      */
-    PREROLL(MiniObjectFlags.LAST.intValue() << 0),
+    DECODE_ONLY(MiniObjectFlags.LAST.intValue() << 1),
+
     /**
      * The {@link Buffer} marks a discontinuity in the stream.
      * This typically occurs after a seek or a dropped buffer from a live or
      * network source.
      */
-    DISCONT(MiniObjectFlags.LAST.intValue() << 1),
-    
-    /** The {@link Buffer} has been added as a field in a {@link Caps}. */
-    IN_CAPS(MiniObjectFlags.LAST.intValue() << 2),
-    
+    DISCONT(MiniObjectFlags.LAST.intValue() << 2),
+
+    /**
+     * The {@link Buffer} timestamps might have a discontinuity and this buffer is a good point to resynchronize.
+     */
+    RESYNC(MiniObjectFlags.LAST.intValue() << 3),
+
+    /**
+     * the {@link Buffer} data is corrupted.
+     */
+    CORRUPTED(MiniObjectFlags.LAST.intValue() << 4),
+
+    /**
+     * the buffer contains a media specific marker. for video this is typically the end of a frame boundary, for audio this is usually the start of a talkspurt.
+     */
+    MARKER(MiniObjectFlags.LAST.intValue() << 5),
+
+    /**
+     * he buffer contains header information that is needed to decode the following data.
+     */
+    HEADER(MiniObjectFlags.LAST.intValue() << 6),
+
     /**
      * The {@link Buffer} has been created to fill a gap in the
      * stream and contains media neutral data (elements can switch to optimized code
      * path that ignores the buffer content).
      */
-    GAP(MiniObjectFlags.LAST.intValue() << 3),
+    GAP(MiniObjectFlags.LAST.intValue() << 7),
+
+    /**
+     * the {@link Buffer} can be dropped without breaking the stream, for example to reduce bandwidth.
+     */
+    DROPPABLE(MiniObjectFlags.LAST.intValue() << 8),
 
     /** This unit cannot be decoded independently. */
-    DELTA_UNIT(MiniObjectFlags.LAST.intValue() << 4),
+    DELTA_UNIT(MiniObjectFlags.LAST.intValue() << 9),
+
+    /**
+     * this flag is set when memory of the {@link Buffer} is added/removed
+     */
+    TAG_MEMORY(MiniObjectFlags.LAST.intValue() << 10),
+
+    /**
+     * Elements which write to disk or permanent storage should ensure the data is synced after writing the contents of this {@link Buffer}. (Since 1.6)
+     */
+    SYNC_AFTER(MiniObjectFlags.LAST.intValue() << 11),
 
     /* padding */
-    LAST(MiniObjectFlags.LAST.intValue() << 8),
+    LAST(MiniObjectFlags.LAST.intValue() << 16),
 
     /** The value used for unknown native values */
     @DefaultEnumValue

src/org/freedesktop/gstreamer/MiniObject.java

@@ -55,10 +55,11 @@ public static GType getType(Pointer ptr) {
     }
 
     /**
-     * Checks if a mini-object is writable.  A mini-object is writable
-     * if the reference count is one and the {@link MiniObjectFlags#READONLY}
-     * flag is not set.  Modification of a mini-object should only be
-     * done after verifying that it is writable.
+     * If mini_object has the LOCKABLE flag set, check if the current EXCLUSIVE lock on object is the only one, this means that changes to the object will not be visible to any other object.
+     *
+     * <p></p>If the LOCKABLE flag is not set, check if the refcount of mini_object is exactly 1, meaning that no other reference exists to the object and that the object is therefore writable.
+     *
+     * <p></p>Modification of a mini-object should only be done after verifying that it is writable.
      *
      * @return true if the object is writable.
      */

src/org/freedesktop/gstreamer/MiniObjectFlags.java

@@ -24,8 +24,20 @@
  *
  */
 public enum MiniObjectFlags implements IntegerEnum {
-    /** The {@link MiniObject} is read-only */
-    READONLY(1 << 0),
+    /**
+     * the object can be locked and unlocked with gst_mini_object_lock() and gst_mini_object_unlock()
+     * */
+    LOCKABLE(1 << 0),
+
+    /**
+     * the object is permanently locked in READONLY mode. Only read locks can be performed on the object.
+     */
+    LOCK_READONLY(1<<1),
+
+    /**
+     * the object is expected to stay alive even after gst_deinit() has been called and so should be ignored by leak detection tools. (Since 1.10)
+     */
+    MAY_BE_LEAKED(1<<2),
 
     /** The last valid MiniObject flag */
     LAST(1 << 4);

src/org/freedesktop/gstreamer/lowlevel/GstBufferAPI.java

@@ -75,6 +75,9 @@ protected List<String> getFieldOrder() {
     void gst_buffer_unmap(Buffer buffer, MapInfoStruct info);
     int gst_buffer_n_memory(Buffer buffer);
     boolean gst_buffer_map_range(Buffer buffer, int idx, int length, MapInfoStruct info, int flags);
+    int gst_buffer_get_flags(Buffer buffer);
+    boolean gst_buffer_set_flags(Buffer buffer, int flags);
+    boolean gst_buffer_unset_flags(Buffer buffer, int flags);
 //    boolean gst_buffer_is_metadata_writable(Buffer buf);
 //    Buffer gst_buffer_make_metadata_writable(@Invalidate Buffer buf);
 //    /* creating a subbuffer */

src/org/freedesktop/gstreamer/lowlevel/MainLoop.java

@@ -45,7 +45,10 @@ public class MainLoop extends RefCountedObject {
     public MainLoop() {
         super(initializer(GLIB_API.g_main_loop_new(Gst.getMainContext(), false)));
     }
-    
+
+    public MainLoop(GMainContext ctx) {
+        super(initializer(GLIB_API.g_main_loop_new(ctx, false)));
+    }
     /**
      * Creates a new instance of {@code MainLoop}
      * 

test/org/freedesktop/gstreamer/BufferFieldsTest.java

@@ -0,0 +1,86 @@
+package org.freedesktop.gstreamer;
+
+import org.junit.*;
+import static org.junit.Assert.*;
+
+/**
+ * <p>Copyright (C) 2018 Robert Forsman, Ericsson SATV
+ * $Author thoth $
+ * $Date 3/8/18 $
+ */
+public class BufferFieldsTest
+{
+    @BeforeClass
+    public static void setUpClass() throws Exception {
+        Gst.init("BufferFieldsTest", new String[] {});
+    }
+
+    @AfterClass
+    public static void tearDownClass() throws Exception {
+        Gst.deinit();
+    }
+
+    private Buffer buf;
+
+    @Before
+    public void setUp()
+    {
+        buf = new Buffer(12);
+    }
+
+    @Test
+    public void setPTS()
+    {
+        buf.setPresentationTimestamp(ClockTime.fromMicros(5004003));
+        ClockTime val = buf.getPresentationTimestamp();
+        assertEquals(5004003, val.toMicros());
+    }
+
+    @Test
+    public void setDTS()
+    {
+        buf.setDecodeTimestamp(ClockTime.fromMicros(9001004));
+        ClockTime val = buf.getDecodeTimestamp();
+        assertEquals(9001004, val.toMicros());
+    }
+
+    @Test
+    public void setDuration()
+    {
+        buf.setDuration(ClockTime.fromMicros(4006008));
+        ClockTime val = buf.getDuration();
+        assertEquals(4006008, val.toMicros());
+    }
+
+    @Test
+    public void setOffset()
+    {
+        buf.setOffset(2009006);
+        long val = buf.getOffset();
+        assertEquals(2009006, val);
+    }
+
+    @Test
+    public void setOffsetEnd()
+    {
+        buf.setOffsetEnd(7005003);
+        long val = buf.getOffsetEnd();
+        assertEquals(7005003, val);
+    }
+
+    @Test
+    public void setFlags()
+    {
+        assertTrue(buf.setFlags(7));
+        int val = buf.getFlags();
+        assertEquals(7, val);
+
+        assertTrue(buf.setFlags(10));
+        val = buf.getFlags();
+        assertEquals(15, val);
+
+        assertTrue(buf.unsetFlags(20));
+        val = buf.getFlags();
+        assertEquals(11, val);
+    }
+}

test/org/freedesktop/gstreamer/PluginTest.java

@@ -76,7 +76,9 @@ public void testGetSource() {
 
     @Test
     public void testGetPackage() {
-        assertTrue(playbackPlugin.getPackage().contains("GStreamer Base"));
+        String pkg = playbackPlugin.getPackage();
+        assertTrue(pkg.contains("GStreamer Base")
+                   || pkg.contains("Gentoo GStreamer"));
     }
 
     @Test