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

Author: neilcsmith-net

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

@@ -51,7 +51,7 @@
 public class GTypeMapper extends com.sun.jna.DefaultTypeMapper {
 
     public GTypeMapper() {
-        addTypeConverter(QueryType.class, querytypeConverter);
+//        addTypeConverter(QueryType.class, querytypeConverter);
         addToNativeConverter(URI.class, uriConverter);
         addTypeConverter(ClockTime.class, clocktimeConverter);
     }
@@ -234,20 +234,20 @@ public Class<?> nativeType() {
             return Native.POINTER_SIZE == 8 ? Long.class : Integer.class;
         }
     };
-    private TypeConverter querytypeConverter = new TypeConverter() {
-        
-        public Object toNative(Object arg, ToNativeContext context) {
-            return ((QueryType)arg).intValue();
-        }
-
-        public Object fromNative(Object arg0, FromNativeContext arg1) {
-            return QueryType.valueOf(((Number) arg0).intValue());            
-        }
-
-        public Class<?> nativeType() {
-            return Integer.class;
-        }
-    };
+//    private TypeConverter querytypeConverter = new TypeConverter() {
+//        
+//        public Object toNative(Object arg, ToNativeContext context) {
+//            return ((QueryType)arg).intValue();
+//        }
+//
+//        public Object fromNative(Object arg0, FromNativeContext arg1) {
+//            return QueryType.valueOf(((Number) arg0).intValue());            
+//        }
+//
+//        public Class<?> nativeType() {
+//            return Integer.class;
+//        }
+//    };
     private static ToNativeConverter uriConverter = new ToNativeConverter() {
 
         public Object toNative(Object arg0, ToNativeContext arg1) {

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

@@ -109,7 +109,7 @@ public static final class QueryStruct extends com.sun.jna.Structure {
         public volatile GstMiniObjectAPI.MiniObjectStruct mini_object;
 
         /*< public > *//* with COW */
-        public volatile int type;
+        public volatile QueryType type;
 
         public QueryStruct(Pointer ptr) {
             useMemory(ptr);

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

@@ -156,7 +156,7 @@ static class MapHolder {
             }};
             public static Class<? extends NativeObject> subtypeFor(Pointer ptr) {
                 GstQueryAPI.QueryStruct struct = new GstQueryAPI.QueryStruct(ptr);
-                QueryType type = QueryType.valueOf((Integer) struct.readField("type"));
+                QueryType type = (QueryType) struct.readField("type");
                 Class<? extends Query> queryClass = typeMap.get(type);
                 return queryClass != null ? queryClass : Query.class;
             }

src/org/freedesktop/gstreamer/query/AllocationQuery.java

@@ -1,4 +1,5 @@
 /*
+ * Copyright (c) 2019 Neil C Smith
  * Copyright (c) 2016 Christophe Lafolet
  *
  * This file is part of gstreamer-java.
@@ -26,40 +27,76 @@
 import com.sun.jna.Pointer;
 import org.freedesktop.gstreamer.lowlevel.NativeObject;
 
+/**
+ * An allocation query for querying allocation properties.
+ * <p>
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstQuery.html#gst-query-new-allocation"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstQuery.html#gst-query-new-allocation</a>
+ * <p>
+ *
+ */
 public class AllocationQuery extends Query {
+
     /**
      * This constructor is for internal use only.
+     *
      * @param init initialization data.
      */
-    public AllocationQuery(Initializer init) {
-    	// special case : no ref shall be added
-    	// the allocationQuery is an in/out parameter during query notification
-    	// so, we shall keep query writable for add methods
-        super(initializer(init.ptr, false, true));        
+    AllocationQuery(Initializer init) {
+        // special case : no ref shall be added
+        // the allocationQuery is an in/out parameter during query notification
+        // so, we shall keep query writable for add methods
+        super(initializer(init.ptr, false, true));
     }
 
+    /**
+     * Create a new allocation query.
+     *
+     * @param caps the negotiated {@link Caps}
+     * @param need_pool return a pool.
+     */
     public AllocationQuery(Caps caps, boolean need_pool) {
         this(initializer(GstQueryAPI.GSTQUERY_API.ptr_gst_query_new_allocation(caps, need_pool)));
     }
 
+    /**
+     * Whether a {@link BufferPool} is needed.
+     *
+     * @return true if BufferPool needed
+     */
     public boolean isPoolNeeded() {
-    	boolean[] need_pool = {false};
-    	GstQueryAPI.GSTQUERY_API.gst_query_parse_allocation(this, null, need_pool);
-    	return need_pool[0];
+        boolean[] need_pool = {false};
+        GstQueryAPI.GSTQUERY_API.gst_query_parse_allocation(this, null, need_pool);
+        return need_pool[0];
     }
 
+    /**
+     * Get the requested {@link Caps}
+     *
+     * @return requested Caps
+     */
     public Caps getCaps() {
-    	Pointer[] ptr = new Pointer[1];
-    	GstQueryAPI.GSTQUERY_API.gst_query_parse_allocation(this, ptr, null);
+        Pointer[] ptr = new Pointer[1];
+        GstQueryAPI.GSTQUERY_API.gst_query_parse_allocation(this, ptr, null);
 //    	return new Caps(new Initializer(ptr[0], false, true));
         return NativeObject.objectFor(ptr[0], Caps.class, false, true);
     }
 
-    public void addAllocationMeta(GType api, Structure params) {
-    	GstQueryAPI.GSTQUERY_API.gst_query_add_allocation_meta(this, api, params);
+    // @TODO how best not to expose GType?
+    void addAllocationMeta(GType api, Structure params) {
+        GstQueryAPI.GSTQUERY_API.gst_query_add_allocation_meta(this, api, params);
     }
 
-    public void addBufferPool(BufferPool pool, int size, int min_buffers, int max_buffers) {
-    	GstQueryAPI.GSTQUERY_API.gst_query_add_allocation_pool(this, pool, size, min_buffers, max_buffers);
+    /**
+     * Set the pool parameters of the query.
+     *
+     * @param pool the {@link BufferPool}
+     * @param size the buffer size
+     * @param min_buffers the min buffers
+     * @param max_buffers the max buffers
+     */
+    public void addAllocationPool(BufferPool pool, int size, int min_buffers, int max_buffers) {
+        GstQueryAPI.GSTQUERY_API.gst_query_add_allocation_pool(this, pool, size, min_buffers, max_buffers);
     }
 }

src/org/freedesktop/gstreamer/query/ConvertQuery.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,41 +19,86 @@
  * 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.query;
 
 import org.freedesktop.gstreamer.Format;
 import org.freedesktop.gstreamer.lowlevel.GstQueryAPI;
 
 /**
- * Convert values between formats
+ * A convert query used to ask for a conversion between one format and another.
+ * <p>
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstQuery.html#gst-query-new-convert"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstQuery.html#gst-query-new-convert</a>
+ * <p>
  */
 public class ConvertQuery extends Query {
 
-    public ConvertQuery(Initializer init) {
+    ConvertQuery(Initializer init) {
         super(init);
     }
+
+    /**
+     * Construct a new convert query object.
+     *
+     * @param srcFormat the source {@link Format} for the new query
+     * @param value the value to convert
+     * @param destFormat the target {@link Format}
+     */
     public ConvertQuery(Format srcFormat, long value, Format destFormat) {
         this(initializer(GstQueryAPI.GSTQUERY_API.ptr_gst_query_new_convert(srcFormat, value, destFormat)));
     }
+
+    /**
+     * Answer a convert query by setting the requested values.
+     *
+     * @param srcFormat the source {@link Format}
+     * @param srcValue the source value
+     * @param dstFormat the destination {@link Format}
+     * @param dstValue the destination value
+     */
     public void setConvert(Format srcFormat, long srcValue, Format dstFormat, long dstValue) {
         GstQueryAPI.GSTQUERY_API.gst_query_set_convert(this, srcFormat, srcValue, dstFormat, dstValue);
     }
+
+    /**
+     * Get the source {@link Format} of this query.
+     *
+     * @return source Format
+     */
     public Format getSourceFormat() {
         Format[] fmt = new Format[1];
         GstQueryAPI.GSTQUERY_API.gst_query_parse_convert(this, fmt, null, null, null);
         return fmt[0];
     }
+
+    /**
+     * Get the destination {@link Format} of this query.
+     *
+     * @return destination Format
+     */
     public Format getDestinationFormat() {
         Format[] fmt = new Format[1];
         GstQueryAPI.GSTQUERY_API.gst_query_parse_convert(this, null, null, fmt, null);
         return fmt[0];
     }
+
+    /**
+     * Get the source value of this query.
+     *
+     * @return source value
+     */
     public long getSourceValue() {
         long[] value = new long[1];
         GstQueryAPI.GSTQUERY_API.gst_query_parse_convert(this, null, value, null, null);
         return value[0];
     }
+
+    /**
+     * Get the destination value of this query.
+     *
+     * @return destination value
+     */
     public long getDestinationValue() {
         long[] value = new long[1];
         GstQueryAPI.GSTQUERY_API.gst_query_parse_convert(this, null, null, null, value);

src/org/freedesktop/gstreamer/query/DurationQuery.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,40 +19,50 @@
  * 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.query;
 
 import org.freedesktop.gstreamer.Format;
 import org.freedesktop.gstreamer.lowlevel.GstQueryAPI;
 
 /**
- * Used to query the total duration of a stream.
+ * A duration query used to get the total length of a stream.
+ * <p>
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstQuery.html#gst-query-new-duration"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstQuery.html#gst-query-new-duration</a>
+ * <p>
+ * @see Format
  */
 public class DurationQuery extends Query {
 
-    public DurationQuery(Initializer init) {
+    DurationQuery(Initializer init) {
         super(init);
     }
+
     /**
-     * Constructs a new stream duration query object to query in the given format. 
-     * A duration query will give the total length of the stream.
-     * 
+     * Constructs a new stream duration query object to query in the given
+     * format. A duration query will give the total length of the stream.
+     *
      * @param format the {@link Format} for this duration query.
      */
     public DurationQuery(Format format) {
         super(initializer(GstQueryAPI.GSTQUERY_API.ptr_gst_query_new_duration(format)));
     }
+
     /**
-     * Answers a duration query by setting the requested value in the given format.
+     * Answers a duration query by setting the requested value in the given
+     * format.
+     *
      * @param format the {@link Format} for the duration
      * @param duration the duration of the stream
      */
     public void setDuration(Format format, long duration) {
         GstQueryAPI.GSTQUERY_API.gst_query_set_duration(this, format, duration);
     }
+
     /**
      * Gets the format of this duration query.
-     * 
+     *
      * @return The {@link Format} of the duration value.
      */
     public Format getFormat() {
@@ -61,19 +72,20 @@ public Format getFormat() {
     }
 
     /**
-     * Gets the duration answer for this duration query.
-     * 
+     * Gets the duration answer for this query, in the format available from 
+     * {@link #getFormat() }
+     *
      * @return The total duration.
      */
     public long getDuration() {
         long[] duration = new long[1];
         GstQueryAPI.GSTQUERY_API.gst_query_parse_duration(this, null, duration);
         return duration[0];
     }
-    
+
     /**
      * Gets the duration as a user-readable string.
-     * 
+     *
      * @return A string representing the duration.
      */
     @Override