add GstQueryBuffers query

This query is used by buffer allocator, for example a video sink element,
to find out any minimum buffer requirements of upstream elements that uses
pad_alloc() to allocate buffers.  For example, some cameras may have need
for additional padding/boarder around the frame (for vstab), or some video
decoders may have requirements for a certain minimum number of buffers (so
they can hold refs to reference-frames)

4 files changed, 164 insertions, 3 deletions

diff --git a/gst/gstquark.c b/gst/gstquark.c
index 91a201271..0459b4e2c 100644
--- a/gst/gstquark.c
+++ b/gst/gstquark.c
@@ -50,7 +50,8 @@ static const gchar *_quark_strings[] = {
   "intermediate", "GstMessageStepStart", "active", "eos", "sink-message",
   "message", "GstMessageQOS", "running-time", "stream-time", "jitter",
   "quality", "processed", "dropped", "buffering-ranges", "GstMessageProgress",
-  "code", "text", "percent", "timeout"
+  "code", "text", "percent", "timeout",
+  "GstQueryBuffers", "caps", "count", "width", "height"
 };
 
 GQuark _priv_gst_quark_table[GST_QUARK_MAX];
diff --git a/gst/gstquark.h b/gst/gstquark.h
index 6e16ee5d7..350f9fc68 100644
--- a/gst/gstquark.h
+++ b/gst/gstquark.h
@@ -132,8 +132,13 @@ typedef enum _GstQuarkId
   GST_QUARK_TEXT = 103,
   GST_QUARK_PERCENT = 104,
   GST_QUARK_TIMEOUT = 105,
+  GST_QUARK_QUERY_BUFFERS = 106,
+  GST_QUARK_CAPS = 107,
+  GST_QUARK_COUNT = 108,
+  GST_QUARK_WIDTH = 109,
+  GST_QUARK_HEIGHT = 110,
 
-  GST_QUARK_MAX = 106
+  GST_QUARK_MAX = 111
 } GstQuarkId;
 
 extern GQuark _priv_gst_quark_table[GST_QUARK_MAX];
diff --git a/gst/gstquery.c b/gst/gstquery.c
index 2b1c38229..1d7f5f99b 100644
--- a/gst/gstquery.c
+++ b/gst/gstquery.c
@@ -96,6 +96,7 @@ static GstQueryTypeDefinition standard_definitions[] = {
   {GST_QUERY_BUFFERING, "buffering", "Buffering status", 0},
   {GST_QUERY_CUSTOM, "custom", "Custom query", 0},
   {GST_QUERY_URI, "uri", "URI of the source or sink", 0},
+  {GST_QUERY_BUFFERS, "buffers", "Minimum buffer requirements", 0},
   {GST_QUERY_NONE, NULL, NULL, 0}
 };
 
@@ -1490,3 +1491,143 @@ gst_query_parse_uri (GstQuery * query, gchar ** uri)
     *uri = g_value_dup_string (gst_structure_id_get_value (query->structure,
             GST_QUARK (URI)));
 }
+
+/**
+ * gst_query_new_buffers:
+ * @caps: the #GstCaps for the buffers that are going to be allocated
+ *
+ * Constructs a new buffer requirements query object to query buffer
+ * requirements for a particular caps.  Use gst_query_unref() when done
+ * with it.
+ *
+ * Returns: A #GstQuery
+ */
+GstQuery *
+gst_query_new_buffers (GstCaps * caps)
+{
+  GstQuery *query;
+  GstStructure *structure;
+
+  /* XXX could add size here, for linear (non YUV/RGB) buffers?  But I'm not
+   * entirely sure what is the use-case for that.. it should be easy enough
+   * to add more optional reply fields later
+   */
+  structure = gst_structure_id_new (GST_QUARK (QUERY_BUFFERS),
+      GST_QUARK (CAPS), GST_TYPE_CAPS, caps,
+      GST_QUARK (COUNT), G_TYPE_INT, -1,
+      GST_QUARK (WIDTH), G_TYPE_INT, -1,
+      GST_QUARK (HEIGHT), G_TYPE_INT, -1, NULL);
+
+  query = gst_query_new (GST_QUERY_BUFFERS, structure);
+
+  return query;
+}
+
+/**
+ * gst_query_set_buffers_count:
+ * @count: minimum number of buffers required
+ *
+ * Answer a buffers query by setting the minimum number of buffers required.
+ * If there is no minimum buffer count requirement, don't set this field in
+ * the query.
+ */
+void
+gst_query_set_buffers_count (GstQuery * query, gint count)
+{
+  GstStructure *structure;
+
+  g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERS);
+
+  structure = gst_query_get_structure (query);
+  gst_structure_id_set (structure, GST_QUARK (COUNT), G_TYPE_INT, count, NULL);
+}
+
+/**
+ * gst_query_set_buffers_dimensions:
+ * @width: minimum buffer width
+ * @height: minimum buffer height
+ *
+ * Answer a buffers query by setting the minimum buffer dimensions required.
+ * If there is no minimum buffer dimensions (beyond the width/height specified
+ * in the #GstCaps), don't set this field in the query.
+ */
+void
+gst_query_set_buffers_dimensions (GstQuery * query, gint width, gint height)
+{
+  GstStructure *structure;
+
+  g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERS);
+
+  structure = gst_query_get_structure (query);
+  gst_structure_id_set (structure,
+      GST_QUARK (WIDTH), G_TYPE_INT, width,
+      GST_QUARK (HEIGHT), G_TYPE_INT, height, NULL);
+}
+
+/**
+ * gst_query_parse_buffers_caps:
+ * @query: a #GstQuery
+ * @caps: the storage for the #GstCaps pointer, or NULL
+ *
+ * Parse a buffers query.
+ */
+void
+gst_query_parse_buffers_caps (GstQuery * query, const GstCaps ** caps)
+{
+  GstStructure *structure;
+
+  g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERS);
+
+  structure = gst_query_get_structure (query);
+  if (caps)
+    *caps = gst_value_get_caps (gst_structure_id_get_value (structure,
+            GST_QUARK (CAPS)));
+}
+
+/**
+ * gst_query_parse_buffers_count:
+ * @query: a #GstQuery
+ * @count: the storage for minimum number of buffers, or NULL
+ *
+ * Parse a buffers query answer to see the minimum number of buffers
+ * required.  A returned value of -1 means there is no minimum requirement
+ */
+void
+gst_query_parse_buffers_count (GstQuery * query, gint * count)
+{
+  GstStructure *structure;
+
+  g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERS);
+
+  structure = gst_query_get_structure (query);
+  if (count)
+    *count = g_value_get_int (gst_structure_id_get_value (structure,
+            GST_QUARK (COUNT)));
+}
+
+/**
+ * gst_query_parse_buffers_dimensions:
+ * @query: a #GstQuery
+ * @width: the storage for minimum width, or NULL
+ * @height: the storage for minimum height, or NULL
+ *
+ * Parse a buffers query answer to see the minimum buffer dimensions required.
+ * A returned value of -1 for either dimension means there is no minimum
+ * requirement in that axis
+ */
+void
+gst_query_parse_buffers_dimensions (GstQuery * query, gint * width,
+    gint * height)
+{
+  GstStructure *structure;
+
+  g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERS);
+
+  structure = gst_query_get_structure (query);
+  if (width)
+    *width = g_value_get_int (gst_structure_id_get_value (structure,
+            GST_QUARK (WIDTH)));
+  if (height)
+    *height = g_value_get_int (gst_structure_id_get_value (structure,
+            GST_QUARK (HEIGHT)));
+}
diff --git a/gst/gstquery.h b/gst/gstquery.h
index 2166537ef..8dd710abd 100644
--- a/gst/gstquery.h
+++ b/gst/gstquery.h
@@ -31,6 +31,7 @@
 #include <gst/gstminiobject.h>
 #include <gst/gststructure.h>
 #include <gst/gstformat.h>
+#include <gst/gstcaps.h>
 
 G_BEGIN_DECLS
 
@@ -51,6 +52,9 @@ G_BEGIN_DECLS
  * @GST_QUERY_CUSTOM: a custom application or element defined query. Since
  * 0.10.22.
  * @GST_QUERY_URI: query the URI of the source or sink. Since 0.10.22.
+ * @GST_QUERY_BUFFERS: query the upstream users of pad_alloc()'d buffers to
+ * find any particular requirements about buffer size (padding) or numbers of
+ * buffers. Since ?.?.?.
  *
  * Standard predefined Query types
  */
@@ -69,7 +73,8 @@ typedef enum {
   GST_QUERY_FORMATS,
   GST_QUERY_BUFFERING,
   GST_QUERY_CUSTOM,
-  GST_QUERY_URI
+  GST_QUERY_URI,
+  GST_QUERY_BUFFERS
 } GstQueryType;
 
 /**
@@ -336,6 +341,15 @@ GstQuery *      gst_query_new_uri                 (void) G_GNUC_MALLOC;
 void            gst_query_parse_uri               (GstQuery *query, gchar **uri);
 void            gst_query_set_uri                 (GstQuery *query, const gchar *uri);
 
+/* buffer requirements query */
+GstQuery *      gst_query_new_buffers             (GstCaps * caps);
+void            gst_query_set_buffers_count       (GstQuery * query, gint count);
+void            gst_query_set_buffers_dimensions  (GstQuery * query, gint width, gint height);
+void            gst_query_parse_buffers_caps      (GstQuery * query, const GstCaps ** caps);
+void            gst_query_parse_buffers_count     (GstQuery * query, gint * count);
+void            gst_query_parse_buffers_dimensions (GstQuery * query, gint * width, gint * height);
+
+
 G_END_DECLS
 
 #endif /* __GST_QUERY_H__ */