event: add new seek snap flags

They can be used to select snapping behavior (to previous, next, or
nearest location, where relevant) when seeking.

The seeking implementation (eg, demuxer) may currently ignore some
or all of these flags.

3 files changed, 36 insertions, 1 deletions

diff --git a/docs/design/part-seeking.txt b/docs/design/part-seeking.txt
index 992edb3291..8461181209 100644
--- a/docs/design/part-seeking.txt
+++ b/docs/design/part-seeking.txt
@@ -174,6 +174,12 @@ implemented demuxer/parser-side, e.g. make demuxers/parsers ignore the
 KEY_UNIT flag if the position adjustment would be larger than 1/10th of
 the duration or somesuch.
 
+Flags can be used to influence snapping direction for those cases where it
+matters. SNAP_BEFORE will select the preceding position to the seek target,
+and SNAP_AFTER will select the following one. If both flags are set, the
+nearest one to the seek target will be used. If none of these flags are set,
+the seeking implemention is free to select whichever it wants.
+
 Summary:
 
  - if the KEY_UNIT flag is *not* specified, the demuxer/parser should
diff --git a/gst/gstevent.h b/gst/gstevent.h
index 2321be5f10..8875432985 100644
--- a/gst/gstevent.h
+++ b/gst/gstevent.h
@@ -291,6 +291,17 @@ typedef enum {
  * @GST_SEEK_FLAG_SKIP: when doing fast foward or fast reverse playback, allow
  *                     elements to skip frames instead of generating all
  *                     frames. Since 0.10.22.
+ * @GST_SEEK_FLAG_SNAP_BEFORE: go to a location before the requested position,
+ *                     if KEY_UNIT this means the keyframe at or before the
+ *                     requested position the one at or before the seek target.
+ *                     Since 0.10.37.
+ * @GST_SEEK_FLAG_SNAP_AFTER: go to a location after the requested position,
+ *                     if KEY_UNIT this means the keyframe at of after the
+ *                     requested position. Since 0.10.37.
+ * @GST_SEEK_FLAG_SNAP_NEAREST: go to a position near the requested position,
+ *                     if KEY_UNIT this means the keyframe closest to the
+ *                     requested position, if both keyframes are at an equal
+ *                     distance, behaves like SNAP_BEFORE. Since 0.10.37.
  *
  * Flags to be used with gst_element_seek() or gst_event_new_seek(). All flags
  * can be used together.
@@ -314,6 +325,16 @@ typedef enum {
  * and demuxers to adjust the playback rate by skipping frames. This can improve
  * performance and decrease CPU usage because not all frames need to be decoded.
  *
+ * The @GST_SEEK_FLAG_SNAP_BEFORE flag can be used to snap to the previous
+ * relevant location, and the @GST_SEEK_FLAG_SNAP_AFTER flag can be used to
+ * select the next relevant location. If KEY_UNIT is specified, the relevant
+ * location is a keyframe. If both flags are specified, the nearest of these
+ * locations will be selected. If none are specified, the implementation is
+ * free to select whichever it wants.
+ * The before and after here are in running time, so when playing backwards,
+ * the next location refers to the one that will played in next, and not the
+ * one that is located after in the actual source stream.
+ *
  * Also see part-seeking.txt in the GStreamer design documentation for more
  * details on the meaning of these flags and the behaviour expected of
  * elements that handle them.
@@ -324,7 +345,11 @@ typedef enum {
   GST_SEEK_FLAG_ACCURATE        = (1 << 1),
   GST_SEEK_FLAG_KEY_UNIT        = (1 << 2),
   GST_SEEK_FLAG_SEGMENT         = (1 << 3),
-  GST_SEEK_FLAG_SKIP            = (1 << 4)
+  GST_SEEK_FLAG_SKIP            = (1 << 4),
+  GST_SEEK_FLAG_SNAP_BEFORE     = (1 << 5),
+  GST_SEEK_FLAG_SNAP_AFTER      = (1 << 6),
+  GST_SEEK_FLAG_SNAP_NEAREST    = GST_SEEK_FLAG_SNAP_BEFORE | GST_SEEK_FLAG_SNAP_AFTER,
+  /* Careful to restart next flag with 1<<7 here */
 } GstSeekFlags;
 
 /**
diff --git a/win32/common/gstenumtypes.c b/win32/common/gstenumtypes.c
index e1edd0d125..2ab504c94c 100644
--- a/win32/common/gstenumtypes.c
+++ b/win32/common/gstenumtypes.c
@@ -616,6 +616,10 @@ gst_seek_flags_get_type (void)
     {C_FLAGS (GST_SEEK_FLAG_KEY_UNIT), "GST_SEEK_FLAG_KEY_UNIT", "key-unit"},
     {C_FLAGS (GST_SEEK_FLAG_SEGMENT), "GST_SEEK_FLAG_SEGMENT", "segment"},
     {C_FLAGS (GST_SEEK_FLAG_SKIP), "GST_SEEK_FLAG_SKIP", "skip"},
+    {C_FLAGS (GST_SEEK_FLAG_SNAP_BEFORE), "GST_SEEK_FLAG_SNAP_BEFORE",
+        "snap-before"},
+    {C_FLAGS (GST_SEEK_FLAG_SNAP_AFTER), "GST_SEEK_FLAG_SNAP_AFTER",
+        "snap-after"},
     {0, NULL, NULL}
   };