Added draft for new query API.

Original commit message from CVS:
* docs/design/draft-push-pull.txt:
* docs/design/draft-query.txt:
* gst/base/gstbasesrc.c: (gst_basesrc_get_range_unlocked),
(gst_basesrc_start):
Added draft for new query API.
Added draft for better selecting scheduling methods.
Make basesrc ignore length if the subclass does not support
it.

diff --git a/ChangeLog b/ChangeLog
index 40dc3cb..8849cdd 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2005-05-02  Wim Taymans  <wim@fluendo.com>
+
+       * docs/design/draft-push-pull.txt:
+       * docs/design/draft-query.txt:
+       * gst/base/gstbasesrc.c: (gst_basesrc_get_range_unlocked),
+       (gst_basesrc_start):
+       Added draft for new query API.
+       Added draft for better selecting scheduling methods.
+       Make basesrc ignore length if the subclass does not support
+       it.
+
 2005-05-02  Thomas Vander Stichele  <thomas at apestaart dot org>
 
        * gst/Makefile.am:

diff --git a/docs/design/draft-push-pull.txt b/docs/design/draft-push-pull.txt
index dac4652..fbcbee7 100644 (file)
--- a/docs/design/draft-push-pull.txt
+++ b/docs/design/draft-push-pull.txt
@@ -73,7 +73,8 @@ Proposition:
 
   - pads queries scheduling mode of peer pad. This query is rather
     finegrained and allows the element to know if the peer supports
-    offsets and sizes in the get_region function.
+    offsets and sizes in the get_region function. A proposition for
+    the query is outlined in draft-query.txt.
   
   - pad selects scheduling mode and informs the peer pad of this
     decision.

diff --git a/docs/design/draft-query.txt b/docs/design/draft-query.txt
new file mode 100644 (file)
index 0000000..7a4f81e
--- /dev/null
+++ b/docs/design/draft-query.txt
@@ -0,0 +1,93 @@
+DRAFT Query
+-----------
+
+Purpose
+
+  Queries are used to get information about the stream. 
+  A query is started on a specific pad and travels up or downstream.
+
+Types of queries
+
+  - get length of stream
+  - get position in stream
+  - get seeking capabilities
+  - get latency
+  - convert one value to another
+  - query supported formats
+  - query internal links.
+
+Current implementation
+
+  The current implementation of query requires pads to implement the 
+  following functions:
+
+     gboolean                (*GstPadConvertFunction)        (GstPad *pad,
+                                                              GstFormat src_format,  gint64  src_value,
+                                                              GstFormat *dest_format, gint64 *dest_value);
+     gboolean                (*GstPadQueryFunction)          (GstPad *pad, GstQueryType type,
+                                                              GstFormat *format, gint64  *value);
+     GList*                  (*GstPadIntLinkFunction)        (GstPad *pad);
+     const GstFormat*        (*GstPadFormatsFunction)        (GstPad *pad);
+     const GstEventMask*     (*GstPadEventMaskFunction)      (GstPad *pad);
+     const GstQueryType*     (*GstPadQueryTypeFunction)      (GstPad *pad);
+
+  Most of these functions are not very extensible in particular,
+  the queryfunction can only return one value.
+
+
+Requirements
+
+  - multiple return values, grouped together when they make sense.
+  - one pad function to perform the query
+  - extensible queries.
+
+Proposition
+
+  - define GstQuery extending GstData and containing a GstStructure (see GstMessage)
+  - define standard query types (see proposed types)
+  - define methods to create a parse the results in the GstQuery.
+  - define pad method:
+
+     gboolean                (*GstPadQueryFunction)          (GstPad *pad, GstQuery *query);
+
+    pad returns result in query structure and TRUE as result or FALSE when
+    query is not supported.
+
+Proposed types
+
+ - GST_QUERY_SEEKING:
+   
+     - get info on how seeking can be done 
+         - getrange, with/without offset/size
+        - ranges where seeking is efficient (for caching network sources)
+        - flags describing seeking behaviour (forward, backward, segments,
+                    play backwards, ...)
+
+ - GST_QUERY_POSITION:
+  
+     - get info on current position of the stream
+       - start position
+       - current position
+       - end position
+       - length
+ 
+ - GST_QUERY_LATENCY:
+
+     - get amount of buffering 
+
+ - GST_QUERY_CONVERT:
+
+     - convert format/value to another format/value pair.
+
+ - GST_QUERY_FORMATS:
+
+     - return list of supported formats.
+
+ - GST_QUERY_LINKS:
+
+     - return list of internal link pads.
+
+Also????
+
+ - GST_QUERY_CAPS:
+

diff --git a/gst/base/gstbasesrc.c b/gst/base/gstbasesrc.c
index 2ead5b1..c45842b 100644 (file)
--- a/gst/base/gstbasesrc.c
+++ b/gst/base/gstbasesrc.c
@@ -455,7 +455,7 @@ gst_basesrc_get_range_unlocked (GstPad * pad, guint64 offset, guint length,
     }
   }
   if (length == 0)
-    return GST_FLOW_UNEXPECTED;
+    goto unexpected_length;
 
   ret = bclass->create (src, offset, length, buf);
 
@@ -472,6 +472,11 @@ no_function:
     GST_DEBUG_OBJECT (src, "no create function");
     return GST_FLOW_ERROR;
   }
+unexpected_length:
+  {
+    GST_DEBUG_OBJECT (src, "unexpected length %u", length);
+    return GST_FLOW_UNEXPECTED;
+  }
 }
 
 static GstFlowReturn
@@ -601,6 +606,8 @@ gst_basesrc_start (GstBaseSrc * basesrc)
   /* figure out the size */
   if (bclass->get_size) {
     result = bclass->get_size (basesrc, &basesrc->size);
+    if (result == FALSE)
+      basesrc->size = -1;
   } else {
     result = FALSE;
     basesrc->size = -1;

diff --git a/libs/gst/base/gstbasesrc.c b/libs/gst/base/gstbasesrc.c
index 2ead5b1..c45842b 100644 (file)
--- a/libs/gst/base/gstbasesrc.c
+++ b/libs/gst/base/gstbasesrc.c
@@ -455,7 +455,7 @@ gst_basesrc_get_range_unlocked (GstPad * pad, guint64 offset, guint length,
     }
   }
   if (length == 0)
-    return GST_FLOW_UNEXPECTED;
+    goto unexpected_length;
 
   ret = bclass->create (src, offset, length, buf);
 
@@ -472,6 +472,11 @@ no_function:
     GST_DEBUG_OBJECT (src, "no create function");
     return GST_FLOW_ERROR;
   }
+unexpected_length:
+  {
+    GST_DEBUG_OBJECT (src, "unexpected length %u", length);
+    return GST_FLOW_UNEXPECTED;
+  }
 }
 
 static GstFlowReturn
@@ -601,6 +606,8 @@ gst_basesrc_start (GstBaseSrc * basesrc)
   /* figure out the size */
   if (bclass->get_size) {
     result = bclass->get_size (basesrc, &basesrc->size);
+    if (result == FALSE)
+      basesrc->size = -1;
   } else {
     result = FALSE;
     basesrc->size = -1;