From 2d88cb7e88368db367b9fa3f1fb59ce813ff0202 Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Thu, 18 Jan 2007 12:00:23 +0000 Subject: [PATCH] gst/: Add more docs regarding tag merge-modes and when to send tags. Fix 'since' statement for new tag. Original commit message from CVS: * gst/gsttaglist.h: * gst/gsttagsetter.c: Add more docs regarding tag merge-modes and when to send tags. Fix 'since' statement for new tag. --- ChangeLog | 7 +++++ gst/gsttaglist.h | 71 ++++++++++++++++++++++++++++++++++++++++++++-- gst/gsttagsetter.c | 5 +++- 3 files changed, 79 insertions(+), 4 deletions(-) diff --git a/ChangeLog b/ChangeLog index 07a50f4b48..6368ed95ab 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2007-01-18 Stefan Kost + + * gst/gsttaglist.h: + * gst/gsttagsetter.c: + Add more docs regarding tag merge-modes and when to send tags. Fix 'since' + statement for new tag. + 2007-01-17 Edward Hervey * plugins/elements/gstmultiqueue.c: (gst_single_queue_new): diff --git a/gst/gsttaglist.h b/gst/gsttaglist.h index 7e90cc94a6..ce48791728 100644 --- a/gst/gsttaglist.h +++ b/gst/gsttaglist.h @@ -31,7 +31,7 @@ G_BEGIN_DECLS /** * GstTagMergeMode: * @GST_TAG_MERGE_UNDEFINED: undefined merge mode - * @GST_TAG_MERGE_REPLACE_ALL: replace all tags + * @GST_TAG_MERGE_REPLACE_ALL: replace all tags (clear list and append) * @GST_TAG_MERGE_REPLACE: replace tags * @GST_TAG_MERGE_APPEND: append tags * @GST_TAG_MERGE_PREPEND: prepend tags @@ -39,7 +39,72 @@ G_BEGIN_DECLS * @GST_TAG_MERGE_KEEP_ALL: keep all existing tags * @GST_TAG_MERGE_COUNT: the number of merge modes * - * The different tag merging modes. + * The different tag merging modes are basically replace, overwrite and append, + * but they can be seen from two directions. + * Given two taglists: A - the one that are supplied to + * gst_tag_setter_merge_tags() or gst_tag_setter_add_tags() and B - the tags + * already in the element, how are the tags merged? In the table below this is + * shown for the cases that a tag exists in the list (A) or does not exists (!A) + * and combination thereof. + * + * + * merge mode + * + * + * + * merge mode + * A + B + * A + !B + * !A + B + * !A + !B + * + * + * + * + * REPLACE_ALL + * B + * - + * B + * - + * + * + * REPLACE + * B + * A + * B + * - + * + * + * APPEND + * A, B + * A + * B + * - + * + * + * PREPEND + * B, A + * A + * B + * - + * + * + * KEEP + * A + * A + * B + * - + * + * + * KEEP_ALL + * A + * A + * - + * - + * + * + * + *
*/ typedef enum { GST_TAG_MERGE_UNDEFINED, @@ -523,7 +588,7 @@ gboolean gst_tag_list_get_date_index (const GstTagList * list, * * number of beats per minute in audio * - * Since: 0.10.11 + * Since: 0.10.12 */ #define GST_TAG_BEATS_PER_MINUTE "beats-per-minute" diff --git a/gst/gsttagsetter.c b/gst/gsttagsetter.c index 453c9e8869..31f65a6d36 100644 --- a/gst/gsttagsetter.c +++ b/gst/gsttagsetter.c @@ -36,7 +36,10 @@ * * If you just want to retrieve metadata in your application then all you * need to do is watch for tag messages on your pipeline's bus. This - * interface is only for setting metadata, not for extracting it. + * interface is only for setting metadata, not for extracting it. To set tags + * from the application, find tagsetter elements and set tags using e.g. + * gst_tag_setter_merge_tags() or gst_tag_setter_add_tags(). The application + * should do that before the element goes to %GST_STATE_PAUSED. * * * Elements implementing the #GstTagSetter interface often have to merge